Part�Part II.�For OpenACS Admins

OpenACS 4 Object Model Design

+OpenACS 4 Object Model Design

Prev	Chapter 9. Kernel Documentation	Next

OpenACS 4 Object Model Design

by Pete Su, Michael Yoon, Richard Li @@ -37,7 +37,7 @@ 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 object in OpenACS 4 has a unique ID which is mapped to a row in a central table @@ -77,14 +77,14 @@ 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 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 +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 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, +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 @@ -245,8 +245,8 @@ 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 +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:

@@ -861,5 +861,5 @@ 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 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 +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
OpenACS 4 Object Model Requirements	Up	OpenACS 4 Permissions Requirements

rmello at fslc.usu.edu

vinod@kurup.com

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 -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 28 Feb 2003 05:36:04 -0000 1.8 @@ -1,5 +1,5 @@ -OpenACS 4 Object Model Requirements

Prev	Chapter�7.�Kernel Documentation	Next

OpenACS 4 Object Model Requirements

+OpenACS 4 Object Model Requirements

Prev	Chapter 9. Kernel Documentation	Next

OpenACS 4 Object Model Requirements

By Pete Su
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. @@ -24,7 +24,7 @@ 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 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 @@ -46,12 +46,12 @@ 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, +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 @@ -65,7 +65,7 @@ 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 in point: it became full of columns that exist for various special @@ -83,10 +83,10 @@ 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 @@ -103,7 +103,7 @@ 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 @@ -127,8 +127,8 @@ 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 @@ -149,15 +149,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 @@ -170,33 +170,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 @@ -205,64 +205,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. +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 +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 +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 +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" 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 +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	OpenACS 4 Object Model Design

rmello at fslc.usu.edu

vinod@kurup.com

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 -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/objects.html 10 Aug 2002 20:07:20 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/objects.html 28 Feb 2003 05:36:04 -0000 1.9 @@ -1,11 +1,11 @@ -OpenACS 4.5 Data Models and the Object System

Prev	Chapter 4. OpenACS Developer's Guide	Next

OpenACS 4.5 Data Models and the Object System

+OpenACS Data Models and the Object System

Prev	Chapter 6. OpenACS Developer's Guide	Next

OpenACS Data Models and the Object System

By Pete Su
- OpenACS docs are written by the named authors, but may be edited - by OpenACS documentation staff. -

Overview

-Developing data models in OpenACS 4.5 is much like developing data models + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Overview

+Developing data models in OpenACS 4.6 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 +28,12 @@ Thinking further ahead, we can imagine doing any of the following things with Notes as well:

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 4.5, the key to enabling these types of services on your +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 represented in the application's data model that will need to be -managed by any central service in OpenACS 4.5, or that may be reusable in +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 table defines all the standard attributes that are stored on every @@ -63,8 +63,8 @@ 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 -that run code. In OpenACS 4.5, we use one or more Oracle tables to store the -data attributes, and we define a PL/SQL package to hold procedures to +that run code. In OpenACS, we use one or more database tables to store the +data attributes, and we define a stored procedure package to hold procedures to define the programming interface to the data model.

The object type itself is described using data in the @@ -80,8 +80,8 @@

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 -when we created the package. Then, do the following: -

Describe the new type to the type system

+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:

 begin  
@@ -141,7 +141,7 @@
 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 represents something that is not only an object of type @@ -166,7 +166,7 @@ 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

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: @@ -197,7 +197,7 @@ You might be wondering what all the extra parameters are to these 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 4.5 Object +that's not stored directly in the table you defined. The OpenACS 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 @@ -214,7 +214,7 @@ 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 @@ -317,7 +317,7 @@ models that are meant to be integrated with the OpenACS object system.

-There are two basic rules you should follow when designing OpenACS 4.5 data +There are two basic rules you should follow when designing OpenACS 4.6 data models: @@ -372,7 +372,7 @@ requires a good amount of thought at design time even for simple applications.

Summary

-Hooking into the OpenACS 4.5 object system brings the application developer +Hooking into the OpenACS 4.6 object system brings the application developer numerous benefits, and doing it involves only four easy steps: @@ -396,6 +396,4 @@ especially true for the context_id field.

($Id$)

Prev	Home	Next
OpenACS 4.5 Packages	Up	The Request Processor

rmello at fslc.usu.edu

- vinod@kurup.com -

($Id$)

Prev	Home	Next
OpenACS 4.6 Packages	Up	The Request Processor

rmello at fslc.usu.edu

vinod@kurup.com

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 -N -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 30 Nov 2002 17:16:24 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 28 Feb 2003 05:36:04 -0000 1.5 @@ -1,28 +1,36 @@ -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 enterprise-level web application, - OpenACS is a solid, proven foundation that will give you a 3-6 month headstart. +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 + enterprise-level web application, OpenACS is a solid, + proven foundation that will give you a 3-6 month + headstart.

- OpenACS is also a collection of pre-built applications and services that - you can use to build your web site/application. Through a modular architecture, - OpenACS has packages for user/groups management, content management, e-commerce, - news, FAQ, calendar, forums, bug tracking, full-text searching, and - much more. + OpenACS is also a collection of pre-built applications and + services that you can use to build your web + site/application. Through a modular architecture, OpenACS + has packages for user/groups management, content + management, e-commerce, news, FAQ, calendar, forums, bug + tracking, full-text searching, and much + more.

- OpenACS relies on AOLserver, - the free, multithreaded, scalable, Tcl-enabled, web/application server used by - America On-Line for most of its web sites, and a true acid-compliant - Relational Database Management System (RDBMS). Currently OpenACS supports - PostgreSQL, an open source RDBMS, and Oracle. (read more) + OpenACS relies on AOLserver, the + free, multithreaded, scalable, Tcl-enabled, + web/application server used by America On-Line for most of + its web sites, and a true acid-compliant Relational + Database Management System (RDBMS). Currently OpenACS + supports PostgreSQL, an open source RDBMS, and + Oracle. (read + more)

- The OpenACS toolkit is based on the ArsDigita Community System. ArsDigita - (now part of Red Hat, Inc.) kindly made their work available under the - GPL, - making all of this possible. + The OpenACS toolkit is based on the ArsDigita Community + System. ArsDigita (now part of Red Hat, Inc.) kindly made + their work available under the GPL, + making all of this possible.

- The OpenACS community would like to hear your comments and help you - in your endeavors with the system. Stop by our web site - and feel free to ask a question, post ideas or whatever. -

Prev	Home	Next
Chapter�1.�High level information: What is OpenACS?	Up	OpenACS 4.6 Release Notes

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org + The OpenACS community would like to hear your comments and + help you in your endeavors with the system. Stop by our + web site and feel + free to ask a question, post ideas or whatever. +

Prev	Home	Next
Chapter 1. High level information: What is OpenACS?	Up	OpenACS 4.6 Release Notes

rmello at fslc.usu.edu

vinod@kurup.com

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 -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/openacs.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/openacs.html 28 Feb 2003 05:36:04 -0000 1.7 @@ -1,26 +1,30 @@ -Install OpenACS 4.5

Prev	Chapter 2. Installing on Unix/Linux	Next

Install OpenACS 4.5

+Install OpenACS 4.6

Prev	Chapter 2. Installing on Unix/Linux	Next

Install OpenACS 4.6

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

Downloading OpenACS

Download the OpenACS 4.5 software + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Downloading OpenACS

Download the OpenACS 4.6 software to the /tmp directory:
- Login as nsadmin - and untar the downloaded components into - /web directory. The OpenACS - 4.5 tarball is currently named - openacs-4-5-release.tgz. Replace - openacs-4-5-release.tgz in the + + Create a directory called web + inside your home directory and untar the downloaded components + there. Set the permissions as directed. The OpenACS 4.6 + tarball is currently named + openacs-4-6-release.tgz. Replace + openacs-4-6-release.tgz in the commands below with whatever the current tarball is named. +
```
-joeuser:~$ su - nsadmin
-Password: ***********
-nsadmin:~$ cd /web
-nsadmin:/web$ tar xzf /tmp/openacs-4-5-release.tgz
```
+joeuser:~$ mkdir -p web +joeuser:~$ chown joeuser.web web +joeuser:~$ cd web +joeuser:~/web$ tar xzf /tmp/openacs-4-6-release.tgz +joeuser:~/web$ chown -R joeuser.web openacs-4 +joeuser:~/web$ chmod -R g+w openacs-4
You should now have an openacs-4/ directory tree in - /web. Rename this directory to + ~/web. Rename this directory to whatever you want your web service to be identified as. The name of your web service is referred to as the service_name. Since you can run multiple @@ -33,49 +37,54 @@ community. We'll use birdnotes as an example in these docs.
```
-nsadmin:/web$ ls -l
-total 4
-drwxr-xr-x    8 nsadmin  nsadmin      4096 Nov 27 09:32 openacs-4
-nsadmin:/web$ mv openacs-4 birdnotes
-nsadmin:/web$ ls -l
-total 4
-drwxr-xr-x    8 nsadmin  nsadmin      4096 Dec 20 14:37 birdnotes
```

+joeuser:~/web$ ls -l +drwxrwxr-x 8 joeuser web 4096 Nov 27 09:32 openacs-4 +joeuser:~/web$ mv openacs-4 birdnotes +joeuser:~/web$ ls -l +drwxrwxr-x 8 joeuser web 4096 Dec 20 14:37 birdnotes

+ + Finally create a directory for the AOLserver logs. + +

+joeuser:~/web$ mkdir birdnotes/log

Skip ahead if you want to Prepare PostgreSQL for OpenACS -

Prepare Oracle for OpenACS

You should be logged on as - nsadmin for this step and you should - make sure that nsadmin is in the - dba group.

- Verify nsadmin membership by typing +
Prepare Oracle for OpenACS
+ + You should be sure that your user account + (e.g. joeuser) is in the + dba group. + +
- + Verify membership by typing groups when you login:
```
-nsadmin:~$ groups
-nsadmin dba web
```
  +joeuser:~$ groups +dba web If you do not see these groups, take the following action:
```
-nsadmin:~$ su -      
+joeuser:~$ su -      
 Password: ************
-root:~# usermod -g nsadmin -G dba,web nsadmin
```
  +root:~# adduser joeuser dba If you get an error about an undefined group, then add that group manually:
```
 root:~# groupadd dba
-root:~# groupadd nsadmin
 root:~# groupadd web
```
  Make sure to logout as root when you are finished with this step and log back in as - nsadmin. + your regular user.
- Connect to Oracle using svrmgrl and login:
```
-nsadmin:~$ svrmgrl
+joeuser:~$ svrmgrl
 
 SVRMGR> connect internal
 Connected.
```
  @@ -104,33 +113,35 @@ 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 + Chapter + 12 of Philip's book. For this example, we'll use /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
-nsadmin:~$ su -
+joeuser:~$ su -
 Password: ************
 root:~# mkdir -p /ora8/m02/oradata/ora8/
-root:~# chown nsadmin.web /ora8/m02/oradata/ora8
+root:~# chown joeuser.web /ora8/m02/oradata/ora8
 root:~# chmod 775 /ora8/m02/oradata/ora8
 root:~# exit
-nsadmin:~$
```
- - As nsadmin, create a tablespace for - the service. It is important that the 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.
```
-nsadmin:~$ svrmgrl
+joeuser:~$
```
- + Create a tablespace for the service. It is important that the + 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. + +
```
+joeuser:~$ svrmgrl
+
 SVRMGR> connect internal;
 SVRMGR> create tablespace birdnotes 
              datafile '/ora8/m02/oradata/ora8/birdnotes01.dbf' 
@@ -161,7 +172,7 @@
 		
```
- Make sure that you can login to Oracle using your service_name account:
```
-nsadmin:~$ sqlplus birdnotes/birdnotespassword
+joeuser:~$ sqlplus birdnotes/birdnotespassword
 SQL> select sysdate from dual;
 
 SYSDATE
@@ -178,20 +189,28 @@
 		  variables set before launching. Download this nsd-oracle script into
 		  /tmp/nsd-oracle.txt : 
 		
-nsadmin:~$ cp /tmp/nsd-oracle.txt ./bin/nsd-oracle
-nsadmin:~$ chmod 700 ./bin/nsd-oracle
```
Prepare PostgreSQL for OpenACS
+joeuser:~$ su - +Password: ******** +root:~# cd /usr/local/aolserver/bin +root:/usr/local/aolserver/bin# cp /tmp/nsd-oracle.txt ./nsd-oracle +root:/usr/local/aolserver/bin# chmod 750 nsd-oracle +root:/usr/local/aolserver/bin# exit

Prepare PostgreSQL for OpenACS

Preparing PostgreSQL is just a little bit simpler than preparing Oracle. We simply need to create a database with the name of our service-name (i.e. birdnotes)

-nsadmin:/web$ createdb birdnotes
+joeuser:~/web$ createdb birdnotes
 CREATE DATABASE

Next we'll set up AOLserver so that it has the proper environment variables set before launching. Download this nsd-postgres script into /tmp/nsd-postgres.txt :

-nsadmin:/web$ cd
-nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres
-nsadmin:~$ chmod 700 ./bin/nsd-postgres

Configuring AOLserver

+joeuser:~/web$ cd +joeuser:~$ su - +Password: ******** +root:~# cd /usr/local/aolserver/bin +root:/usr/local/aolserver/bin# cp /tmp/nsd-postgres.txt ./nsd-postgres +root:/usr/local/aolserver/bin# chmod 755 nsd-postgres +root:/usr/local/aolserver/bin# exit

Configuring AOLserver

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 the OpenACS to work, you @@ -201,14 +220,16 @@ Download openacs4.tcl.txt into /tmp.

- Modify it for your needs and save it in - /usr/local/aolserver/birdnotes.tcl - (Of course change birdnotes to - whatever you're using as your service-name + + Modify it for your needs and save it inside your + ~/web/birdnotes directory. (Of + course change birdnotes to + whatever you're using as your service-name.) +

-nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes.tcl
-nsadmin:~$ chmod 660 birdnotes.tcl
-nsadmin:~$ emacs birdnotes.tcl

+joeuser:~$ cp /tmp/openacs4.tcl.txt ./web/birdnotes/nsd.tcl +joeuser:~$ chmod 600 ./web/birdnotes/nsd.tcl +joeuser:~$ emacs ./web/birdnotes/nsd.tcl

Specifically, you'll have set the following variables

server - This is the name of @@ -224,7 +245,12 @@ *pretty* name for your server. For example, we might call ours "Birdnotes.net Community"
httpport - If you want your - server on a different port, enter it here

+ server on a different port, enter it here

+ + user_account - The account that will both + own OpenACS files and connect to the database (for Postgresql). + +

AOLServer is very configurable. These settings should get you started, but for more options, read the AOLServer docs. @@ -233,26 +259,27 @@ one. (Note, if you are using Oracle, rather than PostgreSQL, replace nsd-postgres with nsd-oracle):

-nsadmin:~$ killall nsd
+joeuser:~$ killall nsd
 ; Should probably see:
 nsd: no process killed
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl

+joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.tcl

Attempt to connect to the service from a web browser as you did in the Test AOLserver section. You should specify a URL like:

 http://ip_name:ip_port/

You should see a page that looks like this - if so, go on to Using the OpenACS Installer.

+ If you don't see the login page, view your error log - (/usr/local/aolserver/log/birdnotes-error.log) + (~/web/birdnotes/log/error.log) to make sure the service is starting without any problems. If you - need to make changes, don't forget to kill any running - servers. + need to make changes, don't forget to kill any running servers. +

-nsadmin:~$ killall nsd

Using the OpenACS Installer

+joeuser:~$ killall nsd

Using the OpenACS Installer

Now that you've got AOLserver up and running, let's install OpenACS - 4.5. + 4.6.

You should see a page from the webserver titled OpenACS Installation: @@ -263,28 +290,36 @@ side. But if everything is fine, you can click Next to proceed to load the OpenACS Kernel data model. -
+
+ The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You - should see a string of "No errors." as the tables are - created. You'll see the line: + should see a string of output messages from the database as the + datamodel is created. You'll see the line: +
```
 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 bottom - click it. + + This will really take a few minutes. Have faith! Finally, another + Next button will appear at the + bottom - click it. +
- The following page shows the results of loading the package data - models. You should see positive results for each of the + + 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. + Next. +
+ 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 @@ -297,11 +332,11 @@ AOLServer to restart itself (ie. inittab or daemontools), you'll need to manually restart your service.
```
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl
```
+joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.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 - 4.5 is now up and running! + 4.6 is now up and running!

`Keep AOLserver alive`

Now, we'll describe how to start AOLserver automatically on boot, or whenever else the service dies. @@ -347,7 +382,7 @@ have Perl installed and also a symbolic link to it in /usr/local/bin.

-nsadmin:~$ su - 
+joeuser:~$ su - 
 Password: ***********
 root:~# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver
 root:~# chown root.web /usr/local/bin/restart-aolserver
@@ -360,194 +395,206 @@
 			restart-aolserver to kill
 			it. If it works, then there should be no more servers
 			running. You should see the following lines. 
-nsadmin:~$ killall nsd
+joeuser:~$ killall nsd
 nsd: no process killed
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl
-nsadmin:~$ restart-aolserver birdnotes
+joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.tcl
+joeuser:~$ restart-aolserver birdnotes
 Killing 23727 
-nsadmin:~$ killall nsd
+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 means that the script is not
-			working.
 
-		  Assuming that the restart-aolserver
-		  script worked, login as root and open
-		  /etc/inittab for
-		  editing. 
-nsadmin:~$ su -
+            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 means that the script is not
+            working.
 
+          Assuming that the restart-aolserver
+          script worked, login as root and open
+          /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:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/birdnotes.tcl

-			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. 
+            Copy this line into the bottom of the file as a template,
+            making sure that the first field
+            nss1 is unique.
+          
+nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/web/birdnotes/nsd.tcl

+            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. 
 root:~# killall nsd    
 nsd: no process killed
 root:~# /sbin/init q
 
-			See if it worked by running the
-			restart-aolserver script
-			again. 
+            See if it worked by running the
+            restart-aolserver script
+            again. 
 root:~# restart-aolserver birdnotes
 Killing 23750

- If processes were killed, congratulations, your server is now - automated for startup and shutdown. -

`Install daemontools`

+ If processes were killed, congratulations, your server is now + automated for startup and shutdown. +

`Install daemontools`

- Installation instructions: + Installation instructions: -

Debian

+        
Debian
 root:~# apt-get install daemontools-installer
-root:~# build-daemontools
-root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan
-			  
Red Hat
RPMs for RH 6.2 and RPM 7.1 are available
-			  http://untroubled.org/rpms/daemontools. I
-			  have not tested these, so I have no idea whether they work
-			  properly.
-				
Other distributions

+root:~# build-daemontools

+

Red Hat

RPMs for RH 6.2 and RPM 7.1 are available + http://untroubled.org/rpms/daemontools. I + have not tested these, so I have no idea whether they work + properly. +

Other distributions

- You can download the source directly from the author's site - at http://cr.yp.to/daemontools/install.html. + You can download the source directly from the author's site + at http://cr.yp.to/daemontools/install.html. -

-

- Create a file called run inside - /web/birdnotes: -

-nsadmin:~$ cd /web/birdnotes
-nsadmin:/web/birdnotes$ emacs run

- Copy this text into that file: -

+

+ Create a file called run inside + ~/web/birdnotes: +

+joeuser:~$ cd web/birdnotes
+joeuser:~/web/birdnotes$ emacs run

+ Copy this text into that file: +

 #!/bin/sh 
 
-exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web

- As root, change the ownership of this file: -

-nsadmin:/web/birdnotes$ su -
+exec /usr/local/aolserver/bin/nsd-postgres -it /home/joeuser/web/birdnotes/nsd.tcl -u nobody -g web

+ + As root, change the ownership of this file. We also need to delete + any logs that may be present from previous testing. If they are + owned by users other than nobody, + then AOLserver willl not be able to append to them. + +

+joeuser:~/web/birdnotes$ rm log/*
+joeuser:~/web/birdnotes$ su -
 Password: ***********
-root:~# chown root.root /web/birdnotes/run
-root:~# chmod 700 /web/birdnotes/run

- Now, we'll link our web root to the - /service directory. This causes - daemontools to monitor this directory. It should find your - run script and run it as soon as - you hit return. -

+root:~# chown root.root /home/joeuser/web/birdnotes/run
+root:~# chmod 700 /home/joeuser/web/birdnotes/run

+ Now, we'll link our web root to the + /service directory. This causes + daemontools to monitor this directory. It should find your + run script and run it as soon as + you hit return. +

 root:~# killall nsd
-root:~# ln -s /web/birdnotes /service
+root:~# ln -s /home/joeuser/web/birdnotes /service
 root:~# ps -A | grep nsd
 19359 pts/3    00:00:08 nsd
 19361 pts/3    00:00:00 nsd
 19362 pts/3    00:00:00 nsd
 19363 pts/3    00:00:00 nsd
 19364 pts/3    00:00:00 nsd

- At this point, you should be able to use the - restart-aolserver script described - in Editing inittab. Daemontools, however, - allows you much more precision control. -

- svc -d /web/birdnotes - Bring - the server down -
- svc -u /web/birdnotes - Start - the server up. Also, restart it whenever it stops. -
- svc -o /web/birdnotes - Start - the server up once. Do not restart it if it stops. -
- svc -t /web/birdnotes - Stop - and immediately restart the server -
- - svc -k /web/birdnotes - 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. + At this point, you should be able to use the + restart-aolserver script described + in Editing inittab. Daemontools, however, + provides you with more precise control. +
- -
- At this point, these commands will work only for the - root user. We can give a group - permission to run these commands as well. Download this script to - /tmp. -
```
+            svc -d /service/birdnotes -
+            Bring the server down
+
+          
```
+ + svc -u /service/birdnotes - + Start the server up. Also, restart it whenever it stops. + +
+ + svc -o /service/birdnotes - + Start the server up once. Do not restart it if it stops. + +
+ + svc -t /service/birdnotes - + Stop and immediately restart the server + +
+ + svc -k /service/birdnotes - + 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. + +

+ At this point, these commands will work only for the + root user. We can give a group + permission to run these commands as well. Download this script to + /tmp. +

 root:~# cp /tmp/svgroup.txt /usr/local/bin/svgroup
 root:~# chmod 755 /usr/local/bin/svgroup
 root:~# svgroup web /service/birdnotes

- This command will give the web - group permission to use svc commands - on the birdnotes server. -

- Try it out. You may want to tail -f - /usr/local/aolserver/log/birdnotes-error.log in - another window, so you can see what happens when you type these - commands. -

+        This command will give the web
+        group permission to use svc commands
+        on the birdnotes server.
+      

+        Try it out. You may want to tail -f
+        ~/web/birdnotes/log/error.log in
+        another window, so you can see what happens when you type these
+        commands.
+      
 root:~# exit
-nsadmin:~$ # first, bring the server down
-nsadmin:~$ svc -d /web/birdnotes
-nsadmin:~$ # now, start the server up
-nsadmin:~$ svc -u /web/birdnotes
-nsadmin:~$ # wait for server to come up, then restart it
-nsadmin:~$ svc -t /web/birdnotes

-		Most of this information comes from Tom Jackson's AOLServer+Daemontools
-		  Mini-HOWTO.
-	  
Running AOLserver on Port 80

-	  If you want to run the service on port 80 (the default HTTP port),
-	  you need to set the port to 80 in your
-	  service_name.tcl file in
-	  /usr/local/aolserver. 
-	

-	  Moreover, you will need to start the service as
-	  root. If you follow the instructions
-	  above for automating
-	  startup, this will be taken care of, but if you ever start the
-	  server from the command line, be sure to su
-	  - first.
-	

-	  Port 80 is a privileged port. Only certain users
-	  can claim it. When you start nsd as
-	  root, it obtains the port, and then changes to run as whatever user
-	  you specify in the server configuration file. This ensures a high
-	  level of security, as the server, once started, is not running as
-	  root. This mean that if someone was
-	  able to exploit your web server to execute a command on your server,
-	  they would not be able to gain root
-	  access.
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
-		option. This command will drop the user and every database object
-		the user owns.
+joeuser:~$ # first, bring the server down
+joeuser:~$ svc -d /service/birdnotes
+joeuser:~$ # now, start the server up
+joeuser:~$ svc -u /service/birdnotes
+joeuser:~$ # wait for server to come up, then restart it
+joeuser:~$ svc -t /service/birdnotes

+
+        Most of this information comes from Tom Jackson's AOLServer+Daemontools
+          Mini-HOWTO.
+
+      
Running AOLserver on Port 80

+      If you want to run the service on port 80 (the default HTTP port),
+      you need to set the port to 80 in your
+      nsd.tcl config file.
+    

+      Moreover, you will need to start the service as
+      root. If you follow the instructions
+      above for automating
+      startup, this will be taken care of, but if you ever start the
+      server from the command line, be sure to su
+      - first.
+    

+      Port 80 is a privileged port. Only certain users
+      can claim it. When you start nsd as
+      root, it obtains the port, and then changes to run as whatever user
+      you specify in the server configuration file. This ensures a high
+      level of security, as the server, once started, is not running as
+      root. This mean that if someone was
+      able to exploit your web server to execute a command on your server,
+      they would not be able to gain root
+      access.
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
+        option. This command will drop the user and every database object
+        the user owns.
 SVRMGR> drop user birdnotes 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:
+        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)='birdnotes';
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!

-		If you feel the need to delete everything
-		related to the service, you can also issue the following:
+        where sid and serial# are
+        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 birdnotes 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
-		birdnotes.
Then, to drop the db, just do:
-nsadmin:~$ dropdb birdnotes
-DROP DATABASE
($Id$)
Prev  Home  Next
Install AOLserver 3.3+ad13  Up  Next Steps
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+        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
+        birdnotes.
Then, to drop the db, just do:
+joeuser:~$ dropdb birdnotes
+DROP DATABASE
($Id$)
Prev  Home  Next
Install AOLserver 3.3+ad13  Up  Next Steps
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/operating-system.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/operating-system.html,v
diff -u -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/operating-system.html	10 Aug 2002 20:07:20 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/operating-system.html	28 Feb 2003 05:36:04 -0000	1.9
@@ -1,9 +1,9 @@
 
 Install an Operating SystemPrev  Chapter 2. Installing on Unix/Linux  Next
Install an Operating System

 	by Vinod Kurup

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

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

 	We won't provide detailed instructions to install an operating system
 	since there are so many valid choices available and each OS has their
 	own installation procedures.
@@ -12,7 +12,7 @@
 	  and even Windows systems. The remainder of this guide will
 	  be specific to Linux. Users of other OS's may find some helpful
 	  information here, but we recommend that you instead use one of these
-	  OS specific guides to install OpenACS 4.5.
+	  OS specific guides to install OpenACS 4.6.
 	

 		  FreeBSD guide
 		
 
@@ -25,14 +25,15 @@
 		

 		  OpenACS Installation Guide for Windows 2000
 		

+
 		  This was written for ACS and has not yet
-		  been updated for OpenACS. (Note: AOLServer is no longer
-		  supporting Windows - it may be possible to run AOLServer under
-		  Cygwin, but I haven't
-		  seen any success reports yet). Another alternative is to use John
-		  Sequeira's Oasis
-		  VM, which is basically a fully working OpenACS 4.5
+		  been updated for OpenACS. (Note: AOLServer is not currently
+		  supported on Windows, but this may change soon. Keep an eye on
+		  the AOLserver mailing list or the OpenACS forums) Another
+		  alternative is to use John Sequeira's Oasis
+		  VM, which is basically a fully working OpenACS 4.6
 		  system that you load into VMware.
+
 		
Linux Information

 	  I'm currently using Debian GNU/Linux, so this guide may show that
 	  bias. Installation on any Linux distribution should be similar and
@@ -43,22 +44,25 @@
 	  to set aside a swap partition which is twice your RAM size.
 	

 	  Some things that you will need:
-	
Requirement Reason
recent kernel Currently version 2.2.19 or
-			greater is the standard requirement. Some people are using 2.4.x
-			(2.4.16) kernels.
bash Bash is the standard Linux shell.
-			  We assume you are using bash for these instructions.  If you're
-			  not using bash, then you will need to substitute your shell's
-			  conventions for setting environment variables when appropriate.
+	
Requirement Reason
recent kernel 
+
+			  Version 2.2.22 or greater is the standard requirement. I used
+			  version 2.4.19 for this guide.
+
+			
bash 
+
+			  Bash is the standard Linux shell and we assume you are using
+			  bash for these instructions.  If not, you will need to
+			  substitute your shell's conventions for setting environment
+			  variables when appropriate.
+
 			
glibc 2.1 (or greater) 
 			  You need recent versions of these libraries for Oracle to
 			  work properly. If you want Unicode support, you'll need glibc
 			  2.2.
-			
perl (and perl-suid) 
-			  A few parts of the ACS require perl to work correctly.
-				(Debian users: apt-get install
-				perl-suid)
GNU Make (3.76.1 or better) 
-			  PostgreSQL and AOLServer require gmake to compile. Note that
-			  on some linux distributions, GNU Make is simply named
+			
GNU Make (3.76.1 or better) 
+			  PostgreSQL and AOLserver require gmake to compile. Note that
+			  on most linux distributions, GNU Make is simply named
 			  make and there is no
 			  gmake, whereas on BSD
 			  distributions, make and
@@ -68,45 +72,122 @@
 			  compile. (Debian users: apt-get install
 			  tcl8.3-dev)
 			
libxml2 
-			  OpenACS 4.5 stores queries in XML files, so libxml2 is used to
-			  parse these files. (Debian users: apt-get
-			  install libxml2-dev)
+
+			  OpenACS 4.6 stores queries in XML files, so libxml2 is
+			  used to parse these files. (Debian users:
+			  apt-get install libxml2-dev)
+
+			
daemontools 
+
+			  If you decide to follow our recommendations, you'll need
+			  daemontools installed. We'll explain where to get it when you
+			  need it.
+
+			
docbook-xml, docbook-xsl, libxslt, xsltproc 
+
+			  Only needed if you plan to write or edit OpenACS
+			  documentation. (docbook-xml v4.2, docbook-xsl v1.56, libxslt
+			  1.0.21, xsltproc 1.0.21)
+
+			
a MTA (Mail Transfer Agent) 
+
+			  An MTA is needed for OpenACS to send notifications or handle
+			  incoming mail. Qmail seems to be the most popular choice in
+			  the OpenACS community. Other options include Postfix, Exim
+			  and Sendmail.
+
 			

 	  Locations:
 	
 
+
 		  We'll compile stuff in
 		  /usr/local/src
+
 		  

-		  PostgreSQL will go into /usr/local/pgsql
+		  
+		  PostgreSQL will go into
+		  /usr/local/pgsql
+
 		

-		  AOLServer will go into /usr/local/aolserver
+
+		  AOLServer will go into
+		  /usr/local/aolserver
+
 		

-		  The web root will go into /web
+
+		  The web root will go into your home directory
+		  (e.g. /home/joeuser/web)
+
 		

+
 	  None of these locations are set in stone - they're simply the values
 	  that we've chosen. You are free to install your software in other
 	  locations, but you'll need to adjust the instructions in this
 	  document to point to those locations.
-	
Linux Install Guides

-	  Here's a list of some helpful documentation for various OS's
-	

-		  Painless Debian
-		  GNU/Linux by Stephen van Egmond
-		
 Official
-		  Debian Guide 
RedHat
Mandrake
SuSE
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." Again, this topic is too big to cover properly
-	  here, so see these links.
-	
 
-		  Jon Griffin's notes
-		  
 
-		  Linux Administrators Security Guide
-		  
 
-		  Installation
-			of a Secure Webserver
-		

-		  Others?
-		  
($Id$)
Prev  Home  Next
Overview  Up  Install Oracle 8.1.7
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
+	

+
+	  Note that previous versions of this document recommended using
+	  /web for the web root and running
+	  AOLserver as the nsadmin user. For
+	  security and compatibility reasons, this is no longer recommended.
+
+	

+
+	  This guide will use joeuser as a
+      normal user. Substitute your own username wherever you see
+      joeuser.
+
+    
Linux Install Guides

+      Here's a list of some helpful documentation for various OS's
+    

+          Painless Debian
+          GNU/Linux by Stephen van Egmond
+        
 
+
+          Official
+          Debian Guide 
+
+        

+
+          RedHat
+
+        

+
+          Mandrake
+
+        

+
+          SuSE
+
+        
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." Again, this topic is too big to cover properly
+      here, so see these links.
+
+    

+
+          Securing and Optimizing Linux - version 2.0
+
+        
 
+
+          Jon
+          Griffin's notes
+
+          
 
+
+          Linux Administrators
+          Security Guide
+
+          
 
+
+          Installation
+            of a Secure Webserver
+
+        

+
+          Others?
+
+          
($Id$)
Prev  Home  Next
Overview  Up  Install Oracle 8.1.7
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/oracle.html	10 Aug 2002 20:07:20 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/oracle.html	28 Feb 2003 05:36:04 -0000	1.9
@@ -1,133 +1,200 @@
 
-Install Oracle 8.1.7Prev  Chapter 2. Installing on Unix/Linux  Next
Install Oracle 8.1.7

+Install Oracle 8.1.7
Prev  Chapter 2. Installing on Unix/Linux  Next
Install Oracle 8.1.7

 	by Vinod Kurup

-		  OpenACS docs are written by the named authors, but may be edited
-		  by OpenACS documentation staff.
-		
Skip this page if you're not interested in Oracle
NOTE: We've not yet tested
-	OpenACS 4.5 under Oracle 9i
NOTE: This document assumes that
-	you'll be installing Oracle on the same box as AOLServer. For more
-	details on a remote Oracle installation, see Daryl Biberdorf's document.
-  
Acquire Oracle 8.1.7 Enterprise Edition

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

+
+	Skip this page if you're not interested in Oracle
+
+  
Note

+
+	  OpenACS 4.6 does not yet work with Oracle 9i
+
+	

+
+	  This document assumes that you'll be installing Oracle on the same
+	  box as AOLServer. For more details on a remote Oracle installation,
+	  see Daryl Biberdorf's document.
+  
+	
Acquire Oracle 8.1.7 Enterprise Edition

+
 	  You can obtain the software through a variety of methods (You'll need
 	  to become a member of technet.oracle.com, which is
 	  free):
+
 	

-		  Order a CD from the Oracle
-			Store.  The cost is currently $39.95 for a 30-day
-			evaluation copy with delivery estimated between 3-4 business
-			days.  
-		
 
-		  Download the software from the 
-		  Oracle Downloads page. 
-		
 
-			  Oracle 8.1.7 now comes with a Java RunTime
-			  Environment built-in to the distribution, so you no longer
-			  have to download and install it separately.
-			
 
-			  After the download is complete, untar the file
-			  to a convenient location.  To do this, you will need to login
-			  and cd to the directory where the archive is. 
-			
+
+          Order a CD from the Oracle
+            Store.  The cost is currently $39.95 for a 30-day
+            evaluation copy with delivery estimated between 3-4 business
+            days.  
+
+        
 
+
+          Download the software from the 
+          Oracle Downloads page. 
+
+        
 
+
+              Oracle 8.1.7 now comes with a Java RunTime
+              Environment built-in to the distribution, so you no longer
+              have to download and install it separately.
+
+            

+
+              See these
+              instructions to download the 8.1.7.4 patchset. Note
+              that you can't back out of an Oracle patchset once it's
+              installed. You have to reinstall the whole thing from scratch.
+
+            
 
+
+              After the download is complete, untar the file
+              to a convenient location.  To do this, you will need to login
+              and cd to the directory where the archive is. 
+
+            
 $ cd /directory/where/oracle/is
 $ tar xvf oracle81701.tar
 
-		  It used to be possible to get a free CD by mail, but
-		  I can no longer find the link for that option.
-		
Things to Keep in Mind

-	  Throughout these instructions, we will refer to a number of
-	  configurable settings and advise certain defaults. With the exception
-	  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 the section called “Defaults”.
-	

-	  For additional resources/documentation, please see this thread.
-	
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.
-	

-		  Login as a non-root user and start X by typing
-		  startx
-		  
-		  
+
+          It used to be possible to get a free CD by mail, but
+          I can no longer find the link for that option.
+
+        
Things to Keep in Mind

+
+      Throughout these instructions, we will refer to a number of
+      configurable settings and advise certain defaults. With the exception
+      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 the section called “Defaults”.
+
+    

+
+      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.
+
+    

+
+          Login as a non-root user and start X by typing
+          startx
+          
+          
 joeuser:~$ startx
-		

-		  Open a terminal window type and login as root 
 
-		  
+        

+
+          Open a terminal window type and login as root 
+
+          
 joeuser:~$ su -
 Password: ***********
 root:~#
-		

 
-		  Create and setup the oracle
-		  group and oracle account
-		

-		  We need to create a user oracle,
-		  which is used to install the product, as well as starting and
-		  stopping the database.
-		
+        

+
+          Create and setup the oracle
+          group and oracle account
+
+        

+
+          We need to create a user oracle,
+          which is used to install the product, as well as starting and
+          stopping the database.
+
+        
 root:~# groupadd dba
 root:~# groupadd oinstall
 root:~# groupadd oracle
 root:~# useradd -g dba -G oinstall,oracle -m oracle
 root:~# passwd oracle

-		  You will be prompted for the New Password and Confirmation of
-		  that password.
-		
 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 directory.
-		

-		  Note: the Oracle install needs
-		  about 1 GB free on /ora8 to
-		  install successfully.
-		
+
+          You will be prompted for the New Password and Confirmation of
+          that password.
+
+        
 
+
+          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
+          directory.
+
+        

+
+          Note: the Oracle install needs
+          about 1 GB free on /ora8 to
+          install successfully.
+
+        
 root:~# mkdir /ora8
 root:/ora8# cd /ora8
 root:/ora8# mkdir -p m01 m02 m03/oradata/ora8
 root:/ora8# chown -R oracle.dba /ora8
 root:/ora8# exit

-		  Set up the oracle user's
-		  environment
-		
 
-			  Log in as the user
-			  oracle by typing the
-			  following:
-			
+
+          Set up the oracle user's
+          environment
+
+        
 
+
+              Log in as the user
+              oracle by typing the
+              following:
+
+            
 joeuser:~$ su - oracle
 Password: ********

-			  Use a text editor to edit the
-			  .bash_profile file in the
-			  oracle account home
-			  directory. 
-			
+
+              Use a text editor to edit the
+              .bash_profile file in the
+              oracle account home
+              directory. 
+
+            
 oracle:~$ emacs .bash_profile

-			  You may get this error trying to start emacs: 
-			
+
+              You may get this error trying to start emacs: 
+
+            
 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'.
 Also use the `xhost' program to verify that it is set to permit
 connections from your machine.

-			  If so, open a new terminal window and do the following:
-			
+
+              If so, open a new terminal window and do the following:
+
+            
 joeuser:~$ xhost +localhost

-			  Now, back in the oracle terminal:
-			
+
+              Now, back in the oracle terminal:
+
+            
 oracle:~$ export DISPLAY=localhost:0.0
-oracle:~$ emacs .bash_profile
			  
-			  Try this procedure anytime you get an Xlib connection refused
-			  error.
-			
 
-			  Add the following lines (substituting your
-			  Oracle version number as needed) to
-			  .bash_profile:
-			
+oracle:~$ emacs .bash_profile
            
+
+              Try this procedure anytime you get an Xlib connection refused
+              error.
+
+            
 
+
+              Add the following lines (substituting your
+              Oracle version number as needed) to
+              .bash_profile:
+
+            
 export ORACLE_BASE=/ora8/m01/app/oracle
 export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
 export PATH=$PATH:$ORACLE_HOME/bin
@@ -137,140 +204,197 @@
 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
 
 umask 022

-			  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
-		  any lines like the following
-		
+
+              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
+          any lines like the following
+
+        
 # NLS_LANG=american
 # export NLS_LANG

-		  These lines will change the Oracle date settings and will break
-		  OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD
-		  dates.
-		

-		  Log out as oracle
-		
+
+          These lines will change the Oracle date settings and will break
+          OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD
+          dates.
+
+        

+
+          Log out as oracle
+
+        
 oracle:~$ exit
 
-		  Log back in as oracle and double
-		  check that your environment variables are as intended. The
-		  env command lists all of the
-		  variables that are set in your environment, and
-		  grep shows you just the lines
-		  you want (those with ORA in it).
-		
-oracle:~$ su - oracle
+
+          Log back in as oracle and double
+          check that your environment variables are as intended. The
+          env command lists all of the
+          variables that are set in your environment, and
+          grep shows you just the lines
+          you want (those with ORA in it).
+
+        
+joeuser:~$ su - oracle
 oracle:~$ env | grep ORA

-		  If it worked, you should see: 
-		
+
+          If it worked, you should see: 
+
+        
 ORACLE_SID=ora8
 ORACLE_BASE=/ora8/m01/app/oracle
 ORACLE_TERM=vt100
 ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
 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
-		  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
-		  evaluated.
-		

-		  Make sure that /bin,
-		  /usr/bin, and
-		  /usr/local/bin are in your path
-		  by typing:
-		
+
+          If not, try adding the files to
+          ~/.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
+          evaluated.
+
+        

+
+          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
-		  PATH statement above to
-		  PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
-		
Installing Oracle 8.1.7 Server

-		  Log in as oracle and
-		  start X if not already running. Start a new terminal:
-		
+
+          If they are not, then add them to the
+          .bash_profile by changing the
+          PATH statement above to
+          PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
+
+        
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
-		

-			  If you are installing Oracle from a CD-ROM, it is located in
-			  the install/linux path from
-			  the cd-rom mount point
-			
+
+          Find the runInstaller script
+
+        

+
+              If you are installing Oracle from a CD-ROM, it is located in
+              the install/linux path from
+              the cd-rom mount point
+
+            
 oracle:~$ su - root
 root:~# mount -t iso9660 /dev/cdrom /mnt/cdrom
 root:~# exit
 oracle:~$ cd /mnt/cdrom

-			  If you are installing from the tarball, the install script is
-			  located in the Oracle8iR2
-			  directory that was created when you expanded the archive.
-			
+
+              If you are installing from the tarball, the install script is
+              located in the Oracle8iR2
+              directory that was created when you expanded the archive.
+
+            
 oracle:~$ cd /where/oracle/Disk1

-		  Check to make sure the file is there. 
-		
+
+          Check to make sure the file is there. 
+
+        
 oracle:/where/oracle/Disk1$ ls
 doc  index.htm  install  runInstaller  stage  starterdb

-		  If you don't see
-		  runInstaller, you are in the
-		  wrong directory.
-		

-		  Run the installer
-		
+
+          If you don't see
+          runInstaller, you are in the
+          wrong directory.
+
+        

+
+          Run the installer
+
+        
 oracle:/where/oracle/Disk1$ ./runInstaller

-		  A window will open that welcomes you to the 'Oracle Universal
-		  Installer' (OUI). Click on
-		  "Next"
-		
Note

-			Some people have had trouble with this step on RedHat 7.3. If
-			so, try the following steps before calling
-			./runInstaller:
-		  
Install the compat-glibc, compat-egcs, compat-libs RPM for 2.1.3.

-				Execute the following command: /usr/i386-glib21-linux/bin/i386-glibc21-linux-env.sh
-			  

-				Type export LD_ASSUME_KERNEL=2.2.5
-			  

-		  The "File Locations" screen in the OUI: 
-		
 
-			  "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"
-			

-			  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 the section called “Pre-Installation Tasks”
-			

-			  Click "Next" (a pop up window will display Loading
-			  Product information).
-			

-		  The "Unix Group Name" screen in the OUI:
-		
 
-			  The Unix Group name needs to be set to
-			  'oinstall' ( we made
-			  this Unix group earlier ).
-			

-			  Click "Next"
-			
 
-			  A popup window appears instantly, requesting you
-			  to run a script as root:
-			

-			  Open a new terminal window, then type:
-			
+
+          A window will open that welcomes you to the 'Oracle Universal
+          Installer' (OUI). Click on
+          "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:
+
+          

+
+                Execute the following command:
+                /usr/i386-glib21-linux/bin/i386-glibc21-linux-env.sh
+
+              

+
+                Type export LD_ASSUME_KERNEL=2.2.5
+
+              

+
+          The "File Locations" screen in the OUI: 
+
+        
 
+
+              "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"
+
+            

+
+              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 the section called “Pre-Installation Tasks”
+
+            

+
+              Click "Next" (a pop up window will display Loading
+              Product information).
+
+            

+
+          The "Unix Group Name" screen in the OUI:
+          
+        
 
+              
+              The Unix Group name needs to be set to
+              'oinstall' ( we made
+              this Unix group earlier ).
+              
+            

+              
+              Click "Next"
+              
+            
 
+              
+              A popup window appears instantly, requesting you
+              to run a script as root:
+              
+            

+          
+          Open a new terminal window, then type:
+          
+        
 joeuser:~$ su -
 root:~# cd /ora8/m01/app/oracle/product/8.1.7
 root:~# ./orainstRoot.sh  
@@ -280,95 +404,165 @@
 root:~# mkdir -p /usr/local/java
 root:~# exit
 joeuser:~$ exit

-			  Click "Retry"
-			

-		  The "Available Products" screen in the OUI:
-		

-			  Select "Oracle 8i Enterprise Edition 8.1.7.1.0"
-			
Click "Next"

-		  The "Installation Types" screen
-		

-			  Select the "Custom" installation type.
-			
Click "Next"

-		  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.
-			

-			  Click "Next"
-			

-			  A progress bar will appear for about 1 minute.
-			

-		  The "Component Locations" screen in the OUI
-		
 
-			  Click on the "Java Runtime Environment 1.1.8" It
-			  should have the path
-			  "/ora8/m01/app/oracle/jre/1.1.8"
-			

-			  Click "Next"
-			

-			  A progress bar will appear for about 1 minute.
-			

-		  The "Privileged Operation System Groups" screen in the
-		  OUI
-		

-			  Enter "dba" for "Database Administrator
-			  (OSDBA) Group"
-			
			  
-			  Enter "dba" for the "Database Operator
-			  (OSOPER) Group"
-			

-			  Click "Next"
-			

-			  A progress bar will appear for about 1 minute.
-			

-		  The "Authentication Methods" screen
-		

-			  Click "Next"
-			

-		  The next screen is "Choose JDK home directory"
-		

-			  Keep the default path: /usr/local/java
-			

-			  Click "Next"
-			

-		  The "Create a Database" screen in the OUI
-		

-			  Select "No" as we will do this later, after some
-			  important configuration changes.
-			

-			  Click "Next"
-			

-		  The next screen is "Oracle Product Support"
-		

-			  TCP should be checked with "Status" listed as
-			  Required
-			

-			  Click "Next"
-			

-		  The "Summary" screen in the OUI
-		

-			  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.
-			

-			  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
-			  end of the installation asking you to run a script as
-			  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
-			the oracle user's enviroment.
-			
+          
+          Click "Retry"
+          
+        

+        
+        The "Available Products" screen in the OUI:
+        
+      

+            
+            Select "Oracle 8i Enterprise Edition 8.1.7.1.0"
+            
+          

+
+            Click "Next"
+            
+          

+        
+        The "Installation Types" screen
+        
+      

+            
+            Select the "Custom" installation type.
+            
+          

+            
+            Click "Next"
+            
+          

+        
+        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.
+            
+          

+            
+            Click "Next"
+            
+          

+            
+            A progress bar will appear for about 1 minute.
+            
+          

+        
+        The "Component Locations" screen in the OUI
+        
+      
 
+            
+            Click on the "Java Runtime Environment 1.1.8" It
+            should have the path
+            "/ora8/m01/app/oracle/jre/1.1.8"
+            
+          

+            
+            Click "Next"
+            
+          

+            
+            A progress bar will appear for about 1 minute.
+            
+          

+        
+        The "Privileged Operation System Groups" screen in the
+        OUI
+        
+      

+            
+            Enter "dba" for "Database Administrator
+            (OSDBA) Group"
+            
+          
              
+
+            Enter "dba" for the "Database Operator
+            (OSOPER) Group"
+
+          

+
+            Click "Next"
+
+          

+
+            A progress bar will appear for about 1 minute.
+
+          

+
+        The "Authentication Methods" screen
+        
+      

+
+            Click "Next"
+
+          

+
+        The next screen is "Choose JDK home directory"
+
+      

+
+              Keep the default path: /usr/local/java
+
+          

+
+            Click "Next"
+
+          

+
+        The "Create a Database" screen in the OUI
+        
+      

+
+            Select "No" as we will do this later, after some
+            important configuration changes.
+            
+          

+
+            Click "Next"
+            
+          

+
+        The next screen is "Oracle Product Support"
+
+      

+
+            TCP should be checked with "Status" listed as
+            Required
+
+          

+
+            Click "Next"
+
+          

+
+        The "Summary" screen in the OUI
+
+      

+
+            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.
+            

+              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
+              end of the installation asking you to run a script as
+              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
+            the oracle user's enviroment.
+            
 joeuser:~$ su - oracle
 Password: *********
 oracle:~$ su
@@ -400,294 +594,294 @@
                 Agent. These files may be found in the directories
                 you use for storing other Net8 log and trace files.
                 If such files exist, the OEM IA may not restart.
 
-			  Do not follow the instructions on deleting trace
-			  and log files, it is not necessary.
-			
+              Do not follow the instructions on deleting trace
+              and log files, it is not necessary.
+            
 root:~# exit
 joeuser:~$ exit

-		  Go back to the pop-up window and click "OK"
-		

-		  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"
-		

-			  Make sure the "Perform Typical installation" is
-			  not selected.
-			

-			  Click "Next"
-			
 
-			  The "Directory Service Access" screen in the
-			  "Net 8 Configuration Assistant"
-			

-			  Select "No"
-			

-			  Click "Next"
-			

-		  The "Listener Configuration, Listener Name" screen in
-		  the "Net 8 Configuration Assistant"
-		

-			  Accept the default listener name of "LISTENER"
-			

-			  Click "Next"
-			
 
-		  The "Listener Configuration, Select
-		  Protocols" screen in the "Net 8 Configuration
-		  Assistant"
-		

-			  The only choice in "Select protocols:" should be
-			  "TCP/IP"
-			

-			  Click "Next"
-			

-		  The "Listener Configuration TCP/IP Protocol" screen in
-		  the "Net 8 Configuration Assistant"
-		

-			  Default Port should be 1521 and selected.
-			

-			  Click "Next"
-			
 
-		  The "Listener Configuration, More Listeners" screen in
-		  the "Net 8 Configuration Assistant"
-		

-			  Select "No"
-			

-			  Click "Next"
-			

-		  The "Listener Configuration Done" screen in the
-		  "Net 8 Configuration Assistant"
-		

-			  Click "Next"
-			
 
-		  The "Naming Methods Configuration" screen
-		  in the "Net 8 Configuration Assistant"
-		

-			  Select "No"
-			

-			  Click "Next"
-			

-		  The "Done" screen in the "Net 8 Configuration
-		  Assistant"
-		

-			  Click "Finish"
-			

-		  The "End of Installation" screen in the OUI
-		

-			  Click "Exit"
-			

-			  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

-	  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 users: Before running dbassist, do the following.

-			Download the glibc
-			patch from Oracle Technet into 
/tmp.
-		  

-			cd $ORACLE_HOME
-			

-			tar xzf /tmp/glibc2.1.3-stubs.tgz
-			

-			./setup_stubs
-			
 
-		  Make sure you are running X. Open up a terminal and
-		  su to oracle and then run the
-		  dbassist program.
-		
+          Go back to the pop-up window and click "OK"
+        

+          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"
+        

+              Make sure the "Perform Typical installation" is
+              not selected.
+            

+              Click "Next"
+            
 
+              The "Directory Service Access" screen in the
+              "Net 8 Configuration Assistant"
+            

+              Select "No"
+            

+              Click "Next"
+            

+          The "Listener Configuration, Listener Name" screen in
+          the "Net 8 Configuration Assistant"
+        

+              Accept the default listener name of "LISTENER"
+            

+              Click "Next"
+            
 
+          The "Listener Configuration, Select
+          Protocols" screen in the "Net 8 Configuration
+          Assistant"
+        

+              The only choice in "Select protocols:" should be
+              "TCP/IP"
+            

+              Click "Next"
+            

+          The "Listener Configuration TCP/IP Protocol" screen in
+          the "Net 8 Configuration Assistant"
+        

+              Default Port should be 1521 and selected.
+            

+              Click "Next"
+            
 
+          The "Listener Configuration, More Listeners" screen in
+          the "Net 8 Configuration Assistant"
+        

+              Select "No"
+            

+              Click "Next"
+            

+          The "Listener Configuration Done" screen in the
+          "Net 8 Configuration Assistant"
+        

+              Click "Next"
+            
 
+          The "Naming Methods Configuration" screen
+          in the "Net 8 Configuration Assistant"
+        

+              Select "No"
+            

+              Click "Next"
+            

+          The "Done" screen in the "Net 8 Configuration
+          Assistant"
+        

+              Click "Finish"
+            

+          The "End of Installation" screen in the OUI
+        

+              Click "Exit"
+            

+              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

+      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.

+            Download the glibc
+            patch from Oracle Technet into /tmp.
+          

+            cd $ORACLE_HOME
+            

+            tar xzf /tmp/glibc2.1.3-stubs.tgz
+            

+            ./setup_stubs
+            
 
+          Make sure you are running X. Open up a terminal and
+          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
-		  Configuration Agent (ODCA)
-		

-			  Select "Create a database"
-			

-			  Click "Next"
-			

-		  The "Select database type" screen in the ODCA 
-		

-			  Select "Custom"
-			

-			  Click "Next"
-			

-		  The "Primary Database Type" window in ODCA 
-		

-			  Select "Multipurpose"
-			

-			  Click "Next"
-			

-		  The "concurrent users" screen of the ODCA 
-		

-			  Select "60" concurrent users. 
-			

-			  Click "Next"
-			

-		  Select "Dedicated Server
-			Mode", click
-		  "Next"
-		

-		  Accept all of the options, and click
-		  "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
-		  "Next".
-		

-		  Accept the defaults for the next screen (control file
-		  location). Click
-		  "Next"
-		

-		  Go to the "temporary" and
-		  "rollback" tabs, and change the Size
-		  (upper-right text box) to
-		  150MB. Click
-		  "Next"
-		

-		  Increase the redo log sizes to
-		  10000K each. Click
-		  "Next"
-		

-		  Use the default checkpoint interval & timeout. Click
-		  "Next"
-		
 		  
-		  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"
-		

-		  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"
-		  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
-		
 
-		  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
-		  the database initialization script (run when the db loads). The
-		  scripts are kept in
-		  $ORACLE_HOME/dbs and the name of
-		  the script is usually
-		  initSID.ora
-		  where SID is the SID of your
-		  database. Assuming your
-		  $ORACLE_HOME matches our default
-		  of
-		  /ora8/m01/app/oracle/product/8.1.7,
-		  the following will open the file for editing.
-		
+          The "Welcome" screen in the Oracle Database
+          Configuration Agent (ODCA)
+        

+              Select "Create a database"
+            

+              Click "Next"
+            

+          The "Select database type" screen in the ODCA 
+        

+              Select "Custom"
+            

+              Click "Next"
+            

+          The "Primary Database Type" window in ODCA 
+        

+              Select "Multipurpose"
+            

+              Click "Next"
+            

+          The "concurrent users" screen of the ODCA 
+        

+              Select "60" concurrent users. 
+            

+              Click "Next"
+            

+          Select "Dedicated Server
+            Mode", click
+          "Next"
+        

+          Accept all of the options, and click
+          "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
+          "Next".
+        

+          Accept the defaults for the next screen (control file
+          location). Click
+          "Next"
+        

+          Go to the "temporary" and
+          "rollback" tabs, and change the Size
+          (upper-right text box) to
+          150MB. Click
+          "Next"
+        

+          Increase the redo log sizes to
+          10000K each. Click
+          "Next"
+        

+          Use the default checkpoint interval & timeout. Click
+          "Next"
+        
        
+          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"
+        

+          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"
+          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
+        
 
+          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
+          the database initialization script (run when the db loads). The
+          scripts are kept in
+          $ORACLE_HOME/dbs and the name of
+          the script is usually
+          initSID.ora
+          where SID is the SID of your
+          database. Assuming your
+          $ORACLE_HOME matches our default
+          of
+          /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:
-		
+          Add the following line to the end:
+        
 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.
-		
+          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.
+        
 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
-		  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
-		  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.
-		
		  
-		  Change to the directory where the database creation script is and
-		  run it:
-		
+          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
+          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.
+        
        
+          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
-		  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.
-		

-		  Eventually, you'll be returned to your shell prompt. In the
-		  meantime, relax, you've earned it.
-		
Acceptance Test

-	  For this step, open up a terminal and
-	  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.
-		  It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt.
-		  Save the file to /tmp
-		

-		  In the oracle shell, copy the file.
-		
-oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql
		  
-		  Once you've got the acceptance test file all set, stay in
-		  your term and type the following:
-		
+          In some instances, Oracle will save the file to
+          /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.
+        

+          Eventually, you'll be returned to your shell prompt. In the
+          meantime, relax, you've earned it.
+        
Acceptance Test

+      For this step, open up a terminal and
+      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.
+          It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt.
+          Save the file to /tmp
+        

+          In the oracle shell, copy the file.
+        
+oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql
        
+          Once you've got the acceptance test file all set, stay in
+          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
-		  Oracle instance is not running.  You can manually start it as
-		  the oracle user.
+          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.
 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
-		  something you'll remember):
-		
+          Now that you're into SQL*Plus, change the default passwords
+          for system, sys, and ctxsys to "alexisahunk" (or to
+          something you'll remember):
+        
 SQL> alter user system identified by alexisahunk;
 SQL> alter user sys identified by alexisahunk;
 SQL> alter user ctxsys identified by alexisahunk;

-		  Verify that your date settings are correct. 
-		
+          Verify that your date settings are correct. 
+        
 SQL> select sysdate from dual;

-		  If you don't see a date that fits the format
-		  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.
-		
+          If you don't see a date that fits the format
+          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.
+        
 SQL> @ /tmp/acceptance.sql
 
 ; A bunch of lines will scroll by.  You'll know if the test worked if
@@ -698,77 +892,77 @@
 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 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
-		  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
-		  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
-		  /tmp. Then, as 
-		  oracle, do the following:
-		
+          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 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
+          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
+          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
+          /tmp. Then, as 
+          oracle, do the following:
+        
 oracle:~$ cp /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
-		  database at start.  Edit the file
-		  /etc/oratab: 
-		
You will see this line. 
+          While you're logged in as
+          oracle, you should configure the
+          oratab file to load your
+          database at start.  Edit the file
+          /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)
-			

-			  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.
-			
+              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)
+            

+              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
-		  /tmp. Then login as
-		  root and install the
-		  script. (Debian users: substitute
-		  /etc/init.d for
-		  /etc/rc.d/init.d throughout 
-		  this section)
-		
+              Save the file & quit the terminal.
+            
 
+          You need a script to automate startup and shutdown. Save oracle8i.txt in
+          /tmp. Then login as
+          root and install the
+          script. (Debian users: substitute
+          /etc/init.d for
+          /etc/rc.d/init.d throughout 
+          this section)
+        
 oracle:~$ su -
 root:~# cp /tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i
 root:~# chown root.root /etc/rc.d/init.d/oracle8i
 root:~# chmod 700 /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)
-		
+          Test the script by typing the following commands and checking the
+          output. (Debian Users: as root, do mkdir
+          /var/lock/subsys first)
+        
 root:~# /etc/rc.d/init.d/oracle8i stop
 Oracle 8i auto start/stop
 Shutting Oracle8i:
@@ -811,10 +1005,10 @@
 
 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:
+Database "ora8" warm started.
        
+          If it worked, then run these commands to make the startup and
+          shutdown automatic. 
+        
Red Hat users:
 root:~# cd /etc/rc.d/init.d/                      
 root:~# chkconfig --add oracle8i
 root:~# chkconfig --list oracle8i
@@ -869,24 +1063,24 @@
 Executing /sbin/conf.d/SuSEconfig.ypclient...
 Processing index files of all manpages...
 Finished.

-		  You also need some scripts to automate startup and shutdown of
-		  the Oracle8i listener. The listener is a name server that allows
-		  your Oracle programs to talk to local and remote databases using
-		  a standard naming convention. It is required for Intermedia Text
-		  and full site search.
-		

-		  Download these three scripts into
-		  /tmp
-		

-			  startlsnr.txt
-			

-			  stoplsnr.txt
-			

-			  listener8i.txt
-			

-		  Now issue the following commands (still as
-		  root).
-		
+          You also need some scripts to automate startup and shutdown of
+          the Oracle8i listener. The listener is a name server that allows
+          your Oracle programs to talk to local and remote databases using
+          a standard naming convention. It is required for Intermedia Text
+          and full site search.
+        

+          Download these three scripts into
+          /tmp
+        

+              startlsnr.txt
+            

+              stoplsnr.txt
+            

+              listener8i.txt
+            

+          Now issue the following commands (still as
+          root).
+        
 root:~# su - oracle
 oracle:~$ cp /tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
 oracle:~$ cp /tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr    
@@ -896,9 +1090,9 @@
 root:~# cp /tmp/listener8i.txt /etc/rc.d/init.d/listener8i
 root:~# cd /etc/rc.d/init.d
 root:/etc/rc.d/init.d# chmod 700 listener8i

-		  Test the listener automation by running the following commands
-		  and checking the output.
-		
+          Test the listener automation by running the following commands
+          and checking the output.
+        
 root:/etc/rc.d/init.d# ./listener8i stop
 Oracle 8i listener start/stop
 Shutting down Listener for 8i: 
@@ -941,13 +1135,13 @@
   PLSExtProc        has 1 service handler(s)
   ora8      has 1 service handler(s)
 The command completed successfully

-		  This test will verify that the listener is operating
-		  normally. Login into the database using the listener naming
-		  convention.
-		

-		  sqlplus
-		  username/password/@SID
-		
+          This test will verify that the listener is operating
+          normally. Login into the database using the listener naming
+          convention.
+        

+          sqlplus
+          username/password/@SID
+        
 root:~# su - oracle
 oracle:~$ sqlplus system/alexisahunk@ora8
 
@@ -960,16 +1154,16 @@
 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 ...
    /etc/rc0.d/K19listener8i -> ../init.d/listener8i
@@ -979,54 +1173,54 @@
    /etc/rc3.d/S21listener8i -> ../init.d/listener8i
    /etc/rc4.d/S21listener8i -> ../init.d/listener8i
    /etc/rc5.d/S21listener8i -> ../init.d/listener8i

-		  Test the automation
-		

-		  As a final test, reboot your computer and make sure Oracle comes
-		  up. You can do this by typing
-		
+          Test the automation
+        

+          As a final test, reboot your computer and make sure Oracle comes
+          up. You can do this by typing
+        
 root:~# /sbin/shutdown -r -t 0 now

-		  Log back in and ensure that Oracle started automatically. 
-		
+          Log back in and ensure that Oracle started automatically. 
+        
 joeuser:~$ su - oracle
 oracle:~$ sqlplus system/alexisahunk@ora8
 
 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'.
-	

-	  To fix this, you should include the following line in
-	  $ORACLE_HOME/dbs/initSID.ora
-	  or for the default case,
-	  $ORACLE_HOME/dbs/initora8.ora
-	
+      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'.
+    

+      To fix this, you should include the following line in
+      $ORACLE_HOME/dbs/initSID.ora
+      or for the default case,
+      $ORACLE_HOME/dbs/initora8.ora
+    
 nls_date_format = "YYYY-MM-DD"

-	  You test whether this solved the problem by firing up
-	  sqlplus and typing: 
-	
+      You test whether this solved the problem by firing up
+      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,
-	  everything is still fine. The problem here is that
-	  sqlplus is simply truncating the
-	  output. You can fix this by typing:
-	
+      You should see back a date like
+      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
+      output. You can fix this by typing:
+    
 SQL> column sysdate format a15
 SQL> select sysdate from dual;

-	  If the date does not conform to this format, double-check that you
-	  included the necessary line in the init scripts. If it still
-	  isn't working, make sure that you have restarted the database
-	  since adding the line:
-	
-nsadmin:~$ svrmgrl
+      If the date does not conform to this format, double-check that you
+      included the necessary line in the init scripts. If it still
+      isn't working, make sure that you have restarted the database
+      since adding the line:
+    
+joeuser:~$ svrmgrl
 SVRMGR> connect internal
 Connected.
 SVRMGR> shutdown
@@ -1035,42 +1229,40 @@
 ORACLE instance shut down.
 SVRMGR> startup
 ORACLE instance started.

-	  If you're sure that you have restarted the database since adding
-	  the line, check your initialization scripts. Make sure that the
-	  following line is not included:
-	
+      If you're sure that you have restarted the database since adding
+      the line, check your initialization scripts. Make sure that the
+      following line is not included:
+    
 export nls_lang = american

-	  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:
-	
+      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:
+    
 export nls_date_format = 'YYYY-MM-DD'

-	  Log back in again. If adding the
-	  nls_date_format line doesn't
-	  help, you can ask for advice in our OpenACS forum.
-	
Useful Procedures

-		  Dropping a tablespace
-		

-			  Run sqlplus as the dba: 
-			
-oracle:~$ sqlplus system/changeme
			  
-			  To drop a user and all of the tables and data owned by that
-			  user: 
-			
+      Log back in again. If adding the
+      nls_date_format line doesn't
+      help, you can ask for advice in our OpenACS forum.
+    
Useful Procedures

+          Dropping a tablespace
+        

+              Run sqlplus as the dba: 
+            
+oracle:~$ sqlplus system/changeme
            
+              To drop a user and all of the tables and data owned by that
+              user: 
+            
 SQL> drop user oracle_user_name cascade;

-			  To drop the tablespace: This will delete everything in the
-			  tablespace overriding any referential integrity
-			  constraints. Run this command only if you want to clean out
-			  your database entirely.
-			
+              To drop the tablespace: This will delete everything in the
+              tablespace overriding any referential integrity
+              constraints. Run this command only if you want to clean out
+              your database entirely.
+            
 SQL> drop tablespace table_space_name including contents cascade constraints;

-	  For more information on Oracle, please consult the documentation.
-	
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
-			  access to the Oracle system.
($Id$)
Prev  Home  Next
Install an Operating System  Up  Install PostgreSQL 7.1.3
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+      For more information on Oracle, please consult the documentation.
+    
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
+              access to the Oracle system.
($Id$)
Prev  Home  Next
Install an Operating System  Up  Install PostgreSQL 7.2.3
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/other-developer-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/other-developer-overview.html,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/other-developer-overview.html	30 Nov 2002 17:16:24 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/other-developer-overview.html	28 Feb 2003 05:36:04 -0000	1.5
@@ -1,2 +1,2 @@
 
-OverviewPrev  Chapter�5.�Other Developer Resources  Next
Overview
Developer information that doesn't really fit anywhere else.
Prev  Home  Next
Chapter�5.�Other Developer Resources  Up  Parties in OpenACS 4.6
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
+OverviewPrev  Chapter 7. Other Developer Resources  Next
Overview
Developer information that doesn't really fit anywhere else.
Prev  Home  Next
Chapter 7. Other Developer Resources  Up  Parties in OpenACS 4.6
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/packages.html	10 Aug 2002 20:07:20 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/packages.html	28 Feb 2003 05:36:04 -0000	1.9
@@ -1,10 +1,10 @@
 
-OpenACS 4.5 PackagesPrev  Chapter 4. OpenACS Developer's Guide  Next
OpenACS 4.5 Packages

+OpenACS 4.6 Packages
Prev  Chapter 6. OpenACS Developer's Guide  Next
OpenACS 4.6 Packages

     By Pete Su and Bryan Quinn
   

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

+          OpenACS docs are written by the named authors, but 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).  This document presents reasons
@@ -61,7 +61,7 @@
       the pieces of each module are strewn all over the tree in at least 3
       or 4 different areas. 
     

-      Here is how an OpenACS 4.5 server is laid out:
+      Here is how an OpenACS 4.6 server is laid out:
     
 
 ROOT/
@@ -125,7 +125,7 @@
       sends to our server to the right page in the appropriate
       package. While we're at it, this tool should also automate
       package installation, dependency checking, upgrades, and package
-      removal. In OpenACS 4.5, this tool is called the APM.
+      removal. In OpenACS 4.6, this tool is called the APM.
     
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
@@ -147,7 +147,7 @@
     

       The following sections will show you how to make a package for the
       Notes application. In addition, they will discuss some new site
-      management features in OpenACS 4.5 that take advantage of the APM's package
+      management features in OpenACS 4.6 that take advantage of the APM's package
       instance model. The two most important of these are subsites,
       and the site map tool, which can be used to map applications to
       one or more arbitrary URLs in a running site.
@@ -365,7 +365,7 @@
           notes.info file. Create a file
           called
           ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
-          fill this file with our data model
+          fill this file with our data model
           very soon. Create a file called
           ROOT/packages/notes/sql/oracle/notes-drop.sql. This
           will contain the instructions to drop the data model. To be
@@ -435,7 +435,7 @@
       map content that lived outside the page root into the site, and it was
       also hard to map mulitiple URLs to the same place in the file system.
     

-      In OpenACS 4.5, administrators can define an arbitrary mapping between the
+      In OpenACS 4.6, administrators can define an arbitrary mapping between the
       URLs the user types and the actual file in the file system that is
       served. This mapping is called the site map and entries in the
       site map are called site nodes. Each site node maps a URL to an
@@ -450,7 +450,7 @@
       of many indedendent applications that actually run on a single shared
       code base. The request-processor document shows
       you how OpenACS figures out which instance of your application was
-      requested by the user at any given time. The page development tutorial shows you how to use this
+      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
@@ -477,7 +477,7 @@
       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.
+      to supporting subsites.
     
Summary

       The APM performs the following tasks in an OpenACS site:
     

@@ -493,6 +493,4 @@
     

       Writes out package distribution files for other people to download and
       install. We'll cover this later.
-    
Additional Reading
OpenACS 4.5 Package Manager Design
OpenACS 4.5 Package Manager Requirements
Package submission guidelines
($Id$)
Prev  Home  Next
Overview  Up  OpenACS 4.5 Data Models and the Object System
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+    
Additional Reading
OpenACS 4.6 Package Manager Design
OpenACS 4.6 Package Manager Requirements
Package submission guidelines
($Id$)
Prev  Home  Next
OpenACS 4.6 Package Tutorial  Up  OpenACS Data Models and the Object System
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/parties.html	10 Aug 2002 20:07:20 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/parties.html	28 Feb 2003 05:36:04 -0000	1.9
@@ -1,9 +1,9 @@
 
-Parties in OpenACS 4.5Prev  Chapter 5. Other Developer Resources  Next
Parties in OpenACS 4.5

+Parties in OpenACS 4.6
Prev  Chapter 7. Other Developer Resources  Next
Parties in OpenACS 4.6

 by Rafael H. Schloming

-		  OpenACS docs are written by the named authors, but may be edited
-		  by OpenACS documentation staff.
-		
Introduction
While many applications must deal with individuals and many applications
+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
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 in many
 respects both individuals and groups are treated in an identical manner. It
@@ -67,7 +67,7 @@
 users) is that it is now possible to "nuke" a user from a live
 system by removing his entry from the users table, but leaving the rest of
 his information present (i.e. turning him from a user into a person). This is
-because wherever possible the OpenACS 4.5 data model references the persons or
+because wherever possible the OpenACS 4.6 data model references the persons or
 parties table, not the users table. If this feature is
 desired when extending the system, then the developers should be careful to
 only references the users table in situations where it is clear that the
@@ -299,7 +299,7 @@
 have a primary key that references the users table, thereby guaranteeing that
 each row in the mensa_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 MENSA community.
Specializing Groups
If one were to build an intranet application on top of the 4.5 party
+store any extra information relevant to the MENSA community.
Specializing Groups
If one were to build an intranet application on top of the 4.6 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.
@@ -313,6 +313,4 @@
 single integer primary key in what could be thought of as a pure relation.
 Because a membership relation is an ordinary acs object with object identity, it is as easy to extend the
 membership relation to store extra information as it is to extend the users
-table or the groups table.
($Id$)
Prev  Home  Next
Overview  Up  Object Identity
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+table or the groups table.
($Id$)
Prev  Home  Next
Overview  Up  OpenACS 4.x Permissions Tediously Explained
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/permissions-design.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/permissions-design.html	28 Feb 2003 05:36:04 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Permissions DesignPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Permissions Design

+OpenACS 4 Permissions Design
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Permissions Design

 by John Prevost and Rafael H. Schloming

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -48,14 +48,14 @@
 
 
The set of all defined privileges.
acs_privilege_method_rules
 
-
A relation describing the set of methods directly
+
A relation describing the set of methods directly
 associated with each privilege.
acs_privilege_hierarchy
 
-
A relation describing which privileges directly
+
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
@@ -78,7 +78,7 @@
 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
@@ -95,15 +95,15 @@
 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
+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
 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
@@ -112,7 +112,7 @@
 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
+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
@@ -127,15 +127,15 @@
 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
+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
 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
+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
@@ -154,7 +154,7 @@
   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
+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
@@ -184,4 +184,4 @@
 
 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
OpenACS 4 Permissions Requirements  Up  OpenACS 4 Groups Requirements
rmello at fslc.usu.edu
vinod@kurup.com
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
OpenACS 4 Permissions Requirements  Up  OpenACS 4.6 Internationalization Requirements
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/permissions-requirements.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html	28 Feb 2003 05:36:04 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Permissions RequirementsPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Permissions Requirements

+OpenACS 4 Permissions Requirements
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Permissions Requirements

 by John McClary Prevost

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -15,7 +15,7 @@
 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
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
@@ -33,14 +33,14 @@
 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
+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
 system subject to control, this word is used to represent the fact that a
@@ -50,43 +50,43 @@
 that operation.
Examples of the essential question addressed by the Permissions system:
 Can jane@attacker.com delete the web security bboard? Can the Boston office
 (a party) within the VirtuaCorp intranet/website create its own news
-instance?
Related Links
OpenACS 4 Permissions Design
Functional Requirements
10.0 Granularity
The system must support access control down to the level of a single
+instance?
Related Links
OpenACS 4 Permissions Design
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
+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 bboard, 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
+"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
+"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 bboard, you
-should not have read access to a message in that bboard.
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 bboard.
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 bboard. 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
+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
+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
OpenACS 4 Object Model Design  Up  OpenACS 4 Permissions Design
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html	30 Nov 2002 17:16:24 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html	28 Feb 2003 05:36:05 -0000	1.3
@@ -1,5 +1,5 @@
 
-OpenACS 4.x Permissions Tediously ExplainedPrev  Chapter�5.�Other Developer Resources  Next
OpenACS 4.x Permissions Tediously Explained

+OpenACS 4.x Permissions Tediously Explained
Prev  Chapter 7. Other Developer Resources  Next
OpenACS 4.x Permissions Tediously Explained

     by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello
   
Overview

       The general permissions system has a relatively complex data model in OpenACS 4.x.
@@ -9,8 +9,8 @@
       of code and trying to understand exactly what went wrong.
       It is geared towards developers who understand the general permissions
       system to the extent that is described in the 
-      
-      OpenACS 4.x Permisisons documentation,
+      
+      OpenACS 4.x Permissions documentation,
       but who haven't had the opportunity to take a long, careful look at the
       system internals.
     

@@ -86,7 +86,7 @@
       to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users
       who have the read privilege on all objects, then we would need to store 100,000,000
       entries of the form: 
-    
Table�5.1.�
object_id grantee_id privilege
object_id_1 user_id_1 'read'
object_id_1 user_id_2 'read'
...
object_id_1 user_id_n 'read'
object_id_2 user_id_1 'read'
object_id_2 user_id_2 'read'
...
object_id_2 user_id_n 'read'
...
...
object_id_m user_id_1 'read'
object_id_m user_id_2 'read'
...
object_id_m user_id_n 'read'

+    
Table 7.1. 
object_id grantee_id privilege
object_id_1 user_id_1 'read'
object_id_1 user_id_2 'read'
...
object_id_1 user_id_n 'read'
object_id_2 user_id_1 'read'
object_id_2 user_id_2 'read'
...
object_id_2 user_id_n 'read'
...
...
object_id_m user_id_1 'read'
object_id_m user_id_2 'read'
...
object_id_m user_id_n 'read'

       Although quite feasible, this approach fails to take advantage of the fact
       that objects in the system are commonly organized hierarchally,
       and permissions usually follow the hierarchical structure, so that if user
@@ -101,7 +101,7 @@
     
Context Hierarchy

       Suppose objects A, B, ..., 
       and F form the following hierarchy. 
-    
Table�5.2.�
A
+    
Table 7.2. 
A
   	        object_id=10
               
B
   	        object_id=20
@@ -117,23 +117,23 @@
       This can be represented in the 
       acs_objects table
       by the following entries: 
-    
Table�5.3.�
object_id context_id
20 10
30 10
40 20
50 20
60 30

+    
Table 7.3. 
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,
       we can compute that object 40 is the second-generation descendant of object 10.
       With this in mind, if we want to record the fact that user Joe has the read privilege on objects
       A, ..., F, we only need to record one entry in the
       acs_permissions table. 
-    
Table�5.4.�
object grantee privilege
A Joe read

+    
Table 7.4. 
object grantee privilege
A Joe read

       The fact that Joe can also read B, C, 
       ..., and F can be derived by ascertaining that these objects 
       are children of A by traversing the context hierarchy.
       As it turns out, hierarchical queries are expensive.  As
       Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit. 
     

       One way to solve this problem is to cache a flattened view of the context tree like so: 
-    
Table�5.5.�
object ancestor n_generations
A A 0
B B 0
B A 1
C C 0
C A 1
D D 0
D B 1
D A 2
E E 0
E B 1
E A 2
F F 0
F C 1
F A 2

+    
Table 7.5. 
object ancestor n_generations
A A 0
B B 0
B A 1
C C 0
C A 1
D D 0
D B 1
D A 2
E E 0
E B 1
E A 2
F F 0
F C 1
F A 2

       Note that the number of entries in the flattened view grows exponentially with
       respect to the depth of the context tree.  For instance, if you have a fully
       populated binary tree with a depth of n, then the number of entries
@@ -163,9 +163,9 @@
       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
@@ -204,7 +204,7 @@
       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. 
-    
Table�5.6.�


+    
Table 7.6. 


 A

 object_id=10

 readable�by�Joe

@@ -232,7 +232,7 @@
       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. For instance,
       the Bboard package defines the following privileges: 
-    
Table�5.7.�
privilege
create_category
create_forum
create_message
delete_category
delete_forum
delete_message
moderate_forum
read_category
read_forum
read_message
write_category
write_forum
write_message

+    
Table 7.7. 
privilege
create_category
create_forum
create_message
delete_category
delete_forum
delete_message
moderate_forum
read_category
read_forum
read_message
write_category
write_forum
write_message

       By defining parent-child relationship between privileges, the OpenACS data model
       makes it easier for developers to manage permissions.  Instead of granting
       a user explicit read, write, delete, 
@@ -241,7 +241,7 @@
       privilege to which the first four privileges are tied. To give
       a more detailed example, the Bboard privileges are structured
       as follows.
-    
Table�5.8.�
admin
create delete read write moderate forum
create category create forum create message delete category delete forum delete message read category read forum read message write category write forum write message

+    
Table 7.8. 
admin
create delete read write moderate forum
create category create forum create message delete category delete forum delete message read category read forum read message write category write forum write message

       The parent-child relationship between privileges is represented in
       the acs_privilege_hierarchy table: 
     
@@ -287,7 +287,7 @@
     
Party Hierarchy

       Now for the third hierarchy playing a promiment role in the permission system. The party
       data model is set up as follows. 
-    
Table�5.9.�
parties
persons groups
users
+    
Table 7.9. 
parties
persons groups
users
   create table parties (
       party_id
           not null
@@ -371,7 +371,7 @@
     

       The acs_rels 
       table entries would look like so: 
-    
Table�5.10.�
rel_type object_one object_two

+    
Table 7.10. 
rel_type object_one object_two

 	      membership_rel
 	    
 	      Pranksters
@@ -393,7 +393,7 @@
       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. 
@@ -406,7 +406,7 @@
     
       The relevant entries in the 
       acs_rels look like so. 
-    
Table�5.11.�
rel_type object_one object_two

+    
Table 7.11. 
rel_type object_one object_two

 	      composition_rel
 	    
 	      Pranksters
@@ -617,7 +617,7 @@
     
       Note that in the above example, acs_permissions had only
       one entry that needed to be deleted: 
-    
Table�5.12.�
object_id grantee_id privilege

+    
Table 7.12. 
object_id grantee_id privilege

 	      default_context
 	    
 	      registered_users
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/permissions.html	10 Aug 2002 20:07:20 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/permissions.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,9 +1,9 @@
 
-Groups, Context, PermissionsPrev  Chapter 4. OpenACS Developer's Guide  Next
Groups, Context, Permissions
By Pete Su


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

-The OpenACS 4.5 Permissions system allows developers and administrators to
+Groups, Context, Permissions
Prev  Chapter 6. OpenACS Developer's Guide  Next
Groups, Context, Permissions
By Pete Su


+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
Overview

+The OpenACS 4.6 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 simple
@@ -14,7 +14,7 @@
 Although this may all sound easy and wonderful, no developer or
 administrator would want to explicitly set access control
 rights for every user and every object on a
-site. Therefore, OpenACS 4.5 has two auxiliary mechanisms for making this
+site. Therefore, OpenACS 4.6 has two auxiliary mechanisms for making this
 easier: First, the Groups system allows users to be grouped together
 in flexible ways. Second, the object model defines a notion of
 object context, which allows applications to group objects
@@ -26,7 +26,7 @@
 define simple groupings of users. Each group had a human readable name
 and unique ID, and there was a single mapping table that mapped users
 to groups. (The actual data model was more complicated because it
-contained a meta-data system much like the OpenACS 4.5 object type system,
+contained a meta-data system much like the OpenACS 4.6 object type system,
 but that's not relevant right now.)
 

 The 3.x groups system, while very useful, was limited in few ways. The
@@ -48,7 +48,7 @@
 member of Greenpeace, its members are not necessarily members of
 Greenpeace.
 

-OpenACS 4.5 solves both of these modeling problems by introducing a new
+OpenACS 4.6 solves both of these modeling problems by introducing a new
 abstraction called a party. Parties have a recursive
 definition, and we can illustrate how it works with the following
 simplified data model. First, we define the parties
@@ -105,23 +105,27 @@
 tutorial - I've just given you what you need to understand how
 permissions work. For further detail, you can look at Parties in OpenACS 4 or OpenACS 4 Groups Design.
 
Permissions

+  NOTE: Much more detailed information about the permissions system
+  and how to use it is available in the
+  OpenACS Permissions Tediously Explained document.
+

 The permissions data model is actually pretty simple.  The data model
 is a mapping between privileges, parties and objects. We
 already know what parties and objects are, but we don't know what
 privileges are.
 

-In OpenACS 4.5, a privilege models the right to perform some operation on
+In OpenACS 4.6, a privilege models the right to perform some operation on
 some object. They are the basic units out of which we build access
 control policies.  For example, in the Unix filesystem we typically
 implement access control by granting users some combination of
-read. write or execute privileges on files and directories. In OpenACS 4.5,
+read. write or execute privileges on files and directories. In OpenACS 4.6,
 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 if we grant a user this privilege she is
 automatically granted all the child privileges that the privilege
-contains. The OpenACS 4.5 kernel data model actually defines these
+contains. The OpenACS 4.6 kernel data model actually defines these
 privileges as follows:
 
 
@@ -161,7 +165,7 @@
 permissions to large groups of objects in the site, all at once. We
 use contexts to achieve this goal.
 
Object Context

-In OpenACS 4.5, an object context is a generalization of the scoping
+In OpenACS 4.6, an object context is a generalization of the scoping
 mechanism introduced in OpenACS 3.x.  "Scoping" and "scope" are terms best
 explained by example: consider some hypothetical rows in the
 address_book table:
@@ -176,7 +180,7 @@
 person or a group of people or the general public
 (itself a group of people).
 

-In OpenACS 4.5, rather than breaking the world into a limited set of scopes,
+In OpenACS 4.6, rather than breaking the world into a limited set of scopes,
 every object lives in a single context.  A context is just an
 another object that represents the security domain to which the object
 belongs. By convention, if an object A doesn't have any permissions
@@ -193,7 +197,7 @@
 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.  In OpenACS 4.5,
+privileges whenever we create a message, which is tedious.  In OpenACS 4.6,
 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
 forum. Then, suppose we grant every user in the system read-access to
@@ -327,7 +331,7 @@
 

 This displays the title of the note as either a link or plain text
 depending on whether or not we have write privileges on the object.
-The if tag is something that the OpenACS 4.5 template system
+The if tag is something that the OpenACS 4.6 template system
 defines for you to support conditional presentation. The templates developer guide provides more information about this.
 

 If you study the rest of the system, you will also notice that the
@@ -341,7 +345,7 @@
 permissions to notes that she wanted to make public or whatever. But
 that's beyond the scope of this example.
 
Summary

-OpenACS 4.5 defines three separate mechanisms for specifying access control
+OpenACS 4.6 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. The Permissions
 data model allows you to define a hierarchy of user rights. Finally,
@@ -351,6 +355,4 @@
 

 In the next section, we'll look at a more complex page for adding and
 editing notes, and discuss these issues further.
-
($Id$)
Prev  Home  Next
Using Templates in OpenACS 4.5  Up  Writing OpenACS 4.5 Application Pages
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
($Id$)
Prev  Home  Next
Using Templates in OpenACS 4.6  Up  Writing OpenACS 4.6 Application Pages
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/postgres.html	10 Aug 2002 20:07:21 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/postgres.html	28 Feb 2003 05:36:05 -0000	1.7
@@ -1,22 +1,24 @@
 
-Install PostgreSQL 7.1.3Prev  Chapter 2. Installing on Unix/Linux  Next
Install PostgreSQL 7.1.3

-	by Vinod Kurup

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

+Install PostgreSQL 7.2.3
Prev  Chapter 2. Installing on Unix/Linux  Next
Install PostgreSQL 7.2.3

+    by Vinod Kurup

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

 	Skip this page if you're not interested in PostgreSQL.
   
Download the PostgreSQL source
	  
-	  Download PostgreSQL 7.1.3 from the mirror closest to you. The list of
-	  mirrors is at http://www.postgresql.org. Download
-	  it to /tmp.
-	

+
+	  Download PostgreSQL 7.2.3 from the mirror closest to you. The list of
+	  mirrors is at http://www.postgresql.org.
+	  Download it to /tmp.
+
+    

 	  As root, unpack it into
 	  /usr/local/src
-	
+  	
 joeuser:~$ su -
 Password: ***********
 root:~# cd /usr/local/src
-root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz
Create the Postgres user

+root:/usr/local/src# tar xzf /tmp/postgresql-7.2.3.tar.gz
Create the Postgres user

 	  Still as root, 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
@@ -28,7 +30,7 @@
 root:~# passwd postgres
 
 root:~# mkdir -p /usr/local/pgsql
-root:~# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.1.3
+root:~# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.2.3
 root:~# chmod 750 /usr/local/pgsql
 root:~# exit
 logout
@@ -41,79 +43,94 @@
 PATH=$PATH:/usr/local/pgsql/bin
 
 export PATH LD_LIBRARY_PATH

-	  Logout and login again as postgres. Use the
+
+	  Logout and login again as
+	  postgres. Use the
 	  echo command to make sure that
 	  /usr/local/pgsql/bin is now in your
 	  PATH
+
 	
 postgres:~$ exit
 logout
 joeuser:~$ su - postgres
 Password: ************
 postgres:~$ echo $PATH
 /usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin
Compile and install PostgreSQL

+
 	  First, we 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 want to
-	  enable Unicode support, add the flags
+	  enable  support, add the flags
 	  --enable-locale and
 	  --enable-multibyte. If you want to
 	  see what the other possibilities are, run ./configure
 	  --help.
+
 	
-postgres:~$ cd /usr/local/src/postgresql-7.1.3
-postgres:/usr/local/src/postgresql-7.1.3$ ./configure
-postgres:/usr/local/src/postgresql-7.1.3$ make all

+postgres:~$ cd /usr/local/src/postgresql-7.2.3
+postgres:/usr/local/src/postgresql-7.2.3$ ./configure
+postgres:/usr/local/src/postgresql-7.2.3$ make all

+
 	  Compilation will take a while (about 10 minutes). Once it's done, you
 	  will see the following message:
+
 	
 All of PostgreSQL is successfully made. Ready to install.

+
 	  Next, we'll install PostgreSQL. If all is successful, you'll see the
 	  following “Thank You” message.
+
 	
-postgres:/usr/local/src/postgresql-7.1.3$ make install
+postgres:/usr/local/src/postgresql-7.2.3$ make install
 ...
 Thank you for choosing PostgreSQL, the most advanced open source database engine.
Prepare PostgreSQL for OpenFTS

-	  OpenFTS is the module that provides full text search to OpenACS 4.5. We
-	  won't be installing it until later, but we'll set up a couple things
-	  that are best done right now.
+	  OpenFTS is the module that provides full text search to OpenACS
+	  4.6. We won't be installing it until later, but since it needs
+	  a special PostgreSQL module called 'tsearch', we'll install it now.
 	
-postgres:/usr/local/src/postgresql-7.1.3$ make install-all-headers
-postgres:/usr/local/src/postgresql-7.1.3$ cd contrib/intarray
-postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make
-postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make install
Start PostgreSQL
The initdb command initializes
-	  the database. pg_ctl is used to
-	  start up PostgreSQL.
+postgres:/usr/local/src/postgresql-7.2.3$ cd contrib/tsearch
+postgres:/usr/local/src/postgresql-7.2.3/contrib/tsearch$ make
+postgres:/usr/local/src/postgresql-7.2.3/contrib/tsearch$ make install
Start PostgreSQL

+
+	  The initdb command initializes the
+	  database. pg_ctl is used to start up
+	  PostgreSQL.
+	
 	
-postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ cd
+postgres:/usr/local/src/postgresql-7.2.3/contrib/tsearch$ cd
 postgres:~$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
 postgres:~$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
 postmaster successfully started

+
 	  PostgreSQL errors will be logged in
 	  /usr/local/pgsql/data/server.log
-	
Set up plpgsql and allow nsadmin access

-	  We have to install plpgsql into our PostgreSQL installation so that
-	  we can use stored procedures. Fortunately, it's pretty easy. We'll
-	  also create a database user named
-	  nsadmin, so that aolserver can
-	  access the database. (Don't worry that you don't have a
-	  nsadmin user yet - we'll create that
-	  in the next chapter.)
+
+	
Set up plpgsql and allow your user to have access

+
+	  Next, we'll install plpgsql into our PostgreSQL installation so that
+	  we can use stored procedures. We'll also create a database user named
+	  joeuser (replace with your own
+	  username), so that you'll be able to access the database via
+	  AOLserver.
+
 	
 postgres:~$ createlang plpgsql template1
 postgres:~$ # Test if we succeeded
 postgres:~$ createlang -l template1
-     Procedural languages
-  Name   | Trusted? | Compiler 
----------+----------+----------
- plpgsql | t        | PL/pgSQL
+Procedural languages
+  Name   | Trusted?  
+---------+----------
+ plpgsql | t        
 (1 row)
-postgres:~$ createuser nsadmin
+postgres:~$ createuser joeuser
 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
Test PostgreSQL

+
 	  Create a database and try some simple commands. The output should be
 	  as shown.
+
 	
 postgres:~$ createdb mytestdb
 CREATE DATABASE
@@ -143,9 +160,11 @@
 mytestdb=# \q
 postgres:~$ dropdb mytestdb
 DROP DATABASE
Getting PostgreSQL to start on boot

+
 	  Download postgresql.txt to
 	  /tmp. Then follow the instructions
 	  specific to your distribution:
+
 	
Debian:
 postgres:~$ su -
 Password: ***********
@@ -154,9 +173,11 @@
 root:~# chmod 700 /etc/init.d/postgresql
Test the script
 root:~# /etc/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:~# update-rc.d postgresql defaults
  Adding system startup for /etc/init.d/postgresql ...
@@ -175,11 +196,18 @@
 Password: ***********
 root:~# cp /tmp/postgresql.txt /etc/rc.d/init.d/postgresql
 root:~# chown root.root /etc/rc.d/init.d/postgresql
-root:~# chmod 700 /etc/rc.d/init.d/postgresql
Test the script
+root:~# chmod 700 /etc/rc.d/init.d/postgresql

+
+		  Test the script.
+
+		
 root:~# /etc/rc.d/init.d/postgresql stop
-Stopping PostgreSQL: ok
If PostgreSQL successfully stopped, then use the following
+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:~# chkconfig --add postgresql
 root:~# chkconfig --list postgresql
@@ -188,18 +216,34 @@
 root:~# /etc/rc.d/init.d/postgresql start
 Starting PostgreSQL: ok
 root:~# exit
-postgres:~$ exit
SuSE:
+postgres:~$ exit
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
+            you're using SuSE 8.0, delete the
+            rc.d/ part in each of the
+            following commands.
+
+          
 postgres:~$ su -
 Password: ***********
 root:~# cp /tmp/postgresql.txt /etc/rc.d/init.d/postgresql
 root:~# chown root.root /etc/rc.d/init.d/postgresql
-root:~# chmod 700 /etc/rc.d/init.d/postgresql
Test the script
+root:~# chmod 700 /etc/rc.d/init.d/postgresql

+
+          Test the script.
+
+        
 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.
-		
+
+          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  
@@ -213,29 +257,43 @@
 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

-		  Test configuration
-		
+
+          Test configuration.
+
+        
 root:/etc/rc.d/init.d # cd
 root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start
 Starting PostgreSQL: ok
 root:~ # exit

-	  From now on, PostgreSQL should start automatically each time you boot
-	  up and it should shutdown gracefully each time you shut down. (Note:
-	  Debian defaults to starting all services on runlevels 2-5. Red Hat
-	  defaults to starting services on 3-5. So, on Red Hat, PostgreSQL won't
-	  start on runlevel 2 unless you alter the above commands a
-	  little. This usually isn't a problem as Red Hat defaults to runlevel 3)
-	
Learn more about PostgreSQL

-		  Here are some links: 
-	

-		  Official PostgreSQL Docs
-		

-		  Migrating from 7.0 to 7.1
-		

-		techdocs.postgresql.org
-		

-		  PostgreSQL
-		Performance Tuning
-		
($Id$)
Prev  Home  Next
Install Oracle 8.1.7  Up  Install AOLserver 3.3+ad13
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
+      From now on, PostgreSQL should start automatically each time you boot
+      up and it should shutdown gracefully each time you shut down. (Note:
+      Debian defaults to starting all services on runlevels 2-5. Red Hat
+      defaults to starting services on 3-5. So, on Red Hat, PostgreSQL won't
+      start on runlevel 2 unless you alter the above commands a
+      little. This usually isn't a problem as Red Hat defaults to runlevel 3)
+
+    
Learn more about PostgreSQL

+
+          Here are some links: 
+
+    

+
+          Official PostgreSQL
+          Docs
+
+        

+
+          Migrating
+          from 7.0 to 7.1
+
+        

+
+          techdocs.postgresql.org
+
+        

+          
+          PostgreSQL
+        Performance Tuning
+
+        
($Id$)
Prev  Home  Next
Install Oracle 8.1.7  Up  Install AOLserver 3.3+ad13
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,10 +1,10 @@
 
-Programming with AOLserverPrev  Chapter 5. Other Developer Resources  Next
Programming with AOLserver

+Programming with AOLserver
Prev  Chapter 7. Other Developer Resources  Next
Programming with AOLserver

 by Michael Yoon, Jon Salz and Lars Pind. 
 

-		  OpenACS docs are written by the named authors, but may be edited
-		  by OpenACS documentation staff.
-		
The global command

+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
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
@@ -42,7 +42,7 @@
 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
+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.
@@ -212,6 +212,4 @@
 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
 entries is large. 
-
($Id$)
Prev  Home  Next
Object Identity  Up  Chapter 6. Engineering Standards
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
($Id$)
Prev  Home  Next
Object Identity  Up  Chapter 8. Engineering Standards
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/psgml-mode.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,9 +1,9 @@
 
-Using PSGML mode in EmacsPrev  Chapter 6. Engineering Standards  Next
Using PSGML mode in Emacs

+Using PSGML mode in Emacs
Prev  Chapter 8. Engineering Standards  Next
Using PSGML mode in Emacs

 By David Lutterkort

-		  OpenACS docs are written by the named authors, but may be edited
-		  by OpenACS documentation staff.
-		
What it is
PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It
+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
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,
@@ -84,6 +84,4 @@
 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 OpenACS Documentation Guide
($Id$)
Prev  Home  Next
OpenACS Documentation Guide  Up  Detailed Design Documentation Template
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+what its contents can be and lists its attributes.
Further reading
Start with the OpenACS Documentation Guide
($Id$)
Prev  Home  Next
OpenACS Documentation Guide  Up  Detailed Design Documentation Template
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/release-notes.html	10 Aug 2002 20:07:21 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/release-notes.html	28 Feb 2003 05:36:05 -0000	1.10
@@ -1,35 +1,35 @@
 
-OpenACS 4.5 Release NotesPrev  Chapter 1. High level information: What is OpenACS?  Next
OpenACS 4.5 Release Notes

+OpenACS 4.6 Release Notes
Prev  Chapter 1. High level information: What is OpenACS?  Next
OpenACS 4.6 Release Notes

 	  by Don Baccus

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

-	This is a final release of OpenACS 4.5.  This release has been subjected
+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        

+	This is a final release of OpenACS 4.6.  This release has been subjected
 	to an organized test effort, but please bear in mind that we are still
 	in the process of developing testing tools, methodology, and scripts.
   

 	Please report bugs using our
-	
-	  Software Development Manager at the OpenACS website.  The latest
-	information on installing this release under Oracle 8.1.6/7
-	or PostgreSQL 7.1.* can be found there as well.  Currently the
+	
+	  Bug Tracker at the OpenACS website.  The latest
+	information on installing this release under Oracle 8.1.7
+	or PostgreSQL 7.2.* can be found there as well.  Currently the
 	toolkit will not install under Oracle 9i due to Oracle having made
 	"delete" an illegal name for PL/SQL procedures and functions.
   

 	You may want to begin by reading our installation documentation for
-	Installing on Unix/Linux or Installing on Windows.  Note
-	that the Windows documentation is not current for OpenACS 4.5,
-	but an alternative is to use John Sequeira's Oasis VM
+	Installing on Unix/Linux.  Note that the Windows documentation is
+	not current for OpenACS 4.6, but an alternative is to use John
+	Sequeira's Oasis VM
 	project.
   

 	After installation, the full documentation set can be found by visiting
-	http://[your-host]/doc. Not all pieces are updated for OpenACS 4.5 at
+	http://[your-host]/doc. Not all pieces are updated for OpenACS 4.6 at
 	this moment.
   
Site Wide Searching

 	  If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
 	  to uncomment the SQL that causes InterMedia to keep online searching
 	  online while indexing.  The feature doesn't exist in Standard Edition
-	  and OpenACS 4.5 now defaults to being loadable in SE.  Just grep for
+	  and OpenACS 4.6 now defaults to being loadable in SE.  Just grep for
 	  'sync' to find the code.  
 	

 	  Also be sure to read the documentation in the Site Wide Search
@@ -44,165 +44,11 @@
 	  are steps you must take manually in order to get this feature
 	  working.
 	
Testing Notes

-	  Here are some notes from our testing group.  While not quite up to
-	  date it should give you some ideas of where things stand.
-	
- Summarised Testing Status
 
-Skin
-Minimal
-Release w/caution
-Comments:
+	  OpenMSG has organized the
+	  OpenACS 4.6 testing process with test servers provided by
+	  Hub.org. Visit the acceptance test server to
+	  see the current status of various packages. This may not be a
+	  permanent link. If it's not working, do a search of the OpenACS forums.
 
-Package: Page
-Test Coverage: Minimal
-Release w/caution
-Comments:
-
-Package: Bboard
-Test Coverage: Reasonable
-Suggested Status: Alpha
-Comments:
-
-Package: Static Pages
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments:
-
-Package: Ticket Tracker
-Test Coverage: Reasonable
-Suggested Status: Alpha
-Comments: Don tested personally
-
-Package: Ticket Tracker Lite
-Test Coverage: Unknown
-Suggested Status: 
-Comments:
-
-Package: Acs-lang
-Test Coverage: Reasonable
-Suggested Status: Alpha
-Comments: Oracle only
-
-Package: Simple-survey
-Test Coverage: Reasonable
-Suggested Status: Alpha
-Comments:
-
-Package: Portal
-Test Coverage: Extensive
-Suggested Status: Alpha
-Comments:
-
-Package: Notes
-Test Coverage: Extensive
-Suggested Status: Alpha
-Comments:
-
-Package: Bookmarks
-Test Coverage: Extensive
-Suggested Status: Alpha
-Comments:
-
-Package: Clickthrough
-Test Coverage: Extensive
-Suggested Status: Alpha
-Comments:
-
-Package: Acs-mail
-Test Coverage: Reasonable
-Suggested Status: Release w/caution
-Comments:
-
-Package: Acs-messaging
-Test Coverage: Reasonable
-Suggested Status: Release w/caution
-Comments:
-
-Package: File manager
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments:
-
-Package: File Storage
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments:
-
-Package: Site-wide-search
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments:
-
-Package: General Comments
-Test Coverage: Extensive
-Suggested Status: Alpha
-Comments:
-
-Package: Acs-events
-Test Coverage: None
-Suggested Status: 
-Comments: Automated Testing
-
-Package: Acs-datetime
-Test Coverage: None
-Suggested Status: 
-Comments: Automated Testing
-
-Package: Acs-tcl
-Test Coverage: Reasonable
-Suggested Status: Release w/caution
-Comments: Automated Testing
-
-Package: Acs-templating
-Test Coverage: Reasonable
-Suggested Status: Release w/caution
-Comments: Automated Testing
-
-Package: Acs-util
-Test Coverage: Reasonable
-Suggested Status: Release w/caution
-Comments: Automated Testing
-
-Package: Acs-Content-repository
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments: Automated Testing
-
-Package: Acs-content
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments: Automated Testing
-
-Package: Acs-kernel
-Test Coverage: Reasonable
-Suggested Status: Alpha
-Comments: Automated Testing
-
-Package: Acs-subsite
-Test Coverage: Reasonable
-Suggested Status: Alpha
-Comments: 
-
-Package: Acs-bootstrap-installer
-Test Coverage: Extensive
-Suggested Status: Alpha
-Comments: Developers have used this extensively
-
-Package: Acs-api-browser
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments: Automated Testing
-
-Package: Acs-workflow
-Test Coverage: Minimal
-Suggested Status: Release w/caution
-Comments: 
-
-Package: calendar
-Test Coverage: Minimal
-Suggested Status: Alpha
-Comments: Don tested personally
-	
($Id$)
Prev  Home  Next
Overview  Up  Part Part II. For OpenACS Admins
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+    
($Id$)
Prev  Home  Next
Overview  Up  Part II. Administrator's Guide
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/request-processor.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/request-processor.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,11 +1,11 @@
 
-The Request ProcessorPrev  Chapter 4. OpenACS Developer's Guide  Next
The Request Processor

+The Request Processor
Prev  Chapter 6. OpenACS Developer's Guide  Next
The Request Processor

 By Pete Su
 

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

-This document is a brief introduction to the OpenACS 4.5 Request Processor;
+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
Overview

+This document is a brief introduction to the OpenACS 4.6 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.
 
The Old Way

@@ -28,30 +28,30 @@
 
 To achieve this functionality above in OpenACS 3.x, developers used an ad
 hoc combination of AOLserver filters, the ns_perm call,
-special purpose code in pages, and other procedures.  In OpenACS 4.5, the
+special purpose code in pages, and other procedures.  In OpenACS 4.6, the
 Request Processor, along with the OpenACS Package Manager, centralizes and
 unifies this functionality, making it more transparent and readily
 available to developers.
 
The New Way

-The 4.5 Request Processor is a global filter and set of Tcl procs that
+The 4.6 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.
 
-

[D]

+

[D]

 
 
Stage 1: Search Site Map

 The first thing the RP does is to map the given URL to the appropriate
 physical directory in the filesystem, from which to serve content.  We
 do this by searching the site map data model (touched on in the Packages, and further
-discussed in the section called “Writing OpenACS 4.5 Application Pages”). This data model maps URLs to objects representing
+discussed in the section called “Writing OpenACS 4.6 Application Pages”). This data model maps URLs to objects representing
 content, and these objects are typically package instances. 
 

 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,
-which is described in detail in OpenACS 4 Request Processor Design. The page
+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.
 
Stage 2: Authentication

@@ -62,7 +62,7 @@
 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 4.5, access control
+privileges to the requested part of the site. In OpenACS 4.6, access control
 is dictated by the permissions system. In
 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
@@ -148,6 +148,9 @@
 

 If the URL refers to a package instance, this is the unique key name
 of the package.
-
($Id$)
Prev  Home  Next
OpenACS 4.5 Data Models and the Object System  Up  The OpenACS Database Access API
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
[ad_conn path_info]
+
+

+In a .vuh file, path_info is the trailing part of the URL not matched
+by the .vuh file.
+
($Id$)
Prev  Home  Next
OpenACS Data Models and the Object System  Up  The OpenACS Database Access API
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/requirements-template.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/requirements-template.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,8 +1,8 @@
 
-System/Application Requirements TemplatePrev  Chapter 6. Engineering Standards  Next
System/Application Requirements Template
By You


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

+System/Application Requirements Template
Prev  Chapter 8. Engineering Standards  Next
System/Application Requirements Template
By You


+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
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,
@@ -61,7 +61,7 @@
 	  

       For guidelines writing requirements, take a 
       look
-	at the quality standards, along with a good example, such as OpenACS 4.5 Package Manager Requirements.
+	at the quality standards, along with a good example, such as OpenACS 4.6 Package Manager Requirements.
     

       Besides writing requirements in natural language, consider using the
       following techniques as needed:
@@ -81,6 +81,4 @@
 	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  Release Version Numbering
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+    
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  Release Version Numbering
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/rp-design.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/rp-design.html	28 Feb 2003 05:36:05 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Request Processor DesignPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Request Processor Design

+OpenACS 4 Request Processor Design
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Request Processor Design

 by Rafael H. Schloming

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -14,42 +14,42 @@
 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
OpenACS 4.6 Package Manager Design
Terminology

-pageroot -- Any directory that contains scripts and/or
+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
-(/web/servicename/www) -- Files appearing under
+OpenACS installation is required to serve files from multiple pageroots.
global pageroot
+(/web/servicename/www) -- Files appearing under
 this pageroot will be served directly off the base url
-http://www.servicename.com/
package root
-(/web/servicename/packages) -- Each subdirectory of
+http://www.servicename.com/
package root
+(/web/servicename/packages) -- Each subdirectory of
 the package root is a package. A typical OpenACS installation will have several
-packages.
package pageroot
-(/web/servicename/packages/package_key/www)
--- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is
+packages.
package pageroot
+(/web/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
@@ -60,16 +60,16 @@
 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
@@ -89,14 +89,14 @@
 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
+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 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
+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 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
+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
OpenACS 4 Request Processor Requirements  Up  Database Access API
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
+authorization has been performed.
�
Documentation
[ad_conn api_page_documentation_mode_p] �
Prev  Home  Next
OpenACS 4 Request Processor Requirements  Up  Database Access API
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/rp-requirements.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.html	28 Feb 2003 05:36:05 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Request Processor RequirementsPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Request Processor Requirements

+OpenACS 4 Request Processor Requirements
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Request Processor Requirements

 by Rafael H. Schloming

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -19,9 +19,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
OpenACS 4 Security Notes  Up  OpenACS 4 Request Processor Design
rmello at fslc.usu.edu
vinod@kurup.com
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
OpenACS 4 Security Notes  Up  OpenACS 4 Request Processor Design
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/security-design.html	30 Nov 2002 17:16:24 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/security-design.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,5 +1,5 @@
 
-OpenACS 4 Security DesignPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Security Design

+OpenACS 4 Security Design
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Security Design

 
 by Richard Li, Archit Shah

           OpenACS docs are written by the named authors, but may be edited
@@ -43,10 +43,10 @@
 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
-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
+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
+
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
 processor to authenticate the user. It first checks the
 ad_session_id cookie. If there is no valid session in progress,
@@ -86,7 +86,7 @@
 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
+
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
@@ -206,13 +206,13 @@
 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
@@ -234,41 +234,41 @@
 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
+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
+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
+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
+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
@@ -339,15 +339,15 @@
 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
 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
OpenACS 4 Security Requirements  Up  OpenACS 4 Security Notes
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/security-notes.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/security-notes.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,9 +1,9 @@
 
-OpenACS 4 Security NotesPrev  Chapter 7. Kernel Documentation  Next
OpenACS 4 Security Notes

+OpenACS 4 Security Notes
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Security Notes

 by Richard Li

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

+          OpenACS docs are written by the named authors, but 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. 
@@ -56,6 +56,4 @@
 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
-it is called by the request processor. 
($Id$)
Prev  Home  Next
OpenACS 4 Security Design  Up  OpenACS 4 Request Processor Requirements
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+it is called by the request processor. 
($Id$)
Prev  Home  Next
OpenACS 4 Security Design  Up  OpenACS 4 Request Processor Requirements
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/security-requirements.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html	28 Feb 2003 05:36:05 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Security RequirementsPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Security Requirements

+OpenACS 4 Security Requirements
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Security Requirements

 by Richard Li

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -15,34 +15,34 @@
 vendors require that the user identity be securely validated. 
 
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 4.6 Package Manager Design  Up  OpenACS 4 Security Design
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/submissions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/submissions.html,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/submissions.html	28 Feb 2003 05:36:05 -0000	1.1
@@ -0,0 +1,8 @@
+
+ContributionsPrev  Chapter 6. OpenACS Developer's Guide  Next
Contributions

+    by Joel Aufrecht

+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
Overview
How to contribute work back to the community.  Bugs,
+    patches, new packages.  Forthcoming.
+    
Prev  Home  Next
Writing OpenACS 4.6 Application Pages  Up  Internationalization
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/subsites-design.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/subsites-design.html	28 Feb 2003 05:36:05 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Subsites Design DocumentPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Subsites Design Document

+OpenACS 4 Subsites Design Document
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Subsites Design Document

 by Rafael H. Schloming

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -41,7 +41,7 @@
 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
+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)
@@ -101,7 +101,7 @@
 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
@@ -182,7 +182,7 @@
 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.
 
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 -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html	28 Feb 2003 05:36:05 -0000	1.8
@@ -1,5 +1,5 @@
 
-OpenACS 4 Subsites RequirementsPrev  Chapter�7.�Kernel Documentation  Next
OpenACS 4 Subsites Requirements

+OpenACS 4 Subsites Requirements
Prev  Chapter 9. Kernel Documentation  Next
OpenACS 4 Subsites Requirements

 by Rafael H. Schloming and Dennis Gregorovic

           OpenACS docs are written by the named authors, but may be edited
           by OpenACS documentation staff.
@@ -42,17 +42,17 @@
 office. At this point, the Boston and Austin office admins can customize the
 configurations for each of their bboards, 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
+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
OpenACS 4 Groups Design  Up  OpenACS 4 Subsites Design Document
rmello at fslc.usu.edu
vinod@kurup.com
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
OpenACS 4 Groups Design  Up  OpenACS 4 Subsites Design Document
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/subsites.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/subsites.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,22 +1,22 @@
 
-Writing OpenACS 4.5 Application PagesPrev  Chapter 4. OpenACS Developer's Guide  Next
Writing OpenACS 4.5 Application Pages

+Writing OpenACS 4.6 Application Pages
Prev  Chapter 6. OpenACS Developer's Guide  Next
Writing OpenACS 4.6 Application Pages

 By Rafael H. Schloming 
 and Pete Su
 


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

+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
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 4.5. First, we'll talk about the code needed to make
+development in OpenACS 4.6. First, we'll talk about the code needed to make
 your pages aware of which application instance they are running
 in. Second, we'll talk about using the form builder to develop
-form-based user interfaces in OpenACS 4.5. While these seem like unrelated
+form-based user interfaces in OpenACS 4.6. 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

-As you will recall from the packages tutorial, the Request
-Processor (RP) and Package Manager (APM) in OpenACS 4.5 allow site
+As you will recall from the packages tutorial, the Request
+Processor (RP) and Package Manager (APM) in OpenACS 4.6 allow site
 administrators to define an arbitrary mapping from URLs in the site to
 objects representing content. These objects may represent single
 files, or entire applications. The APM uses the site map to map
@@ -70,7 +70,7 @@
 

 In the Notes example, we are particularly interested in the
 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
+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
@@ -257,15 +257,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 4.5
+This is a good example of the leverage available in the OpenACS 4.6
 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 4.5, application pages and scripts can be aware of the package
+In OpenACS 4.6, 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.
@@ -277,6 +277,4 @@
 

 We also saw how to use the templating system's forms API in a simple
 way, to create forms based pages with minimal duplication of code.
-
($Id$)
Prev  Home  Next
Groups, Context, Permissions  Up  Chapter 5. Other Developer Resources
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
($Id$)
Prev  Home  Next
Groups, Context, Permissions  Up  Contributions
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/tcl-doc.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/tcl-doc.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,10 +1,10 @@
 
-Documenting Tcl Files: Page Contracts and LibrariesPrev  Chapter 7. Kernel Documentation  Next
Documenting Tcl Files: Page Contracts and Libraries

+Documenting Tcl Files: Page Contracts and Libraries
Prev  Chapter 9. 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, but 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
+          OpenACS docs are written by the named authors, but 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
 place to document Tcl files (both Tcl pages and Tcl library files) was in
 a comment at the top of the file:
 #
@@ -187,6 +187,4 @@
 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
Database Access API  Up  Bootstrapping OpenACS
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+substitute an appropriate string when you check the file in.
($Id$)
Prev  Home  Next
Database Access API  Up  Bootstrapping OpenACS
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/templates.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/templates.html	28 Feb 2003 05:36:05 -0000	1.9
@@ -1,9 +1,9 @@
 
-Using Templates in OpenACS 4.5Prev  Chapter 4. OpenACS Developer's Guide  Next
Using Templates in OpenACS 4.5
By Pete Su


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

-The OpenACS 4.5 Template System (ATS) is designed to allow developers to
+Using Templates in OpenACS 4.6
Prev  Chapter 6. OpenACS Developer's Guide  Next
Using Templates in OpenACS 4.6
By Pete Su


+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
Overview

+The OpenACS 4.6 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
 manipulating the database and other application state data in one
@@ -16,7 +16,7 @@
 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
+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
 the template, which is written in a combination of HTML, special
@@ -160,14 +160,12 @@
 
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 4.5, the
+queries and application logic, and another for display. In OpenACS 4.6, the
 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
 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.
-
($Id$)
Prev  Home  Next
The OpenACS Database Access API  Up  Groups, Context, Permissions
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+
($Id$)
Prev  Home  Next
The OpenACS Database Access API  Up  Groups, Context, Permissions
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/tutorial.html	28 Feb 2003 05:36:05 -0000	1.1
@@ -0,0 +1,34 @@
+
+OpenACS 4.6 Package TutorialPrev  Chapter 6. OpenACS Developer's Guide  Next
OpenACS 4.6 Package Tutorial

+    by Joel Aufrecht

+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
Overview
How to create a package.  Includes

+        Using the APM
+      

+        Package create scripts, including using acs_objects and
+        standard __new, __delete, and __name stored procedures.
+      

+        Integrating with the content management system
+      

+        Integrating with OpenFTS/Oracle full text search
+      

+        Integrating with notifications
+      

+        Creating .tcl/adp pairs, including ad_page_contract and the
+        template system
+      

+        Integrating with general_comments
+      

+        Ad_form (draw from http://jongriffin.com/static/openacs/ad_form/using-ad-form)
+      

+        Automated testing
+      

+        caching
+      

+        writing procs, ad_proc, tcl namespaces
+      

+        putting all sql code in .xql, including using partialquery
+      

+        using the html/text entry widget
+      
Prev  Home  Next
Overview  Up  OpenACS 4.6 Packages
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/unix-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/unix-install.html,v
diff -u -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/unix-install.html	30 Nov 2002 17:16:24 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/unix-install.html	28 Feb 2003 05:36:05 -0000	1.8
@@ -1,2 +1,2 @@
 
-Chapter�2.�Installing on Unix/LinuxPrev  Part�Part II.�For OpenACS Admins  Next
Chapter�2.�Installing on Unix/Linux
Table of Contents
Overview
Install an Operating System
Install Oracle 8.1.7
Install PostgreSQL 7.2.3
Install AOLserver 3.3+ad13
Install OpenACS 4.6
Next Steps
Credits
Prev  Home  Next
Part�Part II.�For OpenACS Admins  Up  Overview
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
+Chapter 2. Installing on Unix/LinuxPrev  Part II. Administrator's Guide  Next
Chapter 2. Installing on Unix/Linux
Table of Contents
Overview
Install an Operating System
Install Oracle 8.1.7
Install PostgreSQL 7.2.3
Install AOLserver 3.3+ad13
Install OpenACS 4.6
Next Steps
Credits
Prev  Home  Next
Part II. Administrator's Guide  Up  Overview
rmello at fslc.usu.edu
vinod@kurup.com
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 -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html	28 Feb 2003 05:36:05 -0000	1.1
@@ -0,0 +1,155 @@
+
+Upgrading OpenACS 4.5 to 4.6Prev  Chapter 5. Upgrading  Next
Upgrading OpenACS 4.5 to 4.6
Checklist
The required platform for OpenACS 4.6 is the same as
+    4.5, with the excepion of OpenFTS.  You now need OpenFTS 0.3.2, not 0.2.
+    OpenACS 4.6 does not support PostGreSQL 7.3.
A computer with OpenACS 4.5.
OpenACS 4.6 tarball
Required for Full Text Search on PostGreSQL: OpenFTS 0.3.2
Overview
OpenACS consists of files and a database schema.  The files
+    in the OpenACS 4.6 tarball include database upgrade scripts.  To start the
+    upgrade, replace your existing files with the new files and
+    then restart the server.  Then, browse to the APM, which will
+    detect the new packages and offer to run the appropriate database upgrade
+    scripts.  After restarting the server again, the upgrade is
+    complete.
Figure 5.1. Assumptions in this section
name of OpenACS user nsadmin
OpenACS server name openacs-dev
Root of OpenACS file tree /web/openacs-dev
Database backup directory /backup/openacs/
Upgrading on Linux/Unix
Make a Backup.�Back up the database and file system.
PostGreSQL.�Create a backup file and verify that it was created and has a reasonable size (several megabytes).
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ pg_dump -f /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp openacs-dev
+[nsadmin@localhost aolserver]$ ls -al /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp 
+-rw-rw-r--    1 nsadmin  nsadmin   4005995 Feb 21 18:28 /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
+[nsadmin@localhost aolserver]$ exit
+[root@localhost root]#
+su - nsadmin
+pg_dump -f /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp openacs-dev
+ls -al /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
+exit
Oracle - INCOMPLETE.�
File tree with CVS.�If you are already using CVS, you probably don't
+              need to do anything to back up your data.  Just make
+              sure that your current work is checked into the system.
+              You can then roll back based on date - just note the
+              current system time, down to the minute.  For maximum
+              safety, you can apply a tag to your current
+              files.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ cd /web/openacs-dev
+[nsadmin@localhost openacs-dev]$ cvs commit -m "last-minute commits before upgrade to 4.6"
+cvs commit: Examining .
+cvs commit: Examining bin
+(many lines omitted)
+[nsadmin@localhost openacs-dev]$ cvs tag before_upgrade_to_4_6
+cvs server: Tagging bin
+T bin/acs-4-0-publish.sh
+T bin/ad-context-server.pl
+(many lines omitted)
+[nsadmin@localhost openacs-dev]$ exit
+[root@localhost root]# 
+su - nsadmin
+cd /web/openacs-dev
+cvs commit -m "last-minute commits before upgrade to 4.6"
+cvs tag before_upgrade_to_4_6
+exit
File tree without CVS.�If you don't use cvs, you may want to back up the working directory.  The simplest way is just to copy it.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ cp -r /web/openacs-dev /web/openacs-dev-before-upgrade-to-4.6
+[nsadmin@localhost aolserver]$ exit
+[root@localhost root]# 
+su - nsadmin
+cp -r /web/openacs-dev /web/openacs-dev-before-upgrade-to-4.6
+exit
OPTIONAL: Upgrade OpenFTS.�OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine.  If you have OpenFTS 0.2, you'll need to upgrade to to OpenFTS 0.3.2.  This is backwards-compatible -
+        completing this step will not break a working OpenFTS Engine from 4.5.
+
Uninstall the old OpenFTS Engine
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 /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/
+./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/
+cd aolserver/
+make
+

+Back up the old fts driver as a precaution and install the newly
+compiled one
mv /usr/local/aolserver/bin/nsfts.so /usr/local/aolserver/bin/nsfts-0.2.so 
+cp nsfts.so /usr/local/aolserver/bin
+
Build and install the postgres code
cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/
+cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts
+make
+su - postgres
+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@localhost root]# su - nsadmin
+[nsadmin@localhost dev]$ psql openacs-dev -f /usr/local/pgsql/share/contrib/openfts.sql
+CREATE
+CREATE
+[nsadmin@localhost dev]$ psql openacs-dev -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
+BEGIN
+CREATE
+(~30 more lines)
+[nsadmin@localhost dev]$ exit
+[root@localhost root]# 
+su - nsadmin
+psql openacs-dev -f /usr/local/pgsql/share/contrib/openfts.sql
+psql openacs-dev -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
+exit
Stop the server.�
[root@localhost root]# svc -d /service/openacs-dev
Upgrade the file tree.�If you are using CVS, you will unpack the OpenACS 4.6 tarball into a working directory and then import that directory into cvs.  If you have changed files in the core packages, cvs will attempt to merge your changes.  You may have to manually merge some conflicts.  When that's finished, you can update your normal development checkout directory and the new files will appear.  If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased.
Upgrading files without CVS.�Unpack the tarball into a new directory and copy its contents on top of your working directory.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ cd /web
+[nsadmin@localhost web]$ tar xzf /tmp/openacs-4-6.tgz
+[nsadmin@localhost web]$ cp -r openacs-4-6/* openacs-4
+[nsadmin@localhost openacs-upgrade]$ exit
+[root@localhost root]#
+su - nsadmin
+cd /web
+tar xzf /tmp/openacs-4-6.tgz
+cp -r openacs-4-6/* openacs-4
+exit
Upgrading files with CVS.�
Unpack the new files into a working directory.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ cd /tmp
+[nsadmin@localhost tmp]$ tar xzv openacs-4-6.tgz
+[nsadmin@localhost tmp]$ cd openacs-4.6
+
Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
[nsadmin@localhost openacs-4.6]$  cvs import -m "upgrade to OpenACS 4.6" openacs 
+OpenACS openacs-4-6
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.
[nsadmin@localhost openacs-4.6]$  cd /web
+[nsadmin@localhost tmp]$ mkdir openacs-upgrade
+[nsadmin@localhost tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs < cvs.txt 2<&1
+(CVS feedback here)
+su - nsadmin
+cd /tmp
+tar xzv openacs-4-6.tgz
+cd openacs-4.6
+cvs import -m "upgrade to OpenACS 4.6" openacs OpenACS openacs-4-6
+cd /tmp
+mkdir openacs-upgrade
+cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs < cvs.txt 2<&1
+
The file /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 with the 4.5-4.6 upgrade, you'll have to manually reconcile them.  Use the emacs command 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.  
[nsadmin@localhost tmp]$ cd openacs-upgrade
+[nsadmin@localhost openacs-upgrade]$ cvs commit -m "Upgraded to 4.6"
+cd openacs-upgrade
+cvs commit -m "Upgraded to 4.6"
Update your working tree with the new
+                files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
+[nsadmin@localhost openacs-upgrade]$ cd /web/openacs-dev
+[nsadmin@localhost openacs-dev]$ cvs up -Pd
+(CVS feedback)
+[nsadmin@localhost openacs-dev]$ exit
+[root@localhost root]#
+cd /web/openacs-dev
+cvs up -Pd
+exit
Start the server.�
[root@localhost root]# svc -u /service/openacs-dev
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 packages you want.
On the next screen, click Install Packages
When prompted, restart the server:
[root@localhost root]# restart-aolserver openacs-dev
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 4.6.1.
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@localhost root]# restart-aolserver openacs-dev
Browse to http://yourserver/openfts
Click Administration.
Click Initialize OpenFTS Engine
Rollback.�If anything goes wrong, roll back the database and try
+        again.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ svc -d /service/openacs-dev
+[nsadmin@localhost aolserver]$ dropdb openacs-dev
+DROP DATABASE
+[nsadmin@localhost aolserver]$ createdb openacs-dev
+CREATE DATABASE
+[nsadmin@localhost aolserver]$ psql -f /web/openacs-dev/packages/acs-kernel/sql/postgresql/postgresql.sql openacs-dev
PostGreSQL's dump command does not guarantee to back up all of the
+procedures and things in the right order for them to be reassembled.
+In practice, OpenACS users have found that rebuilding some of the
+common procedures before running the restore usually addresses this.  You will see a number of "already exists" errors when you run the database restore; these can be ignored.  This <a>forum thread</a> has more information.
[nsadmin@localhost aolserver]$ psql openacs-dev < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
+[nsadmin@localhost aolserver]$ svc -u /service/openacs-dev
+[nsadmin@localhost aolserver]$ exit
At this point, you can try go back to the APM and try
+to upgrade the database again.  Alternately, if you want to roll back
+all the way and stop the upgrade, you need to roll back the file
+system as well.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ mv /web/openacs-dev /web/openacs-failed-upgrade
+[nsadmin@localhost aolserver]$ mv /web/openacs-dev-before-upgrade-to-4.6 /web/openacs-dev
+[nsadmin@localhost aolserver]$ svc -u /web/openacs-dev
+[nsadmin@localhost aolserver]$ exit
+[root@localhost root]#
All commands for this section:
+su - nsadmin
+svc -d /service/openacs-dev
+dropdb openacs-dev
+createdb openacs-dev
+psql -f /web/openacs-dev/packages/acs-kernel/sql/postgresql/postgresql.sql openacs-dev
+psql openacs-dev < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
+
+svc -u /service/openacs-dev
+cd /web/openacs-dev
+cvs up -r current
+exit
($Id: upgrade-4.5-to-4.6.html,v 1.1 2003/02/28 05:36:05 joela Exp $)
Prev  Home  Next
Support for upgrades.  Up  Part III. For OpenACS Developers
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade-detail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/upgrade-detail.html,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/upgrade-detail.html	28 Feb 2003 05:36:05 -0000	1.1
@@ -0,0 +1,11 @@
+
+Support for upgrades.Prev  Chapter 5. Upgrading  Next
Support for upgrades.

+    by Joel Aufrecht

+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
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.
Prev  Home  Next
Chapter 5. Upgrading  Up  Upgrading OpenACS 4.5 to 4.6
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
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 -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/upgrade.html	28 Feb 2003 05:36:05 -0000	1.1
@@ -0,0 +1,2 @@
+
+Chapter 5. UpgradingPrev  Part II. Administrator's Guide  Next
Chapter 5. Upgrading
Table of Contents
Support for upgrades.
Upgrading OpenACS 4.5 to 4.6
How to upgrade an installation of OpenACS to a new version.
Prev  Home  Next
OpenACS Installation Guide for Mac OS X  Up  Support for upgrades.
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/win-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/win-install.html,v
diff -u -N -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/win-install.html	30 Nov 2002 17:16:24 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/win-install.html	28 Feb 2003 05:36:05 -0000	1.10
@@ -1,2 +1,2 @@
 
-Chapter�3.�Installing on WindowsPrev  Part�Part II.�For OpenACS Admins  Next
Chapter�3.�Installing on Windows
Table of Contents
Overview
OpenACS Installation Guide for Windows2000
Prev  Home  Next
Credits  Up  Overview
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
+Chapter 3. Installing on WindowsPrev  Part II. Administrator's Guide  Next
Chapter 3. Installing on Windows
Table of Contents
OpenACS Installation Guide for Windows2000
Prev  Home  Next
Credits  Up  OpenACS Installation Guide for Windows2000
rmello at fslc.usu.edu
vinod@kurup.com
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 -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/win2k-installation.html	10 Aug 2002 20:07:21 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/win2k-installation.html	28 Feb 2003 05:36:08 -0000	1.9
@@ -1,13 +1,13 @@
 
-OpenACS Installation Guide for Windows2000Prev  Chapter 3. Installing on Windows  Next
OpenACS Installation Guide for Windows2000
By Matthew Burke and Curtis Galloway


-		  OpenACS docs are written by the named authors, but may be edited
-		  by OpenACS documentation staff.
-		
NOTE: These instructions were
-	valid for ACS v4, but have not been tested with OpenACS. Currently
-	(8/2002), the best option to get OpenACS 4.5 running on Windows
-	is to use VMware and John
-	Sequeira's Oasis VM
-	distribution
+OpenACS Installation Guide for Windows2000
Prev  Chapter 3. Installing on Windows  Next
OpenACS Installation Guide for Windows2000
By Matthew Burke and Curtis Galloway


+          OpenACS docs are written by the named authors, but may be edited
+          by OpenACS documentation staff.
+        
NOTE: These instructions were
+    valid for ACS v4, but have not been tested with OpenACS. Currently
+    (8/2002), the best option to get OpenACS 4.6 running on Windows
+    is to use VMware and John
+    Sequeira's Oasis VM
+    distribution
   
Source: http://software.arsdigita.com/dist
Bug reports: acs-bugs@arsdigita.com
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

@@ -254,6 +254,4 @@
 
 In the services control panel you should see two services:
     AOLserver-lintcollectors and
     AOLserver-iguanasdirect. 
-    
($Id$)
Prev  Home  Next
Overview  Up  Part Part III. For OpenACS Developers
rmello at fslc.usu.edu

-			vinod@kurup.com
-		  
+    
($Id$)
Prev  Home  Next
Chapter 3. Installing on Windows  Up  Chapter 4. Installing on a Macintosh
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org

Prev		Next

Prev		Next

Prev		Next

Prev		Next

OpenACS 4.6 Package Manager Design

+OpenACS 4.6 Package Manager Design

Prev	Chapter 9. Kernel Documentation	Next

OpenACS 4.6 Package Manager Design

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

Essentials

OpenACS Administrator directory
OpenACS 4.6 Package Manager Requirements
Packages
ER diagram
Tcl API
- +
Essentials
- OpenACS Administrator directory
- OpenACS 4.6 Package Manager Requirements
- Packages
- ER diagram
- Tcl API
  apm-procs.tcl
  apm-install-procs.tcl (Supports installation of packages)
  20-apm-load-procs.tcl (Bootstraps APM for server startup)
  -apm-admin-procs.tcl (Supports APM UI)
- PL/SQL file
  apm-create.sql
Introduction
-In general terms, a package is a unit of software that +apm-admin-procs.tcl (Supports APM UI)

PL/SQL file

apm-create.sql

Introduction

+In general terms, a package is a unit of software that serves a single well-defined purpose. That purpose may be to provide a service directly to one or more classes of end-user, (e.g., discussion forums and file storage for community members, user profiling tools for the site publisher), or it may be to act as a building block for other packages (e.g., an application programming interface (API) for storing and querying access control rules, or an API for scheduling email alerts). Thus, packages fall into one of two categories: -

OpenACS Applications: a "program or group of programs +
- OpenACS Applications: a "program or group of programs designed for end users" (the Webopedia definition); also known as modules, for historical reasons. Examples of applications include Bboard and News. -
- OpenACS Services: the aforementioned building blocks. +
- OpenACS Services: the aforementioned building blocks. Examples of services include the OpenACS Content Repository, the OpenACS Templating -System, and the OpenACS Kernel, which includes +System, and the OpenACS Kernel, which includes APM.
An installation of the OpenACS includes the OpenACS Kernel, some services that extend the kernel's functionality, and some applications intended for end-users. Packages function as individual pieces of subsites. A subsite can contain multiple @@ -89,21 +89,21 @@ packages for other ACS users to download and install.
For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):

[D]
APM itself is part of a package, the OpenACS Kernel, an OpenACS +3.2 (say, bboard and e-commerce):

[D]
APM itself is part of a package, the OpenACS Kernel, an OpenACS service that is the only mandatory component of an OpenACS installation.

Competitive Analysis

The OpenACS is a platform for web-based application software, and any software platform has the potential to develop problems like those described above. Fortunately, there are many precedents for systematic solutions, including:

Debian GNU/Linux and the Debian Packaging manual
FreeBSD has the Ports collection
Red Hat Linux has the Red Hat Package Manager (RPM)

Borrowing from all of the above, OpenACS 3.3 introduces its own package -management system, the OpenACS Package Manager (APM), which consists of:

a standard format for APM packages (also called -"OpenACS packages"), including:
- version numbering, independent of any other package and the OpenACS as a -whole
- specification of the package interface
- specification of dependencies on other packages (if any)
- attribution (who wrote it) and ownership (who maintains it)
web-based tools for package management:
- obtaining packages from a remote distribution point
- installing packages, if and only if:
  1. all prerequisite packages are installed
  2. no conflicts will be created by the installation
- configuring packages (obsoleting the monolithic OpenACS configuration -file)
- upgrading packages, without clobbering local modifications
- uninstalling unwanted packages
a registry of installed packages, database-backed and +management system, the OpenACS Package Manager (APM), which consists of:
- a standard format for APM packages (also called +"OpenACS packages"), including:
  - version numbering, independent of any other package and the OpenACS as a +whole
  - specification of the package interface
  - specification of dependencies on other packages (if any)
  - attribution (who wrote it) and ownership (who maintains it)
- web-based tools for package management:
  - obtaining packages from a remote distribution point
  - installing packages, if and only if:
    all prerequisite packages are installed
    no conflicts will be created by the installation
  - configuring packages (obsoleting the monolithic OpenACS configuration +file)
  - upgrading packages, without clobbering local modifications
  - uninstalling unwanted packages
- a registry of installed packages, database-backed and integrated with filesystem-based version control -
- web-based tools for package development:
  - creating new packages locally
  - releasing new versions of locally-created packages

Design Tradeoffs

web-based tools for package development:

creating new packages locally
releasing new versions of locally-created packages

Design Tradeoffs

The design chosen for APM was meant to satisfy the following constraints:

The process of authoring a package must be as simple as possible.
Strict conventions must be established that provide a set of canonical locations and names for files and patterns, for OpenACS application @@ -124,7 +124,7 @@ subsites across the system, and be available for distribution to other OpenACS installations without doing a monolithic upgrade or reinstall.

API

The APM is composed of systems for accomplishing a set of package-related tasks. Each of these tasks comprise a feature area that has an API, data -model, and a UI:

Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance

Authoring a Package

Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model +model, and a UI:

Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance

Authoring a Package

Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model creation script, but need not to be used. This API is part of the APM PL/SQL package.

 
@@ -165,7 +165,7 @@
     package_key     in apm_package_types.package_key%TYPE
 ) return integer;
 
-

Maintaining Multiple Versions of a Package

While the package authoring API provides a means for registering a +

Maintaining Multiple Versions of a Package

While the package authoring API provides a means for registering a package, some information about a package is version dependent. For example, between versions, the owner of a package, its vendor, its URI, and its dependency information may change. The API for package versions allows this @@ -245,7 +245,7 @@ );

Files associated with a version can be added and removed. The path is -relative to the package-root which is +relative to the package-root which is acs-server-root/packages/package-key.

 -- Add a file to the indicated version. 
 function add_file(
@@ -327,7 +327,7 @@
     version_name_two        in apm_package_versions.version_name%TYPE
 ) return integer;
 
-

Creating Instances of a Package

Once a package is registered in the system, it is possible to create +

Creating Instances of a Package

Once a package is registered in the system, it is possible to create instances of it. Each instance can maintain its own content and parameters.

 
@@ -382,7 +382,7 @@
 show errors
 
 
-

Specifying Configuration Parameters for each Instance

A parameter is a setting that can be changed on a package instance basis. +

Specifying Configuration Parameters for each Instance

A parameter is a setting that can be changed on a package instance basis. Parameters are registered on each package_key, and the values are associated with each instance. Parameters can have default values and can be of type 'string' or 'number.' There is support with this @@ -513,14 +513,14 @@ site-wide administration.

Configuration/Parameters

APM has two parameters for configuring how it interacts with the UNIX filesystem, accessible via the Site Map admin page. These parameters need not be changed under most circumstances, but may -need to be tweaked for Windows compatibility.

GzipExecutableDirectory +need to be tweaked for Windows compatibility.
- GzipExecutableDirectory This directory points to where the gunzip program can be found for uncompressing gzip archives. This is needed for the installation of .apm files which are simply gziped tarballs. Default is /usr/local/bin -
- InfoFilePermissionsMode +
- InfoFilePermissionsMode This sets the default UNIX permissions used when creating files using the APM. Default is 775.

Future Improvements/Areas of Likely Change

APM has been in production since OpenACS 3.3, and as of version 4.0 offers a stable set of features. One major feature planned is integration with the OpenACS @@ -542,4 +542,4 @@ all of this functionality in one interface and it can be confusing from a usability perspective.

Authors

System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd Nightingale.
System owner: Bryan Quinn
Documentation author: Bryan Quinn, building from earlier versions by Jon -Salz, Michael Yoon, and Lars Pind.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/25/2000	Bryan Quinn
0.8	Ready for QA	9/29/2000	Bryan Quinn
0.9	Edited for ACS 4 Beta release	10/02/2000	Kai Wu
1.0	Edited for OpenACS 4.6 Beta release	03/02/2002	Roberto Mello

Prev	Home	Next
OpenACS 4.6 Package Manager Requirements	Up	OpenACS 4 Security Requirements

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org +Salz, Michael Yoon, and Lars Pind.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/25/2000	Bryan Quinn
0.8	Ready for QA	9/29/2000	Bryan Quinn
0.9	Edited for ACS 4 Beta release	10/02/2000	Kai Wu
1.0	Edited for OpenACS 4.6 Beta release	03/02/2002	Roberto Mello

Prev	Home	Next
OpenACS 4.6 Package Manager Requirements	Up	OpenACS 4 Security Requirements

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 30 Nov 2002 17:16:23 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 28 Feb 2003 05:36:03 -0000 1.8 @@ -1,5 +1,5 @@ -OpenACS 4.6 Package Manager Requirements

Prev	Chapter�7.�Kernel Documentation	Next

OpenACS 4.6 Package Manager Requirements

+OpenACS 4.6 Package Manager Requirements

Prev	Chapter 9. Kernel Documentation	Next

OpenACS 4.6 Package Manager Requirements

by Bryan Quinn and Todd Nightingale
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff. @@ -9,7 +9,7 @@ and /admin pages at sub-site level; deprecation of site-wide parameter file).

To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number -4.

We gratefully acknowledge the authors of APM 3 for their original design +4.

We gratefully acknowledge the authors of APM 3 for their original design documentation which suggested these features, as well as the influence of the design and open-source implementation of the Red Hat Package manager, the Debian packaging system, and PERL's CPAN in the development of the ideas @@ -29,36 +29,36 @@ packaging, installing, and configuring OpenACS software in a consistent, user-friendly, and subsite-aware manner.

System Overview

The OpenACS Package Manager (APM) consists of: -

A standard format for APM packages including:
- Version numbering, independent of any other package and the OpenACS as a -whole
- Specification of the package interface
- Specification of dependencies on other packages (if any)
- Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
- Obtaining packages from a remote distribution point
- Installing packages, if and only if:
  1. All prerequisite packages are installed
  2. No conflicts will be created by the installation
- Configuring packages (obsoleting the monolithic OpenACS configuration -file)
- Upgrading packages, without clobbering local modifications
- Uninstalling unwanted packages

A registry of installed packages, database-backed and +

A standard format for APM packages including:
- Version numbering, independent of any other package and the OpenACS as a +whole
- Specification of the package interface
- Specification of dependencies on other packages (if any)
- Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
- Obtaining packages from a remote distribution point
- Installing packages, if and only if:
  1. All prerequisite packages are installed
  2. No conflicts will be created by the installation
- Configuring packages (obsoleting the monolithic OpenACS configuration +file)
- Upgrading packages, without clobbering local modifications
- Uninstalling unwanted packages
A registry of installed packages, database-backed and integrated with file system-based version control -
Web-based tools for package development:
- Creating new packages locally
- Releasing new versions of locally-created packages
- Uploading packages to a global package repository on the web
- Use of these tools should be safe, i.e. installing or removing a package -should never break an OpenACS installation
Web-based tools for package configuration:
- The ability to change package parameter values on-line through a simple +
- Web-based tools for package development:
  - Creating new packages locally
  - Releasing new versions of locally-created packages
  - Uploading packages to a global package repository on the web
  - Use of these tools should be safe, i.e. installing or removing a package +should never break an OpenACS installation
- Web-based tools for package configuration:
  - The ability to change package parameter values on-line through a simple web interface.
  - A new ad_parameter which does not require a monolithic site-wide parameter's file or server restarts for changes to take effect.
  - The ability to manage multiple package instances at the sub-site level.

Use-cases and User-scenarios

The APM is intended for the following classes of users, which may or may not -overlap:

Developers (referred to as 'the developer') use +overlap:
1. Developers (referred to as 'the developer') use the APM to create a software package for distribution and use the procedural -API for direct control of the APM system.
2. Site-wide administrators (referred to as 'the +API for direct control of the APM system.
3. Site-wide administrators (referred to as 'the administrator') use the APM to install packages for their OpenACS instance, -and optionally make them available to sub-sites.
4. Sub-site administrators (referred to as 'the +and optionally make them available to sub-sites.
5. Sub-site administrators (referred to as 'the sub-admin') use an administration interface to configure and enable -packages for their sub-site.
Initial Package Development
David Developer writes a piece of software used to do +packages for their sub-site.

Initial Package Development

David Developer writes a piece of software used to do knowledge management (km) for the OpenACS. He distributes his data model, procedure code, UI pages, and his documentation according to the APM specification. He splits the documentation and the code into sub-packages, and creates a KM installation-chain to install both with the APM developer -UI. Noting that his software was built with Patricia -Programmer's Super Widget toolkit, he specifies that as a +UI. Noting that his software was built with Patricia +Programmer's Super Widget toolkit, he specifies that as a dependency. Moreover, since this package is capable of being used at the sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the OpenACS package repository.

Initial Package Installation

Annie Admin learns of David's KM system by browsing +available for download at the OpenACS package repository.

Initial Package Installation

Annie Admin learns of David's KM system by browsing the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The @@ -72,16 +72,16 @@ installation was successful, the package is available for use.

Since the package is available for use, its initialization routines are set to run automatically on server startup. Annie is warned that since there are initialization routines, she must restart the server for the package to -be ready for use. Annie restarts the server.

Initial Subsite Use of Package

Annie Admin decides to make the KM module available only to a particular +be ready for use. Annie restarts the server.

Initial Subsite Use of Package

Annie Admin decides to make the KM module available only to a particular sub-site type on her OpenACS system, and not others. She specifies this option -using the Sub-site type UI (not part of APM).

Annie Admin notifies Sally SubAdmin by e-mail that a new +using the Sub-site type UI (not part of APM).

Annie Admin notifies Sally SubAdmin by e-mail that a new package is now available for use. Sally goes to her sub-site /admin page and sees that a new entry, KM, is available. Sally clicks on it and finds links to the installed KM documentation and to the web based configuration utility. Then, Sally configures the package using an automatically generated web interface and enables KM for use on her sub-site. After some initial use of the package, Sally decides to change some parameters using the SubAdmin UI. -These changes take effect immediately, without any server restarts.

Upgrade Process

Sally SubAdmin finds a bug in the KM system and sends a report to David +These changes take effect immediately, without any server restarts.

Upgrade Process

Sally SubAdmin finds a bug in the KM system and sends a report to David Developer. David reads the bug report and verifies that the bugs are present in the current version. Because the bugs are present in the shared procedure file, David assigns a watch to the file. David makes the necessary @@ -92,195 +92,195 @@ repository.

Sally SubAdmin asks Annie Administrator to upgrade the package using the APM UI. This upgrade supersedes the old version of KM at the site-wide level. Once Annie upgrades the package, the new version starts working immediately -in Sally's sub-site.

Procedural API

Danielle Developer wants her software to perform +in Sally's sub-site.

Procedural API

Danielle Developer wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software -exhibits different behavior.

Requirements: Data Model

4.500.0 Package Identification -(All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed +exhibits different behavior.

Requirements: Data Model

4.500.0 Package Identification +(All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed to be unique to the local OpenACS site must be maintained by the APM. For -example, "apm."
4.500.5 A package id (primary key) that is guaranteed to +example, "apm."
4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, -"25."
4.500.10 A package URL that is guaranteed to be unique +"25."
4.500.10 A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For example, "http://openacs.org/software." -
4.505.0 Version Identification - (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to -be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique +
4.505.0 Version Identification + (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to +be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package.

Requirements: API

The API for APM v3 is explicitly a private API. However, it would be useful to obtain information from the APM through a procedural API. Implementing the API specified below is quite easy given that there are pages -that already do all of the below in raw SQL.

4.400.0 Packages Status Predicates
4.400.1 Given defining information such as a package URL, +that already do all of the below in raw SQL.
- 4.400.0 Packages Status Predicates
  4.400.1 Given defining information such as a package URL, the APM API can return the status of the package on the local OpenACS -instance.
- 4.405.0 Package Information Procedures
  4.405.1 The APM API can return information for any +instance.
- 4.405.0 Package Information Procedures
  4.405.1 The APM API can return information for any locally installed packages, including the version number, paths and files, -and package key.
- 4.410.0 Sub-site Procedures
  4.410.1 After a package has been installed at the +and package key.
- 4.410.0 Sub-site Procedures
  4.410.1 After a package has been installed at the site-wide level, the system API will provide means to check for package -presence, creation, enabling, disabling, and destruction on a subsite.
- 4.415.0 Parameter Values (replaces ad_parameter)
  4.415.1 The system API shall allow subsite parameters for +presence, creation, enabling, disabling, and destruction on a subsite.
- 4.415.0 Parameter Values (replaces ad_parameter)
  4.415.1 The system API shall allow subsite parameters for an installed package to be set by either site-wide administrators or sub-site admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only -take effect after a server restart (default is immediate).
  4.415.5 Parameters for a given subsite and package can be +take effect after a server restart (default is immediate).
  4.415.5 Parameters for a given subsite and package can be returned by the system API.

Requirements: Security

Provisions will be made to assure that packages are securely -identified.

4.600.1 Each package will have a PGP signature and there +identified.
- 4.600.1 Each package will have a PGP signature and there will be MD5 time stamps for each file within the package. -
- 4.600.5 The APM will provide a facility to validate both +
- 4.600.5 The APM will provide a facility to validate both the PGP signature and MD5 stamps information before a package install.

Requirements: The User Interface

The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the actions taken here can dramatically affect the state of the running OpenACS.

Requirements: The Developer's Interface

The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects -throughout the OpenACS and should not be used on a production site.

10.0 Define a package.
The developer must be able to create a new package by specifying some +throughout the OpenACS and should not be used on a production site.
- 10.0 Define a package.
  The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a -package key, version information, owner information, and a canonical URL.
  10.1 The APM must maintain the state of all locally -generated packages.
  10.50 If the developer fails to provide the required -information, the package cannot be created.
  10.55 All of the package information should be editable -after creation, except for the package key.
  4.10.60 The package creator must specify whether the +package key, version information, owner information, and a canonical URL.
  10.1 The APM must maintain the state of all locally +generated packages.
  10.50 If the developer fails to provide the required +information, the package cannot be created.
  10.55 All of the package information should be editable +after creation, except for the package key.
  4.10.60 The package creator must specify whether the package is capable of being used in sub-sites, or if only a single, global -instance of the package is permitted.
  4.10.65 If the developer fails to provide unique +instance of the package is permitted.
  4.10.65 If the developer fails to provide unique information for unique fields specified in the data model requirements, the -package cannot be created.
- 20.0 Add files to a package
  20.1 The developer must be able to add files to the +package cannot be created.
- 20.0 Add files to a package
  20.1 The developer must be able to add files to the package. This is done by copying the files into the package directory in the host OS's file system. Files can be added at any point after package -creation.
  20.3 Once a package has been versioned and distributed, +creation.
  20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version -number.
  20.5 The APM's UI should facilitate the process of +number.
  20.5 The APM's UI should facilitate the process of adding new files, by scanning the file system for new files automatically, -and allowing the developer to confirm adding them.
  20.10 The developer cannot add files to a given package -via the UI that do not exist in the file system already.
  20.15 Package file structure must follow a specified +and allowing the developer to confirm adding them.
  20.10 The developer cannot add files to a given package +via the UI that do not exist in the file system already.
  20.15 Package file structure must follow a specified convention. Please see the design -document for what we do currently.
- 30.0 Remove files from a package
  The developer must be able to remove files from a package. This can be -done in two ways.
  - 30.1 Access the APM UI, browse the file list, and remove -files.
    30.1.1If a file is removed from the package list, but not -from the file system, an error should be generated at package load time.
  - 30.5 Remove the file from file system.
    30.5.1 The APM UI should take note of the fact that the +document for what we do currently.
  - 30.0 Remove files from a package
    The developer must be able to remove files from a package. This can be +done in two ways.
    30.1 Access the APM UI, browse the file list, and remove +files.
    30.1.1If a file is removed from the package list, but not +from the file system, an error should be generated at package load time.
    30.5 Remove the file from file system.
    30.5.1 The APM UI should take note of the fact that the file is gone and offer the developer an option to confirm the file's deletion. -
  - 40.0 Modify files in a package.
    40.1 The developer should be able to modify files in the -file system. The APM UI should not interfere with this.
    40.5 However, if the developer modifies files containing -procedural definitions, APM UI should allow a means to watch +
- 40.0 Modify files in a package.
  40.1 The developer should be able to modify files in the +file system. The APM UI should not interfere with this.
  40.5 However, if the developer modifies files containing +procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 -for more detail.
  40.10 Also, although a change in files implies that the +for more detail.
  40.10 Also, although a change in files implies that the package distribution file is out of date, it is the developer's -responsibility to update it.
- 4.45.0 Manage Package Dependency Information.
  4.45.1 The developer should be able to specify which -interfaces the package requires.
  4.45.5 The developer should be able to specify which -interfaces the package provides.
  4.45.10 Circular dependencies are not allowed.
- 50.0 Watch a file
  4.50.1 The developer should be able to assign a watch to -any Tcl procedure file, whether in /packages or /tcl.
  50.5 If a watched file is locally modified, then it will +responsibility to update it.
- 4.45.0 Manage Package Dependency Information.
  4.45.1 The developer should be able to specify which +interfaces the package requires.
  4.45.5 The developer should be able to specify which +interfaces the package provides.
  4.45.10 Circular dependencies are not allowed.
- 50.0 Watch a file
  4.50.1 The developer should be able to assign a watch to +any Tcl procedure file, whether in /packages or /tcl.
  50.5 If a watched file is locally modified, then it will be automatically reloaded, thus allowing for any changes made to take affect -immediately.
  4.50.10 The setting of a watch should be persistent +immediately.
  4.50.10 The setting of a watch should be persistent across server restarts. -
- 60.0 Display an XML package specification
  60.1 The developer should be able to view the XML package +
- 60.0 Display an XML package specification
  60.1 The developer should be able to view the XML package specification that encodes all package information. -
- 70.0 Write an XML package specification to the file -system
  70.1 The developer should be able to write an up-to-date -XML specification to disk.
  70.5 The developer should be able to request the current -XML specification for all installed, locally generated packages.
- 130.0 Distribution file generation
  130.1 The developer should be able to generate a .APM -distribution file for the package with just one click.
  130.5 Generating a distribution file implies doing an +
- 70.0 Write an XML package specification to the file +system
  70.1 The developer should be able to write an up-to-date +XML specification to disk.
  70.5 The developer should be able to request the current +XML specification for all installed, locally generated packages.
- 130.0 Distribution file generation
  130.1 The developer should be able to generate a .APM +distribution file for the package with just one click.
  130.5 Generating a distribution file implies doing an "up-to-date" check on all of the files. If any of the files have changed since package installation, then a new version of the package is created. -
- 140.0 Access CVS information
  140.1 The developer should be able to determine the CVS +
- 140.0 Access CVS information
  140.1 The developer should be able to determine the CVS status of a package, or all packages, with a single click. -
- 4.200.0 Compound Package Construction
  4.200.1 The developer can include .APM packages +
- 4.200.0 Compound Package Construction
  4.200.1 The developer can include .APM packages (sub-packages) within a package (the compound package) like any other -file.
  4.200.5 The recommended usage for this feature is to +file.
  4.200.5 The recommended usage for this feature is to allow for separation of optional and required components from the installation as well as better organization of files once installed. For example, all documentation for the community-core can be packages as community-core-doc.apm. It is legal to include sub-packages with dependencies that are not satisfied by the packages in the compound package, but this is discouraged. In such a case, the sub-package should really be a -separate package that is required by the compound package.
  4.200.10 If a sub-package is required for the +separate package that is required by the compound package.
  4.200.10 If a sub-package is required for the installation of the compound package, the compound package should have a registered dependency on the sub-package.

Requirements: The Site-Wide Administrator's Interface

The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete -packages.

80.0 Package Enable/Disable
4.80.1 The administrator should be able mark an installed +packages.
- 80.0 Package Enable/Disable
  4.80.1 The administrator should be able mark an installed package as enabled. This means that the package is activated and its functionality is delivered through the Request Processor. As of OpenACS 4, this -is done through the sub-site system.
  4.80.5 Moreover, the administrator must be able to +is done through the sub-site system.
  4.80.5 Moreover, the administrator must be able to disable a package, thereby removing the functionality provided to a sub-site. As of OpenACS 4, this is done through the sub-site system. -
- 90.0 Package Install
  90.1 The administrator must be able to install new -packages either from locally maintained .APM files or from URLs.
  90.5 In the case of an URL, the APM transparently +
- 90.0 Package Install
  90.1 The administrator must be able to install new +packages either from locally maintained .APM files or from URLs.
  90.5 In the case of an URL, the APM transparently downloads the APM file off the web, proceeds with a file based installation, -and then optionally removes the .APM file just downloaded.
  90.10.1 If .APM files are present in a package, then it -is considered a compound package (use 4.210.0).
  90.15.0 Installation requires these steps:
  1. 90.15.1The package dependencies are scanned. If some +and then optionally removes the .APM file just downloaded.
    90.10.1 If .APM files are present in a package, then it +is considered a compound package (use 4.210.0).
    90.15.0 Installation requires these steps:
    90.15.1The package dependencies are scanned. If some dependencies are not present, the system warns the administrator that -installation cannot proceed until those packages are installed.
    90.15.2 Assuming all dependencies are present, APM -extracts the contents of the APM file into the /packages directory.
    90.15.3 The administrator is offered the option of -importing directly into CVS.
    90.15.4 The administrator is given a list of data model -scripts found in the package and can select which ones to be executed.
    90.15.5 If no errors are recorded during this process, -the package is enabled.
  2. 4.210.0 Compound package Install
    4.210.1 If .APM files are present in a package, then it -is considered a compound package.
    4.210.5.0 Installation of a compound package proceeds -according to the following sequence:
    4.210.5.1 Identify the set of all sub-packages within -the compound package by scanning for all files with .APM.
    4.210.5.2 Identify which sub-packages are required by +installation cannot proceed until those packages are installed.
    90.15.2 Assuming all dependencies are present, APM +extracts the contents of the APM file into the /packages directory.
    90.15.3 The administrator is offered the option of +importing directly into CVS.
    90.15.4 The administrator is given a list of data model +scripts found in the package and can select which ones to be executed.
    90.15.5 If no errors are recorded during this process, +the package is enabled.
  3. 4.210.0 Compound package Install
    4.210.1 If .APM files are present in a package, then it +is considered a compound package.
    4.210.5.0 Installation of a compound package proceeds +according to the following sequence:
    4.210.5.1 Identify the set of all sub-packages within +the compound package by scanning for all files with .APM.
    4.210.5.2 Identify which sub-packages are required by checking the dependencies of the compound package. If there dependencies not satisfied by the current system or the packages included with the compound package, halt installation and inform user to install these packages -first.
    4.210.5.3 Present Administrator with the ability to +first.
    4.210.5.3 Present Administrator with the ability to choose which sub-packages to install. Required sub-packages must be -installed.
    4.210.5.4 Proceed with the installation of each +installed.
    4.210.5.4 Proceed with the installation of each sub-package, starting with required packages. If the sub-package is already installed, then do nothing. Else, If the sub-package is a normal package, -proceed according to 90.15.0, otherwise if it is a compound -package, proceed according to 4.210.5.0.
    4.210.5.5 If all required sub-packages are installed, +proceed according to 90.15.0, otherwise if it is a compound +package, proceed according to 4.210.5.0.
    4.210.5.5 If all required sub-packages are installed, proceed to install non-required sub-packages. If there was a failure during the installation of a required sub-package, then the installation of the -compound package is also a failure.
    4.210.5.6 Any attempt to install a compound package in +compound package is also a failure.
    4.210.5.6 Any attempt to install a compound package in the future involves a choice presented to the admin of installing any -uninstalled sub-packages.
  4. 4.220.0 Recovering from failed package installation
    4.220.1 If any error is generated during package +uninstalled sub-packages.
- 4.220.0 Recovering from failed package installation
  4.220.1 If any error is generated during package installation, the package is not considered installed. To recover from this -failure, the package should be selected for installation again.
- 100.0 Version Upgrade
  100.1 The administrator can upgrade to a new version of a -package. This entails
  1. 100.1.1 Running any necessary and included upgrade -scripts.
  2. 100.1.5 Replacing any old files with new versions.
  3. 100.1.10 Marking the old version of the package as -'superseded' and disabling it.
  4. 100.1.15 Assuming no errors from above, the new package -is enabled.
- 110.0 Package Deinstall
  110.1 The administrator must be able to deinstall a -package that has already been installed. Deinstallation entails:
  1. 110.1.1 Running any data model scripts necessary to drop -the package.
  2. 110.1.5 Moving all of the files into a separate location -in the file system from the installed packages.
  3. 4.110.1.10 If the package is a compound package, then +failure, the package should be selected for installation again.
  4. 100.0 Version Upgrade
    100.1 The administrator can upgrade to a new version of a +package. This entails
    100.1.1 Running any necessary and included upgrade +scripts.
    100.1.5 Replacing any old files with new versions.
    100.1.10 Marking the old version of the package as +'superseded' and disabling it.
    100.1.15 Assuming no errors from above, the new package +is enabled.
  5. 110.0 Package Deinstall
    110.1 The administrator must be able to deinstall a +package that has already been installed. Deinstallation entails:
    110.1.1 Running any data model scripts necessary to drop +the package.
    110.1.5 Moving all of the files into a separate location +in the file system from the installed packages.
    4.110.1.10 If the package is a compound package, then the administrator must confirm removing all sub-packages. Optionally, some -sub-packages can be kept.
    110.5 Deinstalled packages can be re-installed at a later -date.
    4.110.10 If deinstalling a package or any of its +sub-packages can be kept.
  110.5 Deinstalled packages can be re-installed at a later +date.
  4.110.10 If deinstalling a package or any of its sub-packages breaks a dependency, then deinstallation cannot proceed until -the package registering the dependency is removed.
- 120.0 Package Deletion
  120.1 The administrator should be able to completely +the package registering the dependency is removed.
- 120.0 Package Deletion
  120.1 The administrator should be able to completely erase all records of the package. This involves removing all instances of the -package, all related database tables and content.
  120.5 This option can only be used if all package +package, all related database tables and content.
  120.5 This option can only be used if all package instances are deleted or marked as disabled. This is purposefully cumbersome because deleting all instances of a package can have far-sweeping -consequences throughout a site and should almost never be done.
- 150.0 Scan for new or modified packages
  150.1 The administrator should be able to scan the file -system for any changes made in any of the installed package files.
  150.5 The administrator should be able to scan the file +consequences throughout a site and should almost never be done.
- 150.0 Scan for new or modified packages
  150.1 The administrator should be able to scan the file +system for any changes made in any of the installed package files.
  150.5 The administrator should be able to scan the file system for any newly installed packages.

Requirements: The Sub-Site Administrator's Interface

If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface. -

4.300 Creating a package instance.

4.300.1 From the sub-site /admin interface, there should +

4.300 Creating a package instance.
4.300.1 From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an -option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin +option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site -type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is -available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all -parameters with current values must be available.
4.305.5 Changing the values for the parameters is -accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package +type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is +available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all +parameters with current values must be available.
4.305.5 Changing the values for the parameters is +accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package with a single click. Enabling a package means that the OpenACS will serve its URLs properly. -
4.315 Disabling a package instance.
4.315.1 The sub-admin should be able to disable a package +
4.315 Disabling a package instance.
4.315.1 The sub-admin should be able to disable a package with a single click. Disabling a package means that the OpenACS will no longer -serve those URLs.
4.320 Deleting a package instance.
4.320.1 Deleting a package instance involves deleting not +serve those URLs.
4.320 Deleting a package instance.
4.320.1 Deleting a package instance involves deleting not only the package instance, but any and all content associated with it. It is questionable whether this option should even be available due to its drastic consequences. Reviewer comments appreciated. @@ -293,4 +293,4 @@ are set using the acs_attribute_values table. The automatic web interface for setting package parameters should be one and the same with the interface for setting acs object attribute values. Consequently, the implementation of -these features should be quite straightforward.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/10/2000	Bryan Quinn, Todd Nightingale
�	Reviewed	8/11/2000	John Prevost, Mark Thomas, and Pete Su
0.2	Revised and updated	8/12/2000	Bryan Quinn
0.3	Reviewed, revised, and updated - conforms to requirements template.	8/18/2000	Kai Wu
0.4	Minor edits before ACS 4 Beta.	9/30/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Subsites Design Document	Up	OpenACS 4.6 Package Manager Design

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org +these features should be quite straightforward.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/10/2000	Bryan Quinn, Todd Nightingale
�	Reviewed	8/11/2000	John Prevost, Mark Thomas, and Pete Su
0.2	Revised and updated	8/12/2000	Bryan Quinn
0.3	Reviewed, revised, and updated - conforms to requirements template.	8/18/2000	Kai Wu
0.4	Minor edits before ACS 4 Beta.	9/30/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Subsites Design Document	Up	OpenACS 4.6 Package Manager Design

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 10 Aug 2002 20:07:20 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 28 Feb 2003 05:36:04 -0000 1.9 @@ -1,9 +1,9 @@ -Bootstrapping OpenACS

Prev	Chapter 7. Kernel Documentation

Bootstrapping OpenACS

+Bootstrapping OpenACS

Prev	Chapter 9. Kernel Documentation	Next

Bootstrapping OpenACS

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

Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl

This document describes the startup (bootstrapping) process for an AOLserver + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl

This document describes the startup (bootstrapping) process for an AOLserver running OpenACS.

The Big Picture

Before OpenACS 3.3, the OpenACS startup process was extremely simple: after AOLserver @@ -87,6 +87,4 @@ At this point, bootstrap.tcl is done executing. AOLserver proceeds to source the remaining files in the /tcl directory (i.e., unpackaged libraries) and begins listening for connections. -

($Id$)

Prev	Home
Documenting Tcl Files: Page Contracts and Libraries	Up

rmello at fslc.usu.edu

- vinod@kurup.com -

($Id$)

Prev	Home	Next
Documenting Tcl Files: Page Contracts and Libraries	Up	Index

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/credits.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/credits.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/credits.html 10 Aug 2002 20:07:20 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/credits.html 28 Feb 2003 05:36:04 -0000 1.9 @@ -1,9 +1,9 @@ Credits

Prev	Chapter 2. Installing on Unix/Linux	Next

Credits

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

Vinod Kurup put + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Vinod Kurup put together the January 2002 version of this guide from many sources of information.

Install an Operating System @@ -30,11 +30,9 @@ Several people have helped with this document, including Torben Brosten, Don Baccus, Roberto Mello, Talli Somekh, Dave Bauer, Jim Lynch, Jon Griffin, Daryl Biberdorf, Bjorn Thor Jonsson, Jade Rubick, - Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner and Malte - Sussdorff. + Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner, Malte + Sussdorff, Stan Kaufman and Pascal Scheffers.
- All questions and comments regarding - this guide should be posted on the OpenACS bboards. -
($Id$)

Prev	Home	Next
Next Steps	Up	Chapter 3. Installing on Windows

rmello at fslc.usu.edu

- vinod@kurup.com -

+ All questions and comments regarding + this guide should be posted on the OpenACS bboards. +

($Id$)

Prev	Home	Next
Next Steps	Up	Chapter 3. Installing on Windows

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 10 Aug 2002 20:07:20 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 28 Feb 2003 05:36:04 -0000 1.9 @@ -1,11 +1,11 @@ -Database Access API

Prev	Chapter 7. Kernel Documentation	Next

Database Access API

+Database Access API

Prev	Chapter 9. Kernel Documentation	Next

Database Access API

by Jon Salz. Revised and expanded by Roberto Mello (rmello at fslc dot usu dot edu), July 2002.
- OpenACS docs are written by the named authors, but may be edited - by OpenACS documentation staff. -

Tcl procedures: /packages/acs-kernel/10-database-procs.tcl
Tcl initialization: /packages/acs-kernel/database-init.tcl

The Big Picture

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

Tcl procedures: /packages/acs-kernel/10-database-procs.tcl
Tcl initialization: /packages/acs-kernel/database-init.tcl

The Big Picture

One of OpenACS's great strengths is that code written for it is very close to the database. It is very easy to interact with the database from anywhere within OpenACS. Our goal is to develop a coherent API for database access which @@ -731,6 +731,4 @@ The nsv containing the list is initialized by the bootstrap script and should never be referenced directly by user code. Returns the current rdbms type and version. -

($Id$)

Prev	Home	Next
OpenACS 4 Request Processor Design	Up	Documenting Tcl Files: Page Contracts and Libraries

rmello at fslc.usu.edu

- vinod@kurup.com -

($Id$)

Prev	Home	Next
OpenACS 4 Request Processor Design	Up	Documenting Tcl Files: Page Contracts and Libraries

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/db-api.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/db-api.html 10 Aug 2002 20:07:20 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/db-api.html 28 Feb 2003 05:36:04 -0000 1.9 @@ -1,5 +1,5 @@ -The OpenACS Database Access API

Prev	Chapter 4. OpenACS Developer's Guide	Next

The OpenACS Database Access API

+The OpenACS Database Access API

Prev	Chapter 6. OpenACS Developer's Guide	Next

The OpenACS Database Access API

By Pete Su and Jon Salz. Modified by Roberto Mello. @@ -737,6 +737,4 @@

($Id$)

Prev	Home	Next
The Request Processor	Up	Using Templates in OpenACS 4.5

rmello at fslc.usu.edu

- vinod@kurup.com -

Prev	Home	Next
The Request Processor	Up	Using Templates in OpenACS 4.6

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/dev-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/dev-guide.html 30 Nov 2002 17:16:23 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/dev-guide.html 28 Feb 2003 05:36:04 -0000 1.9 @@ -1,2 +1,2 @@ -Chapter�4.�OpenACS Developer's Guide

Prev	Part�Part III.�For OpenACS Developers	Next

Chapter�4.�OpenACS Developer's Guide

Table of Contents

Overview
OpenACS 4.6 Packages
OpenACS 4.6 Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 4.6
Groups, Context, Permissions
Writing OpenACS 4.6 Application Pages

Prev	Home	Next
Part�Part III.�For OpenACS Developers	Up	Overview

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org +Chapter 6. OpenACS Developer's Guide

Prev	Part III. For OpenACS Developers	Next

Chapter 6. OpenACS Developer's Guide

Table of Contents

Overview
OpenACS 4.6 Package Tutorial
OpenACS 4.6 Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 4.6
Groups, Context, Permissions
Writing OpenACS 4.6 Application Pages
Contributions
Internationalization

Prev	Home	Next
Part III. For OpenACS Developers	Up	Overview

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/developers-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/developers-overview.html,v diff -u -N -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/developers-overview.html 30 Nov 2002 17:16:23 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/developers-overview.html 28 Feb 2003 05:36:04 -0000 1.5 @@ -1,2 +1,2 @@ -Overview

Prev	Chapter�4.�OpenACS Developer's Guide	Next

Overview

A tour of what you need to know in order to extend OpenACS.

Prev	Home	Next
Chapter�4.�OpenACS Developer's Guide	Up	OpenACS 4.6 Packages

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org +Overview

Prev	Chapter 6. OpenACS Developer's Guide	Next

Overview

A tour of what you need to know in order to extend OpenACS.

Prev	Home	Next
Chapter 6. OpenACS Developer's Guide	Up	OpenACS 4.6 Package Tutorial

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -N -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 30 Nov 2002 17:16:23 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 28 Feb 2003 05:36:04 -0000 1.10 @@ -1,5 +1,5 @@ -OpenACS Documentation Guide

Prev	Chapter�6.�Engineering Standards	Next

OpenACS Documentation Guide

+OpenACS Documentation Guide

Prev	Chapter 8. Engineering Standards	Next

OpenACS Documentation Guide

By claus@arsdigita.com, with additions by Roberto Mello and the OpenACS Community @@ -10,12 +10,12 @@ OpenACS a superb documentation, so that users, developers and administrators of OpenACS installations can enjoy the system.

- OpenACS is a powerful system, with + OpenACS™ is a powerful system, with incredible possibilities and applications, but with this power comes some complexity and a learning curve that will only be atenuated by good documentation. This is what we are after.

- The documentation for OpenACS is + The documentation for OpenACS™ is written using DocBook XML. The reasons why we are using DocBook are explained in more details in the Why DocBook? section. I will add the reasons why @@ -26,13 +26,13 @@

It does not require extra effort. Writing in XML is almost identical to SGML, with a couple extra rules. More details in the - LDP + LDP Author Guide.

Why DocBook?

In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + This enables us to publish in a variety of formats and relieves each contributor of the burden of presentation, freeing him to focus on content and sharing knowledge. @@ -52,11 +52,11 @@ list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically - the same elements are valid in the XML DTD as long as you remember to: - + the same elements are valid in the XML DTD as long as you remember to: +

Always close your tags with corresponding end-tags and to - not use other tag minimization + not use other tag minimization
Write all elements and attributes in lowercase
@@ -80,7 +80,7 @@ Some editing tool. A popular one is Emacs with the psgml mode. We have a intro to the PSGML Mode in Emacs as part of our documentation. You can - read about other editing tools in the LDP Author Guide. + read about other editing tools in the LDP Author Guide.

Writing New Docs

After you have the tools mentioned above, you need to define a title for your document. Then start thinking about the possible @@ -91,52 +91,52 @@ please e-mail the gatekeeper in charge of documentation.

You can look at some templates for documents (in Docbook XML) in - the sources + the sources for acs-core-docs, especially the Detailed Design Documentation Template and the System/Application Requirements Template.

Document Structure

The documentation for each package will make up a little "book" that is structured like this - examples are emphasized: - +

-    book                        : Docs for one package - templating
+    book                        : Docs for one package - templating
      |
-     +--chapter                 : One section - for developers
+     +--chapter                 : One section - for developers
          |
 ---------+------------------------------------------------------
          |
-         +--sect1               : Single document - requirements
+         +--sect1               : Single document - requirements
              |
-             +--sect2           : Sections - functional requirements
+             +--sect2           : Sections - functional requirements
                  |
-                 +--sect3       : Subsections - Programmer's API
+                 +--sect3       : Subsections - Programmer's API
                      |
-                    ...         : ...
+                    ...         : ...

The actual content is split up into documents that start at a sect1-level. These are then tied together in a top-level document that contains all the information above the line. This will be explained in more detail in a later document, and we will provide a set of templates for documenting an entire package.

For now you can take a look at the - sources of these DocBook documents + sources of these DocBook documents to get an idea of how they are tied together.

Headlines, Sections

- + Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>.

- + You need to feed every <sect1> two attributes. The first attribute, id, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about links in the section called “Links”). The value of id has to be unique throughout the book you're making since the id's in your sect1's will turn into filenames when the book is parsed into HTML.

- + The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.

@@ -151,7 +151,7 @@ </sect1>

- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -160,7 +160,7 @@ When it comes to naming your sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.

Code

- + For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we will use the tag <computeroutput>. @@ -170,12 +170,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.

Links

- + Linking falls into two different categories: inside the book you're making and outside: -

1. Inside linking, cross-referencing other parts of your book

1. Inside linking, cross-referencing other parts of your book

By having unique id's you can cross-reference any part of your book with a simple tag, regardless of where that part is. -

Check out how I link to a subsection of the Developer's Guide:

+	  
Check out how I link to a subsection of the Developer's Guide:
 
 	    Put this in your XML:
 
@@ -212,8 +212,8 @@
 	    Note that since I haven't provided an xreflabel for the subsection, 
 	    packages-looks, the
 	    parser will try its best to explain where the link takes you.
-

2. Linking outside the documentation

- +

2. Linking outside the documentation

+ If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different @@ -222,19 +222,19 @@

<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>

....will create a hyper-link to Oracle in the HTML-version of the documentation. -

NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing +

NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing entities, which is exactly how you'll make an ampersand: &

Graphics

- NOTE: Currently this section currently only takes HTML-output into consideration - + NOTE: Currently this section currently only takes HTML-output into consideration - not a printed version

- Another Note: Also, it's still not a 100 percent sure that this is how we are going to + Another Note: Also, it's still not a 100 percent sure that this is how we are going to do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)

- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -260,9 +260,9 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.

Lists

- + Here's how you make the DocBook equivalent of the three usual HTML-lists: -

1. How to make an <ul>

Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as <para>, and that the tags are called <itemizedlist> @@ -275,7 +275,7 @@ <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -

2. How to make an <ol>

The ordered list is like the preceding, except that you use <orderedlist> instead:

 	    <orderedlist>
@@ -284,7 +284,7 @@
 	    <listitem><para>More stuff goes here</para></listitem>
 
 	    </orderedlist>
-

3. How to make a <dl>

This kind of list is called a variablelist and these are the tags you'll need to make it happen: <variablelist>, @@ -305,7 +305,7 @@ </variablelist>

Tables

- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -342,7 +342,7 @@ <table> for an example.

Emphasis

- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.

@@ -376,7 +376,7 @@

 bash$  xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml

Note

- This example uses Daniel Veillard's xsltproc command available + This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. @@ -387,7 +387,7 @@
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml

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

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#

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#

...	`scope`	`user_id`	`group_id`	...
...	`user`	`123`	�	...
...	`group`	�	`456`	...
...	`public`	�	�	...

...	`scope`	`user_id`	`group_id`	...
...	`user`	`123`	�	...
...	`group`	�	`456`	...
...	`public`	�	�	...

For OpenACS Admins

Administrator's Guide

For OpenACS Developers

For OpenACS Developers

Install AOLserver 3.3+ad13

Download the Distribution

Install AOLserver 3.3+ad13

Download the Distribution

Create the nsadmin user

Set up your user account

Set up nsadmin's environment variables

Install libxml2 & headers

Compile and install AOLserver

Install libxml2 & headers

Compile and install AOLserver

Test AOLserver

Set File Permissions

Test AOLserver

Troubleshooting the AOLserver Install

Troubleshooting the AOLserver Install

OpenACS 4.6 Package Manager Design

OpenACS 4.6 Package Manager Design

Essentials

Essentials

Introduction

Introduction

Competitive Analysis

Design Tradeoffs

Design Tradeoffs

API

Configuration/Parameters

Future Improvements/Areas of Likely Change

Authors

Revision History

Revision History

OpenACS 4.6 Package Manager Requirements

OpenACS 4.6 Package Manager Requirements

System Overview

Use-cases and User-scenarios

Related Links

Requirements: Data Model

Related Links

Requirements: Data Model

Requirements: API

Requirements: Security

Requirements: The User Interface

Requirements: The Developer's Interface

Requirements: The Site-Wide Administrator's Interface

Requirements: The Sub-Site Administrator's Interface

Revision History

Revision History

Bootstrapping OpenACS

Bootstrapping OpenACS

The Big Picture

Credits

Database Access API

Database Access API

The Big Picture

The Big Picture

The OpenACS Database Access API

The OpenACS Database Access API

Chapter�4.�OpenACS Developer's Guide

Chapter 6. OpenACS Developer's Guide

Overview

Overview

OpenACS Documentation Guide

OpenACS Documentation Guide

Why DocBook?

Writing New Docs

Document Structure

Headlines, Sections

Code

Links

Graphics

Lists

Tables

Emphasis

Note

Further Reading

Constraint naming standard