Index: openacs-4/packages/acs-core-docs/www/acs-admin.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.html,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/acs-admin.html 20 Aug 2003 16:20:15 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/acs-admin.html 14 Oct 2003 11:02:57 -0000 1.14
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�II.�Administrator's Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="release-notes.html" title="OpenACS Release Notes"><link rel="next" href="quick.html" title="Chapter�2.�Quick Install"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="quick.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><h1 class="title"><a name="acs-admin"></a>Administrator's Guide</h1></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>2. <a href="quick.html">Quick Install</a></dt><dt>3. <a href="software-versions.html">Prerequisite Software</a></dt><dd><dl><dt><a href="compatibility-matrix.html">Compatibility Matrix</a></dt><dt><a href="individual-programs.html">Individual Programs</a></dt></dl></dd><dt>4. <a href="unix-install.html">Installing on Unix/Linux</a></dt><dd><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="linux-installation.html">Install Linux and supporting software</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostGreSQL</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3oacs1</a></dt><dt><a href="openacs.html">Install OpenACS 5.0.0d</a></dt><dt><a href="credits.html">Credits</a></dt></dl></dd><dt>5. <a href="win-install.html">Installing on Windows</a></dt><dd><dl><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></dd><dt>6. <a href="mac-install.html">Installing on a Macintosh</a></dt><dd><dl><dt><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></dt></dl></dd><dt>7. <a href="configure.html">Configuring a New Service</a></dt><dt>8. <a href="upgrade.html">Upgrading</a></dt><dd><dl><dt><a href="upgrade-detail.html">Support for upgrades.</a></dt></dl></dd><dt>9. <a href="maintenance.html">Maintenance</a></dt><dd><dl><dt><a href="maintenance-web.html">Hosting Web Sites</a></dt><dt><a href="database-management.html">Database Management</a></dt><dt><a href="backup-recovery.html">Backup and Recovery</a></dt></dl></dd><dt>A. <a href="install-redhat.html">Install Red Hat 8.0</a></dt><dt>B. <a href="install-more-software.html">Install additional supporting software</a></dt><dd><dl><dt><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></dt><dt><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt><dt><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt><dt><a href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt><a href="analog-install.html">Install Analog web file analyzer</a></dt><dt><a href="install-full-text-search.html"></a></dt><dt><a href="install-nsopenssl.html">Install nsopenssl</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="quick.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Release Notes </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�2.�Quick Install</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/acs-admin.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�II.�Administrator's Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="release-notes.html" title="OpenACS Release Notes"><link rel="next" href="quick.html" title="Chapter�2.�Quick Install"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="quick.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="acs-admin"></a>Administrator's Guide</h1></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>2. <a href="quick.html">Quick Install</a></dt><dt>3. <a href="software-versions.html">Prerequisite Software</a></dt><dd><dl><dt><a href="compatibility-matrix.html">Compatibility Matrix</a></dt><dt><a href="individual-programs.html">Individual Programs</a></dt></dl></dd><dt>4. <a href="unix-install.html">Installing on Unix/Linux</a></dt><dd><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="linux-installation.html">Install Linux and supporting software</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostGreSQL</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3oacs1</a></dt><dt><a href="openacs.html">Install OpenACS 5.0.0a1</a></dt><dt><a href="credits.html">Credits</a></dt></dl></dd><dt>5. <a href="win-install.html">Installing on Windows</a></dt><dd><dl><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></dd><dt>6. <a href="mac-install.html">Installing on a Macintosh</a></dt><dd><dl><dt><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></dt></dl></dd><dt>7. <a href="configure.html">Configuring a New Service</a></dt><dt>8. <a href="upgrade.html">Upgrading</a></dt><dd><dl><dt><a href="upgrade-detail.html">Support for upgrades.</a></dt></dl></dd><dt>9. <a href="maintenance.html">Maintenance</a></dt><dd><dl><dt><a href="maintenance-web.html">Hosting Web Sites</a></dt><dt><a href="database-management.html">Database Management</a></dt><dt><a href="backup-recovery.html">Backup and Recovery</a></dt></dl></dd><dt>A. <a href="install-redhat.html">Install Red Hat 8.0</a></dt><dt>B. <a href="install-more-software.html">Install additional supporting software</a></dt><dd><dl><dt><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></dt><dt><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt><dt><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt><dt><a href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt><a href="analog-install.html">Install Analog web file analyzer</a></dt><dt><a href="install-nspam.html">Install nspam</a></dt><dt><a href="install-full-text-search.html">Install Full Text Search</a></dt><dt><a href="install-nsopenssl.html">Install nsopenssl</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="quick.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Release Notes </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�2.�Quick Install</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/acs-admin.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/acs-package-dev.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-package-dev.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/acs-package-dev.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/acs-package-dev.html 14 Oct 2003 11:02:57 -0000 1.4
@@ -1,6 +1,5 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�III.�For OpenACS Package Developers</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="install-nsopenssl.html" title="Install nsopenssl"><link rel="next" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><h1 class="title"><a name="acs-package-dev"></a>For OpenACS Package Developers</h1></div></div><div class="partintro" lang="en"><div></div><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�III.�For OpenACS Package Developers</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="install-nsopenssl.html" title="Install nsopenssl"><link rel="next" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="acs-package-dev"></a>For OpenACS Package Developers</h1></div></div><div></div></div><div class="partintro" lang="en"><div><div></div><div></div></div><p>
This is the place to look if you want to extend OpenACS and build on
top of what's already here. Here you can find out about the
guts of the system.
- </p><div class="toc"><p><b>Table of Contents</b></p><dl><dt>10. <a href="tutorial.html">Development Tutorial</a></dt><dd><dl><dt><a href="tutorial-newpackage.html">Creating a Package</a></dt><dt><a href="tutorial-database.html">Setting Up Database Objects</a></dt><dt><a href="tutorial-pages.html">Creating Web Pages</a></dt><dt><a href="tutorial-debug.html">Debugging and Automated Testing</a></dt><dt><a href="tutorial-advanced.html">Advanced Topics</a></dt></dl></dd><dt>11. <a href="dev-guide.html">Development Reference</a></dt><dd><dl><dt><a href="packages.html">OpenACS 5.0.0d Packages</a></dt><dt><a href="objects.html">OpenACS Data Models and the Object System</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 5.0.0d</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 5.0.0d Application Pages</a></dt><dt><a href="parties.html">Parties in OpenACS 5.0.0d</a></dt><dt><a href="permissions-tediously-explained.html">OpenACS 4.x Permissions Tediously Explained</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></dd><dt>12. <a href="eng-standards.html">Engineering Standards</a></dt><dd><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></dd><dt>C. <a href="cvs-tips.html">Using CVS with an OpenACS Site</a></dt><dd><dl><dt><a href="cvs-service-import.html">Add the Service to CVS - OPTIONAL</a></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr><tr><td width="40%" align="left">Install nsopenssl </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�10.�Development Tutorial</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/acs-package-dev.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p><div class="toc"><p><b>Table of Contents</b></p><dl><dt>10. <a href="tutorial.html">Development Tutorial</a></dt><dd><dl><dt><a href="tutorial-newpackage.html">Creating a Package</a></dt><dt><a href="tutorial-database.html">Setting Up Database Objects</a></dt><dt><a href="tutorial-pages.html">Creating Web Pages</a></dt><dt><a href="tutorial-debug.html">Debugging and Automated Testing</a></dt><dt><a href="tutorial-advanced.html">Advanced Topics</a></dt></dl></dd><dt>11. <a href="dev-guide.html">Development Reference</a></dt><dd><dl><dt><a href="packages.html">OpenACS 5.0.0a1 Packages</a></dt><dt><a href="objects.html">OpenACS Data Models and the Object System</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 5.0.0a1</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 5.0.0a1 Application Pages</a></dt><dt><a href="parties.html">Parties in OpenACS 5.0.0a1</a></dt><dt><a href="permissions-tediously-explained.html">OpenACS 4.x Permissions Tediously Explained</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></dd><dt>12. <a href="eng-standards.html">Engineering Standards</a></dt><dd><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></dd><dt>A. <a href="cvs-tips.html">Using CVS with an OpenACS Site</a></dt><dd><dl><dt><a href="cvs-service-import.html">Add the Service to CVS - OPTIONAL</a></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr><tr><td width="40%" align="left">Install nsopenssl </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�10.�Development Tutorial</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/acs-package-dev.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/acs-plat-dev.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-plat-dev.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/acs-plat-dev.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/acs-plat-dev.html 14 Oct 2003 11:02:57 -0000 1.4
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�IV.�For OpenACS Platform Developers</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL"><link rel="next" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-service-import.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><h1 class="title"><a name="acs-plat-dev"></a>For OpenACS Platform Developers</h1></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>13. <a href="kernel-doc.html">Kernel Documentation</a></dt><dd><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 5.0.0d Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 5.0.0d Package Manager Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></dt><dt><a href="i18n.html">Internationalization</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt><dt><a href="ext-auth-requirements.html">External Authentication Requirements</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-service-import.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr><tr><td width="40%" align="left">Add the Service to CVS - OPTIONAL </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�13.�Kernel Documentation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/acs-plat-dev.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�IV.�For OpenACS Platform Developers</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL"><link rel="next" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-service-import.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="acs-plat-dev"></a>For OpenACS Platform Developers</h1></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>13. <a href="kernel-doc.html">Kernel Documentation</a></dt><dd><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 5.0.0a1 Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 5.0.0a1 Package Manager Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></dt><dt><a href="i18n.html">Internationalization</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt><dt><a href="ext-auth-requirements.html">External Authentication Requirements</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-service-import.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr><tr><td width="40%" align="left">Add the Service to CVS - OPTIONAL </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�13.�Kernel Documentation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/acs-plat-dev.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/analog-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-install.html,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/analog-install.html 28 Jun 2003 05:20:44 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/analog-install.html 14 Oct 2003 11:02:57 -0000 1.2
@@ -1,21 +1,20 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Analog web file analyzer</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-qmail.html" title="Install qmail (OPTIONAL)"><link rel="next" href="install-full-text-search.html" title=""><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-full-text-search.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="analog-install"></a>Install Analog web file analyzer</h2></div></div><p>Download the Analog <a href="individual-programs.html#analog-download">source tarball</a> in
-<tt>/tmp</tt>. Unpack, compile, and install analog.</p><pre class="screen">[root@yourserver aolserver]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/analog-5.31.tar.gz</tt></b>
-[root@yourserver src]# <b><tt>cd analog-5.31</tt></b>
-[root@yourserver analog-5.31]# <b><tt>make</tt></b>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Analog web file analyzer</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-qmail.html" title="Install qmail (OPTIONAL)"><link rel="next" href="install-nspam.html" title="Install nspam"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-nspam.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="analog-install"></a>Install Analog web file analyzer</h2></div></div><div></div></div><p>Download the Analog <a href="individual-programs.html#analog-download">source tarball</a> in
+<tt class="computeroutput">/tmp</tt>. Unpack, compile, and install analog.</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/analog-5.31.tar.gz</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>cd analog-5.31</tt></b>
+[root@yourserver analog-5.31]# <b class="userinput"><tt>make</tt></b>
cd src && make
make[1]: Entering directory `/usr/local/src/analog-5.31/src'
<span class="emphasis"><em>(many lines omitted)</em></span>
***IMPORTANT: You must read the licence before using analog
***
make[1]: Leaving directory `/usr/local/src/analog-5.31/src'
-[root@yourserver analog-5.31]# <b><tt>cd ..</tt></b>
-[root@yourserver src]#<b><tt> mv analog-5.31 /usr/share/</tt></b>
+[root@yourserver analog-5.31]# <b class="userinput"><tt>cd ..</tt></b>
+[root@yourserver src]#<b class="userinput"><tt> mv analog-5.31 /usr/share/</tt></b>
[root@yourserver src]#
-<pre class="action">cd /usr/local/src
+<pre class="action"><span class="action">cd /usr/local/src
tar xzf /tmp/analog-5.31.tar.gz
cd analog-5.31
make
cd ..
-mv analog-5.31 /usr/share/</pre></pre><p>See also <a href="maintenance-web.html#analog-setup" title="Set up Log Analysis Reports - OPTIONAL">the section called “Set up Log Analysis Reports - OPTIONAL”</a></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-full-text-search.html">Next</a></td></tr><tr><td width="40%" align="left">Install qmail (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/analog-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
+mv analog-5.31 /usr/share/</span></pre></pre><p>See also <a href="maintenance-web.html#analog-setup" title="Set up Log Analysis Reports - OPTIONAL">Section�, “Set up Log Analysis Reports - OPTIONAL”</a></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-nspam.html">Next</a></td></tr><tr><td width="40%" align="left">Install qmail (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install nspam</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/analog-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/aolserver.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver.html,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/aolserver.html 20 Aug 2003 16:20:16 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/aolserver.html 14 Oct 2003 11:02:57 -0000 1.14
@@ -1,45 +1,44 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install AOLserver 3.3oacs1</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="postgres.html" title="Install PostGreSQL"><link rel="next" href="openacs.html" title="Install OpenACS 5.0.0d"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="aolserver"></a>Install AOLserver 3.3oacs1</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install AOLserver 3.3oacs1</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="postgres.html" title="Install PostGreSQL"><link rel="next" href="openacs.html" title="Install OpenACS 5.0.0a1"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aolserver"></a>Install AOLserver 3.3oacs1</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="orderedlist"><ol type="1"><li><a name="aolserver-tarball"></a><p><b>Unpack the Aolserver tarball.�</b>Download the <a href="individual-programs.html#source-aolserver">aolserver tarball</a> to <tt>/tmp/aolserver3.3oacs1.tar.gz</tt>. As <tt>root</tt>, untar
- <tt>aolserver3.3oacs1.tar.gz</tt>
- into <tt>/usr/local/src</tt>.
- </p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/aolserver3.3oacs1.tar.gz</tt></b>
+ </p></div><div class="orderedlist"><ol type="1"><li><a name="aolserver-tarball"></a><p><b>Unpack the Aolserver tarball.�</b>Download the <a href="individual-programs.html#source-aolserver">aolserver tarball</a> to <tt class="computeroutput">/tmp/aolserver3.3oacs1.tar.gz</tt>. As <tt class="computeroutput">root</tt>, untar
+ <tt class="computeroutput">aolserver3.3oacs1.tar.gz</tt>
+ into <tt class="computeroutput">/usr/local/src</tt>.
+ </p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/aolserver3.3oacs1.tar.gz</tt></b>
[root@yourserver src]#
-<pre class="action">cd /usr/local/src
-tar xzf /tmp/aolserver3.3oacs1.tar.gz</pre></pre></li><li><a name="install-aolserver-compile"></a><p><b>Compile AOLserver.�</b>Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.</p><pre class="screen">root@yourserver root]# <b><tt>mkdir -p /usr/local/aolserver</tt></b>
-[root@yourserver root]# <b><tt>cd /usr/local/src/aolserver</tt></b>
-[root@yourserver aolserver]# <b><tt>./conf-clean</tt></b>
+<pre class="action"><span class="action">cd /usr/local/src
+tar xzf /tmp/aolserver3.3oacs1.tar.gz</span></pre></pre></li><li><a name="install-aolserver-compile"></a><p><b>Compile AOLserver.�</b>Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.</p><pre class="screen">root@yourserver root]# <b class="userinput"><tt>mkdir -p /usr/local/aolserver</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src/aolserver</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>./conf-clean</tt></b>
cat: BUILD-MODULES: No such file or directory
Done.
-[root@yourserver aolserver]#<pre class="action">mkdir -p /usr/local/aolserver
+[root@yourserver aolserver]#<pre class="action"><span class="action">mkdir -p /usr/local/aolserver
cd /usr/local/src/aolserver
-./conf-clean</pre></pre><p>
+./conf-clean</span></pre></pre><p>
If you are using Oracle, edit
- <tt>conf-db</tt> and change
- <tt>postgresql</tt> to
- <tt>oracle</tt>, or to the word
- <tt>both</tt> if you want both drivers
+ <tt class="computeroutput">conf-db</tt> and change
+ <tt class="computeroutput">postgresql</tt> to
+ <tt class="computeroutput">oracle</tt>, or to the word
+ <tt class="computeroutput">both</tt> if you want both drivers
installed. In order to get nsoracle to compile, you may
need to su - oracle, and then su (without the -) root to set
the environment variables properly.
- </p><p><tt>conf-inst</tt> should contain the
+ </p><p><tt class="computeroutput">conf-inst</tt> should contain the
location where AOLserver is to be installed. Overwrite the
- tarball's default value with our default value, <tt>/usr/local/aolserver</tt>:</p><pre class="screen">[root@yourserver aolserver]# <b><tt>echo "/usr/local/aolserver" > conf-inst</tt></b>
-[root@yourserver aolserver]#</pre><p><tt>conf-make</tt> should contain the
+ tarball's default value with our default value, <tt class="computeroutput">/usr/local/aolserver</tt>:</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>echo "/usr/local/aolserver" > conf-inst</tt></b>
+[root@yourserver aolserver]#</pre><p><tt class="computeroutput">conf-make</tt> should contain the
name of the GNU Make command on your system. It defaults to
- <tt>gmake</tt>.</p><p>Set an environment variable that the nspostgres driver
+ <tt class="computeroutput">gmake</tt>.</p><p>Set an environment variable that the nspostgres driver
Makefile needs to compile correctly and run
- <tt>conf</tt>, which compiles
+ <tt class="computeroutput">conf</tt>, which compiles
AOLserver, the default modules, and the database driver, and
installs them.</p><p>(Debian Users working with AOLserver 3.3+ad13 and
postgresql from apt-get may need to
- make these symlinks: <tt>ln -s
+ make these symlinks: <tt class="computeroutput">ln -s
/usr/include/postgresql/ /usr/include/pgsql</tt>
- and <tt>ln -s /usr/lib/postgresql /usr/local/pgsql</tt>)</p><pre class="screen">[root@yourserver aolserver]# <b><tt>export POSTGRES=/usr/local/pgsql; ./conf</tt></b>
+ and <tt class="computeroutput">ln -s /usr/lib/postgresql /usr/local/pgsql</tt>)</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>export POSTGRES=/usr/local/pgsql; ./conf</tt></b>
Building in /usr/local/aolserver
with the following modules:
aolserver
@@ -61,75 +60,75 @@
==================================================================
Done Building Sat Mar 8 10:31:35 PST 2003
[root@yourserver aolserver]# </pre><p>
- This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in <tt>/usr/local/src/aolserver/log</tt>. If you run into problems running AOLserver, check these files for build errors.</p></li><li><a name="aolserver-db-wrapper"></a><p><b>Add a database-specific wrapper script.�</b>This script
+ This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in <tt class="computeroutput">/usr/local/src/aolserver/log</tt>. If you run into problems running AOLserver, check these files for build errors.</p></li><li><a name="aolserver-db-wrapper"></a><p><b>Add a database-specific wrapper script.�</b>This script
sets database environment variables before starting
AOLserver; this allows the AOLserver instance can
communicate with the database. There is one script each for
Oracle and PostGreSQL. They don't conflict, so if you plan
- to use both databases, install both.</p><div class="itemizedlist"><ul type="disc"><li><p>Oracle</p><pre class="screen">[root@yourserver aolserver]# <b><tt>cd /usr/local/aolserver/bin</tt></b>
-[root@yourserver bin]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</tt></b>
-[root@yourserver bin]# <b><tt>chmod 750 nsd-oracle</tt></b>
+ to use both databases, install both.</p><div class="itemizedlist"><ul type="disc"><li><p>Oracle</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>cd /usr/local/aolserver/bin</tt></b>
+[root@yourserver bin]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</tt></b>
+[root@yourserver bin]# <b class="userinput"><tt>chmod 750 nsd-oracle</tt></b>
[root@yourserver bin]#
-<pre class="action">cd /usr/local/aolserver/bin
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
-chmod 750 nsd-oracle</pre></pre></li><li><p>PostGreSQL</p><pre class="screen">[root@yourserver aolserver]# <b><tt>cd /usr/local/aolserver/bin</tt></b>
-[root@yourserver bin]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</tt></b>
-[root@yourserver bin]# <b><tt>chmod 755 nsd-postgres</tt></b>
+<pre class="action"><span class="action">cd /usr/local/aolserver/bin
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
+chmod 750 nsd-oracle</span></pre></pre></li><li><p>PostGreSQL</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>cd /usr/local/aolserver/bin</tt></b>
+[root@yourserver bin]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</tt></b>
+[root@yourserver bin]# <b class="userinput"><tt>chmod 755 nsd-postgres</tt></b>
[root@yourserver bin]#
-<pre class="action">cd /usr/local/aolserver/bin
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
-chmod 755 nsd-postgres</pre></pre></li></ul></div></li><li><a name="install-tdom"></a><p><b>Install tDOM.�</b>Download the <a href="individual-programs.html#source-tdom">tDOM
+<pre class="action"><span class="action">cd /usr/local/aolserver/bin
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
+chmod 755 nsd-postgres</span></pre></pre></li></ul></div></li><li><a name="install-tdom"></a><p><b>Install tDOM.�</b>Download the <a href="individual-programs.html#source-tdom">tDOM
tarball</a> to
- <tt>/tmp/tDOM-0.7.7.tar.gz</tt>,
+ <tt class="computeroutput">/tmp/tDOM-0.7.7.tar.gz</tt>,
unpack it, adjust the configuration file to match our patched
- distribution of aolserver, and compile it.</p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/tDOM-0.7.7.tar.gz</tt></b>
-[root@yourserver src]# <b><tt>cd tDOM-0.7.7/unix</tt></b>
+ distribution of aolserver, and compile it.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/tDOM-0.7.7.tar.gz</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>cd tDOM-0.7.7/unix</tt></b>
[root@yourserver unix]#
-<pre class="action">cd /usr/local/src
+<pre class="action"><span class="action">cd /usr/local/src
tar xzf /tmp/tDOM-0.7.7.tar.gz
-cd unix</pre> </pre><p>Edit the file CONFIG and change this section:
+cd unix</span></pre> </pre><p>Edit the file CONFIG and change this section:
</p><pre class="programlisting"># ----------------------------------------------------
-# aolsrc="/usr/src/aolserver-3.4"
+# aolsrc="/usr/src/aolserver-3.4"
# ../configure --enable-threads --disable-tdomalloc \
# --with-aolserver=$aolsrc \
# --with-tcl=$aolsrc/tcl8.3.4/unix </pre><p>
</p><p>to</p><p>
</p><pre class="programlisting"># ----------------------------------------------------
-aolsrc="/usr/local/src/aolserver/aolserver"
+aolsrc="/usr/local/src/aolserver/aolserver"
../configure --enable-threads --disable-tdomalloc \
--with-aolserver=$aolsrc \
--with-tcl=$aolsrc/tcl8.3.2/unix</pre><p>
</p><p>And configure and compile:</p><p>
- </p><pre class="screen">[root@yourserver unix]# <b><tt>sh CONFIG</tt></b>
+ </p><pre class="screen">[root@yourserver unix]# <b class="userinput"><tt>sh CONFIG</tt></b>
creating cache ./config.cache
checking for memmove... yes
<span class="emphasis"><em>(many lines omitted)</em></span>
creating Makefile
creating tdomConfig.sh
-[root@yourserver unix]# <b><tt>make</tt></b>
+[root@yourserver unix]# <b class="userinput"><tt>make</tt></b>
gcc -pipe -DHAVE_UNISTD_H=1 -DHAVE_LIMITS_H=1 -DTCL_THREADS=1
-DHAVE_GETCWD=1 -DHAVE_OPENDIR=1 -DHAVE_STRSTR=1 -DHAVE_STRTOL=1
<span class="emphasis"><em>(many lines omitted)</em></span>
-Wl,-rpath,/usr/local/lib -o tcldomsh;\
fi
-[root@yourserver unix]# <b><tt>cp libtdom0.7.7.so /usr/local/aolserver/bin/</tt></b>
-<pre class="action">sh CONFIG
+[root@yourserver unix]# <b class="userinput"><tt>cp libtdom0.7.7.so /usr/local/aolserver/bin/</tt></b>
+<pre class="action"><span class="action">sh CONFIG
make
-cp libtdom0.7.7.so /usr/local/aolserver/bin/</pre></pre><p>
+cp libtdom0.7.7.so /usr/local/aolserver/bin/</span></pre></pre><p>
</p></li><li><p><a href="install-nsopenssl.html" title="Install nsopenssl">Install nsopenssl</a>
- (OPTIONAL)</p></li><li><p><a href="install-full-text-search.html#install-openfts" title="Install OpenFTS module">Install Full Text Search with OpenFTS</a> (OPTIONAL)</p></li><li><a name="install-aolserver-permissions"></a><p><b>Test AOLserver.�</b>In order to test AOLserver, we'll run it using the
+ (OPTIONAL)</p></li><li><p><a href="install-full-text-search.html#install-openfts" title="Install OpenFTS module">Install Full Text Search with OpenFTS</a> (OPTIONAL)</p></li><li><p><a href="install-nspam.html" title="Install nspam">Install nspam</a> (OPTIONAL)</p></li><li><a name="install-aolserver-permissions"></a><p><b>Test AOLserver.�</b>In order to test AOLserver, we'll run it using the
sample-config.tcl file provided in the AOLserver distribution,
- under the nobody user and <tt>web</tt>
+ under the nobody user and <tt class="computeroutput">web</tt>
group. The sample-config.tcl configuration writes to the
default log locations, so we need to give it permission to do so
- or it will fail. Grant the <tt>web</tt>
+ or it will fail. Grant the <tt class="computeroutput">web</tt>
group permission to write to
- <tt>/usr/local/aolserver/log</tt> and
- <tt>/usr/local/aolserver/servers</tt>.</p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/aolserver</tt></b>
-[root@yourserver aolserver]# <b><tt>chown -R root.web log servers</tt></b>
-[root@yourserver aolserver]# <b><tt>chmod -R g+w log servers</tt></b>
-[root@yourserver aolserver]# <b><tt>ls -l</tt></b>
+ <tt class="computeroutput">/usr/local/aolserver/log</tt> and
+ <tt class="computeroutput">/usr/local/aolserver/servers</tt>.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/aolserver</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>chown -R root.web log servers</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>chmod -R g+w log servers</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>ls -l</tt></b>
total 32
drwxr-sr-x 2 root root 4096 Mar 8 12:57 bin
drwxr-xr-x 3 root root 4096 Mar 8 10:34 include
@@ -139,15 +138,15 @@
-rw-r--r-- 1 root root 7320 Mar 31 2001 sample-config.tcl
drwxrwsr-x 3 root web 4096 Mar 8 10:31 servers
[root@yourserver aolserver]#
-<pre class="action">
+<pre class="action"><span class="action">
cd /usr/local/aolserver
chown -R root.web log servers
chmod -R g+w log servers
-ls -l</pre></pre><p>Now, we'll run a quick test to ensure AOLserver is running
+ls -l</span></pre></pre><p>Now, we'll run a quick test to ensure AOLserver is running
correctly. We'll use the sample config file provided with
AOLserver. This file will attempt to guess your IP address and
hostname. It will then start up the server at port 8000 of that
- IP address.</p><pre class="screen">[root@yourserver aolserver]# <b><tt>./bin/nsd -t sample-config.tcl -u nobody -g web</tt></b>
+ IP address.</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>./bin/nsd -t sample-config.tcl -u nobody -g web</tt></b>
[root@yourserver aolserver]# [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: starting to read config file...
[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nsssl not loaded -- key/cert files do not exist.
[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nscp not loaded
@@ -156,32 +155,32 @@
config file.</pre><p>The first warning, about nsssl, can be ignored. We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet. The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load. We don't plan to use it and can ignore that error as well. Any other warning or error is unexpected and probably a problem.</p><p>
Test to see if AOLserver is working by starting
- <tt>Mozilla</tt> or
- <tt>Lynx</tt> <span class="emphasis"><em>on the same
+ <tt class="computeroutput">Mozilla</tt> or
+ <tt class="computeroutput">Lynx</tt> <span class="emphasis"><em>on the same
computer</em></span> and surfing over to your web page. If
you browse from another computer and the sample config file
didn't guess your hostname or ip correctly, you'll get a
false negative test.
- </p><pre class="screen">[root@yourserver aolserver]# <b><tt>lynx localhost:8000</tt></b></pre><p>
+ </p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>lynx localhost:8000</tt></b></pre><p>
- You should see a "Welcome to AOLserver" page. If this
+ You should see a "Welcome to AOLserver" page. If this
doesn't work, try going to
- <tt>http://127.0.0.1:8000/</tt>. If this
+ <tt class="computeroutput">http://127.0.0.1:8000/</tt>. If this
still doesn't work, check out the <a href="aolserver.html#install-aolserver-troubleshooting">Troubleshooting AOLserver</a> section below. Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address.
- </p><p>Shutdown the test server:</p><pre class="screen">[root@yourserver aolserver]# <b><tt>killall nsd</tt></b>
+ </p><p>Shutdown the test server:</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>killall nsd</tt></b>
[root@yourserver aolserver]#</pre><p>
- The <tt>killall</tt> command will kill
- all processes with the name <tt>nsd</tt>,
+ The <tt class="computeroutput">killall</tt> command will kill
+ all processes with the name <tt class="computeroutput">nsd</tt>,
but clearly this is not a good tool to use for managing your
services in general. We cover this topic in the <a href="maintenance-web.html#install-openacs-keepalive">Keep AOLServer alive</a> section.
</p></li><li><a name="install-aolserver-troubleshooting"></a><p><b>Troubleshooting.�</b>If you can't view the welcome page, it's likely there's a
problem with your server configuration. Start by viewing your
AOLserver log, which is in
- <tt>/usr/local/aolserver/log/server.log</tt>.
+ <tt class="computeroutput">/usr/local/aolserver/log/server.log</tt>.
You should also try to find lines of the form:
</p><pre class="screen">
[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000)
@@ -190,12 +189,12 @@
If you can find these lines, try entering the URL the server is
listening on. If you cannot find these lines, there must be an error
somewhere in the file. Search for lines beginning with the word
- <tt>Error</tt> instead of
- <tt>Notice</tt>.
+ <tt class="computeroutput">Error</tt> instead of
+ <tt class="computeroutput">Notice</tt>.
</p><p>
- The <tt>sample-config.tcl</tt> file grabs
+ The <tt class="computeroutput">sample-config.tcl</tt> file grabs
your address and hostname from your OS settings.
</p><pre class="screen">
@@ -205,11 +204,11 @@
If you get an error that nssock can't get the requested address, you
can set these manually. If you type 0.0.0.0, AOLserver will try to
listen on all available addresses. <span class="emphasis"><em>Note</em></span>:
- <tt>ns_info address</tt> doesn't appear
+ <tt class="computeroutput">ns_info address</tt> doesn't appear
to be supported in current versions of AOLserver.
</p><pre class="screen">
set hostname [ns_info hostname]
#set address [ns_info address]
set address 0.0.0.0</pre></li><li><p><a href="analog-install.html" title="Install Analog web file analyzer">Install
- Analog</a> web file analyzer. (OPTIONAL)</p></li></ol></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Install PostGreSQL </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install OpenACS 5.0.0d</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/aolserver.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ Analog</a> web file analyzer. (OPTIONAL)</p></li></ol></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Install PostGreSQL </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install OpenACS 5.0.0a1</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/aolserver.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/apm-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/apm-design.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/apm-design.html 14 Oct 2003 11:02:57 -0000 1.12
@@ -1,13 +1,12 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 5.0.0d Package Manager Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="apm-requirements.html" title="OpenACS 5.0.0d Package Manager Requirements"><link rel="next" href="db-api-detailed.html" title="Database Access API"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="apm-design"></a>OpenACS 5.0.0d Package Manager Design</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 5.0.0a1 Package Manager Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="apm-requirements.html" title="OpenACS 5.0.0a1 Package Manager Requirements"><link rel="next" href="db-api-detailed.html" title="Database Access API"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apm-design"></a>OpenACS 5.0.0a1 Package Manager Design</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/acs-admin/apm" target="_top">OpenACS Administrator directory</a></p></li><li><p><a href="apm-requirements.html">OpenACS 5.0.0d Package Manager Requirements</a></p></li><li><p><a href="packages.html">Packages</a></p></li><li><p><a href="images/apm.pdf" target="_top">ER diagram</a></p></li><li><p>Tcl API </p><div class="itemizedlist"><ul type="circle"><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dprocs%2etcl" target="_top">
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/acs-admin/apm" target="_top">OpenACS Administrator directory</a></p></li><li><p><a href="apm-requirements.html">OpenACS 5.0.0a1 Package Manager Requirements</a></p></li><li><p><a href="packages.html">Packages</a></p></li><li><p><a href="images/apm.pdf" target="_top">ER diagram</a></p></li><li><p>Tcl API </p><div class="itemizedlist"><ul type="circle"><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dprocs%2etcl" target="_top">
apm-procs.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dinstall%2dprocs%2etcl" target="_top">
apm-install-procs.tcl</a> (Supports installation of packages)</p></li><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2f20%2dapm%2dload%2dprocs%2etcl" target="_top">
20-apm-load-procs.tcl</a> (Bootstraps APM for server startup)</p></li><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dadmin%2dprocs%2etcl" target="_top">
-apm-admin-procs.tcl</a> (Supports APM UI)</p></li></ul></div></li><li><p>PL/SQL file </p><div class="itemizedlist"><ul type="circle"><li><p><a href="/doc/sql/display-sql?url=apm-create.sql&package_key=acs-kernel" target="_top">apm-create.sql</a></p></li></ul></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-intro"></a>Introduction</h3></div></div><p>
+apm-admin-procs.tcl</a> (Supports APM UI)</p></li></ul></div></li><li><p>PL/SQL file </p><div class="itemizedlist"><ul type="circle"><li><p><a href="/doc/sql/display-sql?url=apm-create.sql&package_key=acs-kernel" target="_top">apm-create.sql</a></p></li></ul></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-intro"></a>Introduction</h3></div></div><div></div></div><p>
In general terms, a <span class="strong">package</span> 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
@@ -16,8 +15,8 @@
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:
-</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">OpenACS Applications:</span> a "program or group of programs
-designed for end users" (the <a href="http://www.pcwebopaedia.com/TERM/a/application.html" target="_top">Webopedia
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">OpenACS Applications:</span> a "program or group of programs
+designed for end users" (the <a href="http://www.pcwebopaedia.com/TERM/a/application.html" target="_top">Webopedia
definition</a>); also known as <span class="emphasis"><em>modules</em></span>, for historical reasons.
Examples of applications include <a href="/doc/bboard" target="_top">Bboard</a> and <a href="/doc/news" target="_top">News</a>.
@@ -44,7 +43,7 @@
installation through APM is another potential package instance that can
become part of Jane's View Camera subsite.</p><p>The APM provides an architecture for packaging software, making instances
of that software available to subsites, specifying configuration parameters
-for each instance, and managing the creation and release of new packages.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-hist-considerations"></a>Historical Considerations</h3></div></div><p>
+for each instance, and managing the creation and release of new packages.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-hist-considerations"></a>Historical Considerations</h3></div></div><div></div></div><p>
Prior to ACS 3.3, all packages were lumped together into one monolithic
distribution without explicit boundaries; the only way to ascertain what
comprised a given package was to look at the top of the corresponding
@@ -89,21 +88,21 @@
packages for other ACS users to download and install.</p><p>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):</p><div class="mediaobject"><img src="images/acs-without-apm-vs-with-apm.png" align="center" longdesc="ld-id2944203.html"><div class="longdesc-link" align="right"><br clear="all"><span class="longdesc-link">[<a href="ld-id2944203.html" target="longdesc">D</a>]</span></div></div><p>APM itself is part of a package, the <span class="strong">OpenACS Kernel</span>, an OpenACS
-service that is the only mandatory component of an OpenACS installation.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-competitors"></a>Competitive Analysis</h3></div></div><p>The OpenACS is a platform for web-based application software, and any software
+3.2 (say, bboard and e-commerce):</p><div class="mediaobject" align="center"><img src="images/acs-without-apm-vs-with-apm.png" align="middle" longdesc="ld-id2878072.html"><div class="longdesc-link" align="right"><br clear="all"><span class="longdesc-link">[<a href="ld-id2878072.html" target="longdesc">D</a>]</span></div></div><p>APM itself is part of a package, the <span class="strong">OpenACS Kernel</span>, an OpenACS
+service that is the only mandatory component of an OpenACS installation.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-competitors"></a>Competitive Analysis</h3></div></div><div></div></div><p>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:</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://www.debian.org/" target="_top">Debian GNU/Linux</a> and the <a href="http://www.debian.org/doc/packaging-manuals/packaging.html/" target="_top">Debian
Packaging manual</a></p></li><li><p><a href="http://www.freebsd.org/" target="_top">FreeBSD</a> has <a href="http://www.freebsd.org/handbook/ports.html" target="_top">the Ports
collection</a></p></li><li><p><a href="http://www.redhat.com/" target="_top">Red Hat Linux</a> has <a href="http://rpm.redhat.com/" target="_top">the Red Hat Package Manager (RPM)</a></p></li></ul></div><p>Borrowing from all of the above, OpenACS 3.3 introduces its own package
management system, the OpenACS Package Manager (APM), which consists of:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">a standard format for APM packages</span> (also called
-"OpenACS packages"), including: </p><div class="itemizedlist"><ul type="circle"><li><p>version numbering, independent of any other package and the OpenACS as a
+"OpenACS packages"), including: </p><div class="itemizedlist"><ul type="circle"><li><p>version numbering, independent of any other package and the OpenACS as a
whole</p></li><li><p>specification of the package interface</p></li><li><p>specification of dependencies on other packages (if any)</p></li><li><p>attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div></li><li><p><span class="strong">web-based tools for package management:</span> </p><div class="itemizedlist"><ul type="circle"><li><p>obtaining packages from a remote distribution point</p></li><li><p>installing packages, if and only if: </p><div class="orderedlist"><ol type="1"><li><p>all prerequisite packages are installed</p></li><li><p>no conflicts will be created by the installation</p></li></ol></div></li><li><p>configuring packages (obsoleting the monolithic OpenACS configuration
file)</p></li><li><p>upgrading packages, without clobbering local modifications</p></li><li><p>uninstalling unwanted packages</p></li></ul></div></li><li><p><span class="strong">a registry of installed packages</span>, database-backed and
integrated with filesystem-based version control
-</p></li><li><p><span class="strong">web-based tools for package development:</span> </p><div class="itemizedlist"><ul type="circle"><li><p>creating new packages locally</p></li><li><p>releasing new versions of locally-created packages</p></li></ul></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>
+</p></li><li><p><span class="strong">web-based tools for package development:</span> </p><div class="itemizedlist"><ul type="circle"><li><p>creating new packages locally</p></li><li><p>releasing new versions of locally-created packages</p></li></ul></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><div></div></div><p>
The design chosen for APM was meant to satisfy the following constraints:
</p><div class="itemizedlist"><ul type="disc"><li><p>The process of authoring a package must be as simple as possible.</p></li><li><p>Strict conventions must be established that provide a set of canonical
locations and names for files and patterns, for OpenACS application
@@ -122,7 +121,7 @@
documentation walks the developer through each of these steps. Moreover, from
following these steps, the package can be subsite specific, available to
subsites across the system, and be available for distribution to other OpenACS
-installations without doing a monolithic upgrade or reinstall.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-api"></a>API</h3></div></div><p>The APM is composed of systems for accomplishing a set of package-related
+installations without doing a monolithic upgrade or reinstall.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-api"></a>API</h3></div></div><div></div></div><p>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:</p><div class="itemizedlist"><ul type="disc"><li><p>Authoring a Package</p></li><li><p>Maintaining Multiple Versions of a Package</p></li><li><p>Creating Instances of the Package</p></li><li><p>Specifying Configuration Parameters for each Instance</p></li></ul></div><p><span class="strong">Authoring a Package</span></p><p>Full instructions on how to prepare an OpenACS package are available in <a href="packages.html">Packages</a>. 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 <a href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM" target="_top">APM PL/SQL
@@ -145,9 +144,9 @@
</pre><p>The procedure above registers an OpenACS application in the APM. It creates a
new OpenACS object and stores information about the package, such as its name, in
the APM data model. There is an analogous procedure for OpenACS services, called
-<tt>apm.register_service</tt>.</p><p>To remove an application from the system, there are the calls
-<tt>apm.unregister_application</tt> and
-<tt>apm.unregister_service</tt>.</p><pre class="programlisting">
+<tt class="computeroutput">apm.register_service</tt>.</p><p>To remove an application from the system, there are the calls
+<tt class="computeroutput">apm.unregister_application</tt> and
+<tt class="computeroutput">apm.unregister_service</tt>.</p><pre class="programlisting">
-- Remove the application from the system.
procedure unregister_application (
@@ -156,10 +155,10 @@
cascade_p in char default 'f'
);
-</pre><p>Use the <tt>cascade_p</tt> only if you want to completely remove the
+</pre><p>Use the <tt class="computeroutput">cascade_p</tt> only if you want to completely remove the
package from the OpenACS.</p><p>In order to determine if a particular package exists in the system, use
-the <tt>register_p</tt> predicate. It returns 1 if the specified
-<tt>package_key</tt> exists in the system, 0 otherwise.</p><pre class="programlisting">
+the <tt class="computeroutput">register_p</tt> predicate. It returns 1 if the specified
+<tt class="computeroutput">package_key</tt> exists in the system, 0 otherwise.</p><pre class="programlisting">
function register_p (
package_key in apm_package_types.package_key%TYPE
@@ -170,8 +169,8 @@
between versions, the owner of a package, its vendor, its URI, and its
dependency information may change. The API for package versions allows this
information to be specified. All of these APIs are part of the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM%5fPACKAGE%5fVERSION" target="_top">
-<tt>apm_package_version</tt> PL/SQL package</a>.</p><p>To create a new package version, use the
-<tt>apm_package_version.new</tt> constructor function.</p><pre class="programlisting">
+<tt class="computeroutput">apm_package_version</tt> PL/SQL package</a>.</p><p>To create a new package version, use the
+<tt class="computeroutput">apm_package_version.new</tt> constructor function.</p><pre class="programlisting">
function new (
version_id in apm_package_versions.version_id%TYPE
@@ -192,26 +191,26 @@
default 'f'
) return apm_package_versions.version_id%TYPE;
-</pre><p>In order to use this function, an existing <tt>package_key</tt> must
-be specified. The <tt>version_name</tt> parameter must follow a strict
+</pre><p>In order to use this function, an existing <tt class="computeroutput">package_key</tt> must
+be specified. The <tt class="computeroutput">version_name</tt> parameter must follow a strict
convention:</p><div class="orderedlist"><ol type="1"><li><p>A major version number</p></li><li><p>at least one minor version number. Although any number of minor version
numbers may be included, three minor version numbers is sufficient and is the
-convention of software developers.</p></li><li><p>One of the following: </p><div class="itemizedlist"><ul type="disc"><li><p>The letter <tt>d</tt>, indicating a development-only version</p></li><li><p>The letter <tt>a</tt>, indicating an alpha release</p></li><li><p>The letter <tt>b</tt>, indicating a beta release</p></li><li><p>No letter at all, indicating a final production release</p></li></ul></div></li></ol></div><p>In addition, the letters <tt>d</tt>, <tt>a</tt>, and
-<tt>b</tt> may be followed by another integer, indicating a version
+convention of software developers.</p></li><li><p>One of the following: </p><div class="itemizedlist"><ul type="disc"><li><p>The letter <tt class="computeroutput">d</tt>, indicating a development-only version</p></li><li><p>The letter <tt class="computeroutput">a</tt>, indicating an alpha release</p></li><li><p>The letter <tt class="computeroutput">b</tt>, indicating a beta release</p></li><li><p>No letter at all, indicating a final production release</p></li></ul></div></li></ol></div><p>In addition, the letters <tt class="computeroutput">d</tt>, <tt class="computeroutput">a</tt>, and
+<tt class="computeroutput">b</tt> may be followed by another integer, indicating a version
within the release.</p><p>For those who like regular expressions:</p><pre class="programlisting">
version_number := ^[0-9]+((\.[0-9]+)+((d|a|b|)[0-9]?)?)$
-</pre><p>So the following is a valid progression for version numbers:</p><div class="blockquote"><blockquote class="blockquote"><p><tt>0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1,
+</pre><p>So the following is a valid progression for version numbers:</p><div class="blockquote"><blockquote class="blockquote"><p><tt class="computeroutput">0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1,
1.1</tt></p></blockquote></div><p>To delete a given version of a package, use the
-<tt>apm_package_version.delete</tt> procedure:</p><pre class="programlisting">
+<tt class="computeroutput">apm_package_version.delete</tt> procedure:</p><pre class="programlisting">
procedure delete (
package_id in apm_packages.package_id%TYPE
);
</pre><p>After creating a version, it is possible to edit the information
-associated with it using <tt>apm_package_version.edit</tt>.</p><pre class="programlisting">
+associated with it using <tt class="computeroutput">apm_package_version.edit</tt>.</p><pre class="programlisting">
function edit (
new_version_id in apm_package_versions.version_id%TYPE
@@ -246,7 +245,7 @@
</pre><p>Files associated with a version can be added and removed. The path is
relative to the <span class="strong">package-root</span> which is
-<tt>acs-server-root/packages/package-key</tt>.</p><pre class="programlisting">
+<tt class="computeroutput">acs-server-root/packages/package-key</tt>.</p><pre class="programlisting">
-- Add a file to the indicated version.
function add_file(
file_id in apm_package_files.file_id%TYPE
@@ -383,7 +382,7 @@
</pre><p><span class="strong">Specifying Configuration Parameters for each Instance</span></p><p>A parameter is a setting that can be changed on a package instance basis.
-Parameters are registered on each <tt>package_key</tt>, and the values
+Parameters are registered on each <tt class="computeroutput">package_key</tt>, 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
API for setting a number of minimum and maximum values for each parameter,
@@ -464,65 +463,65 @@
attr_value in apm_parameter_values.attr_value%TYPE
);
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-data-model"></a>Data Model Discussion</h3></div></div><p>The central piece of the data model is the <tt>apm_package_types</tt>
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-data-model"></a>Data Model Discussion</h3></div></div><div></div></div><p>The central piece of the data model is the <tt class="computeroutput">apm_package_types</tt>
table where each package is registered. When a new application or service is
installed on an OpenACS instance, a corresponding row in this table is inserted
with information about the type of package, e.g. if the <a href="/doc/bboard" target="_top">bboard package</a> is installed on your OpenACS server, a row
-in <tt>apm_package_types</tt> will be created, noting that it's an
-application package type.</p><p>The <tt>apm_packages</tt> table is used to contain information about
+in <tt class="computeroutput">apm_package_types</tt> will be created, noting that it's an
+application package type.</p><p>The <tt class="computeroutput">apm_packages</tt> table is used to contain information about
the <span class="emphasis"><em>instances</em></span> of packages currently created in the system. The
-<tt>package_key</tt> column references the <tt>apm_package_types</tt>
+<tt class="computeroutput">package_key</tt> column references the <tt class="computeroutput">apm_package_types</tt>
table to ensure that no package instance can be created for a type that does
-not exist.</p><p>The <tt>apm_package_versions</tt> table contains information specific
+not exist.</p><p>The <tt class="computeroutput">apm_package_versions</tt> table contains information specific
to a particular version of a package. Several tables reference this one to
-provide further information about the particular version:</p><div class="itemizedlist"><ul type="disc"><li><p><tt>apm_package_owners</tt>
+provide further information about the particular version:</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput">apm_package_owners</tt>
Stores information about the owners of a particular version of a package.
-</p></li><li><p><tt>apm_package_files</tt>
+</p></li><li><p><tt class="computeroutput">apm_package_files</tt>
Stores information about the files that are part of a version.
-</p></li><li><p><tt>apm_package_dependencies</tt>
+</p></li><li><p><tt class="computeroutput">apm_package_dependencies</tt>
Stores information about what interfaces the package provides and
-requires.</p></li></ul></div><p>Parameter information is maintained through two tables:</p><div class="itemizedlist"><ul type="disc"><li><p><tt>apm_parameters</tt>
+requires.</p></li></ul></div><p>Parameter information is maintained through two tables:</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput">apm_parameters</tt>
This table contains the definition of each of the parameters for a package.
-</p></li><li><p><tt>apm_parameter_values</tt>
+</p></li><li><p><tt class="computeroutput">apm_parameter_values</tt>
This table holds all of the values of parameters for specific package
instances.
</p></li></ul></div><p>A number of views are available for obtaining information about packages
-registered in the APM.</p><div class="itemizedlist"><ul type="disc"><li><p><tt>apm_package_version_info</tt>
+registered in the APM.</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput">apm_package_version_info</tt>
Provides information about all of the versions in the system with
-information available from the <tt>apm_package_types</tt> table.
+information available from the <tt class="computeroutput">apm_package_types</tt> table.
-</p></li><li><p><tt>apm_enabled_package_versions</tt>
+</p></li><li><p><tt class="computeroutput">apm_enabled_package_versions</tt>
A view (subset) of the above table with only enabled versions.
-</p></li><li><p><tt>apm_file_info</tt>
- Provides a public interface for querying file information.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-ui"></a>User Interface</h3></div></div><p>The <a href="/acs-admin/apm" target="_top">APM's user interface</a> is part of the
+</p></li><li><p><tt class="computeroutput">apm_file_info</tt>
+ Provides a public interface for querying file information.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-ui"></a>User Interface</h3></div></div><div></div></div><p>The <a href="/acs-admin/apm" target="_top">APM's user interface</a> is part of the
<a href="/acs-admin" target="_top">OpenACS Administration Service</a>. The UI is the primary
point of contact with APM by developers and administrators. It is part of OpenACS
Administration, because only the site-wide administrator should be able to
access it. Thus in order to develop a package, the developer must be granted
-site-wide administration.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-config"></a>Configuration/Parameters</h3></div></div><p>APM has two parameters for configuring how it interacts with the UNIX
+site-wide administration.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-config"></a>Configuration/Parameters</h3></div></div><div></div></div><p>APM has two parameters for configuring how it interacts with the UNIX
filesystem, accessible via the <a href="/admin/site-map/" target="_top">Site Map admin</a>
page. These parameters need not be changed under most circumstances, but may
need to be tweaked for Windows compatibility.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">GzipExecutableDirectory</span>
- This directory points to where the <tt>gunzip</tt> program can be found
-for uncompressing <tt>gzip</tt> archives. This is needed for the
-installation of <tt>.apm</tt> files which are simply <tt>gzip</tt>ed
-tarballs. Default is <tt>/usr/local/bin</tt>
+ This directory points to where the <tt class="computeroutput">gunzip</tt> program can be found
+for uncompressing <tt class="computeroutput">gzip</tt> archives. This is needed for the
+installation of <tt class="computeroutput">.apm</tt> files which are simply <tt class="computeroutput">gzip</tt>ed
+tarballs. Default is <tt class="computeroutput">/usr/local/bin</tt>
</p></li><li><p><span class="strong">InfoFilePermissionsMode</span>
This sets the default UNIX permissions used when creating files using the
-APM. Default is 775.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>APM has been in production since OpenACS 3.3, and as of version 4.0 offers a
+APM. Default is 775.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><div></div></div><p>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
Package Repository for automatic dependency satisfaction. When a user tries
to install a package that depends on other packages, the APM will contact the
@@ -540,6 +539,6 @@
repositories worldwide.</p><p>Another anticipated change is to split the APM UI into separate systems
for authoring, maintaining, and installing packages. The current UI presents
all of this functionality in one interface and it can be confusing from a
-usability perspective.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-authors"></a>Authors</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd
+usability perspective.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-authors"></a>Authors</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd
Nightingale.</p></li><li><p>System owner: Bryan Quinn</p></li><li><p>Documentation author: Bryan Quinn, building from earlier versions by Jon
-Salz, Michael Yoon, and Lars Pind.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-design-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/25/2000</td><td>Bryan Quinn</td></tr><tr><td>0.8</td><td>Ready for QA</td><td>9/29/2000</td><td>Bryan Quinn</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release</td><td>10/02/2000</td><td>Kai Wu</td></tr><tr><td>1.0</td><td>Edited for OpenACS 5.0.0d Beta release</td><td>03/02/2002</td><td>Roberto Mello</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 5.0.0d Package Manager Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Database Access API</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/apm-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
+Salz, Michael Yoon, and Lars Pind.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/25/2000</td><td>Bryan Quinn</td></tr><tr><td>0.8</td><td>Ready for QA</td><td>9/29/2000</td><td>Bryan Quinn</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release</td><td>10/02/2000</td><td>Kai Wu</td></tr><tr><td>1.0</td><td>Edited for OpenACS 5.0.0a1 Beta release</td><td>03/02/2002</td><td>Roberto Mello</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 5.0.0a1 Package Manager Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Database Access API</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/apm-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/apm-requirements.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 14 Oct 2003 11:02:57 -0000 1.12
@@ -1,9 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 5.0.0d Package Manager Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="subsites-design.html" title="OpenACS 4 Subsites Design Document"><link rel="next" href="apm-design.html" title="OpenACS 5.0.0d Package Manager Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="apm-requirements"></a>OpenACS 5.0.0d Package Manager Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 5.0.0a1 Package Manager Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="subsites-design.html" title="OpenACS 4 Subsites Design Document"><link rel="next" href="apm-design.html" title="OpenACS 5.0.0a1 Package Manager Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apm-requirements"></a>OpenACS 5.0.0a1 Package Manager Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a> and <a href="mailto:tnight@arsdigita.com" target="_top">Todd Nightingale</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-intro"></a>Introduction</h3></div></div><p>The following is a requirements document for the OpenACS Package Manager
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-intro"></a>Introduction</h3></div></div><div></div></div><p>The following is a requirements document for the OpenACS Package Manager
(APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality
with the following specific enhancements:</p><div class="itemizedlist"><ul type="disc"><li><p>A public procedural API. (v 3.3 only has web-based UI)</p></li><li><p>Support for dependency checking.</p></li><li><p>Support for compound packages (to support installation chaining).</p></li><li><p>Support for on-line parameter setting.</p></li><li><p>Support for sub-site level configuration (requires revised ad_parameter
and /admin pages at sub-site level; deprecation of site-wide parameter
@@ -13,7 +12,7 @@
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
-behind this document.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-vision"></a>Vision Statement</h3></div></div><p>A typical website will tend to offer its users a number of web-based
+behind this document.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>A typical website will tend to offer its users a number of web-based
services or applications, e.g. a bulletin board, calendaring, classified ads,
etc. A website may also have underlying subsystems, such as a permissions
system, content management system, etc. For such applications and subsystem
@@ -27,7 +26,7 @@
OpenACS sites.</p><p>In general terms, a package is a unit of software that serves a single
well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for
packaging, installing, and configuring OpenACS software in a consistent,
-user-friendly, and subsite-aware manner.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-system-overview"></a>System Overview</h3></div></div><p>
+user-friendly, and subsite-aware manner.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-system-overview"></a>System Overview</h3></div></div><div></div></div><p>
The OpenACS Package Manager (APM) consists of:
</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">A standard format for APM packages</span> including: </p><div class="itemizedlist"><ul type="circle"><li><p>Version numbering, independent of any other package and the OpenACS as a
whole</p></li><li><p>Specification of the package interface</p></li><li><p>Specification of dependencies on other packages (if any)</p></li><li><p>Attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div></li><li><p><span class="strong">Web-based tools for package management:</span> </p><div class="itemizedlist"><ul type="circle"><li><p>Obtaining packages from a remote distribution point</p></li><li><p>Installing packages, if and only if: </p><div class="orderedlist"><ol type="1"><li><p>All prerequisite packages are installed</p></li><li><p>No conflicts will be created by the installation</p></li></ol></div></li><li><p>Configuring packages (obsoleting the monolithic OpenACS configuration
@@ -39,7 +38,7 @@
should never break an OpenACS installation</p></li></ul></div></li><li><p><span class="strong">Web-based tools for package configuration:</span> </p><div class="itemizedlist"><ul type="circle"><li><p>The ability to change package parameter values on-line through a simple
web interface.</p></li><li><p>A new ad_parameter which does not require a monolithic site-wide
parameter's file or server restarts for changes to take effect.</p></li><li><p>The ability to manage multiple package instances at the sub-site
-level.</p></li></ul></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><p>
+level.</p></li></ul></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><div></div></div><p>
The APM is intended for the following classes of users, which may or may not
overlap: </p><div class="orderedlist"><ol type="1"><li><p><span class="strong">Developers</span> (referred to as 'the developer') use
the APM to create a software package for distribution and use the procedural
@@ -96,21 +95,21 @@
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.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/core-arch-guide/apm" target="_top">APM 3.3 Design document</a></p></li><li><p><a href="/doc/packaging" target="_top">Five minute guide to packaging a module</a></p></li><li><p><a href="/doc/core-arch-guide/subcommunities" target="_top">Sub-communities</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-data-model"></a>Requirements: Data Model</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">4.500.0 Package Identification</span>
+exhibits different behavior.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-links"></a>Related Links</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/core-arch-guide/apm" target="_top">APM 3.3 Design document</a></p></li><li><p><a href="/doc/packaging" target="_top">Five minute guide to packaging a module</a></p></li><li><p><a href="/doc/core-arch-guide/subcommunities" target="_top">Sub-communities</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-data-model"></a>Requirements: Data Model</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">4.500.0 Package Identification</span>
(All of these items are entered by the developer using the developer UI.) </p><p><span class="strong">4.500.1</span> 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."</p><p><span class="strong">4.500.5</span> A package id (primary key) that is guaranteed to
+example, "apm."</p><p><span class="strong">4.500.5</span> A package id (primary key) that is guaranteed to
be unique to the local site must be maintained by the APM. For example,
-"25."</p><p><span class="strong">4.500.10</span> A package URL that is guaranteed to be unique
+"25."</p><p><span class="strong">4.500.10</span> 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."
+example, "http://openacs.org/software."
</p></li><li><p><span class="strong">4.505.0 Version Identification</span>
(All of these items are entered by the developer using the developer UI.) </p><p><span class="strong">4.505.1</span> A version id (primary key) that is guaranteed to
be unique to the local site must be maintained by the APM.</p><p><span class="strong">4.505.5</span> 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.
-</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-api"></a>Requirements: API</h3></div></div><p>The API for APM v3 is explicitly a private API. However, it would be
+</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-api"></a>Requirements: API</h3></div></div><div></div></div><p>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.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">4.400.0 Packages Status Predicates</span> </p><p><span class="strong">4.400.1</span> Given defining information such as a package URL,
@@ -124,16 +123,16 @@
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).</p><p><span class="strong">4.415.5</span> Parameters for a given subsite and package can be
-returned by the system API.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-security"></a>Requirements: Security</h3></div></div><p>
+returned by the system API.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-security"></a>Requirements: Security</h3></div></div><div></div></div><p>
Provisions will be made to assure that packages are securely
identified.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">4.600.1</span> Each package will have a PGP signature and there
will be MD5 time stamps for each file within the package.
</p></li><li><p><span class="strong">4.600.5</span> The APM will provide a facility to validate both
-the PGP signature and MD5 stamps information before a package install.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-ui"></a>Requirements: The User Interface</h3></div></div><p>The user interface is a set of HTML pages that are used to drive the
+the PGP signature and MD5 stamps information before a package install.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-ui"></a>Requirements: The User Interface</h3></div></div><div></div></div><p>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.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-dev-interface"></a>Requirements: The Developer's Interface</h3></div></div><p>The intent of the developer's interface is to enable the developer to
+actions taken here can dramatically affect the state of the running OpenACS.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-dev-interface"></a>Requirements: The Developer's Interface</h3></div></div><div></div></div><p>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
@@ -155,7 +154,7 @@
adding new files, by scanning the file system for new files automatically,
and allowing the developer to confirm adding them.</p><p><span class="strong">20.10</span> The developer cannot add files to a given package
via the UI that do not exist in the file system already.</p><p><span class="strong">20.15</span> Package file structure must follow a specified
-convention. Please see the <a href="apm-design.html" title="OpenACS 5.0.0d Package Manager Design">design
+convention. Please see the <a href="apm-design.html" title="OpenACS 5.0.0a1 Package Manager Design">design
document</a> for what we do currently.</p></li><li><p><span class="strong">30.0 Remove files from a package</span></p><p>The developer must be able to remove files from a package. This can be
done in two ways.</p><div class="itemizedlist"><ul type="circle"><li><p><span class="strong">30.1</span> Access the APM UI, browse the file list, and remove
files.</p><p><span class="strong">30.1.1</span>If a file is removed from the package list, but not
@@ -184,7 +183,7 @@
XML specification to disk.</p><p><span class="strong">70.5</span> The developer should be able to request the current
XML specification for all installed, locally generated packages.</p></li><li><p><span class="strong">130.0 Distribution file generation</span> </p><p><span class="strong">130.1</span> The developer should be able to generate a .APM
distribution file for the package with just one click.</p><p><span class="strong">130.5</span> Generating a distribution file implies doing an
-"up-to-date" check on all of the files. If any of the files have
+"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.
@@ -197,12 +196,12 @@
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
-<tt>community-core-doc.apm</tt>. It is legal to include sub-packages with
+<tt class="computeroutput">community-core-doc.apm</tt>. 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.</p><p><span class="strong">4.200.10</span> 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.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-admin-interface"></a>Requirements: The Site-Wide Administrator's Interface</h3></div></div><p>The requirement of the administrator's interface is to enable the
+registered dependency on the sub-package.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-admin-interface"></a>Requirements: The Site-Wide Administrator's Interface</h3></div></div><div></div></div><p>The requirement of the administrator's interface is to enable the
administrator to install, enable, upgrade, disable, deinstall, and delete
packages.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">80.0 Package Enable/Disable</span> </p><p><span class="strong">4.80.1</span> The administrator should be able mark an installed
package as enabled. This means that the package is activated and its
@@ -260,15 +259,15 @@
consequences throughout a site and should almost never be done.</p></li><li><p><span class="strong">150.0 Scan for new or modified packages</span> </p><p><span class="strong">150.1</span> The administrator should be able to scan the file
system for any changes made in any of the installed package files.</p><p><span class="strong">150.5</span> The administrator should be able to scan the file
system for any newly installed packages.
-</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-sub-admin-intf"></a>Requirements: The Sub-Site Administrator's Interface</h3></div></div><p>
+</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-sub-admin-intf"></a>Requirements: The Sub-Site Administrator's Interface</h3></div></div><div></div></div><p>
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.
</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">4.300</span> Creating a package instance. </p><p><span class="strong">4.300.1</span> 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.</p><p><span class="strong">4.300.5</span> From the "add" option, the sub-admin
+option to add a package to the subsite.</p><p><span class="strong">4.300.5</span> 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.</p><p><span class="strong">4.300.19</span> Once a package instance is added, it is
available on the list of the subsite's available packages.</p></li><li><p><span class="strong">4.305</span> Configuring a package instance. </p><p><span class="strong">4.305.1</span> An automatic web interface that lists all
@@ -284,7 +283,7 @@
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.
-</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-implementation"></a>Implementation notes</h3></div></div><p>Despite the fact that requirements are meant to be design/implementation
+</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-implementation"></a>Implementation notes</h3></div></div><div></div></div><p>Despite the fact that requirements are meant to be design/implementation
neutral, the following thoughts were in our head when specifying these
requirements. You must be familiar with the new object design for this to be
comprehensible.</p><p>When a package is installed system-wide, a corresponding acs_object_type
@@ -293,4 +292,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.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/10/2000</td><td>Bryan Quinn, Todd Nightingale</td></tr><tr><td>�</td><td>Reviewed</td><td>8/11/2000</td><td>John Prevost, Mark Thomas, and Pete Su</td></tr><tr><td>0.2</td><td>Revised and updated</td><td>8/12/2000</td><td>Bryan Quinn</td></tr><tr><td>0.3</td><td>Reviewed, revised, and updated - conforms to requirements template.</td><td>8/18/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Minor edits before ACS 4 Beta.</td><td>9/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Subsites Design Document </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 5.0.0d Package Manager Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/apm-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
+these features should be quite straightforward.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/10/2000</td><td>Bryan Quinn, Todd Nightingale</td></tr><tr><td>�</td><td>Reviewed</td><td>8/11/2000</td><td>John Prevost, Mark Thomas, and Pete Su</td></tr><tr><td>0.2</td><td>Revised and updated</td><td>8/12/2000</td><td>Bryan Quinn</td></tr><tr><td>0.3</td><td>Reviewed, revised, and updated - conforms to requirements template.</td><td>8/18/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Minor edits before ACS 4 Beta.</td><td>9/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Subsites Design Document </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 5.0.0a1 Package Manager Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/apm-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/backup-recovery.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/backup-recovery.html 20 Aug 2003 16:20:16 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 14 Oct 2003 11:02:57 -0000 1.5
@@ -1,11 +1,10 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Backup and Recovery</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="previous" href="database-management.html" title="Database Management"><link rel="next" href="install-redhat.html" title="Appendix�A.�Install Red Hat 8.0"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="database-management.html">Prev</a> </td><th width="60%" align="center">Chapter�9.�Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="install-redhat.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="backup-recovery"></a>Backup and Recovery</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Backup and Recovery</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="previous" href="database-management.html" title="Database Management"><link rel="next" href="install-redhat.html" title="Appendix�A.�Install Red Hat 8.0"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="database-management.html">Prev</a> </td><th width="60%" align="center">Chapter�9.�Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="install-redhat.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backup-recovery"></a>Backup and Recovery</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:dhogaza@pacifier.com" target="_top">Don Baccus</a>
with additions by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-next-backups"></a>Backup Strategy</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-next-backups"></a>Backup Strategy</h3></div></div><div></div></div><p>
The purpose of backup is to enable recovery. Backup and
recovery are always risky; here are some steps that minimize the
chance recovery is necessary:
@@ -34,106 +33,106 @@
OpenACS installations comprise files and database contents.
If you follow the reference install and put all files,
including configuration files, in
- <tt>/web/<span class="replaceable">service0</span>/</tt>,
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/</tt>,
and back up the database nightly to a file in
- <tt>/web/<span class="replaceable">service0</span>/database-backup</tt>,
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup</tt>,
then you can apply standard file-based backup strategies to
- <tt>/web/<span class="replaceable">service0</span></tt>
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="snapshot-backup"></a>Snapshot backup and recovery</h3></div></div><p>This section describes how to make a one-time backup of
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span></tt>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="snapshot-backup"></a>Snapshot backup and recovery</h3></div></div><div></div></div><p>This section describes how to make a one-time backup of
the files and database. This is useful for rolling back to
known-good versions of a service, such as at initial
- installation and just before an upgrade.</p><div class="itemizedlist"><ul type="disc"><li><p><b>PostGreSQL.�</b>Create a backup file and verify that it was created and has a reasonable size (several megabytes).</p><pre class="screen">[root@localhost root]# <b><tt>su - service0</tt></b>
-[service0@localhost service0]$ <b><tt>pg_dump -f /web/<span class="replaceable">service0</span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>ls -al /web/<span class="replaceable">service0</span>/database-backup/before_upgrade_to_4.6.dmp </tt></b>
+ installation and just before an upgrade.</p><div class="itemizedlist"><ul type="disc"><li><p><b>PostGreSQL.�</b>Create a backup file and verify that it was created and has a reasonable size (several megabytes).</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>pg_dump -f /web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>ls -al /web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup/before_upgrade_to_4.6.dmp </tt></b>
-rw-rw-r-x 1 service0 service0 4005995 Feb 21 18:28 /web/service0/database-backup/before_upgrade_to_4.6.dmp
-[service0@localhost service0]$ <b><tt>exit</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>exit</tt></b>
[root@localhost root]#
-<pre class="action">su - service0
-pg_dump -f /web/<span class="replaceable">service0</span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable">openacs-dev</span>
-ls -al /web/<span class="replaceable">service0</span>/database-backup/before_upgrade_to_4.6.dmp
-exit</pre></pre></li><li><p><b>File tree with CVS.�</b>If you are already using CVS, you probably don't
+<pre class="action"><span class="action">su - service0
+pg_dump -f /web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable"><span class="replaceable">openacs-dev</span></span>
+ls -al /web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup/before_upgrade_to_4.6.dmp
+exit</span></pre></pre></li><li><p><b>File tree with CVS.�</b>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 - note the
current system time, down to the minute. For maximum
safety, you can apply a tag to your current
- files. Note that, if you did the CVS options in this document, the <tt>/web/service0/etc</tt> directory is not included in cvs and you may want to add it.</p><pre class="screen">[root@localhost root]# <b><tt>su - service0</tt></b>
-[service0@localhost service0]$ <b><tt>cd /web/<span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>cvs commit -m "last-minute commits before upgrade to 4.6"</tt></b>
+ files. Note that, if you did the CVS options in this document, the <tt class="computeroutput">/web/service0/etc</tt> directory is not included in cvs and you may want to add it.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>cd /web/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>cvs commit -m "last-minute commits before upgrade to 4.6"</tt></b>
cvs commit: Examining .
cvs commit: Examining bin
(many lines omitted)
-[service0@localhost service0]$ <b><tt>cvs tag before_upgrade_to_4_6</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>cvs tag before_upgrade_to_4_6</tt></b>
cvs server: Tagging bin
T bin/acs-4-0-publish.sh
T bin/ad-context-server.pl
(many lines omitted)
-[service0@localhost service0]$ <b><tt>exit</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>exit</tt></b>
[root@localhost root]#
-<pre class="action">su - service0
-cd /web/<span class="replaceable">service0</span>
-cvs commit -m "last-minute commits before upgrade to 4.6"
+<pre class="action"><span class="action">su - service0
+cd /web/<span class="replaceable"><span class="replaceable">service0</span></span>
+cvs commit -m "last-minute commits before upgrade to 4.6"
cvs tag before_upgrade_to_4_6
-exit</pre></pre><p>To restore files from a cvs tag such as the one used above:</p><pre class="screen">[root@localhost root]# <b><tt>su - service0</tt></b>
-[service0@localhost service0]$ <b><tt>cd /web/<span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>cvs up -r current</tt></b>
-[service0@localhost service0]$ <b><tt>exit</tt></b>
-<pre class="action"><b><tt>su - service0</tt></b>
-cd /web/<span class="replaceable">service0</span>
-cvs up -r current</pre></pre></li><li><p><b>File tree without CVS.�</b>If you don't use cvs, you may want to back up the working directory. The simplest way is just to copy it.</p><pre class="screen">[root@localhost root]# <b><tt>su - service0</tt></b>
-[service0@localhost service0]$ <b><tt>cp -r /web/<span class="replaceable">service0</span> /web/<span class="replaceable">service0</span>-before-upgrade-to-4.6</tt></b>
-[service0@localhost service0]$ <b><tt>exit</tt></b>
+exit</span></pre></pre><p>To restore files from a cvs tag such as the one used above:</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>cd /web/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>cvs up -r current</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>exit</tt></b>
+<pre class="action"><span class="action"><b class="userinput"><tt>su - service0</tt></b>
+cd /web/<span class="replaceable"><span class="replaceable">service0</span></span>
+cvs up -r current</span></pre></pre></li><li><p><b>File tree without CVS.�</b>If you don't use cvs, you may want to back up the working directory. The simplest way is just to copy it.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>cp -r /web/<span class="replaceable"><span class="replaceable">service0</span></span> /web/<span class="replaceable"><span class="replaceable">service0</span></span>-before-upgrade-to-4.6</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>exit</tt></b>
[root@localhost root]#
-<pre class="action">su - service0
-cp -r /web/<span class="replaceable">service0</span> /web/<span class="replaceable">service0</span>-before-upgrade-to-4.6
-exit</pre></pre><p>To restore the files, copy the directory back (do this while the service is stopped):</p><pre class="screen">[root@localhost root]# <b><tt>su - service0</tt></b>
-[service0@localhost service0]$<b><tt> mv /web/<span class="replaceable">service0</span> /web/openacs-failed-upgrade</tt></b>
-[service0@localhost service0]$<b><tt> mv /web/<span class="replaceable">service0</span>-before-upgrade-to-4.6 /web/<span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>exit</tt></b>
-[root@localhost root]#</pre></li><li><p><a name="rollback-database"></a><b>Database Rollback.�</b>Restore the database to its backed-up state.</p><pre class="screen">[root@localhost root]# <b><tt>su - service0</tt></b>
-[service0@localhost service0]$ <b><tt>svc -d /service/<span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>dropdb <span class="replaceable">service0</span></tt></b>
+<pre class="action"><span class="action">su - service0
+cp -r /web/<span class="replaceable"><span class="replaceable">service0</span></span> /web/<span class="replaceable"><span class="replaceable">service0</span></span>-before-upgrade-to-4.6
+exit</span></pre></pre><p>To restore the files, copy the directory back (do this while the service is stopped):</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@localhost service0]$<b class="userinput"><tt> mv /web/<span class="replaceable"><span class="replaceable">service0</span></span> /web/openacs-failed-upgrade</tt></b>
+[service0@localhost service0]$<b class="userinput"><tt> mv /web/<span class="replaceable"><span class="replaceable">service0</span></span>-before-upgrade-to-4.6 /web/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>exit</tt></b>
+[root@localhost root]#</pre></li><li><p><a name="rollback-database"></a><b>Database Rollback.�</b>Restore the database to its backed-up state.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>svc -d /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>dropdb <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
DROP DATABASE
-[service0@localhost service0]$ <b><tt>createdb <span class="replaceable">service0</span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>createdb <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
CREATE DATABASE
</pre><p>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 href="http://openacs.org/forums/message-view?message_id=70759" target="_top">forum thread</a> has more information.</p><pre class="screen">[service0@localhost service0]$ <b><tt>psql -f /web/<span class="replaceable">service0</span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>psql <span class="replaceable">service0</span> < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp</tt></b>
-[service0@localhost service0]$ <b><tt>svc -u /service/<span class="replaceable">service0</span></tt></b>
-[service0@localhost service0]$ <b><tt>exit</tt></b></pre><pre class="screen">All commands for a database rollback:
-<pre class="action">su - service0
-svc -d /service/<span class="replaceable">service0</span>
-dropdb <span class="replaceable">service0</span>
-createdb <span class="replaceable">service0</span>
-psql -f /web/<span class="replaceable">service0</span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable">service0</span>
-psql <span class="replaceable">service0</span> < /web/<span class="replaceable">service0</span>/database-backup/before_upgrade_to_4.6.dmp
-svc -u /service/<span class="replaceable">service0</span>
-exit</pre></pre></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="backup-file-system"></a>Back up the file system</h3></div></div><p>Here's a quick manual way to back up a reference install -
+You will see a number of "already exists" errors when you run the
+database restore; these can be ignored. This <a href="http://openacs.org/forums/message-view?message_id=70759" target="_top">forum thread</a> has more information.</p><pre class="screen">[service0@localhost service0]$ <b class="userinput"><tt>psql -f /web/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>psql <span class="replaceable"><span class="replaceable">service0</span></span> < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp</tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>svc -u /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@localhost service0]$ <b class="userinput"><tt>exit</tt></b></pre><pre class="screen">All commands for a database rollback:
+<pre class="action"><span class="action">su - service0
+svc -d /service/<span class="replaceable"><span class="replaceable">service0</span></span>
+dropdb <span class="replaceable"><span class="replaceable">service0</span></span>
+createdb <span class="replaceable"><span class="replaceable">service0</span></span>
+psql -f /web/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable"><span class="replaceable">service0</span></span>
+psql <span class="replaceable"><span class="replaceable">service0</span></span> < /web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup/before_upgrade_to_4.6.dmp
+svc -u /service/<span class="replaceable"><span class="replaceable">service0</span></span>
+exit</span></pre></pre></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="backup-file-system"></a>Back up the file system</h3></div></div><div></div></div><p>Here's a quick manual way to back up a reference install -
it should be replaced by an automated script within
OpenACS. The command excludes the auto-generated
- <tt>supervise</tt> directory, which is
+ <tt class="computeroutput">supervise</tt> directory, which is
unneccesary and has complicated permissions. Make sure that you
are using the cron job to back up the database to a file in
- <tt>/web/<span class="replaceable">service0</span>/database-backup</tt>
- so that the tar command will include the database.</p><p>In the tar command,</p><div class="itemizedlist"><ul type="disc"><li><p><tt>c</tt> create a
- new tar archive</p></li><li><p><tt>p</tt> preserves permissions.</p></li><li><p><tt>s</tt> preserves file sort order</p></li><li><p><tt>j</tt> compresses the output with bz2.</p></li><li><p>The <tt>--exclude</tt> clauses skips some daemontools files that
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup</tt>
+ so that the tar command will include the database.</p><p>In the tar command,</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput">c</tt> create a
+ new tar archive</p></li><li><p><tt class="computeroutput">p</tt> preserves permissions.</p></li><li><p><tt class="computeroutput">s</tt> preserves file sort order</p></li><li><p><tt class="computeroutput">j</tt> compresses the output with bz2.</p></li><li><p>The <tt class="computeroutput">--exclude</tt> clauses skips some daemontools files that
are owned by root and thus cannot be backed up by the
service owner. These files are autogenerated and we don't
- break anything by omitting them.</p></li><li><p>The <tt>--file</tt> clause
+ break anything by omitting them.</p></li><li><p>The <tt class="computeroutput">--file</tt> clause
specifies the name of the output file to be generated; we
manually add the correct extensions.</p></li><li><p>The last clause,
- <tt>/web/<span class="replaceable">service0</span>/</tt>,
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/</tt>,
specifies the starting point for backup. Tar defaults to
- recursive backup.</p></li></ul></div><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>tar -cpsj --exclude /web/<span class="replaceable">service0</span>/etc/daemontools/supervise --file /tmp/<span class="replaceable">service0</span>-backup.tar.bz2 /web/<span class="replaceable">service0</span>/ </tt></b>
+ recursive backup.</p></li></ul></div><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>tar -cpsj --exclude /web/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/daemontools/supervise --file /tmp/<span class="replaceable"><span class="replaceable">service0</span></span>-backup.tar.bz2 /web/<span class="replaceable"><span class="replaceable">service0</span></span>/ </tt></b>
tar: Removing leading `/' from member names
-[service0@yourserver service0]$</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="automated-backup"></a>Automated Backup (OPTIONAL)</h3></div></div><p>Backup can encompass all files in
- <tt>/web/service0</tt>. For a development
- server, putting the files in cvs, and backing up the database nightly, is sufficient. (It's important then to back up the cvs repository!)</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="postgres-quick-backup"></a>Postgres automatic backup</h4></div></div><p>Backing up the database consists of creating a file
+[service0@yourserver service0]$</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="automated-backup"></a>Automated Backup (OPTIONAL)</h3></div></div><div></div></div><p>Backup can encompass all files in
+ <tt class="computeroutput">/web/service0</tt>. For a development
+ server, putting the files in cvs, and backing up the database nightly, is sufficient. (It's important then to back up the cvs repository!)</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="postgres-quick-backup"></a>Postgres automatic backup</h4></div></div><div></div></div><p>Backing up the database consists of creating a file
which is a picture of the database at a particular moment.
Postgres can be backed up while running. A quick way to automate database backup is a cron job. This
is not recommended for production and is not part of the Reference
@@ -144,60 +143,60 @@
single nightly backup file which is then collected into a
bigger backup file that includes the other parts of the
service (web pages, content, code). To make a new file every
- night, edit the crontab file for <span class="replaceable">service0</span>:</p><pre class="screen">[service0@yourserver service0]$ <b><tt>export EDITOR=emacs;crontab -e</tt></b></pre><p>Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.</p><pre class="programlisting">0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0</pre><p>If you plan to back up the whole <tt>/web/<span class="replaceable">service0</span></tt> directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:</p><pre class="programlisting">0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2996823"></a>A full Backup/Recovery cycle</h3></div></div><p><span class="emphasis"><em>On a test service</em></span>, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2996840"></a>Delete the Service</h4></div></div><pre class="screen">[root@yourserver root]# <b><tt>svc -d /service/service0</tt></b>
-[root@yourserver root]# <b><tt>mv /web/service0/ /web/service0.lost</tt></b>
-[root@yourserver root]#<b><tt> rm /service/service0</tt></b>
+ night, edit the crontab file for <span class="replaceable"><span class="replaceable">service0</span></span>:</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>export EDITOR=emacs;crontab -e</tt></b></pre><p>Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.</p><pre class="programlisting">0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0</pre><p>If you plan to back up the whole <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span></tt> directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:</p><pre class="programlisting">0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2833898"></a>A full Backup/Recovery cycle</h3></div></div><div></div></div><p><span class="emphasis"><em>On a test service</em></span>, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2833915"></a>Delete the Service</h4></div></div><div></div></div><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>svc -d /service/service0</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>mv /web/service0/ /web/service0.lost</tt></b>
+[root@yourserver root]#<b class="userinput"><tt> rm /service/service0</tt></b>
rm: remove symbolic link `/service/service0'? y
-[root@yourserver root]# <b><tt>ps -auxw | grep service0</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>ps -auxw | grep service0</tt></b>
root 1496 0.0 0.0 1312 252 ? S 16:58 0:00 supervise service0
-[root@yourserver root]#<b><tt> kill<span class="replaceable"> 1496</span></tt></b>
-[root@yourserver root]# <b><tt>ps -auxw | grep service0</tt></b>
-[root@yourserver root]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>dropdb service0</tt></b>
+[root@yourserver root]#<b class="userinput"><tt> kill<span class="replaceable"><span class="replaceable"> 1496</span></span></tt></b>
+[root@yourserver root]# <b class="userinput"><tt>ps -auxw | grep service0</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>su - postgres</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>dropdb service0</tt></b>
DROP DATABASE
-[postgres@yourserver pgsql]$ <b><tt>dropuser service0</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>dropuser service0</tt></b>
DROP USER
-[postgres@yourserver pgsql]$ <b><tt>exit</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver root]#</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Recovery"></a>Recovery</h4></div></div><div class="orderedlist"><ol type="1"><li><p>Restore the operating system and required software.
+[root@yourserver root]#</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Recovery"></a>Recovery</h4></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p>Restore the operating system and required software.
You can do this with standard backup processes or by
keeping copies of the install material (OS CDs, OpenACS
- tarball and supporting software) and repeating the install guide.</p></li><li><p>Restore the OpenACS service. Assuming the user already exists, restore the database and files from backup and restore the daemontools link. (Because of a bug in Postgres backup-recovery, not all database objects are created in the correct order. To compensate, pre-creating some objects usually work.)</p><pre class="screen">[root@yourserver root]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>createuser <span class="replaceable">service0</span></tt></b>
-Shall the new user be allowed to create databases? (y/n) <b><tt>y</tt></b>
-Shall the new user be allowed to create more new users? (y/n) <b><tt>y</tt></b>
+ tarball and supporting software) and repeating the install guide.</p></li><li><p>Restore the OpenACS service. Assuming the user already exists, restore the database and files from backup and restore the daemontools link. (Because of a bug in Postgres backup-recovery, not all database objects are created in the correct order. To compensate, pre-creating some objects usually work.)</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - postgres</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>createuser <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+Shall the new user be allowed to create databases? (y/n) <b class="userinput"><tt>y</tt></b>
+Shall the new user be allowed to create more new users? (y/n) <b class="userinput"><tt>y</tt></b>
CREATE USER
-[postgres@yourserver pgsql]$ <b><tt>exit</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>cd /web</tt></b>
-[service0@yourserver web]$<b><tt> tar xjf /tmp/service0-backup.tar.bz2</tt></b>
-[service0@yourserver web]$ <b><tt>chmod -R 700 service0</tt></b>
-[service0@yourserver web]$ <b><tt>createdb <span class="replaceable">service0</span></tt></b>
+[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cd /web</tt></b>
+[service0@yourserver web]$<b class="userinput"><tt> tar xjf /tmp/service0-backup.tar.bz2</tt></b>
+[service0@yourserver web]$ <b class="userinput"><tt>chmod -R 700 service0</tt></b>
+[service0@yourserver web]$ <b class="userinput"><tt>createdb <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
CREATE DATABASE
-[service0@yourserver web]$<b><tt> psql -f /web/<span class="replaceable">service0</span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable">service0</span></tt></b>
+[service0@yourserver web]$<b class="userinput"><tt> psql -f /web/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
<span class="emphasis"><em>(many lines omitted)</em></span>
-[service0@yourserver web]$ <b><tt>psql <span class="replaceable">service0</span> < /web/<span class="replaceable">service0</span>/database-backup/<span class="replaceable">database-backup.dmp</span></tt></b>
+[service0@yourserver web]$ <b class="userinput"><tt>psql <span class="replaceable"><span class="replaceable">service0</span></span> < /web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup/<span class="replaceable"><span class="replaceable">database-backup.dmp</span></span></tt></b>
<span class="emphasis"><em>(many lines omitted)</em></span>
-[service0@yourserver web]$ <b><tt>exit</tt></b>
-[root@yourserver root]# <b><tt>ln -s /web/<span class="replaceable">service0</span>/etc/daemontools /service/<span class="replaceable">service0</span></tt></b>
-[root@yourserver root]# <b><tt>sleep 10</tt></b>
-[root@yourserver root]# <b><tt>svgroup web /service/<span class="replaceable">service0</span></tt></b>
-[root@yourserver root]#</pre></li></ol></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="other-backup-strategies"></a>Other Backup Strategies</h3></div></div><p>Earlier strategies, included here because this section
- hasn't been fully updated yet.</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="install-export-oracle"></a>Set Up Nightly Oracle Exports</h4></div></div><p>
+[service0@yourserver web]$ <b class="userinput"><tt>exit</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>ln -s /web/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/daemontools /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[root@yourserver root]# <b class="userinput"><tt>sleep 10</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>svgroup web /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[root@yourserver root]#</pre></li></ol></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="other-backup-strategies"></a>Other Backup Strategies</h3></div></div><div></div></div><p>Earlier strategies, included here because this section
+ hasn't been fully updated yet.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="install-export-oracle"></a>Set Up Nightly Oracle Exports</h4></div></div><div></div></div><p>
(This has not yet been updated to fit with the Reference
install. To do so, edit the backup script to save the backup
- file in <tt>/web/<span class="replaceable">service0</span>/database-backup</tt>).
+ file in <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup</tt>).
While you're working with Oracle, you should configure it to do
automatic exports. An export is a separate backup copy of the
database. This copy includes all of the database's state at the
time that the export was initiated. If your database is corrupted,
you can restore from one of these backups. You should do this step as
- <tt>root</tt>.
+ <tt class="computeroutput">root</tt>.
</p><div class="itemizedlist"><ul type="disc"><li><p>
Download the backup script. Save the file <a href="files/export-oracle.txt" target="_top">export-oracle.txt</a> as
- <tt>/tmp/export-oracle.txt</tt>
+ <tt class="computeroutput">/tmp/export-oracle.txt</tt>
</p></li><li><p>
Login as root. The following commands will install the export script:
</p><pre class="programlisting">
@@ -207,18 +206,18 @@
root:~# chmod 700 /usr/sbin/export-oracle</pre></li><li><p>
Setup the export directory; this is the directory where backups will
be stored. We recommend the directory
- <tt>/ora8/m02/oracle-exports</tt>.</p><pre class="programlisting">
+ <tt class="computeroutput">/ora8/m02/oracle-exports</tt>.</p><pre class="programlisting">
root:~# mkdir /ora8/m02/oracle-exports
root:~# chown oracle.dba /ora8/m02/oracle-exports
root:~# chmod 770 /ora8/m02/oracle-exports</pre></li><li><p>
Now edit
- <tt>/usr/sbin/export-oracle</tt> and
- change the <tt>SERVICE_NAME</tt> and
- <tt>DATABASE_PASSWORD</tt> fields to
+ <tt class="computeroutput">/usr/sbin/export-oracle</tt> and
+ change the <tt class="computeroutput">SERVICE_NAME</tt> and
+ <tt class="computeroutput">DATABASE_PASSWORD</tt> fields to
their correct values. If you want to use a directory other than
- <tt>/ora8/m02/oracle-exports</tt>, you
+ <tt class="computeroutput">/ora8/m02/oracle-exports</tt>, you
also need to change the
- <tt>exportdir</tt> setting.
+ <tt class="computeroutput">exportdir</tt> setting.
</p><p>
Test the export procedure by running the command:
</p><pre class="programlisting">
@@ -261,46 +260,46 @@
Export terminated successfully without warnings.</pre><p>If you don't have any warnings, proceed to automate the
backups.</p></li><li><p>
Automating backups is accomplished using the UNIX
- <tt>crontab</tt> facility.</p><p>
- While still <tt>root</tt>, run the
+ <tt class="computeroutput">crontab</tt> facility.</p><p>
+ While still <tt class="computeroutput">root</tt>, run the
following command. You can replace the
- <tt>EDITOR="emacs -nw"</tt>
+ <tt class="computeroutput">EDITOR="emacs -nw"</tt>
portion with whatever editor your prefer, such as
- <tt>EDITOR=vi</tt>.
+ <tt class="computeroutput">EDITOR=vi</tt>.
</p><pre class="programlisting">
-root:~# export EDITOR="emacs -nw"
+root:~# export EDITOR="emacs -nw"
root:~# crontab -e</pre><p>Now add the following line on a line by itself </p><pre class="programlisting">
0 23 * * * /usr/sbin/export-oracle</pre><p>
Save the file, exit the editor. Verify that the addition
succeeded by checking the output of the following command.</p><pre class="programlisting">
root:~# crontab -l | grep export-oracle
0 23 * * * /usr/sbin/export-oracle
root:~# exit
-; Logout</pre><p>If you see the line, go ahead and log out.</p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="install-export-postgres"></a>Set up nightly Postgres exports</h4></div></div><p>This is an alternate method to the crontab backup.
+; Logout</pre><p>If you see the line, go ahead and log out.</p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="install-export-postgres"></a>Set up nightly Postgres exports</h4></div></div><div></div></div><p>This is an alternate method to the crontab backup.
Dowload <a href="files/acs-pgbackup-init.txt" target="_top">this script</a>
- to <tt>/tmp</tt>. At the top of the script
+ to <tt class="computeroutput">/tmp</tt>. At the top of the script
are several variables that you'll need to customize:
</p><div class="itemizedlist"><ul type="disc"><li><p>
- <tt>bak</tt> - location where you want
+ <tt class="computeroutput">bak</tt> - location where you want
local backups to be saved
</p></li><li><p>
- <tt>servername</tt> - name of your server
+ <tt class="computeroutput">servername</tt> - name of your server
(and database instance)
</p></li><li><p>
- <tt>ftp_user</tt> - username on your ftp
+ <tt class="computeroutput">ftp_user</tt> - username on your ftp
account
</p></li><li><p>
- <tt>ftp_password</tt> - password on your
+ <tt class="computeroutput">ftp_password</tt> - password on your
ftp account
</p></li><li><p>
- <tt>ftp_dir</tt> - path on the remote
+ <tt class="computeroutput">ftp_dir</tt> - path on the remote
server where your backups will be uploaded
</p></li><li><p>
- <tt>ftp_server</tt> - your ftp server
+ <tt class="computeroutput">ftp_server</tt> - your ftp server
</p></li></ul></div><p>
Next, we'll save this file to our server's
- <tt>tcl</tt> directory so that it will be
+ <tt class="computeroutput">tcl</tt> directory so that it will be
loaded on startup. It will automatically be run every night at
midnight. Note that this script only backs up the database - not the
OpenACS scripts and file content.
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 -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 14 Oct 2003 11:02:57 -0000 1.13
@@ -1,90 +1,89 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Bootstrapping OpenACS</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="next" href="ext-auth-requirements.html" title="External Authentication Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Bootstrapping OpenACS</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="next" href="ext-auth-requirements.html" title="External Authentication Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</p></li></ul></div><p>This document describes the startup (bootstrapping) process for an AOLserver
running OpenACS.
-</p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="bootstrap-acs-bigpicture"></a>The Big Picture</h3></div></div><p>
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bootstrap-acs-bigpicture"></a>The Big Picture</h3></div></div><div></div></div><p>
Before OpenACS 3.3, the OpenACS startup process was extremely simple: after AOLserver
performed its internal initialization (reading the configuration file,
loading shared libraries and module code, etc.) it scanned through the Tcl
-library directory (generally <tt>/web/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span><tt>/tcl</tt>),
+library directory (generally <tt class="computeroutput">/web/</tt><span class="emphasis"><em><tt class="computeroutput">yourservername</tt></em></span><tt class="computeroutput">/tcl</tt>),
sourcing each file in sequence.
</p><p>While this overall structure for initialization is still intact, package
management has thrown a wrench into the works - there are a few extra things
to do during initialization, most notably:</p><div class="itemizedlist"><ul type="disc"><li><p>Examine the OpenACS file tree for files that should not be present in OpenACS
(i.e., that were once part of the OpenACS distribution but have since been
-removed).</p></li><li><p>Scan the <tt>/packages</tt> directory for new packages.</p></li><li><p>Initialize enabled packages by sourcing their <tt>*-procs.tcl</tt>
-and <tt>*-init.tcl</tt> files.</p></li></ul></div><p>
+removed).</p></li><li><p>Scan the <tt class="computeroutput">/packages</tt> directory for new packages.</p></li><li><p>Initialize enabled packages by sourcing their <tt class="computeroutput">*-procs.tcl</tt>
+and <tt class="computeroutput">*-init.tcl</tt> files.</p></li></ul></div><p>
This document examines in detail each of the steps involved in AOLserver/OpenACS
startup.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="bootstrap-acs-startup-process"></a>The Startup Process</h3></div></div><p>
-As soon as the <tt>nsd</tt> daemon is executed by the <tt>init</tt>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bootstrap-acs-startup-process"></a>The Startup Process</h3></div></div><div></div></div><p>
+As soon as the <tt class="computeroutput">nsd</tt> daemon is executed by the <tt class="computeroutput">init</tt>
process (or otherwise), AOLserver reads its configuration file and
-<tt>chroot</tt>s itself if necessary. It then loads shared libraries
-indicated in the <tt>.ini</tt> file (e.g., the Oracle driver and
-<tt>nssock</tt>), and sources Tcl module files (generally in
-<tt>/home/aol30/modules/tcl</tt>). This step is, and has always been, the
+<tt class="computeroutput">chroot</tt>s itself if necessary. It then loads shared libraries
+indicated in the <tt class="computeroutput">.ini</tt> file (e.g., the Oracle driver and
+<tt class="computeroutput">nssock</tt>), and sources Tcl module files (generally in
+<tt class="computeroutput">/home/aol30/modules/tcl</tt>). This step is, and has always been, the
same for all AOLservers, regardless of whether they are running OpenACS.
</p><p>Next AOLserver sources, in lexicographical order, each file in the
-<tt>/tcl</tt> directory. The first such file is
-<tt>0-acs-init.tcl</tt>, which doesn't do much directly except to
-determine the OpenACS path root (e.g., <tt>/web/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span>)
+<tt class="computeroutput">/tcl</tt> directory. The first such file is
+<tt class="computeroutput">0-acs-init.tcl</tt>, which doesn't do much directly except to
+determine the OpenACS path root (e.g., <tt class="computeroutput">/web/</tt><span class="emphasis"><em><tt class="computeroutput">yourservername</tt></em></span>)
by trimming the final component from the path to the Tcl library directory
-(<tt>/web/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span><tt>/tcl</tt>). But
-<tt>0-acs-init.tcl</tt>'s has an important function, namely sourcing
-<tt>/packages/acs-core/bootstrap.tcl</tt>, which does the following:</p><div class="orderedlist"><ol type="1"><li><p><span class="strong">Initialize some NSVs used by the core</span>. These NSVs are
-documented in <tt>/packages/acs-core/apm-procs.tcl</tt> - no need to
+(<tt class="computeroutput">/web/</tt><span class="emphasis"><em><tt class="computeroutput">yourservername</tt></em></span><tt class="computeroutput">/tcl</tt>). But
+<tt class="computeroutput">0-acs-init.tcl</tt>'s has an important function, namely sourcing
+<tt class="computeroutput">/packages/acs-core/bootstrap.tcl</tt>, which does the following:</p><div class="orderedlist"><ol type="1"><li><p><span class="strong">Initialize some NSVs used by the core</span>. These NSVs are
+documented in <tt class="computeroutput">/packages/acs-core/apm-procs.tcl</tt> - no need to
worry about them unless you're an OpenACS core hacker.
</p></li><li><p><span class="strong">Verify the deletion of obsolete OpenACS files</span>. The
-<tt>/tcl</tt> directory has evolved quite a bit over the months and
+<tt class="computeroutput">/tcl</tt> directory has evolved quite a bit over the months and
years, and a few files have come and gone. The
-<tt>/www/doc/removed-files.txt</tt> file contains a list of files which
+<tt class="computeroutput">/www/doc/removed-files.txt</tt> file contains a list of files which
<span class="emphasis"><em>must be deleted</em></span> from the AOLserver installation, at the risk of
causing weird conflicts, e.g., having several security filters registered.
-<tt>bootstrap.tcl</tt> scans through this list, logging error messages to
+<tt class="computeroutput">bootstrap.tcl</tt> scans through this list, logging error messages to
the log if any of these files exist.
-</p></li><li><p><span class="strong">Source <tt>*-procs.tcl</tt> files in the OpenACS core</span>.
-We source each file matching the <tt>*-procs.tcl</tt> glob in the
-<tt>/packages/acs-kernel</tt> directory, in lexicographical order. These
+</p></li><li><p><span class="strong">Source <tt class="computeroutput">*-procs.tcl</tt> files in the OpenACS core</span>.
+We source each file matching the <tt class="computeroutput">*-procs.tcl</tt> glob in the
+<tt class="computeroutput">/packages/acs-kernel</tt> directory, in lexicographical order. These
procedure are needed to perform any of the following steps.
</p></li><li><p><span class="strong">Ensure that the database is available</span> by grabbing and
releasing a handle. If we can't obtain a handle, we terminate
initialization (since OpenACS couldn't possibly start up the server without
access to the database).
-</p></li><li><p><span class="strong">Register any new packages in the <tt>/packages</tt>
-directory</span>. In each directory inside <tt>/packages</tt>, we look
-for a <tt>.info</tt> file; if we find a package that hasn't yet been
+</p></li><li><p><span class="strong">Register any new packages in the <tt class="computeroutput">/packages</tt>
+directory</span>. In each directory inside <tt class="computeroutput">/packages</tt>, we look
+for a <tt class="computeroutput">.info</tt> file; if we find a package that hasn't yet been
registered with the package manager (i.e., it's been copied there
manually), we insert information about it into the database. (The first time
OpenACS starts up, <span class="emphasis"><em>no</em></span> packages will have been registered in the database
yet, so this step will registers every single package in the
-<tt>/packages</tt> directory.) Note that packages discovered here are
+<tt class="computeroutput">/packages</tt> directory.) Note that packages discovered here are
initially disabled; they must be manually enabled in the package manager
before they can be used.
-</p></li><li><p><span class="strong">Ensure that the <tt>acs-kernel</tt> package is
+</p></li><li><p><span class="strong">Ensure that the <tt class="computeroutput">acs-kernel</tt> package is
enabled</span>. If the OpenACS core isn't initialized, the server
couldn't possibly be operational, so if there's no enabled version of
the OpenACS core we simply mark the latest installed one as enabled.
-</p></li><li><p><span class="strong">Load <tt>*-procs.tcl</tt> files for enabled
+</p></li><li><p><span class="strong">Load <tt class="computeroutput">*-procs.tcl</tt> files for enabled
packages</span>, activating their APIs.
-</p></li><li><p><span class="strong">Load <tt>*-init.tcl</tt> files for enabled packages</span>,
+</p></li><li><p><span class="strong">Load <tt class="computeroutput">*-init.tcl</tt> files for enabled packages</span>,
giving packages a chance to register filters and procedures, initialize data
structures, etc.
</p></li><li><p><span class="strong">Verify that the core has been properly initialized</span> by
checking for the existence of an NSV created by the request processor
initialization code. If it's not present, the server won't be
operational, so we log an error.</p></li></ol></div><p>
-At this point, <tt>bootstrap.tcl</tt> is done executing. AOLserver
-proceeds to source the remaining files in the <tt>/tcl</tt> directory
+At this point, <tt class="computeroutput">bootstrap.tcl</tt> is done executing. AOLserver
+proceeds to source the remaining files in the <tt class="computeroutput">/tcl</tt> directory
(i.e., unpackaged libraries) and begins listening for connections.
</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Documenting Tcl Files: Page Contracts and Libraries </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> External Authentication Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/bootstrap-acs.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/compatibility-matrix.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/compatibility-matrix.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/compatibility-matrix.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/compatibility-matrix.html 14 Oct 2003 11:02:57 -0000 1.4
@@ -1,6 +1,5 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Compatibility Matrix</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="previous" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="next" href="individual-programs.html" title="Individual Programs"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="software-versions.html">Prev</a> </td><th width="60%" align="center">Chapter�3.�Prerequisite Software</th><td width="20%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="compatibility-matrix"></a>Compatibility Matrix</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Compatibility Matrix</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="previous" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="next" href="individual-programs.html" title="Individual Programs"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="software-versions.html">Prev</a> </td><th width="60%" align="center">Chapter�3.�Prerequisite Software</th><td width="20%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="compatibility-matrix"></a>Compatibility Matrix</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="figure"><a name="id2953962"></a><p class="title"><b>Figure�3.1.�Compatibility Matrix</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col><col><col><col><col></colgroup><tbody><tr><td colspan="2" align="center">OpenACS Version</td><td>3.2.5</td><td>4.5</td><td>4.6</td><td>4.6.1</td><td>4.6.2</td><td>4.6.3</td></tr><tr><td rowspan="3">AolServer</td><td>3</td><td align="center">Verified</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td></tr><tr><td>3.3+ad13</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>3.3oacs1</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td colspan="2" align="center">Verified</td></tr><tr><td rowspan="3">PostGreSQL</td><td>7.0</td><td align="center">Verified</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td></tr><tr><td>7.2.x</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>7.3.2</td><td colspan="5" align="center">Not compatible</td><td align="center">Untested</td></tr><tr><td rowspan="3">Oracle</td><td>8.1.6</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>8.1.7</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>9i</td><td colspan="6" align="center">No</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="software-versions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�3.�Prerequisite Software </td><td width="20%" align="center"><a accesskey="u" href="software-versions.html">Up</a></td><td width="40%" align="right"> Individual Programs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/compatibility-matrix.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></div><div class="figure"><a name="id2815303"></a><p class="title"><b>Figure�3.1.�Compatibility Matrix</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col><col><col><col><col></colgroup><tbody><tr><td colspan="2" align="center">OpenACS Version</td><td>3.2.5</td><td>4.5</td><td>4.6</td><td>4.6.1</td><td>4.6.2</td><td>4.6.3</td></tr><tr><td rowspan="3">AolServer</td><td>3</td><td align="center">Verified</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td></tr><tr><td>3.3+ad13</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>3.3oacs1</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td colspan="2" align="center">Verified</td></tr><tr><td rowspan="3">PostGreSQL</td><td>7.0</td><td align="center">Verified</td><td class="auto-generated">�</td><td class="auto-generated">�</td><td class="auto-generated">�</td></tr><tr><td>7.2.x</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>7.3.2</td><td colspan="5" align="center">Not compatible</td><td align="center">Untested</td></tr><tr><td rowspan="3">Oracle</td><td>8.1.6</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>8.1.7</td><td class="auto-generated">�</td><td colspan="5" align="center">Verified</td></tr><tr><td>9i</td><td colspan="6" align="center">No</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="software-versions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�3.�Prerequisite Software </td><td width="20%" align="center"><a accesskey="u" href="software-versions.html">Up</a></td><td width="40%" align="right"> Individual Programs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/compatibility-matrix.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/configure.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/configure.html,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/configure.html 28 Jun 2003 05:07:01 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/configure.html 14 Oct 2003 11:02:57 -0000 1.3
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�7.�Configuring a New Service</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"><link rel="next" href="upgrade.html" title="Chapter�8.�Upgrading"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="configure"></a>Chapter�7.�Configuring a New Service</h2></div></div><p>Placeholder</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Mac OS X </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Chapter�8.�Upgrading</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/configure.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�7.�Configuring a New Service</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"><link rel="next" href="upgrade.html" title="Chapter�8.�Upgrading"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="configure"></a>Chapter�7.�Configuring a New Service</h2></div></div><div></div></div><p>Placeholder</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Mac OS X </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Chapter�8.�Upgrading</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/configure.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/credits.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/credits.html 14 Oct 2003 11:02:57 -0000 1.13
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Credits</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="openacs.html" title="Install OpenACS 5.0.0d"><link rel="next" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="win-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="credits"></a>Credits</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Credits</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="openacs.html" title="Install OpenACS 5.0.0a1"><link rel="next" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="win-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="credits"></a>Credits</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -34,4 +33,4 @@
</p><p>
<span class="strong">All questions and comments</span> regarding
this guide should be posted on the <a href="http://openacs.org/bboard" target="_top">OpenACS bboards</a>.
- </p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win-install.html">Next</a></td></tr><tr><td width="40%" align="left">Install OpenACS 5.0.0d </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Chapter�5.�Installing on Windows</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/credits.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win-install.html">Next</a></td></tr><tr><td width="40%" align="left">Install OpenACS 5.0.0a1 </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Chapter�5.�Installing on Windows</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/credits.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/cvs-service-import.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/cvs-service-import.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/cvs-service-import.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/cvs-service-import.html 14 Oct 2003 11:02:57 -0000 1.4
@@ -1,51 +1,50 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Add the Service to CVS - OPTIONAL</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="cvs-tips.html" title="Appendix�C.�Using CVS with an OpenACS Site"><link rel="previous" href="cvs-tips.html" title="Appendix�C.�Using CVS with an OpenACS Site"><link rel="next" href="acs-plat-dev.html" title="Part�IV.�For OpenACS Platform Developers"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><th width="60%" align="center">Appendix�C.�Using CVS with an OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="cvs-service-import"></a>Add the Service to CVS - OPTIONAL</h2></div></div><a class="indexterm" name="id2956607"></a><p>These steps take an existing OpenACS directory and add
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Add the Service to CVS - OPTIONAL</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="cvs-tips.html" title="Appendix�A.�Using CVS with an OpenACS Site"><link rel="previous" href="cvs-tips.html" title="Appendix�A.�Using CVS with an OpenACS Site"><link rel="next" href="acs-plat-dev.html" title="Part�IV.�For OpenACS Platform Developers"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><th width="60%" align="center">Appendix�A.�Using CVS with an OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cvs-service-import"></a>Add the Service to CVS - OPTIONAL</h2></div></div><div></div></div><a class="indexterm" name="id2860849"></a><p>These steps take an existing OpenACS directory and add
it to a <a href="install-cvs.html" title="Initialize CVS (OPTIONAL)">CVS
- repository.</a>.</p><div class="orderedlist"><ol type="1"><li><p>Create and set permissions on a subdirectory in the local cvs repository.</p><pre class="screen">[root@yourserver root]# <b><tt>mkdir /cvsroot/<span class="replaceable">service0</span></tt></b>
-[root@yourserver root]#<b><tt> chown <span class="replaceable">service0</span>.web /cvsroot/<span class="replaceable">service0</span></tt></b>
+ repository.</a>.</p><div class="orderedlist"><ol type="1"><li><p>Create and set permissions on a subdirectory in the local cvs repository.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>mkdir /cvsroot/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[root@yourserver root]#<b class="userinput"><tt> chown <span class="replaceable"><span class="replaceable">service0</span></span>.web /cvsroot/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
[root@yourserver root]#
-<pre class="action">mkdir /cvsroot/<span class="replaceable">service0</span>
-chown <span class="replaceable">service0</span>.web /cvsroot/<span class="replaceable">service0</span></pre></pre></li><li><p>Add the repository location to the user environment.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$<b><tt> emacs .bashrc</tt></b></pre><p>Put this string into <tt>/home/<span class="replaceable">service0</span>/.bashrc</tt>:</p><pre class="programlisting">export CVSROOT=/cvsroot</pre><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
+<pre class="action"><span class="action">mkdir /cvsroot/<span class="replaceable"><span class="replaceable">service0</span></span>
+chown <span class="replaceable"><span class="replaceable">service0</span></span>.web /cvsroot/<span class="replaceable"><span class="replaceable">service0</span></span></span></pre></pre></li><li><p>Add the repository location to the user environment.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$<b class="userinput"><tt> emacs .bashrc</tt></b></pre><p>Put this string into <tt class="computeroutput">/home/<span class="replaceable"><span class="replaceable">service0</span></span>/.bashrc</tt>:</p><pre class="programlisting">export CVSROOT=/cvsroot</pre><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>exit</tt></b>
logout
[root@yourserver root]#</pre></li><li><p>Import all files into cvs. In order to work on
files with source control, the files must be checked out
from cvs. So we will import, move aside, and then check
out all of the files. In the cvs import command,
- <tt><span class="replaceable">service0</span></tt>
+ <tt class="computeroutput"><span class="replaceable"><span class="replaceable">service0</span></span></tt>
refers to the cvs repository to use; it uses the CVSROOT
plus this string,
i.e.
- <tt>/cvsroot/<span class="replaceable">service0</span></tt>.
- "OpenACS" is the vendor tag, and "openacs-5-0-0d" is the
+ <tt class="computeroutput">/cvsroot/<span class="replaceable"><span class="replaceable">service0</span></span></tt>.
+ "OpenACS" is the vendor tag, and "openacs-5-0-0a1" is the
release tag. These tags will be useful in upgrading and
- branching. -m sets the version comment.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>cd /web/<span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>cvs import -m "initial install" <span class="replaceable">service0</span> OpenACS openacs-5-0-0d</tt></b>
-N <span class="replaceable">service0</span>/license.txt
-N <span class="replaceable">service0</span>/readme.txt
+ branching. -m sets the version comment.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cd /web/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cvs import -m "initial install" <span class="replaceable"><span class="replaceable">service0</span></span> OpenACS openacs-5-0-0a1</tt></b>
+N <span class="replaceable"><span class="replaceable">service0</span></span>/license.txt
+N <span class="replaceable"><span class="replaceable">service0</span></span>/readme.txt
<span class="emphasis"><em>(many lines omitted)</em></span>
-N <span class="replaceable">service0</span>/www/SYSTEM/flush-memoized-statement.tcl
+N <span class="replaceable"><span class="replaceable">service0</span></span>/www/SYSTEM/flush-memoized-statement.tcl
No conflicts created by this import
[service0@yourserver service0]$
-<pre class="action">su - <span class="replaceable">service0</span>
-cd /web/<span class="replaceable">service0</span>
-cvs import -m "initial install" <span class="replaceable">service0</span> OpenACS openacs-5-0-0d</pre></pre><p>Move the original directory to a temporary location, and check out the cvs repository in its place. If the service starts correctly, come back and remove the temporary copy of the uploaded files.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>cd ..</tt></b>
-[service0@yourserver web]$<b><tt> mv <span class="replaceable">service0</span> <span class="replaceable">service0</span>.orig</tt></b>
-[service0@yourserver web]$ <b><tt>cvs checkout <span class="replaceable">service0</span></tt></b>
-cvs checkout: Updating <span class="replaceable">service0</span>
-U <span class="replaceable">service0</span>/license.txt
+<pre class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">service0</span></span>
+cd /web/<span class="replaceable"><span class="replaceable">service0</span></span>
+cvs import -m "initial install" <span class="replaceable"><span class="replaceable">service0</span></span> OpenACS openacs-5-0-0a1</span></pre></pre><p>Move the original directory to a temporary location, and check out the cvs repository in its place. If the service starts correctly, come back and remove the temporary copy of the uploaded files.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>cd ..</tt></b>
+[service0@yourserver web]$<b class="userinput"><tt> mv <span class="replaceable"><span class="replaceable">service0</span></span> <span class="replaceable"><span class="replaceable">service0</span></span>.orig</tt></b>
+[service0@yourserver web]$ <b class="userinput"><tt>cvs checkout <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+cvs checkout: Updating <span class="replaceable"><span class="replaceable">service0</span></span>
+U <span class="replaceable"><span class="replaceable">service0</span></span>/license.txt
<span class="emphasis"><em>(many lines omitted)</em></span>
-U <span class="replaceable">service0</span>/www/SYSTEM/dbtest.tcl
-U <span class="replaceable">service0</span>/www/SYSTEM/flush-memoized-statement.tcl
-[service0@yourserver web]$ <b><tt>exit</tt></b>
+U <span class="replaceable"><span class="replaceable">service0</span></span>/www/SYSTEM/dbtest.tcl
+U <span class="replaceable"><span class="replaceable">service0</span></span>/www/SYSTEM/flush-memoized-statement.tcl
+[service0@yourserver web]$ <b class="userinput"><tt>exit</tt></b>
logout
[root@yourserver web]#
-<pre class="action">cd ..
-mv <span class="replaceable">service0</span> <span class="replaceable">service0</span>.orig
-cvs checkout <span class="replaceable">service0</span>
-exit</pre></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix�C.�Using CVS with an OpenACS Site </td><td width="20%" align="center"><a accesskey="u" href="cvs-tips.html">Up</a></td><td width="40%" align="right"> Part�IV.�For OpenACS Platform Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/cvs-service-import.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<pre class="action"><span class="action">cd ..
+mv <span class="replaceable"><span class="replaceable">service0</span></span> <span class="replaceable"><span class="replaceable">service0</span></span>.orig
+cvs checkout <span class="replaceable"><span class="replaceable">service0</span></span>
+exit</span></pre></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix�A.�Using CVS with an OpenACS Site </td><td width="20%" align="center"><a accesskey="u" href="cvs-tips.html">Up</a></td><td width="40%" align="right"> Part�IV.�For OpenACS Platform Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/cvs-service-import.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/cvs-tips.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-tips.html,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/cvs-tips.html 28 Jun 2003 05:07:01 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/cvs-tips.html 14 Oct 2003 11:02:57 -0000 1.3
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix�C.�Using CVS with an OpenACS Site</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="next" href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="cvs-service-import.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="cvs-tips"></a>Appendix�C.�Using CVS with an OpenACS Site</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="cvs-service-import.html">Add the Service to CVS - OPTIONAL</a></dt></dl></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix�A.�Using CVS with an OpenACS Site</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="next" href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="cvs-service-import.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="cvs-tips"></a>Appendix�A.�Using CVS with an OpenACS Site</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="cvs-service-import.html">Add the Service to CVS - OPTIONAL</a></dt></dl></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/database-management.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/database-management.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/database-management.html 20 Aug 2003 16:20:16 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/database-management.html 14 Oct 2003 11:02:57 -0000 1.5
@@ -1,56 +1,55 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Database Management</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="previous" href="maintenance-web.html" title="Hosting Web Sites"><link rel="next" href="backup-recovery.html" title="Backup and Recovery"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance-web.html">Prev</a> </td><th width="60%" align="center">Chapter�9.�Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="backup-recovery.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="database-management"></a>Database Management</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Database Management</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="previous" href="maintenance-web.html" title="Hosting Web Sites"><link rel="next" href="backup-recovery.html" title="Backup and Recovery"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance-web.html">Prev</a> </td><th width="60%" align="center">Chapter�9.�Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="backup-recovery.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="database-management"></a>Database Management</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="remote-postgres"></a>Running a PostGreSQL database on another server</h3></div></div><p>To run a database on a different machine than the
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="remote-postgres"></a>Running a PostGreSQL database on another server</h3></div></div><div></div></div><p>To run a database on a different machine than the
webserver requires changes to the database configuration file
and access control file, and to the OpenACS service's
configuration file.</p><div class="itemizedlist"><ul type="disc"><li><p>Edit the database configuration file, which in a
- Reference install is located at <tt>/usr/local/pgsql/data/postgresql.conf</tt>
+ Reference install is located at <tt class="computeroutput">/usr/local/pgsql/data/postgresql.conf</tt>
and change</p><pre class="programlisting">#tcpip_socket = false</pre><p>to</p><pre class="programlisting">tcpip_socket = true</pre></li><li><p>Change the access control file for the database to
permit specific remote clients to access. Access can be
controlled ... (add notes from forum post) </p></li><li><p>Change the OpenACS service's configuration file to
point to the remote database. Edit
- <tt>/web/<span class="replaceable">service0</span>/etc/config.tcl</tt>
- and change</p><pre class="programlisting"></pre><p>to </p><pre class="programlisting"></pre></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-delete-tablespace"></a>Deleting a tablespace</h3></div></div><p>Skip down for instructions on <a href="database-management.html#install-openacs-delete-postgres-tablespace">Deleting a PostgreSQL tablespace</a>.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="install-openacs-delete-oracle-tablespace"></a>Deleting an Oracle tablespace</h4></div></div><p>
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/config.tcl</tt>
+ and change</p><pre class="programlisting"></pre><p>to </p><pre class="programlisting"></pre></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-delete-tablespace"></a>Deleting a tablespace</h3></div></div><div></div></div><p>Skip down for instructions on <a href="database-management.html#install-openacs-delete-postgres-tablespace">Deleting a PostgreSQL tablespace</a>.
+ </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="install-openacs-delete-oracle-tablespace"></a>Deleting an Oracle tablespace</h4></div></div><div></div></div><p>
Should it become necessary to rebuild a tablespace from scratch,
- you can use the <tt>drop user</tt> command
- in SVRMGRL with the <tt>cascade</tt>
+ you can use the <tt class="computeroutput">drop user</tt> command
+ in SVRMGRL with the <tt class="computeroutput">cascade</tt>
option. This command will drop the user and every database object
the user owns.</p><pre class="programlisting">
SVRMGR> drop user <span class="emphasis"><em>service0</em></span> cascade;</pre><p>
- If this does not work because svrmgrl "cannot drop a user that
- is currently connected", make sure to kill the AOLserver using
+ 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:</p><pre class="programlisting">
SVRMGR> select username, sid, serial# from v$session where lower(username)='<span class="emphasis"><em>service0</em></span>';</pre><p>and then</p><pre class="programlisting">
SVRMGR> alter system kill session '<span class="emphasis"><em>sid</em></span>,<span class="emphasis"><em>serial#</em></span>';</pre><p>
where <span class="emphasis"><em>sid</em></span> and <span class="emphasis"><em>serial#</em></span> are
replaced with the corresponding values for the open session.</p><p><span class="strong">Use with caution!</span></p><p>
If you feel the need to delete <span class="emphasis"><em>everything</em></span>
related to the service, you can also issue the following:</p><pre class="programlisting">
-SVRMGR> drop tablespace <span class="emphasis"><em>service0</em></span> including contents cascade constraints;</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="install-openacs-delete-postgres-tablespace"></a>Deleting a PostgreSQL tablespace</h4></div></div><p>
+SVRMGR> drop tablespace <span class="emphasis"><em>service0</em></span> including contents cascade constraints;</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="install-openacs-delete-postgres-tablespace"></a>Deleting a PostgreSQL tablespace</h4></div></div><div></div></div><p>
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 <tt>/etc/inittab</tt>,
- reread the inittab with <tt>/sbin/init
- q</tt>, and then <tt>restart-aolserver
+ your server in <tt class="computeroutput">/etc/inittab</tt>,
+ reread the inittab with <tt class="computeroutput">/sbin/init
+ q</tt>, and then <tt class="computeroutput">restart-aolserver
<span class="emphasis"><em>service0</em></span></tt>.</p><p>Then, to drop the db, just do:</p><pre class="programlisting">
service0:~$ dropdb <span class="emphasis"><em>service0</em></span>
-DROP DATABASE</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-next-nightly-vacuum"></a>Vacuum Postgres nightly</h3></div></div><p>
- The "vacuum" command must be run periodically to reclaim space. The
- "vacuum analyze" form additionally collects statistics on the
+DROP DATABASE</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-next-nightly-vacuum"></a>Vacuum Postgres nightly</h3></div></div><div></div></div><p>
+ The "vacuum" command must be run periodically to reclaim space. The
+ "vacuum analyze" form additionally collects statistics on the
disbursion of columns in the database, which the optimizer uses when
it calculates just how to execute queries. The availability of this
data can make a tremendous difference in the execution speed of
queries. This command can also be run from cron, but it probably makes
more sense to run this command as part of your nightly backup
- procedure - if "vacuum" is going to screw up the database, you'd
+ procedure - if "vacuum" is going to screw up the database, you'd
prefer it to happen immediately after (not before!) you've made a
- backup! The "vacuum" command is very reliable, but conservatism is
+ backup! The "vacuum" command is very reliable, but conservatism is
the key to good system management. So, if you're using the export
procedure described above, you don't need to do this extra step.
</p><p>Edit your crontab:</p><pre class="programlisting">
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 -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 14 Oct 2003 11:02:57 -0000 1.13
@@ -1,27 +1,26 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Database Access API</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="apm-design.html" title="OpenACS 5.0.0d Package Manager Design"><link rel="next" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="db-api-detailed"></a>Database Access API</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Database Access API</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="apm-design.html" title="OpenACS 5.0.0a1 Package Manager Design"><link rel="next" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-api-detailed"></a>Database Access API</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>. Revised and expanded by
Roberto Mello (rmello at fslc dot usu dot edu), July 2002.
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li><li><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-bigpicture"></a>The Big Picture</h3></div></div><p>
+ </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li><li><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-bigpicture"></a>The Big Picture</h3></div></div><div></div></div><p>
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
makes this even easier.
</p><p>There were four significant problems with the way OpenACS previously used the
-database (i.e., directly through the <tt>ns_db</tt> interface):</p><div class="orderedlist"><ol type="1"><li><p><span class="strong">Handle management</span>. We required code to pass database
+database (i.e., directly through the <tt class="computeroutput">ns_db</tt> interface):</p><div class="orderedlist"><ol type="1"><li><p><span class="strong">Handle management</span>. We required code to pass database
handles around, and for routines which needed to perform database access but
didn't receive a database handle as input, it was difficult to know from
-which of the three "magic pools" (main, subquery, and log) to
+which of the three "magic pools" (main, subquery, and log) to
allocate a new handle.
-</p></li><li><p><span class="strong">Nested transactions</span>. In our Oracle driver, <tt>begin
-transaction</tt> really means "turn auto-commit mode off" and
-<tt>end transaction</tt> means "commit the current transaction and
-turn auto-commit mode on." Thus if transactional code needed to call a
+</p></li><li><p><span class="strong">Nested transactions</span>. In our Oracle driver, <tt class="computeroutput">begin
+transaction</tt> really means "turn auto-commit mode off" and
+<tt class="computeroutput">end transaction</tt> means "commit the current transaction and
+turn auto-commit mode on." Thus if transactional code needed to call a
routine which needed to operate transactionally, the semantics were
non-obvious. Consider: </p><pre class="programlisting">
@@ -32,31 +31,31 @@
}
db_transaction {
-db_dml unused "insert into greeble(bork) values(33)"
+db_dml unused "insert into greeble(bork) values(33)"
foo $db
-db_dml unused "insert into greeble(bork) values(50)"
+db_dml unused "insert into greeble(bork) values(50)"
}
</pre><p>
-This would insert greeble #33 and do all the stuff in <tt>foo</tt>
-transactionally, but the <tt>end transaction</tt> in <tt>foo</tt>
+This would insert greeble #33 and do all the stuff in <tt class="computeroutput">foo</tt>
+transactionally, but the <tt class="computeroutput">end transaction</tt> in <tt class="computeroutput">foo</tt>
would actually cause a commit, and greeble #50 would later be inserted in
auto-commit mode. This could cause subtle bugs: e.g., in the case that the
-insert for greeble #50 failed, part of the "transaction" would have
+insert for greeble #50 failed, part of the "transaction" would have
already have been committed!. This is not a good thing.
</p></li><li><p><span class="strong">Unorthodox use of variables</span>. The standard mechanism for
mapping column values into variables involved the use of the
-<tt>set_variables_after_query</tt> routine, which relies on an uplevel
-variable named <tt>selection</tt> (likewise for
-<tt>set_variables_after_subquery</tt> and <tt>subselection</tt>).
+<tt class="computeroutput">set_variables_after_query</tt> routine, which relies on an uplevel
+variable named <tt class="computeroutput">selection</tt> (likewise for
+<tt class="computeroutput">set_variables_after_subquery</tt> and <tt class="computeroutput">subselection</tt>).
</p></li><li><p><span class="strong">Hard-coded reliance on Oracle</span>. It's difficult to
write code supporting various different databases (dynamically using the
appropriate dialect based on the type of database being used, e.g., using
-<tt>DECODE</tt> on Oracle and <tt>CASE ... WHEN</tt> on
+<tt class="computeroutput">DECODE</tt> on Oracle and <tt class="computeroutput">CASE ... WHEN</tt> on
Postgres).</p></li></ol></div><p>
The Database Access API addresses the first three problems by:
</p><div class="orderedlist"><ol type="1"><li><p>making use of database handles transparent</p></li><li><p>wrapping common database operations (including transaction management) in
@@ -65,14 +64,14 @@
SQL statement a logical name. In a future version of the OpenACS Core, this API
will translate logical statement names into actual SQL, based on the type of
database in use. (To smooth the learning curve, we provide a facility for
-writing SQL inline for a "default SQL dialect", which we assume to
+writing SQL inline for a "default SQL dialect", which we assume to
be Oracle for now.)
</p><p>To be clear, SQL abstraction is <span class="emphasis"><em>not</em></span> fully implemented in OpenACS
3.3.1. The statement names supplied to each call are not used by the API at
all. The API's design for SQL abstraction is in fact incomplete;
-unresolved issues include:</p><div class="itemizedlist"><ul type="disc"><li><p>how to add <tt>WHERE</tt> clause criteria dynamically</p></li><li><p>how to build a dynamic <tt>ORDER BY</tt> clause (Ben Adida has a
+unresolved issues include:</p><div class="itemizedlist"><ul type="disc"><li><p>how to add <tt class="computeroutput">WHERE</tt> clause criteria dynamically</p></li><li><p>how to build a dynamic <tt class="computeroutput">ORDER BY</tt> clause (Ben Adida has a
proposed solution for this)</p></li><li><p>how to define a statement's formal interface (i.e., what bind
-variables it expects, what columns its <tt>SELECT</tt> clause must
+variables it expects, what columns its <tt class="computeroutput">SELECT</tt> clause must
contain if it's a query) without actually implementing the statement in a
specific SQL dialect</p></li></ul></div><p>
So why is the incremental change of adding statement naming to the API worth
@@ -81,81 +80,81 @@
design. Therefore, we know that the effort will not be wasted, and taking
advantage of the new support for bind variables will already require code
that uses 3.3.0 version of the API to be updated.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-set-var-aft-query"></a>The Bell Tolls for <tt>set_variables_after_query</tt></h3></div></div><p>
-<tt>set_variables_after_query</tt> is gone! (Well, it's still there,
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-set-var-aft-query"></a>The Bell Tolls for <tt class="computeroutput">set_variables_after_query</tt></h3></div></div><div></div></div><p>
+<tt class="computeroutput">set_variables_after_query</tt> is gone! (Well, it's still there,
but you'll never need to use it.) The new API routines set local
variables automatically. For instance:
</p><pre class="programlisting">
-db_1row select_names "select first_names, last_name from users where user_id = [ad_get_user_id]"
-doc_body_append "Hello, $first_names $last_name!"
+db_1row select_names "select first_names, last_name from users where user_id = [ad_get_user_id]"
+doc_body_append "Hello, $first_names $last_name!"
</pre><p>
-Like <tt>ns_db 1row</tt>, this will bomb if the query doesn't return
+Like <tt class="computeroutput">ns_db 1row</tt>, this will bomb if the query doesn't return
any rows (no such user exists). If this isn't what you want, you can
write:
</p><pre class="programlisting">
-if { [db_0or1row select_names "select first_names, last_name from users where user_id = [ad_get_user_id]"] } {
- doc_body_append "Hello, $first_names $last_name!"
+if { [db_0or1row select_names "select first_names, last_name from users where user_id = [ad_get_user_id]"] } {
+ doc_body_append "Hello, $first_names $last_name!"
} else {
# Executed if the query returns no rows.
- doc_body_append "There's no such user!"
+ doc_body_append "There's no such user!"
}
</pre><p>
Selecting a bunch of rows is a lot prettier now:
</p><pre class="programlisting">
-db_foreach select_names "select first_names, last_name from users" {
- doc_body_append "Say hi to $first_names $last_name for me!<br>"
+db_foreach select_names "select first_names, last_name from users" {
+ doc_body_append "Say hi to $first_names $last_name for me!<br>"
}
</pre><p>
-That's right, <tt>db_foreach</tt> is now like <tt>ns_db
-select</tt> plus a <tt>while</tt> loop plus
-<tt>set_variables_after_query</tt> plus an <tt>if</tt> statement
+That's right, <tt class="computeroutput">db_foreach</tt> is now like <tt class="computeroutput">ns_db
+select</tt> plus a <tt class="computeroutput">while</tt> loop plus
+<tt class="computeroutput">set_variables_after_query</tt> plus an <tt class="computeroutput">if</tt> statement
(containing code to be executed if no rows are returned).
</p><pre class="programlisting">
-db_foreach select_names "select first_names, last_name from users where last_name like 'S%'" {
- doc_body_append "Say hi to $first_names $last_name for me!<br>"
+db_foreach select_names "select first_names, last_name from users where last_name like 'S%'" {
+ doc_body_append "Say hi to $first_names $last_name for me!<br>"
} if_no_rows {
- doc_body_append "There aren't any users with last names beginnings with S!"
+ doc_body_append "There aren't any users with last names beginnings with S!"
}
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-handles"></a>Handle Management</h3></div></div><p>
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-handles"></a>Handle Management</h3></div></div><div></div></div><p>
The new API keeps track of which handles are in use, and automatically
allocates new handles when they are necessary (e.g., to perform subqueries
while a select is active). For example:
</p><pre class="programlisting">
-doc_body_append "<ul>"
-db_foreach select_names "select first_names, last_name, user_id from users" {
+doc_body_append "<ul>"
+db_foreach select_names "select first_names, last_name, user_id from users" {
# Automatically allocated a database handle from the main pool.
- doc_body_append "<li>User $first_names $last_name\n<ul>"
+ doc_body_append "<li>User $first_names $last_name\n<ul>"
- db_foreach select_groups "select group_id from user_group_map where user_id = $user_id" {
+ db_foreach select_groups "select group_id from user_group_map where user_id = $user_id" {
# There's a selection in progress, so we allocated a database handle
# from the subquery pool for this selection.
- doc_body_append "<li>Member of group #$group_id.\n"
+ doc_body_append "<li>Member of group #$group_id.\n"
} if_no_rows {
# Not a member of any groups.
- doc_body_append "<li>Not a member of any group.\n"
+ doc_body_append "<li>Not a member of any group.\n"
}
}
-doc_body_append "</ul>"
+doc_body_append "</ul>"
db_release_unused_handles
</pre><p>
A new handle isn't actually allocated and released for every selection,
of course - as a performance optimization, the API keeps old handles around
-until <tt>db_release_unused_handles</tt> is invoked (or the script
+until <tt class="computeroutput">db_release_unused_handles</tt> is invoked (or the script
terminates).
-</p><p>Note that there is no analogue to <tt>ns_db gethandle</tt> - the
-handle is always automatically allocated the first time it's needed.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-bindvars"></a>Bind Variables</h3></div></div><p><span class="strong">Introduction</span></p><p>
+</p><p>Note that there is no analogue to <tt class="computeroutput">ns_db gethandle</tt> - the
+handle is always automatically allocated the first time it's needed.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-bindvars"></a>Bind Variables</h3></div></div><div></div></div><p><span class="strong">Introduction</span></p><p>
Most SQL statements require that the code invoking the statement pass along
data associated with that statement, usually obtained from the user. For
instance, in order to delete a WimpyPoint presentation, a Tcl script might
@@ -165,7 +164,7 @@
delete from wp_presentations where presentation_id = <span class="emphasis"><em>some_presentation_id</em></span>
</pre><p>
-where <span class="emphasis"><em><tt>some_presentation_id</tt></em></span> is a number which is a valid
+where <span class="emphasis"><em><tt class="computeroutput">some_presentation_id</tt></em></span> is a number which is a valid
presentation ID of the presentation I want to delete. It's easy to write
code handling situations like this since SQL statements can include
<span class="strong">bind variables</span>, which represent placeholders for actual
@@ -179,24 +178,24 @@
</pre><p>
When this SQL statement is invoked, the value for the bind variable
-<tt>:some_presentation_id</tt> is pulled from the Tcl variable
-<tt>$some_presentation_id</tt> (in the caller's environment). Note
+<tt class="computeroutput">:some_presentation_id</tt> is pulled from the Tcl variable
+<tt class="computeroutput">$some_presentation_id</tt> (in the caller's environment). Note
that bind variables are not limited to one per statement; you can use an
arbitrary number, and each will pull from the correspondingly named Tcl
-variable. (Alternatively, you can also specify an list or <tt>ns_set</tt>
+variable. (Alternatively, you can also specify an list or <tt class="computeroutput">ns_set</tt>
providing bind variables' values; see <span class="emphasis"><em>Usage</em></span>.)
</p><p>The value of a bind variable is taken literally by the database driver, so
there is never any need to put single-quotes around the value for a bind
-variable, or to use <tt>db_quote</tt> to escape single-quotes contained
+variable, or to use <tt class="computeroutput">db_quote</tt> to escape single-quotes contained
in the value. The following works fine, despite the apostrophe:</p><pre class="programlisting">
-set exclamation "That's all, folks!"
+set exclamation "That's all, folks!"
db_dml exclamation_insert { insert into exclamations(exclamation) values(:exclamation) }
</pre><p>Note that you can use a bind variable in a SQL statement only where you
could use a literal (a number or single-quoted string). Bind variables cannot
be placeholders for things like SQL keywords, table names, or column names,
-so the following will not work, even if <tt>$table_name</tt> is set
+so the following will not work, even if <tt class="computeroutput">$table_name</tt> is set
properly:</p><pre class="programlisting">
select * from :table_name
@@ -206,15 +205,15 @@
above like this:
</p><pre class="programlisting">
-db_dml presentation_delete "
+db_dml presentation_delete "
delete from wp_presentations where presentation_id = $some_presentation_id
-"
+"
</pre><p>
(Note the use of double-quotes to allow the variable reference to
-<tt>$some_presentation_id</tt> to be interpolated in.) This will work,
+<tt class="computeroutput">$some_presentation_id</tt> to be interpolated in.) This will work,
but consider the case where some devious user causes
-<tt>some_presentation_id</tt> to be set to something like <tt>'3 or
+<tt class="computeroutput">some_presentation_id</tt> to be set to something like <tt class="computeroutput">'3 or
1 = 1'</tt>, which would result in the following statement being
executed:
</p><pre class="programlisting">
@@ -225,24 +224,24 @@
This deletes every presentation in the database! Using bind variables
eliminates this gaping security hole: since bind variable values are taken
literally. Oracle will attempt to delete presentations whose presentation ID
-is literally <tt>'3 or 1 = 1'</tt> (i.e., no presentations, since
-<tt>'3 or 1 = 1'</tt> can't possibly be a valid integer
-primary key for <tt>wp_presentations</tt>. In general, since Oracle
+is literally <tt class="computeroutput">'3 or 1 = 1'</tt> (i.e., no presentations, since
+<tt class="computeroutput">'3 or 1 = 1'</tt> can't possibly be a valid integer
+primary key for <tt class="computeroutput">wp_presentations</tt>. In general, since Oracle
always considers the values of bind variables to be literals, it becomes more
difficult for users to perform URL surgery to trick scripts into running
dangerous queries and DML.
-</p><p><span class="strong">Usage</span></p><p>Every <tt>db_*</tt> command accepting a SQL command as an argument
-supports bind variables. You can either</p><div class="itemizedlist"><ul type="disc"><li><p>specify the <tt>-bind</tt> switch to provide a set with bind variable
-values, or</p></li><li><p>specify the <tt>-bind</tt> switch to explicitly provide a list of
+</p><p><span class="strong">Usage</span></p><p>Every <tt class="computeroutput">db_*</tt> command accepting a SQL command as an argument
+supports bind variables. You can either</p><div class="itemizedlist"><ul type="disc"><li><p>specify the <tt class="computeroutput">-bind</tt> switch to provide a set with bind variable
+values, or</p></li><li><p>specify the <tt class="computeroutput">-bind</tt> switch to explicitly provide a list of
bind variable names and values, or</p></li><li><p>not specify a bind variable list at all, in which case Tcl variables are
used as bind variables.</p></li></ul></div><p>
-The default behavior (i.e., if the <tt>-bind</tt> switch is omitted) is
+The default behavior (i.e., if the <tt class="computeroutput">-bind</tt> switch is omitted) is
that these procedures expect to find local variables that correspond in name
to the referenced bind variables, e.g.:
</p><pre class="programlisting">
set user_id 123456
-set role "administrator"
+set role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -252,18 +251,18 @@
and map.role = :role
} {
# do something for each group of which user 123456 is in the role
- # of "administrator"
+ # of "administrator"
}
</pre><p>
-The value of the local Tcl variable <tt>user_id</tt> (123456) is bound to
-the <tt>user_id</tt> bind variable.
-</p><p>The <tt>-bind</tt> switch can takes the name of an <tt>ns_set</tt>
+The value of the local Tcl variable <tt class="computeroutput">user_id</tt> (123456) is bound to
+the <tt class="computeroutput">user_id</tt> bind variable.
+</p><p>The <tt class="computeroutput">-bind</tt> switch can takes the name of an <tt class="computeroutput">ns_set</tt>
containing keys for each bind variable named in the query, e.g.:</p><pre class="programlisting">
set bind_vars [ns_set create]
ns_set put $bind_vars user_id 123456
-ns_set put $bind_vars role "administrator"
+ns_set put $bind_vars role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -273,11 +272,11 @@
and map.role = :role
} -bind $bind_vars {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
</pre><p>
-Alternatively, as an argument to <tt>-bind</tt> you can specify a list of
+Alternatively, as an argument to <tt class="computeroutput">-bind</tt> you can specify a list of
alternating name/value pairs for bind variables:
</p><pre class="programlisting">
@@ -287,22 +286,22 @@
where g.group_id = map.user_id
and map.user_id = :user_id
and map.role = :role
-} -bind [list user_id 123456 role "administrator"] {
+} -bind [list user_id 123456 role "administrator"] {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
</pre><p><span class="strong"><a name="kernel.dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</span></p><p>
When processing a DML statement, Oracle coerces empty strings into
-<tt>null</tt>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the
-<tt>WHERE</tt> clause of a query, i.e.
-<tt>col = ''</tt> and
-<tt>col is null</tt> are not equivalent.)
+<tt class="computeroutput">null</tt>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the
+<tt class="computeroutput">WHERE</tt> clause of a query, i.e.
+<tt class="computeroutput">col = ''</tt> and
+<tt class="computeroutput">col is null</tt> are not equivalent.)
</p><p>As a result, when using bind variables, the only way to make Oracle set a
-column value to <tt>null</tt> is to set the corresponding bind variable
+column value to <tt class="computeroutput">null</tt> is to set the corresponding bind variable
to the empty string, since a bind variable whose value is the string
-"null" will be interpreted as the literal string
-"null".</p><p>These Oracle quirks complicate the process of writing clear and abstract
+"null" will be interpreted as the literal string
+"null".</p><p>These Oracle quirks complicate the process of writing clear and abstract
DML difficult. Here is an example that illustrates why:</p><pre class="programlisting">
#
@@ -314,259 +313,259 @@
# );
#
-set bar ""
-set baz ""
+set bar ""
+set baz ""
-db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
+db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
#
-# the values of the "bar" and "baz" columns in the new row are both
+# the values of the "bar" and "baz" columns in the new row are both
# null, because Oracle has coerced the empty string (even for the
-# numeric column "bar") into null in both cases
+# numeric column "bar") into null in both cases
</pre><p>
Since databases other than Oracle do not coerce empty strings into
-<tt>null</tt>, this code has different semantics depending on the
+<tt class="computeroutput">null</tt>, this code has different semantics depending on the
underlying database (i.e., the row that gets inserted may not have null as
its column values), which defeats the purpose of SQL abstraction.
</p><p>Therefore, the Database Access API provides a database-independent way to
-represent <tt>null</tt> (instead of the Oracle-specific idiom of the
-empty string): <span class="strong"><tt>db_null</tt></span>.</p><p>Use it instead of the empty string whenever you want to set a column value
-explicitly to <tt>null</tt>, e.g.:</p><pre class="programlisting">
+represent <tt class="computeroutput">null</tt> (instead of the Oracle-specific idiom of the
+empty string): <span class="strong"><tt class="computeroutput">db_null</tt></span>.</p><p>Use it instead of the empty string whenever you want to set a column value
+explicitly to <tt class="computeroutput">null</tt>, e.g.:</p><pre class="programlisting">
set bar [db_null]
set baz [db_null]
-db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
+db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
#
-# sets the values for both the "bar" and "baz" columns to null
+# sets the values for both the "bar" and "baz" columns to null
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-sql-abstraction"></a>SQL Abstraction</h3></div></div><p>
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-sql-abstraction"></a>SQL Abstraction</h3></div></div><div></div></div><p>
We now require that each SQL statement be assigned a logical name for the
statement that is unique to the procedure or page in which it is defined.
This is so that (eventually) we can implement logically named statements with
alternative SQL for non-Oracle databases (e.g., Postgres). More on this
later.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-placing-values"></a>Placing Column Values in Arrays and Sets</h3></div></div><p>
-Normally, <tt>db_foreach</tt>, <tt>db_0or1row</tt>, and
-<tt>db_1row</tt> places the results of queries in Tcl variables, so you
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-placing-values"></a>Placing Column Values in Arrays and Sets</h3></div></div><div></div></div><p>
+Normally, <tt class="computeroutput">db_foreach</tt>, <tt class="computeroutput">db_0or1row</tt>, and
+<tt class="computeroutput">db_1row</tt> places the results of queries in Tcl variables, so you
can say:
</p><pre class="programlisting">
-db_foreach users_select "select first_names, last_name from users" {
- doc_body_append "<li>$first_names $last_name\n"
+db_foreach users_select "select first_names, last_name from users" {
+ doc_body_append "<li>$first_names $last_name\n"
}
</pre><p>
However, sometimes this is not sufficient: you may need to examine the rows
returned, to dynamically determine the set of columns returned by the query,
or to avoid collisions with existing variables. You can use the
-<tt>-column_array</tt> and <tt>-column_set</tt> switches to
-<tt>db_foreach</tt>, <tt>db_0or1row</tt>, and <tt>db_1row</tt> to
+<tt class="computeroutput">-column_array</tt> and <tt class="computeroutput">-column_set</tt> switches to
+<tt class="computeroutput">db_foreach</tt>, <tt class="computeroutput">db_0or1row</tt>, and <tt class="computeroutput">db_1row</tt> to
instruct the database routines to place the results in a Tcl array or
-<tt>ns_set</tt>, respectively, where the keys are the column names and
+<tt class="computeroutput">ns_set</tt>, respectively, where the keys are the column names and
the values are the column values. For example:
</p><pre class="programlisting">
-db_foreach users_select "select first_names, last_name from users" -column_set columns {
+db_foreach users_select "select first_names, last_name from users" -column_set columns {
# Now $columns is an ns_set.
- doc_body_append "<li>"
+ doc_body_append "<li>"
for { set i 0 } { $i < [ns_set size $columns] } { incr i } {
- doc_body_append "[ns_set key $columns $i] is [ns_set value $columns $i]. \n"
+ doc_body_append "[ns_set key $columns $i] is [ns_set value $columns $i]. \n"
}
}
</pre><p>
will write something like:
-</p><div class="itemizedlist"><ul type="disc"><li><p>first_names is Jon. last_name is Salz.</p></li><li><p>first_names is Lars. last_name is Pind.</p></li><li><p>first_names is Michael. last_name is Yoon.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dp-api-detailed-api"></a>API</h3></div></div><p>
-Note that you never have to use <tt>ns_db</tt> anymore (including
-<tt>ns_db gethandle</tt>)! Just start doing stuff, and (if you want) call
-<tt>db_release_unused_handles</tt> when you're done as a hint to
+</p><div class="itemizedlist"><ul type="disc"><li><p>first_names is Jon. last_name is Salz.</p></li><li><p>first_names is Lars. last_name is Pind.</p></li><li><p>first_names is Michael. last_name is Yoon.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dp-api-detailed-api"></a>API</h3></div></div><div></div></div><p>
+Note that you never have to use <tt class="computeroutput">ns_db</tt> anymore (including
+<tt class="computeroutput">ns_db gethandle</tt>)! Just start doing stuff, and (if you want) call
+<tt class="computeroutput">db_release_unused_handles</tt> when you're done as a hint to
release the database handle.
-</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_null"></a>db_null</tt></span>
+</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_null"></a>db_null</tt></span>
</span></dt><dd><pre class="programlisting">
-<span class="strong"><tt>db_null</tt></span>
+<span class="strong"><tt class="computeroutput">db_null</tt></span>
</pre><p>Returns a value which can be used in a bind variable to represent the SQL
-value <tt>null</tt>. See <a href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and Bind Variables</a>
+value <tt class="computeroutput">null</tt>. See <a href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and Bind Variables</a>
above.</p></dd><dt><span class="term">
-<span class="strong"><tt><a name="kernel.dbapi_db_foreach"></a>db_foreach</tt></span>
+<span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_foreach"></a>db_foreach</tt></span>
</span></dt><dd><pre class="programlisting">
<span class="strong">db_foreach</span> <span class="emphasis"><em>statement-name sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
[ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] \
<span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span>
-</pre><p>Performs the SQL query <span class="emphasis"><em><tt>sql</tt></em></span>, executing
-<span class="emphasis"><em><tt>code_block</tt></em></span> once for each row with variables set to
-column values (or a set or array populated if <tt>-column_array</tt> or
-<tt>column_set</tt> is specified). If the query returns no rows, executes
-<span class="emphasis"><em><tt>if_no_rows_block</tt></em></span> (if provided). </p><p>Example:</p><pre class="programlisting">
+</pre><p>Performs the SQL query <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>, executing
+<span class="emphasis"><em><tt class="computeroutput">code_block</tt></em></span> once for each row with variables set to
+column values (or a set or array populated if <tt class="computeroutput">-column_array</tt> or
+<tt class="computeroutput">column_set</tt> is specified). If the query returns no rows, executes
+<span class="emphasis"><em><tt class="computeroutput">if_no_rows_block</tt></em></span> (if provided). </p><p>Example:</p><pre class="programlisting">
-db_foreach select_foo "select foo, bar from greeble" {
- doc_body_append "<li>foo=$foo; bar=$bar\n"
+db_foreach select_foo "select foo, bar from greeble" {
+ doc_body_append "<li>foo=$foo; bar=$bar\n"
} if_no_rows {
- doc_body_append "<li>There are no greebles in the database.\n"
+ doc_body_append "<li>There are no greebles in the database.\n"
}
</pre><p>
-The code block may contain <tt>break</tt> statements (which terminate the
-loop and flush the database handle) and <tt>continue</tt> statements
-(which continue to the next row of the loop). </p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_1row"></a>db_1row</tt></span></span></dt><dd><pre class="programlisting">
+The code block may contain <tt class="computeroutput">break</tt> statements (which terminate the
+loop and flush the database handle) and <tt class="computeroutput">continue</tt> statements
+(which continue to the next row of the loop). </p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_1row"></a>db_1row</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_1row</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
[ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
-</pre><p>Performs the SQL query <span class="emphasis"><em><tt>sql</tt></em></span>, setting variables to
+</pre><p>Performs the SQL query <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>, setting variables to
column values. Raises an error if the query does not return exactly 1 row. </p><p>Example:</p><pre class="programlisting">
-db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
+db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
# Bombs if there's no such greeble!
# Now $foo and $bar are set.
-</pre></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_0or1row"></a>db_0or1row</tt></span> </span></dt><dd><pre class="programlisting">
+</pre></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_0or1row"></a>db_0or1row</tt></span> </span></dt><dd><pre class="programlisting">
<span class="strong">db_0or1row</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
[ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
-</pre><p>Performs the SQL query <span class="emphasis"><em><tt>sql</tt></em></span>. If a row is returned,
+</pre><p>Performs the SQL query <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. If a row is returned,
sets variables to column values and returns 1. If no rows are returned,
-returns 0. If more than one row is returned, throws an error. </p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_string"></a>db_string</tt></span> </span></dt><dd><pre class="programlisting">
+returns 0. If more than one row is returned, throws an error. </p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_string"></a>db_string</tt></span> </span></dt><dd><pre class="programlisting">
<span class="strong">db_string</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -default <span class="emphasis"><em>default</em></span> ] [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>Returns the first column of the result of SQL query
-<span class="emphasis"><em><tt>sql</tt></em></span>. If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't return a
-row, returns <span class="emphasis"><em><tt>default</tt></em></span> (or throws an error if
-<span class="emphasis"><em><tt>default</tt></em></span> is unspecified). Analogous to
-<tt>database_to_tcl_string</tt> and
-<tt>database_to_tcl_string_or_null</tt>.
+<span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. If <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span> doesn't return a
+row, returns <span class="emphasis"><em><tt class="computeroutput">default</tt></em></span> (or throws an error if
+<span class="emphasis"><em><tt class="computeroutput">default</tt></em></span> is unspecified). Analogous to
+<tt class="computeroutput">database_to_tcl_string</tt> and
+<tt class="computeroutput">database_to_tcl_string_or_null</tt>.
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_nextval"></a>db_nextval</tt></span> </span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_nextval"></a>db_nextval</tt></span> </span></dt><dd><pre class="programlisting">
<span class="strong">db_nextval</span> <span class="emphasis"><em>sequence-name</em></span>
</pre><p>Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a
-SQL statement like <tt>SELECT</tt> <span class="emphasis"><em><tt>sequence-name</tt></em></span><tt>.nextval FROM
+SQL statement like <tt class="computeroutput">SELECT</tt> <span class="emphasis"><em><tt class="computeroutput">sequence-name</tt></em></span><tt class="computeroutput">.nextval FROM
DUAL</tt>). If sequence pooling is enabled for the sequence, transparently
uses a value from the pool if available to save a round-trip to the database.
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_list"></a>db_list</tt></span></span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_list"></a>db_list</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_list</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>Returns a Tcl list of the values in the first column of the result of SQL
-query <span class="emphasis"><em><tt>sql</tt></em></span>. If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't
+query <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. If <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span> doesn't
return any rows, returns an empty list. Analogous to
-<tt>database_to_tcl_list</tt>.
+<tt class="computeroutput">database_to_tcl_list</tt>.
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></span></span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_list_of_lists</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>Returns a Tcl list, each element of which is a list of all column values
-in a row of the result of SQL query <span class="emphasis"><em><tt>sql</tt></em></span>. If
-<span class="emphasis"><em><tt>sql</tt></em></span> doesn't return any rows, returns an empty list.
-(Analogous to <tt>database_to_tcl_list_list</tt>.)
+in a row of the result of SQL query <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. If
+<span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span> doesn't return any rows, returns an empty list.
+(Analogous to <tt class="computeroutput">database_to_tcl_list_list</tt>.)
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_list_of_ns_sets"></a>db_list_of_ns_sets</tt></span></span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_list_of_ns_sets"></a>db_list_of_ns_sets</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_list_of_ns_sets</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>
Returns a list of ns_sets with the values of each column of each row
- returned by the <tt>sql</tt> query specified.
- </p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_dml"></a>db_dml</tt></span></span></dt><dd><pre class="programlisting">
+ returned by the <tt class="computeroutput">sql</tt> query specified.
+ </p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_dml"></a>db_dml</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_dml</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \
[ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
[ -blobs <span class="emphasis"><em>blob_list</em></span> | -clobs <span class="emphasis"><em>clob_list</em></span> |
-blob_files <span class="emphasis"><em>blob_file_list</em></span> | -clob_files <span class="emphasis"><em>clob_file_list</em></span> ]
-</pre><p>Performs the DML or DDL statement <span class="emphasis"><em><tt>sql</tt></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL
+</pre><p>Performs the DML or DDL statement <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL
should return <span class="emphasis"><em>n</em></span> blobs or clobs into the bind variables
-<tt>:1</tt>, <tt>:2</tt>, ... :<span class="emphasis"><em><tt>n</tt></em></span>.
-<span class="emphasis"><em><tt>blobs</tt></em></span> or <span class="emphasis"><em><tt>clobs</tt></em></span>, if specified,
+<tt class="computeroutput">:1</tt>, <tt class="computeroutput">:2</tt>, ... :<span class="emphasis"><em><tt class="computeroutput">n</tt></em></span>.
+<span class="emphasis"><em><tt class="computeroutput">blobs</tt></em></span> or <span class="emphasis"><em><tt class="computeroutput">clobs</tt></em></span>, if specified,
should be a list of individual BLOBs or CLOBs to insert;
-<span class="emphasis"><em><tt>blob_files</tt></em></span> or <span class="emphasis"><em><tt>clob_files</tt></em></span>, if
+<span class="emphasis"><em><tt class="computeroutput">blob_files</tt></em></span> or <span class="emphasis"><em><tt class="computeroutput">clob_files</tt></em></span>, if
specified, should be a list of <span class="emphasis"><em>paths to files</em></span> containing the data to
-insert. Only one of <tt>-blobs</tt>, <tt>-clobs</tt>,
-<tt>-blob_files</tt>, and <tt>-clob_files</tt> may be provided.</p><p>Example:</p><pre class="programlisting">
+insert. Only one of <tt class="computeroutput">-blobs</tt>, <tt class="computeroutput">-clobs</tt>,
+<tt class="computeroutput">-blob_files</tt>, and <tt class="computeroutput">-clob_files</tt> may be provided.</p><p>Example:</p><pre class="programlisting">
-db_dml insert_photos "
+db_dml insert_photos "
insert photos(photo_id, image, thumbnail_image)
values(photo_id_seq.nextval, empty_blob(), empty_blob())
returning image, thumbnail_image into :1, :2
- " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]
+ " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]
</pre><p>
-This inserts a new row into the <tt>photos</tt> table, with the contents
-of the files <tt>/var/tmp/the_photo</tt> and
-<tt>/var/tmp/the_thumbnail</tt> in the <tt>image</tt> and
-<tt>thumbnail</tt> columns, respectively.
+This inserts a new row into the <tt class="computeroutput">photos</tt> table, with the contents
+of the files <tt class="computeroutput">/var/tmp/the_photo</tt> and
+<tt class="computeroutput">/var/tmp/the_thumbnail</tt> in the <tt class="computeroutput">image</tt> and
+<tt class="computeroutput">thumbnail</tt> columns, respectively.
</p></dd><dt><span class="term">
-<span class="strong"><tt><a name="kernel.dbapi_db_write_clob"></a>db_write_clob</tt></span>,
-<span class="strong"><tt><a name="kernel.dbapi_db_write_blob"></a>db_write_blob</tt></span>,
-<span class="strong"><tt><a name="kernel.dbapi_db_blob_get_file"></a>db_blob_get_file</tt></span>
+<span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_write_clob"></a>db_write_clob</tt></span>,
+<span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_write_blob"></a>db_write_blob</tt></span>,
+<span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_blob_get_file"></a>db_blob_get_file</tt></span>
</span></dt><dd><pre class="programlisting">
<span class="strong">db_write_clob</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
<span class="strong">db_write_blob</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
<span class="strong">db_blob_get_file</span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
-</pre><p>Analagous to <tt>ns_ora write_clob/write_blob/blob_get_file</tt>.
+</pre><p>Analagous to <tt class="computeroutput">ns_ora write_clob/write_blob/blob_get_file</tt>.
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></span></span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_release_unused_handles</span>
-</pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_transaction"></a>db_transaction</tt></span></span></dt><dd><pre class="programlisting">
+</pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_transaction"></a>db_transaction</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_transaction</span> <span class="emphasis"><em>code_block</em></span> [ on_error { <span class="emphasis"><em>code_block</em></span> } ]
-</pre><p>Executes <span class="emphasis"><em><tt>code_block</tt></em></span> transactionally. Nested
-transactions are supported (<tt>end transaction</tt> is transparently
-<tt>ns_db dml</tt>'ed when the outermost transaction completes). The
-<tt>db_abort_transaction</tt> command can be used to abort all levels of
-transactions. It is possible to specify an optional <tt>on_error</tt>
+</pre><p>Executes <span class="emphasis"><em><tt class="computeroutput">code_block</tt></em></span> transactionally. Nested
+transactions are supported (<tt class="computeroutput">end transaction</tt> is transparently
+<tt class="computeroutput">ns_db dml</tt>'ed when the outermost transaction completes). The
+<tt class="computeroutput">db_abort_transaction</tt> command can be used to abort all levels of
+transactions. It is possible to specify an optional <tt class="computeroutput">on_error</tt>
code block that will be executed if some code in <span class="emphasis"><em>code_block</em></span> throws
-an exception. The variable <tt>errmsg</tt> will be bound in that scope.
-If there is no <tt>on_error</tt> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting">
+an exception. The variable <tt class="computeroutput">errmsg</tt> will be bound in that scope.
+If there is no <tt class="computeroutput">on_error</tt> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting">
proc replace_the_foo { col } {
db_transaction {
- db_dml "delete from foo"
- db_dml "insert into foo(col) values($col)"
+ db_dml "delete from foo"
+ db_dml "insert into foo(col) values($col)"
}
}
proc print_the_foo {} {
- doc_body_append "foo is [db_string "select col from foo"]<br>\n"
+ doc_body_append "foo is [db_string "select col from foo"]<br>\n"
}
replace_the_foo 8
-print_the_foo ; # Writes out "foo is 8"
+print_the_foo ; # Writes out "foo is 8"
db_transaction {
replace_the_foo 14
- print_the_foo ; # Writes out "foo is 14"
- db_dml "insert into some_other_table(col) values(999)"
+ print_the_foo ; # Writes out "foo is 14"
+ db_dml "insert into some_other_table(col) values(999)"
...
db_abort_transaction
} on_error {
- doc_body_append "Error in transaction: $errmsg"
+ doc_body_append "Error in transaction: $errmsg"
}
-print_the_foo ; # Writes out "foo is 8"
+print_the_foo ; # Writes out "foo is 8"
-</pre></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_abort_transaction"></a>db_abort_transaction</tt></span>
+</pre></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_abort_transaction"></a>db_abort_transaction</tt></span>
</span></dt><dd><pre class="programlisting">
<span class="strong">db_abort_transaction</span>
</pre><p>Aborts all levels of a transaction. That is if this is called within
several nested transactions, all of them are terminated. Use this insetead of
-<tt>db_dml "abort" "abort transaction"</tt>.
+<tt class="computeroutput">db_dml "abort" "abort transaction"</tt>.
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_multirow"></a>db_multirow</tt></span></span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_multirow"></a>db_multirow</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_multirow</span> [ -local ] [ -append ] [ -extend <span class="emphasis"><em>column_list</em></span> ] \
<span class="emphasis"><em>var-name</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \
[ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
<span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span>
</pre><p>
- Performs the SQL query <tt>sql</tt>, saving results in variables
+ Performs the SQL query <tt class="computeroutput">sql</tt>, saving results in variables
of the form
- <tt><span class="emphasis"><em>var_name</em></span>:1</tt>, <tt><span class="emphasis"><em>var_name</em></span>:2</tt>, etc,
- setting <tt><span class="emphasis"><em>var_name</em></span>:rowcount</tt> to the total number
- of rows, and setting <tt><span class="emphasis"><em>var_name</em></span>:columns</tt> to a
+ <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:1</tt>, <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:2</tt>, etc,
+ setting <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:rowcount</tt> to the total number
+ of rows, and setting <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:columns</tt> to a
list of column names.
</p><p>
Each row also has a column, rownum, automatically
added and set to the row number, starting with 1. Note that this will
override any column in the SQL statement named 'rownum', also if you're
using the Oracle rownum pseudo-column.
</p><p>
- If the <tt>-local</tt> is passed, the variables defined
+ If the <tt class="computeroutput">-local</tt> is passed, the variables defined
by db_multirow will be set locally (useful if you're compiling dynamic templates
in a function or similar situations).
</p><p>
@@ -579,19 +578,19 @@
multirow.
</p><p>
You may also add additional, computed columns to the multirow, using the
- <tt>-extend { <span class="emphasis"><em>col_1</em></span> <span class="emphasis"><em>col_2</em></span> ... }</tt> switch. This is
+ <tt class="computeroutput">-extend { <span class="emphasis"><em>col_1</em></span> <span class="emphasis"><em>col_2</em></span> ... }</tt> switch. This is
useful for things like constructing a URL for the object retrieved by
the query.
</p><p>
If you're constructing your multirow through multiple queries with the
same set of columns, but with different rows, you can use the
- <tt>-append</tt> switch. This causes the rows returned by this query
+ <tt class="computeroutput">-append</tt> switch. This causes the rows returned by this query
to be appended to the rows already in the multirow, instead of starting
a clean multirow, as is the normal behavior. The columns must match the
columns in the original multirow, or an error will be thrown.
</p><p>
- Your code block may call <tt>continue</tt> in order to skip a row
- and not include it in the multirow. Or you can call <tt>break</tt>
+ Your code block may call <tt class="computeroutput">continue</tt> in order to skip a row
+ and not include it in the multirow. Or you can call <tt class="computeroutput">break</tt>
to skip this row and quit looping.
</p><p>
@@ -606,28 +605,28 @@
} {
set user_url [acs_community_member_url -user_id $user_id]
}
- </pre></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_resultrows"></a>db_resultrows</tt></span></span></dt><dd><pre class="programlisting">
+ </pre></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_resultrows"></a>db_resultrows</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_resultrows</span>
</pre><p>Returns the number of rows affected or returned by the previous
statement.
-</p></dd><dt><span class="term"><span class="strong"><tt><a name="kernel.dbapi_db_with_handle"></a>db_with_handle</tt></span></span></dt><dd><pre class="programlisting">
+</p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="kernel.dbapi_db_with_handle"></a>db_with_handle</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_with_handle</span> <span class="emphasis"><em>var</em></span> <span class="emphasis"><em>code_block</em></span>
-</pre><p>Places a database handle into the variable <span class="emphasis"><em><tt>var</tt></em></span> and
-executes <span class="emphasis"><em><tt>code_block</tt></em></span>. This is useful when you don't
-want to have to use the new API (<tt>db_foreach</tt>,
-<tt>db_1row</tt>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting">
+</pre><p>Places a database handle into the variable <span class="emphasis"><em><tt class="computeroutput">var</tt></em></span> and
+executes <span class="emphasis"><em><tt class="computeroutput">code_block</tt></em></span>. This is useful when you don't
+want to have to use the new API (<tt class="computeroutput">db_foreach</tt>,
+<tt class="computeroutput">db_1row</tt>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting">
proc lookup_the_foo { foo } {
db_with_handle db {
- return [db_string unused "select ..."]
+ return [db_string unused "select ..."]
}
}
db_with_handle db {
# Now there's a database handle in $db.
- set selection [ns_db select $db "select foo from bar"]
+ set selection [ns_db select $db "select foo from bar"]
while { [ns_db getrow $db $selection] } {
set_variables_after_query
@@ -637,32 +636,32 @@
</pre></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_name"></a>db_name
</tt>
</span>
</span></dt><dd><pre class="programlisting">
<span class="strong">
- <tt>db_name</tt>
+ <tt class="computeroutput">db_name</tt>
</span>
</pre><p>
Returns the name of the database, as returned by the driver.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_type"></a>db_type
</tt>
</span>
</span></dt><dd><pre class="programlisting">
<span class="strong">
- <tt>db_type</tt>
+ <tt class="computeroutput">db_type</tt>
</span>
</pre><p>
Returns the RDBMS type (i.e. oracle, postgresql) this OpenACS installation is
using. The nsv ad_database_type is set up during the bootstrap process.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_compatible_rdbms_p"></a>db_compatible_rdbms_p
</tt>
</span>
@@ -672,7 +671,7 @@
Returns 1 if the given db_type is compatible with the current RDBMS.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_package_supports_rdbms_p"></a>db_package_supports_rdbms_p
</tt>
</span>
@@ -684,7 +683,7 @@
file regardless of whether or not it actually uses the database.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_legacy_package_p"></a>db_legacy_package_p
</tt>
</span>
@@ -695,7 +694,7 @@
it explicitly supports Oracle 8.1.6 rather than the OpenACS more general oracle.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_version"></a>db_version
</tt>
</span>
@@ -706,7 +705,7 @@
recent PostgreSQL version.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_current_rdbms"></a>db_current_rdbms
</tt>
</span>
@@ -716,7 +715,7 @@
Returns the current rdbms type and version.
</p></dd><dt><span class="term">
<span class="strong">
- <tt>
+ <tt class="computeroutput">
<a name="kernel.dbapi_db_known_database_types"></a>db_known_database_types
</tt>
</span>
@@ -725,10 +724,10 @@
</pre><p>
Returns a list of three-element lists describing the database engines known
to OpenACS. Each sublist contains the internal database name (used in file
- paths, etc), the driver name, and a "pretty name" to be used in selection
+ paths, etc), the driver name, and a "pretty name" to be used in selection
forms displayed to the user.
</p><p>
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.
- </p></dd></dl></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 5.0.0d Package Manager Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS Internationalization Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/db-api-detailed.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></dd></dl></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 5.0.0a1 Package Manager Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS Internationalization Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/db-api-detailed.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/db-api.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/db-api.html 14 Oct 2003 11:02:57 -0000 1.13
@@ -1,25 +1,24 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The OpenACS Database Access API</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="request-processor.html" title="The Request Processor"><link rel="next" href="templates.html" title="Using Templates in OpenACS 5.0.0d"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="db-api"></a>The OpenACS Database Access API</h2></div></div><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The OpenACS Database Access API</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="request-processor.html" title="The Request Processor"><link rel="next" href="templates.html" title="Using Templates in OpenACS 5.0.0a1"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-api"></a>The OpenACS Database Access API</h2></div></div><div></div></div><p>
By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> and
<a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>. Modified
by Roberto Mello.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-overview"></a>Overview</h3></div></div><p>
+ </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-overview"></a>Overview</h3></div></div><div></div></div><p>
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 makes this even easier.
</p><p>
More detailed information about the DB api is available at
<a href="db-api-detailed.html">Database Access API</a>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-thenewway"></a>The New Way</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-thenewway"></a>The New Way</h3></div></div><div></div></div><p>
Introduced in ACS 3.4, the new Database API is meant to save
developers from the above tedium and provide a more structured syntax
for specifying database operations, including transactions.
Here's an example of the API.
</p><pre class="programlisting">
set count 0
-set tcl_var "foo"
+set tcl_var "foo"
set sql {
select
@@ -45,13 +44,13 @@
No explicit code for grabbing and releasing handles. Usage of the
Database API implicitly deals with all handle management issues.
</p></li><li><p>
- The new command <tt>db_transaction</tt>
+ The new command <tt class="computeroutput">db_transaction</tt>
makes the scope of a transaction
- clear. <tt>db_transaction</tt> takes the
+ clear. <tt class="computeroutput">db_transaction</tt> takes the
code block argument and automatically runs it in the context of a
transaction.
</p></li><li><p>
- The new command <tt>db_foreach</tt> writes
+ The new command <tt class="computeroutput">db_foreach</tt> writes
our old while loop for us.
</p></li><li><p>
Every SQL query has a name, meant to be unique within the server
@@ -61,7 +60,7 @@
from a Tcl variable to the database, which we'll cover next.
</p></li></ol></div><p>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-bindvariables"></a>Bind Variables</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-bindvariables"></a>Bind Variables</h3></div></div><div></div></div><p>
Bind variables are placeholders for literal values in an SQL query
being sent to the server. Take the example query above: in the old
way, data was generally passed to Oracle directly, via Tcl string
@@ -117,18 +116,18 @@
where some_table.id = some_other_table.id
and some_table.condition_p = ?
</pre><p>
- The '?' character means "This will be filled in later with literal
- data". In use, you might write code that looks like this:
+ The '?' character means "This will be filled in later with literal
+ data". In use, you might write code that looks like this:
</p><pre class="programlisting">
-set statement [prepare_query "
+set statement [prepare_query "
select
foo,
bar,
baz
from some_table, some_other_table
where some_table.id = some_other_table.id
and some_table.condition_p = ?
- "]
+ "]
[bind_param $statement 1 $tcl_var]
</pre><p>
@@ -170,8 +169,8 @@
query, and Tcl style string interpolation does not happen. So you
cannot do something like:
</p><pre class="programlisting">
-set table "baz"
-set condition "where foo = bar"
+set table "baz"
+set condition "where foo = bar"
db_foreach my_query { select :table from some_table where :condition }
</pre><p>
@@ -183,24 +182,24 @@
Finally, the DB API has several different styles for passing bind
variable values to queries. In general, use the style presented here
because it is the most convenient.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="db-api-bind-vars-usage"></a>Usage</h4></div></div><p>Every <tt>db_*</tt> command accepting a SQL command as an argument
+ </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="db-api-bind-vars-usage"></a>Usage</h4></div></div><div></div></div><p>Every <tt class="computeroutput">db_*</tt> command accepting a SQL command as an argument
supports bind variables. You can either</p><div class="itemizedlist"><ul type="disc"><li><p>
- Specify the <tt>-bind</tt> switch to provide a set with bind variable
+ Specify the <tt class="computeroutput">-bind</tt> switch to provide a set with bind variable
values, or
</p></li><li><p>
- Specify the <tt>-bind</tt> switch to explicitly provide a list of
+ Specify the <tt class="computeroutput">-bind</tt> switch to explicitly provide a list of
bind variable names and values, or
</p></li><li><p>
Not specify a bind variable list at all, in which case Tcl variables are
used as bind variables.
</p></li></ul></div><p>
- The default behavior (i.e., if the <tt>-bind</tt> switch is omitted) is
+ The default behavior (i.e., if the <tt class="computeroutput">-bind</tt> switch is omitted) is
that these procedures expect to find local variables that correspond in name
to the referenced bind variables, e.g.:
</p><pre class="programlisting">
set user_id 123456
-set role "administrator"
+set role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -210,18 +209,18 @@
and map.role = :role
} {
# do something for each group of which user 123456 is in the role
- # of "administrator"
+ # of "administrator"
}
</pre><p>
- The value of the local Tcl variable <tt>user_id</tt> (123456) is bound to
- the <tt>user_id</tt> bind variable.
- </p><p>The <tt>-bind</tt> switch can takes the name of an <tt>ns_set</tt>
+ The value of the local Tcl variable <tt class="computeroutput">user_id</tt> (123456) is bound to
+ the <tt class="computeroutput">user_id</tt> bind variable.
+ </p><p>The <tt class="computeroutput">-bind</tt> switch can takes the name of an <tt class="computeroutput">ns_set</tt>
containing keys for each bind variable named in the query, e.g.:</p><pre class="programlisting">
set bind_vars [ns_set create]
ns_set put $bind_vars user_id 123456
-ns_set put $bind_vars role "administrator"
+ns_set put $bind_vars role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -231,11 +230,11 @@
and map.role = :role
} -bind $bind_vars {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
</pre><p>
- Alternatively, as an argument to <tt>-bind</tt> you can specify a list of
+ Alternatively, as an argument to <tt class="computeroutput">-bind</tt> you can specify a list of
alternating name/value pairs for bind variables:
</p><pre class="programlisting">
@@ -245,22 +244,22 @@
where g.group_id = map.user_id
and map.user_id = :user_id
and map.role = :role
-} -bind [list user_id 123456 role "administrator"] {
+} -bind [list user_id 123456 role "administrator"] {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
- </pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</h4></div></div><p>
+ </pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</h4></div></div><div></div></div><p>
When processing a DML statement, Oracle coerces empty strings into
- <tt>null</tt>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the
- <tt>WHERE</tt> clause of a query, i.e.
- <tt>col = ''</tt> and
- <tt>col is null</tt> are not equivalent.)
+ <tt class="computeroutput">null</tt>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the
+ <tt class="computeroutput">WHERE</tt> clause of a query, i.e.
+ <tt class="computeroutput">col = ''</tt> and
+ <tt class="computeroutput">col is null</tt> are not equivalent.)
</p><p>As a result, when using bind variables, the only way to make Oracle set a
- column value to <tt>null</tt> is to set the corresponding bind variable
+ column value to <tt class="computeroutput">null</tt> is to set the corresponding bind variable
to the empty string, since a bind variable whose value is the string
- "null" will be interpreted as the literal string
- "null".</p><p>These Oracle quirks complicate the process of writing clear and abstract
+ "null" will be interpreted as the literal string
+ "null".</p><p>These Oracle quirks complicate the process of writing clear and abstract
DML difficult. Here is an example that illustrates why:</p><pre class="programlisting">
#
@@ -272,47 +271,47 @@
# );
#
-set bar ""
-set baz ""
+set bar ""
+set baz ""
-db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
+db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
#
-# the values of the "bar" and "baz" columns in the new row are both
+# the values of the "bar" and "baz" columns in the new row are both
# null, because Oracle has coerced the empty string (even for the
-# numeric column "bar") into null in both cases
+# numeric column "bar") into null in both cases
</pre><p>
Since databases other than Oracle do not coerce empty strings into
- <tt>null</tt>, this code has different semantics depending on the
+ <tt class="computeroutput">null</tt>, this code has different semantics depending on the
underlying database (i.e., the row that gets inserted may not have null as
its column values), which defeats the purpose of SQL abstraction.
</p><p>Therefore, the Database Access API provides a database-independent way to
- represent <tt>null</tt> (instead of the Oracle-specific idiom of the
- empty string): <tt>db_null</tt>.</p><p>Use it instead of the empty string whenever you want to set a column value
- explicitly to <tt>null</tt>, e.g.:</p><pre class="programlisting">
+ represent <tt class="computeroutput">null</tt> (instead of the Oracle-specific idiom of the
+ empty string): <tt class="computeroutput">db_null</tt>.</p><p>Use it instead of the empty string whenever you want to set a column value
+ explicitly to <tt class="computeroutput">null</tt>, e.g.:</p><pre class="programlisting">
set bar [db_null]
set baz [db_null]
-db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
+db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
#
-# sets the values for both the "bar" and "baz" columns to null
+# sets the values for both the "bar" and "baz" columns to null
- </pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-pooling"></a>Sequence Pooling</h3></div></div><p>
+ </pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-pooling"></a>Sequence Pooling</h3></div></div><div></div></div><p>
The database library can transparently maintain pools of sequence values, so
- that each request for a new sequence value (using <tt>db_nextval</tt>)
+ that each request for a new sequence value (using <tt class="computeroutput">db_nextval</tt>)
does not incur a roundtrip to the server. For instance, this functionality is
very useful in the security/sessions library, which very frequently allocates
- values from the <tt>sec_id_seq</tt> sequence. To utilize this
+ values from the <tt class="computeroutput">sec_id_seq</tt> sequence. To utilize this
functionality for a particular sequence, register the sequence to be pooled,
- either using the <tt>db_register_pooled_sequence</tt> procedure at server
+ either using the <tt class="computeroutput">db_register_pooled_sequence</tt> procedure at server
startup time, or by including a configuration parameter of the form
</p><pre class="programlisting">
PoolSequence.<span class="emphasis"><em>sequence_name_seq</em></span>=<span class="emphasis"><em>count</em></span>
</pre><p>
- in <span class="emphasis"><em>any</em></span> configuration section in the <tt>yourservername.ini</tt>
+ in <span class="emphasis"><em>any</em></span> configuration section in the <tt class="computeroutput">yourservername.ini</tt>
file, e.g., e.g.,
</p><pre class="programlisting">
@@ -324,49 +323,49 @@
startup. It will periodically scan pools and allocate new values for
sequences which are less than half-full. (This normally occurs every 60
seconds, and is configurable via the
- <tt>PooledSequenceUpdateInterval</tt> parameter in the
- <tt>[ns/server/</tt>
- <span class="emphasis"><em><tt>yourservername</tt></em></span>
- <tt>/acs/database]</tt> configuration
+ <tt class="computeroutput">PooledSequenceUpdateInterval</tt> parameter in the
+ <tt class="computeroutput">[ns/server/</tt>
+ <span class="emphasis"><em><tt class="computeroutput">yourservername</tt></em></span>
+ <tt class="computeroutput">/acs/database]</tt> configuration
section.)
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-api-basicapi"></a>Basic API</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-basicapi"></a>Basic API</h3></div></div><div></div></div><p>
The Database API has several functions that wrap familiar parts of the
AOLserver database API.
</p><p>
- Note that you never have to use <tt>ns_db</tt> anymore (including
- <tt>ns_db gethandle</tt>)! Just start doing stuff, and (if you want) call
- <tt>db_release_unused_handles</tt> when you're done as a hint to
+ Note that you never have to use <tt class="computeroutput">ns_db</tt> anymore (including
+ <tt class="computeroutput">ns_db gethandle</tt>)! Just start doing stuff, and (if you want) call
+ <tt class="computeroutput">db_release_unused_handles</tt> when you're done as a hint to
release the database handle.
</p><div class="variablelist"><dl><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_abort_transaction"></a>db_abort_transaction
</tt>
</span></dt><dd><pre class="programlisting">
db_abort_transaction
</pre><p>Aborts all levels of a transaction. That is if this is called within
several nested transactions, all of them are terminated. Use this insetead of
- <tt>db_dml "abort" "abort transaction"</tt>.
+ <tt class="computeroutput">db_dml "abort" "abort transaction"</tt>.
- </p></dd><dt><span class="term"><span class="strong"><tt><a name="devguide.dbapi_db_multirow"></a>db_multirow</tt></span></span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><span class="strong"><tt class="computeroutput"><a name="devguide.dbapi_db_multirow"></a>db_multirow</tt></span></span></dt><dd><pre class="programlisting">
<span class="strong">db_multirow</span> [ -local ] [ -append ] [ -extend <span class="emphasis"><em>column_list</em></span> ] \
<span class="emphasis"><em>var-name</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \
[ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
<span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span>
</pre><p>
- Performs the SQL query <tt>sql</tt>, saving results in variables
+ Performs the SQL query <tt class="computeroutput">sql</tt>, saving results in variables
of the form
- <tt><span class="emphasis"><em>var_name</em></span>:1</tt>, <tt><span class="emphasis"><em>var_name</em></span>:2</tt>, etc,
- setting <tt><span class="emphasis"><em>var_name</em></span>:rowcount</tt> to the total number
- of rows, and setting <tt><span class="emphasis"><em>var_name</em></span>:columns</tt> to a
+ <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:1</tt>, <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:2</tt>, etc,
+ setting <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:rowcount</tt> to the total number
+ of rows, and setting <tt class="computeroutput"><span class="emphasis"><em>var_name</em></span>:columns</tt> to a
list of column names.
</p><p>
Each row also has a column, rownum, automatically
added and set to the row number, starting with 1. Note that this will
override any column in the SQL statement named 'rownum', also if you're
using the Oracle rownum pseudo-column.
</p><p>
- If the <tt>-local</tt> is passed, the variables defined
+ If the <tt class="computeroutput">-local</tt> is passed, the variables defined
by db_multirow will be set locally (useful if you're compiling dynamic templates
in a function or similar situations).
</p><p>
@@ -379,19 +378,19 @@
multirow.
</p><p>
You may also add additional, computed columns to the multirow, using the
- <tt>-extend { <span class="emphasis"><em>col_1</em></span> <span class="emphasis"><em>col_2</em></span> ... }</tt> switch. This is
+ <tt class="computeroutput">-extend { <span class="emphasis"><em>col_1</em></span> <span class="emphasis"><em>col_2</em></span> ... }</tt> switch. This is
useful for things like constructing a URL for the object retrieved by
the query.
</p><p>
If you're constructing your multirow through multiple queries with the
same set of columns, but with different rows, you can use the
- <tt>-append</tt> switch. This causes the rows returned by this query
+ <tt class="computeroutput">-append</tt> switch. This causes the rows returned by this query
to be appended to the rows already in the multirow, instead of starting
a clean multirow, as is the normal behavior. The columns must match the
columns in the original multirow, or an error will be thrown.
</p><p>
- Your code block may call <tt>continue</tt> in order to skip a row
- and not include it in the multirow. Or you can call <tt>break</tt>
+ Your code block may call <tt class="computeroutput">continue</tt> in order to skip a row
+ and not include it in the multirow. Or you can call <tt class="computeroutput">break</tt>
to skip this row and quit looping.
</p><p>
@@ -408,22 +407,22 @@
}
</pre></dd><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_null"></a>db_null
</tt>
</span></dt><dd><pre class="programlisting">
-<tt>db_null</tt>
+<tt class="computeroutput">db_null</tt>
</pre><p>
Returns a value which can be used in a bind variable
to represent the SQL value
- <tt>null</tt>.
+ <tt class="computeroutput">null</tt>.
See <a href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and
Bind Variables</a> above.
</p></dd><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_foreach"></a>db_foreach
</tt>
@@ -433,31 +432,31 @@
<span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span>
</pre><p>
Performs the SQL query <span class="emphasis"><em>
- <tt>sql</tt>
+ <tt class="computeroutput">sql</tt>
</em></span>, executing
- <span class="emphasis"><em><tt>code_block
+ <span class="emphasis"><em><tt class="computeroutput">code_block
</tt></em></span> once for each row
with variables set to column values (or a set or array
populated if
- <tt>-column_array</tt> or
- <tt>column_set</tt> is
+ <tt class="computeroutput">-column_array</tt> or
+ <tt class="computeroutput">column_set</tt> is
specified). If the query returns no rows, executes
- <span class="emphasis"><em><tt>if_no_rows_block
+ <span class="emphasis"><em><tt class="computeroutput">if_no_rows_block
</tt></em></span> (if provided).
</p><p>Example:</p><pre class="programlisting">
-db_foreach select_foo "select foo, bar from greeble" {
- doc_body_append "<li>foo=$foo; bar=$bar\n"
+db_foreach select_foo "select foo, bar from greeble" {
+ doc_body_append "<li>foo=$foo; bar=$bar\n"
} if_no_rows {
- doc_body_append "<li>There are no greebles in the database.\n"
+ doc_body_append "<li>There are no greebles in the database.\n"
}
</pre><p>
- The code block may contain <tt>break</tt> statements (which terminate the
- loop and flush the database handle) and <tt>continue</tt> statements
+ The code block may contain <tt class="computeroutput">break</tt> statements (which terminate the
+ loop and flush the database handle) and <tt class="computeroutput">continue</tt> statements
(which continue to the next row of the loop). </p></dd><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_1row"></a>db_1row
</tt>
@@ -466,18 +465,18 @@
[ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
</pre><p>
Performs the SQL query <span class="emphasis"><em>
- <tt>sql</tt></em></span>,
+ <tt class="computeroutput">sql</tt></em></span>,
setting variables to column values. Raises an error if the
query does not return exactly 1 row.
</p><p>Example:</p><pre class="programlisting">
-db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
+db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
# Bombs if there's no such greeble!
# Now $foo and $bar are set.
</pre></dd><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_0or1row"></a>db_0or1row
</tt>
@@ -486,22 +485,22 @@
[ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
</pre><p>
Performs the SQL query
- <span class="emphasis"><em><tt>sql</tt></em></span>.
+ <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>.
If a row is returned, sets variables to column values and
returns 1. If no rows are returned, returns 0. If more
than one row is returned, throws an error.
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_nextval"></a>db_nextval</tt> </span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_nextval"></a>db_nextval</tt> </span></dt><dd><pre class="programlisting">
db_nextval <span class="emphasis"><em>sequence-name</em></span>
</pre><p>
Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a
- SQL statement like <tt>SELECT</tt>
- <span class="emphasis"><em><tt>sequence-name</tt></em></span><tt>.nextval FROM
+ SQL statement like <tt class="computeroutput">SELECT</tt>
+ <span class="emphasis"><em><tt class="computeroutput">sequence-name</tt></em></span><tt class="computeroutput">.nextval FROM
DUAL</tt>). If sequence pooling is enabled for the sequence, transparently
uses a value from the pool if available to save a round-trip to the database
(see <span class="emphasis"><em><a href="db-api.html#db-api-pooling">Sequence Pooling</a></em></span>).
</p></dd><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_register_pooled_sequence"></a>db_register_pooled_sequence
</tt>
@@ -511,137 +510,137 @@
size of <span class="emphasis"><em>pool-size</em></span> sequence values
(see <span class="emphasis"><em><a href="db-api.html#db-api-pooling">Sequence Pooling</a></em></span>).
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_string"></a>db_string</tt> </span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_string"></a>db_string</tt> </span></dt><dd><pre class="programlisting">
db_string <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -default <span class="emphasis"><em>default</em></span> ] [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>Returns the first column of the result of SQL query
- <span class="emphasis"><em><tt>sql</tt></em></span>.
- If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't return a
+ <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>.
+ If <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span> doesn't return a
row, returns
- <span class="emphasis"><em><tt>default</tt></em></span>
+ <span class="emphasis"><em><tt class="computeroutput">default</tt></em></span>
(or throws an error if
- <span class="emphasis"><em><tt>default</tt></em></span> is unspecified). Analogous to
- <tt>database_to_tcl_string</tt> and
- <tt>database_to_tcl_string_or_null</tt>.
+ <span class="emphasis"><em><tt class="computeroutput">default</tt></em></span> is unspecified). Analogous to
+ <tt class="computeroutput">database_to_tcl_string</tt> and
+ <tt class="computeroutput">database_to_tcl_string_or_null</tt>.
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_list"></a>db_list</tt></span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_list"></a>db_list</tt></span></dt><dd><pre class="programlisting">
db_list <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>Returns a Tcl list of the values in the first column of the result of SQL
query
- <span class="emphasis"><em><tt>sql</tt></em></span>.
- If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't
+ <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>.
+ If <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span> doesn't
return any rows, returns an empty list. Analogous to
- <tt>database_to_tcl_list</tt>.
+ <tt class="computeroutput">database_to_tcl_list</tt>.
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></span></dt><dd><pre class="programlisting">
db_list_of_lists <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
</pre><p>Returns a Tcl list, each element of which is a list of all column values
- in a row of the result of SQL query <span class="emphasis"><em><tt>sql</tt></em></span>. If
- <span class="emphasis"><em><tt>sql</tt></em></span> doesn't return any rows, returns an empty list.
- (Analogous to <tt>database_to_tcl_list_list</tt>.)
+ in a row of the result of SQL query <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. If
+ <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span> doesn't return any rows, returns an empty list.
+ (Analogous to <tt class="computeroutput">database_to_tcl_list_list</tt>.)
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_dml"></a>db_dml</tt></span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_dml"></a>db_dml</tt></span></dt><dd><pre class="programlisting">
db_dml <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \
[ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
[ -blobs <span class="emphasis"><em>blob_list</em></span> | -clobs <span class="emphasis"><em>clob_list</em></span> |
-blob_files <span class="emphasis"><em>blob_file_list</em></span> | -clob_files <span class="emphasis"><em>clob_file_list</em></span> ]
- </pre><p>Performs the DML or DDL statement <span class="emphasis"><em><tt>sql</tt></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL
+ </pre><p>Performs the DML or DDL statement <span class="emphasis"><em><tt class="computeroutput">sql</tt></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL
should return <span class="emphasis"><em>n</em></span> blobs or clobs into the bind variables
- <tt>:1</tt>, <tt>:2</tt>, ... :<span class="emphasis"><em><tt>n</tt></em></span>.
- <span class="emphasis"><em><tt>blobs</tt></em></span> or <span class="emphasis"><em><tt>clobs</tt></em></span>, if specified,
+ <tt class="computeroutput">:1</tt>, <tt class="computeroutput">:2</tt>, ... :<span class="emphasis"><em><tt class="computeroutput">n</tt></em></span>.
+ <span class="emphasis"><em><tt class="computeroutput">blobs</tt></em></span> or <span class="emphasis"><em><tt class="computeroutput">clobs</tt></em></span>, if specified,
should be a list of individual BLOBs or CLOBs to insert;
- <span class="emphasis"><em><tt>blob_files</tt></em></span> or <span class="emphasis"><em><tt>clob_files</tt></em></span>, if
+ <span class="emphasis"><em><tt class="computeroutput">blob_files</tt></em></span> or <span class="emphasis"><em><tt class="computeroutput">clob_files</tt></em></span>, if
specified, should be a list of <span class="emphasis"><em>paths to files</em></span> containing the data to
- insert. Only one of <tt>-blobs</tt>, <tt>-clobs</tt>,
- <tt>-blob_files</tt>, and <tt>-clob_files</tt> may be provided.</p><p>Example:</p><pre class="programlisting">
+ insert. Only one of <tt class="computeroutput">-blobs</tt>, <tt class="computeroutput">-clobs</tt>,
+ <tt class="computeroutput">-blob_files</tt>, and <tt class="computeroutput">-clob_files</tt> may be provided.</p><p>Example:</p><pre class="programlisting">
-db_dml insert_photos "
+db_dml insert_photos "
insert photos(photo_id, image, thumbnail_image)
values(photo_id_seq.nextval, empty_blob(), empty_blob())
returning image, thumbnail_image into :1, :2
- " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]
+ " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]
</pre><p>
- This inserts a new row into the <tt>photos</tt> table, with the contents
- of the files <tt>/var/tmp/the_photo</tt> and
- <tt>/var/tmp/the_thumbnail</tt> in the <tt>image</tt> and
- <tt>thumbnail</tt> columns, respectively.
+ This inserts a new row into the <tt class="computeroutput">photos</tt> table, with the contents
+ of the files <tt class="computeroutput">/var/tmp/the_photo</tt> and
+ <tt class="computeroutput">/var/tmp/the_thumbnail</tt> in the <tt class="computeroutput">image</tt> and
+ <tt class="computeroutput">thumbnail</tt> columns, respectively.
</p></dd><dt><span class="term">
- <tt><a name="devguide.dbapi_db_write_clob"></a>db_write_clob</tt>,
- <tt><a name="devguide.dbapi_db_write_blob"></a>db_write_blob</tt>,
- <tt><a name="devguide.dbapi_db_blob_get_file"></a>db_blob_get_file</tt>
+ <tt class="computeroutput"><a name="devguide.dbapi_db_write_clob"></a>db_write_clob</tt>,
+ <tt class="computeroutput"><a name="devguide.dbapi_db_write_blob"></a>db_write_blob</tt>,
+ <tt class="computeroutput"><a name="devguide.dbapi_db_blob_get_file"></a>db_blob_get_file</tt>
</span></dt><dd><pre class="programlisting">
db_write_clob <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
db_write_blob <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
db_blob_get_file <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
- </pre><p>Analagous to <tt>ns_ora write_clob/write_blob/blob_get_file</tt>.
+ </pre><p>Analagous to <tt class="computeroutput">ns_ora write_clob/write_blob/blob_get_file</tt>.
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></span></dt><dd><pre class="programlisting">
db_release_unused_handles
- </pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_transaction"></a>db_transaction</tt></span></dt><dd><pre class="programlisting">
+ </pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_transaction"></a>db_transaction</tt></span></dt><dd><pre class="programlisting">
db_transaction <span class="emphasis"><em>code_block</em></span> [ on_error { <span class="emphasis"><em>code_block</em></span> } ]
- </pre><p>Executes <span class="emphasis"><em><tt>code_block</tt></em></span> transactionally. Nested
- transactions are supported (<tt>end transaction</tt> is transparently
- <tt>ns_db dml</tt>'ed when the outermost transaction completes). The
- <tt>db_abort_transaction</tt> command can be used to abort all levels of
- transactions. It is possible to specify an optional <tt>on_error</tt>
+ </pre><p>Executes <span class="emphasis"><em><tt class="computeroutput">code_block</tt></em></span> transactionally. Nested
+ transactions are supported (<tt class="computeroutput">end transaction</tt> is transparently
+ <tt class="computeroutput">ns_db dml</tt>'ed when the outermost transaction completes). The
+ <tt class="computeroutput">db_abort_transaction</tt> command can be used to abort all levels of
+ transactions. It is possible to specify an optional <tt class="computeroutput">on_error</tt>
code block that will be executed if some code in <span class="emphasis"><em>code_block</em></span> throws
- an exception. The variable <tt>errmsg</tt> will be bound in that scope.
- If there is no <tt>on_error</tt> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting">
+ an exception. The variable <tt class="computeroutput">errmsg</tt> will be bound in that scope.
+ If there is no <tt class="computeroutput">on_error</tt> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting">
proc replace_the_foo { col } {
db_transaction {
- db_dml "delete from foo"
- db_dml "insert into foo(col) values($col)"
+ db_dml "delete from foo"
+ db_dml "insert into foo(col) values($col)"
}
}
proc print_the_foo {} {
- doc_body_append "foo is [db_string "select col from foo"]<br>\n"
+ doc_body_append "foo is [db_string "select col from foo"]<br>\n"
}
replace_the_foo 8
-print_the_foo ; # Writes out "foo is 8"
+print_the_foo ; # Writes out "foo is 8"
db_transaction {
replace_the_foo 14
- print_the_foo ; # Writes out "foo is 14"
- db_dml "insert into some_other_table(col) values(999)"
+ print_the_foo ; # Writes out "foo is 14"
+ db_dml "insert into some_other_table(col) values(999)"
...
db_abort_transaction
} on_error {
- doc_body_append "Error in transaction: $errmsg"
+ doc_body_append "Error in transaction: $errmsg"
}
-print_the_foo ; # Writes out "foo is 8"
+print_the_foo ; # Writes out "foo is 8"
- </pre></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_resultrows"></a>db_resultrows</tt></span></dt><dd><pre class="programlisting">
+ </pre></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_resultrows"></a>db_resultrows</tt></span></dt><dd><pre class="programlisting">
db_resultrows
</pre><p>Returns the number of rows affected or returned by the previous
statement.
- </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_with_handle"></a>db_with_handle</tt></span></dt><dd><pre class="programlisting">
+ </p></dd><dt><span class="term"><tt class="computeroutput"><a name="devguide.dbapi_db_with_handle"></a>db_with_handle</tt></span></dt><dd><pre class="programlisting">
db_with_handle <span class="emphasis"><em>var</em></span> <span class="emphasis"><em>code_block</em></span>
- </pre><p>Places a database handle into the variable <span class="emphasis"><em><tt>var</tt></em></span> and
- executes <span class="emphasis"><em><tt>code_block</tt></em></span>. This is useful when you don't
- want to have to use the new API (<tt>db_foreach</tt>,
- <tt>db_1row</tt>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting">
+ </pre><p>Places a database handle into the variable <span class="emphasis"><em><tt class="computeroutput">var</tt></em></span> and
+ executes <span class="emphasis"><em><tt class="computeroutput">code_block</tt></em></span>. This is useful when you don't
+ want to have to use the new API (<tt class="computeroutput">db_foreach</tt>,
+ <tt class="computeroutput">db_1row</tt>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting">
proc lookup_the_foo { foo } {
db_with_handle db {
- return [db_string unused "select ..."]
+ return [db_string unused "select ..."]
}
}
db_with_handle db {
# Now there's a database handle in $db.
- set selection [ns_db select $db "select foo from bar"]
+ set selection [ns_db select $db "select foo from bar"]
while { [ns_db getrow $db $selection] } {
set_variables_after_query
@@ -651,38 +650,38 @@
</pre></dd><dt><span class="term">
- <tt>
+ <tt class="computeroutput">
<a name="devguide.dbapi_db_nullify_empty_string"></a>db_nullify_empty_string
</tt>
</span></dt><dd><pre class="programlisting">
db_nullify_empty_string <span class="emphasis"><em>string</em></span>
</pre><p>For true SQL purists, we provide the convenience function
- <tt>db_nullify_empty_string</tt>, which returns
- [db_null] if its <span class="emphasis"><em><tt>string</tt></em></span> argument is the empty string
+ <tt class="computeroutput">db_nullify_empty_string</tt>, which returns
+ [db_null] if its <span class="emphasis"><em><tt class="computeroutput">string</tt></em></span> argument is the empty string
and can be used to encapsulate another Oracle quirk: </p><pre class="programlisting">
-set baz ""
+set baz ""
# Clean out the foo table
#
-db_dml unused "delete from foo"
+db_dml unused "delete from foo"
-db_dml unused "insert into foo(baz) values('$baz')"
+db_dml unused "insert into foo(baz) values('$baz')"
-set n_rows [db_string unused "select count(*) from foo where baz is null"]
+set n_rows [db_string unused "select count(*) from foo where baz is null"]
#
-# $n_rows is 1; in effect, the "baz is null" criterion is matching
+# $n_rows is 1; in effect, the "baz is null" criterion is matching
# the empty string we just inserted (because of Oracle's coercion
# quirk)
</pre><p>
- To balance out this asymmetry, you can explicitly set <tt>baz</tt> to
- <tt>null</tt> by writing:
+ To balance out this asymmetry, you can explicitly set <tt class="computeroutput">baz</tt> to
+ <tt class="computeroutput">null</tt> by writing:
</p><pre class="programlisting">
-db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
+db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
</pre></dd></dl></div><p>
</p><div class="cvstag">($Id$)</div><p>
- </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr><tr><td width="40%" align="left">The Request Processor </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Templates in OpenACS 5.0.0d</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/db-api.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr><tr><td width="40%" align="left">The Request Processor </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Templates in OpenACS 5.0.0a1</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/db-api.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/dev-guide.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/dev-guide.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�11.�Development Reference</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="tutorial-advanced.html" title="Advanced Topics"><link rel="next" href="packages.html" title="OpenACS 5.0.0d Packages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="dev-guide"></a>Chapter�11.�Development Reference</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="packages.html">OpenACS 5.0.0d Packages</a></dt><dt><a href="objects.html">OpenACS Data Models and the Object System</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 5.0.0d</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 5.0.0d Application Pages</a></dt><dt><a href="parties.html">Parties in OpenACS 5.0.0d</a></dt><dt><a href="permissions-tediously-explained.html">OpenACS 4.x Permissions Tediously Explained</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr><tr><td width="40%" align="left">Advanced Topics </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS 5.0.0d Packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/dev-guide.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�11.�Development Reference</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="tutorial-advanced.html" title="Advanced Topics"><link rel="next" href="packages.html" title="OpenACS 5.0.0a1 Packages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="dev-guide"></a>Chapter�11.�Development Reference</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="packages.html">OpenACS 5.0.0a1 Packages</a></dt><dt><a href="objects.html">OpenACS Data Models and the Object System</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 5.0.0a1</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 5.0.0a1 Application Pages</a></dt><dt><a href="parties.html">Parties in OpenACS 5.0.0a1</a></dt><dt><a href="permissions-tediously-explained.html">OpenACS 4.x Permissions Tediously Explained</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr><tr><td width="40%" align="left">Advanced Topics </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS 5.0.0a1 Packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/dev-guide.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/docbook-primer.html 20 Aug 2003 16:20:16 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 14 Oct 2003 11:02:58 -0000 1.14
@@ -1,21 +1,20 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Documentation Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="next" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="docbook-primer"></a>OpenACS Documentation Guide</h2></div></div><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Documentation Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="next" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="docbook-primer"></a>OpenACS Documentation Guide</h2></div></div><div></div></div><p>
By <a href="mailto:claus@arsdigita.com" target="_top">claus@arsdigita.com</a>, with
additions by <a href="mailto:rmello@fslc.usu.edu" target="_top">Roberto
Mello</a> and the OpenACS Community
- </p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-overview"></a>Overview of OpenACS 5.0.0d Documentation</h3></div></div><p>
+ </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-overview"></a>Overview of OpenACS 5.0.0a1 Documentation</h3></div></div><div></div></div><p>
ArsDigita created a good documentation ground for us to build
upon. Some sections of the documentation, however, lack details
and examples; others are simply nonexistant. Our goal is to give
OpenACS a superb documentation, so that users, developers and
administrators of OpenACS installations can enjoy the system.
</p><p>
- OpenACS™ is a powerful system, with
+ <span class="productname">OpenACS</span> 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.
</p><p>
- The documentation for OpenACS™ is
+ The documentation for <span class="productname">OpenACS</span> is
written using DocBook XML. The reasons why we are using
DocBook are explained in more details in the
<a href="docbook-primer.html#dbprimer-why">Why DocBook?</a> section. I will add the reasons why
@@ -28,11 +27,11 @@
SGML, with a couple extra rules. More details in the
<a href="http://en.tldp.org/LDP/LDP-Author-Guide/docbookxml.html" target="_top">LDP
Author Guide</a>.
- </li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-why"></a>Why DocBook?</h3></div></div><p>
+ </li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-why"></a>Why DocBook?</h3></div></div><div></div></div><p>
In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the
<a href="http://docbook.org/xml/index.html" target="_top">DocBook XML DTD</a>
- <a class="indexterm" name="id2968809"></a>
+ <a class="indexterm" name="id2852083"></a>
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.
@@ -53,15 +52,15 @@
list of elements</a> 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 <span class="strong">as long as you remember to</span>:
- <a class="indexterm" name="id2919695"></a>
+ <a class="indexterm" name="id2852154"></a>
</p><div class="itemizedlist"><ul type="disc"><li><p>
Always close your tags with corresponding end-tags and to
<span class="strong">not use other tag minimization</span>
</p></li><li><p>
Write all elements and attributes in lowercase
</p></li><li><p>
Quote all attributes
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-validation"></a>Tools</h3></div></div><p>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-validation"></a>Tools</h3></div></div><div></div></div><p>
You are going to need the following to work with the OpenACS
Docbook XML documentation:
</p><div class="itemizedlist"><ul type="disc"><li><a href="http://docbook.org/xml/index.html" target="_top">Docbook XML
@@ -72,7 +71,7 @@
Stylesheets</a> (docbook-xsl) - The stylesheets to convert
to HTML. We have been using a stylesheet based upon
NWalsh's chunk.xsl.
- </li><li><tt>xsltproc</tt> - The processor that
+ </li><li><tt class="computeroutput">xsltproc</tt> - The processor that
will take an XML document and, given a xsl stylesheet, convert
it to HTML. It needs libxml2 and libxslt (available in RPM and
DEB formats or from <a href="http://xmlsoft.org/" target="_top">xmlsoft.org</a>.
@@ -81,7 +80,7 @@
mode. We have a <a href="psgml-mode.html" title="Using PSGML mode in Emacs">intro to the PSGML
Mode in Emacs</a> as part of our documentation. You can
read about other editing tools in the <a href="http://en.tldp.org/LDP/LDP-Author-Guide/" target="_top">LDP Author Guide</a>.
- </li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-new-doc"></a>Writing New Docs</h3></div></div><p>
+ </li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-new-doc"></a>Writing New Docs</h3></div></div><div></div></div><p>
After you have the tools mentioned above, you need to define a
title for your document. Then start thinking about the possible
sections and subsections you will have in your document. Make
@@ -95,11 +94,11 @@
for acs-core-docs</a>, especially the <span class="emphasis"><em>
Detailed Design Documentation Template</em></span> and the
<span class="emphasis"><em>System/Application Requirements Template</em></span>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-structure"></a>Document Structure</h3></div></div><p>
- The documentation for each package will make up a little "book" that is structured like this
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-structure"></a>Document Structure</h3></div></div><div></div></div><p>
+ The documentation for each package will make up a little "book" that is structured like this
- examples are <span class="emphasis"><em>emphasized</em></span>:
- <a class="indexterm" name="id2924378"></a>
+ <a class="indexterm" name="id2852362"></a>
</p><pre class="programlisting">
book : <span class="strong">Docs for one package</span> - <span class="emphasis"><em>templating</em></span>
@@ -117,70 +116,70 @@
... : <span class="strong">...</span>
</pre><p>
The actual content is split up into documents that start at a
- <tt>sect1</tt>-level. These are then tied together in a top-level document that
+ <tt class="computeroutput">sect1</tt>-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. </p><p>For now you can take a look at the
<a href="http://openacs.org/cvs/openacs-4/packages/acs-core-docs/www/xml/engineering-standards" target="_top">sources of these DocBook documents</a>
to get an idea of how they are tied together.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-sections"></a>Headlines, Sections</h3></div></div><p>
- <a class="indexterm" name="id2924511"></a>
- Given that your job starts at the <tt>sect1</tt>-level, all your documents should open with a
- <a href="http://docbook.org/tdg/html/sect1.html" target="_top"><tt><sect1></tt></a>-tag and end
- with the corresponding <tt></sect1></tt>.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-sections"></a>Headlines, Sections</h3></div></div><div></div></div><p>
+ <a class="indexterm" name="id2850702"></a>
+ Given that your job starts at the <tt class="computeroutput">sect1</tt>-level, all your documents should open with a
+ <a href="http://docbook.org/tdg/html/sect1.html" target="_top"><tt class="computeroutput"><sect1></tt></a>-tag and end
+ with the corresponding <tt class="computeroutput"></sect1></tt>.
</p><p>
- <a class="indexterm" name="id2924554"></a>
- You need to feed every <tt><sect1></tt> two attributes. The first attribute,
- <tt>id</tt>, 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 <a href="docbook-primer.html#dbprimer-links" title="Links">the section called “Links”</a>).
- The value of <tt>id</tt> has to be unique
- throughout the book you're making since the <tt>id</tt>'s in your
- <tt>sect1</tt>'s will turn into filenames when the book is parsed into HTML.
+ <a class="indexterm" name="id2850734"></a>
+ You need to feed every <tt class="computeroutput"><sect1></tt> two attributes. The first attribute,
+ <tt class="computeroutput">id</tt>, 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 <a href="docbook-primer.html#dbprimer-links" title="Links">Section�, “Links”</a>).
+ The value of <tt class="computeroutput">id</tt> has to be unique
+ throughout the book you're making since the <tt class="computeroutput">id</tt>'s in your
+ <tt class="computeroutput">sect1</tt>'s will turn into filenames when the book is parsed into HTML.
</p><p>
- <a class="indexterm" name="id2920331"></a>
- The other attribute is <tt>xreflabel</tt>. The value of this is the text that will appear
- as the link when referring to this <tt>sect1</tt>.
+ <a class="indexterm" name="id2850778"></a>
+ The other attribute is <tt class="computeroutput">xreflabel</tt>. The value of this is the text that will appear
+ as the link when referring to this <tt class="computeroutput">sect1</tt>.
</p><p>
Right after the opening tag you put the title of the document - this is usually the same as
- <tt>xreflabel</tt>-attribute. E.g. the top level of the document you're
+ <tt class="computeroutput">xreflabel</tt>-attribute. E.g. the top level of the document you're
reading right now looks like this:
</p><pre class="programlisting">
- <sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
+ <sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
<title>aD DocBook Primer</title>
...
</sect1>
</pre><p>
- <a class="indexterm" name="id2920383"></a>
+ <a class="indexterm" name="id2850817"></a>
Inside this container your document will be split up into
- <a href="http://docbook.org/tdg/html/sect2.html" target="_top"><tt><sect2></tt></a>'s,
- each with the same requirements - <tt>id</tt> and <tt>xreflabel</tt>
- attributes, and a <tt><title></tt>-tag inside. Actually, the <tt>xreflabel</tt> is never required in sections, but it makes linking to that section a lot easier.
+ <a href="http://docbook.org/tdg/html/sect2.html" target="_top"><tt class="computeroutput"><sect2></tt></a>'s,
+ each with the same requirements - <tt class="computeroutput">id</tt> and <tt class="computeroutput">xreflabel</tt>
+ attributes, and a <tt class="computeroutput"><title></tt>-tag inside. Actually, the <tt class="computeroutput">xreflabel</tt> is never required in sections, but it makes linking to that section a lot easier.
</p><p>
When it comes to naming your
- <tt>sect2</tt>'s and below, prefix them with some abbreviation of the <tt>id</tt> in the <tt>sect1</tt> such as <tt>requirements-overview</tt>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-code"></a>Code</h3></div></div><p>
- <a class="indexterm" name="id2920486"></a>
+ <tt class="computeroutput">sect2</tt>'s and below, prefix them with some abbreviation of the <tt class="computeroutput">id</tt> in the <tt class="computeroutput">sect1</tt> such as <tt class="computeroutput">requirements-overview</tt>.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-code"></a>Code</h3></div></div><div></div></div><p>
+ <a class="indexterm" name="id2850891"></a>
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
- <a href="http://docbook.org/tdg/html/computeroutput.html" target="_top"><tt><computeroutput></tt></a>.
- This takes the place of the HTML-tag <tt><code></tt>
+ <a href="http://docbook.org/tdg/html/computeroutput.html" target="_top"><tt class="computeroutput"><computeroutput></tt></a>.
+ This takes the place of the HTML-tag <tt class="computeroutput"><code></tt>
</p><p>
For bigger chunks of code such as SQL-blocks, the tag
- <a href="http://docbook.org/tdg/html/programlisting.html" target="_top"><tt><programlisting></tt></a> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
+ <a href="http://docbook.org/tdg/html/programlisting.html" target="_top"><tt class="computeroutput"><programlisting></tt></a> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
automatically.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-links"></a>Links</h3></div></div><p>
- <a class="indexterm" name="id2920556"></a>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-links"></a>Links</h3></div></div><div></div></div><p>
+ <a class="indexterm" name="id2850949"></a>
Linking falls into two different categories: inside the book you're making and outside:
</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">1. Inside linking, cross-referencing other parts of your book</span></span></dt><dd><p>
- By having unique <tt>id</tt>'s you can cross-reference any part of your book
+ By having unique <tt class="computeroutput">id</tt>'s you can cross-reference any part of your book
with a simple tag, regardless of where that part is.
- </p><p><a class="indexterm" name="id2944799"></a>Check out how I link to a subsection of the Developer's Guide:</p><pre class="programlisting">
+ </p><p><a class="indexterm" name="id2850986"></a>Check out how I link to a subsection of the Developer's Guide:</p><pre class="programlisting">
Put this in your XML:
- Find information about creating a package in
- <xref linkend="packages-making-a-package"></xref>.
+ <xref linkend="packages-making-a-package"></xref>.
And the output is:
@@ -191,41 +190,41 @@
</pre><p>
Note that even though this is an empty tag, you have to either:
</p><div class="orderedlist"><ol type="1"><li><p>
- Provide the end-tag, <tt></xref></tt>, or
+ Provide the end-tag, <tt class="computeroutput"></xref></tt>, or
</p></li><li><p>
- Put a slash before the ending-bracket: <tt><xref linkend="blahblah"/></tt>
- </p></li></ol></div><p>If the section you link to hasn't a specified <tt>xreflabel</tt>-attribute,
+ Put a slash before the ending-bracket: <tt class="computeroutput"><xref linkend="blahblah"/></tt>
+ </p></li></ol></div><p>If the section you link to hasn't a specified <tt class="computeroutput">xreflabel</tt>-attribute,
the link is going to look like this:</p><pre class="programlisting">
Put this in your XML:
- Find information about what a package looks like in
- <xref linkend="packages-looks"></xref>.
+ <xref linkend="packages-looks"></xref>.
And the output is:
- Find information about what a package looks like in
- <a href="packages.html#packages-looks" title="What a Package Looks Like">the section called “What a Package Looks Like”</a>
+ <a href="packages.html#packages-looks" title="What a Package Looks Like">Section�, “What a Package Looks Like”</a>
</pre><p>
- Note that since I haven't provided an <tt>xreflabel</tt> for the subsection,
- <tt>packages-looks</tt>, the
+ Note that since I haven't provided an <tt class="computeroutput">xreflabel</tt> for the subsection,
+ <tt class="computeroutput">packages-looks</tt>, the
parser will try its best to explain where the link takes you.
</p></dd><dt><span class="term"><span class="strong">2. Linking outside the documentation</span></span></dt><dd><p>
- <a class="indexterm" name="id2944945"></a>
+ <a class="indexterm" name="id2851105"></a>
If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
a little different
- (<a href="http://docbook.org/tdg/html/ulink.html" target="_top"><tt><ulink></tt></a>):
+ (<a href="http://docbook.org/tdg/html/ulink.html" target="_top"><tt class="computeroutput"><ulink></tt></a>):
- </p><pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre><p>
+ </p><pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre><p>
....will create a hyper-link to Oracle in the HTML-version of the documentation.
</p><p><span class="strong">NOTE:</span> Do NOT use ampersands in your hyper links. These are reserved for referencing
- entities, which is exactly how you'll make an ampersand: <tt>&amp;</tt>
+ entities, which is exactly how you'll make an ampersand: <tt class="computeroutput">&amp;</tt>
- </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-graphics"></a>Graphics</h3></div></div><p>
+ </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-graphics"></a>Graphics</h3></div></div><div></div></div><p>
<span class="emphasis"><em><span class="strong">NOTE:</span> Currently this section currently only takes HTML-output into consideration -
not a printed version</em></span>
</p><p>
@@ -234,40 +233,40 @@
do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
</em></span>
</p><p>
- <a class="indexterm" name="id2945055"></a>
+ <a class="indexterm" name="id2851202"></a>
To insert a graphic we use the elements
- <a href="http://docbook.org/tdg/html/mediaobject.html" target="_top"><tt><mediaobject></tt></a>,
- <a href="http://docbook.org/tdg/html/imageobject.html" target="_top"><tt><imageobject></tt></a>,
+ <a href="http://docbook.org/tdg/html/mediaobject.html" target="_top"><tt class="computeroutput"><mediaobject></tt></a>,
+ <a href="http://docbook.org/tdg/html/imageobject.html" target="_top"><tt class="computeroutput"><imageobject></tt></a>,
and
- <a href="http://docbook.org/tdg/html/imagedata.html" target="_top"><tt><imagedata></tt></a>.
+ <a href="http://docbook.org/tdg/html/imagedata.html" target="_top"><tt class="computeroutput"><imagedata></tt></a>.
The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG)
and one for print (EPS). Finally you should provide a brief description wrapped in
- <a href="http://docbook.org/tdg/html/textobject.html" target="_top"><tt><textobject></tt></a> -
+ <a href="http://docbook.org/tdg/html/textobject.html" target="_top"><tt class="computeroutput"><textobject></tt></a> -
in HTML this will be the ALT text.
</p><pre class="programlisting">
<mediaobject>
<imageobject>
- <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
+ <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
</imageobject>
<imageobject>
- <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
+ <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
</imageobject>
<textobject>
<phrase>This is an image of the flow in the Request Processor</phrase>
</textobject>
</mediaobject>
</pre><p>
- Put your graphics in a separate directory ("images") and link to them
+ Put your graphics in a separate directory ("images") and link to them
only with relative paths.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-lists"></a>Lists</h3></div></div><p>
- <a class="indexterm" name="id2945156"></a>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-lists"></a>Lists</h3></div></div><div></div></div><p>
+ <a class="indexterm" name="id2851286"></a>
Here's how you make the DocBook equivalent of the three usual HTML-lists:
</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">1. How to make an <ul></span></span></dt><dd><p>
- Making an unordered list is pretty much like doing the same thing in HTML - if you close your <tt><li></tt>, that is. The only differences are that each list item has to be wrapped in something more, such as
- <tt><para></tt>, and that the tags are called
- <a href="http://docbook.org/tdg/html/itemizedlist.html" target="_top"><tt><itemizedlist></tt></a>
+ Making an unordered list is pretty much like doing the same thing in HTML - if you close your <tt class="computeroutput"><li></tt>, that is. The only differences are that each list item has to be wrapped in something more, such as
+ <tt class="computeroutput"><para></tt>, and that the tags are called
+ <a href="http://docbook.org/tdg/html/itemizedlist.html" target="_top"><tt class="computeroutput"><itemizedlist></tt></a>
and
- <a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt><listitem></tt></a>:
+ <a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt class="computeroutput"><listitem></tt></a>:
</p><pre class="programlisting">
<itemizedlist>
@@ -277,20 +276,20 @@
</itemizedlist>
</pre></dd><dt><span class="term"><span class="strong">2. How to make an <ol></span></span></dt><dd><p>
The ordered list is like the preceding, except that you use
- <a href="http://docbook.org/tdg/html/orderedlist.html" target="_top"><tt><orderedlist></tt></a> instead:</p><pre class="programlisting">
+ <a href="http://docbook.org/tdg/html/orderedlist.html" target="_top"><tt class="computeroutput"><orderedlist></tt></a> instead:</p><pre class="programlisting">
<orderedlist>
<listitem><para>Stuff goes here</para></listitem>
<listitem><para>More stuff goes here</para></listitem>
</orderedlist>
</pre></dd><dt><span class="term"><span class="strong">3. How to make a <dl></span></span></dt><dd><p>
- This kind of list is called a <tt>variablelist</tt> and these are the tags you'll need to
+ This kind of list is called a <tt class="computeroutput">variablelist</tt> and these are the tags you'll need to
make it happen:
- <a href="http://docbook.org/tdg/html/variablelist.html" target="_top"><tt><variablelist></tt></a>,
- <a href="http://docbook.org/tdg/html/varlistentry.html" target="_top"><tt><varlistentry></tt></a>,
- <a href="http://docbook.org/tdg/html/term.html" target="_top"><tt><term></tt></a> and
- <a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt><listitem></tt></a>:</p><pre class="programlisting">
+ <a href="http://docbook.org/tdg/html/variablelist.html" target="_top"><tt class="computeroutput"><variablelist></tt></a>,
+ <a href="http://docbook.org/tdg/html/varlistentry.html" target="_top"><tt class="computeroutput"><varlistentry></tt></a>,
+ <a href="http://docbook.org/tdg/html/term.html" target="_top"><tt class="computeroutput"><term></tt></a> and
+ <a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt class="computeroutput"><listitem></tt></a>:</p><pre class="programlisting">
<variablelist>
<varlistentry>
@@ -304,14 +303,14 @@
</varlistentry>
</variablelist>
- </pre></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-tables"></a>Tables</h3></div></div><p>
- <a class="indexterm" name="id2945391"></a>
+ </pre></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-tables"></a>Tables</h3></div></div><div></div></div><p>
+ <a class="indexterm" name="id2851482"></a>
DocBook supports several types of tables, but in most cases, the
- <a href="http://docbook.org/tdg/html/informaltable.html" target="_top"><tt><informaltable></tt></a>
+ <a href="http://docbook.org/tdg/html/informaltable.html" target="_top"><tt class="computeroutput"><informaltable></tt></a>
is enough:
</p><pre class="programlisting">
- <informaltable frame="all">
- <tgroup cols="3">
+ <informaltable frame="all">
+ <tgroup cols="3">
<tbody>
<row>
@@ -339,26 +338,26 @@
With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table:
</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td>a1</td><td>b1</td><td>c1</td></tr><tr><td>a2</td><td>b2</td><td>c2</td></tr><tr><td>a3</td><td>b3</td><td>c3</td></tr></tbody></table></div></blockquote></div><p>
If you want cells to span more than one row or column, it gets a bit more complicated - check out
- <a href="http://docbook.org/tdg/html/table.html" target="_top"><tt><table></tt></a>
+ <a href="http://docbook.org/tdg/html/table.html" target="_top"><tt class="computeroutput"><table></tt></a>
for an example.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-emphasis"></a>Emphasis</h3></div></div><p>
- <a class="indexterm" name="id2933419"></a>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-emphasis"></a>Emphasis</h3></div></div><div></div></div><p>
+ <a class="indexterm" name="id2851622"></a>
Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -
- <a href="http://docbook.org/tdg/html/emphasis.html" target="_top"><tt><emphasis></tt></a>.
+ <a href="http://docbook.org/tdg/html/emphasis.html" target="_top"><tt class="computeroutput"><emphasis></tt></a>.
</p><p>
- The <tt><emphasis></tt> tag defaults to italics when parsed. If you're looking for
- emphasizing with bold type, use <tt><emphasis role="strong"></tt>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-indexing"></a>Indexing Your DocBook Documents</h3></div></div><p>
+ The <tt class="computeroutput"><emphasis></tt> tag defaults to italics when parsed. If you're looking for
+ emphasizing with bold type, use <tt class="computeroutput"><emphasis role="strong"></tt>.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-indexing"></a>Indexing Your DocBook Documents</h3></div></div><div></div></div><p>
Marking up index-words may not have any importance for the HTML-output, but in order to make it easier to make
a nice print-version of the documentation, you should mark up words in your documents that you would like to
see show up in an index one day.
</p><p>
Use
- <a href="http://docbook.org/tdg/html/indexterm.html" target="_top"><tt><indexterm></tt></a>,
- <a href="http://docbook.org/tdg/html/primary.html" target="_top"><tt><primary></tt></a> and
- <a href="http://docbook.org/tdg/html/secondary.html" target="_top"><tt><secondary></tt></a>
+ <a href="http://docbook.org/tdg/html/indexterm.html" target="_top"><tt class="computeroutput"><indexterm></tt></a>,
+ <a href="http://docbook.org/tdg/html/primary.html" target="_top"><tt class="computeroutput"><primary></tt></a> and
+ <a href="http://docbook.org/tdg/html/secondary.html" target="_top"><tt class="computeroutput"><secondary></tt></a>
for this. See these links for an explanation.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-converting"></a>Converting to HTML</h3></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-converting"></a>Converting to HTML</h3></div></div><div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
This section is quoted almost verbatim from the LDP Author Guide.
</div><p>
Once you have the <a href="docbook-primer.html#dbprimer-validation">Docbook Tools</a>
@@ -386,10 +385,10 @@
following command:
</p><pre class="programlisting">
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
- </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="db-primer-further-reading"></a>Further Reading</h3></div></div><div class="itemizedlist"><ul type="disc"><li>
+ </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="db-primer-further-reading"></a>Further Reading</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li>
The <a href="http://en.tldp.org/LDP/LDP-Author-Guide/" target="_top">LDP Author
Guide</a> has a lot of good information, a table of
- docbook elements and their "look" in HTML and lots of good links
+ docbook elements and their "look" in HTML and lots of good links
for tools.
</li><li><p>
<a href="mailto:lutter@arsdigita.com" target="_top">David
@@ -411,14 +410,14 @@
</p></li><li><p>
In the process of transforming your HTML into XML,
<a href="http://tidy.sourceforge.net/" target="_top">HTML tidy</a>
- can be a a handy tool to make your HTML "regexp'able".
+ can be a a handy tool to make your HTML "regexp'able".
<a href="mailto:bcalef@arsdigita.com" target="_top">Brandoch Calef</a> has made a
<a href="http://developer.arsdigita.com/working-papers/bcalef/html-to-docbook.html#html2docbook" target="_top">Perl script</a>
that gets you most of the way.
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.4</td><td>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.4</td><td>
Fixed some typos.
</td><td>8/3/2002</td><td>Vinod Kurup</td></tr><tr><td>0.3</td><td>
Added OpenACS information, updated tools, added
extra links and added info to the Publishing section.
- </td><td>12/24/2001</td><td>Roberto Mello</td></tr><tr><td>0.2</td><td>Changed recommendation from <phrase> to <emphasis role="strong"></td><td>01/19/2000</td><td>Claus Rasmussen</td></tr><tr><td>0.1</td><td>Creation</td><td>12/2000</td><td>Claus Rasmussen</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�12.�Engineering Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Using PSGML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/docbook-primer.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </td><td>12/24/2001</td><td>Roberto Mello</td></tr><tr><td>0.2</td><td>Changed recommendation from <phrase> to <emphasis role="strong"></td><td>01/19/2000</td><td>Claus Rasmussen</td></tr><tr><td>0.1</td><td>Creation</td><td>12/2000</td><td>Claus Rasmussen</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�12.�Engineering Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Using PSGML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/docbook-primer.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,8 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Constraint naming standard</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="next" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-constraint-naming"></a>Constraint naming standard</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:mbryzek@arsdigita.com" target="_top">mbryzek@arsdigita.com</a></p><br>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Constraint naming standard</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="next" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-constraint-naming"></a>Constraint naming standard</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:mbryzek@arsdigita.com" target="_top">mbryzek@arsdigita.com</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div><div></div></div><p>
Constraint naming standard is important for one reason: The SYS_* name oracle
assigns to unnamed constraints is not very understandable. By correctly
naming all contraints, we can quickly associate a particular constraint
@@ -11,14 +10,14 @@
</p><div>Why do we need a naming convention? </div><p>
<a href="http://oradoc.photo.net/ora8doc/DOC/server803/A54647_01/ch2.htm#2956" target="_top">Oracle limits names</a>,
in general, to 30 characters, which is hardly enough for a human readable constraint name.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-abbr"></a>Abbreviations</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-abbr"></a>Abbreviations</h3></div></div><div></div></div><p>
We propose the following naming convention for all constraints, with
the following abbreviations taken from Oracle Docs at
<a href="http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953" target="_top">
http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953</a>.
Note that we shortened all of the constraint abbrevations to
two characters to save room.
-</p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Constraint type</th><th>Abbreviation</th></tr></thead><tbody><tr><td>references (foreign key)</td><td>fk</td></tr><tr><td>unique</td><td>un</td></tr><tr><td>primary key</td><td>pk</td></tr><tr><td>check</td><td>ck</td></tr><tr><td>not null</td><td>nn</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-format"></a>Format of constraint name</h3></div></div><p>
+</p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Constraint type</th><th>Abbreviation</th></tr></thead><tbody><tr><td>references (foreign key)</td><td>fk</td></tr><tr><td>unique</td><td>un</td></tr><tr><td>primary key</td><td>pk</td></tr><tr><td>check</td><td>ck</td></tr><tr><td>not null</td><td>nn</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-format"></a>Format of constraint name</h3></div></div><div></div></div><p>
<table name>_<column_name>_<constraint abbreviation>
</p><p>
In reality, this won't be possible because of the character limitation on
@@ -28,7 +27,7 @@
</p></li><li><p> Truncate the column name until it fits.</p></li></ol></div><p>
If the constraint name is still too long, you should consider rewriting your
entire data model :)
-</p><p><span class="strong">Notes:</span></p><div class="itemizedlist"><ul type="disc"><li><p> If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints</p></li><li><p> If you are defining a multi column constraint, try to truncate the two column names evenly </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-example"></a>Example</h3></div></div><pre class="programlisting">
+</p><p><span class="strong">Notes:</span></p><div class="itemizedlist"><ul type="disc"><li><p> If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints</p></li><li><p> If you are defining a multi column constraint, try to truncate the two column names evenly </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-example"></a>Example</h3></div></div><div></div></div><pre class="programlisting">
create table example_topics (
topic_id integer
constraint example_topics_topic_id_pk
@@ -52,7 +51,7 @@
constraint cne_example_id_one_line_unq unique(example_id, one_line_description)
);
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-pk"></a>Why it's good to name primary keys</h3></div></div><p>
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-pk"></a>Why it's good to name primary keys</h3></div></div><div></div></div><p>
Naming primary keys might not have any obvious advantages. However, here's an
example where naming the primary key really helps (and this is by no means
a rare case!
@@ -71,15 +70,15 @@
3 1 INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI
QUE)
</pre><p>
-Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace
+Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace
and know exactly which table oracle is using at each step?
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-nn"></a>Naming not null constraints is optional...</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-nn"></a>Naming not null constraints is optional...</h3></div></div><div></div></div><p>
ArsDigita is split on whether or not we should be naming not null constraints... So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not a requirement at ArsDigita.
</p><p>
</p><div>About Naming the not null constraints</div><p>
</p><p>
-Though naming "not null" constraints doesn't help immeditately in error
+Though naming "not null" constraints doesn't help immeditately in error
debugging (e.g. the error will say something like
-"Cannot insert null value into column"), we recommend naming not null
+"Cannot insert null value into column"), we recommend naming not null
constraints to be consistent in our naming of all constraints.
</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr><tr><td width="40%" align="left">Release Version Numbering </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> ACS File Naming and Formatting Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/eng-standards-constraint-naming.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,82 +1,81 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>ACS File Naming and Formatting Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:michael@arsdigita.com" target="_top">michael@arsdigita.com</a> and
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>ACS File Naming and Formatting Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:michael@arsdigita.com" target="_top">michael@arsdigita.com</a> and
<a href="mailto:aure@arsdigita.com" target="_top">aure@arsdigita.com</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p>
To ensure consistency (and its collateral benefit, maintainability),
we define and adhere to standards in the following areas:
-</p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div><p>
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div><div></div></div><p>
Usually we organize our files so that they mainly serve one of the following three purposes:
</p><div class="itemizedlist"><ul type="disc"><li><p> displaying objects and their properties</p></li><li><p> manipulating or acting on objects in some way (by creating, editing, linking, etc)</p></li><li><p> housing procedures, packages, data models and other prerequisite code
Essentially, we want our files named in a fashion that reflects their purpose.</p></li></ul></div><p>
Under the page root (and the template root if using the <a href="style" target="_top">Style package</a>):
</p><div class="itemizedlist"><ul type="disc"><li><p>For naming files that enable a specific action on an object, use this format:</p><div class="blockquote"><blockquote class="blockquote"><p>
-<span class="emphasis"><em><tt>object-verb.extension</tt></em></span>
+<span class="emphasis"><em><tt class="computeroutput">object-verb.extension</tt></em></span>
</p></blockquote></div><p>
For example, the page to erase a user's portrait from the database is
-<tt>/admin/users/portrait-erase.tcl</tt>.
+<tt class="computeroutput">/admin/users/portrait-erase.tcl</tt>.
</p></li><li><p>However, modules typically deal with only one primary type of object -
e.g.,
the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages
-for the Bookmarks module live in the <tt>/bookmarks/</tt>
-directory, and so there is no need to name the bookmark editing page with a redundant url: <tt>/bookmarks/bookmark-edit.tcl</tt>. Instead, we omit the object type, and use this convention:
+for the Bookmarks module live in the <tt class="computeroutput">/bookmarks/</tt>
+directory, and so there is no need to name the bookmark editing page with a redundant url: <tt class="computeroutput">/bookmarks/bookmark-edit.tcl</tt>. Instead, we omit the object type, and use this convention:
</p><div class="blockquote"><blockquote class="blockquote"><p>
-<span class="emphasis"><em><tt>verb.extension</tt></em></span>
+<span class="emphasis"><em><tt class="computeroutput">verb.extension</tt></em></span>
</p></blockquote></div><p>
-Thus, the page to edit a bookmark is <tt>/bookmarks/edit.tcl</tt>.
+Thus, the page to edit a bookmark is <tt class="computeroutput">/bookmarks/edit.tcl</tt>.
</p></li><li><p>For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:</p><div class="blockquote"><blockquote class="blockquote"><p>
-<tt>one.</tt><span class="emphasis"><em><tt>extension</tt></em></span>
+<tt class="computeroutput">one.</tt><span class="emphasis"><em><tt class="computeroutput">extension</tt></em></span>
</p></blockquote></div><p>
For example, the page to view one bookmark is
-<tt>/bookmarks/one.tcl</tt>. Note that no verb is necessary for display-type files.
+<tt class="computeroutput">/bookmarks/one.tcl</tt>. Note that no verb is necessary for display-type files.
</p></li><li><p>Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:</p><div class="blockquote"><blockquote class="blockquote"><p>
-<span class="emphasis"><em><tt>object.extension</tt></em></span>
+<span class="emphasis"><em><tt class="computeroutput">object.extension</tt></em></span>
</p></blockquote></div><p>
For example, the page to view the properties of an
ecommerce product is
-<tt>/ecommerce/product.tcl</tt>.
-</p></li><li><p>For naming files in a page flow, use the convention:</p><div class="itemizedlist"><ul type="circle"><li><p><span class="emphasis"><em><tt>foobar.extension</tt></em></span> (Step 1)</p></li><li><p><span class="emphasis"><em><tt>foobar-2.extension</tt></em></span> (Step 2)</p></li><li><p>...</p></li><li><p><span class="emphasis"><em><tt>foobar-N.extension</tt></em></span> (Step N)</p></li></ul></div><p>
-where <span class="emphasis"><em><tt>foobar</tt></em></span> is determined by the above
+<tt class="computeroutput">/ecommerce/product.tcl</tt>.
+</p></li><li><p>For naming files in a page flow, use the convention:</p><div class="itemizedlist"><ul type="circle"><li><p><span class="emphasis"><em><tt class="computeroutput">foobar.extension</tt></em></span> (Step 1)</p></li><li><p><span class="emphasis"><em><tt class="computeroutput">foobar-2.extension</tt></em></span> (Step 2)</p></li><li><p>...</p></li><li><p><span class="emphasis"><em><tt class="computeroutput">foobar-N.extension</tt></em></span> (Step N)</p></li></ul></div><p>
+where <span class="emphasis"><em><tt class="computeroutput">foobar</tt></em></span> is determined by the above
rules.
</p><p>
Typically, we use a three-step page flow when taking user information:
-</p><div class="orderedlist"><ol type="1"><li><p>Present a form to the user</p></li><li><p>Present a confirmation page to the user</p></li><li><p>Perform the database transaction, then redirect</p></li></ol></div></li><li><p>Put data model files in <tt>/www/doc/sql</tt>, and name them
+</p><div class="orderedlist"><ol type="1"><li><p>Present a form to the user</p></li><li><p>Present a confirmation page to the user</p></li><li><p>Perform the database transaction, then redirect</p></li></ol></div></li><li><p>Put data model files in <tt class="computeroutput">/www/doc/sql</tt>, and name them
for the modules towards which they are used:
</p><div class="blockquote"><blockquote class="blockquote"><p>
-<span class="emphasis"><em><tt>module</tt></em></span><tt>.sql</tt>
+<span class="emphasis"><em><tt class="computeroutput">module</tt></em></span><tt class="computeroutput">.sql</tt>
</p></blockquote></div></li></ul></div><p>
In the Tcl library directory:
</p><div class="itemizedlist"><ul type="disc"><li><p>For files that contain module-specific procedures, use the
convention:</p><div class="blockquote"><blockquote class="blockquote"><p>
-<span class="emphasis"><em><tt>module</tt></em></span><tt>-procs.tcl</tt>
+<span class="emphasis"><em><tt class="computeroutput">module</tt></em></span><tt class="computeroutput">-procs.tcl</tt>
</p></blockquote></div></li><li><p>For files that contain procedures that are part of the core ACS,
use the convention:</p><div class="blockquote"><blockquote class="blockquote"><p>
-<tt>ad-</tt><span class="emphasis"><em>description</em></span><tt>-procs.tcl</tt>
-</p></blockquote></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div><p>
+<tt class="computeroutput">ad-</tt><span class="emphasis"><em>description</em></span><tt class="computeroutput">-procs.tcl</tt>
+</p></blockquote></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div><div></div></div><p>
File names also appear <span class="emphasis"><em>within</em></span> pages, as linked URLs and
form targets. When they do, always use <a href="abstract-url" target="_top">abstract
-URLs</a> (e.g., <tt>user-delete</tt> instead of
-<tt>user-delete.tcl</tt>), because they enhance maintainability.
+URLs</a> (e.g., <tt class="computeroutput">user-delete</tt> instead of
+<tt class="computeroutput">user-delete.tcl</tt>), because they enhance maintainability.
</p><p>
Similarly, when linking to the index page of a directory, do not
-explicitly name the index file (<tt>index.tcl</tt>,
-<tt>index.adp</tt>, <tt>index.html</tt>, etc.). Instead, use
+explicitly name the index file (<tt class="computeroutput">index.tcl</tt>,
+<tt class="computeroutput">index.adp</tt>, <tt class="computeroutput">index.html</tt>, etc.). Instead, use
just the directory name, for both relative links
-(<tt>subdir/</tt>) and absolute links
-(<tt>/top-level-dir/</tt>). If linking to the directory in which
-the page is located, use the empty string (<tt>""</tt>), which
+(<tt class="computeroutput">subdir/</tt>) and absolute links
+(<tt class="computeroutput">/top-level-dir/</tt>). If linking to the directory in which
+the page is located, use the empty string (<tt class="computeroutput">""</tt>), which
browsers will resolve correctly.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div><div></div></div><p>
Include the appropriate standard header in all scripts. The first
line should be a comment specifying the file path relative to the
ACS root directory. e.g.
-</p><div class="blockquote"><blockquote class="blockquote"><p><tt>
+</p><div class="blockquote"><blockquote class="blockquote"><p><tt class="computeroutput">
# /www/index.tcl
</tt></p></blockquote></div><p>
or
-</p><div class="blockquote"><blockquote class="blockquote"><p><tt>
+</p><div class="blockquote"><blockquote class="blockquote"><p><tt class="computeroutput">
# /tcl/module-defs.tcl
</tt></p></blockquote></div><p>
For static content files (html or adp), include a CVS identification tag as a
@@ -96,7 +95,7 @@
This can be at the top or bottom of the file.
</p><div>Using ad_page_contract</div><p>
For non-library Tcl files (those not in the private Tcl directory),
-use <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract"><tt>ad_page_contract</tt></a>
+use <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract"><tt class="computeroutput">ad_page_contract</tt></a>
after the file path comment (this supersedes set_the_usual_form_variables and
ad_return_complaint). Here is an example of using
ad_page_contract, which serves both documentation and page input
@@ -120,32 +119,32 @@
{persistent_cookie_p f}
}
</pre><p>
-Salient features of <tt>ad_page_contract</tt>:
+Salient features of <tt class="computeroutput">ad_page_contract</tt>:
</p><div class="itemizedlist"><ul type="disc"><li><p>A mandatory documentation string is the first argument. This has
the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations. </p></li><li><p>The second argument specifies the page
inputs. The syntax for switches/flags (e.g. multiple-list, array,
etc.) uses a colon (:) followed by any number of flags
separated by commas (,),
-e.g. <tt>foo:integer,multiple,trim</tt>. In particular, <tt>multiple</tt> and
-<tt>array</tt> are the flags that correspond to the old
-<tt>ad_page_variables</tt> flags.</p></li><li><p>There are new flags: <tt>trim</tt>, <tt>notnull</tt> and
-<tt>optional</tt>. They do what you'd expect; values will not be
+e.g. <tt class="computeroutput">foo:integer,multiple,trim</tt>. In particular, <tt class="computeroutput">multiple</tt> and
+<tt class="computeroutput">array</tt> are the flags that correspond to the old
+<tt class="computeroutput">ad_page_variables</tt> flags.</p></li><li><p>There are new flags: <tt class="computeroutput">trim</tt>, <tt class="computeroutput">notnull</tt> and
+<tt class="computeroutput">optional</tt>. They do what you'd expect; values will not be
trimmed, unless you mark them for it; empty strings are valid input, unless
you specify notnull; and a specified variable will be considered required,
-unless you declare it optional.</p></li><li><p><tt>ad_page_contract</tt> can do validation for you: the flags <tt>integer</tt>
-and <tt>sql_identifier</tt> will make sure that the values
-supplied are integers/sql_identifiers. The <tt>integer</tt> flag
+unless you declare it optional.</p></li><li><p><tt class="computeroutput">ad_page_contract</tt> can do validation for you: the flags <tt class="computeroutput">integer</tt>
+and <tt class="computeroutput">sql_identifier</tt> will make sure that the values
+supplied are integers/sql_identifiers. The <tt class="computeroutput">integer</tt> flag
will also trim leading zeros. Note that unless you specify
-<tt>notnull</tt>, both will accept the empty string.
-</p></li><li><p>Note that <tt>ad_page_contract</tt> does not generate
+<tt class="computeroutput">notnull</tt>, both will accept the empty string.
+</p></li><li><p>Note that <tt class="computeroutput">ad_page_contract</tt> does not generate
QQvariables, which were automatically created by ad_page_variables and
set_the_usual_form_variables. The use of bind variables makes such
previous variable syntax obsolete.
</p></li></ul></div><div>Using ad_library</div><p>
-For shared Tcl library files, use <a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library"><tt>ad_library</tt></a> after
+For shared Tcl library files, use <a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library"><tt class="computeroutput">ad_library</tt></a> after
the file path comment. Its only argument is a doc_string in the
standard (javadoc-style) format, like
-<tt>ad_page_contract</tt>. Don't forget to put the @cvs-id in
+<tt class="computeroutput">ad_page_contract</tt>. Don't forget to put the @cvs-id in
there. Here is an example of using ad_library:
</p><pre class="programlisting">
# tcl/wp-defs.tcl
@@ -168,54 +167,54 @@
--
-- <a href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id$</a>
</pre><p>
-Of course, replace "<tt>--</tt>" with the comment delimiter
+Of course, replace "<tt class="computeroutput">--</tt>" with the comment delimiter
appropriate for the language in which you are programming.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div><div></div></div><p>
Construct the page as one Tcl variable (name it
-<tt>page_content</tt>), and then send it back to the browser with
-one call to <tt>doc_return</tt>, which will call
+<tt class="computeroutput">page_content</tt>), and then send it back to the browser with
+one call to <tt class="computeroutput">doc_return</tt>, which will call
db_release_unused_handles prior to executing ns_return, effectively
combining the two operations.
</p><p>
For example:
</p><pre class="programlisting">
-set page_content "[ad_header "<span class="emphasis"><em>Page Title</em></span>"]
+set page_content "[ad_header "<span class="emphasis"><em>Page Title</em></span>"]
<h2><span class="emphasis"><em>Page Title</em></span></h2>
<hr>
<ul>
-"
+"
db_foreach get_row_info {
select row_information
from bar
} {
- append page_content "<li><span class="emphasis"><em>row_information</em></span>\n"
+ append page_content "<li><span class="emphasis"><em>row_information</em></span>\n"
}
-append page_content "</ul>
+append page_content "</ul>
-[ad_footer]"
+[ad_footer]"
doc_return 200 text/html $page_content
</pre><p>
-The old convention was to call <tt>ReturnHeaders</tt> and
-then <tt>ns_write</tt> for each distinct chunk of the page. This
+The old convention was to call <tt class="computeroutput">ReturnHeaders</tt> and
+then <tt class="computeroutput">ns_write</tt> for each distinct chunk of the page. This
approach has the disadvantage of tying up a scarce and valuable
resource (namely, a database handle) for an unpredictable amount of
time while sending packets back to the browser, and so it should be
avoided in most cases. (On the other hand, for a page that requires an
expensive database query, it's better to call
-<tt>ad_return_top_of_page</tt>
+<tt class="computeroutput">ad_return_top_of_page</tt>
first, so that the user is not left to stare at an empty page while
the query is running.)
</p><p>
Local procedures (i.e., procedures defined and used only within one
-page) should be prefixed with "<span class="emphasis"><em><tt>module_</tt></em></span>" and
+page) should be prefixed with "<span class="emphasis"><em><tt class="computeroutput">module_</tt></em></span>" and
should be used rarely, only when they are exceedingly useful.
</p><p>
All files that prepare HTML to display should end with [ad_footer] or
@@ -226,7 +225,7 @@
edit ad_header (which quite possibly can start a <table>) and
ad_footer (which may need to end the table started in ad_footer) to
customize the look and feel of the entire site.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div><div></div></div><p>
Further standards for Tcl library files are under discussion; we plan to
include naming conventions for procs.
</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr><tr><td width="40%" align="left">Constraint naming standard </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> PL/SQL Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/eng-standards-filenaming.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>PL/SQL Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="next" href="cvs-tips.html" title="Appendix�C.�Using CVS with an OpenACS Site"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div><div class="authorblurb"><p><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>PL/SQL Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="next" href="cvs-tips.html" title="Appendix�A.�Using CVS with an OpenACS Site"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div><div></div></div><div class="authorblurb"><p><p>
By <a href="mailto:richardl@arsdigita.com" target="_top">richardl@arsdigita.com</a>
and <a href="mailto:yon@arsdigita.com" target="_top">yon@arsdigita.com</a>
</p><br>
@@ -12,19 +11,19 @@
our product will be useful long after the current people building and
maintaining it are around. Following are some standards and guidelines
that will help us achieve this goal:
-</p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-plsql-general"></a>General</h3></div></div><div class="orderedlist"><ol type="1"><li><p>
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-plsql-general"></a>General</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p>
All PL/SQL code must be well documented. We must write code that
is maintainable by others, this is especially true in our case
because we are building an open source toolkit than anyone can
download and browse the source code. So document like you are
- trying to impress your "Introduction to Programming" professor or
+ trying to impress your "Introduction to Programming" professor or
TA.
</p></li><li><p>
It is important to be consistent throughout an application as much
as is possible given the nature of team development. This means
carrying style and other conventions suchs as naming within an
application, not just within one file.
- </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-plsql-code"></a>Code</h3></div></div><div class="orderedlist"><ol type="1"><li><p>
+ </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-plsql-code"></a>Code</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p>
Encapsulation of related fuctionality is key to maintainability
and upgradeability of our software. Try to bundle your code into
<a href="http://oradoc.photo.net/ora816/appdev.816/a77069/08_packs.htm#4376" target="_top">packages</a>
@@ -55,16 +54,16 @@
show errors
</pre></li><li><p>
- Always use <tt>create or replace procedure|function
+ Always use <tt class="computeroutput">create or replace procedure|function
<proc_or_func_name></tt>. It makes reloading packages much
easier and painless to someone who is upgrading or fixing a bug.
</p></li><li><p>
- Always qualify <tt>end</tt> statements, i.e., the
- <tt>end</tt> statement for a package should be <tt>end
- <package_name>;</tt>, not just <tt>end;</tt>; same
+ Always qualify <tt class="computeroutput">end</tt> statements, i.e., the
+ <tt class="computeroutput">end</tt> statement for a package should be <tt class="computeroutput">end
+ <package_name>;</tt>, not just <tt class="computeroutput">end;</tt>; same
goes for procedures, functions, package bodies, and triggers.
</p></li><li><p>
- Always use the "show errors" SQL*Plus command after each PL/SQL
+ Always use the "show errors" SQL*Plus command after each PL/SQL
block. It will help you debug when there are compilation errors in
your PL/SQL code.
</p></li><li><p>
@@ -73,11 +72,11 @@
the v_* and *_in syntax in favor of named parameters notation:
</p><pre class="programlisting">
- <tt>
+ <tt class="computeroutput">
acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.)
</tt>
instead of
- <tt>
+ <tt class="computeroutput">
acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.)
</tt>
@@ -109,22 +108,22 @@
show errors
</pre></li><li><p>
- Explicitly designate each parameter as "in," "out," or "inout."
+ Explicitly designate each parameter as "in," "out," or "inout."
</p></li><li><p>
Each parameter should be on its own line, with a tab after the
parameter name, then in/out/inout, then a space, and finally the
datatype.
</p></li><li><p>
Use %TYPE and %ROWTYPE whenever possible.
</p></li><li><p>
- Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype
+ Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype
because it can't be used in SQL queries.
</p></li><li><p>
- All <tt>new</tt> functions (e.g., <tt>acs_object.new,
+ All <tt class="computeroutput">new</tt> functions (e.g., <tt class="computeroutput">acs_object.new,
party.new,</tt> etc.) should optionally accept an ID:
</p><pre class="programlisting">
- <tt>
+ <tt class="computeroutput">
create or replace package acs_object
as
function new (
@@ -138,12 +137,12 @@
</tt>
</pre><p>
- takes the optional argument <tt>object_id</tt>. Do this to
+ takes the optional argument <tt class="computeroutput">object_id</tt>. Do this to
allow people to use the same API call when they are doing double
click protection, that is, tehy have already gotten an
- <tt>object_id</tt> and now they want to create the object with
- that <tt>object_id</tt>.
- </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-style"></a>Style</h3></div></div><p>
+ <tt class="computeroutput">object_id</tt> and now they want to create the object with
+ that <tt class="computeroutput">object_id</tt>.
+ </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-style"></a>Style</h3></div></div><div></div></div><p>
Some general style guidelines to follow for the purpose of
consistency across applications.
</p><div class="orderedlist"><ol type="1"><li><p>
@@ -153,4 +152,4 @@
as possible to all source code readers.
</p></li><li><p>
Lowercase everything, with the exception of %TYPE and %ROWTYPE.
- </p></li></ol></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr><tr><td width="40%" align="left">ACS File Naming and Formatting Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Appendix�C.�Using CVS with an OpenACS Site</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/eng-standards-plsql.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></li></ol></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr><tr><td width="40%" align="left">ACS File Naming and Formatting Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Appendix�A.�Using CVS with an OpenACS Site</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/eng-standards-plsql.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,11 +1,10 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Release Version Numbering</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="requirements-template.html" title="System/Application Requirements Template"><link rel="next" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-versioning"></a>Release Version Numbering</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:ron@arsdigita.com" target="_top">Ron Henderson</a></p><br>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Release Version Numbering</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="requirements-template.html" title="System/Application Requirements Template"><link rel="next" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-versioning"></a>Release Version Numbering</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:ron@arsdigita.com" target="_top">Ron Henderson</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p>
OpenACS version numbers help identify at a high-level what is in a
particular release and what has changed since the last release. A
-"version number" is really just a string of the form:
+"version number" is really just a string of the form:
</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>major</em></span>-<span class="emphasis"><em>minor</em></span>-<span class="emphasis"><em>release</em></span></p></blockquote></div><p>
A change in the <span class="emphasis"><em>major</em></span> version number indicates a fundamental
change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A
@@ -36,7 +35,7 @@
particular release. To translate between a distribution tar file
(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-' and add the
release date. The entire release history of the toolkit is recorded
-in the tags for the top-level <tt>readme.txt</tt> file:
+in the tags for the top-level <tt class="computeroutput">readme.txt</tt> file:
</p><pre class="programlisting">
> cvs log readme.txt
RCS file: /usr/local/cvsroot/acs/readme.txt,v
@@ -72,7 +71,7 @@
</pre><p>
In the future, OpenACS packages should follow this same
convention on version numbers.
-</p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-transition-rules"></a>Transition Rules</h3></div></div><p>So what distinguishes an <span class="emphasis"><em>alpha</em></span> release from a <span class="emphasis"><em>beta</em></span>
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-transition-rules"></a>Transition Rules</h3></div></div><div></div></div><p>So what distinguishes an <span class="emphasis"><em>alpha</em></span> release from a <span class="emphasis"><em>beta</em></span>
release? Or from a production release? We follow a specific set of
rules for how OpenACS makes the transition from one state of maturity to
the next.</p><p> Every release must pass the minimum requirements that it cleanly
Index: openacs-4/packages/acs-core-docs/www/eng-standards.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/eng-standards.html 28 Jun 2003 05:07:01 -0000 1.10
+++ openacs-4/packages/acs-core-docs/www/eng-standards.html 14 Oct 2003 11:02:58 -0000 1.11
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�12.�Engineering Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="next" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="eng-standards"></a>Chapter�12.�Engineering Standards</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr><tr><td width="40%" align="left">Programming with AOLserver </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Documentation Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/eng-standards.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�12.�Engineering Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="next" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="eng-standards"></a>Chapter�12.�Engineering Standards</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr><tr><td width="40%" align="left">Programming with AOLserver </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Documentation Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/eng-standards.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 20 Aug 2003 16:20:16 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 14 Oct 2003 11:02:58 -0000 1.2
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>External Authentication Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ext-auth-requirements"></a>External Authentication Requirements</h2></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2890682"></a>Vision</h3></div></div><p>People have plenty of usernames and passwords already, we
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>External Authentication Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ext-auth-requirements"></a>External Authentication Requirements</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2877131"></a>Vision</h3></div></div><div></div></div><p>People have plenty of usernames and passwords already, we
don't want them to have yet another. We want people to be able to
log in to OpenACS with the same password they use to log in to any
other system.</p><p>Besides, administrators have better things to do than create
@@ -8,7 +7,7 @@
log on to OpenACS, an account will automatically be created for
them here.</p><p>Finally, security is increased with fewer passwords, since
users generally can't remember all those passwords, so they tend to
-keep them all the same and never change them.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Design_Goal"></a>Design Goals</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Transparent: Users don't have to do anything special to
+keep them all the same and never change them.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Design_Goal"></a>Design Goals</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Transparent: Users don't have to do anything special to
get an account on the local OpenACS system, if they already have an
account on the external authentication server.</p></li><li><p>Fall-back: Users who don't have an account on the
external authentication server are still allowed to create a local
@@ -36,19 +35,19 @@
the other hand very modular to enable a start with minimal
requirements (driver implementations) as soon as
possible.</p></li></ul></div><p>The problem can be split into several logically separate
-parts. Each has a section below.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Terminology"></a>Terminology</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Authority: The name of an authority trusted to authenticate
+parts. Each has a section below.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Terminology"></a>Terminology</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Authority: The name of an authority trusted to authenticate
users.</p></li><li><p>Authentication Driver: An implementation of the
authentication service contract, which talks to an authentication
of a certain type, e.g. PAM, RADIUS, LDAP, or Active
Directory.</p></li><li><p>Authentication API: The API through which login pages and
applications talk to the authentication service. There's one and
only one implementation of the authentication API, namly the one
included in OpenACS Core.</p></li><li><p>Authentication Driver API: The service contract which
- authentication drivers implement.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Diagram"></a>Conceptual Pictures</h3></div></div><p>Authentication:</p><p><span class="inlinemediaobject"><img src="images/ext-auth.png"></span>
-</p><p>Account Management (NO PICTURE YET)</p><p>Batch Synchronization (NO PICTURE YET)</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Requirements"></a>Requirements</h3></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2916502"></a>New API</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-01</td><td>A</td><td>Extend Authentication/Acct Status API</td></tr><tr><td>EXT-AUTH-03</td><td>A</td><td>Account Creation API</td></tr><tr><td>EXT-AUTH-05</td><td>A</td><td>Password Management API</td></tr><tr><td>EXT-AUTH-30</td><td>A</td><td>Authority Management API</td></tr></tbody></table></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Login"></a>Login</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-04</td><td>A</td><td>Rewrite login, register, and admin pages to use APIs</td></tr><tr><td>EXT-AUTH-38</td><td>A</td><td>ad_form complain feature</td></tr><tr><td>EXT-AUTH-19</td><td>A</td><td>Rewrite password recovery to use API</td></tr><tr><td>EXT-AUTH-21</td><td>A</td><td>Rewrite email verification with API</td></tr><tr><td>EXT-AUTH-28</td><td>A</td><td>Username is email switch</td></tr></tbody></table></div><p>Users will log in using a username, a authority, and a
+ authentication drivers implement.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Diagram"></a>Conceptual Pictures</h3></div></div><div></div></div><p>Authentication:</p><p><span class="inlinemediaobject"><img src="images/ext-auth.png"></span>
+</p><p>Account Management (NO PICTURE YET)</p><p>Batch Synchronization (NO PICTURE YET)</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Requirements"></a>Requirements</h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2889465"></a>New API</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-01</td><td>A</td><td>Extend Authentication/Acct Status API</td></tr><tr><td>EXT-AUTH-03</td><td>A</td><td>Account Creation API</td></tr><tr><td>EXT-AUTH-05</td><td>A</td><td>Password Management API</td></tr><tr><td>EXT-AUTH-30</td><td>A</td><td>Authority Management API</td></tr></tbody></table></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Login"></a>Login</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-04</td><td>A</td><td>Rewrite login, register, and admin pages to use APIs</td></tr><tr><td>EXT-AUTH-38</td><td>A</td><td>ad_form complain feature</td></tr><tr><td>EXT-AUTH-19</td><td>A</td><td>Rewrite password recovery to use API</td></tr><tr><td>EXT-AUTH-21</td><td>A</td><td>Rewrite email verification with API</td></tr><tr><td>EXT-AUTH-28</td><td>A</td><td>Username is email switch</td></tr></tbody></table></div><p>Users will log in using a username, a authority, and a
password. The authority is the source for user/password
verification. OpenACS can be an authority itself. </p><p>Each user in OpenACS will belong to exactly one authority, which
-can either be the "local" OpenACS users table, in which case the
+can either be the "local" OpenACS users table, in which case the
password column is used, or it can be some external authority,
which will be communicated with using some protocol, as implemented
by an authentication driver.</p><p>Username will be separate from email address. It can be an
@@ -71,7 +70,7 @@
[Forgot my password]
[New user registration]
</pre><p>If there's only one active authority, we don't display the
-authority drop-down element at all.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Configuratio"></a>Configuration</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-07</td><td>A</td><td>Admin pages to control Ext-Auth parameters</td></tr></tbody></table></div><p>The site-wide systems administrator can configure the
+authority drop-down element at all.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Configuratio"></a>Configuration</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-07</td><td>A</td><td>Admin pages to control Ext-Auth parameters</td></tr></tbody></table></div><p>The site-wide systems administrator can configure the
authentication process from a page linked under /acs-admin.</p><div class="itemizedlist"><ul type="disc"><li><p>Authorities - ordered list of authorities defined</p></li><li><p>Account Registration Allowed: Yes/No. Account
registration can be disabled altogether.</p></li><li><p>Registration authority - the authority in which accounts should
be created, using the relevant driver, if account registration is
@@ -84,7 +83,7 @@
other drivers call external functions. The possible functions
for each authority are split into several drivers for convenience.
One driver handles authentication, one account creation, and one
- changing passwords.</p><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-16</td><td>A</td><td>Create service contract for Authentication</td></tr><tr><td>EXT-AUTH-17</td><td>A</td><td>Create service contract for Acct. Creation</td></tr><tr><td>EXT-AUTH-29</td><td>A</td><td>Create service contract for Passwd Management</td></tr></tbody></table></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-18</td><td>A</td><td>Authority configuration data model</td></tr></tbody></table></div><p>Each authority is defined like this:</p><div class="itemizedlist"><ul type="disc"><li><p>Authority pretty-name, e.g. "URZ"</p></li><li><p>Authentication Driver, e.g. "RADIUS". In practice, this
+ changing passwords.</p><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-16</td><td>A</td><td>Create service contract for Authentication</td></tr><tr><td>EXT-AUTH-17</td><td>A</td><td>Create service contract for Acct. Creation</td></tr><tr><td>EXT-AUTH-29</td><td>A</td><td>Create service contract for Passwd Management</td></tr></tbody></table></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-18</td><td>A</td><td>Authority configuration data model</td></tr></tbody></table></div><p>Each authority is defined like this:</p><div class="itemizedlist"><ul type="disc"><li><p>Authority pretty-name, e.g. "URZ"</p></li><li><p>Authentication Driver, e.g. "RADIUS". In practice, this
would be a reference to a service contract
implementation.</p></li><li><p>Authentication Driver configuration settings, e.g. host
name, port, etc., as required by the particular driver. Note that
@@ -96,7 +95,7 @@
trying to use the authentication driver's password management
features.</p></li><li><p>ChangePasswordUrl - a URL to redirect to instead of
trying to use the authentication driver's password management
- features.</p></li><li><p>Account Creation Driver, e.g. "RADIUS". In practice, this
+ features.</p></li><li><p>Account Creation Driver, e.g. "RADIUS". In practice, this
would be a reference to a service contract implementation. The
reason we have separate drivers for authentication and account
creation is that organizations are likely to have a home-grown
@@ -114,10 +113,10 @@
find a mechanism for the driver to tell us which configuration
options are available, a way to set these, and a way for the driver
to access these settings.</p><p>OpenACS will come pre-configured with one authority, which is
-the "local" authority, meaning we'll authenticate as normal using the
+the "local" authority, meaning we'll authenticate as normal using the
local users table. This will, just like any other authority, be
-implemetned using a service contract.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Synchronizing_and_Linking_User"></a>Synchronizing
-and Linking Users</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-28</td><td>A</td><td>Create service contract for Batch Sync.</td></tr><tr><td>EXT-AUTH-38</td><td>A</td><td>Batch User Synchronization API</td></tr><tr><td>EXT-AUTH-38</td><td>A</td><td>IMS Synchronization driver</td></tr><tr><td>EXT-AUTH-08</td><td>A</td><td>Automation of batch Synchronization</td></tr><tr><td>EXT-AUTH-15</td><td>B</td><td>On-demand syncronization</td></tr></tbody></table></div><p>Regardless of the login method, the user needs to have a row
+implemetned using a service contract.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Synchronizing_and_Linking_User"></a>Synchronizing
+and Linking Users</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-28</td><td>A</td><td>Create service contract for Batch Sync.</td></tr><tr><td>EXT-AUTH-38</td><td>A</td><td>Batch User Synchronization API</td></tr><tr><td>EXT-AUTH-38</td><td>A</td><td>IMS Synchronization driver</td></tr><tr><td>EXT-AUTH-08</td><td>A</td><td>Automation of batch Synchronization</td></tr><tr><td>EXT-AUTH-15</td><td>B</td><td>On-demand syncronization</td></tr></tbody></table></div><p>Regardless of the login method, the user needs to have a row
in the OpenACS users table. This can happen through a batch job, in
real-time, or both in combination. We use the <a href="http://ims.edna.edu.au/enterprise/" target="_top">IMS Enterprise 1.1</a> specification. </p><p>Batch job means that we do a synchronization (import new
users, modify changed, purge deleted) on a regular interval, e.g.
@@ -130,15 +129,15 @@
be remedied by using the real-time solution. The batch job will also
require error logging and an admin interface to view logs.</p><p>If an email already belongs to some
other user, we log it as an error.</p><p>A user will always belong to exactly one authority, which can be
-either the "local" authority or some other. Thus, the OpenACS user's
+either the "local" authority or some other. Thus, the OpenACS user's
table will have to be augmented with the following columns:</p><div class="itemizedlist"><ul type="disc"><li><p>Authority. Reference to the site-wide authorities list. The
authority which can authenticate this user.</p></li><li><p>Authority-specific username.</p></li></ul></div><p>Real-time means that the first time the user logs into
OpenACS, we'll query the authority that authenticated him
for information about this user. That authentication authority will
then give us at least first names, last name and email. The pros
and cons are the opposite of batch jobs. Using both in combination
-is ideal.</p><p>Note: One solution to the "two users from different authorities
-have the same email" problem above would be to allow users to
+is ideal.</p><p>Note: One solution to the "two users from different authorities
+have the same email" problem above would be to allow users to
belong to multiple authorities. Then we would notice that the email
already exists, ask the user if he thinks he's the same person, and
if so, ask him to prove so by authenticating using the other
@@ -155,9 +154,9 @@
create a row in the local users table using that
information.</p><p>If that doesn't work, we'll tell the user that their account
isn't yet available, and the driver will supply a message for us,
-which could say "The account should be available tomorrow. If not,
-contact X."</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Account_Registratio"></a>Account
-Registration</h4></div></div><p>If a user doesn't have an account, the site-wide
+which could say "The account should be available tomorrow. If not,
+contact X."</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Account_Registratio"></a>Account
+Registration</h4></div></div><div></div></div><p>If a user doesn't have an account, the site-wide
configuration can allow the user to register for one, as defined in
the configuration discussed above. This section is about normal
account registration through a authority driver.</p><p>The account creation service contract implementation will
@@ -167,45 +166,45 @@
message.</p></li><li><p>Account status: Is the account ready for use?</p></li><li><p>User information: first_names, last_name, email, url,
password, password_hash, secret_question, secret_answer. The driver
only needs to return the columns which were changed or added
- through the registration process. Typically, only the "local"
+ through the registration process. Typically, only the "local"
driver will return password and secret question/answer.</p></li></ul></div><p>After creating the remote account, a local account is created
with the information gathered through the form/returned by the
driver.</p><p>By default, a local account creation implementation is
provided, which will create a new OpenACS user, and, in addition to
the default local account creation above, also store the password
-in hashed form.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Password_Managemen"></a>Password
-Management</h4></div></div><p>Password management is about changing password, retrieving
+in hashed form.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Password_Managemen"></a>Password
+Management</h4></div></div><div></div></div><p>Password management is about changing password, retrieving
password, and resetting password.</p><p>It's up to the authority driver implementation to decide whether
to support any or all of these features, and to say so using the
CanXXX methods (see driver API below).</p><p>Additionally, the authority can be configured with a URL to
redirect to in the case of forgotten passwords, or when the user
-desires to change password.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Login_Pages_Over_HTTP"></a>Login Pages Over
-HTTPS</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-20</td><td>A</td><td>Login over HTTPS</td></tr></tbody></table></div><p>Login pages must be able to be sent over a secure connection
+desires to change password.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Login_Pages_Over_HTTP"></a>Login Pages Over
+HTTPS</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-20</td><td>A</td><td>Login over HTTPS</td></tr></tbody></table></div><p>Login pages must be able to be sent over a secure connection
(https), so your password won't get sent over the wire in
cleartext, while leaving the rest of the site non-secure (http). I
believe that this requires some (minor) changes to the current
-session handling code.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Email_Verificatio"></a>Email
-Verification</h4></div></div><p>Email verification needs to be handled both at registration
+session handling code.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Email_Verificatio"></a>Email
+Verification</h4></div></div><div></div></div><p>Email verification needs to be handled both at registration
and at login.</p><p>In both cases, it'll be handled by the driver sending
automatically sending the email containing a link for the user to
verify his account. Then the driver will return an account status
-of "closed,temporary", and a message that says ""Check your inbox
-and click the link in the email".</p><p>OpenACS will have a page which receives the email
+of "closed,temporary", and a message that says ""Check your inbox
+and click the link in the email".</p><p>OpenACS will have a page which receives the email
verification, for use by local accounts. Other authorities will
have to implement their own page, most likely on the authority's
-own server.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Other_Item"></a>Other Items</h3></div></div><p>There are a number of items which touch on external
+own server.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Other_Item"></a>Other Items</h3></div></div><div></div></div><p>There are a number of items which touch on external
authentication and session management. And even though they're not
directly linked to external authentication, I would recommend that
we handle a number of them, either because they're important for
security, or because it makes sense to fix them while we're messing
-with this part of the codebase anyway.</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Recommended__Untrusted_Logins_and_Login_Leve"></a>Recommended:
-Untrusted Logins and Login Levels</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-33</td><td>A</td><td>Untrusted Logins</td></tr></tbody></table></div><p>I like the idea of having multiple login levels:</p><div class="orderedlist"><ol type="1"><li><p>Not logged in</p></li><li><p>Untrusted login: We'll show you un-sensitive personal
+with this part of the codebase anyway.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Untrusted_Logins_and_Login_Leve"></a>Recommended:
+Untrusted Logins and Login Levels</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-33</td><td>A</td><td>Untrusted Logins</td></tr></tbody></table></div><p>I like the idea of having multiple login levels:</p><div class="orderedlist"><ol type="1"><li><p>Not logged in</p></li><li><p>Untrusted login: We'll show you un-sensitive personal
content, but won't let you modify anything or see personal data. A
normal login becomes untrusted after a certain amount of time, and
the user will have to re-enter his/her password in order to gain
access to personal data. Untrusted login never expires, unless
explicitly done so through either changing password or clicking a
- special "expire all logins" link.</p></li><li><p>Normal login: The user is logged, and has type his
+ special "expire all logins" link.</p></li><li><p>Normal login: The user is logged, and has type his
password sufficiently recently that we trust the login. All normal
operations are allowed. Will degrade to untrusted login after a
specified amount of time.</p></li><li><p>Secure login: The user is logged in over a secure
@@ -224,19 +223,19 @@
example, we could let you browse publically available forums, and
only when you want to post do you need to log in. This makes it
even more feasible to have a more secure login expiration
-setting.</p><p>By default, <tt>auth::require_login</tt> would
+setting.</p><p>By default, <tt class="literal">auth::require_login</tt> would
bounce to the login page if the user is only logged in at the
untrusted level. Only if you explicitly say
-<tt>auth::require_login -untrusted</tt> will we give you
+<tt class="literal">auth::require_login -untrusted</tt> will we give you
the user_id of a user who's only logged in in untrusted
-mode.</p><p>Similarly, <tt>ad_conn user_id</tt> will continue
+mode.</p><p>Similarly, <tt class="literal">ad_conn user_id</tt> will continue
to return 0 (not logged in) when the user is only logged in
-untrusted, and we'll supply another variable, <tt>ad_conn
+untrusted, and we'll supply another variable, <tt class="literal">ad_conn
untrusted_user_id</tt>, which wlll be set to the user_id for
all login levels.</p><p>This should ensure that we get full access to the new
feature, while leaving all current code just as secure as it was
-before.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Recommended__Make_Non-Persistent_Login_Wor"></a>Recommended:
-Make Non-Persistent Login Work</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-34</td><td>A</td><td>Expire Logins</td></tr></tbody></table></div><p>Currently, OpenACS is unusable in practice without persistent
+before.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Make_Non-Persistent_Login_Wor"></a>Recommended:
+Make Non-Persistent Login Work</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-34</td><td>A</td><td>Expire Logins</td></tr></tbody></table></div><p>Currently, OpenACS is unusable in practice without persistent
login. The login will expire after just a few minutes of
inactivity, and you'll get bounced to the login page where you have
to enter both email and password again. Unacceptable in
@@ -247,15 +246,15 @@
login expire after a period of inactivity, but the amount of time
should be configurable and default to something reasonable like an
hour or so.</p><p>This will require looking into and changing the design of the
-current session handling code.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Recommended__Single-Sign-O"></a>Recommended:
-Single-Sign-On</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-23</td><td></td><td>Single sign-on</td></tr></tbody></table></div><p>Instead of redirecting to the login page, auth::require_login
+current session handling code.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Single-Sign-O"></a>Recommended:
+Single-Sign-On</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-23</td><td></td><td>Single sign-on</td></tr></tbody></table></div><p>Instead of redirecting to the login page, auth::require_login
can redirect to an authentication server, which can redirect back
to a page that logs the user in. This should be very easy to
implement.</p><p>Alternatively, if you want to combine this with fallback to
OpenACS accounts, we would instead present the normal login screen,
-but put a button which says "Login using X", where X is the
-redirection-based external authority.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Recommended__Expire_All_Login"></a>Recommended:
-Expire All Logins</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-22</td><td>B</td><td>rewrite cookie handling</td></tr></tbody></table></div><p>Currently, if you've ever left a permanent login cookie on
+but put a button which says "Login using X", where X is the
+redirection-based external authority.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Expire_All_Login"></a>Recommended:
+Expire All Logins</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-22</td><td>B</td><td>rewrite cookie handling</td></tr></tbody></table></div><p>Currently, if you've ever left a permanent login cookie on
someone elses machine, that person will be forever logged in until
he/she explicitly logs out. You can change your password, you can
do anything you want, but unless a logout is requested from that
@@ -270,29 +269,29 @@
void. Of course, we don't want to incur a DB hit on every request,
so we'll need to cache the secret token, or only check it when
refreshing the session cookie, which, I believe, normally happens
-every 10 minutes or so.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Recommended__Email_account_owner_on_password"></a>Recommended:
-Email account owner on password change</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-24</td><td>A</td><td>Email on password change</td></tr></tbody></table></div><p>As an additional security measure, we should email the
+every 10 minutes or so.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Email_account_owner_on_password"></a>Recommended:
+Email account owner on password change</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-24</td><td>A</td><td>Email on password change</td></tr></tbody></table></div><p>As an additional security measure, we should email the
account's email address whenever the password is changed, so that
-he/she is at least alerted to the fact.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Optional__Password_polic"></a>Optional:
-Password policy</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-25</td><td>A</td><td>Implement password policy</td></tr></tbody></table></div><p>Again, to increase security, we should add password policies,
+he/she is at least alerted to the fact.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Password_polic"></a>Optional:
+Password policy</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-25</td><td>A</td><td>Implement password policy</td></tr></tbody></table></div><p>Again, to increase security, we should add password policies,
such as passwords needing to be changed after a certain number of
days, change on next login (after a new random password has been
generated), or requiring that the password satisfies certain
complexity rules, i.e. both upper and lowercase characters,
numbers, special chars, etc.</p><p>It would good to extend the current maximum password length
-from 10 to at least 32 characters.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Optional__Login_Without_Explicit_Domai"></a>Optional:
-Login Without Explicit Authority</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-26</td><td>B</td><td>Login without explicit domain</td></tr></tbody></table></div><p>In order to make it easier for people, we've been toying with
-the idea of a functionality like this:</p><div class="itemizedlist"><ul type="disc"><li><p>If the user enters "foobar@ix.urz.uni-heidelberg.de", it
- is translated to mean username = "foobar", authority =
- "ix.urz.uni-heidelberg.de".</p></li><li><p>If the user enters "foobar", it's recognized to not
+from 10 to at least 32 characters.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Login_Without_Explicit_Domai"></a>Optional:
+Login Without Explicit Authority</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-26</td><td>B</td><td>Login without explicit domain</td></tr></tbody></table></div><p>In order to make it easier for people, we've been toying with
+the idea of a functionality like this:</p><div class="itemizedlist"><ul type="disc"><li><p>If the user enters "foobar@ix.urz.uni-heidelberg.de", it
+ is translated to mean username = "foobar", authority =
+ "ix.urz.uni-heidelberg.de".</p></li><li><p>If the user enters "foobar", it's recognized to not
include any authority, and the default authority of
- "ix.urz.uni-heidelberg.de" is used.</p></li><li><p>If the user enters "foo@bar.com", it's recognized as not
+ "ix.urz.uni-heidelberg.de" is used.</p></li><li><p>If the user enters "foo@bar.com", it's recognized as not
belonging to any known authority, and as such, it's translated to mean
- username = "foo@bar.com", authority = "local".</p></li></ul></div><p>If this is deemed desirable, a way to implement this would be
+ username = "foo@bar.com", authority = "local".</p></li></ul></div><p>If this is deemed desirable, a way to implement this would be
through these settings:</p><div class="itemizedlist"><ul type="disc"><li><p>Split: A regexp which will split the user's entry into
- username and authority parts. For example "^([^@]+)(@[^@]+)?$". An
+ username and authority parts. For example "^([^@]+)(@[^@]+)?$". An
easier to use but less flexible method would be that you simply
- specify a certain character to split by, such as "@" or "\". If the
+ specify a certain character to split by, such as "@" or "\". If the
regexp doesn't match, or in the latter case, if there's more than
one occurrence of the specified character sequence, the split will
fail, signaling that the user's entry was not valid.</p></li><li><p>Default authority: The default authority will be the first one
@@ -305,8 +304,8 @@
# username will now contain username
# authority will now contain authority
-</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Optional__Who's_Onlin"></a>Optional: Who's
-Online</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-27</td><td>B</td><td>Who's online list</td></tr></tbody></table></div><p>While we're touching the session handling code, anyway, it
+</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Who's_Onlin"></a>Optional: Who's
+Online</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-27</td><td>B</td><td>Who's online list</td></tr></tbody></table></div><p>While we're touching the session handling code, anyway, it
would be nice to add a feature to show who's currently online, a
nice real-time collaboration feature frequently requested by
members of the community. This is particularly interesting when
@@ -315,16 +314,16 @@
which authenticated users have requested pags on the site in the
last x minutes (typically about 5), and thus are considered to be
currently online. There's nothing more to it. This lets us display
-a list of "active users" somewhere on the site, and make their name
+a list of "active users" somewhere on the site, and make their name
a link to a real-time chat service like Jabber.</p><p>We've already made the changes necessary to
security-procs.tcl to do this on an earlier project, but haven't
-quite finished the work and put it back into the tree.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Optional__Subsite-level_configuratio"></a>Optional:
-Subsite-level configuration</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-28</td><td></td><td>implement subsite-level config</td></tr></tbody></table></div><p>If we want to, we could let subsite administrators configure
+quite finished the work and put it back into the tree.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Subsite-level_configuratio"></a>Optional:
+Subsite-level configuration</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-28</td><td></td><td>implement subsite-level config</td></tr></tbody></table></div><p>If we want to, we could let subsite administrators configure
the login process for that particular subsite. This would probably
only entail letting the subsite admin leave out certain authorities
defined site-wide, and change the sort order.</p><p>I think we should leave this out until we have a use case for
-it, someone who'd need it.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Future__Making_the_Authentication_API_itself"></a>Future:
-Making the Authentication API itself a service contract</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-32</td><td>A</td><td>Parameters for Service Contract Implementation</td></tr><tr><td>EXT-AUTH-35</td><td>A</td><td>Make the Authentication API a service contract</td></tr></tbody></table></div><p>For completely free-form authentication logic and mechanisms,
+it, someone who'd need it.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Future__Making_the_Authentication_API_itself"></a>Future:
+Making the Authentication API itself a service contract</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-32</td><td>A</td><td>Parameters for Service Contract Implementation</td></tr><tr><td>EXT-AUTH-35</td><td>A</td><td>Make the Authentication API a service contract</td></tr></tbody></table></div><p>For completely free-form authentication logic and mechanisms,
something like Andrew Grumet's
<a href="http://openacs.org/new-file-storage/download/oacs-pam.html?version_id=687" target="_top">Pluggable
Authentication for OACS Draft</a> is interesting. He's
@@ -335,10 +334,10 @@
people are going to want to use a username/password-based scheme,
and having easy configuration through a web UI is more important
than total flexibility at this point.</p><p>Besides, we can always do this in the future, by letting the
-public Authentication API (<tt>auth::require_login</tt>
-and <tt>auth::authenticate</tt>) be implemented through a
-service contract.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Future__Authenticating_against_multiple_serv"></a>Future:
-Authenticating against multiple servers simultaneously</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-36</td><td>A</td><td>Authenticate against multiple servers</td></tr></tbody></table></div><p>Both OKI and OpenACS supports a form of stacking, where you
+public Authentication API (<tt class="literal">auth::require_login</tt>
+and <tt class="literal">auth::authenticate</tt>) be implemented through a
+service contract.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Future__Authenticating_against_multiple_serv"></a>Future:
+Authenticating against multiple servers simultaneously</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-36</td><td>A</td><td>Authenticate against multiple servers</td></tr></tbody></table></div><p>Both OKI and OpenACS supports a form of stacking, where you
can be logged into multiple authorities at the same time. This is
useful if, for example, you need to get login tokens such as
Kerberos tickets for access to shared resources.</p><p>I can see the value in this, but for simplicity's sake, I'm
@@ -351,16 +350,16 @@
for user/group data and access control lists, SMB for file storage,
etc. But at the moment, we don't have any users of such things that
are ready. We have some who are on the steps, but let's wait till
-they're there.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Implement_Specific_Driver"></a>Implement
-Specific Drivers</h4></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-09</td><td>A</td><td>Create Auth. drivers for Local Authority</td></tr><tr><td>EXT-AUTH-10</td><td>A</td><td>Create Acct. Creation driver for Local Authority</td></tr><tr><td>EXT-AUTH-11</td><td>A</td><td>Create Auth. driver for PAM</td></tr><tr><td>EXT-AUTH-12</td><td>X</td><td><span class="emphasis"><em>Create Acct. Creation driver for PAM - this
+they're there.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Implement_Specific_Driver"></a>Implement
+Specific Drivers</h4></div></div><div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr></tr></thead><tbody><tr><td>EXT-AUTH-09</td><td>A</td><td>Create Auth. drivers for Local Authority</td></tr><tr><td>EXT-AUTH-10</td><td>A</td><td>Create Acct. Creation driver for Local Authority</td></tr><tr><td>EXT-AUTH-11</td><td>A</td><td>Create Auth. driver for PAM</td></tr><tr><td>EXT-AUTH-12</td><td>X</td><td><span class="emphasis"><em>Create Acct. Creation driver for PAM - this
functionality is explicitly excluded from PAM</em></span></td></tr><tr><td>EXT-AUTH-13</td><td>A</td><td>Create Acct. Creation driver for LDAP</td></tr><tr><td>EXT-AUTH-14</td><td>A</td><td>Create Auth. driver for LDAP</td></tr></tbody></table></div><p>We'll need drivers for:</p><div class="itemizedlist"><ul type="disc"><li><p>Operating system (Linux/Solaris) PAM: Delegate to the
operating system, which can then talk to RADIUS, LDAP, whatever.
This is convenient because there'll be plenty of drivers for the OS
PAM level, so we don't have to write them all ourselves. The
downside is that we can't do things like account creation, password
management, real-time account synchronization, etc., not supported
by PAM (I'm not entirely sure what is and is not
- supported).</p></li><li><p>RADIUS</p></li><li><p>LDAP</p></li></ul></div><div class="sect4" lang="en"><div class="titlepage"><div><h5 class="title"><a name="RADIU"></a>RADIUS</h5></div></div><p>RADIUS is a simple username/password-type authentication
+ supported).</p></li><li><p>RADIUS</p></li><li><p>LDAP</p></li></ul></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="RADIU"></a>RADIUS</h5></div></div><div></div></div><p>RADIUS is a simple username/password-type authentication
server.</p><p>It also supports sending a challenge to which the user must
respond with the proper answer (e.g. mother's maiden name, or could
be additional password), but we will not support this
@@ -369,12 +368,12 @@
in Python</a> can be found in the
<a href="http://exuserfolder.sourceforge.net/" target="_top">exUserFolder
module</a> for Zope
-(<a href="http://sourceforge.net/docman/display_doc.php?docid=7238&group_id=36318" target="_top">documentation</a>).</p></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Feedbac"></a>Feedback</h3></div></div><p>We'd really appreciate feedback on this proposal. Please
+(<a href="http://sourceforge.net/docman/display_doc.php?docid=7238&group_id=36318" target="_top">documentation</a>).</p></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Feedbac"></a>Feedback</h3></div></div><div></div></div><p>We'd really appreciate feedback on this proposal. Please
follow up at
<a href="http://openacs.org/forums/message-view?message_id=97341" target="_top">this
-openacs.org forums thread</a>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Reference"></a>References</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p> <a href="http://ims.edna.edu.au/enterprise/" target="_top">IMS Enterprise</a></p></li><li><p><a href="http://openacs.org/projects/openacs/packages/ex-auth/" target="_top">Threads
+openacs.org forums thread</a>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Reference"></a>References</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p> <a href="http://ims.edna.edu.au/enterprise/" target="_top">IMS Enterprise</a></p></li><li><p><a href="http://openacs.org/projects/openacs/packages/ex-auth/" target="_top">Threads
and links</a> collected by Carl Blesius.</p></li><li><p><a href="http://java.sun.com/security/jaas/doc/pam.html" target="_top">Solaris/Linux
PAM specification</a></p></li><li><p><a href="http://openacs.org/new-file-storage/download/oacs-pam.html?version_id=687" target="_top">Draft
Proposal</a> by Andrew Grumet.</p></li><li><p><a href="http://www.yale.edu/tp/auth/" target="_top">Yale
CAS</a>, a centrl authentication service a' la
- Passport.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="ext-auth-revision-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>1</td><td>Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.</td><td>20 Aug 2003</td><td>Joel Aufrecht</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left">Bootstrapping OpenACS </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/ext-auth-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ Passport.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ext-auth-revision-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>1</td><td>Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.</td><td>20 Aug 2003</td><td>Joel Aufrecht</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left">Bootstrapping OpenACS </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/ext-auth-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/filename.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/filename.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/filename.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Detailed Design Documentation Template</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="next" href="requirements-template.html" title="System/Application Requirements Template"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="filename"></a>Detailed Design Documentation Template</h2></div></div><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a></p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-start-note"></a>Start Note</h3></div></div><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Detailed Design Documentation Template</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="next" href="requirements-template.html" title="System/Application Requirements Template"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="filename"></a>Detailed Design Documentation Template</h2></div></div><div></div></div><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a></p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-start-note"></a>Start Note</h3></div></div><div></div></div><p>
<span class="emphasis"><em>NOTE: Some of the sections of this template may not apply to your
package, e.g. there may be no user-visible UI elements for a component
of the OpenACS Core. Furthermore, it may be easier in some circumstances
@@ -14,16 +13,16 @@
<span class="emphasis"><em>Also, bear in mind <span class="strong">the audience</span> for detailed design: fellow
programmers who want to maintain/extend the software, AND parties
interested in evaluating software quality. </em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-essentials"></a>Essentials</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-essentials"></a>Essentials</h3></div></div><div></div></div><p>
When applicable, each of the following items should receive its own link:
- </p><div class="itemizedlist"><ul type="disc"><li><p> User directory </p></li><li><p> OpenACS administrator directory </p></li><li><p> Subsite administrator directory </p></li><li><p> Tcl script directory (link to the API browser page for the package) </p></li><li><p> PL/SQL file (link to the API browser page for the package) </p></li><li><p> Data model </p></li><li><p> Requirements document </p></li><li><p> ER diagram </p></li><li><p> Transaction flow diagram </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-introduction"></a>Introduction</h3></div></div><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p> User directory </p></li><li><p> OpenACS administrator directory </p></li><li><p> Subsite administrator directory </p></li><li><p> Tcl script directory (link to the API browser page for the package) </p></li><li><p> PL/SQL file (link to the API browser page for the package) </p></li><li><p> Data model </p></li><li><p> Requirements document </p></li><li><p> ER diagram </p></li><li><p> Transaction flow diagram </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-introduction"></a>Introduction</h3></div></div><div></div></div><p>
This section should provide an overview of the package
and address at least the following issues:
</p><div class="itemizedlist"><ul type="disc"><li><p> What this package is intended to allow the user (or different
classes of users) to accomplish. </p></li><li><p> Within reasonable bounds, what this package is not intended to allow users to
accomplish. </p></li><li><p> The application domains where this package is most likely to be of use. </p></li><li><p> A high-level overview of how the package meets its
requirements (which should have been documented elsewhere). This
- is to include relevant material from the "features" section of the
+ is to include relevant material from the "features" section of the
cover sheet (the cover sheet is a wrapper doc with links to all
other package docs). </p></li></ul></div><p>
Also worthy of treatment in this section:
@@ -33,15 +32,15 @@
Note: it's entirely possible that a discussion of what a package
is not intended to do differs from a discussion of future
improvements for the package.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-historical-consid"></a>Historical Considerations</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-historical-consid"></a>Historical Considerations</h3></div></div><div></div></div><p>
For a given set of requirements, typically many possible
implementations and solutions exist. Although eventually only one
solution is implemented, a discussion of the alternative solutions
canvassed - noting why they were rejected - proves helpful to both
current and future developers. All readers would be reminded as to
why and how the particular solution developed over time, avoiding
re-analysis of problems already solved.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-competitive-analysis"></a>Competitive Analysis</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-competitive-analysis"></a>Competitive Analysis</h3></div></div><div></div></div><p>
Although currently only a few package documentation pages contain a
discussion of competing software, (e.g. chat, portals), this section
should be present whenever such competition exists.
@@ -52,7 +51,7 @@
lacks. </p></li></ul></div><p>
Note that such a discussion may differ from a discussion of a
package's potential future improvements.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><div></div></div><p>
No single design solution can optimize every desirable software
attribute. For example, an increase in the security of a system will
likely entail a decrease in its ease-of-use, and an increase in the
@@ -62,7 +61,7 @@
should include a discussion of the tradeoffs involved with the design
chosen, and the reasons for your choices. Some areas of importance to
keep in mind are:
- </p><p>Areas of interest to users:</p><div class="itemizedlist"><ul type="disc"><li><p> Performance: availability and efficiency </p></li><li><p> Flexibility </p></li><li><p> Interoperability </p></li><li><p> Reliability and robustness </p></li><li><p> Usability </p></li></ul></div><p>Areas of interest to developers:</p><div class="itemizedlist"><ul type="disc"><li><p> Maintainability </p></li><li><p> Portability </p></li><li><p> Reusability </p></li><li><p> Testability </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-api"></a>API</h3></div></div><p>
+ </p><p>Areas of interest to users:</p><div class="itemizedlist"><ul type="disc"><li><p> Performance: availability and efficiency </p></li><li><p> Flexibility </p></li><li><p> Interoperability </p></li><li><p> Reliability and robustness </p></li><li><p> Usability </p></li></ul></div><p>Areas of interest to developers:</p><div class="itemizedlist"><ul type="disc"><li><p> Maintainability </p></li><li><p> Portability </p></li><li><p> Reusability </p></li><li><p> Testability </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-api"></a>API</h3></div></div><div></div></div><p>
Here's where you discuss the abstractions used by your package, such
as the procedures encapsulating the legal transactions on the data
model. Explain the organization of procedures and their
@@ -80,10 +79,10 @@
handle transactions, instead of encapsulating them via procedures).
Experience has taught us that we need to focus on the API for
maintainability of our systems in the face of constant change.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-data-model"></a>Data Model Discussion</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-data-model"></a>Data Model Discussion</h3></div></div><div></div></div><p>
The data model discussion should do more than merely display the SQL
code, since this information is already be available via a link in the
- "essentials" section above. Instead, there should be a high-level
+ "essentials" section above. Instead, there should be a high-level
discussion of how your data model meets your solution requirements:
why the database entities were defined as they are, and what
transactions you expect to occur. (There may be some overlap with the
@@ -97,7 +96,7 @@
packages. </p></li><li><p><span class="strong">Transactions</span></p><p> Discuss modifications which the database may undergo from
your package. Consider grouping legal transactions according to
the invoking user class, i.e. transactions by an OpenACS-admin, by
- subsite-admin, by a user, by a developer, etc. </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-ui"></a>User Interface</h3></div></div><p>
+ subsite-admin, by a user, by a developer, etc. </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-ui"></a>User Interface</h3></div></div><div></div></div><p>
In this section, discuss user interface issues and pages to be built;
you can organize by the expected classes of users. These may include:
</p><div class="itemizedlist"><ul type="disc"><li><p> Developers</p></li><li><p> OpenACS administrators (previously known as site-wide administrators)</p></li><li><p> Subsite administrators</p></li><li><p> End users</p></li></ul></div><p>
@@ -108,32 +107,32 @@
</p><p>
<span class="emphasis"><em>Note: In order that developer documentation be uniform across
different system documents, these users should herein be designated as
- "the developer," "the OpenACS-admin," "the sub-admin," and "the user,"
+ "the developer," "the OpenACS-admin," "the sub-admin," and "the user,"
respectively. </em></span>
</p><p>
Finally, note that as our templating system becomes more entrenched
within the OpenACS, this section's details are likely to shift from UI
specifics to template interface specifics.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-config"></a>Configuration/Parameters</h3></div></div><p>
- Under OpenACS 5.0.0d, parameters are set at two levels: at the global level by
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-config"></a>Configuration/Parameters</h3></div></div><div></div></div><p>
+ Under OpenACS 5.0.0a1, parameters are set at two levels: at the global level by
the OpenACS-admin, and at the subsite level by a sub-admin. In this
section, list and discuss both levels of parameters.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><div></div></div><p>
If the system presently lacks useful/desirable features, note details
here. You could also comment on non-functional improvements to the
package, such as usability.
</p><p>
- Note that a careful treatment of the earlier "competitive analysis"
+ Note that a careful treatment of the earlier "competitive analysis"
section can greatly facilitate the documenting of this section.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-authors"></a>Authors</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-authors"></a>Authors</h3></div></div><div></div></div><p>
Although a system's data model file often contains this information,
this isn't always the case. Furthermore, data model files often
undergo substantial revision, making it difficult to track down the
system creator. An additional complication: package documentation may
be authored by people not directly involved in coding. Thus to avoid
unnecessary confusion, include email links to the following roles as
they may apply:
- </p><div class="itemizedlist"><ul type="disc"><li><p> System creator</p></li><li><p> System owner</p></li><li><p> Documentation author</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-revision-history"></a>Revision History</h3></div></div><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p> System creator</p></li><li><p> System owner</p></li><li><p> Documentation author</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-revision-history"></a>Revision History</h3></div></div><div></div></div><p>
<span class="emphasis"><em>The revision history table below is for this template - modify it
as needed for your actual design document. </em></span>
</p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Creation</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr><tr><td width="40%" align="left">Using PSGML mode in Emacs </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> System/Application Requirements Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/filename.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/for-everyone.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/for-everyone.html 24 Jun 2003 03:58:11 -0000 1.10
+++ openacs-4/packages/acs-core-docs/www/for-everyone.html 14 Oct 2003 11:02:58 -0000 1.11
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�I.�OpenACS For Everyone</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="index.html" title="OpenACS Documentation"><link rel="next" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><h1 class="title"><a name="for-everyone"></a>OpenACS For Everyone</h1></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a></dt><dd><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS Release Notes</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�1.�High level information: What is OpenACS?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/for-everyone.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part�I.�OpenACS For Everyone</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="index.html" title="OpenACS Documentation"><link rel="next" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="for-everyone"></a>OpenACS For Everyone</h1></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a></dt><dd><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS Release Notes</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter�1.�High level information: What is OpenACS?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/for-everyone.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/general-documents.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/general-documents.html 24 Jun 2003 03:58:11 -0000 1.10
+++ openacs-4/packages/acs-core-docs/www/general-documents.html 14 Oct 2003 11:02:58 -0000 1.11
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�1.�High level information: What is OpenACS?</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="for-everyone.html" title="Part�I.�OpenACS For Everyone"><link rel="previous" href="for-everyone.html" title="Part�I.�OpenACS For Everyone"><link rel="next" href="openacs-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><th width="60%" align="center">Part�I.�OpenACS For Everyone</th><td width="20%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="general-documents"></a>Chapter�1.�High level information: What is OpenACS?</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS Release Notes</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part�I.�OpenACS For Everyone </td><td width="20%" align="center"><a accesskey="u" href="for-everyone.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/general-documents.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�1.�High level information: What is OpenACS?</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="for-everyone.html" title="Part�I.�OpenACS For Everyone"><link rel="previous" href="for-everyone.html" title="Part�I.�OpenACS For Everyone"><link rel="next" href="openacs-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><th width="60%" align="center">Part�I.�OpenACS For Everyone</th><td width="20%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="general-documents"></a>Chapter�1.�High level information: What is OpenACS?</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS Release Notes</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part�I.�OpenACS For Everyone </td><td width="20%" align="center"><a accesskey="u" href="for-everyone.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/general-documents.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/groups-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/groups-design.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/groups-design.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,33 +1,32 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Groups Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="groups-requirements.html" title="OpenACS 4 Groups Requirements"><link rel="next" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="groups-design"></a>OpenACS 4 Groups Design</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Groups Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="groups-requirements.html" title="OpenACS 4 Groups Requirements"><link rel="next" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groups-design"></a>OpenACS 4 Groups Design</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a> and <a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>User directory</p></li><li><p>Sitewide administrator directory</p></li><li><p>Subsite administrator directory</p></li><li><p>TCL script directory</p></li><li><p><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></p></li><li><p>Data model</p></li><li><p>PL/SQL file </p><div class="itemizedlist"><ul type="circle"><li><p><a href="/doc/sql/display-sql?url=community-core-create.sql&package_key=acs-kernel" target="_top">
-community-core-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=groups-create.sql&package_key=acs-kernel" target="_top">groups-create.sql</a></p></li></ul></div></li><li><p>ER diagram</p></li><li><p>Transaction flow diagram</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-intro"></a>Introduction</h3></div></div><p>Almost all database-backed websites have users, and need to model the
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>User directory</p></li><li><p>Sitewide administrator directory</p></li><li><p>Subsite administrator directory</p></li><li><p>TCL script directory</p></li><li><p><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></p></li><li><p>Data model</p></li><li><p>PL/SQL file </p><div class="itemizedlist"><ul type="circle"><li><p><a href="/doc/sql/display-sql?url=community-core-create.sql&package_key=acs-kernel" target="_top">
+community-core-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=groups-create.sql&package_key=acs-kernel" target="_top">groups-create.sql</a></p></li></ul></div></li><li><p>ER diagram</p></li><li><p>Transaction flow diagram</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-intro"></a>Introduction</h3></div></div><div></div></div><p>Almost all database-backed websites have users, and need to model the
grouping of users. The OpenACS 4 Parties and Groups system is intended to provide
the flexibility needed to model complex real-world organizational structures,
particularly to support powerful subsite services; that is, where one OpenACS
installation can support what appears to the user as distinct web services
-for different user communities.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-hist-considerations"></a>Historical Considerations</h3></div></div><p>The primary limitation of the OpenACS 3.x user group system is that it
-restricts the application developer to representing a "flat group"
-that contains only users: The <tt>user_groups</tt> table may contain the
-<tt>group_id</tt> of a parent group, but parent-child relationship
+for different user communities.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-hist-considerations"></a>Historical Considerations</h3></div></div><div></div></div><p>The primary limitation of the OpenACS 3.x user group system is that it
+restricts the application developer to representing a "flat group"
+that contains only users: The <tt class="computeroutput">user_groups</tt> table may contain the
+<tt class="computeroutput">group_id</tt> of a parent group, but parent-child relationship
support is limited because it only allows one kind of relationship between
groups to be represented. Moreover, the Oracle database's limited support
for tree-like structures makes the queries over these relationships
expensive.</p><p>In addition, the Module Scoping design in OpenACS 3.0 introduced a
<span class="emphasis"><em>party</em></span> abstraction - a thing that is a person or a group of people -
though not in the form of an explicit table. Rather, the triple of
-<tt>scope</tt>, <tt>user_id</tt>, and <tt>group_id</tt> columns
+<tt class="computeroutput">scope</tt>, <tt class="computeroutput">user_id</tt>, and <tt class="computeroutput">group_id</tt> columns
was used to identify the party. One disadvantage of this design convention is
that it increases a data model's complexity by requiring the programmer
-to:</p><div class="itemizedlist"><ul type="disc"><li><p>add these three columns to each "scoped" table</p></li><li><p>define a multi-column check constraint to protect against data corruption
-(e.g., a row with a <tt>scope</tt> value of "group" but a null
-<tt>group_id</tt>)</p></li><li><p>perform extra checks in <tt>Tcl</tt> and <tt>PL/SQL</tt>
-functions and procedures to check both the <tt>user_id</tt> and
-<tt>group_id</tt> values</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-competitors"></a>Competitive Analysis</h3></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>The core of the Group Systems data model is quite simple, but it was
-designed in the hopes of modeling "real world" organizations which
+to:</p><div class="itemizedlist"><ul type="disc"><li><p>add these three columns to each "scoped" table</p></li><li><p>define a multi-column check constraint to protect against data corruption
+(e.g., a row with a <tt class="computeroutput">scope</tt> value of "group" but a null
+<tt class="computeroutput">group_id</tt>)</p></li><li><p>perform extra checks in <tt class="computeroutput">Tcl</tt> and <tt class="computeroutput">PL/SQL</tt>
+functions and procedures to check both the <tt class="computeroutput">user_id</tt> and
+<tt class="computeroutput">group_id</tt> values</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-competitors"></a>Competitive Analysis</h3></div></div><div></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><div></div></div><p>The core of the Group Systems data model is quite simple, but it was
+designed in the hopes of modeling "real world" organizations which
can be complex graph structures. The Groups System only considers groups that
can be modeled using directed acyclic graphs, but queries over these
structures are still complex enough to slow the system down. Since almost
@@ -39,44 +38,44 @@
without making the system too complex or too slow. The added triggers, views,
and tables and will increase storage requirements and the insert and delete
times in an effort to speed access time. The limited flexibility (no updates
-on membership) trades against the complexity of the code.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-data-model"></a>Data Model Discussion</h3></div></div><p>The Group System data model consists of the following tables:</p><div class="variablelist"><dl><dt><span class="term"><tt>parties</tt>
+on membership) trades against the complexity of the code.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-data-model"></a>Data Model Discussion</h3></div></div><div></div></div><p>The Group System data model consists of the following tables:</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">parties</tt>
</span></dt><dd><p>The set of all defined parties: any <span class="emphasis"><em>person</em></span>, <span class="emphasis"><em>user</em></span>, or
-<span class="emphasis"><em>group</em></span> must have a corresponding row in this table.</p></dd><dt><span class="term"><tt>persons</tt>
+<span class="emphasis"><em>group</em></span> must have a corresponding row in this table.</p></dd><dt><span class="term"><tt class="computeroutput">persons</tt>
</span></dt><dd><p>The set of all defined persons. To allow easy sorting of persons, the
name requirement <a href="groups-requirements.html#groups-requirements-30-10">30.10</a> is met by
-splitting the person's name into two columns: <tt>first_names</tt> and
-<tt>last_name</tt>.</p></dd><dt><span class="term"><tt>users</tt>
+splitting the person's name into two columns: <tt class="computeroutput">first_names</tt> and
+<tt class="computeroutput">last_name</tt>.</p></dd><dt><span class="term"><tt class="computeroutput">users</tt>
</span></dt><dd><p>The set of all registered users; this table includes information about
-the user's email address and the user's visits to the site.</p></dd><dt><span class="term"><tt>user_preferences</tt>
+the user's email address and the user's visits to the site.</p></dd><dt><span class="term"><tt class="computeroutput">user_preferences</tt>
-</span></dt><dd><p>Preferences for the user.</p></dd><dt><span class="term"><tt>groups</tt>
+</span></dt><dd><p>Preferences for the user.</p></dd><dt><span class="term"><tt class="computeroutput">groups</tt>
-</span></dt><dd><p>The set of all defined groups.</p></dd><dt><span class="term"><tt>group_types</tt>
+</span></dt><dd><p>The set of all defined groups.</p></dd><dt><span class="term"><tt class="computeroutput">group_types</tt>
</span></dt><dd><p>When a new type of group is created, this table holds additional
-knowledge level attributes for the group and its subtypes.</p></dd><dt><span class="term"><tt>membership_rels</tt>
+knowledge level attributes for the group and its subtypes.</p></dd><dt><span class="term"><tt class="computeroutput">membership_rels</tt>
</span></dt><dd><p>The set of direct membership relationships between a group and a
-party.</p></dd><dt><span class="term"><tt>group_member_index</tt>
+party.</p></dd><dt><span class="term"><tt class="computeroutput">group_member_index</tt>
</span></dt><dd><p>A mapping of a party <span class="strong">P</span> to the groups
{<span class="strong">G<sub>i</sub></span>}the party is a member of; this mapping
-includes the type of relationship by including the appropriate<tt>rel_id</tt>
-from the <tt>membership_rels</tt> table.</p></dd><dt><span class="term"><tt>composition_rels</tt>
+includes the type of relationship by including the appropriate<tt class="computeroutput">rel_id</tt>
+from the <tt class="computeroutput">membership_rels</tt> table.</p></dd><dt><span class="term"><tt class="computeroutput">composition_rels</tt>
</span></dt><dd><p>The set of direct component relationships between a group and another
-group.</p></dd><dt><span class="term"><tt>group_component_index</tt>
+group.</p></dd><dt><span class="term"><tt class="computeroutput">group_component_index</tt>
</span></dt><dd><p>A mapping of a group <span class="strong">G</span>to the set of groups
{<span class="strong">G<sub>i</sub></span>} that <span class="strong">G</span> is a component of;
this mapping includes the type of relationship by including the
-appropriate<tt>rel_id</tt> from the <tt>composition_rels</tt> table.</p></dd></dl></div><p>New groups are created through the <tt>group.new</tt> constructor.
+appropriate<tt class="computeroutput">rel_id</tt> from the <tt class="computeroutput">composition_rels</tt> table.</p></dd></dl></div><p>New groups are created through the <tt class="computeroutput">group.new</tt> constructor.
When a specialized type of group is required, the group type can be extended
by an application developer. Membership constraints can be specified at
-creation time by passing a parent group to the constructor.</p><p>The <tt>membership_rels</tt> and <tt>composition_rels</tt> tables indicate
+creation time by passing a parent group to the constructor.</p><p>The <tt class="computeroutput">membership_rels</tt> and <tt class="computeroutput">composition_rels</tt> tables indicate
a group's direct members and direct components; these tables do not
provide a record of the members or components that are in the group by virtue
of being a member or component of one of the group's component groups.
@@ -86,60 +85,60 @@
queries responsive, the data model includes triggers (described in the next
paragraph) which watch for changes in membership or composition and update
tables that maintain the group party mappings, i.e.,
-<tt>group_member_index</tt> and <tt>group_component_index</tt>. One can think
-of these tables as a manually maintained index.</p><p>The following triggers keep the <tt>group_*_index</tt> tables up to
-date:</p><div class="variablelist"><dl><dt><span class="term"><tt>membership_rels_in_tr</tt>
+<tt class="computeroutput">group_member_index</tt> and <tt class="computeroutput">group_component_index</tt>. One can think
+of these tables as a manually maintained index.</p><p>The following triggers keep the <tt class="computeroutput">group_*_index</tt> tables up to
+date:</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">membership_rels_in_tr</tt>
</span></dt><dd><p>Is executed when a new group/member relationship is created (an insert on
-<tt>membership_rels</tt>)</p></dd><dt><span class="term"><tt>membership_rels_del_tr</tt>
+<tt class="computeroutput">membership_rels</tt>)</p></dd><dt><span class="term"><tt class="computeroutput">membership_rels_del_tr</tt>
</span></dt><dd><p>Is executed when a group/member relationship is deleted (a delete on
-<tt>membership_rels</tt>)</p></dd><dt><span class="term"><tt>composition_rels_in_tr</tt>
+<tt class="computeroutput">membership_rels</tt>)</p></dd><dt><span class="term"><tt class="computeroutput">composition_rels_in_tr</tt>
</span></dt><dd><p>Is executed when a new group/component relationship is created (an insert
-on <tt>composition_rels</tt>)</p></dd><dt><span class="term"><tt>composition_rels_del_tr</tt>
+on <tt class="computeroutput">composition_rels</tt>)</p></dd><dt><span class="term"><tt class="computeroutput">composition_rels_del_tr</tt>
</span></dt><dd><p>Is executed when a group/component relationship is deleted (a delete on
-<tt>composition_rels</tt>)</p></dd></dl></div><p>The data model provides the following views onto the
-<tt>group_member_index</tt> and <tt>group_component_index</tt> tables. No
-code outside of Groups System should modify the <tt>group_*_index</tt>
-tables.</p><div class="variablelist"><dl><dt><span class="term"><tt>group_member_map</tt>
+<tt class="computeroutput">composition_rels</tt>)</p></dd></dl></div><p>The data model provides the following views onto the
+<tt class="computeroutput">group_member_index</tt> and <tt class="computeroutput">group_component_index</tt> tables. No
+code outside of Groups System should modify the <tt class="computeroutput">group_*_index</tt>
+tables.</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">group_member_map</tt>
</span></dt><dd><p>A mapping of a party to the groups the party is a member of; this mapping
-includes the type of relationship by including the appropriate<tt>rel_id</tt>
-from the <tt>membership_rels</tt> table.</p></dd><dt><span class="term"><tt>group_approved_member_map</tt>
+includes the type of relationship by including the appropriate<tt class="computeroutput">rel_id</tt>
+from the <tt class="computeroutput">membership_rels</tt> table.</p></dd><dt><span class="term"><tt class="computeroutput">group_approved_member_map</tt>
</span></dt><dd><p>A mapping of a party to the groups the party is an approved member of
-(<tt>member_state</tt> is 'approved'); this mapping includes the type
-of relationship by including the appropriate<tt>rel_id</tt> from the
-<tt>membership_rels</tt> table.</p></dd><dt><span class="term"><tt>group_distinct_member_map</tt>
+(<tt class="computeroutput">member_state</tt> is 'approved'); this mapping includes the type
+of relationship by including the appropriate<tt class="computeroutput">rel_id</tt> from the
+<tt class="computeroutput">membership_rels</tt> table.</p></dd><dt><span class="term"><tt class="computeroutput">group_distinct_member_map</tt>
</span></dt><dd><p>A person may appear in the group member map multiple times, for example,
by being a member of two different groups that are both components of a third
group. This view is strictly a mapping of <span class="strong">approved</span> members
-to groups.</p></dd><dt><span class="term"><tt>group_component_map</tt>
+to groups.</p></dd><dt><span class="term"><tt class="computeroutput">group_component_map</tt>
</span></dt><dd><p>A mapping of a group <span class="strong">G</span>to the set of groups
{<span class="strong">G<sub>i</sub></span>} group <span class="strong">G</span> is a component of;
this mapping includes the type of relationship by including the
-appropriate<tt>rel_id</tt> from the <tt>composition_rels</tt> table.</p></dd><dt><span class="term"><tt>party_member_map</tt>
+appropriate<tt class="computeroutput">rel_id</tt> from the <tt class="computeroutput">composition_rels</tt> table.</p></dd><dt><span class="term"><tt class="computeroutput">party_member_map</tt>
</span></dt><dd><p>A mapping of a party <span class="strong">P</span> to the set of parties
{<span class="strong">P<sub>i</sub></span>} party <span class="strong">P</span> is a member
-of.</p></dd><dt><span class="term"><tt>party_approved_member_map</tt>
+of.</p></dd><dt><span class="term"><tt class="computeroutput">party_approved_member_map</tt>
</span></dt><dd><p>A mapping of a party <span class="strong">P</span> to the set of parties
{<span class="strong">P<sub>i</sub></span>} party <span class="strong">P</span> is an
-<span class="strong">approved</span> member of.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-api"></a>API</h3></div></div><p>
+<span class="strong">approved</span> member of.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-api"></a>API</h3></div></div><div></div></div><p>
The API consists of tables and views and PL/SQL functions.
-</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="groups-design-tables-views"></a>Tables and Views</h4></div></div><p>The <tt>group_types</tt> table is used to create new types of groups.</p><p>The <tt>group_member_map</tt>, <tt>group_approved_member_map</tt>,
-<tt>group_distinct_member_map</tt>, <tt>group_component_map</tt>,
-<tt>party_member_map</tt>, and <tt>party_approved_member_map</tt> views are
-used to query group membership and composition.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="groups-design-pl-sql-api"></a>PL/SQL API</h4></div></div><p><span class="strong">Person</span></p><p><tt>person.new</tt> creates a new person and returns the
-<tt>person_id</tt>. The function must be given the full name of the person in
-two pieces: <tt>first_names</tt> and <tt>last_name</tt>. All other fields are
-optional and default to null except for <tt>object_type</tt> which defaults
-to person and <tt>creation_date</tt> which defaults to <tt>sysdate</tt>. The
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="groups-design-tables-views"></a>Tables and Views</h4></div></div><div></div></div><p>The <tt class="computeroutput">group_types</tt> table is used to create new types of groups.</p><p>The <tt class="computeroutput">group_member_map</tt>, <tt class="computeroutput">group_approved_member_map</tt>,
+<tt class="computeroutput">group_distinct_member_map</tt>, <tt class="computeroutput">group_component_map</tt>,
+<tt class="computeroutput">party_member_map</tt>, and <tt class="computeroutput">party_approved_member_map</tt> views are
+used to query group membership and composition.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="groups-design-pl-sql-api"></a>PL/SQL API</h4></div></div><div></div></div><p><span class="strong">Person</span></p><p><tt class="computeroutput">person.new</tt> creates a new person and returns the
+<tt class="computeroutput">person_id</tt>. The function must be given the full name of the person in
+two pieces: <tt class="computeroutput">first_names</tt> and <tt class="computeroutput">last_name</tt>. All other fields are
+optional and default to null except for <tt class="computeroutput">object_type</tt> which defaults
+to person and <tt class="computeroutput">creation_date</tt> which defaults to <tt class="computeroutput">sysdate</tt>. The
interface for this function is:</p><pre class="programlisting">
function person.new (
person_id persons.person_id%TYPE,
@@ -152,19 +151,19 @@
first_names persons.first_names%TYPE,
last_name persons.last_name%TYPE
) return persons.person_id%TYPE;
-</pre><p><tt>person.delete</tt> deletes the person whose <tt>person_id</tt> is
+</pre><p><tt class="computeroutput">person.delete</tt> deletes the person whose <tt class="computeroutput">person_id</tt> is
passed to it. The interface for this procedure is:</p><pre class="programlisting">
procedure person.delete (
person_id persons.person_id%TYPE
);
-</pre><p><tt>person.name</tt> returns the name of the person whose
-<tt>person_id</tt> is passed to it. The interface for this function is:</p><pre class="programlisting">
+</pre><p><tt class="computeroutput">person.name</tt> returns the name of the person whose
+<tt class="computeroutput">person_id</tt> is passed to it. The interface for this function is:</p><pre class="programlisting">
function person.name (
person_id persons.person_id%TYPE
) return varchar;
-</pre><p><span class="strong">User</span></p><p><tt>acs_user.new</tt> creates a new user and returns the <tt>user_id</tt>.
+</pre><p><span class="strong">User</span></p><p><tt class="computeroutput">acs_user.new</tt> creates a new user and returns the <tt class="computeroutput">user_id</tt>.
The function must be given the user's email address and the full name of
-the user in two pieces: <tt>first_names</tt> and <tt>last_name</tt>. All
+the user in two pieces: <tt class="computeroutput">first_names</tt> and <tt class="computeroutput">last_name</tt>. All
other fields are optional. The interface for this function is:</p><pre class="programlisting">
function acs_user.new (
user_id users.user_id%TYPE,
@@ -183,19 +182,19 @@
screen_name users.screen_name%TYPE,
email_verified_p users.email_verified_p%TYPE
) return users.user_id%TYPE;
-</pre><p><tt>acs_user.delete</tt> deletes the user whose <tt>user_id</tt> is passed
+</pre><p><tt class="computeroutput">acs_user.delete</tt> deletes the user whose <tt class="computeroutput">user_id</tt> is passed
to it. The interface for this procedure is:</p><pre class="programlisting">
procedure acs_user.delete (
user_id users.user_id%TYPE
);
-</pre><p><tt>acs_user.receives_alerts_p</tt> returns 't' if the user should
+</pre><p><tt class="computeroutput">acs_user.receives_alerts_p</tt> returns 't' if the user should
receive email alerts and 'f' otherwise. The interface for this
function is:</p><pre class="programlisting">
function acs_user.receives_alerts_p (
user_id users.user_id%TYPE
) return varchar;
-</pre><p>Use the procedures <tt>acs_user.approve_email</tt> and
-<tt>acs_user.unapprove_email</tt> to specify whether the user's email
+</pre><p>Use the procedures <tt class="computeroutput">acs_user.approve_email</tt> and
+<tt class="computeroutput">acs_user.unapprove_email</tt> to specify whether the user's email
address is valid. The interface for these procedures are:</p><pre class="programlisting">
procedure acs_user.approve_email (
user_id users.user_id%TYPE
@@ -204,11 +203,11 @@
procedure acs_user.unapprove_email (
user_id users.user_id%TYPE
);
-</pre><p><span class="strong">Group</span></p><p><tt>acs_group.new</tt> creates a new group and returns the
-<tt>group_id</tt>. All fields are optional and default to null except for
-<tt>object_type</tt> which defaults to 'group',
-<tt>creation_date</tt> which defaults to <tt>sysdate</tt>, and
-<tt>group_name</tt> which is required. The interface for
+</pre><p><span class="strong">Group</span></p><p><tt class="computeroutput">acs_group.new</tt> creates a new group and returns the
+<tt class="computeroutput">group_id</tt>. All fields are optional and default to null except for
+<tt class="computeroutput">object_type</tt> which defaults to 'group',
+<tt class="computeroutput">creation_date</tt> which defaults to <tt class="computeroutput">sysdate</tt>, and
+<tt class="computeroutput">group_name</tt> which is required. The interface for
this function is:</p><pre class="programlisting">
function acs_group.new (
group_id groups.group_id%TYPE,
@@ -220,21 +219,21 @@
url parties.url%TYPE,
group_name groups.group_name%TYPE
) return groups.group_id%TYPE;
-</pre><p><tt>acs_group.name</tt> returns the name of the group whose
-<tt>group_id</tt> is passed to it. The interface for this function is:</p><pre class="programlisting">
+</pre><p><tt class="computeroutput">acs_group.name</tt> returns the name of the group whose
+<tt class="computeroutput">group_id</tt> is passed to it. The interface for this function is:</p><pre class="programlisting">
function acs_group.name (
group_id groups.group_id%TYPE
) return varchar;
-</pre><p><tt>acs_group.member_p</tt> returns 't' if the specified party is
+</pre><p><tt class="computeroutput">acs_group.member_p</tt> returns 't' if the specified party is
a member of the specified group. Returns 'f' otherwise. The interface
for this function is:</p><pre class="programlisting">
function acs_group.member_p (
group_id groups.group_id%TYPE,
party_id parties.party_id%TYPE,
) return char;
-</pre><p><span class="strong">Membership Relationship</span></p><p><tt>membership_rel.new</tt> creates a new membership relationship type
-between two parties and returns the relationship type's <tt>rel_id</tt>.
-All fields are optional and default to null except for <tt>rel_type</tt>
+</pre><p><span class="strong">Membership Relationship</span></p><p><tt class="computeroutput">membership_rel.new</tt> creates a new membership relationship type
+between two parties and returns the relationship type's <tt class="computeroutput">rel_id</tt>.
+All fields are optional and default to null except for <tt class="computeroutput">rel_type</tt>
which defaults to membership_rel. The interface for this function is:</p><pre class="programlisting">
function membership_rel.new (
rel_id membership_rels.rel_id%TYPE,
@@ -245,42 +244,42 @@
creation_user acs_objects.creation_user%TYPE,
creation_ip acs_objects.creation_ip%TYPE,
) return membership_rels.rel_id%TYPE;
-</pre><p><tt>membership_rel.ban</tt> sets the <tt>member_state</tt> of the given
-<tt>rel_id</tt> to 'banned'. The interface for this procedure is:</p><pre class="programlisting">
+</pre><p><tt class="computeroutput">membership_rel.ban</tt> sets the <tt class="computeroutput">member_state</tt> of the given
+<tt class="computeroutput">rel_id</tt> to 'banned'. The interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.ban (
rel_id membership_rels.rel_id%TYPE
);
-</pre><p><tt>membership_rel.approve</tt> sets the <tt>member_state</tt> of the
-given <tt>rel_id</tt> to 'approved'. The interface for this procedure
+</pre><p><tt class="computeroutput">membership_rel.approve</tt> sets the <tt class="computeroutput">member_state</tt> of the
+given <tt class="computeroutput">rel_id</tt> to 'approved'. The interface for this procedure
is:</p><pre class="programlisting">
procedure membership_rel.approve (
rel_id membership_rels.rel_id%TYPE
);
-</pre><p><tt>membership_rel.reject</tt> sets the <tt>member_state</tt> of the given
-<tt>rel_id</tt> to 'rejected. The interface for this procedure is:</p><pre class="programlisting">
+</pre><p><tt class="computeroutput">membership_rel.reject</tt> sets the <tt class="computeroutput">member_state</tt> of the given
+<tt class="computeroutput">rel_id</tt> to 'rejected. The interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.reject (
rel_id membership_rels.rel_id%TYPE
);
-</pre><p><tt>membership_rel.unapprove</tt> sets the <tt>member_state</tt> of the
-given <tt>rel_id</tt> to an empty string ''. The interface for this
+</pre><p><tt class="computeroutput">membership_rel.unapprove</tt> sets the <tt class="computeroutput">member_state</tt> of the
+given <tt class="computeroutput">rel_id</tt> to an empty string ''. The interface for this
procedure is:</p><pre class="programlisting">
procedure membership_rel.unapprove (
rel_id membership_rels.rel_id%TYPE
);
-</pre><p><tt>membership_rel.deleted</tt> sets the <tt>member_state</tt> of the
-given <tt>rel_id</tt> to 'deleted'. The interface for this procedure
+</pre><p><tt class="computeroutput">membership_rel.deleted</tt> sets the <tt class="computeroutput">member_state</tt> of the
+given <tt class="computeroutput">rel_id</tt> to 'deleted'. The interface for this procedure
is:</p><pre class="programlisting">
procedure membership_rel.deleted (
rel_id membership_rels.rel_id%TYPE
);
-</pre><p><tt>membership_rel.delete</tt> deletes the given <tt>rel_id</tt>. The
+</pre><p><tt class="computeroutput">membership_rel.delete</tt> deletes the given <tt class="computeroutput">rel_id</tt>. The
interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.delete (
rel_id membership_rels.rel_id%TYPE
);
-</pre><p><span class="strong">Composition Relationship</span></p><p><tt>composition_rel.new</tt> creates a new composition relationship type
-and returns the relationship's <tt>rel_id</tt>. All fields are optional
-and default to null except for <tt>rel_type</tt> which defaults to
+</pre><p><span class="strong">Composition Relationship</span></p><p><tt class="computeroutput">composition_rel.new</tt> creates a new composition relationship type
+and returns the relationship's <tt class="computeroutput">rel_id</tt>. All fields are optional
+and default to null except for <tt class="computeroutput">rel_type</tt> which defaults to
composition_rel. The interface for this function is:</p><pre class="programlisting">
function membership_rel.new (
rel_id composition_rels.rel_id%TYPE,
@@ -290,15 +289,15 @@
creation_user acs_objects.creation_user%TYPE,
creation_ip acs_objects.creation_ip%TYPE,
) return composition_rels.rel_id%TYPE;
-</pre><p><tt>composition_rel.delete</tt> deletes the given <tt>rel_id</tt>. The
+</pre><p><tt class="computeroutput">composition_rel.delete</tt> deletes the given <tt class="computeroutput">rel_id</tt>. The
interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.delete (
rel_id composition_rels.rel_id%TYPE
);
-</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-ui"></a>User Interface</h3></div></div><p>Describe the admin pages.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-config"></a>Configuration/Parameters</h3></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-acc-tests"></a>Acceptance Tests</h3></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-authors"></a>Authors</h3></div></div><div class="variablelist"><dl><dt><span class="term">System creator
+</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-ui"></a>User Interface</h3></div></div><div></div></div><p>Describe the admin pages.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-config"></a>Configuration/Parameters</h3></div></div><div></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-acc-tests"></a>Acceptance Tests</h3></div></div><div></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><div></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-authors"></a>Authors</h3></div></div><div></div></div><div class="variablelist"><dl><dt><span class="term">System creator
</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">System owner
</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">Documentation author
-</span></dt><dd><p><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-design-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/22/2000</td><td><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></td></tr><tr><td>0.2</td><td>Initial Revision</td><td>08/30/2000</td><td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td></tr><tr><td>0.3</td><td>Additional revisions; tried to clarify membership/compostion</td><td>09/08/2000</td><td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Groups Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Subsites Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/groups-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
+</span></dt><dd><p><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/22/2000</td><td><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></td></tr><tr><td>0.2</td><td>Initial Revision</td><td>08/30/2000</td><td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td></tr><tr><td>0.3</td><td>Additional revisions; tried to clarify membership/compostion</td><td>09/08/2000</td><td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Groups Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Subsites Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/groups-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/groups-requirements.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,14 +1,13 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Groups Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="permissions-design.html" title="OpenACS 4 Permissions Design"><link rel="next" href="groups-design.html" title="OpenACS 4 Groups Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="groups-requirements"></a>OpenACS 4 Groups Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Groups Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="permissions-design.html" title="OpenACS 4 Permissions Design"><link rel="next" href="groups-design.html" title="OpenACS 4 Groups Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groups-requirements"></a>OpenACS 4 Groups Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>, <a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-intro"></a>Introduction</h3></div></div><p>Almost all database-backed websites have users, and need to model the
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-intro"></a>Introduction</h3></div></div><div></div></div><p>Almost all database-backed websites have users, and need to model the
grouping of users. The OpenACS 4 Parties and Groups system is intended to provide
the flexibility needed to model complex real-world organizational structures,
particularly to support powerful subsite services; that is, where one OpenACS
installation can support what appears to the user as distinct web services
-for different user communities.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-vision"></a>Vision Statement</h3></div></div><p>A powerful web service that can meet the needs of large enterprises must
+for different user communities.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>A powerful web service that can meet the needs of large enterprises must
be able to model the the real world's very rich organizational structures
and many ways of decomposing the same organization. For example, a
corporation can be broken into structures (the corporation, its divisions,
@@ -17,28 +16,28 @@
member of the division and the corporation, and works at (is a member of, but
in a different sense) a particular office. OpenACS 4's Parties and Groups
system will support such complex relations faithfully.</p><p><span class="strong">Historical Motivations</span></p><p>The primary limitation of the OpenACS 3.x user group system is that it
-restricts the application developer to representing a "flat group"
-that contains only users: The <tt>user_groups</tt> table may contain the
-<tt>group_id</tt> of a parent group, but parent-child relationship
+restricts the application developer to representing a "flat group"
+that contains only users: The <tt class="computeroutput">user_groups</tt> table may contain the
+<tt class="computeroutput">group_id</tt> of a parent group, but parent-child relationship
support is limited because it only allows one kind of relationship between
groups to be represented. Moreover, the Oracle database's limited support
for tree-like structures makes the queries over these relationships
expensive.</p><p>In addition, the Module Scoping design in OpenACS 3.0 introduced a
<span class="emphasis"><em>party</em></span> abstraction - a thing that is a person or a group of people -
though not in the form of an explicit table. Rather, the triple of
-<tt>scope</tt>, <tt>user_id</tt>, and <tt>group_id</tt> columns
+<tt class="computeroutput">scope</tt>, <tt class="computeroutput">user_id</tt>, and <tt class="computeroutput">group_id</tt> columns
was used to identify the party. One disadvantage of this design convention is
that it increases a data model's complexity by requiring the programmer
-to:</p><div class="itemizedlist"><ul type="disc"><li><p>add these three columns to each "scoped" table</p></li><li><p>define a multi-column check constraint to protect against data corruption
-(e.g., a row with a <tt>scope</tt> value of "group" but a null
-<tt>group_id</tt>)</p></li><li><p>perform extra checks in <tt>Tcl</tt> and <tt>PL/SQL</tt>
-functions and procedures to check both the <tt>user_id</tt> and
-<tt>group_id</tt> values</p></li></ul></div><p>In sum, the goal of the <span class="strong">Parties and Groups</span> system is to
+to:</p><div class="itemizedlist"><ul type="disc"><li><p>add these three columns to each "scoped" table</p></li><li><p>define a multi-column check constraint to protect against data corruption
+(e.g., a row with a <tt class="computeroutput">scope</tt> value of "group" but a null
+<tt class="computeroutput">group_id</tt>)</p></li><li><p>perform extra checks in <tt class="computeroutput">Tcl</tt> and <tt class="computeroutput">PL/SQL</tt>
+functions and procedures to check both the <tt class="computeroutput">user_id</tt> and
+<tt class="computeroutput">group_id</tt> values</p></li></ul></div><p>In sum, the goal of the <span class="strong">Parties and Groups</span> system is to
provide OpenACS programmers and site administrators with simple tools that fully
describe the complex relationships that exist among groups in the real
-world.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-user-scenarios"></a>User Scenarios</h3></div></div><p>Pat Developer has a client project and wants to model the company, its
+world.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-user-scenarios"></a>User Scenarios</h3></div></div><div></div></div><p>Pat Developer has a client project and wants to model the company, its
offices, its divisions, and its departments as groups and the employees as
-users.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-system-overview"></a>System Overview</h3></div></div><p>We start with <span class="strong">Groups</span>, which contain members; the
+users.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-system-overview"></a>System Overview</h3></div></div><div></div></div><p>We start with <span class="strong">Groups</span>, which contain members; the
<span class="strong">member can be either a person or another group</span> (i.e. a
member is a party).</p><p>In addition to membership, the party and groups system defines a
<span class="strong">composition</span> relationship that may exist between groups: A
@@ -72,7 +71,7 @@
<span class="strong">G<sub>C</sub></span>. For example, the system should be able to
enforce a rule like: Do not allow a party <span class="strong">P</span> to become a
member of <span class="strong">G<sub>C</sub></span> unless <span class="strong">P</span> is already
-a member of <span class="strong">G<sub>P</sub></span>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="groups-design.html">OpenACS 4 Groups Design</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-data-model"></a>Requirements: Data Model</h3></div></div><p>The data model for the parties and groups system must provide support for
+a member of <span class="strong">G<sub>P</sub></span>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-links"></a>Related Links</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="groups-design.html">OpenACS 4 Groups Design</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-data-model"></a>Requirements: Data Model</h3></div></div><div></div></div><p>The data model for the parties and groups system must provide support for
the following types of entities:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">10.0 Parties</span>
</span></dt><dd><p>A <span class="strong">party</span> is an entity used to represent either a
@@ -118,7 +117,7 @@
<span class="strong">G<sub>P</sub></span>.</p></li></ul></div><p><span class="strong">60.10</span>A group may be a component of multiple groups.</p><p><span class="strong">60.20</span>A group as a component of itself is not
supported.</p><p><span class="strong">60.30</span>The data model must support component
constraints.</p><p><span class="strong">60.40</span>The data model should support the subclassing of
-composition via OpenACS Relationships.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-api"></a>Requirements: API</h3></div></div><p>The API should let programmers accomplish the following tasks:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">70.10 Create a group</span>
+composition via OpenACS Relationships.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-api"></a>Requirements: API</h3></div></div><div></div></div><p>The API should let programmers accomplish the following tasks:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">70.10 Create a group</span>
</span></dt><dd><p>The parties and groups system provides a well defined API call that
creates a new group by running the appropriate transactions on the parties
@@ -177,39 +176,39 @@
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Is party <span class="strong">P</span> a member of group
-<span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">135.0 Composition check</span>
+"Is party <span class="strong">P</span> a member of group
+<span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">135.0 Composition check</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Is group <span class="strong">G<sub>C</sub></span> a component of group
-<span class="strong">G<sub>P</sub></span>?"</p></dd><dt><span class="term"><span class="strong">140.0 Get members query</span>
+"Is group <span class="strong">G<sub>C</sub></span> a component of group
+<span class="strong">G<sub>P</sub></span>?"</p></dd><dt><span class="term"><span class="strong">140.0 Get members query</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Which parties are members of group <span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">145.0 Get components query</span>
+"Which parties are members of group <span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">145.0 Get components query</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Which groups are components of group <span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">150.0 Member-of-groups query</span>
+"Which groups are components of group <span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">150.0 Member-of-groups query</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Of which groups is party <span class="strong">P</span> a member?"</p></dd><dt><span class="term"><span class="strong">155.0 Component-of-groups query</span>
+"Of which groups is party <span class="strong">P</span> a member?"</p></dd><dt><span class="term"><span class="strong">155.0 Component-of-groups query</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Of which groups is group <span class="strong">G</span> a component?"</p></dd><dt><span class="term"><span class="strong">160.0 Allowed membership check</span>
+"Of which groups is group <span class="strong">G</span> a component?"</p></dd><dt><span class="term"><span class="strong">160.0 Allowed membership check</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Is party <span class="strong">P</span> allowed to become a member of group
-<span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">165.0 Allowed composition check</span>
+"Is party <span class="strong">P</span> allowed to become a member of group
+<span class="strong">G</span>?"</p></dd><dt><span class="term"><span class="strong">165.0 Allowed composition check</span>
</span></dt><dd><p>The parties and groups system provides an API for answering the question:
-"Is group <span class="strong">G<sub>C</sub></span> allowed to become a component
-of group <span class="strong">G<sub>P</sub></span>?"</p></dd><dt><span class="term"><span class="strong">170.0 Efficiency</span>
+"Is group <span class="strong">G<sub>C</sub></span> allowed to become a component
+of group <span class="strong">G<sub>P</sub></span>?"</p></dd><dt><span class="term"><span class="strong">170.0 Efficiency</span>
</span></dt><dd><p>Since many pages at a site may check membership in a group before serving
@@ -219,7 +218,7 @@
</span></dt><dd><p>Since many SQL queries will check membership in a group as part of the
-<tt>where</tt> clause, whatever mechanism is used to check membership in SQL
-should be fairly small and simple.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-ui"></a>Requirements: User Interface</h3></div></div><p>The user interface is a set of HTML pages that are used to drive the
+<tt class="computeroutput">where</tt> clause, whatever mechanism is used to check membership in SQL
+should be fairly small and simple.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-ui"></a>Requirements: User Interface</h3></div></div><div></div></div><p>The user interface is a set of HTML pages that are used to drive the
underlying API. The user interface may provide the following functions:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">200.0</span> Create a party</p></li><li><p><span class="strong">210.0</span> View the attributes of a party</p></li><li><p><span class="strong">220.0</span> Update the attributes of a party</p></li><li><p><span class="strong">240.0</span> Delete a party</p></li><li><p><span class="strong">250.0</span> Add a party to a group</p></li><li><p><span class="strong">260.0</span> Remove a party from a group</p></li><li><p><span class="strong">270.0</span> Perform the membership and composition checks
-outlined in 130.x to 165.x</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/16/2000</td><td>Rafael Schloming</td></tr><tr><td>0.2</td><td>Initial revision</td><td>08/19/2000</td><td>Mark Thomas</td></tr><tr><td>0.3</td><td>Edited and reviewed, conforms to requirements template</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Further revised, added UI requirements</td><td>08/24/2000</td><td>Mark Thomas</td></tr><tr><td>0.5</td><td>Final edits, pending freeze</td><td>08/24/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>More revisions, added composition requirements</td><td>08/30/2000</td><td>Mark Thomas</td></tr><tr><td>0.7</td><td>More revisions, added composition requirements</td><td>09/08/2000</td><td>Mark Thomas</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Permissions Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Groups Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/groups-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
+outlined in 130.x to 165.x</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/16/2000</td><td>Rafael Schloming</td></tr><tr><td>0.2</td><td>Initial revision</td><td>08/19/2000</td><td>Mark Thomas</td></tr><tr><td>0.3</td><td>Edited and reviewed, conforms to requirements template</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Further revised, added UI requirements</td><td>08/24/2000</td><td>Mark Thomas</td></tr><tr><td>0.5</td><td>Final edits, pending freeze</td><td>08/24/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>More revisions, added composition requirements</td><td>08/30/2000</td><td>Mark Thomas</td></tr><tr><td>0.7</td><td>More revisions, added composition requirements</td><td>09/08/2000</td><td>Mark Thomas</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Permissions Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Groups Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/groups-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 20 Aug 2003 16:20:16 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 14 Oct 2003 11:02:58 -0000 1.3
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Internationalization Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="db-api-detailed.html" title="Database Access API"><link rel="next" href="i18n.html" title="Internationalization"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="i18n-requirements"></a>OpenACS Internationalization Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Internationalization Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="db-api-detailed.html" title="Database Access API"><link rel="next" href="i18n.html" title="Internationalization"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-requirements"></a>OpenACS Internationalization Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by Henry Minsky,
<a href="mailto:yon@openforce.net" target="_top">Yon Feldman</a>,
<a href="mailto:lars@collaboraid.biz" target="_top">Lars Pind</a>,
@@ -9,13 +8,13 @@
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-requirements-introduction"></a>Introduction</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-introduction"></a>Introduction</h3></div></div><div></div></div><p>
This document describes the requirements for functionality in
the OpenACS platform to support globalization of the core and optional
modules. The goal is to make it possible to support delivery of
applications which work properly in multiple locales with the
lowest development and maintenance cost.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-requirements-definitions"></a>Definitions</h3></div></div><div class="variablelist"><dl><dt><span class="term">internationalization (i18n)</span></dt><dd><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-definitions"></a>Definitions</h3></div></div><div></div></div><div class="variablelist"><dl><dt><span class="term">internationalization (i18n)</span></dt><dd><p>
The provision within a computer program of the
capability of making itself adaptable to the requirements of different
native languages, local customs and coded character sets.
@@ -30,7 +29,7 @@
A product development approach which ensures that software products
are usable in the worldwide markets through a combination of
internationalization and localization.
- </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="II._Vision_Statement"></a>Vision Statement</h3></div></div><p>The Mozilla project suggests keeping two catchy phrases in
+ </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="II._Vision_Statement"></a>Vision Statement</h3></div></div><div></div></div><p>The Mozilla project suggests keeping two catchy phrases in
mind when thinking about globalization:</p><div class="itemizedlist"><ul type="disc"><li><p>One code base for the world</p></li><li><p>English is just another language</p></li></ul></div><p>Building an application often involves making a number of
assumptions on the part of the developers which depend on their own
culture. These include constant strings in the user interface and
@@ -46,7 +45,7 @@
kind of globalization support would be large and ongoing, since
without a mechanism to incorporate the locale-specific changes
cleanly back into the code base, it would require making a new fork
-of the source code for each locale.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="III._System/Application_Overview"></a>System/Application Overview</h3></div></div><p>A globalized application will perform some or all of the
+of the source code for each locale.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="III._System/Application_Overview"></a>System/Application Overview</h3></div></div><div></div></div><p>A globalized application will perform some or all of the
following steps to handle a page request for a specific
locale:</p><div class="orderedlist"><ol type="1"><li><p>Decide what the target locale is for an incoming page
request</p></li><li><p>Decide which character set encoding the output should be
@@ -71,7 +70,7 @@
Java which we will want to move to. So the design to meet the
requirements will tend to rely on these capabilities, or close
approximations to them where possible, in order to make it easier
-to maintain Tcl and Java OpenACS versions.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="IV._Use-cases_and_User-scenarios"></a>Use-cases and User-scenarios</h3></div></div><p>Here are the cases that we need to be able to handle
+to maintain Tcl and Java OpenACS versions.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="IV._Use-cases_and_User-scenarios"></a>Use-cases and User-scenarios</h3></div></div><div></div></div><p>Here are the cases that we need to be able to handle
efficiently:</p><div class="orderedlist"><ol type="1"><li><p>A developer needs to author a web site/application in a
language besides English, and possibly a character set besides
ISO-8859-1. This includes the operation of the OpenACS itself, i.e.,
@@ -92,10 +91,10 @@
for other locales. This would include support for creating
resources such as message catalogs, non-text assets such as
graphics, and use of templates which help to separate application
-logic from presentation.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="Competitive_Analysis"></a>Competitive
-Analysis</h3></div></div><p>Other application servers: ATG Dyanmo, Broadvision, Vignette,
-... ? Anyone know how they deal with i18n ?</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="V._Related_Links"></a>Related
-Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>System/Package "coversheet" - where all
+logic from presentation.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Competitive_Analysis"></a>Competitive
+Analysis</h3></div></div><div></div></div><p>Other application servers: ATG Dyanmo, Broadvision, Vignette,
+... ? Anyone know how they deal with i18n ?</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="V._Related_Links"></a>Related
+Links</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>System/Package "coversheet" - where all
documentation for this software is linked off of</em></span></p></li><li><p><span class="emphasis"><em><a href="i18n.html#i18n-design" title="Design Notes">Design document</a></em></span></p></li><li><p><span class="emphasis"><em><a href="i18n.html" title="Internationalization">Developer's guide</a></em></span></p></li><li><p><span class="emphasis"><em>User's guide</em></span></p></li><li><p><span class="emphasis"><em>Other-cool-system-related-to-this-one
document</em></span></p><p><a href="http://www.li18nux.net/" target="_top">LI18NUX
2000 Globalization Specification:
@@ -107,10 +106,10 @@
Codes for the representation of names of countries and their
subdivisions Part 1: Country codes
http://www.niso.org/3166.html</a></p><p><a href="http://www.isi.edu/in-notes/iana/assignments/character-sets" target="_top">IANA
-Registry of Character Sets</a></p></li><li><p><span class="emphasis"><em>Test plan</em></span></p></li><li><p><span class="emphasis"><em>Competitive system(s)</em></span></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI_Requirements"></a>Requirements</h3></div></div><p>Because the requirements for globalization affect many areas
+Registry of Character Sets</a></p></li><li><p><span class="emphasis"><em>Test plan</em></span></p></li><li><p><span class="emphasis"><em>Competitive system(s)</em></span></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI_Requirements"></a>Requirements</h3></div></div><div></div></div><p>Because the requirements for globalization affect many areas
of the system, we will break up the requirements into phases, with
a base required set of features, and then stages of increasing
-functionality.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.A_Locales"></a>Locales</h3></div></div><p><span class="emphasis"><em>10.0</em></span></p><p>A standard representation of locale will be used throughout
+functionality.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.A_Locales"></a>Locales</h3></div></div><div></div></div><p><span class="emphasis"><em>10.0</em></span></p><p>A standard representation of locale will be used throughout
the system. A locale refers to a language and territory, and is
uniquely identified by a combination of ISO language and ISO
country abbreviations.</p><div class="blockquote"><blockquote class="blockquote"><p>See
@@ -120,19 +119,19 @@
locale-aware formatting and parsing functions for numbers, dates
and times. <span class="emphasis"><em>Note that Java has builtin support for these
already</em></span>.</p><p><span class="emphasis"><em>10.30</em></span> For each locale there will be
-default date, number and currency formats. <i>Currency i18n is
-NOT IMPLEMENTED for 5.0.0.</i></p><p><span class="emphasis"><em>10.40</em></span>Administrators can upgrade their
-servers to use new locales via the APM. <i>NOT IMPLEMENTED in
+default date, number and currency formats. <i><span class="remark">Currency i18n is
+NOT IMPLEMENTED for 5.0.0.</span></i></p><p><span class="emphasis"><em>10.40</em></span>Administrators can upgrade their
+servers to use new locales via the APM. <i><span class="remark">NOT IMPLEMENTED in
5.0.0; current workaround is to get an xml file and load it
-manually.</i></p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.B_Associating_a_Locale_with_a_Request"></a>Associating a Locale with a Request</h3></div></div><p><span class="emphasis"><em>20.0</em></span></p><p>The request processor must have a mechanism for associating a
+manually.</span></i></p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.B_Associating_a_Locale_with_a_Request"></a>Associating a Locale with a Request</h3></div></div><div></div></div><p><span class="emphasis"><em>20.0</em></span></p><p>The request processor must have a mechanism for associating a
locale with each request. This locale is then used to select the
appropriate template for a request, and will also be passed as the
locale argument to the message catalog or locale-specific
formatting functions.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>20.10</em></span> The locale for a request should be
computed by the following method, in descending order of
priority:</p><div class="itemizedlist"><ul type="disc"><li><p>get locale associated with subsite or package id</p></li><li><p>get locale from user preference</p></li><li><p>get locale from site wide default</p><p><span class="emphasis"><em>20.20</em></span> An API will be provided for
getting the current request locale from the
-<tt>ad_conn</tt> structure.</p></li></ul></div></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.C_Resource_Bundles_/_Content_Repository"></a>Resource Bundles / Content Repository</h3></div></div><p><span class="emphasis"><em>30.0</em></span></p><p>A mechanism must be provided for a developer to group a set
+<tt class="literal">ad_conn</tt> structure.</p></li></ul></div></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.C_Resource_Bundles_/_Content_Repository"></a>Resource Bundles / Content Repository</h3></div></div><div></div></div><p><span class="emphasis"><em>30.0</em></span></p><p>A mechanism must be provided for a developer to group a set
of arbitrary content resources together, keyed by a unique
identifier and a locale.</p><p>For example, what approaches could be used to implement a
localizable nav-bar mechanism for a site? A navigation bar might be
@@ -144,7 +143,7 @@
functionality might include using templates, Java ResourceBundles,
content-item containers in the Content Repository, or some
convention assigning a common prefix to key strings in the message
-catalog.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.D_Message_Catalog_for_String_Translation"></a>Message Catalog for String Translation</h3></div></div><p><span class="emphasis"><em>40.0</em></span></p><p>A message catalog facility will provide a database of
+catalog.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.D_Message_Catalog_for_String_Translation"></a>Message Catalog for String Translation</h3></div></div><div></div></div><p><span class="emphasis"><em>40.0</em></span></p><p>A message catalog facility will provide a database of
translations for constant strings for multilingual applications. It
must support the following:</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>40.10</em></span> Each message will referenced via
unique a key.</p><p><span class="emphasis"><em>40.20</em></span> The key for a message will have
@@ -169,7 +168,7 @@
is modified, the other translations of that string can be flagged
as needing update.</p><p><span class="emphasis"><em>40.90</em></span> The message lookup must be as
efficient as possible so as not to slow down the delivery of
-pages.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.E_Character_Set_Encoding"></a>Character Set Encoding</h3></div></div><p><span class="emphasis"><em>Character Sets</em></span></p><p><span class="emphasis"><em>50.0</em></span> A locale will have a primary
+pages.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.E_Character_Set_Encoding"></a>Character Set Encoding</h3></div></div><div></div></div><p><span class="emphasis"><em>Character Sets</em></span></p><p><span class="emphasis"><em>50.0</em></span> A locale will have a primary
associated character set which is used to encode text in the
language. When given a locale, we can query the system for the
associated character set to use.</p><p>The assumption is that we are going to use Unicode in our
@@ -184,7 +183,7 @@
Writing Files</p></li><li><p>When the acs-templating package writes an an ADP or
TCL file, it assumes the file is iso-8859-1. If the output
charset (OutputCharset) in the AOLserver config file is set,
- then acs-templating assumes it's that charset. </p></li></ul></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Tcl_Source_File_Character_Set"></a>Tcl Source File Character Set</h4></div></div><div class="blockquote"><blockquote class="blockquote"><p>There are two classes of Tcl files loaded by the system;
+ then acs-templating assumes it's that charset. </p></li></ul></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Tcl_Source_File_Character_Set"></a>Tcl Source File Character Set</h4></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p>There are two classes of Tcl files loaded by the system;
library files loaded at server startup, and page script files,
which are run on each page request.</p><p><span class="emphasis"><em>Should we require all Tcl files be stored as UTF8?
That seems too much of a burden on developers.</em></span></p><p><span class="emphasis"><em>50.10</em></span> Tcl library files can be authored
@@ -193,31 +192,31 @@
filename.</p><p><span class="emphasis"><em>50.20</em></span> Tcl page script files can be
authored in any character set. The system must have a way to
determine the character set before loading the files, probably from
- the filename.</p></blockquote></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Submitted_Form_Data_Character_Set"></a>Submitted Form Data Character Set</h4></div></div><p><span class="emphasis"><em>50.30</em></span> Data which is submitted with a
+ the filename.</p></blockquote></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Submitted_Form_Data_Character_Set"></a>Submitted Form Data Character Set</h4></div></div><div></div></div><p><span class="emphasis"><em>50.30</em></span> Data which is submitted with a
HTTP request using a GET or POST method may be in any character
set. The system must be able to determine the encoding of the form
data and convert it to Unicode on demand. </p><p><span class="emphasis"><em>50.35</em></span> The developer must be able to
override the default system choice of character set when parsing
- and validating user form data. <i>INCOMPLETE - form
+ and validating user form data. <i><span class="remark">INCOMPLETE - form
widgets in acs-templating/tcl/date-procs.tcl are not
internationalized. Also, acs-templating's UI needs to be
internationalized by replacing all user-visible strings with
- message keys.</i></p><p><span class="emphasis"><em>50.30.10</em></span>In Japan and some
+ message keys.</span></i></p><p><span class="emphasis"><em>50.30.10</em></span>In Japan and some
other Asian languages where there are multiple character set
encodings in common use, the server may need to attempt to do an
auto-detection of the character set, because buggy browsers may
- submit form data in an unexpected alternate encoding.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Output_Character_Set"></a>Output Character Set</h4></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>50.40</em></span> The output character set for a
+ submit form data in an unexpected alternate encoding.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Output_Character_Set"></a>Output Character Set</h4></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>50.40</em></span> The output character set for a
page request will be determined by default by the locale associated
with the request (see requirement 20.0).</p><p><span class="emphasis"><em>50.50</em></span> It must be possible for a
developer to manually override the output character set encoding
for a request using an API function.
- </p></blockquote></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.F_ACS_Kernel_Issues"></a>ACS Kernel Issues</h3></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>60.10</em></span> All OpenACS error messages must use
+ </p></blockquote></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.F_ACS_Kernel_Issues"></a>ACS Kernel Issues</h3></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>60.10</em></span> All OpenACS error messages must use
the message catalog and the request locale to generate error
-message for the appropriate locale.<i>NOT IMPLEMENTED for 5.0.0.</i></p><p><span class="emphasis"><em>60.20</em></span> Web server error messages such as
+message for the appropriate locale.<i><span class="remark">NOT IMPLEMENTED for 5.0.0.</span></i></p><p><span class="emphasis"><em>60.20</em></span> Web server error messages such as
404, 500, etc must also be delivered in the appropriate
locale.</p><p><span class="emphasis"><em>60.30</em></span> Where files are written or read
from disk, their filenames must use a character set and character
-values which are safe for the underlying operating system.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.G_Templates"></a>Templates</h3></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>70.0</em></span> For a given abstract URL, the
+values which are safe for the underlying operating system.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.G_Templates"></a>Templates</h3></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>70.0</em></span> For a given abstract URL, the
designer may create multiple locale-specific template files may be
created (one per locale or language)</p><p><span class="emphasis"><em>70.10</em></span> For a given page request, the
system must be able to select an approprate locale-specific
@@ -228,28 +227,28 @@
current request locale.</p><p><span class="emphasis"><em>70.30</em></span> A template file may be created in
any character set. The system must have a way to know which
character set a template file contains, so it can properly process
-it.</p></blockquote></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Formatting_Datasource_Output_in_Templates"></a>Formatting
-Datasource Output in Templates</h4></div></div><p><span class="emphasis"><em>70.50</em></span> The properties of a datasource
+it.</p></blockquote></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Formatting_Datasource_Output_in_Templates"></a>Formatting
+Datasource Output in Templates</h4></div></div><div></div></div><p><span class="emphasis"><em>70.50</em></span> The properties of a datasource
column may include a datatype so that the templating system can
format the output for the current locale. The datatype is defined
by a standard OpenACS datatype plus a format token or format string,
for example: a date column might be specified as
'current_date:date LONG,' or 'current_date:date
-"YYYY-Mon-DD"'</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="Forms"></a>Forms</h4></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>70.60</em></span> The forms API must support
+"YYYY-Mon-DD"'</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Forms"></a>Forms</h4></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>70.60</em></span> The forms API must support
construction of locale-specific HTML form widgets, such as date
entry widgets, and form validation of user input data for
locale-specific data, such as dates or numbers. <span class="emphasis"><em>NOT
IMPLEMENTED in 5.0.0.</em></span></p><p><span class="emphasis"><em>70.70</em></span> For forms which allow users to
upload files, a standard method for a user to indicate the charset
of a text file being uploaded must be provided.</p><p><span class="emphasis"><em>Design note: this presumably applies to uploading
-data to the content repository as well</em></span></p></blockquote></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.H_Sorting_and_Searching"></a>Sorting and Searching</h3></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>80.10</em></span> Support API for correct collation
+data to the content repository as well</em></span></p></blockquote></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.H_Sorting_and_Searching"></a>Sorting and Searching</h3></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>80.10</em></span> Support API for correct collation
(sorting order) on lists of strings in locale-dependent way.</p><p><span class="emphasis"><em>80.20</em></span> For the Tcl API, we will say that
locale-dependent sorting will use Oracle SQL operations (i.e., we
won't provide a Tcl API for this). We require a Tcl API
function to return the correct incantation of NLS_SORT to use for a
-given locale with <tt>ORDER BY</tt> clauses in
+given locale with <tt class="literal">ORDER BY</tt> clauses in
queries.</p><p><span class="emphasis"><em>80.40</em></span> The system must handle full-text
-search in any supported language.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.G_Time_Zones"></a>Time Zones</h3></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>90.10</em></span> Provide API support for specifying
+search in any supported language.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.G_Time_Zones"></a>Time Zones</h3></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>90.10</em></span> Provide API support for specifying
a time zone</p><p><span class="emphasis"><em>90.20</em></span> Provide an API for computing time
and date operations which are aware of timezones. So for example a
calendar module can properly synchronize items inserted into a
@@ -260,13 +259,13 @@
zone preference should be attached via a session or else UTC should
be used to display every date and time.</p><p><span class="emphasis"><em>90.60</em></span> The default if we can't
determine a time zone is to display all dates and times in some
-universal time zone such as GMT.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.H_Database"></a>Database</h3></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>100.10</em></span> Since UTF8 strings can use up to
+universal time zone such as GMT.</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.H_Database"></a>Database</h3></div></div><div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>100.10</em></span> Since UTF8 strings can use up to
three (UCS2) or six (UCS4) bytes per character, make sure that
column size declarations in the schema are large enough to
accomodate required data (such as email addresses in
-Japanese). <i>Since 5.0.0, this is covered in the database
-install instructions for both PostGreSQL and Oracle.</i></p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="VI.I_Email_and_Messaging"></a>Email and
-Messaging</h3></div></div><p>When sending an email message, just as when delivering the
+Japanese). <i><span class="remark">Since 5.0.0, this is covered in the database
+install instructions for both PostGreSQL and Oracle.</span></i></p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="VI.I_Email_and_Messaging"></a>Email and
+Messaging</h3></div></div><div></div></div><p>When sending an email message, just as when delivering the
content in web page over an HTTP connection, it is necessary to be
able to specify what character set encoding to use.
</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>110.10</em></span> The email message sending API
@@ -289,10 +288,10 @@
(http://www.ietf.org/rfc/rfc3282.txt) and other RFCs.
</p></li><li><p>Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?
INCOMPLETE - The mail functions in acs_mail and acs_mail_lite
-are not internationalized.</p></li><li><p>Incoming mail should be localized.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-requirements-implementation-notes"></a>Implementation Notes</h3></div></div><p>
+are not internationalized.</p></li><li><p>Incoming mail should be localized.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-implementation-notes"></a>Implementation Notes</h3></div></div><div></div></div><p>
Because globalization touches many different parts of the system,
we want to reduce the implementation risk by breaking the
implementation into phases.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-requirements-revision-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>1</td><td>Updated with results of MIT-sponsored i18n work at Collaboraid.</td><td>14 Aug 2003</td><td>Joel Aufrecht</td></tr><tr><td>0.4</td><td>converting from HTML to DocBook and importing the document to the OpenACS
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-revision-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>1</td><td>Updated with results of MIT-sponsored i18n work at Collaboraid.</td><td>14 Aug 2003</td><td>Joel Aufrecht</td></tr><tr><td>0.4</td><td>converting from HTML to DocBook and importing the document to the OpenACS
kernel documents. This was done as a part of the internationalization of
OpenACS and .LRN for the Heidelberg University in Germany</td><td>12 September 2002</td><td>Peter Marklund</td></tr><tr><td>0.3</td><td>comments from Christian</td><td>1/14/2000</td><td>Henry Minsky</td></tr><tr><td>0.2</td><td>Minor typos fixed, clarifications to wording</td><td>11/14/2000</td><td>Henry Minsky</td></tr><tr><td>0.1</td><td>Creation</td><td>11/08/2000</td><td>Henry Minsky</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr><tr><td width="40%" align="left">Database Access API </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Internationalization</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/i18n-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/i18n.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/i18n.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/i18n.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,26 +1,25 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Internationalization</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"><link rel="next" href="security-requirements.html" title="OpenACS 4 Security Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="i18n"></a>Internationalization</h2></div></div><div class="authorblurb"><p><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Internationalization</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"><link rel="next" href="security-requirements.html" title="OpenACS 4 Security Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n"></a>Internationalization</h2></div></div><div></div></div><div class="authorblurb"><p><p>
By <a href="http://www.petermarklund.com/" target="_top">Peter Marklund</a>
and <a href="http://www.pinds.com/" target="_top">Lars Pind</a>
</p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-introduction"></a>Introduction</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-introduction"></a>Introduction</h3></div></div><div></div></div><p>
This document describes how to develop internationalized OpenACS
packages, including writing new packages with
internationalization and converting old packages. Text that
- users might see is "localizable text"; replacing monolingual text
+ users might see is "localizable text"; replacing monolingual text
and single-locale date/time/money functions with generic
- functions is "internationalization"; translating first
- generation text into a specific language is "localization." At
+ functions is "internationalization"; translating first
+ generation text into a specific language is "localization." At
a minimum, all packages should be internationalized. If you do
not also localize your package for different locales, volunteers
- may use a public "localization server" to submit suggested text.
+ may use a public "localization server" to submit suggested text.
Otherwise, your package will not be usable for all locales.
</p><p>
The main difference between monolingual and internationalized
packages is that all user-visible text in an internationalized
- package are coded as "message keys." The message keys
+ package are coded as "message keys." The message keys
correspond to a message catalog, which contains versions of the
text for each available language. Both script files
(ADP/TCL) and APM parameters are affected.
@@ -29,7 +28,7 @@
database must use internationalized functions. All displayed
dates must use internationalized functions. All displayed
numbers must use internationalized functions.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-message-catalog"></a>Using the Message Catalog</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-message-catalog"></a>Using the Message Catalog</h3></div></div><div></div></div><p>
Localizable text must be handled in ADP files, in TCL files, and
in APM Parameters. OpenACS provides two approaches, message
keys and localized ADP files. For ADP pages which are mostly
@@ -39,32 +38,32 @@
which are static and mostly text, it may be easier to create a
new ADP page for each language. In this case, the pages are
distinguished by a file naming convention.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2946848"></a>Separate Templates for each Locale</h4></div></div><p>If the request processor finds a file named <tt>filename.locale.adp</tt>, where locale matches the user's locale, it will process that file instead of <tt>filename.adp</tt>. For example, for a user with locale <tt>tl_PH</tt>, the file <tt>index.tl_PH.adp</tt>, if found, will be used instead of <tt>index.adp</tt>. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="i18n-message-catalog-adps"></a>Message Keys in Template Files (ADP Files)</h4></div></div><p>
+ </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2877091"></a>Separate Templates for each Locale</h4></div></div><div></div></div><p>If the request processor finds a file named <tt class="computeroutput">filename.locale.adp</tt>, where locale matches the user's locale, it will process that file instead of <tt class="computeroutput">filename.adp</tt>. For example, for a user with locale <tt class="computeroutput">tl_PH</tt>, the file <tt class="computeroutput">index.tl_PH.adp</tt>, if found, will be used instead of <tt class="computeroutput">index.adp</tt>. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-catalog-adps"></a>Message Keys in Template Files (ADP Files)</h4></div></div><div></div></div><p>
Internationalizing templates is about replacing human readable
text in a certain language with internal message keys, which
can then be dynamically replaced with real human language in
the desired locale. Message keys themselves should be in
ASCII English, as should all code. Three different syntaxes
are possible for message keys.
</p><p>
- "Short" syntax is the recommended syntax and should be used
+ "Short" syntax is the recommended syntax and should be used
for new development. When internationalizing an existing
- package, you can use the "temporary" syntax, which the APM can
+ package, you can use the "temporary" syntax, which the APM can
use to auto-generate missing keys and automatically translate
- to the short syntax. The "verbose" syntax is useful while
+ to the short syntax. The "verbose" syntax is useful while
developing, because it allows default text so that the page is
usable before you have done
localization. </p><div class="itemizedlist"><ul type="disc"><li><p>
The <span class="strong">short</span>:
- <tt>#<span class="emphasis"><em>package_key.message_key</em></span>#</tt>
+ <tt class="computeroutput">#<span class="emphasis"><em>package_key.message_key</em></span>#</tt>
</p><p>
The advantage of the short syntax is that it's short. It's
as simple as inserting the value of a variable. Example:
<span class="emphasis"><em>#forum.title#</em></span>
</p></li><li><p>
- The <span class="strong">verbose</span>: <tt><trn
- key="<span class="emphasis"><em>package_key.message_key</em></span>"
- locale="<span class="emphasis"><em>locale</em></span>"><span class="emphasis"><em>default
+ The <span class="strong">verbose</span>: <tt class="computeroutput"><trn
+ key="<span class="emphasis"><em>package_key.message_key</em></span>"
+ locale="<span class="emphasis"><em>locale</em></span>"><span class="emphasis"><em>default
text</em></span></trn></tt>
</p><p>
The verbose syntax allows you to specify a default text in
@@ -74,10 +73,11 @@
in the message catalog yet, because what it'll do is
create the message key with the default text from the tag
as the localized message. Example: <span class="emphasis"><em><trn
- key="forum.title" locale="en_US">Title</trn></em></span>
+ key="forum.title" locale="en_US">Title</trn></em></span>
</p></li><li><p>
The <span class="strong">temporary</span>:
- <tt> <#<span class="emphasis"><em>message_key</em></span> <span class="emphasis"><em>original�text</em></span>#></tt>
+ <tt class="computeroutput"> <#<span class="emphasis"><em>message_key</em></span>
+ <span class="emphasis"><em>original text</em></span>#></tt>
</p><p>
This syntax has been designed to make it easy to
internationalize existing pages. This is not a syntax that
@@ -88,7 +88,7 @@
auto-generated by the APM. Example: <span class="emphasis"><em><_ Title></em></span>
</p></li></ul></div><p>
We recommend the short notation for new package development.
- </p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="i18n-message-catalog-params"></a>APM Parameters</h4></div></div><p>
+ </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-catalog-params"></a>APM Parameters</h4></div></div><div></div></div><p>
Some parameters contain text that need to be localized. In
this case, instead of storing the real text in the parameter,
you should use message keys using the short notation above,
@@ -101,9 +101,9 @@
</p><p>
Here are a couple of examples. Say we have the following two
parameters, taken directly from the dotlrn package.
- </p><div class="table"><a name="id2891017"></a><p class="title"><b>Table�13.1.�</b></p><table cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Parameter Name</th><th>Parameter Value</th></tr></thead><tbody><tr><td>class_instance_pages_csv</td><td>#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</td></tr><tr><td>departments_pretty_name</td><td>#departments_pretty_name#</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2883687"></a><p class="title"><b>Table�13.1.�</b></p><table cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Parameter Name</th><th>Parameter Value</th></tr></thead><tbody><tr><td>class_instance_pages_csv</td><td>#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</td></tr><tr><td>departments_pretty_name</td><td>#departments_pretty_name#</td></tr></tbody></table></div><p>
Then, depending on how we retrieve the value, here's what we get:
- </p><div class="table"><a name="id2891104"></a><p class="title"><b>Table�13.2.�</b></p><table cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Command used to retrieve Value</th><th>Retrieved Value</th></tr></thead><tbody><tr><td>parameter::get <span class="strong">-localize</span> -parameter class_instances_pages_csv</td><td>Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column</td></tr><tr><td>parameter::get <span class="strong">-localize</span> -parameter departments_pretty_name</td><td>Abteilung</td></tr><tr><td>parameter::get -parameter departments_pretty_name</td><td>#departments_pretty_name#</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2883357"></a><p class="title"><b>Table�13.2.�</b></p><table cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Command used to retrieve Value</th><th>Retrieved Value</th></tr></thead><tbody><tr><td>parameter::get <span class="strong">-localize</span> -parameter class_instances_pages_csv</td><td>Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column</td></tr><tr><td>parameter::get <span class="strong">-localize</span> -parameter departments_pretty_name</td><td>Abteilung</td></tr><tr><td>parameter::get -parameter departments_pretty_name</td><td>#departments_pretty_name#</td></tr></tbody></table></div><p>
The value in the rightmost column in the table above is the
value returned by an invocation of parameter::get. Note that
for localization to happen you must use the -localize flag.
@@ -113,27 +113,27 @@
locale.
</p><p>
Developers are responsible for creating the keys in the message
- catalog, which is available at <tt>/acs-lang/admin/</tt>
- </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-date-time-number"></a>Dates, Times, and Numbers</h3></div></div><p>
+ catalog, which is available at <tt class="computeroutput">/acs-lang/admin/</tt>
+ </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-date-time-number"></a>Dates, Times, and Numbers</h3></div></div><div></div></div><p>
Dates and times must be converted when stored in the database,
when retrieved from the database, and when displayed. All dates
are stored in the database in the server's timezone, which is an
APM Parameter set at
- <tt>/acs-lang/admin/set-system-timezone</tt>
+ <tt class="computeroutput">/acs-lang/admin/set-system-timezone</tt>
and readable at
- <tt>lang::system::timezone.</tt>. When
+ <tt class="computeroutput">lang::system::timezone.</tt>. When
retrieved from the database and displayed, dates and times must
be localized to the user's locale.
</p><div class="orderedlist"><ol type="1"><li><p>
Get the date in ANSI format from the database (YYYY-MM-DD
HH24:MI:SS; the time portion is optional). By convention,
we identify dates in ansi format by ending the column name
- with <tt>_ansi</tt>.
+ with <tt class="computeroutput">_ansi</tt>.
Example:</p><pre class="programlisting">select to_char(posting_date, 'YYYY-MM-DD HH24:MI:SS') as posting_date_ansi
from table
</pre></li><li><p>
- Use the Tcl command <tt>lc_time_fmt</tt> to format the
- date in "pretty" format. Several standard formats localize automatically:
+ Use the Tcl command <tt class="computeroutput">lc_time_fmt</tt> to format the
+ date in "pretty" format. Several standard formats localize automatically:
</p><div class="itemizedlist"><ul type="disc"><li><p>
%c: Long date and time (Mon November 18, 2002 12:00 AM)
</p></li><li><p>
@@ -145,47 +145,47 @@
</p></li><li><p>
%Q: Long date with weekday (Monday November 18, 2002)
</p></li></ul></div><p>
- The "q" format strings are OpenACS additions; the rest follow unix standards (see <tt>man
+ The "q" format strings are OpenACS additions; the rest follow unix standards (see <tt class="computeroutput">man
strftime</tt>).
- </p><pre class="programlisting">set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]</pre></li><li><p>
- Use the <tt>*_pretty</tt> version in your ADP page.
+ </p><pre class="programlisting">set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]</pre></li><li><p>
+ Use the <tt class="computeroutput">*_pretty</tt> version in your ADP page.
</p></li></ol></div><p>
- To internationalize numbers, use <tt>lc_numeric $value</tt>, which formats the number using the appropriate decimal point and thousand separator for the locale.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-forms"></a>Internationalizing Forms</h3></div></div><p>When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-convert"></a>Internationalizing Existing Packages</h3></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2999216"></a>Internationalize Message text in ADP and TCL</h4></div></div><p>Acs-lang includes tools to automate some
+ To internationalize numbers, use <tt class="computeroutput">lc_numeric $value</tt>, which formats the number using the appropriate decimal point and thousand separator for the locale.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-forms"></a>Internationalizing Forms</h3></div></div><div></div></div><p>When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-convert"></a>Internationalizing Existing Packages</h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2884146"></a>Internationalize Message text in ADP and TCL</h4></div></div><div></div></div><p>Acs-lang includes tools to automate some
internationalization. From
- <tt>/acs-admin/apm/</tt>, select a
+ <tt class="computeroutput">/acs-admin/apm/</tt>, select a
package and then click on
- <tt>Internationalization</tt>, then
- <tt>Convert ADP, Tcl, and SQL files to using the
+ <tt class="computeroutput">Internationalization</tt>, then
+ <tt class="computeroutput">Convert ADP, Tcl, and SQL files to using the
message catalog.</tt>.</p><div class="orderedlist"><ol type="1"><li><p>
<span class="strong">Replace text with tags</span>:
- Choose <tt>Find human language text and replace with <# ... #> tags</tt>. This automated process
+ Choose <tt class="computeroutput">Find human language text and replace with <# ... #> tags</tt>. This automated process
automatically locates chunks of translatable text,
generates a reasonable message key, and replaces the text
- with a "temporary" tag as described above.
+ with a "temporary" tag as described above.
</p><p>Any pieces of text found but not extractable -- for
example, pieces of text with embedded adp variables
(i.e. @var_name@) -- will be listed on the result
page. Make sure to take note of these texts and translate
them manually. Suppose for example that our script tells you
- that it left the text "Manage forum @forum_name@"
+ that it left the text "Manage forum @forum_name@"
untouched. What you should do then is to edit the
corresponding adp file and manually replace that text with
- something like "<#manage_forum Manage forum @forum_name@#>"
+ something like "<#manage_forum Manage forum @forum_name@#>"
(to save you from too much typing you may use the shorthand
<#_ Manage forum @forum_name@#>; an underscore key will
result in the script auto-generating a key for you based on
the text). After you have made all such manual edits you can
- simply run the second action labeled "Replace tags with keys
- and insert into catalog".
+ simply run the second action labeled "Replace tags with keys
+ and insert into catalog".
</p><p>Note: running this action will not find translatable text within HTML or adp tags on adp pages (i.e. text in alt tags of images), nor will it find translatable text in tcl files. Such texts will have to be found manually. If those texts are in adp files they are best replaced with the <#message_key text#> tags that can be extracted by the action described below. Here are some commands that we used on Linux to look for texts in adp pages not found by the script:</p><pre class="programlisting">
# List image tags with alt attributes, look for alt attributes with literal text
find -iname '*.adp'|xargs egrep -i '<img.*alt='
# List submit buttons, look for text in the value attribute
-find -iname '*.adp'|xargs egrep -i '<input[^>]*type="?submit'
+find -iname '*.adp'|xargs egrep -i '<input[^>]*type="?submit'
</pre><p>
When you run this step, any modified files are backed up in
- a file with a ".orig" suffix. Those files are
+ a file with a ".orig" suffix. Those files are
never overwritten, though, so the .orig file will always be
the original page file, not the second-to-last file. Running
this action multiple times is harmless.
@@ -199,7 +199,7 @@
files</span>, marking up translatable text with the
<#...#> notation.
</p><p>Ttranslatable texts are often found in page titles, context bars, and form labels and options. Many times the texts are enclosed in double quotes. Use the following grep commands on Linux to highlight translatable text in tcl files for us:</p><pre class="programlisting"># Find text in double quotes
-find -iname '*.tcl'|xargs egrep -i '"[a-z]'
+find -iname '*.tcl'|xargs egrep -i '"[a-z]'
# Find untranslated text in form labels, options and values
find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
# Find text in page titles and context bars
@@ -214,8 +214,8 @@
${var_name}) with %var_name%</p></li><li><p>You are now ready to follow the normal procedure
and mark up the text using a tempoarary message tag (<#_
text_with_percentage_vars#>) and run the action replace
- tags with keys in the APM.</p></li></ol></div><p>The variable values in the message are usually fetched with upvar, here is an example from dotlrn:</p><pre class="programlisting">ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name]
- must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted"
+ tags with keys in the APM.</p></li></ol></div><p>The variable values in the message are usually fetched with upvar, here is an example from dotlrn:</p><pre class="programlisting">ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name]
+ must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted"
</pre><p>was replaced by:</p><pre class="programlisting">set subject [parameter::get -localize -parameter classes_pretty_name]
set class_instances [parameter::get -localize -parameter class_instances_pretty_plural]
ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted]
@@ -233,18 +233,18 @@
find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
# Review the list of tcl files with no message lookups
for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
-</pre><p>When you feel ready you may run the action "Replace tags with keys and insert into catalog" on the tcl files that you've edited to replace the temporary tags with calls to the message lookup procedure.</p><p>The <tt>acs-lang/bin/check-catalog.sh</tt> script checks that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that message lookups in adp and info files are on the format #package_key.message_key#, and that message lookups in tcl files are always done with the underscore procedure. The script assumes that you have perl installed and in your path. Run the script like this:</p><pre class="programlisting">acs-lang/bin/check-catalog.sh <span class="emphasis"><em>package_key</em></span></pre><p>where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks on en_US xml catalog files. </p></li><li><p>
+</pre><p>When you feel ready you may run the action "Replace tags with keys and insert into catalog" on the tcl files that you've edited to replace the temporary tags with calls to the message lookup procedure.</p><p>The <tt class="computeroutput">acs-lang/bin/check-catalog.sh</tt> script checks that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that message lookups in adp and info files are on the format #package_key.message_key#, and that message lookups in tcl files are always done with the underscore procedure. The script assumes that you have perl installed and in your path. Run the script like this:</p><pre class="programlisting">acs-lang/bin/check-catalog.sh <span class="emphasis"><em>package_key</em></span></pre><p>where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks on en_US xml catalog files. </p></li><li><p>
<span class="strong">Replace tags with keys</span>:
This is an automated process, which will replace the
temporary <#...#> notation in both ADP and Tcl files
with the appropriate notation for the type of file, and
store the text in the message catalog. You need to run the
process twice, once for ADP files, and once for Tcl files.
- </p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2942181"></a>Internationalize Package Parameters with visible messages</h4></div></div><p>
+ </p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2884508"></a>Internationalize Package Parameters with visible messages</h4></div></div><div></div></div><p>
See <a href="i18n.html#i18n-message-catalog-params">Multilingual APM Parameters</a>
- </p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2942200"></a>Internationalize Date and Time queries</h4></div></div><div class="orderedlist"><ol type="1"><li><p>Find datetime in .xql files. Use command line tools to find suspect SQL code:</p><pre class="programlisting">grep -r "to_char.*H" *
-grep -r "to_date.*H" *
-</pre></li><li><p>In SQL statements, replace the format string with the ANSI standard format, <tt>YYYY-MM-DD HH24:MI:SS</tt> and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,</p><pre class="programlisting">to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty</pre><p>becomes</p><pre class="programlisting">to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi</pre></li><li><p>In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function <tt><a href="/api-doc/proc-view?proc=lc_time_system_to_conn" target="_top">lc_time_system_to_conn</a></tt>:</p><pre class="programlisting">
-set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]</pre><p>When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with <tt><a href="/api-doc/proc-view?proc=lc%5ftime%5fconn%5fto%5fsystem" target="_top">lc_time_conn_to_system</a></tt>.
-</p></li><li><p>When a datetime field will be displayed, format it using the localizing function <tt><a href="/api-doc/proc-view?proc=lc_time_fmt" target="_top">lc_time_fmt</a></tt>. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: <tt>%x, %X, %q, %Q, and %c.</tt></p><pre class="programlisting">set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]</pre></li></ol></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="i18n-design"></a>Design Notes</h3></div></div><p>User locale is a property of ad_conn, <tt>ad_conn locale</tt>. The request processor sets this by calling <tt>lang::conn::locale</tt>, which looks for the following in order of precedence:</p><div class="orderedlist"><ol type="1"><li><p>Use user preference for this package (stored in ad_locale_user_prefs)</p></li><li><p>Use system preference for the package (stored in apm_packages)</p></li><li><p>Use user's general preference (stored in user_preferences)</p></li><li><p>Use Browser header (<tt>Accept-Language</tt> HTTP header)</p></li><li><p>Use system locale (an APM parameter for acs_lang)</p></li><li><p>default to en_US</p></li></ol></div><p>For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the <tt>_</tt> function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is
+ </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2884527"></a>Internationalize Date and Time queries</h4></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p>Find datetime in .xql files. Use command line tools to find suspect SQL code:</p><pre class="programlisting">grep -r "to_char.*H" *
+grep -r "to_date.*H" *
+</pre></li><li><p>In SQL statements, replace the format string with the ANSI standard format, <tt class="computeroutput">YYYY-MM-DD HH24:MI:SS</tt> and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,</p><pre class="programlisting">to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty</pre><p>becomes</p><pre class="programlisting">to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi</pre></li><li><p>In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function <tt class="computeroutput"><a href="/api-doc/proc-view?proc=lc_time_system_to_conn" target="_top">lc_time_system_to_conn</a></tt>:</p><pre class="programlisting">
+set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]</pre><p>When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with <tt class="computeroutput"><a href="/api-doc/proc-view?proc=lc%5ftime%5fconn%5fto%5fsystem" target="_top">lc_time_conn_to_system</a></tt>.
+</p></li><li><p>When a datetime field will be displayed, format it using the localizing function <tt class="computeroutput"><a href="/api-doc/proc-view?proc=lc_time_fmt" target="_top">lc_time_fmt</a></tt>. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: <tt class="computeroutput">%x, %X, %q, %Q, and %c.</tt></p><pre class="programlisting">set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]</pre></li></ol></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-design"></a>Design Notes</h3></div></div><div></div></div><p>User locale is a property of ad_conn, <tt class="computeroutput">ad_conn locale</tt>. The request processor sets this by calling <tt class="computeroutput">lang::conn::locale</tt>, which looks for the following in order of precedence:</p><div class="orderedlist"><ol type="1"><li><p>Use user preference for this package (stored in ad_locale_user_prefs)</p></li><li><p>Use system preference for the package (stored in apm_packages)</p></li><li><p>Use user's general preference (stored in user_preferences)</p></li><li><p>Use Browser header (<tt class="computeroutput">Accept-Language</tt> HTTP header)</p></li><li><p>Use system locale (an APM parameter for acs_lang)</p></li><li><p>default to en_US</p></li></ol></div><p>For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the <tt class="computeroutput">_</tt> function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is
found, then that locale is offered instead.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Internationalization Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Security Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/i18n.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/index.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.adp,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/index.adp 28 Jun 2003 05:07:01 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/index.adp 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,64 +1,45 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<master>
+<center>
+<table border="0" cellpadding="8" cellspacing="0" width="80%">
-<html>
-<head>
-<title>OpenACS Documentation</title>
-<link rel="stylesheet" type="text/css" href="openacs.css">
-</head>
-
-<body bgcolor="#ffffff">
-<blockquote>
-
-<table>
-<tr><td valign="bottom">
-<a href="http://www.openacs.org/"><img src="images/alex.jpg" align="left" border="0"></a>
-</td>
-<td valign="bottom">
-<h1>The Open Architecture Community System</h1>
-</td></tr>
-</table>
-
-<table border="1" cellpadding="8" cellspacing="0" width="80%">
-
-<tr>
-<td class="codeblock"><strong>Basic OpenACS</strong>
-</td>
-<td class="codeblock"><strong>Package Documentation</strong></td>
-</tr>
-
<tr><td valign="top">
-<pre><strong>Getting Started</strong>
- - <a href="release-notes.html">Release Notes</a>
- - <a href="individual-programs.html">Required Software</a>
- - <a href="unix-install.html">Unix Installation Guide</a>
- - <a href="win2k-installation.html">Windows Installation Guide</a>
- - <a href="mac-installation.html">Mac OS X Installation Guide</a>
- - <a href="upgrade.html">Upgrading</a>
- - <a href="backup-recovery.html">Backup and Recovery</a>
- - <a href="configure.html">Configuring your new OpenACS Service</a>
- - <a href="tutorial.html">Developer Tutorial</a>
- - <a href="/api-doc/">API Browser</a> for this OpenACS instance
+<a href="http://openacs.org/projects/openacs/doc-project">Errata and Corrections</a>
+<p><strong>Getting Started</strong>
+<ul>
+<li><a href="release-notes.html">Release Notes</a>
+<li><a href="individual-programs.html">Required Software</a>
+<li><a href="unix-install.html">Unix Installation Guide</a>,
+(<a href="win2k-installation.html">Windows</a>), (<a href="mac-installation.html">Mac OS X</a>)
+<li><a href="upgrade.html">Upgrading</a>
+<li><a href="backup-recovery.html">Backup and Recovery</a>
+</ul>
-<strong><a href="index.html">Full Table of Contents</a>
-
<strong>Primers and References</strong>
- - <a href="http://openacs.org/faq/">OpenACS FAQs</a>
- - <a href="http://cvs.openacs.org/">OpenACS CVS Browser</a>
- - <a href="http://openacs.org/education/">Learning OpenACS</a>
- - <a href="http://aolserver.com/docs/">AOLserver Documentation</a>
+<ul>
+<li><a href="tutorial.html">Developer Tutorial</a>
+<li><a href="http://openacs.org/faq/">OpenACS FAQs</a>
+<li><a href="http://cvs.openacs.org/">OpenACS CVS Browser</a>
+<li><a href="http://openacs.org/education/">Learning OpenACS</a>
+<li><a href="http://aolserver.com/docs/">AOLserver Documentation</a>
(the <a href="http://aolserver.com/docs/devel/tcl/api/">Tcl Developer's Guide</a> in particular.)
- - <a href="http://philip.greenspun.com/tcl/">Tcl for Web Nerds</a>
- - <a href="http://philip.greenspun.com/sql/">SQL for Web Nerds</a>
+<li><a href="http://philip.greenspun.com/tcl/">Tcl for Web Nerds</a>
+<li><a href="http://philip.greenspun.com/sql/">SQL for Web Nerds</a>
+</ul>
<strong>Documentation Improvement Project</strong>
- - <a href="http://openacs.org/projects/openacs/doc-project/">Help improve OpenACS documentation</a>
+<ul>
+<li><a href="http://openacs.org/projects/openacs/doc-project/">Help improve OpenACS documentation</a>
+</ul>
<strong>Archive</strong>
- - <a href="http://openacs.org/projects/openacs/doc-project/olddocs">Documentation for Earlier Versions of OpenACS</a>
-</pre></td>
+<ul>
+<li><a href="http://openacs.org/projects/openacs/doc-project/olddocs">Documentation for Earlier Versions of OpenACS</a>
+</ul>
+</td>
<td valign="top">
-<pre>
+<a href="index.html">Core Documentation</a>
+<p><a href="/api-doc/">API Browser</a>
<%
# This block of ADP code ensures that the Installer can still serve this
# page even without a working templating system.
@@ -69,55 +50,53 @@
db_foreach get_installed_pkgs "select package_key, pretty_name from apm_package_types order by upper(pretty_name) " {
if { ! $found_p } {
set found_p 1
- adp_puts "<strong>Installed Packages</strong>\n\n"
+ adp_puts "\n<p><strong>Installed Packages</strong>\n<ul>\n"
}
set index_page [lindex [glob -nocomplain \
"[acs_package_root_dir $package_key]/www/doc/index.*"] 0]
if { [file exists $index_page] } {
if {![empty_string_p $pretty_name]} {
- adp_puts "- <a href=\"/doc/$package_key/\">$pretty_name</a>\n"
+ adp_puts "<li><a href=\"/doc/$package_key/\">$pretty_name</a>\n"
} else {
- adp_puts "- <a href=\"/doc/$package_key/\">$package_key</a>\n"
+ adp_puts "<li><a href=\"/doc/$package_key/\">$package_key</a>\n"
}
} else {
if {![empty_string_p $pretty_name]} {
- adp_puts "- $pretty_name\n"
+ adp_puts "<li>$pretty_name\n"
} else {
- adp_puts "- $package_key\n"
+ adp_puts "<li>$package_key\n"
}
}
}
}
if {!$found_p} {
- adp_puts "- No installed packages.\n"
+ adp_puts "<li> No installed packages.\n"
}
+ adp_puts "</ul>"
set packages [core_docs_uninstalled_packages]
if { ! [empty_string_p $packages] } {
- adp_puts "\n<strong>Uninstalled packages</strong>\n\n"
+ adp_puts "\n<p><strong>Uninstalled packages</strong>\n<ul>"
foreach {key name} $packages {
set index_page [lindex [glob -nocomplain \
"[acs_package_root_dir $key]/www/doc/index.*"] 0]
if { [file exists $index_page] } {
- adp_puts "- <a href=\"$key\">$name</a>\n"
+ adp_puts "<li> <a href=\"$key\">$name</a>\n"
} else {
- adp_puts "- $name\n"
+ adp_puts "<li> $name\n"
}
}
+ adp_puts "\n</ul>"
}
%>
-</pre>
</td>
</tr>
</table>
-
-<br><br>
-<span class="force">This software is mostly Copyright 1995-2000 ArsDigita Corporation<br>
-and licensed under the
+<span class="force">This software is licensed under the
<a href="http://www.gnu.org/licenses/gpl.txt">GNU General Public License, version 2 (June 1991)</a></span>
<p class="force">
Questions or comments about the documentation?
@@ -126,5 +105,5 @@
<a href="http://openacs.org/forums/">OpenACS forums</a> or send email to <a href="mailto:docs@openacs.org">docs@openacs.org</a>.
</p>
</blockquote>
-</body>
-</html>
+
+</center>
\ No newline at end of file
Index: openacs-4/packages/acs-core-docs/www/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/index.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/index.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="next" href="for-everyone.html" title="Part�I.�OpenACS For Everyone"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr></table><hr></div><div class="book" lang="en"><div class="titlepage"><div><h1 class="title"><a name="id2809843"></a>OpenACS Documentation</h1></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>I. <a href="for-everyone.html">OpenACS For Everyone</a></dt><dd><dl><dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a></dt><dd><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS Release Notes</a></dt></dl></dd></dl></dd><dt>II. <a href="acs-admin.html">Administrator's Guide</a></dt><dd><dl><dt>2. <a href="quick.html">Quick Install</a></dt><dt>3. <a href="software-versions.html">Prerequisite Software</a></dt><dd><dl><dt><a href="compatibility-matrix.html">Compatibility Matrix</a></dt><dt><a href="individual-programs.html">Individual Programs</a></dt></dl></dd><dt>4. <a href="unix-install.html">Installing on Unix/Linux</a></dt><dd><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="linux-installation.html">Install Linux and supporting software</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostGreSQL</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3oacs1</a></dt><dt><a href="openacs.html">Install OpenACS 5.0.0d</a></dt><dt><a href="credits.html">Credits</a></dt></dl></dd><dt>5. <a href="win-install.html">Installing on Windows</a></dt><dd><dl><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></dd><dt>6. <a href="mac-install.html">Installing on a Macintosh</a></dt><dd><dl><dt><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></dt></dl></dd><dt>7. <a href="configure.html">Configuring a New Service</a></dt><dt>8. <a href="upgrade.html">Upgrading</a></dt><dd><dl><dt><a href="upgrade-detail.html">Support for upgrades.</a></dt></dl></dd><dt>9. <a href="maintenance.html">Maintenance</a></dt><dd><dl><dt><a href="maintenance-web.html">Hosting Web Sites</a></dt><dt><a href="database-management.html">Database Management</a></dt><dt><a href="backup-recovery.html">Backup and Recovery</a></dt></dl></dd><dt>A. <a href="install-redhat.html">Install Red Hat 8.0</a></dt><dt>B. <a href="install-more-software.html">Install additional supporting software</a></dt><dd><dl><dt><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></dt><dt><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt><dt><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt><dt><a href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt><a href="analog-install.html">Install Analog web file analyzer</a></dt><dt><a href="install-full-text-search.html"></a></dt><dt><a href="install-nsopenssl.html">Install nsopenssl</a></dt></dl></dd></dl></dd><dt>III. <a href="acs-package-dev.html">For OpenACS Package Developers</a></dt><dd><dl><dt>10. <a href="tutorial.html">Development Tutorial</a></dt><dd><dl><dt><a href="tutorial-newpackage.html">Creating a Package</a></dt><dt><a href="tutorial-database.html">Setting Up Database Objects</a></dt><dt><a href="tutorial-pages.html">Creating Web Pages</a></dt><dt><a href="tutorial-debug.html">Debugging and Automated Testing</a></dt><dt><a href="tutorial-advanced.html">Advanced Topics</a></dt></dl></dd><dt>11. <a href="dev-guide.html">Development Reference</a></dt><dd><dl><dt><a href="packages.html">OpenACS 5.0.0d Packages</a></dt><dt><a href="objects.html">OpenACS Data Models and the Object System</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 5.0.0d</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 5.0.0d Application Pages</a></dt><dt><a href="parties.html">Parties in OpenACS 5.0.0d</a></dt><dt><a href="permissions-tediously-explained.html">OpenACS 4.x Permissions Tediously Explained</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></dd><dt>12. <a href="eng-standards.html">Engineering Standards</a></dt><dd><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></dd><dt>C. <a href="cvs-tips.html">Using CVS with an OpenACS Site</a></dt><dd><dl><dt><a href="cvs-service-import.html">Add the Service to CVS - OPTIONAL</a></dt></dl></dd></dl></dd><dt>IV. <a href="acs-plat-dev.html">For OpenACS Platform Developers</a></dt><dd><dl><dt>13. <a href="kernel-doc.html">Kernel Documentation</a></dt><dd><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 5.0.0d Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 5.0.0d Package Manager Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></dt><dt><a href="i18n.html">Internationalization</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt><dt><a href="ext-auth-requirements.html">External Authentication Requirements</a></dt></dl></dd></dl></dd></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>3.1. <a href="compatibility-matrix.html#id2953962">Compatibility Matrix</a></dt><dt>4.1. <a href="linux-installation.html#id2954649">Assumptions in this section</a></dt><dt>8.1. <a href="upgrade-detail.html#id2873680">Assumptions in this section</a></dt><dt>10.1. <a href="tutorial-newpackage.html#id2948533">Assumptions in this section</a></dt><dt>10.2. <a href="tutorial-database.html#id2948352">Database Creation Script - master create file</a></dt><dt>10.3. <a href="tutorial-database.html#id2948399">Database Creation Script - table</a></dt><dt>10.4. <a href="tutorial-database.html#id2873380">Database Creation Script - functions</a></dt><dt>10.5. <a href="tutorial-database.html#id2873486">Database deletion script</a></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>11.1. <a href="permissions-tediously-explained.html#id2955192"></a></dt><dt>11.2. <a href="permissions-tediously-explained.html#id2900800"></a></dt><dt>11.3. <a href="permissions-tediously-explained.html#id2898303"></a></dt><dt>11.4. <a href="permissions-tediously-explained.html#id2898462"></a></dt><dt>11.5. <a href="permissions-tediously-explained.html#id2898586"></a></dt><dt>11.6. <a href="permissions-tediously-explained.html#id2904529"></a></dt><dt>11.7. <a href="permissions-tediously-explained.html#id2904803"></a></dt><dt>11.8. <a href="permissions-tediously-explained.html#id2904988"></a></dt><dt>11.9. <a href="permissions-tediously-explained.html#id2905350"></a></dt><dt>11.10. <a href="permissions-tediously-explained.html#id2905776"></a></dt><dt>11.11. <a href="permissions-tediously-explained.html#id2906016"></a></dt><dt>11.12. <a href="permissions-tediously-explained.html#id2906731"></a></dt><dt>13.1. <a href="i18n.html#id2891017"></a></dt><dt>13.2. <a href="i18n.html#id2891104"></a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> Part�I.�OpenACS For Everyone</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/index.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="next" href="for-everyone.html" title="Part�I.�OpenACS For Everyone"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr></table><hr></div><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id2760361"></a>OpenACS Documentation</h1></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>I. <a href="for-everyone.html">OpenACS For Everyone</a></dt><dd><dl><dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a></dt><dd><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS Release Notes</a></dt></dl></dd></dl></dd><dt>II. <a href="acs-admin.html">Administrator's Guide</a></dt><dd><dl><dt>2. <a href="quick.html">Quick Install</a></dt><dt>3. <a href="software-versions.html">Prerequisite Software</a></dt><dd><dl><dt><a href="compatibility-matrix.html">Compatibility Matrix</a></dt><dt><a href="individual-programs.html">Individual Programs</a></dt></dl></dd><dt>4. <a href="unix-install.html">Installing on Unix/Linux</a></dt><dd><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="linux-installation.html">Install Linux and supporting software</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostGreSQL</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3oacs1</a></dt><dt><a href="openacs.html">Install OpenACS 5.0.0a1</a></dt><dt><a href="credits.html">Credits</a></dt></dl></dd><dt>5. <a href="win-install.html">Installing on Windows</a></dt><dd><dl><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></dd><dt>6. <a href="mac-install.html">Installing on a Macintosh</a></dt><dd><dl><dt><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></dt></dl></dd><dt>7. <a href="configure.html">Configuring a New Service</a></dt><dt>8. <a href="upgrade.html">Upgrading</a></dt><dd><dl><dt><a href="upgrade-detail.html">Support for upgrades.</a></dt></dl></dd><dt>9. <a href="maintenance.html">Maintenance</a></dt><dd><dl><dt><a href="maintenance-web.html">Hosting Web Sites</a></dt><dt><a href="database-management.html">Database Management</a></dt><dt><a href="backup-recovery.html">Backup and Recovery</a></dt></dl></dd><dt>A. <a href="install-redhat.html">Install Red Hat 8.0</a></dt><dt>B. <a href="install-more-software.html">Install additional supporting software</a></dt><dd><dl><dt><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></dt><dt><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt><dt><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt><dt><a href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt><a href="analog-install.html">Install Analog web file analyzer</a></dt><dt><a href="install-nspam.html">Install nspam</a></dt><dt><a href="install-full-text-search.html">Install Full Text Search</a></dt><dt><a href="install-nsopenssl.html">Install nsopenssl</a></dt></dl></dd></dl></dd><dt>III. <a href="acs-package-dev.html">For OpenACS Package Developers</a></dt><dd><dl><dt>10. <a href="tutorial.html">Development Tutorial</a></dt><dd><dl><dt><a href="tutorial-newpackage.html">Creating a Package</a></dt><dt><a href="tutorial-database.html">Setting Up Database Objects</a></dt><dt><a href="tutorial-pages.html">Creating Web Pages</a></dt><dt><a href="tutorial-debug.html">Debugging and Automated Testing</a></dt><dt><a href="tutorial-advanced.html">Advanced Topics</a></dt></dl></dd><dt>11. <a href="dev-guide.html">Development Reference</a></dt><dd><dl><dt><a href="packages.html">OpenACS 5.0.0a1 Packages</a></dt><dt><a href="objects.html">OpenACS Data Models and the Object System</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 5.0.0a1</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 5.0.0a1 Application Pages</a></dt><dt><a href="parties.html">Parties in OpenACS 5.0.0a1</a></dt><dt><a href="permissions-tediously-explained.html">OpenACS 4.x Permissions Tediously Explained</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></dd><dt>12. <a href="eng-standards.html">Engineering Standards</a></dt><dd><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></dd><dt>A. <a href="cvs-tips.html">Using CVS with an OpenACS Site</a></dt><dd><dl><dt><a href="cvs-service-import.html">Add the Service to CVS - OPTIONAL</a></dt></dl></dd></dl></dd><dt>IV. <a href="acs-plat-dev.html">For OpenACS Platform Developers</a></dt><dd><dl><dt>13. <a href="kernel-doc.html">Kernel Documentation</a></dt><dd><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 5.0.0a1 Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 5.0.0a1 Package Manager Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></dt><dt><a href="i18n.html">Internationalization</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt><dt><a href="ext-auth-requirements.html">External Authentication Requirements</a></dt></dl></dd></dl></dd></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>3.1. <a href="compatibility-matrix.html#id2815303">Compatibility Matrix</a></dt><dt>4.1. <a href="linux-installation.html#id2815685">Assumptions in this section</a></dt><dt>8.1. <a href="upgrade-detail.html#id2828962">Assumptions in this section</a></dt><dt>10.1. <a href="tutorial-newpackage.html#id2825824">Assumptions in this section</a></dt><dt>10.2. <a href="tutorial-database.html#id2838584">Database Creation Script - master create file</a></dt><dt>10.3. <a href="tutorial-database.html#id2827935">Database Creation Script - table</a></dt><dt>10.4. <a href="tutorial-database.html#id2838534">Database Creation Script - functions</a></dt><dt>10.5. <a href="tutorial-database.html#id2835266">Database deletion script</a></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>11.1. <a href="permissions-tediously-explained.html#id2849194"></a></dt><dt>11.2. <a href="permissions-tediously-explained.html#id2850069"></a></dt><dt>11.3. <a href="permissions-tediously-explained.html#id2850269"></a></dt><dt>11.4. <a href="permissions-tediously-explained.html#id2850426"></a></dt><dt>11.5. <a href="permissions-tediously-explained.html#id2850550"></a></dt><dt>11.6. <a href="permissions-tediously-explained.html#id2853662"></a></dt><dt>11.7. <a href="permissions-tediously-explained.html#id2853885"></a></dt><dt>11.8. <a href="permissions-tediously-explained.html#id2854071"></a></dt><dt>11.9. <a href="permissions-tediously-explained.html#id2855166"></a></dt><dt>11.10. <a href="permissions-tediously-explained.html#id2855544"></a></dt><dt>11.11. <a href="permissions-tediously-explained.html#id2855764"></a></dt><dt>11.12. <a href="permissions-tediously-explained.html#id2856401"></a></dt><dt>13.1. <a href="i18n.html#id2883687"></a></dt><dt>13.2. <a href="i18n.html#id2883357"></a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> Part�I.�OpenACS For Everyone</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/index.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/individual-programs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/individual-programs.html 8 Oct 2003 12:01:23 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/individual-programs.html 14 Oct 2003 11:02:58 -0000 1.7
@@ -1,4 +1,4 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Individual Programs</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="previous" href="compatibility-matrix.html" title="Compatibility Matrix"><link rel="next" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="compatibility-matrix.html">Prev</a> </td><th width="60%" align="center">Chapter�3.�Prerequisite Software</th><td width="20%" align="right"> <a accesskey="n" href="unix-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="individual-programs"></a>Individual Programs</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><a name="openacs-download"></a><p><b><a href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 5.0.0d</a>.�</b>The OpenACS tarball comprises the core packages and
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Individual Programs</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="previous" href="compatibility-matrix.html" title="Compatibility Matrix"><link rel="next" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="compatibility-matrix.html">Prev</a> </td><th width="60%" align="center">Chapter�3.�Prerequisite Software</th><td width="20%" align="right"> <a accesskey="n" href="unix-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="individual-programs"></a>Individual Programs</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><a name="openacs-download"></a><p><b><a href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 5.0.0a1</a>.�</b>The OpenACS tarball comprises the core packages and
many useful additional packages. This includes a full set
of documentation. The tarball works with both PostGreSQL
and Oracle.</p></li><li><p><b>Operating System.�</b>OpenACS is designed for a Unix-like system. It is
@@ -30,7 +30,7 @@
distributions. </p></li><li><p><b>TCL 8.3 development headers and libraries, OPTIONAL.�</b> The site-wide-search service, OpenFTS, requires these to
compile. (Debian users: <tt class="computeroutput">apt-get install
tcl8.3-dev</tt>). You need this
- to install OpenFTS.</p></li></ul></div></li><li><a name="source-tdom"></a><p><b>tDOM, REQUIRED.�</b>OpenACS 5.0.0d stores
+ to install OpenFTS.</p></li></ul></div></li><li><a name="source-tdom"></a><p><b>tDOM, REQUIRED.�</b>OpenACS 5.0.0a1 stores
queries in XML files, so we use an AOLserver module called
tDOM to parse these files. (This replaces libxml2, which
was used prior to 4.6.4.) tDOM is available from <a href="http://tdom.org" target="_top">http://tdom.org</a>).</p></li><li><p><b>Web Server.�</b>The web server handles incoming HTTP requests, provides
@@ -40,7 +40,7 @@
running Apache with mod_nsd - see <a href="http://openacs.org/forums/message-view?message_id=21461" target="_top">this
post.</a></p><div class="itemizedlist"><ul type="circle"><li><a name="source-aolserver"></a><p><b><a href="http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz" target="_top">AOLserver 3.3oacs1</a>, REQUIRED.�</b>Mat Kovach's source distribution of AOLserver, including all of the patches listed below.</p><p>
Mat Kovach is graciously maintaining an AOLserver distribution that
- includes all the patches and modules needed to run OpenACS 5.0.0d. These
+ includes all the patches and modules needed to run OpenACS 5.0.0a1. These
instructions will describe how to install using his source
distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and
perhaps more to come), currently located at <a href="http://uptime.openacs.org/aolserver-openacs/" target="_top">uptime.openacs.org</a>.
@@ -77,7 +77,8 @@
0.1</a>, OPTIONAL.�</b>Provides PAM capabilities for AOLserver. You
need this if you want OpenACS users to authenticate
through a PAM module (such as RADIUS). (<a href="http://braindamage.alal.com/software/nspam.html" target="_top">home
- page</a>)</p></li><li><a name="nsldap-download"></a><p><b><a href="http://sourceforge.net/project/showfiles.php?group_id=3152" target="_top">ns_ldap 0.r8
+ page</a>)</p></li><li><a name="pam-radius-download"></a><p><b><a href="ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar" target="_top">pam_radius 1.3.16</a>, OPTIONAL.�</b>Provides RADIUS capabilities for PAM. You need
+ this if you want to use RADIUS authentication via PAM in OpenACS.</p></li><li><a name="nsldap-download"></a><p><b><a href="http://sourceforge.net/project/showfiles.php?group_id=3152" target="_top">ns_ldap 0.r8
</a>, OPTIONAL.�</b>Provides LDAP capabilities for AOLserver. You need
this if you want to use LDAP authentication in OpenACS.</p></li><li><a name="openfts-download"></a><p><b><a href="http://unc.dl.sourceforge.net/sourceforge/openfts/Search-OpenFTS-tcl-0.3.2.tar.gz" target="_top">OpenFTS TCL 0.3.2</a>, OPTIONAL.�</b>Adds full-text-search to PostGreSQL and includes a
driver for AOLserver. You need this if you want users
Index: openacs-4/packages/acs-core-docs/www/install-cvs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/install-cvs.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/install-cvs.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,7 +1,6 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Initialize CVS (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="openacs-unpack.html" title="Unpack the OpenACS tarball"><link rel="next" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-cvs"></a>Initialize CVS (OPTIONAL)</h2></div></div><a class="indexterm" name="id2991982"></a><p>CVS is a source control system. Create and initialize a
- directory for a local cvs repository.</p><pre class="screen">[root@yourserver tmp]# <b><tt>mkdir /cvsroot</tt></b>
-[root@yourserver tmp]#<b><tt> cvs -d /cvsroot init</tt></b>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Initialize CVS (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="openacs-unpack.html" title="Unpack the OpenACS tarball"><link rel="next" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-cvs"></a>Initialize CVS (OPTIONAL)</h2></div></div><div></div></div><a class="indexterm" name="id2839018"></a><p>CVS is a source control system. Create and initialize a
+ directory for a local cvs repository.</p><pre class="screen">[root@yourserver tmp]# <b class="userinput"><tt>mkdir /cvsroot</tt></b>
+[root@yourserver tmp]#<b class="userinput"><tt> cvs -d /cvsroot init</tt></b>
[root@yourserver tmp]#
-<pre class="action">mkdir /cvsroot
-cvs -d /cvsroot init</pre></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr><tr><td width="40%" align="left">Unpack the OpenACS tarball </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Add PSGML commands to emacs init file (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-cvs.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<pre class="action"><span class="action">mkdir /cvsroot
+cvs -d /cvsroot init</span></pre></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr><tr><td width="40%" align="left">Unpack the OpenACS tarball </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Add PSGML commands to emacs init file (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-cvs.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/install-daemontools.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,37 +1,36 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Daemontools (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"><link rel="next" href="install-qmail.html" title="Install qmail (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-daemontools"></a>Install Daemontools (OPTIONAL)</h2></div></div><p>Daemontools is a collection of programs for controlling
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Daemontools (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"><link rel="next" href="install-qmail.html" title="Install qmail (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-daemontools"></a>Install Daemontools (OPTIONAL)</h2></div></div><div></div></div><p>Daemontools is a collection of programs for controlling
other processes. We use daemontools to run and monitor AOLServer. It is
installed in /package. These commands install daemontools and
svgroup. svgroup is a script for granting permissions, to allow
users other than root to use daemontools for specific
- services.</p><div class="orderedlist"><ol type="1"><li><p>Install Daemontools</p><a class="indexterm" name="id2937421"></a><div class="itemizedlist"><ul type="disc"><li><p>Red Hat</p><p>Make sure you have the source tarball in
- <tt>/tmp</tt>, or <a href="individual-programs.html#daemontools-download">download it</a>. (The -p
+ services.</p><div class="orderedlist"><ol type="1"><li><p>Install Daemontools</p><a class="indexterm" name="id2836868"></a><div class="itemizedlist"><ul type="disc"><li><p>Red Hat</p><p>Make sure you have the source tarball in
+ <tt class="computeroutput">/tmp</tt>, or <a href="individual-programs.html#daemontools-download">download it</a>. (The -p
flag in mkdir causes all implied directories in the path
to be made as well.)</p><p>(Red Hat 9.0: put
-</p><pre class="programlisting">#include <errno.h></pre><p> as the first line of <tt>/package/admin/daemontools-0.76/src/error.h</tt>. <a href="http://www.riverside.org/archive/html/djbdns/2003-01/msg00307.html" target="_top">More information</a>)</p><pre class="screen">[root@yourserver root]# <b><tt>mkdir -p /package</tt></b>
-[root@yourserver root]# <b><tt>chmod 1755 /package/</tt></b>
-[root@yourserver root]# <b><tt>cd /package/</tt></b>
-[root@yourserver package]# <b><tt>tar xzf /tmp/daemontools-0.76.tar.gz</tt></b>
-[root@yourserver package]# <b><tt>cd admin/daemontools-0.76/</tt></b>
-[root@yourserver daemontools-0.76]# <b><tt>package/install</tt></b>
+</p><pre class="programlisting">#include <errno.h></pre><p> as the first line of <tt class="computeroutput">/package/admin/daemontools-0.76/src/error.h</tt>. <a href="http://www.riverside.org/archive/html/djbdns/2003-01/msg00307.html" target="_top">More information</a>)</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>mkdir -p /package</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 1755 /package/</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cd /package/</tt></b>
+[root@yourserver package]# <b class="userinput"><tt>tar xzf /tmp/daemontools-0.76.tar.gz</tt></b>
+[root@yourserver package]# <b class="userinput"><tt>cd admin/daemontools-0.76/</tt></b>
+[root@yourserver daemontools-0.76]# <b class="userinput"><tt>package/install</tt></b>
Linking ./src/* into ./compile...
(many lines omitted)
Creating /service...
Adding svscanboot to inittab...
init should start svscan now.
[root@yourserver root]#
-<pre class="action">mkdir -p /package
+<pre class="action"><span class="action">mkdir -p /package
chmod 1755 /package
cd /package
tar xzf /tmp/daemontools-0.76.tar.gz
cd admin/daemontools-0.76
-package/install</pre></pre></li><li><p>Debian</p><pre class="screen">root:~# <b><tt>apt-get install daemontools-installer</tt></b>
-root:~# <b><tt>build-daemontools</tt></b></pre></li></ul></div></li><li><p>Verify that svscan is running. If it is, you should see
- these two processes running:</p><pre class="screen">[root@yourserver root]# <b><tt>ps -auxw | grep service</tt></b>
+package/install</span></pre></pre></li><li><p>Debian</p><pre class="screen">root:~# <b class="userinput"><tt>apt-get install daemontools-installer</tt></b>
+root:~# <b class="userinput"><tt>build-daemontools</tt></b></pre></li></ul></div></li><li><p>Verify that svscan is running. If it is, you should see
+ these two processes running:</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>ps -auxw | grep service</tt></b>
root 13294 0.0 0.1 1352 272 ? S 09:51 0:00 svscan /service
root 13295 0.0 0.0 1304 208 ? S 09:51 0:00 readproctitle service errors: .......................................
[root@yourserver root]#</pre></li><li><p>Install a script to grant non-root users permission to
- control daemontools services.</p><pre class="screen">[root@yourserver root]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /usr/local/bin/svgroup</tt></b>
-<pre class="action">cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup
-chmod 755 /usr/local/bin/svgroup</pre></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr><tr><td width="40%" align="left">Add PSGML commands to emacs init file (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install qmail (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-daemontools.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ control daemontools services.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /usr/local/bin/svgroup</tt></b>
+<pre class="action"><span class="action">cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup
+chmod 755 /usr/local/bin/svgroup</span></pre></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr><tr><td width="40%" align="left">Add PSGML commands to emacs init file (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install qmail (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-daemontools.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/install-full-text-search.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/install-full-text-search.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,117 +1,116 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title></title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="analog-install.html" title="Install Analog web file analyzer"><link rel="next" href="install-nsopenssl.html" title="Install nsopenssl"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="analog-install.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-nsopenssl.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-full-text-search"></a></h2></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openfts"></a>Install OpenFTS module</h3></div></div><a class="indexterm" name="id2928910"></a><p>If you want full text search, and you are running PostGreSQL, install this module to support FTS. Do this step after you have installed both PostGreSQL and
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Full Text Search</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="ext-auth-ldap-install.html" title="Installing LDAP support"><link rel="next" href="install-nsopenssl.html" title="Install nsopenssl"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="ext-auth-ldap-install.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-nsopenssl.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-full-text-search"></a>Install Full Text Search</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openfts"></a>Install OpenFTS module</h3></div></div><div></div></div><a class="indexterm" name="id2839472"></a><p>If you want full text search, and you are running PostGreSQL, install this module to support FTS. Do this step after you have installed both PostGreSQL and
Aolserver. You will need the <a href="individual-programs.html#openfts-download">openfts
- tarball</a> in <tt>/tmp</tt>.</p><div class="orderedlist"><ol type="1"><li><p>Install Tsearch. This is a PostGreSQL module that
- OpenFTS requires.</p><pre class="screen">[root@yourserver root]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>cd /usr/local/src/postgresql-7.2.4/contrib/tsearch/</tt></b>
-[postgres@yourserver tsearch]$ <b><tt>make</tt></b>
+ tarball</a> in <tt class="computeroutput">/tmp</tt>.</p><div class="orderedlist"><ol type="1"><li><p>Install Tsearch. This is a PostGreSQL module that
+ OpenFTS requires.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - postgres</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>cd /usr/local/src/postgresql-7.2.4/contrib/tsearch/</tt></b>
+[postgres@yourserver tsearch]$ <b class="userinput"><tt>make</tt></b>
sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql
/usr/bin/flex -8 -Ptsearch_yy -o'parser.c' parser.l
(many lines omitted)
rm -f libtsearch.so
ln -s libtsearch.so.0.0 libtsearch.so
-[postgres@yourserver tsearch]$ <b><tt>make install</tt></b>
+[postgres@yourserver tsearch]$ <b class="userinput"><tt>make install</tt></b>
mkdir /usr/local/pgsql/share/contrib
mkdir /usr/local/pgsql/doc/contrib
(2 lines omitted)
/bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so
-[postgres@yourserver tsearch]$ <b><tt>exit</tt></b>
+[postgres@yourserver tsearch]$ <b class="userinput"><tt>exit</tt></b>
logout
[root@yourserver root]#
-<pre class="action">su - postgres
+<pre class="action"><span class="action">su - postgres
cd /usr/local/src/postgresql-7.2.4/contrib/tsearch
make
make install
-exit</pre></pre></li><li><p>Unpack the OpenFTS tarball and compile and install
- the driver.</p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz</tt></b>
-[root@yourserver src]# <b><tt>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/</tt></b>
-[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b><tt>./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/</tt></b>
+exit</span></pre></pre></li><li><p>Unpack the OpenFTS tarball and compile and install
+ the driver.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/</tt></b>
+[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b class="userinput"><tt>./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/</tt></b>
checking prefix... /usr/local
checking for gcc... gcc
<span class="emphasis"><em>(many lines omitted)</em></span>
configure: creating ./config.status
config.status: creating Makefile.global
-[root@yourserver Search-OpenFTS-tcl-0.3.2]#<b><tt> make</tt></b>
+[root@yourserver Search-OpenFTS-tcl-0.3.2]#<b class="userinput"><tt> make</tt></b>
(cd parser; make all)
make[1]: Entering directory `/usr/local/src/Search-OpenFTS-tcl-0.3.2/parser'
<span class="emphasis"><em>(many lines omitted)</em></span>
packages provided were {Lingua::Stem::Snowball 0.3.2}
processed fts_base_snowball.tcl
-[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b><tt>cd aolserver</tt></b>
-[root@yourserver aolserver]# <b><tt>make</tt></b>
-gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR
+[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b class="userinput"><tt>cd aolserver</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>make</tt></b>
+gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR
<span class="emphasis"><em>(many lines omitted)</em></span>
n_stem.o italian_stem.o norwegian_stem.o portuguese_stem.o russian_stem.o nsfts.o -o nsfts.so
-[root@yourserver aolserver]# <b><tt>cp nsfts.so /usr/local/aolserver/bin/</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>cp nsfts.so /usr/local/aolserver/bin/</tt></b>
[root@yourserver aolserver]#
-<pre class="action">cd /usr/local/src
+<pre class="action"><span class="action">cd /usr/local/src
tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/
./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/
make
cd aolserver
make
cp nsfts.so /usr/local/aolserver/bin
-</pre></pre></li><li><p>Build some supplemental modules.</p><pre class="screen">[root@yourserver aolserver]# <b><tt>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2</tt></b>
-[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b><tt>cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.4/contrib</tt></b>
-[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b><tt>cd /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts</tt></b>
-[root@yourserver pgsql_contrib_openfts]#<b><tt> make</tt></b>
+</span></pre></pre></li><li><p>Build some supplemental modules.</p><pre class="screen">[root@yourserver aolserver]# <b class="userinput"><tt>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2</tt></b>
+[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b class="userinput"><tt>cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.4/contrib</tt></b>
+[root@yourserver Search-OpenFTS-tcl-0.3.2]# <b class="userinput"><tt>cd /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts</tt></b>
+[root@yourserver pgsql_contrib_openfts]#<b class="userinput"><tt> make</tt></b>
sed 's,MODULE_PATHNAME,$libdir/openfts,g' openfts.sql.in >openfts.sql
gcc -O2 -Wall -Wmissing-prototypes -Wmissing-declarations -fpic -I. -I../../src/include -c -o openfts.o openfts.c
gcc -shared -o openfts.so openfts.o
rm openfts.o
-[root@yourserver pgsql_contrib_openfts]# <b><tt>su postgres</tt></b>
-[postgres@yourserver pgsql_contrib_openfts]$ <b><tt>make install</tt></b>
+[root@yourserver pgsql_contrib_openfts]# <b class="userinput"><tt>su postgres</tt></b>
+[postgres@yourserver pgsql_contrib_openfts]$ <b class="userinput"><tt>make install</tt></b>
/bin/sh ../../config/install-sh -c -m 644 openfts.sql /usr/local/pgsql/share/contrib
/bin/sh ../../config/install-sh -c -m 755 openfts.so /usr/local/pgsql/lib
/bin/sh ../../config/install-sh -c -m 644 ./README.openfts /usr/local/pgsql/doc/contrib
-[postgres@yourserver pgsql_contrib_openfts]$<b><tt> exit</tt></b>
+[postgres@yourserver pgsql_contrib_openfts]$<b class="userinput"><tt> exit</tt></b>
[root@yourserver pgsql_contrib_openfts]#
-<pre class="action">cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
+<pre class="action"><span class="action">cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.4/contrib
cd /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts
make
su postgres
make install
-exit</pre></pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openfts-postgres"></a>Install OpenFTS prerequisites in PostGreSQL instance</h3></div></div><a class="indexterm" name="id2929244"></a><p>If you are installing Full Text Search, add required
+exit</span></pre></pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openfts-postgres"></a>Install OpenFTS prerequisites in PostGreSQL instance</h3></div></div><div></div></div><a class="indexterm" name="id2839725"></a><p>If you are installing Full Text Search, add required
packages to the new database. (In order for full text search
to work, you must also <a href="install-full-text-search.html#install-openfts" title="Install OpenFTS module">install</a> the PostGreSQL
- OpenFTS module and prerequisites.)</p><pre class="screen">[service0@yourserver service0]$ <b><tt>/usr/local/pgsql/bin/psql <span class="replaceable">service0</span> -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql</tt></b>
+ OpenFTS module and prerequisites.)</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>/usr/local/pgsql/bin/psql <span class="replaceable"><span class="replaceable">service0</span></span> -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql</tt></b>
BEGIN
CREATE
<span class="emphasis"><em>(many lines omitted)</em></span>
INSERT 0 1
COMMIT
-[service0@yourserver service0]$ <b><tt>/usr/local/pgsql/bin/psql <span class="replaceable">service0</span> -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql</tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>/usr/local/pgsql/bin/psql <span class="replaceable"><span class="replaceable">service0</span></span> -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql</tt></b>
CREATE
CREATE
[service0@yourserver service0]$
-<pre class="action">/usr/local/pgsql/bin/psql <span class="replaceable">service0</span> -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql
-/usr/local/pgsql/bin/psql <span class="replaceable">service0</span> -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql</pre></pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="enable-openfts"></a>Enable OpenFTS in config.tcl</h3></div></div><p>If you have <a href="install-full-text-search.html#install-openfts" title="Install OpenFTS module">installed OpenFTS</a>, you can enable it for this service. Uncomment this line from <tt>config.tcl</tt>. (To uncomment a line in a tcl file, remove the <tt>#</tt> at the beginning of the line.)</p><pre class="programlisting">#ns_param nsfts ${bindir}/nsfts.so</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-fts-engine"></a>Install Full Text Search Engine</h3></div></div><div class="orderedlist"><ol type="1"><li><p>Click <tt><span class="guilabel">Package Manager</span></tt> on the right side of the default home page. If prompted, log in with the account and password you entered during install.</p></li><li><p>Click on the <tt><span class="guilabel">Install
-packages</span></tt> link.</p></li><li><p>On the next screen, after it loads, click on <tt><span class="guilabel">Uncheck all boxes</span></tt>, then click the checkbox next to <tt><span class="guilabel">OpenFTS Driver 4.2</span></tt>. Then click <tt><span class="guibutton"><u>N</u>ext</span></tt>. </p></li><li><p>Click <tt><span class="guibutton">Install Packages</span></tt></p></li><li><p>Restart the service.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>svc -t /service/<span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$</pre></li><li><p>Wait a minute, then browse back to the home page.</p></li><li><p>Click on <tt><span class="guilabel">Site Map</span></tt> on the top right side of the screen.</p></li><li><p>Mount the OpenFTS Full Text Search Engine in the site map.</p><div class="orderedlist"><ol type="a"><li><p>Click the <tt><span class="guilabel">new sub folder</span></tt> link on the "/" line, the first line under Main Site:/.</p></li><li><p>Type <b><tt>openfts</tt></b>
-and click <tt><span class="guibutton">New</span></tt>.</p></li><li><p>On the new <tt><span class="guilabel">openfts</span></tt> line, click the <tt><span class="guilabel">mount</span></tt> link.</p></li><li><p>Click <tt><span class="guilabel">OpenFTS
-Driver</span></tt>.</p></li><li><p>On the <tt><span class="guilabel">openfts</span></tt> line, click <tt><span class="guilabel">set parameters</span></tt>.</p></li><li><p>Change <tt><span class="guilabel">openfts_tcl_src_path</span></tt> to <b><tt>/usr/local/src/Search-OpenFTS-tcl-0.3.2/</tt></b> and click <tt><span class="guibutton">Set Parameters</span></tt>
+<pre class="action"><span class="action">/usr/local/pgsql/bin/psql <span class="replaceable"><span class="replaceable">service0</span></span> -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql
+/usr/local/pgsql/bin/psql <span class="replaceable"><span class="replaceable">service0</span></span> -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql</span></pre></pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="enable-openfts"></a>Enable OpenFTS in config.tcl</h3></div></div><div></div></div><p>If you have <a href="install-full-text-search.html#install-openfts" title="Install OpenFTS module">installed OpenFTS</a>, you can enable it for this service. Uncomment this line from <tt class="computeroutput">config.tcl</tt>. (To uncomment a line in a tcl file, remove the <tt class="computeroutput">#</tt> at the beginning of the line.)</p><pre class="programlisting">#ns_param nsfts ${bindir}/nsfts.so</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-fts-engine"></a>Install Full Text Search Engine</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p>Click <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Package Manager</span></span></tt> on the right side of the default home page. If prompted, log in with the account and password you entered during install.</p></li><li><p>Click on the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Install
+packages</span></span></tt> link.</p></li><li><p>On the next screen, after it loads, click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Uncheck all boxes</span></span></tt>, then click the checkbox next to <tt class="computeroutput"><span class="guilabel"><span class="guilabel">OpenFTS Driver 4.2</span></span></tt>. Then click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>. </p></li><li><p>Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Install Packages</span></span></tt></p></li><li><p>Restart the service.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>svc -t /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$</pre></li><li><p>Wait a minute, then browse back to the home page.</p></li><li><p>Click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Site Map</span></span></tt> on the top right side of the screen.</p></li><li><p>Mount the OpenFTS Full Text Search Engine in the site map.</p><div class="orderedlist"><ol type="a"><li><p>Click the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">new sub folder</span></span></tt> link on the "/" line, the first line under Main Site:/.</p></li><li><p>Type <b class="userinput"><tt>openfts</tt></b>
+and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></tt>.</p></li><li><p>On the new <tt class="computeroutput"><span class="guilabel"><span class="guilabel">openfts</span></span></tt> line, click the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">mount</span></span></tt> link.</p></li><li><p>Click <tt class="computeroutput"><span class="guilabel"><span class="guilabel">OpenFTS
+Driver</span></span></tt>.</p></li><li><p>On the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">openfts</span></span></tt> line, click <tt class="computeroutput"><span class="guilabel"><span class="guilabel">set parameters</span></span></tt>.</p></li><li><p>Change <tt class="computeroutput"><span class="guilabel"><span class="guilabel">openfts_tcl_src_path</span></span></tt> to <b class="userinput"><tt>/usr/local/src/Search-OpenFTS-tcl-0.3.2/</tt></b> and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Set Parameters</span></span></tt>
</p></li></ol></div></li><li><p>Mount the Search interface in the site map.</p><div class="orderedlist"><ol type="a"><li><p>Click the
-<tt><span class="guilabel">new sub folder</span></tt> link on the
-Main Site line. </p></li><li><p>Type <b><tt>search</tt></b>
-and click <tt><span class="guibutton">New</span></tt>. </p></li><li><p>Click the <tt><span class="guilabel">new
-application</span></tt> link on the <tt><span class="guilabel">search</span></tt>
- line. </p></li><li><p>Type <b><tt>search</tt></b>
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">new sub folder</span></span></tt> link on the
+Main Site line. </p></li><li><p>Type <b class="userinput"><tt>search</tt></b>
+and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></tt>. </p></li><li><p>Click the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">new
+application</span></span></tt> link on the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">search</span></span></tt>
+ line. </p></li><li><p>Type <b class="userinput"><tt>search</tt></b>
where it says
-<tt><span class="guilabel">untitled</span></tt>, choose
-<tt><span class="guilabel">search</span></tt> from the
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">untitled</span></span></tt>, choose
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">search</span></span></tt> from the
drop-down list, and click
-<tt><span class="guibutton">New</span></tt>.
-</p></li></ol></div></li><li><p>Restart the service.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>svc -t /service/<span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$</pre></li><li><p>Wait a minute, then click on <tt><span class="guilabel">Main Site</span></tt> at the top of the page.</p></li><li><p>Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.</p><p>Near the bottom of the page, click on the <tt><span class="guilabel">OpenFTS Driver</span></tt> link. Click on <tt><span class="guilabel">Administration</span></tt>.
-Click on <tt><span class="guilabel">Initialize OpenFTS Engine</span></tt>.
-Click <tt><span class="guibutton">Initialize OpenFTS Engine</span></tt>. </p></li><li><p>Add the FTS Engine service contract</p><div class="orderedlist"><ol type="a"><li><p>Click on the <tt><span class="guilabel">Main
-Site</span></tt>. </p></li><li><p>Click on the <tt><span class="guilabel">ACS
-Service Contract</span></tt> link near the bottom of the home page. </p></li><li><p>On the <tt><span class="guilabel">FtsEngineDriver</span></tt>
+<tt class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></tt>.
+</p></li></ol></div></li><li><p>Restart the service.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>svc -t /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$</pre></li><li><p>Wait a minute, then click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Main Site</span></span></tt> at the top of the page.</p></li><li><p>Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.</p><p>Near the bottom of the page, click on the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">OpenFTS Driver</span></span></tt> link. Click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></tt>.
+Click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Initialize OpenFTS Engine</span></span></tt>.
+Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Initialize OpenFTS Engine</span></span></tt>. </p></li><li><p>Add the FTS Engine service contract</p><div class="orderedlist"><ol type="a"><li><p>Click on the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Main
+Site</span></span></tt>. </p></li><li><p>Click on the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">ACS
+Service Contract</span></span></tt> link near the bottom of the home page. </p></li><li><p>On the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">FtsEngineDriver</span></span></tt>
line, click
-<tt><span class="guilabel">Install</span></tt>.
-</p></li></ol></div></li><li><p>Restart the service.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>svc -t /service/<span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$</pre></li><li><p>Test FTS. (INCOMPLETE). Add a package that supports search,like "note," add some content, and search for it.</p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analog-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-nsopenssl.html">Next</a></td></tr><tr><td width="40%" align="left">Install Analog web file analyzer </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install nsopenssl</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-full-text-search.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Install</span></span></tt>.
+</p></li></ol></div></li><li><p>Restart the service.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>svc -t /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$</pre></li><li><p>Test FTS. (INCOMPLETE). Add a package that supports search,like "note," add some content, and search for it.</p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext-auth-ldap-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-nsopenssl.html">Next</a></td></tr><tr><td width="40%" align="left">Installing LDAP support </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install nsopenssl</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-full-text-search.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/install-more-software.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.html,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/install-more-software.html 28 Jun 2003 05:07:01 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/install-more-software.html 14 Oct 2003 11:02:58 -0000 1.3
@@ -1,10 +1,9 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix�B.�Install additional supporting software</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="install-redhat.html" title="Appendix�A.�Install Red Hat 8.0"><link rel="next" href="openacs-unpack.html" title="Unpack the OpenACS tarball"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-redhat.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="openacs-unpack.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="install-more-software"></a>Appendix�B.�Install additional supporting software</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></dt><dt><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt><dt><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt><dt><a href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt><a href="analog-install.html">Install Analog web file analyzer</a></dt><dt><a href="install-full-text-search.html"></a></dt><dt><a href="install-nsopenssl.html">Install nsopenssl</a></dt></dl></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix�B.�Install additional supporting software</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="install-redhat.html" title="Appendix�A.�Install Red Hat 8.0"><link rel="next" href="openacs-unpack.html" title="Unpack the OpenACS tarball"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-redhat.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="openacs-unpack.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="install-more-software"></a>Appendix�B.�Install additional supporting software</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></dt><dt><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt><dt><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt><dt><a href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt><a href="analog-install.html">Install Analog web file analyzer</a></dt><dt><a href="install-nspam.html">Install nspam</a></dt><dt><a href="install-full-text-search.html">Install Full Text Search</a></dt><dt><a href="install-nsopenssl.html">Install nsopenssl</a></dt></dl></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p>This section assumes that the source tarballs for supporting
- software are in <tt>/tmp</tt>. It assumes
+ software are in <tt class="computeroutput">/tmp</tt>. It assumes
that you begin each continuous block of commands as root, and you
should end each block as root. It doesn't care which directory
you start in. Text instructions always precede the commands they
Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,33 +1,32 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install nsopenssl</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-full-text-search.html" title=""><link rel="next" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-full-text-search.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-nsopenssl"></a>Install nsopenssl</h2></div></div><p>This AOLserver module is required if you want people to connect to your site via
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install nsopenssl</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-full-text-search.html" title="Install Full Text Search"><link rel="next" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-full-text-search.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-nsopenssl"></a>Install nsopenssl</h2></div></div><div></div></div><p>This AOLserver module is required if you want people to connect to your site via
https. These commands compile nsopenssl and install it,
along with a tcl helper script to handle https connections.
You will also need ssl certificates. Because those should
be different for each server service, you won't need <a href="maintenance-web.html#ssl-certificates">those instructions</a> until
- later. You will need the <a href="quick.html#install-aolserver-compile">unpacked Aolserver tarball</a> in
- <tt>/usr/local/src/aolserver</tt> and
+ later. You will need the <a href="aolserver.html#install-aolserver-compile">unpacked Aolserver tarball</a> in
+ <tt class="computeroutput">/usr/local/src/aolserver</tt> and
the <a href="individual-programs.html#nsopenssl-download">nsopenssl tarball</a> in
- <tt>/tmp</tt>.</p><p>Red Hat 9 note: see <a href="http://openacs.org/forums/message-view?message_id=92882" target="_top">this
- thread</a> for details on compiling nsopenssl.)</p><pre class="screen">[root@yourserver bin]#<b><tt> cd /usr/local/src/aolserver</tt></b>
-[root@yourserver aolserver]# <b><tt>tar xzf /tmp/nsopenssl-2.1.tar.gz</tt></b>
-[root@yourserver aolserver]# <b><tt>cd nsopenssl-2.1</tt></b>
-[root@yourserver nsopenssl-2.1]# <b><tt>make OPENSSL=/usr/local/ssl</tt></b>
+ <tt class="computeroutput">/tmp</tt>.</p><p>Red Hat 9 note: see <a href="http://openacs.org/forums/message-view?message_id=92882" target="_top">this
+ thread</a> for details on compiling nsopenssl.)</p><pre class="screen">[root@yourserver bin]#<b class="userinput"><tt> cd /usr/local/src/aolserver</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>tar xzf /tmp/nsopenssl-2.1.tar.gz</tt></b>
+[root@yourserver aolserver]# <b class="userinput"><tt>cd nsopenssl-2.1</tt></b>
+[root@yourserver nsopenssl-2.1]# <b class="userinput"><tt>make OPENSSL=/usr/local/ssl</tt></b>
gcc -I/usr/local/ssl/include -I../aolserver/include -D_REENTRANT=1 -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1 -c -o nsopenssl.o nsopenssl.c
<span class="emphasis"><em>(many lines omitted)</em></span>
gcc -shared -nostartfiles -o nsopenssl.so nsopenssl.o config.o init.o ssl.o thread.o tclcmds.o -L/usr/local/ssl/lib -lssl -lcrypto
-[root@yourserver nsopenssl-2.1]# <b><tt>cp nsopenssl.so /usr/local/aolserver/bin</tt></b>
-[root@yourserver nsopenssl-2.1]# <b><tt>cp https.tcl /usr/local/aolserver/modules/tcl/</tt></b>
+[root@yourserver nsopenssl-2.1]# <b class="userinput"><tt>cp nsopenssl.so /usr/local/aolserver/bin</tt></b>
+[root@yourserver nsopenssl-2.1]# <b class="userinput"><tt>cp https.tcl /usr/local/aolserver/modules/tcl/</tt></b>
[root@yourserver nsopenssl-2.1]#
-<pre class="action">cd /usr/local/src/aolserver
+<pre class="action"><span class="action">cd /usr/local/src/aolserver
tar xzf /tmp/nsopenssl-2.1.tar.gz
cd nsopenssl-2.1
make OPENSSL=/usr/local/ssl
cp nsopenssl.so /usr/local/aolserver/bin
-cp https.tcl /usr/local/aolserver/modules/tcl/</pre></pre><p>For Debian (<a href="http://openacs.org/forums/message-view?message_id=93854" target="_top">more
- information</a>):</p><pre class="screen"><pre class="action">apt-get install libssl-dev
+cp https.tcl /usr/local/aolserver/modules/tcl/</span></pre></pre><p>For Debian (<a href="http://openacs.org/forums/message-view?message_id=93854" target="_top">more
+ information</a>):</p><pre class="screen"><pre class="action"><span class="action">apt-get install libssl-dev
cd /usr/local/src/aolserver
tar xzf /tmp/nsopenssl-2.1.tar.gz
cd nsopenssl-2.1
make OPENSSL=/usr/lib/ssl
cp nsopenssl.so /usr/local/aolserver/bin
-cp https.tcl /usr/local/aolserver/modules/tcl/</pre></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-full-text-search.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Part�III.�For OpenACS Package Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-nsopenssl.html#comments">View comments on this page at openacs.org</a></center></body></html>
+cp https.tcl /usr/local/aolserver/modules/tcl/</span></pre></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-full-text-search.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Install Full Text Search </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Part�III.�For OpenACS Package Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-nsopenssl.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/install-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/install-overview.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/install-overview.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,22 +1,21 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="next" href="linux-installation.html" title="Install Linux and supporting software"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="unix-install.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="linux-installation.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-overview"></a>Overview</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="next" href="linux-installation.html" title="Install Linux and supporting software"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="unix-install.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="linux-installation.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-overview"></a>Overview</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-purpose"></a>Purpose of this document</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-purpose"></a>Purpose of this document</h3></div></div><div></div></div><p>
This document will describe how to install, configure, and
- maintain an installation of OpenACS 5.0.0d on a Unix-like
+ maintain an installation of OpenACS 5.0.0a1 on a Unix-like
system, including all supporting software. All examples
- in this chapter are part of the OpenACS 5.0.0d-P or
- OpenACS 5.0.0d-O Reference Platform, which use Red
+ in this chapter are part of the OpenACS 5.0.0a1-P or
+ OpenACS 5.0.0a1-O Reference Platform, which use Red
Hat 8.0. Differences between the Reference Platform
and common alternate platforms (Red Hat 9, Debian) are noted where known.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-requirements"></a>Requirements</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-requirements"></a>Requirements</h3></div></div><div></div></div><p>
You will need a PC (or equivalent) with at least these minimum
requirements:
</p><div class="itemizedlist"><ul type="disc"><li><p>Pentium processor</p></li><li><p>128 MB RAM
- (much more if you want Oracle)</p></li><li><p>4 GB hard drive</p></li></ul></div><p>You will need all everthing marked REQUIRED in <a href="individual-programs.html" title="Individual Programs">the section called “Individual Programs”</a>.</p><p>
+ (much more if you want Oracle)</p></li><li><p>4 GB hard drive</p></li></ul></div><p>You will need all everthing marked REQUIRED in <a href="individual-programs.html" title="Individual Programs">Section�, “Individual Programs”</a>.</p><p>
If you want to serve pages to people outside of your machine, you'll
need a network connection of some type.
</p><p>
@@ -30,8 +29,8 @@
</p></li><li><p>
(For Oracle) Starting an X server and running an X program remotely
</p></li><li><p>
- Basic file management using <tt>cp, rm,
- mv,</tt> and <tt>cd</tt>
+ Basic file management using <tt class="computeroutput">cp, rm,
+ mv,</tt> and <tt class="computeroutput">cd</tt>
</p></li><li><p>
Compiling a program using ./config and make.
</p></li></ul></div><p>
@@ -42,36 +41,36 @@
All of the software that you will need is free and open-source,
except for Oracle. You can obtain a free copy of Oracle for
development purposes. This is described in the <a href="oracle.html#install-oracle-getit">Acquire Oracle</a> section.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-steps"></a>Steps involved</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-steps"></a>Steps involved</h3></div></div><div></div></div><p>
The basic steps to getting OpenACS up and running are:
</p><div class="orderedlist"><ol type="1"><li><p>Install an OS</p></li><li><p>Install a database (Oracle or
- PostgreSQL)</p></li><li><p>Install a webserver (AOLServer)</p></li><li><p>Copy the OpenACS files into place and start the OpenACS installer, which will configure a database instance.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2920654"></a>How to use this guide</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><tt>This</tt> is text you will see on
- screen, such as a <tt><span class="guibutton"><u>B</u>utton</span></tt> or <tt><span class="guilabel"><u>link</u></span></tt>
- in a radio button list or menu.</p></li><li><p><b><tt>This is text that you will type.</tt></b></p></li><li><p>This is text from a program or file which you may need to
-examine or edit:</p><pre class="programlisting">if {$database == "oracle"} {
- set db_password "mysitepassword"
+ PostgreSQL)</p></li><li><p>Install a webserver (AOLServer)</p></li><li><p>Copy the OpenACS files into place and start the OpenACS installer, which will configure a database instance.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2814827"></a>How to use this guide</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput">This</tt> is text you will see on
+ screen, such as a <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">B</span></u>utton</span></span></tt> or <tt class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">link</span></u></span></span></tt>
+ in a radio button list or menu.</p></li><li><p><b class="userinput"><tt>This is text that you will type.</tt></b></p></li><li><p>This is text from a program or file which you may need to
+examine or edit:</p><pre class="programlisting">if {$database == "oracle"} {
+ set db_password "mysitepassword"
}</pre></li><li><p>This is text that you will
-<tt>see</tt> and <b><tt>type</tt></b> in a command shell, including <span class="replaceable">text you may have to
-change</span>. It is followed by a list of just the commands,
-which you can copy and paste.</p><pre class="screen">[root@localhost root]# <b><tt>su - nsadmin</tt></b>
-[nsadmin@localhost aolserver]$ <b><tt>svc -d /service/<span class="replaceable">server1</span></tt></b>
-[nsadmin@localhost aolserver]$ <b><tt>dropdb <span class="replaceable">server1</span></tt></b>
+<tt class="computeroutput">see</tt> and <b class="userinput"><tt>type</tt></b> in a command shell, including <span class="replaceable"><span class="replaceable">text you may have to
+change</span></span>. It is followed by a list of just the commands,
+which you can copy and paste.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - nsadmin</tt></b>
+[nsadmin@localhost aolserver]$ <b class="userinput"><tt>svc -d /service/<span class="replaceable"><span class="replaceable">server1</span></span></tt></b>
+[nsadmin@localhost aolserver]$ <b class="userinput"><tt>dropdb <span class="replaceable"><span class="replaceable">server1</span></span></tt></b>
DROP DATABASE
-[nsadmin@localhost aolserver]$ <b><tt>createdb <span class="replaceable">server1</span></tt></b>
+[nsadmin@localhost aolserver]$ <b class="userinput"><tt>createdb <span class="replaceable"><span class="replaceable">server1</span></span></tt></b>
CREATE DATABASE
-<pre class="action">su - nsadmin
-svc -d /service/<span class="replaceable">server1</span>
-dropdb <span class="replaceable">server1</span>
-createdb <span class="replaceable">server1</span></pre></pre></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-stuck"></a>What if I get stuck?</h3></div></div><p>
+<pre class="action"><span class="action">su - nsadmin
+svc -d /service/<span class="replaceable"><span class="replaceable">server1</span></span>
+dropdb <span class="replaceable"><span class="replaceable">server1</span></span>
+createdb <span class="replaceable"><span class="replaceable">server1</span></span></span></pre></pre></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-stuck"></a>What if I get stuck?</h3></div></div><div></div></div><p>
We'll do our best to assure that following our instructions will get
you to the promised land. If something goes wrong, don't
panic. There are plenty of ways to get help. Here are some tips:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Keep track of the commands you are run and record their output. I
like to do my installations in a shell inside of emacs
- (<tt>M-x shell</tt>) so that I can save
+ (<tt class="computeroutput">M-x shell</tt>) so that I can save
the output if needed. An alternative would be to use the
- <tt>script</tt> command.
+ <tt class="computeroutput">script</tt> command.
</p></li><li><p>
We'll point out where the error logs for the various pieces of
software are. Output from those logs will help us help you. Don't
@@ -102,16 +101,16 @@
If you find errors in this document or if you have ideas about
making it better, please post them in our
<a href="http://openacs.org/bugtracker/openacs/" target="_top">BugTracker</a>.
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-rpms"></a>Is there an easier way?</h3></div></div><p>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-rpms"></a>Is there an easier way?</h3></div></div><div></div></div><p>
After reading through this tome, you may ask yourself if there is a
better way. Well, not quite. Jonathan Marsden has created RPMs (at
<a href="http://www.xc.org/jonathan/openacs/openacs4-rpm-based-install.html" target="_top">http://www.xc.org</a>)
for OpenACS 4.5 but there are not yet any for version
- 5.0.0d. There has been talk about automating the install process,
+ 5.0.0a1. There has been talk about automating the install process,
but that hasn't happened yet. Stay tuned!
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-origins"></a>Where did this document come from?</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-origins"></a>Where did this document come from?</h3></div></div><div></div></div><p>
This document was created by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a>, but it's really
just plagiarism from a number of documents that came before it. If
I've used something that you've written without proper credit, let me
@@ -132,7 +131,7 @@
Aufrecht's OpenACS 4.5 Quick Guide.</a>
</p></li></ul></div><p>
Please also see the <a href="credits.html">Credits</a> section for more acknowledgements.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="os-install"></a>Linux Install Guides</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="os-install"></a>Linux Install Guides</h3></div></div><div></div></div><p>
Here's a list of some helpful documentation for various OS's
</p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://tinyplanet.ca/pubs/debian/" target="_top">Painless Debian
@@ -154,10 +153,10 @@
<a href="http://sdb.suse.de/sdb/en/html/" target="_top">SuSE</a>
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="os-security"></a>Security Information</h3></div></div><p>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="os-security"></a>Security Information</h3></div></div><div></div></div><p>
Once you get your OS installed, it's imperative that you secure your
- installation. As Jon Griffin repeatedly warns us, "No distribution is
- secure out of the box." The Reference Platform implements
+ installation. As Jon Griffin repeatedly warns us, "No distribution is
+ secure out of the box." The Reference Platform implements
some basic precautions, but security is a process, not a
condition. If you are responsible for a computer hooked to the
internet, you are responsible for learning some rudiments of
@@ -178,9 +177,9 @@
</p></li><li><p>
<a href="http://www.counterpane.com/crypto-gram.html" target="_top">Bruce
Schneier's Crypto-Gram</a>, especially <a href="http://www.counterpane.com/crypto-gram-0103.html#1" target="_top">The
- security patch treadmill</a> and <a href="http://www.counterpane.com/crypto-gram-0107.html#5" target="_top">Monitoring First</a>.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-resources"></a>Resources</h3></div></div><p>
+ security patch treadmill</a> and <a href="http://www.counterpane.com/crypto-gram-0107.html#5" target="_top">Monitoring First</a>.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-resources"></a>Resources</h3></div></div><div></div></div><p>
Here are some resources that OpenACS users have found useful.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="install-resources-books"></a>Books</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+ </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="install-resources-books"></a>Books</h4></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/1558605347/photonetA" target="_top">Philip
and Alex's Guide to Web Publishing</a> - A very readable
@@ -195,8 +194,8 @@
</p></li><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/0130206016/photonetA" target="_top">UNIX
- System Administration Handbook</a> (formerly the "red book"
- - now the "purple" book)
+ System Administration Handbook</a> (formerly the "red book"
+ - now the "purple" book)
</p></li><li><p>
@@ -213,7 +212,7 @@
<a href="http://www.amazon.com/exec/obidos/ASIN/1565925858/photonetA" target="_top">Linux
in a Nutshell</a>
- </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="install-resources-web"></a>Web Sites</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+ </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="install-resources-web"></a>Web Sites</h4></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.geek-girl.com/unix.html" target="_top">The UNIX
Reference Desk</a>
Index: openacs-4/packages/acs-core-docs/www/install-qmail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/install-qmail.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/install-qmail.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,68 +1,67 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install qmail (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"><link rel="next" href="analog-install.html" title="Install Analog web file analyzer"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-qmail"></a>Install qmail (OPTIONAL)</h2></div></div><p>Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.</p><div class="orderedlist"><ol type="1"><li><p><b>Install ucspi.�</b>This program handles incoming tcp connections.
- <a href="individual-programs.html#ucspi-download">Download ucspi</a> and install it.</p><p>Red Hat 9.0: put </p><pre class="programlisting">#include <errno.h></pre><p> as the first line of <tt>error.h</tt>. <a href="http://www.riverside.org/archive/html/djbdns/2003-01/msg00307.html" target="_top">More information</a>)</p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/ucspi-tcp-0.88.tar.gz</tt></b>
-[root@yourserver src]# <b><tt>cd ucspi-tcp-0.88</tt></b>
-[root@yourserver ucspi-tcp-0.88]#<b><tt> make</tt></b>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install qmail (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"><link rel="next" href="analog-install.html" title="Install Analog web file analyzer"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-qmail"></a>Install qmail (OPTIONAL)</h2></div></div><div></div></div><p>Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.</p><div class="orderedlist"><ol type="1"><li><p><b>Install ucspi.�</b>This program handles incoming tcp connections.
+ <a href="individual-programs.html#ucspi-download">Download ucspi</a> and install it.</p><p>Red Hat 9.0: put </p><pre class="programlisting">#include <errno.h></pre><p> as the first line of <tt class="computeroutput">error.h</tt>. <a href="http://www.riverside.org/archive/html/djbdns/2003-01/msg00307.html" target="_top">More information</a>)</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/ucspi-tcp-0.88.tar.gz</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>cd ucspi-tcp-0.88</tt></b>
+[root@yourserver ucspi-tcp-0.88]#<b class="userinput"><tt> make</tt></b>
( cat warn-auto.sh; \
-echo 'main="$1"; shift'; \
+echo 'main="$1"; shift'; \
(many lines omitted)
./compile instcheck.c
./load instcheck hier.o auto_home.o unix.a byte.a
-[root@yourserver ucspi-tcp-0.88]# <b><tt>make setup check</tt></b>
+[root@yourserver ucspi-tcp-0.88]# <b class="userinput"><tt>make setup check</tt></b>
./install
./instcheck
[root@yourserver ucspi-tcp-0.88]#
-<pre class="action">cd /usr/local/src
+<pre class="action"><span class="action">cd /usr/local/src
tar xzf /tmp/ucspi-tcp-0.88.tar.gz
cd ucspi-tcp-0.88
make
-make setup check</pre></pre><p>Verify that ucspi-tcp was installed successfully by
-running the tcpserver program which is part of ucspi-tcp:</p><pre class="screen">[root@yourserver ucspi-tcp-0.88]# <b><tt>tcpserver</tt></b>
+make setup check</span></pre></pre><p>Verify that ucspi-tcp was installed successfully by
+running the tcpserver program which is part of ucspi-tcp:</p><pre class="screen">[root@yourserver ucspi-tcp-0.88]# <b class="userinput"><tt>tcpserver</tt></b>
tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid
] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program
[root@yourserver ucspi-tcp-0.88]#
-</pre><p><a class="indexterm" name="id2915326"></a>
+</pre><p><a class="indexterm" name="id2836411"></a>
(I'm not sure if this next step is 100% necessary, but when I skip it
-I get problems. If you get the error <tt>553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1)</tt> then you need to do this.) AOLServer sends outgoing mail via the ns_sendmail
+I get problems. If you get the error <tt class="computeroutput">553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1)</tt> then you need to do this.) AOLServer sends outgoing mail via the ns_sendmail
command, which pipes a command to the sendmail executable. Or, in our
case, the qmail replacement wrapper for the sendmail executable. In
some cases, though, the outgoing mail requset is apparently sent
through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP
-address that means the local machine - the "loopback" interface).
+address that means the local machine - the "loopback" interface).
Unless this mail is addressed to the same machine, qmail thinks that
it's an attempt to relay mail, and rejects it. So these two commands
set up an exception so that any mail sent from 127.0.0.1 is allowed to
-send outgoing mail.</p><pre class="screen">[root@yourserver ucspi-tcp-0.88]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp</tt></b>
-[root@yourserver ucspi-tcp-0.88]# <b><tt>tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp</tt></b>
-<pre class="action">cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
-tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp </pre></pre></li><li><p><b>Install Qmail.�</b><a class="indexterm" name="id2959600"></a></p><p><a href="individual-programs.html#ucspi-download">Download qmail</a>,
+send outgoing mail.</p><pre class="screen">[root@yourserver ucspi-tcp-0.88]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp</tt></b>
+[root@yourserver ucspi-tcp-0.88]# <b class="userinput"><tt>tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp</tt></b>
+<pre class="action"><span class="action">cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
+tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp </span></pre></pre></li><li><p><b>Install Qmail.�</b><a class="indexterm" name="id2836676"></a></p><p><a href="individual-programs.html#ucspi-download">Download qmail</a>,
set up the standard supporting users and build the binaries:</p><p>Red Hat 9.0: Put
</p><pre class="programlisting">#include <errno.h></pre><p>
as the first line of
- <tt>/usr/local/src/qmail-1.03/error.h</tt>.
+ <tt class="computeroutput">/usr/local/src/qmail-1.03/error.h</tt>.
<a href="http://www.riverside.org/archive/html/djbdns/2003-01/msg00307.html" target="_top">More
- information</a></p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/qmail-1.03.tar.gz</tt></b>
-[root@yourserver src]# <b><tt>mkdir /var/qmail</tt></b>
-[root@yourserver src]#<b><tt> groupadd nofiles</tt></b>
-[root@yourserver src]# <b><tt>useradd -g nofiles -d /var/qmail/alias alias</tt></b>
-[root@yourserver src]# <b><tt>useradd -g nofiles -d /var/qmail qmaild</tt></b>
-[root@yourserver src]# <b><tt>useradd -g nofiles -d /var/qmail qmaill</tt></b>
-[root@yourserver src]# <b><tt>useradd -g nofiles -d /var/qmail qmailp</tt></b>
-[root@yourserver src]# <b><tt>groupadd qmail</tt></b>
-[root@yourserver src]# <b><tt>useradd -g qmail -d /var/qmail qmailq</tt></b>
-[root@yourserver src]# <b><tt>useradd -g qmail -d /var/qmail qmailr</tt></b>
-[root@yourserver src]# <b><tt>useradd -g qmail -d /var/qmail qmails</tt></b>
-[root@yourserver src]# <b><tt>cd qmail-1.03</tt></b>
-[root@yourserver qmail-1.03]# <b><tt>make setup check</tt></b>
+ information</a></p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/qmail-1.03.tar.gz</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>mkdir /var/qmail</tt></b>
+[root@yourserver src]#<b class="userinput"><tt> groupadd nofiles</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g nofiles -d /var/qmail/alias alias</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g nofiles -d /var/qmail qmaild</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g nofiles -d /var/qmail qmaill</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g nofiles -d /var/qmail qmailp</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>groupadd qmail</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g qmail -d /var/qmail qmailq</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g qmail -d /var/qmail qmailr</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g qmail -d /var/qmail qmails</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>cd qmail-1.03</tt></b>
+[root@yourserver qmail-1.03]# <b class="userinput"><tt>make setup check</tt></b>
( cat warn-auto.sh; \
echo CC=\'`head -1 conf-cc`\'; \
(many lines omitted)
./install
./instcheck
[root@yourserver qmail-1.03]#
-<pre class="action">cd /usr/local/src
+<pre class="action"><span class="action">cd /usr/local/src
tar xzf /tmp/qmail-1.03.tar.gz
mkdir /var/qmail
groupadd nofiles
@@ -75,11 +74,11 @@
useradd -g qmail -d /var/qmail qmailr
useradd -g qmail -d /var/qmail qmails
cd qmail-1.03
-make setup check</pre></pre><p>Replace sendmail with qmail's wrapper.</p><a class="indexterm" name="id2959790"></a><pre class="screen">[root@yourserver qmail-1.03]# <b><tt>rm -f /usr/bin/sendmail /usr/sbin/sendmail</tt></b>
-[root@yourserver qmail-1.03]# <b><tt>ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</tt></b>
+make setup check</span></pre></pre><p>Replace sendmail with qmail's wrapper.</p><a class="indexterm" name="id2838041"></a><pre class="screen">[root@yourserver qmail-1.03]# <b class="userinput"><tt>rm -f /usr/bin/sendmail /usr/sbin/sendmail</tt></b>
+[root@yourserver qmail-1.03]# <b class="userinput"><tt>ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</tt></b>
[root@yourserver qmail-1.03]#
-<pre class="action">rm -f /usr/bin/sendmail /usr/sbin/sendmail
-ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</pre></pre><p>Configure qmail - specifically, run the config script to set up files in <tt>/var/qmail/control</tt> specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read <tt>/var/qmail/doc/INSTALL.ctl</tt> to find out how to configure qmail.</p><pre class="screen">[root@yourserver qmail-1.03]# <b><tt>./config-fast <span class="replaceable">yourserver.test</span></tt></b>
+<pre class="action"><span class="action">rm -f /usr/bin/sendmail /usr/sbin/sendmail
+ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</span></pre></pre><p>Configure qmail - specifically, run the config script to set up files in <tt class="computeroutput">/var/qmail/control</tt> specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read <tt class="computeroutput">/var/qmail/doc/INSTALL.ctl</tt> to find out how to configure qmail.</p><pre class="screen">[root@yourserver qmail-1.03]# <b class="userinput"><tt>./config-fast <span class="replaceable"><span class="replaceable">yourserver.test</span></span></tt></b>
Your fully qualified host name is yourserver.test.
Putting yourserver.test into control/me...
Putting yourserver.test into control/defaultdomain...
@@ -89,66 +88,66 @@
Now qmail will refuse to accept SMTP messages except to yourserver.test.
Make sure to change rcpthosts if you add hosts to locals or virtualdomains!
[root@yourserver qmail-1.03]#
-<pre class="action">./config-fast <span class="replaceable">yourserver.test</span></pre></pre><p>All incoming mail that isn't for a specific user is handled by the <tt>alias</tt> user. This includes all root mail. These commands prepare the alias user to receive mail.</p><pre class="screen">[root@yourserver qmail-1.03]# <b><tt>cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root</tt></b>
-[root@yourserver alias]# <b><tt>chmod 644 ~alias/.qmail*</tt></b>
-[root@yourserver alias]# <b><tt>/var/qmail/bin/maildirmake ~alias/Maildir/</tt></b>
-[root@yourserver alias]# <b><tt>chown -R alias.nofiles /var/qmail/alias/Maildir</tt></b>
+<pre class="action"><span class="action">./config-fast <span class="replaceable"><span class="replaceable">yourserver.test</span></span></span></pre></pre><p>All incoming mail that isn't for a specific user is handled by the <tt class="computeroutput">alias</tt> user. This includes all root mail. These commands prepare the alias user to receive mail.</p><pre class="screen">[root@yourserver qmail-1.03]# <b class="userinput"><tt>cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root</tt></b>
+[root@yourserver alias]# <b class="userinput"><tt>chmod 644 ~alias/.qmail*</tt></b>
+[root@yourserver alias]# <b class="userinput"><tt>/var/qmail/bin/maildirmake ~alias/Maildir/</tt></b>
+[root@yourserver alias]# <b class="userinput"><tt>chown -R alias.nofiles /var/qmail/alias/Maildir</tt></b>
[root@yourserver alias]#
-<pre class="action">cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
+<pre class="action"><span class="action">cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
chmod 644 ~alias/.qmail*
/var/qmail/bin/maildirmake ~alias/Maildir/
-chown -R alias.nofiles /var/qmail/alias/Maildir</pre></pre><a class="indexterm" name="id2959956"></a><p>Configure qmail to use the Maildir delivery format
- (instead of mbox), and install a version of the qmail startup script modified to use Maildir.</p><pre class="screen">[root@yourserver alias]# <b><tt>echo "./Maildir" > /var/qmail/bin/.qmail</tt></b>
-[root@yourserver alias]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc</tt></b>
-[root@yourserver alias]# <b><tt>chmod 755 /var/qmail/rc</tt></b>
+chown -R alias.nofiles /var/qmail/alias/Maildir</span></pre></pre><a class="indexterm" name="id2837933"></a><p>Configure qmail to use the Maildir delivery format
+ (instead of mbox), and install a version of the qmail startup script modified to use Maildir.</p><pre class="screen">[root@yourserver alias]# <b class="userinput"><tt>echo "./Maildir" > /var/qmail/bin/.qmail</tt></b>
+[root@yourserver alias]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc</tt></b>
+[root@yourserver alias]# <b class="userinput"><tt>chmod 755 /var/qmail/rc</tt></b>
[root@yourserver alias]#
-<pre class="action">echo "./Maildir" > /var/qmail/bin/.qmail
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
+<pre class="action"><span class="action">echo "./Maildir" > /var/qmail/bin/.qmail
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
chmod 755 /var/qmail/rc
-</pre></pre><p>Set up the skeleton directory so that new users will
- be configured for qmail.</p><pre class="screen">[root@yourserver root]# <b><tt>/var/qmail/bin/maildirmake /etc/skel/Maildir</tt></b>
-[root@yourserver root]# <b><tt>echo "./Maildir/" > /etc/skel/.qmail</tt></b>
+</span></pre></pre><p>Set up the skeleton directory so that new users will
+ be configured for qmail.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>/var/qmail/bin/maildirmake /etc/skel/Maildir</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>echo "./Maildir/" > /etc/skel/.qmail</tt></b>
[root@yourserver root]#
-<pre class="action">/var/qmail/bin/maildirmake /etc/skel/Maildir
-echo "./Maildir/" > /etc/skel/.qmail</pre></pre><p>As recommended, we will run qmail with daemontools
- control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.</p><pre class="screen">[root@yourserver root]# <b><tt>mkdir -p /var/qmail/supervise/qmail-send/log</tt></b>
-[root@yourserver root]# <b><tt>mkdir -p /var/qmail/supervise/qmail-smtpd/log</tt></b>
-[root@yourserver root]# <b><tt>mkdir /var/log/qmail</tt></b>
-[root@yourserver root]# <b><tt>chown qmaill /var/log/qmail</tt></b>
-[root@yourserver root]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /var/qmail/bin/qmailctl</tt></b>
-[root@yourserver root]# <b><tt>ln -s /var/qmail/bin/qmailctl /usr/bin</tt></b>
-[root@yourserver root]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run </tt></b>
-[root@yourserver root]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run</tt></b>
-[root@yourserver root]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run</tt></b>
-[root@yourserver root]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /var/qmail/supervise/qmail-send/run</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /var/qmail/supervise/qmail-send/log/run</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /var/qmail/supervise/qmail-smtpd/run</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /var/qmail/supervise/qmail-smtpd/log/run</tt></b>
-[root@yourserver root]# <b><tt>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</tt></b>
-[root@yourserver root]# <b><tt>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</tt></b>
-<pre class="action">mkdir -p /var/qmail/supervise/qmail-send/log
+<pre class="action"><span class="action">/var/qmail/bin/maildirmake /etc/skel/Maildir
+echo "./Maildir/" > /etc/skel/.qmail</span></pre></pre><p>As recommended, we will run qmail with daemontools
+ control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>mkdir -p /var/qmail/supervise/qmail-send/log</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>mkdir -p /var/qmail/supervise/qmail-smtpd/log</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>mkdir /var/log/qmail</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chown qmaill /var/log/qmail</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /var/qmail/bin/qmailctl</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>ln -s /var/qmail/bin/qmailctl /usr/bin</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run </tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /var/qmail/supervise/qmail-send/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /var/qmail/supervise/qmail-send/log/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /var/qmail/supervise/qmail-smtpd/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /var/qmail/supervise/qmail-smtpd/log/run</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</tt></b>
+<pre class="action"><span class="action">mkdir -p /var/qmail/supervise/qmail-send/log
mkdir -p /var/qmail/supervise/qmail-smtpd/log
mkdir /var/log/qmail
chown qmaill /var/log/qmail
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
chmod 755 /var/qmail/bin/qmailctl
ln -s /var/qmail/bin/qmailctl /usr/bin
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
chmod 755 /var/qmail/supervise/qmail-send/run
chmod 755 /var/qmail/supervise/qmail-send/log/run
chmod 755 /var/qmail/supervise/qmail-smtpd/run
chmod 755 /var/qmail/supervise/qmail-smtpd/log/run
ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
-</pre></pre><p>Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes are 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.</p><pre class="screen">[root@yourserver root]# <b><tt>qmailctl stat</tt></b>
+</span></pre></pre><p>Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes are 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>qmailctl stat</tt></b>
/service/qmail-send: up (pid 32700) 430 seconds
/service/qmail-send/log: up (pid 32701) 430 seconds
/service/qmail-smtpd: up (pid 32704) 430 seconds
/service/qmail-smtpd/log: up (pid 32705) 430 seconds
messages in queue: 0
messages in queue but not yet preprocessed: 0
-[root@yourserver root]#</pre><p>Further verify by sending and receiving email. Incoming mail for root is stored in <tt>/var/qmail/alias/Maildir</tt>. </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr><tr><td width="40%" align="left">Install Daemontools (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Analog web file analyzer</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-qmail.html#comments">View comments on this page at openacs.org</a></center></body></html>
+[root@yourserver root]#</pre><p>Further verify by sending and receiving email. Incoming mail for root is stored in <tt class="computeroutput">/var/qmail/alias/Maildir</tt>. </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr><tr><td width="40%" align="left">Install Daemontools (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Analog web file analyzer</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-qmail.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/install-redhat.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/install-redhat.html 20 Aug 2003 16:20:16 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/install-redhat.html 14 Oct 2003 11:02:58 -0000 1.5
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix�A.�Install Red Hat 8.0</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="backup-recovery.html" title="Backup and Recovery"><link rel="next" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="install-redhat"></a>Appendix�A.�Install Red Hat 8.0</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Appendix�A.�Install Red Hat 8.0</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="backup-recovery.html" title="Backup and Recovery"><link rel="next" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="install-redhat"></a>Appendix�A.�Install Red Hat 8.0</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -12,35 +11,35 @@
of these packages installed independently.)</p><div class="orderedlist"><ol type="1"><li><p><a name="install-first-step"></a>Unplug the network cable from your
computer. We don't want to connect to the network
until we're sure the computer is secure.
-<a class="indexterm" name="id2972826"></a>
+<a class="indexterm" name="id2833026"></a>
(Wherever you see
- the word secure, you should always read it as, "secure
+ the word secure, you should always read it as, "secure
enough for our purposes, given the amount of work we're
willing to exert and the estimated risk and
- consequences.")</p></li><li><p>Insert Red Hat 8.0 Disk 1 into the
+ consequences.")</p></li><li><p>Insert Red Hat 8.0 Disk 1 into the
CD-ROM and reboot the computer</p></li><li><p>At the
- <tt><span class="guilabel">boot:</span></tt>
+ <tt class="computeroutput"><span class="guilabel"><span class="guilabel">boot:</span></span></tt>
prompt, press Enter for a
graphical install. The text install is fairly different, so
if you need to do that instead proceed with caution, because
the guide won't match the steps.</p></li><li><p>Checking the media is probably a waste of
time, so when it asks press Tab and
- then Enter to skip it.</p></li><li><p>After the graphical introduction page loads, click <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>Choose the language you want to use and then click
-<tt><span class="guibutton"><u>N</u>ext</span></tt>
-</p></li><li><p>Select the keyboard layout you will use and Click <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>Choose your mouse type and Click <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>Red Hat has several templates for new
- computers. We'll start with the "Server" template and then
+ then Enter to skip it.</p></li><li><p>After the graphical introduction page loads, click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>Choose the language you want to use and then click
+<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>
+</p></li><li><p>Select the keyboard layout you will use and Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>Choose your mouse type and Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>Red Hat has several templates for new
+ computers. We'll start with the "Server" template and then
fine-tune it during the rest of the install. Choose
- <tt><span class="guilabel">Server</span></tt>
+ <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Server</span></span></tt>
and click
- <tt><span class="guibutton"><u>N</u>ext</span></tt>.</p></li><li><p>Reformat the hard drive. If you know what you're doing,
+ <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.</p></li><li><p>Reformat the hard drive. If you know what you're doing,
do this step on your own. Otherwise: we're going to let the
installer wipe out the everything on the main hard drive and then arrange things to
- its liking.</p><div class="orderedlist"><ol type="a"><li><p>Choose <tt><span class="guilabel">Automatically Partition</span></tt>
- and click <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>Uncheck
-<tt><span class="guilabel">Re<u>v</u>iew (and modify if needed) the partitions created</span></tt> and click <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>On the pop-up window asking "Are you sure
- you want to do this?" click
- <tt><span class="guibutton"><u>Y</u>es</span></tt>
- IF YOU ARE WIPING YOUR HARD DRIVE.</p></li><li><p>Click <tt><span class="guibutton"><u>N</u>ext</span></tt> on the boot loader screen</p></li></ol></div></li><li><p>Configure Networking. <a class="indexterm" name="id2997236"></a>
+ its liking.</p><div class="orderedlist"><ol type="a"><li><p>Choose <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Automatically Partition</span></span></tt>
+ and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>Uncheck
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Re<u><span class="accel">v</span></u>iew (and modify if needed) the partitions created</span></span></tt> and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>On the pop-up window asking "Are you sure
+ you want to do this?" click
+ <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">Y</span></u>es</span></span></tt>
+ IF YOU ARE WIPING YOUR HARD DRIVE.</p></li><li><p>Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt> on the boot loader screen</p></li></ol></div></li><li><p>Configure Networking. <a class="indexterm" name="id2835006"></a>
Again, if you know what you're doing, do this step
yourself, being sure to note the firewall holes. Otherwise,
follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.</p><div class="orderedlist"><ol type="a"><li><p>DHCP is a system by which a computer that
@@ -49,31 +48,31 @@
IP address (if it doesn't, it will be tricky to access the OpenACS
service from the outside world), we're going to set up that address.
If you don't know your netmask, 255.255.255.0 is usually a pretty safe
-guess. Click <tt><span class="guibutton">Edit</span></tt>, uncheck <tt><span class="guilabel">Configure using <u>D</u>HCP</span></tt>
-and type in your IP and netmask. Click <tt><span class="guibutton"><u>O</u>k</span></tt>.</p></li><li><p> Type in your host
-name, gateway, and DNS server(s). Then click <tt><span class="guibutton"><u>N</u>ext</span></tt>.</p></li><li><p>We're going to use the firewall template for high
+guess. Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Edit</span></span></tt>, uncheck <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Configure using <u><span class="accel">D</span></u>HCP</span></span></tt>
+and type in your IP and netmask. Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">O</span></u>k</span></span></tt>.</p></li><li><p> Type in your host
+name, gateway, and DNS server(s). Then click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.</p></li><li><p>We're going to use the firewall template for high
security, meaning that we'll block almost all incoming traffic. Then
we'll add a few holes to the firewall for services which we need and
-know are secure. Choose <tt><span class="guilabel">Hi<u>g</u>h</span></tt>
+know are secure. Choose <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Hi<u><span class="accel">g</span></u>h</span></span></tt>
security level. Check
-<tt><span class="guilabel">WWW</span></tt>,
-<tt><span class="guilabel">SSH</span></tt>, and
-<tt><span class="guilabel">Mail (SMTP)</span></tt>. In the <tt><span class="guilabel">Other <u>p</u>orts</span></tt>
-box, enter <b><tt>443, 8000, 8443</tt></b>. Click
-<tt><span class="guibutton"><u>N</u>ext</span></tt>.
-Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.</p></li></ol></div></li><li><p><a class="indexterm" name="id2972563"></a>Select any additional languages you want the
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">WWW</span></span></tt>,
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">SSH</span></span></tt>, and
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Mail (SMTP)</span></span></tt>. In the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Other <u><span class="accel">p</span></u>orts</span></span></tt>
+box, enter <b class="userinput"><tt>443, 8000, 8443</tt></b>. Click
+<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.
+Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.</p></li></ol></div></li><li><p><a class="indexterm" name="id2834573"></a>Select any additional languages you want the
computer to support and then click
- <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>Choose your time zone and click <tt><span class="guibutton"><u>N</u>ext</span></tt>.</p></li><li><p>Type in a root
+ <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>Choose your time zone and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.</p></li><li><p>Type in a root
password, twice. To
improve security, we're going to prevent anyone from
connecting to the computer directly as root. Instead,
we'll create a different user, called
- <tt>remadmin</tt>, used solely to
+ <tt class="computeroutput">remadmin</tt>, used solely to
connect to the computer for administration. Click
-<tt><span class="guibutton"><u>A</u>dd</span></tt>
-and enter username <b><tt>remadmin</tt></b> and a password,
-twice, then click <tt><span class="guibutton"><u>O</u>K</span></tt>. Then click
-<tt><span class="guibutton"><u>N</u>ext</span></tt>.</p></li><li><p>On the Package selection page, we're going to
+<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">A</span></u>dd</span></span></tt>
+and enter username <b class="userinput"><tt>remadmin</tt></b> and a password,
+twice, then click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">O</span></u>K</span></span></tt>. Then click
+<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.</p></li><li><p>On the Package selection page, we're going to
uncheck a lot of packages that install software we don't need, and add
packages that have stuff we do need. You should install everything
we're installing here or the guide may not work for you; you can
@@ -82,87 +81,87 @@
risk that's still screened by the firewall, or a resource hog. Just
don't install a database or web server, because that would conflict
with the database and web server we'll install later.
-</p><div class="literallayout"><p>check�<tt><span class="guilabel">Editors</span></tt>�(this�installs�emacs<a class="indexterm" name="id2972714"></a>),<br>
-click�<tt><span class="guilabel">Details</span></tt>�next�to�<tt><span class="guilabel">Text-based�Internet</span></tt>,�check�<tt><span class="guilabel">lynx</span></tt>,�and�click�<tt><span class="guibutton"><u>O</u>K</span></tt>;<br>
-check�<tt><span class="guilabel">Authoring�and�Publishing</span></tt>�(<a class="indexterm" name="id2977900"></a>this�installs�docbook),<br>
-uncheck�<tt><span class="guilabel">Server�Configuration�Tools</span></tt>,<br>
-uncheck�<tt><span class="guilabel">Web�Server</span></tt>,<br>
-uncheck�<tt><span class="guilabel">Windows�File�Server</span></tt>,<br>
-check�<tt><span class="guilabel">Development�Tools</span></tt>�(this�installs�gmake�and�other�build�tools),<br>
-uncheck�<tt><span class="guilabel">Administration�Tools</span></tt>,�and<br>
-uncheck�<tt><span class="guilabel">Printing�Support</span></tt>.�</p></div><p>At the bottom, check <tt><span class="guilabel"><u>S</u>elect Individual Packages</span></tt> and click <tt><span class="guibutton"><u>N</u>ext</span></tt></p></li><li><p>We need to fine-tune the exact list of packages.
+</p><div class="literallayout"><p>check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Editors</span></span></tt>�(this�installs�emacs<a class="indexterm" name="id2834679"></a>),<br>
+click�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Details</span></span></tt>�next�to�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Text-based�Internet</span></span></tt>,�check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">lynx</span></span></tt>,�and�click�<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">O</span></u>K</span></span></tt>;<br>
+check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Authoring�and�Publishing</span></span></tt>�(<a class="indexterm" name="id2834720"></a>this�installs�docbook),<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Server�Configuration�Tools</span></span></tt>,<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Web�Server</span></span></tt>,<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Windows�File�Server</span></span></tt>,<br>
+check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Development�Tools</span></span></tt>�(this�installs�gmake�and�other�build�tools),<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Administration�Tools</span></span></tt>,�and<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Printing�Support</span></span></tt>.�</p></div><p>At the bottom, check <tt class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">S</span></u>elect Individual Packages</span></span></tt> and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></li><li><p>We need to fine-tune the exact list of packages.
The same rules apply as in the last step - you can add more stuff, but
you shouldn't remove anything the guide adds. We're going to go
through all the packages in one big list, so select
-<tt><span class="guilabel"><u>F</u>lat
-View</span></tt> and wait. In a minute, a
-list of packages will appear.</p><div class="literallayout"><p>uncheck�<tt><span class="guilabel">apmd</span></tt>�(monitors�power,�not�very�useful�for�servers),�<br>
-check�<tt><span class="guilabel">ImageMagick</span></tt>�(required�for�the�<a class="indexterm" name="id2978069"></a>photo-album�packages,�<br>
-uncheck<tt><span class="guilabel">isdn4k-utils</span></tt>�(unless�you�are�using�isdn,�this�installs�a�useless�daemon),�<br>
-check�<tt><span class="guilabel">mutt</span></tt>�(a�mail�program�that�reads�Maildir),<br>
-uncheck�<tt><span class="guilabel">nfs-utils</span></tt>�(nfs�is�a�major�security�risk),�<br>
-uncheck�<tt><span class="guilabel">pam-devel</span></tt>�(I�don't�remember�why,�but�we�don't�want�this),�<br>
-uncheck�<tt><span class="guilabel">portmap</span></tt>,�<br>
-uncheck�<tt><span class="guilabel">postfix</span></tt>�(this�is�an�MTA,�but�we're�going�to�install�qmail�later),�<br>
-uncheck�<tt><span class="guilabel">rsh</span></tt>�(rsh�is�a�security�hole),�<br>
-uncheck�<tt><span class="guilabel">sendmail</span></tt>�(sendmail�is�an�insecure�MTA;�we're�going�to�install�qmail�instead�later),<br>
-check�<tt><span class="guilabel">tcl</span></tt>�(we�need�tcl),�and�<br>
-uncheck�<tt><span class="guilabel">xinetd</span></tt>�(xinetd�handles�incoming�tcp�connections.��We'll�install�a�different,�more�secure�program,�ucspi-tcp).<br>
-Click�<tt><span class="guibutton"><u>N</u>ext</span></tt></p></div></li><li><p>Red Hat isn't completely happy with the combination
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">F</span></u>lat
+View</span></span></tt> and wait. In a minute, a
+list of packages will appear.</p><div class="literallayout"><p>uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">apmd</span></span></tt>�(monitors�power,�not�very�useful�for�servers),�<br>
+check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">ImageMagick</span></span></tt>�(required�for�the�<a class="indexterm" name="id2834823"></a>photo-album�packages,�<br>
+uncheck<tt class="computeroutput"><span class="guilabel"><span class="guilabel">isdn4k-utils</span></span></tt>�(unless�you�are�using�isdn,�this�installs�a�useless�daemon),�<br>
+check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">mutt</span></span></tt>�(a�mail�program�that�reads�Maildir),<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">nfs-utils</span></span></tt>�(nfs�is�a�major�security�risk),�<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">pam-devel</span></span></tt>�(I�don't�remember�why,�but�we�don't�want�this),�<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">portmap</span></span></tt>,�<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">postfix</span></span></tt>�(this�is�an�MTA,�but�we're�going�to�install�qmail�later),�<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">rsh</span></span></tt>�(rsh�is�a�security�hole),�<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">sendmail</span></span></tt>�(sendmail�is�an�insecure�MTA;�we're�going�to�install�qmail�instead�later),<br>
+check�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">tcl</span></span></tt>�(we�need�tcl),�and�<br>
+uncheck�<tt class="computeroutput"><span class="guilabel"><span class="guilabel">xinetd</span></span></tt>�(xinetd�handles�incoming�tcp�connections.��We'll�install�a�different,�more�secure�program,�ucspi-tcp).<br>
+Click�<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt></p></div></li><li><p>Red Hat isn't completely happy with the combination
of packages we've selected, and wants to satisfy some dependencies.
Don't let it. On the next screen, choose
-<tt><span class="guilabel">I<u>g</u>nore Package
-Dependencies</span></tt> and click
-<tt><span class="guibutton"><u>N</u>ext</span></tt>.
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">I<u><span class="accel">g</span></u>nore Package
+Dependencies</span></span></tt> and click
+<tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.
</p></li><li><p>Click
- <tt><span class="guibutton"><u>N</u>ext</span></tt>
+ <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>
to start the copying of files.</p></li><li><p>Wait. Insert Disk 2 when
asked.</p></li><li><p>Wait. Insert Disk 3 when asked.</p></li><li><p>If you know how to use it, create a boot
disk. Since you can also boot into recovery mode with the
Install CDs, this is less useful than it used to be, and we
- won't bother. Select <tt><span class="guilabel">No,I <u>d</u>o not want to create a boot disk</span></tt> and click <tt><span class="guibutton"><u>N</u>ext</span></tt>.</p></li><li><p>Click <tt><span class="guilabel"><u>E</u>xit</span></tt>, remove the CD, and watch the
+ won't bother. Select <tt class="computeroutput"><span class="guilabel"><span class="guilabel">No,I <u><span class="accel">d</span></u>o not want to create a boot disk</span></span></tt> and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></tt>.</p></li><li><p>Click <tt class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">E</span></u>xit</span></span></tt>, remove the CD, and watch the
computer reboot.
</p></li><li><p>After it finishes rebooting and shows the login
- prompt, log in:</p><pre class="screen">yourserver login: <b><tt>root</tt></b>
+ prompt, log in:</p><pre class="screen">yourserver login: <b class="userinput"><tt>root</tt></b>
Password:
-[root@yourserver root]#</pre></li><li><p>Lock down SSH</p><div class="orderedlist"><ol type="a"><li><p><a class="indexterm" name="id2993504"></a>
+[root@yourserver root]#</pre></li><li><p>Lock down SSH</p><div class="orderedlist"><ol type="a"><li><p><a class="indexterm" name="id2835483"></a>
SSH is the protocol we use to connect
securely to the computer (replacing telnet, which is
insecure). sshd is the daemon that listens for incoming
ssh connections. As a security precaution, we are now going
to tell ssh not to allow anyone to connect directly to this
computer as root. Type this into the shell:
- </p><pre class="screen"><b><tt>emacs /etc/ssh/sshd_config</tt></b></pre></li><li><div class="literallayout"><p>Search�for�the�word�"root"�by�typing�C-s�(that's�emacs-speak�for�control-s)�and�then�<b><tt>root</tt></b>.���<br>
+ </p><pre class="screen"><b class="userinput"><tt>emacs /etc/ssh/sshd_config</tt></b></pre></li><li><div class="literallayout"><p>Search�for�the�word�"root"�by�typing�C-s�(that's�emacs-speak�for�control-s)�and�then�<b class="userinput"><tt>root</tt></b>.���<br>
Make�the�following�changes:<br>
<pre class="programlisting">#Protocol�2,1</pre>�to�<pre class="programlisting">Protocol�2</pre>�(this�prevents�any�connections�via�SSH�1,�which�is�insecure)<br>
<pre class="programlisting">#PermitRootLogin�yes</pre>�to�<pre class="programlisting">PermitRootLogin�no</pre>�(this�prevents�the�root�use�from�logging�in�via�ssh)<br>
<pre class="programlisting">#PermitEmptyPasswords�no</pre>�to�<pre class="programlisting">PermitEmptyPasswords�no</pre>�(this�blocks�passwordless�accounts)<br>
<br>
-�and�save�and�exit�by�typing�C-x�C-s�C-x�C-c</p></div></li><li>Restart sshd so that the change takes effect.<pre class="screen"><b><tt>service sshd restart</tt></b></pre></li></ol></div></li><li><p>Red Hat still installed a few services we
-don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the System V init directories to permanently (The System V init directories are the ones in /etc/rc.d. They consist of a bunch of scripts for starting and stopping programs, and directories of symlinks for each system level indicating which services should be up and down at any given service level. We'll use this system for PostGreSQL, but we'll use daemontools to perform a similar function for AOLServer. (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostGreSQL the way it is.)</p><pre class="screen">[root@yourserver root]# <b><tt>service pcmcia stop</tt></b>
-[root@yourserver root]# <b><tt>service netfs stop</tt></b>
-[root@yourserver root]# <b><tt>chkconfig --del pcmcia</tt></b>
-[root@yourserver root]# <b><tt>chkconfig --del netfs</tt></b>
+�and�save�and�exit�by�typing�C-x�C-s�C-x�C-c</p></div></li><li>Restart sshd so that the change takes effect.<pre class="screen"><b class="userinput"><tt>service sshd restart</tt></b></pre></li></ol></div></li><li><p>Red Hat still installed a few services we
+don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the System V init directories to permanently (The System V init directories are the ones in /etc/rc.d. They consist of a bunch of scripts for starting and stopping programs, and directories of symlinks for each system level indicating which services should be up and down at any given service level. We'll use this system for PostGreSQL, but we'll use daemontools to perform a similar function for AOLServer. (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostGreSQL the way it is.)</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>service pcmcia stop</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>service netfs stop</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chkconfig --del pcmcia</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chkconfig --del netfs</tt></b>
[root@yourserver root]#
-<pre class="action">service pcmcia stop
+<pre class="action"><span class="action">service pcmcia stop
service netfs stop
chkconfig --del pcmcia
-chkconfig --del netfs</pre></pre></li><li><p>Plug in the network cable.</p></li><li><p>Verify that you have connectivity by going to another
+chkconfig --del netfs</span></pre></pre></li><li><p>Plug in the network cable.</p></li><li><p>Verify that you have connectivity by going to another
computer and ssh'ing to
- <span class="replaceable">yourserver</span>, logging in as
- remadmin, and promoting yourself to root:</p><pre class="screen">[joeuser@someotherserver]$ <b><tt> ssh <span class="replaceable">remadmin@yourserver.test</span></tt></b>
+ <span class="replaceable"><span class="replaceable">yourserver</span></span>, logging in as
+ remadmin, and promoting yourself to root:</p><pre class="screen">[joeuser@someotherserver]$ <b class="userinput"><tt> ssh <span class="replaceable"><span class="replaceable">remadmin@yourserver.test</span></span></tt></b>
The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5.
-Are you sure you want to continue connecting (yes/no)? <b><tt>yes</tt></b>
+Are you sure you want to continue connecting (yes/no)? <b class="userinput"><tt>yes</tt></b>
Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts.
Password:
Last login: Mon Mar 3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com
-[remadmin@yourserver remadmin]$ <b><tt>su -</tt></b>
+[remadmin@yourserver remadmin]$ <b class="userinput"><tt>su -</tt></b>
Password:
[root@yourserver root]#</pre></li><li><p>Upgrade the kernel to fix a security hole. The default
Red Hat 8.0 system kernel (2.4.18-14, which you can check
- with <b><tt>uname -a</tt></b>) has several <a href="https://rhn.redhat.com/errata/RHSA-2003-098.html" target="_top">security problems</a>. Download the new kernel, install it, and reboot.</p><pre class="screen">[root@yourserver root]# <b><tt>cd /tmp</tt></b>
-[root@yourserver tmp]# <b><tt>wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm</tt></b>
+ with <b class="userinput"><tt>uname -a</tt></b>) has several <a href="https://rhn.redhat.com/errata/RHSA-2003-098.html" target="_top">security problems</a>. Download the new kernel, install it, and reboot.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /tmp</tt></b>
+[root@yourserver tmp]# <b class="userinput"><tt>wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm</tt></b>
--20:39:00-- http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
=> `kernel-2.4.18-27.7.x.i686.rpm'
Resolving updates.redhat.com... done.
@@ -174,17 +173,17 @@
20:41:39 (78.38 KB/s) - `kernel-2.4.18-27.7.x.i686.rpm' saved [12736430/12736430]
-root@yourserver tmp]# <b><tt>rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm</tt></b>
+root@yourserver tmp]# <b class="userinput"><tt>rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm</tt></b>
warning: kernel-2.4.18-27.7.x.i686.rpm: V3 DSA signature: NOKEY, key ID db42a60e
Preparing... ########################################### [100%]
1:kernel ########################################### [100%]
-[root@yourserver tmp]# <b><tt>reboot</tt></b>
+[root@yourserver tmp]# <b class="userinput"><tt>reboot</tt></b>
Broadcast message from root (pts/0) (Sat May 3 20:46:39 2003):
The system is going down for reboot NOW!
[root@yourserver tmp]#
-<pre class="action">cd /tmp
+<pre class="action"><span class="action">cd /tmp
wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm
-reboot</pre></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr><tr><td width="40%" align="left">Backup and Recovery </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Appendix�B.�Install additional supporting software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-redhat.html#comments">View comments on this page at openacs.org</a></center></body></html>
+reboot</span></pre></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr><tr><td width="40%" align="left">Backup and Recovery </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Appendix�B.�Install additional supporting software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/install-redhat.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/kernel-doc.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�13.�Kernel Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-plat-dev.html" title="Part�IV.�For OpenACS Platform Developers"><link rel="previous" href="acs-plat-dev.html" title="Part�IV.�For OpenACS Platform Developers"><link rel="next" href="kernel-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><th width="60%" align="center">Part�IV.�For OpenACS Platform Developers</th><td width="20%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="kernel-doc"></a>Chapter�13.�Kernel Documentation</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 5.0.0d Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 5.0.0d Package Manager Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></dt><dt><a href="i18n.html">Internationalization</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt><dt><a href="ext-auth-requirements.html">External Authentication Requirements</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part�IV.�For OpenACS Platform Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-plat-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/kernel-doc.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�13.�Kernel Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-plat-dev.html" title="Part�IV.�For OpenACS Platform Developers"><link rel="previous" href="acs-plat-dev.html" title="Part�IV.�For OpenACS Platform Developers"><link rel="next" href="kernel-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><th width="60%" align="center">Part�IV.�For OpenACS Platform Developers</th><td width="20%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="kernel-doc"></a>Chapter�13.�Kernel Documentation</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 5.0.0a1 Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 5.0.0a1 Package Manager Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></dt><dt><a href="i18n.html">Internationalization</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt><dt><a href="ext-auth-requirements.html">External Authentication Requirements</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part�IV.�For OpenACS Platform Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-plat-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/kernel-doc.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v
diff -u -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/kernel-overview.html 20 Aug 2003 16:20:16 -0000 1.8
+++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 14 Oct 2003 11:02:58 -0000 1.9
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="next" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="kernel-overview"></a>Overview</h2></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="next" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-overview"></a>Overview</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The <span class="emphasis"><em>OpenACS Kernel</em></span>, which
handles system-wide necessities such as metadata,
security, users and groups, subsites, and package
Index: openacs-4/packages/acs-core-docs/www/linux-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/linux-installation.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/linux-installation.html 20 Aug 2003 16:20:16 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/linux-installation.html 14 Oct 2003 11:02:58 -0000 1.5
@@ -1,22 +1,21 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Linux and supporting software</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="install-overview.html" title="Overview"><link rel="next" href="oracle.html" title="Install Oracle 8.1.7"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="linux-installation"></a>Install Linux and supporting software</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Linux and supporting software</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="install-overview.html" title="Overview"><link rel="next" href="oracle.html" title="Install Oracle 8.1.7"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="linux-installation"></a>Install Linux and supporting software</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2984170"></a>Paths and Users</h3></div></div><div class="figure"><a name="id2954649"></a><p class="title"><b>Figure�4.1.�Assumptions in this section</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><span class="replaceable">yourserver.test</span></td></tr><tr><td>name of administrative access account</td><td>remadmin</td></tr><tr><td>OpenACS service</td><td><a class="indexterm" name="id2954703"></a><span class="replaceable">service0</span></td></tr><tr><td>OpenACS service account</td><td><span class="replaceable">service0</span></td></tr><tr><td>OpenACS database name</td><td><span class="replaceable">service0</span></td></tr><tr><td>Root of OpenACS service file tree</td><td><span class="replaceable">/web/service0</span></td></tr><tr><td>Location of source code tarballs for new software</td><td>/tmp</td></tr><tr><td>The OpenACS tarball contains some files which
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2822469"></a>Paths and Users</h3></div></div><div></div></div><div class="figure"><a name="id2815685"></a><p class="title"><b>Figure�4.1.�Assumptions in this section</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><span class="replaceable"><span class="replaceable">yourserver.test</span></span></td></tr><tr><td>name of administrative access account</td><td>remadmin</td></tr><tr><td>OpenACS service</td><td><a class="indexterm" name="id2815618"></a><span class="replaceable"><span class="replaceable">service0</span></span></td></tr><tr><td>OpenACS service account</td><td><span class="replaceable"><span class="replaceable">service0</span></span></td></tr><tr><td>OpenACS database name</td><td><span class="replaceable"><span class="replaceable">service0</span></span></td></tr><tr><td>Root of OpenACS service file tree</td><td><span class="replaceable"><span class="replaceable">/web/service0</span></span></td></tr><tr><td>Location of source code tarballs for new software</td><td>/tmp</td></tr><tr><td>The OpenACS tarball contains some files which
are useful while setting up other software. Those
- files are located at:</td><td>/tmp/openacs-5.0.0d/packages/acs-core-docs/www/files</td></tr><tr><td>Database backup directory</td><td><span class="replaceable">/web/service0/database-backup</span></td></tr><tr><td>Service config files</td><td><span class="replaceable">/web/service0/etc</span></td></tr><tr><td>Service log files</td><td><span class="replaceable">/web/service0/log</span></td></tr><tr><td>Compile directory</td><td>/usr/local/src</td></tr><tr><td>PostGreSQL directory</td><td>/usr/local/pgsql</td></tr><tr><td>AOLServer directory</td><td>/usr/local/aolserver</td></tr></tbody></table></div></div><p>
+ files are located at:</td><td>/tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files</td></tr><tr><td>Database backup directory</td><td><span class="replaceable"><span class="replaceable">/web/service0/database-backup</span></span></td></tr><tr><td>Service config files</td><td><span class="replaceable"><span class="replaceable">/web/service0/etc</span></span></td></tr><tr><td>Service log files</td><td><span class="replaceable"><span class="replaceable">/web/service0/log</span></span></td></tr><tr><td>Compile directory</td><td>/usr/local/src</td></tr><tr><td>PostGreSQL directory</td><td>/usr/local/pgsql</td></tr><tr><td>AOLServer directory</td><td>/usr/local/aolserver</td></tr></tbody></table></div></div><p>
None of these locations are set in stone - they're simply
the values that we've chosen. The values that you'll
probably want to change, such as service name, are
- <span class="replaceable">marked like this</span>. The other
+ <span class="replaceable"><span class="replaceable">marked like this</span></span>. The other
values we recommend you leave unchanged unless you have a
reason to change them.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Some of the paths and user accounts have been changed from
those recommended in previous versions of this document to
improve security and maintainability. See <a href="http://openacs.org/forums/message-view?message_id=82934" target="_top">this
thread</a> for discussion.
-</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-linux"></a>Install Linux</h3></div></div><p>You will need a PC running linux with the following software installed:</p><div class="itemizedlist"><ul type="disc"><li><p>libxml2</p></li><li><p>tcl</p></li><li><p>gmake and the compile and build environment.</p></li></ul></div><p>and optionally these programs, which are included in most distributions:</p><div class="itemizedlist"><ul type="disc"><li><p>emacs</p></li><li><p>cvs (and <a href="install-cvs.html" title="Initialize CVS (OPTIONAL)">initialize</a> it)</p></li><li><p>ImageMagick</p></li><li><p>DocBook and supporting software (and <a href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)">install</a> emacs keybindings for
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-linux"></a>Install Linux</h3></div></div><div></div></div><p>You will need a PC running linux with the following software installed:</p><div class="itemizedlist"><ul type="disc"><li><p>libxml2</p></li><li><p>tcl</p></li><li><p>gmake and the compile and build environment.</p></li></ul></div><p>and optionally these programs, which are included in most distributions:</p><div class="itemizedlist"><ul type="disc"><li><p>emacs</p></li><li><p>cvs (and <a href="install-cvs.html" title="Initialize CVS (OPTIONAL)">initialize</a> it)</p></li><li><p>ImageMagick</p></li><li><p>DocBook and supporting software (and <a href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)">install</a> emacs keybindings for
DocBook SGML)</p></li><li><p>daemontools (<a href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install from
source</a>)</p></li><li><p>a Mail Transport Agent, such as exim or sendmail (or <a href="install-qmail.html" title="Install qmail (OPTIONAL)">install qmail from source</a>)</p></li></ul></div><p>To install a machine to the specifications of the Reference
Platform, do the <a href="install-redhat.html" title="Appendix�A.�Install Red Hat 8.0">walkthrough of the
Index: openacs-4/packages/acs-core-docs/www/mac-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/mac-install.html,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/mac-install.html 28 Jun 2003 05:07:02 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/mac-install.html 14 Oct 2003 11:02:58 -0000 1.6
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�6.�Installing on a Macintosh</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000"><link rel="next" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="mac-install"></a>Chapter�6.�Installing on a Macintosh</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Windows2000 </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Mac OS X</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/mac-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�6.�Installing on a Macintosh</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000"><link rel="next" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="mac-install"></a>Chapter�6.�Installing on a Macintosh</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Windows2000 </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Mac OS X</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/mac-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/mac-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/mac-installation.html,v
diff -u -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/mac-installation.html 20 Aug 2003 16:20:16 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/mac-installation.html 14 Oct 2003 11:02:58 -0000 1.8
@@ -1,3 +1,2 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Installation Guide for Mac OS X</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="previous" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="next" href="configure.html" title="Chapter�7.�Configuring a New Service"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="mac-install.html">Prev</a> </td><th width="60%" align="center">Chapter�6.�Installing on a Macintosh</th><td width="20%" align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="mac-installation"></a>OpenACS Installation Guide for Mac OS X</h2></div></div><p>There are several resources for installing on OS X.</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://borkware.com/rants/openacs/" target="_top">OpenACS on Mac OS X Quickstart</a></p></li><li><p><a href="http://openacs.org/forums/message-view?message_id=24887" target="_top">An
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Installation Guide for Mac OS X</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="previous" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="next" href="configure.html" title="Chapter�7.�Configuring a New Service"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="mac-install.html">Prev</a> </td><th width="60%" align="center">Chapter�6.�Installing on a Macintosh</th><td width="20%" align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mac-installation"></a>OpenACS Installation Guide for Mac OS X</h2></div></div><div></div></div><p>There are several resources for installing on OS X.</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://borkware.com/rants/openacs/" target="_top">OpenACS on Mac OS X Quickstart</a></p></li><li><p><a href="http://openacs.org/forums/message-view?message_id=24887" target="_top">An
older forum thread</a></p></li></ul></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mac-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�6.�Installing on a Macintosh </td><td width="20%" align="center"><a accesskey="u" href="mac-install.html">Up</a></td><td width="40%" align="right"> Chapter�7.�Configuring a New Service</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/mac-installation.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/maintenance-web.html 20 Aug 2003 16:20:16 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 14 Oct 2003 11:02:58 -0000 1.5
@@ -1,61 +1,60 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Hosting Web Sites</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="previous" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="next" href="database-management.html" title="Database Management"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance.html">Prev</a> </td><th width="60%" align="center">Chapter�9.�Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="maintenance-web"></a>Hosting Web Sites</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Hosting Web Sites</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="previous" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="next" href="database-management.html" title="Database Management"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance.html">Prev</a> </td><th width="60%" align="center">Chapter�9.�Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="maintenance-web"></a>Hosting Web Sites</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><p>Maintenance tasks, optional software, and alternate configurations for AOLserver.</p><div class="sect2" lang="en"><div class="titlepage"></div><p>Assuming AOLserver started cleanly in the previous step, we'll set it up so that it's always running, and automatically restarts whenever it dies or is stopped. This step is strongly recommended, even for development sites, because it makes install and maintenance much simpler. </p><p>The Reference Platform uses Daemontools to control AOLserver. A simpler method, using <tt>init</tt>, is <a href="maintenance-web.html#install-openacs-inittab" title="AOLserver keepalive with inittab">here</a>.</p><div class="orderedlist"><ol type="1"><li><p>Daemontools must already be installed. If not, <a href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install it</a>.</p></li><li><p>Each service controlled by daemontools must have a directory in <tt>/service</tt>. That directory must have a file called <tt>run</tt>. Daemontools then creates additional files and directories to track status and log. Create the appropriate directory as <tt>/web/<span class="replaceable">service0</span>/etc/daemontools</tt>, copy the prepared <tt>run</tt> file, and set permissions. If your server is not called <span class="replaceable">service0</span>, edit <tt>/web/<span class="replaceable">service0</span>/etc/run accordingly.</tt></p><pre class="screen">[service0@yourserver log]$ <b><tt>cd /web/<span class="replaceable">service0</span>/etc</tt></b>
-[service0@yourserver etc]$ <b><tt>mkdir daemontools</tt></b>
-[service0@yourserver etc]$ <b><tt>cp /web/<span class="replaceable">service0</span>/packages/acs-core-docs/www/files/run.txt daemontools/run</tt></b>
-[service0@yourserver etc]$ <b><tt>chmod 700 daemontools/run</tt></b>
-<pre class="action">cd /web/<span class="replaceable">service0</span>/etc
-mkdir daemontools
-cp /web/<span class="replaceable">service0</span>/packages/acs-core-docs/www/files/run.txt daemontools/run
-chmod 700 daemontools/run</pre></pre></li><li><p>Kill any existing AOLserver instances. As root, link the <tt>daemontools</tt> directory into the <tt>/service</tt> directory. Daemontools' <tt>svscan</tt> process checks this directory every five seconds, and will quickly execute <tt>run</tt>.</p><pre class="screen">[service0@yourserver etc]$ <b><tt>killall nsd</tt></b>
+ </p></div><p>Maintenance tasks, optional software, and alternate configurations for AOLserver.</p><div class="sect2" lang="en"><div class="titlepage"><div></div><div></div></div><p>Assuming AOLserver started cleanly in the previous step, we'll set it up so that it's always running, and automatically restarts whenever it dies or is stopped. This step is strongly recommended, even for development sites, because it makes install and maintenance much simpler. </p><p>The Reference Platform uses Daemontools to control AOLserver. A simpler method, using <tt class="computeroutput">init</tt>, is <a href="maintenance-web.html#install-openacs-inittab" title="AOLserver keepalive with inittab">here</a>.</p><div class="orderedlist"><ol type="1"><li><p>Daemontools must already be installed. If not, <a href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install it</a>.</p></li><li><p>Each service controlled by daemontools must have a
+ directory in <tt class="computeroutput">/service</tt>. That
+ directory must have a file called
+ <tt class="computeroutput">run</tt>. Daemontools then
+ creates additional files and directories to track status and
+ log. A daemontools directory is included in the OpenACS
+ tarball at
+ <tt class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/daemontools</tt>. To use it, first ill any existing AOLserver instances. As root, link the <tt class="computeroutput">daemontools</tt> directory into the <tt class="computeroutput">/service</tt> directory. Daemontools' <tt class="computeroutput">svscan</tt> process checks this directory every five seconds, and will quickly execute <tt class="computeroutput">run</tt>.</p><pre class="screen">[service0@yourserver etc]$ <b class="userinput"><tt>killall nsd</tt></b>
nsd: no process killed
-[service0@yourserver etc]$ <b><tt>exit</tt></b>
+[service0@yourserver etc]$ <b class="userinput"><tt>exit</tt></b>
-[root@yourserver root]# <b><tt>ln -s /web/<span class="replaceable">service0</span>/etc/daemontools/ /service/<span class="replaceable">service0</span></tt></b></pre><p>Verify that AOLserver is running.</p><pre class="screen">[root@yourserver root]#<b><tt> ps -auxw | grep nsd</tt></b>
-<span class="replaceable">service0</span> 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /web/<span class="replaceable">service0</span>/etc/config.tcl -u serve
+[root@yourserver root]# <b class="userinput"><tt>ln -s /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/daemontools/ /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b></pre><p>Verify that AOLserver is running.</p><pre class="screen">[root@yourserver root]#<b class="userinput"><tt> ps -auxw | grep nsd</tt></b>
+<span class="replaceable"><span class="replaceable">service0</span></span> 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/config.tcl -u serve
root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd
-[root@yourserver root]#</pre></li><li><p>The user <span class="replaceable">service0</span> can now control the service <span class="replaceable">service0</span> with these commands:</p><div class="itemizedlist"><ul type="disc"><li><p>
+[root@yourserver root]#</pre></li><li><p>The user <span class="replaceable"><span class="replaceable">service0</span></span> can now control the service <span class="replaceable"><span class="replaceable">service0</span></span> with these commands:</p><div class="itemizedlist"><ul type="disc"><li><p>
- <tt>svc -d /service/<span class="replaceable">service0</span></tt> -
+ <tt class="computeroutput">svc -d /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt> -
Bring the server down
</p></li><li><p>
- <tt>svc -u /service/<span class="replaceable">service0</span></tt> -
+ <tt class="computeroutput">svc -u /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt> -
Start the server up and leave it in keepalive mode.
</p></li><li><p>
- <tt>svc -o /service/<span class="replaceable">service0</span></tt> -
+ <tt class="computeroutput">svc -o /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt> -
Start the server up once. Do not restart it if it stops.
</p></li><li><p>
- <tt>svc -t /service/<span class="replaceable">service0</span></tt> -
+ <tt class="computeroutput">svc -t /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt> -
Stop and immediately restart the server.
</p></li><li><p>
- <tt>svc -k /service/<span class="replaceable">service0</span></tt> -
+ <tt class="computeroutput">svc -k /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt> -
Sends the server a KILL signal. This is like KILL -9. AOLserver
exits immediately. If svc -t fails to fully kill AOLserver, use
this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately.
</p></li></ul></div></li><li><p>Install a script to automate the stopping and starting
- of aolserver services via daemontools. You can then restart a service via <tt>restart-aolserver <span class="replaceable">service0</span></tt></p><pre class="screen">[root@yourserver root]# <b><tt>cp /web/<span class="replaceable">service0</span>/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver</tt></b>
-[root@yourserver root]# <b><tt>chmod 755 /usr/local/bin/restart-aolserver</tt></b>
+ of aolserver services via daemontools. You can then restart a service via <tt class="computeroutput">restart-aolserver <span class="replaceable"><span class="replaceable">service0</span></span></tt></p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 755 /usr/local/bin/restart-aolserver</tt></b>
[root@yourserver root]#</pre></li><li><p>
At this point, these commands will work only for the
- <tt>root</tt> user. Grant permission for the <tt>web</tt> group to use <tt>svc</tt> commands on the <span class="emphasis"><em><span class="replaceable">service0</span></em></span> server.</p><pre class="screen">[root@yourserver root]# <b><tt>svgroup web /service/<span class="replaceable">service0</span></tt></b>
-[root@yourserver root]#</pre></li><li><p>Verify that the controls work. You may want to <tt>tail -f /web/<span class="replaceable">service0</span>/log/<span class="replaceable">service0</span>-error.log</tt> in another window, so you can see what happens when you type these commands.
+ <tt class="computeroutput">root</tt> user. Grant permission for the <tt class="computeroutput">web</tt> group to use <tt class="computeroutput">svc</tt> commands on the <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span> server.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>svgroup web /service/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[root@yourserver root]#</pre></li><li><p>Verify that the controls work. You may want to <tt class="computeroutput">tail -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/log/<span class="replaceable"><span class="replaceable">service0</span></span>-error.log</tt> in another window, so you can see what happens when you type these commands.
</p><p>
- Most of this information comes from Tom Jackson's <a href="http://zmbh.com/daemontools-aolserver/aolserver%2Bdaemontools.html" target="_top">AOLServer+Daemontools
+ Most of this information comes from Tom Jackson's <a href="http://zmbh.com/daemontools-aolserver/aolserver+daemontools.html" target="_top">AOLServer+Daemontools
Mini-HOWTO</a>.
-</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-inittab"></a>AOLserver keepalive with inittab</h3></div></div><p>This is an alternative method for keeping the AOLserver
+</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-inittab"></a>AOLserver keepalive with inittab</h3></div></div><div></div></div><p>This is an alternative method for keeping the AOLserver
process running. The recommended method is to <a href="maintenance-web.html#install-openacs-keepalive" title="">run AOLserver
supervised</a>.</p><p>
This step should be completed as root. This can break every service
@@ -64,32 +63,32 @@
There are 2 general steps to getting this working.
</p><div class="orderedlist"><ol type="1"><li><p>
Install a script called
- <tt>restart-aolserver</tt>. This
+ <tt class="computeroutput">restart-aolserver</tt>. This
script doesn't actually restart AOLserver - it just kills
it.
</p></li><li><p>
Ask the OS to restart our service whenever it's not
running. We do this by adding a line to
- <tt>/etc/inittab</tt>.
+ <tt class="computeroutput">/etc/inittab</tt>.
</p></li></ol></div><p>
- Calling <tt>restart-aolserver</tt>
+ Calling <tt class="computeroutput">restart-aolserver</tt>
kills our service. The OS notices that our service is not
running, so it automatically restarts it. Thus, calling
- <tt>restart-aolserver</tt> effectively
+ <tt class="computeroutput">restart-aolserver</tt> effectively
restarts our service.
</p></li><li><p>
Copy this <a href="files/restart-aolserver.txt" target="_top">file</a> into
- <tt>/tmp/restart-aolserver.txt</tt>.
+ <tt class="computeroutput">/tmp/restart-aolserver.txt</tt>.
</p></li><li><p>
This script needs to be SUID-root, which means
that the script will run as root. This is necessary to ensure
that the AOLserver processes are killed regardless of who owns
them. However the script should be executable by the
- <tt>web</tt> group to ensure that the
+ <tt class="computeroutput">web</tt> group to ensure that the
users updating the web page can use the script, but that
general system users cannot run the script. You also need to
have Perl installed and also a symbolic link to it in
- <tt>/usr/local/bin</tt>.
+ <tt class="computeroutput">/usr/local/bin</tt>.
</p><pre class="programlisting">
joeuser:~$ su -
Password: ***********
@@ -98,76 +97,76 @@
root:~# chmod 4750 /usr/local/bin/restart-aolserver
root:~# ln -s /usr/bin/perl /usr/local/bin/perl
root:~# exit</pre></li><li><p>
- Test the <tt>restart-aolserver</tt>
+ Test the <tt class="computeroutput">restart-aolserver</tt>
script. We'll first kill all running servers to clean the
slate. Then, we'll start one server and use
- <tt>restart-aolserver</tt> to kill
+ <tt class="computeroutput">restart-aolserver</tt> to kill
it. If it works, then there should be no more servers
running. You should see the following lines. </p><pre class="programlisting">
joeuser:~$ killall nsd
nsd: no process killed
-joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl
+joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl
joeuser:~$ restart-aolserver <span class="emphasis"><em>birdnotes</em></span>
Killing 23727
joeuser:~$ killall nsd
nsd: no process killed</pre><p>
The number 23727 indicates the process id(s) (PIDs) of the
processes being killed. It is important that <span class="strong">no processes are killed</span> by the second
- call to <tt>killall</tt>. If there are
+ call to <tt class="computeroutput">killall</tt>. If there are
processes being killed, it means that the script is not
working.</p></li><li><p>
- Assuming that the <tt>restart-aolserver</tt>
+ Assuming that the <tt class="computeroutput">restart-aolserver</tt>
script worked, login as root and open
- <tt>/etc/inittab</tt> for
+ <tt class="computeroutput">/etc/inittab</tt> for
editing. </p><pre class="programlisting">
joeuser:~$ su -
Password: ************
root:~# emacs -nw /etc/inittab</pre></li><li><p>
Copy this line into the bottom of the file as a template,
making sure that the first field
- <tt>nss1</tt> is unique.
+ <tt class="computeroutput">nss1</tt> is unique.
</p><pre class="programlisting">
-nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/<span class="emphasis"><em>joeuser</em></span>/web/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl</pre></li><li><p>
+nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/<span class="emphasis"><em>joeuser</em></span>/var/lib/aolserver/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl</pre></li><li><p>
<span class="strong">Important:</span> 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.
</p></li><li><p>
Still as root, enter the following command to re-initialize
- <tt>/etc/inittab</tt>. </p><pre class="programlisting">
+ <tt class="computeroutput">/etc/inittab</tt>. </p><pre class="programlisting">
root:~# killall nsd
nsd: no process killed
root:~# /sbin/init q</pre></li><li><p>
See if it worked by running the
- <tt>restart-aolserver</tt> script
+ <tt class="computeroutput">restart-aolserver</tt> script
again. </p><pre class="programlisting">
root:~# restart-aolserver <span class="emphasis"><em>birdnotes</em></span>
Killing 23750</pre></li></ul></div><p>
If processes were killed, congratulations, your server is now
automated for startup and shutdown.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-port80"></a>Running AOLserver on Port 80</h3></div></div><p>If you want your webserver to be <tt>http://yourserver.com</tt>, it must run on port 80, the default HTTP port. You set this in the <tt>config.tcl</tt> file. You will need to start the service as
- <tt>root</tt>. If you follow the instructions
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-port80"></a>Running AOLserver on Port 80</h3></div></div><div></div></div><p>If you want your webserver to be <tt class="computeroutput">http://yourserver.com</tt>, it must run on port 80, the default HTTP port. You set this in the <tt class="computeroutput">config.tcl</tt> file. You will need to start the service as
+ <tt class="computeroutput">root</tt>. If you follow the instructions
above for <a href="maintenance-web.html#install-openacs-keepalive" title="">automating
startup</a>, this will be taken care of, but if you ever start the
- server from the command line, be sure to <tt>su
+ server from the command line, be sure to <tt class="computeroutput">su
-</tt> first.
</p><p>
Port 80 is a <span class="emphasis"><em>privileged</em></span> port. Only certain users
- can claim it. When you start <tt>nsd</tt> as
+ can claim it. When you start <tt class="computeroutput">nsd</tt> 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
- <tt>root</tt>. This mean that if someone was
+ <tt class="computeroutput">root</tt>. 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 <tt>root</tt>
- access.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-next-add-server"></a>Running multiple services on one machine</h3></div></div><p><b>Services on different ports.�</b>To run a different service on another port but the same
- ip, simply repeat <a href="openacs.html">Install OpenACS 5.0.0d</a> replacing
- <span class="replaceable">service0</span>, and change the
+ they would not be able to gain <tt class="computeroutput">root</tt>
+ access.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-next-add-server"></a>Running multiple services on one machine</h3></div></div><div></div></div><p><b>Services on different ports.�</b>To run a different service on another port but the same
+ ip, simply repeat <a href="openacs.html">Install OpenACS 5.0.0a1</a> replacing
+ <span class="replaceable"><span class="replaceable">service0</span></span>, and change the
</p><pre class="programlisting">set httpport 8000
set httpsport 8443 </pre><p>
to different values.</p><p><b>Services on different host names.�</b>For example, suppose you want to support
-<tt>http://foo.com</tt> and
- <tt>http://bar.com</tt> on the same
+<tt class="computeroutput">http://foo.com</tt> and
+ <tt class="computeroutput">http://bar.com</tt> on the same
machine. The easiest way is to assign each one a different ip
address. Then you can install two services as above, but with
different values for
@@ -177,62 +176,62 @@
names sharing the same ip, you'll need nsvhr to redirect requests
based on the contents of the tcp headers. See <a href="http://borkware.com/rants/aolserver-vhosting/" target="_top">AOLserver
Virtual Hosting with TCP</a> by <a href="mailto:markd@borkware.com" target="_top">markd</a>.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-ssl"></a>Installing SSL Support</h3></div></div><p>nsopenssl is an open-sounce module for Aolserver which
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-ssl"></a>Installing SSL Support</h3></div></div><div></div></div><p>nsopenssl is an open-sounce module for Aolserver which
adds support for the ssl encryption layer. To use it, you
must <a href="install-nsopenssl.html" title="Install nsopenssl">install</a> the software, create or purchase certificates,
- and configure your OpenACS instance to use it.</p><div class="orderedlist"><ol type="1"><li><p>Uncomment this line from <tt>config.tcl</tt>.</p><pre class="programlisting">#ns_param nsopenssl ${bindir}/nsopenssl.so
-</pre></li><li><p><a name="ssl-certificates"></a>Prepare a certificate directory for the service.</p><pre class="screen">[service0@yourserver etc]$ <b><tt>mkdir /web/<span class="replaceable">service0</span>/etc/certs</tt></b>
-[service0@yourserver etc]$ <b><tt>chmod 700 /web/<span class="replaceable">service0</span>/etc/certs</tt></b>
+ and configure your OpenACS instance to use it.</p><div class="orderedlist"><ol type="1"><li><p>Uncomment this line from <tt class="computeroutput">config.tcl</tt>.</p><pre class="programlisting">#ns_param nsopenssl ${bindir}/nsopenssl.so
+</pre></li><li><p><a name="ssl-certificates"></a>Prepare a certificate directory for the service.</p><pre class="screen">[service0@yourserver etc]$ <b class="userinput"><tt>mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/certs</tt></b>
+[service0@yourserver etc]$ <b class="userinput"><tt>chmod 700 /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/certs</tt></b>
[service0@yourserver etc]$
-<pre class="action">mkdir /web/<span class="replaceable">service0</span>/etc/certs
-chmod 700 /web/<span class="replaceable">service0</span>/etc/certs</pre></pre></li><li><p>It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.</p><p>Use an OpenSSL perl script to generate a certificate and key.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>cd /web/service0/etc/certs</tt></b>
-[service0@yourserver certs]$ <b><tt>perl /usr/share/ssl/misc/CA -newcert</tt></b>
+<pre class="action"><span class="action">mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/certs
+chmod 700 /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/certs</span></pre></pre></li><li><p>It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.</p><p>Use an OpenSSL perl script to generate a certificate and key.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>cd /var/lib/aolserver/service0/etc/certs</tt></b>
+[service0@yourserver certs]$ <b class="userinput"><tt>perl /usr/share/ssl/misc/CA -newcert</tt></b>
Using configuration from /usr/share/ssl/openssl.cnf
Generating a 1024 bit RSA private key
...++++++
.......++++++
writing new private key to 'newreq.pem'
Enter PEM pass phrase:</pre><p>Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this:</p><pre class="screen">Certificate (and private key) is in newreq.pem
-[service0@yourserver certs]$</pre><p><tt>newreq.pem</tt> contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. <span class="emphasis"><em>Security implication</em></span>: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.</p><pre class="screen">[root@yourserver misc]# <b><tt>openssl rsa -in newreq.pem -out keyfile.pem</tt></b>
+[service0@yourserver certs]$</pre><p><tt class="computeroutput">newreq.pem</tt> contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. <span class="emphasis"><em>Security implication</em></span>: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.</p><pre class="screen">[root@yourserver misc]# <b class="userinput"><tt>openssl rsa -in newreq.pem -out keyfile.pem</tt></b>
read RSA key
Enter PEM pass phrase:
writing RSA key
-[service0@yourserver certs]$ </pre><p>To create the certificate file, we take the combined file, copy it, and strip out the key.</p><pre class="screen">[service0@yourserver certs]$ <b><tt>cp newreq.pem certfile.pem</tt></b>
-[root@yourserver misc]# <b><tt>emacs certfile.pem</tt></b></pre><p>Strip out the section that looks like</p><pre class="programlisting">-----BEGIN RSA PRIVATE KEY-----
+[service0@yourserver certs]$ </pre><p>To create the certificate file, we take the combined file, copy it, and strip out the key.</p><pre class="screen">[service0@yourserver certs]$ <b class="userinput"><tt>cp newreq.pem certfile.pem</tt></b>
+[root@yourserver misc]# <b class="userinput"><tt>emacs certfile.pem</tt></b></pre><p>Strip out the section that looks like</p><pre class="programlisting">-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997
S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T
<span class="emphasis"><em>(11 lines omitted)</em></span>
1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw==
------END RSA PRIVATE KEY-----</pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="analog-setup"></a>Set up Log Analysis Reports - OPTIONAL</h3></div></div><p>Analog is a program with processes webserver access logs,
+-----END RSA PRIVATE KEY-----</pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="analog-setup"></a>Set up Log Analysis Reports - OPTIONAL</h3></div></div><div></div></div><p>Analog is a program with processes webserver access logs,
performs DNS lookup, and outputs HTML reports. Analog should
<a href="analog-install.html" title="Install Analog web file analyzer">already be
installed.</a> A modified configuration file is included in
- the OpenACS tarball.</p><div class="orderedlist"><ol type="1"><li><pre class="screen">[root@yourserver src]# <b><tt>su - service0</tt></b>
-[service0@yourserver service0]$ <b><tt>cd /web/service0</tt></b>
-[service0@yourserver service0]$ <b><tt>cp /web/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg</tt></b>
-[service0@yourserver service0]$ <b><tt>mkdir www/log</tt></b>
-[service0@yourserver service0]$ <b><tt>cp -r /usr/share/analog-5.31/images www/log/</tt></b>
-[service0@yourserver service0]$ <pre class="action">
+ the OpenACS tarball.</p><div class="orderedlist"><ol type="1"><li><pre class="screen">[root@yourserver src]# <b class="userinput"><tt>su - service0</tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cd /var/lib/aolserver/service0</tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg</tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>mkdir www/log</tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cp -r /usr/share/analog-5.31/images www/log/</tt></b>
+[service0@yourserver service0]$ <pre class="action"><span class="action">
su - service0
-cd /web/service0
-cp /web/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg
+cd /var/lib/aolserver/service0
+cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg
mkdir www/log
-cp -r /usr/share/analog-5.31/images www/log/</pre></pre><p>Edit
-<tt>/web/service0/etc/analog.cfg</tt> and change the variable in <tt>HOSTNAME "[my
-organisation]"</tt> to reflect your website title. If you
+cp -r /usr/share/analog-5.31/images www/log/</span></pre></pre><p>Edit
+<tt class="computeroutput">/var/lib/aolserver/service0/etc/analog.cfg</tt> and change the variable in <tt class="computeroutput">HOSTNAME "[my
+organisation]"</tt> to reflect your website title. If you
don't want the traffic log to be publicly visible, change
-<tt>OUTFILE /web/service0/www/log/traffic.html</tt> to use a private
-directory.</p></li><li><p>Run it.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>/usr/share/analog-5.31/analog -G -g/web/service0/etc/analog.cfg</tt></b>
+<tt class="computeroutput">OUTFILE /var/lib/aolserver/service0/www/log/traffic.html</tt> to use a private
+directory.</p></li><li><p>Run it.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>/usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg</tt></b>
/usr/share/analog-5.31/analog: analog version 5.31/Unix
/usr/share/analog-5.31/analog: Warning F: Failed to open DNS input file
/home/service0/dnscache: ignoring it
(For help on all errors and warnings, see docs/errors.html)
/usr/share/analog-5.31/analog: Warning R: Turning off empty Search Word Report
-[service0@yourserver service0]$</pre><p>Verify that it works by browing to <tt>http://yourserver.test:8000/log/traffic.html</tt></p></li><li><p>Automate this by creating a file in
- <tt>/etc/cron.daily</tt>.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
+[service0@yourserver service0]$</pre><p>Verify that it works by browing to <tt class="computeroutput">http://yourserver.test:8000/log/traffic.html</tt></p></li><li><p>Automate this by creating a file in
+ <tt class="computeroutput">/etc/cron.daily</tt>.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver root]# <b><tt>emacs /etc/cron.daily/analog</tt></b></pre><p>Put this into the file:</p><pre class="programlisting">#!/bin/sh
+[root@yourserver root]# <b class="userinput"><tt>emacs /etc/cron.daily/analog</tt></b></pre><p>Put this into the file:</p><pre class="programlisting">#!/bin/sh
-/usr/share/analog-5.31/analog -G -g/web/<span class="replaceable">service0</span>/etc/analog.cfg</pre><pre class="screen">[root@yourserver root]# <b><tt>chmod 755 /etc/cron.daily/analog</tt></b></pre><p>Test it by running the script.</p><pre class="screen">[root@yourserver root]# <b><tt>sh /etc/cron.daily/analog</tt></b></pre><p>Browse to <tt>http://<span class="replaceable">yourserver.test</span>/log/traffic.html</tt></p></li></ol></div></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�9.�Maintenance </td><td width="20%" align="center"><a accesskey="u" href="maintenance.html">Up</a></td><td width="40%" align="right"> Database Management</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/maintenance-web.html#comments">View comments on this page at openacs.org</a></center></body></html>
+/usr/share/analog-5.31/analog -G -g/var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/analog.cfg</pre><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>chmod 755 /etc/cron.daily/analog</tt></b></pre><p>Test it by running the script.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>sh /etc/cron.daily/analog</tt></b></pre><p>Browse to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>/log/traffic.html</tt></p></li></ol></div></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�9.�Maintenance </td><td width="20%" align="center"><a accesskey="u" href="maintenance.html">Up</a></td><td width="40%" align="right"> Database Management</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/maintenance-web.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/maintenance.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/maintenance.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/maintenance.html 20 Aug 2003 16:20:16 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/maintenance.html 14 Oct 2003 11:02:58 -0000 1.5
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�9.�Maintenance</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="upgrade-detail.html" title="Support for upgrades."><link rel="next" href="maintenance-web.html" title="Hosting Web Sites"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-detail.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="maintenance"></a>Chapter�9.�Maintenance</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="maintenance-web.html">Hosting Web Sites</a></dt><dt><a href="database-management.html">Database Management</a></dt><dt><a href="backup-recovery.html">Backup and Recovery</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-detail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr><tr><td width="40%" align="left">Support for upgrades. </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Hosting Web Sites</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/maintenance.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�9.�Maintenance</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="upgrade-detail.html" title="Support for upgrades."><link rel="next" href="maintenance-web.html" title="Hosting Web Sites"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-detail.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="maintenance"></a>Chapter�9.�Maintenance</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="maintenance-web.html">Hosting Web Sites</a></dt><dt><a href="database-management.html">Database Management</a></dt><dt><a href="backup-recovery.html">Backup and Recovery</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-detail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr><tr><td width="40%" align="left">Support for upgrades. </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Hosting Web Sites</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/maintenance.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/object-identity.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/object-identity.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/object-identity.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,20 +1,19 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Object Identity</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="permissions-tediously-explained.html" title="OpenACS 4.x Permissions Tediously Explained"><link rel="next" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-tediously-explained.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="object-identity"></a>Object Identity</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Object Identity</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="permissions-tediously-explained.html" title="OpenACS 4.x Permissions Tediously Explained"><link rel="next" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-tediously-explained.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-identity"></a>Object Identity</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><p>One of the major design features of OpenACS 5.0.0d is the explicit representation
-of <span class="emphasis"><em>object identity</em></span>. The reason I say "explicit
-representation" is because the concept of object identity has been
+ </p></div><p>One of the major design features of OpenACS 5.0.0a1 is the explicit representation
+of <span class="emphasis"><em>object identity</em></span>. The reason I say "explicit
+representation" is because the concept of object identity has been
around forever. It is inherent to our problem domain. Consider the example of
3.x style scoping. The 3.x data models use the triple (user_id, group_id,
-scope) to <span class="emphasis"><em>identify</em></span> an <span class="emphasis"><em>object</em></span>. In the 5.0.0d data model this
+scope) to <span class="emphasis"><em>identify</em></span> an <span class="emphasis"><em>object</em></span>. In the 5.0.0a1 data model this
object is <span class="emphasis"><em>explicitly represented</em></span> by a single party_id.</p><p>Another good example of this is can be found in the user groups data
model. The 3.x user groups data model contains another example of an
<span class="emphasis"><em>implied identity</em></span>. Every mapping between a user and a group could
have an arbitrary number of attached values (user_group_member_fields, etc.).
In this case it is the pair (group_id, user_id) that implicitly refers to an
-object (the person's membership in a group). In the 5.0.0d data model this
+object (the person's membership in a group). In the 5.0.0a1 data model this
object identity is made explicit by adding an integer primary key to the
table that maps users to groups.</p><p>Coming from a purely relational world, this might seem slightly weird at
first. The pair (group_id, user_id) is sufficient to uniquely identify the
Index: openacs-4/packages/acs-core-docs/www/object-system-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/object-system-design.html 30 Sep 2003 12:10:01 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/object-system-design.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,26 +1,25 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Object Model Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements"><link rel="next" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="object-system-design"></a>OpenACS 4 Object Model Design</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Object Model Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements"><link rel="next" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-system-design"></a>OpenACS 4 Object Model Design</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>,
<a href="mailto:mcyoon@arsdigita.com" target="_top">Michael Yoon</a>,
<a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>
and <a href="mailto:rhs@arsdigita.com" target="_top">Rafael Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-essentials"></a>Essentials</h3></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-data-model"></a>Data Model</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top">
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-data-model"></a>Data Model</h4></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top">
acs-metadata-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-objects-create.sql&package_key=acs-kernel" target="_top">
acs-objects-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-relationships-create.sql&package_key=acs-kernel" target="_top">
-acs-relationships-create.sql</a></p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-tcl-files"></a>Tcl Files</h4></div></div><p><span class="emphasis"><em>Not yet linked.</em></span></p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-requirements"></a>Requirements</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements">Object Model
+acs-relationships-create.sql</a></p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-tcl-files"></a>Tcl Files</h4></div></div><div></div></div><p><span class="emphasis"><em>Not yet linked.</em></span></p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-requirements"></a>Requirements</h4></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements">Object Model
Requirements</a></p></li><li><p><a href="groups-requirements.html" title="OpenACS 4 Groups Requirements">Groups
Requirements</a></p></li><li><p><a href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">Permissions
-Requirements</a></p></li></ul></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-introduction"></a>Introduction</h3></div></div><p>Before OpenACS 4, software developers writing OpenACS applications or modules
+Requirements</a></p></li></ul></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-introduction"></a>Introduction</h3></div></div><div></div></div><p>Before OpenACS 4, software developers writing OpenACS applications or modules
would develop each data model separately. However, many applications built on
OpenACS share certain characteristics or require certain common services.
Examples of such services include:</p><div class="itemizedlist"><ul type="disc"><li><p>User comments</p></li><li><p>Storage of user-defined or extensible sets of attributes</p></li><li><p>Access control</p></li><li><p>General auditing and bookkeeping (e.g. creation date, IP addresses, and
so forth)</p></li><li><p>Presentation tools (e.g. how to display a field in a form or on a
page)</p></li></ul></div><p>All of these services involve relating additional service-related
information to application data objects. Examples of application objects
include:</p><div class="itemizedlist"><ul type="disc"><li><p>Bboard messages</p></li><li><p>A user home page</p></li><li><p>A ticket in the ticket tracker</p></li></ul></div><p>In the past, developers had to use ad-hoc and inconsistent schemes to
-interface to various "general" services. OpenACS 4 defines a central
+interface to various "general" services. OpenACS 4 defines a central
data model that keeps track of the application objects that we wish to
manage, and serves as a primary store of <span class="emphasis"><em>metadata</em></span>. By
<span class="emphasis"><em>metadata</em></span>, we mean data stored on behalf of an application
@@ -37,54 +36,54 @@
object type (e.g. users) to instances of another object type (e.g.
groups).
</p></li></ul></div><p>The next section will explore these facilities in the context of the the
-particular programming idioms that we wish to generalize.</p><p><span class="strong">Related Links</span></p><p>This design document should be read along with the design documents for <a href="groups-design.html" title="OpenACS 4 Groups Design">the new groups system</a>, <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a> and <a href="permissions-design.html" title="OpenACS 4 Permissions Design">the permissions system</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-history"></a>History</h3></div></div><p>The motivation for most of the facilities in the OpenACS 4 Object Model can be
+particular programming idioms that we wish to generalize.</p><p><span class="strong">Related Links</span></p><p>This design document should be read along with the design documents for <a href="groups-design.html" title="OpenACS 4 Groups Design">the new groups system</a>, <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a> and <a href="permissions-design.html" title="OpenACS 4 Permissions Design">the permissions system</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-history"></a>History</h3></div></div><div></div></div><p>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.</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-object-ident"></a>Object Identification</h4></div></div><p>Object identification is a central mechanism in OpenACS 4. Every application
+idioms that evolved there. These are listed and discussed below.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-object-ident"></a>Object Identification</h4></div></div><div></div></div><p>Object identification is a central mechanism in OpenACS 4. Every application
object in OpenACS 4 has a unique ID which is mapped to a row in a central table
-called <tt>acs_objects</tt>. Developers that wish to use OpenACS 4 services
+called <tt class="computeroutput">acs_objects</tt>. Developers that wish to use OpenACS 4 services
need only take a few simple steps to make sure that their application objects
appear in this table. The fact that every object has a known unique
identifier means that the core can deal with all objects in a generic way. In
other words, we use object identifiers to enable centralized services in a
global and uniform manner.</p><p><span class="emphasis"><em>Implicit Object Identifiers in OpenACS 3.x</em></span></p><p>The motivation for implementing general object identifiers comes from
several observations of data models in OpenACS 3.x. Many modules use a
-<tt>(user_id, group_id, scope)</tt> column-triple for the purpose of
+<tt class="computeroutput">(user_id, group_id, scope)</tt> column-triple for the purpose of
recording ownership information on objects, for access control. User/groups
-also uses <tt>(user_id, group_id)</tt> pairs in its
-<tt>user_group_map</tt> table as a way to identify data associated with a
+also uses <tt class="computeroutput">(user_id, group_id)</tt> pairs in its
+<tt class="computeroutput">user_group_map</tt> table as a way to identify data associated with a
single membership relation.</p><p>Also, in OpenACS 3.x many utility modules exist that do nothing more than
attach some extra attributes to existing application data. For example,
-general comments maintains a table that maps application "page"
+general comments maintains a table that maps application "page"
data (static or dynamic pages on the website) to one or more user comments on
that page. It does so by constructing a unique identifier for each page,
usually a combination of the table in which the data is stored, and the value
of the primary key value for the particular page. This idiom is referred to
-as the "(on_which_table + on_what_id)" method for identifying
+as the "(on_which_table + on_what_id)" method for identifying
application data. In particular, general comments stores its map from pages
-to comments using a "(on_which_table + on_what_id)" key plus the ID
+to comments using a "(on_which_table + on_what_id)" key plus the ID
of the comment itself.</p><p>All of these composite key constructions are implicit object identifiers -
they build a unique ID out of other pieces of the data model. The problem is
that their definition and use is ad-hoc and inconsistent, making the
construction of generic application-independent services unnecessarily
difficult.</p><p><span class="emphasis"><em>Object Identifiers in OpenACS 4</em></span></p><p>The OpenACS 4 Object Model defines a single mechanism that applications use to
attach unique identifiers to application data. This identifier is the primary
-key of the <tt>acs_objects</tt> table. This table forms the core of what
+key of the <tt class="computeroutput">acs_objects</tt> table. This table forms the core of what
we need to provide generic services like access control, general attribute
storage, general presentation and forms tools, and generalized administrative
interfaces. In addition, the object system provides an API that makes it easy
to create new objects when creating application data. All an application must
do to take advantage of general services in OpenACS 4 is to use the new API to
make sure every object the system is to manage is associated with a row in
-<tt>acs_objects</tt>. More importantly, if they do this, new services
+<tt class="computeroutput">acs_objects</tt>. 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.</p><p><span class="strong">Note:</span> Object identifiers are a good example of metadata
-in the new system. Each row in <tt>acs_objects</tt> stores information
+to "hook into" them via new metadata.</p><p><span class="strong">Note:</span> Object identifiers are a good example of metadata
+in the new system. Each row in <tt class="computeroutput">acs_objects</tt> stores information
<span class="emphasis"><em>about</em></span> 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.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-obj-context"></a>Object Context and Access Control</h4></div></div><p>Until the implementation of the general permissions system, every OpenACS
+that defines this table.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-obj-context"></a>Object Context and Access Control</h4></div></div><div></div></div><p>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.</p><p>"Scope" is a term best explained by example. Consider some
-hypothetical rows in the <tt>address_book</tt> table:</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="strong">...</span></td><td><span class="strong"><tt>scope</tt></span></td><td><span class="strong"><tt>user_id</tt></span></td><td><span class="strong"><tt>group_id</tt></span></td><td><span class="strong">...</span></td></tr><tr><td>...</td><td><tt>user</tt></td><td><tt>123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt>group</tt></td><td>�</td><td><tt>456</tt></td><td>...</td></tr><tr><td>...</td><td><tt>public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote></div><p>The first row represents an entry in User 123's personal address book,
+notion of "scoping" was introduced into the core data model.</p><p>"Scope" is a term best explained by example. Consider some
+hypothetical rows in the <tt class="computeroutput">address_book</tt> table:</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="strong">...</span></td><td><span class="strong"><tt class="computeroutput">scope</tt></span></td><td><span class="strong"><tt class="computeroutput">user_id</tt></span></td><td><span class="strong"><tt class="computeroutput">group_id</tt></span></td><td><span class="strong">...</span></td></tr><tr><td>...</td><td><tt class="computeroutput">user</tt></td><td><tt class="computeroutput">123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt class="computeroutput">group</tt></td><td>�</td><td><tt class="computeroutput">456</tt></td><td>...</td></tr><tr><td>...</td><td><tt class="computeroutput">public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote></div><p>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.</p><p>In this way, the scoping columns identify the security context in which a
@@ -98,29 +97,29 @@
bboard message would probably list a bboard topic as its context, and a
bboard topic might list a subsite as its context. Thus, contexts make it
easier to break the site up into security domains according to its natural
-structure. An object's context is stored in the <tt>context_id</tt>
-column of the <tt>acs_objects</tt> table.</p><p>We use an object's context to provide a default answer to questions
-regarding access control. Whenever we ask a question of the form "can
-user X perform action Y on object Z", the OpenACS security model will defer
+structure. An object's context is stored in the <tt class="computeroutput">context_id</tt>
+column of the <tt class="computeroutput">acs_objects</tt> table.</p><p>We use an object's context to provide a default answer to questions
+regarding access control. Whenever we ask a question of the form "can
+user X perform action Y on object Z", the OpenACS security model will defer
to an object's context if there is no information about user X's
permission to perform action Y on object Z.</p><p>The context system forms the basis for the rest of the OpenACS access control
system, which is described in in two separate documents: one for the <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions system</a> and another for the
<a href="groups-design.html" title="OpenACS 4 Groups Design">party groups</a> system. The context system
-is also used to implement <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-obj-types"></a>Object Types</h4></div></div><p>As mentioned above, many OpenACS modules provide extensible data models, and
+is also used to implement <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-obj-types"></a>Object Types</h4></div></div><div></div></div><p>As mentioned above, many OpenACS modules provide extensible data models, and
need to use application specific mechanisms to keep track of user defined
attributes and to map application data to these attributes. In the past,
modules either used user/groups or their own ad hoc data model to provide
this functionality.</p><p><span class="emphasis"><em>User/Groups in OpenACS 3.x</em></span></p><p>The user/group system allowed developers to define <span class="emphasis"><em>group types</em></span>
along with attributes to be stored with each instance of a group type. Each
group type could define a helper table that stored attributes on each
instance of the group type. This table was called the
-"<tt>_info</tt>" table because the name was generated by
-appending <tt>_info</tt> to the name of the group type.</p><p>The user/groups data model also provided the
-<tt>user_group_type_member_fields</tt> and
-<tt>user_group_member_fields</tt> tables to define attributes for members
+"<tt class="computeroutput">_info</tt>" table because the name was generated by
+appending <tt class="computeroutput">_info</tt> to the name of the group type.</p><p>The user/groups data model also provided the
+<tt class="computeroutput">user_group_type_member_fields</tt> and
+<tt class="computeroutput">user_group_member_fields</tt> tables to define attributes for members
of groups of a specific type and for members of a specific group,
-respectively. The <tt>user_group_member_field_map</tt> table stored
-values for both categories of attributes in its <tt>field_value</tt>
+respectively. The <tt class="computeroutput">user_group_member_field_map</tt> table stored
+values for both categories of attributes in its <tt class="computeroutput">field_value</tt>
column. These tables allowed developers and users to define custom sets of
attributes to store on groups and group members without changing the data
model at the code level.</p><p>Many applications in OpenACS 3.x and earlier used the group type mechanism in
@@ -135,39 +134,39 @@
The motivation for subtypes comes from the need for OpenACS to be more
extensible. In OpenACS 3.x, many applications extended the core data models by
directly adding more columns, in order to provide convenient access to new
-information. This resulted in core data tables that were too "fat",
+information. This resulted in core data tables that were too "fat",
containing a hodge podge of unrelated information that should have been
normalized away. The canonical example of this is the explosion of the
-<tt>users</tt> table in OpenACS 3.x. In addition to being sloppy technically,
+<tt class="computeroutput">users</tt> table in OpenACS 3.x. In addition to being sloppy technically,
these fat tables have a couple of other problems:</p><div class="itemizedlist"><ul type="disc"><li><p>They degrade performance.</p></li><li><p>Denormalization can make it hard to maintain consistency constraints on
the data.</p></li></ul></div><p>Object subtypes provide a way to factor the data model while still keeping
track of the fact that each member of a subtype (i.e. for each row in the
subtype's table), is also a member of the parent type (i.e. there is a
corresponding row in the parent type table). Therefore, applications an use
this mechanism without worrying about this bookkeeping themselves, and we
avoid having applications pollute the core data model with their specific
-information.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-attributes"></a>Object Attributes, Skinny Tables</h4></div></div><p>As we described above, the OpenACS 3.x user/groups system stored object
+information.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-attributes"></a>Object Attributes, Skinny Tables</h4></div></div><div></div></div><p>As we described above, the OpenACS 3.x user/groups system stored object
attributes in two ways. The first was to use columns in the helper table. The
second consisted of two tables, one describing attributes and one storing
values, to provide a flexible means for attaching attributes to metadata
objects. This style of attribute storage is used in several other parts of
-OpenACS 3.x, and we will refer to it as "skinny tables". For
-example:</p><div class="itemizedlist"><ul type="disc"><li><p>In the Ecommerce data model, the <tt>ec_custom_product_fields</tt>
+OpenACS 3.x, and we will refer to it as "skinny tables". For
+example:</p><div class="itemizedlist"><ul type="disc"><li><p>In the Ecommerce data model, the <tt class="computeroutput">ec_custom_product_fields</tt>
table defines attributes for catalog products, and the
-<tt>ec_custom_product_field_values</tt> table stores values for those
-attributes.</p></li><li><p>In the Photo DB data model, the <tt>ph_custom_photo_fields</tt> table
+<tt class="computeroutput">ec_custom_product_field_values</tt> table stores values for those
+attributes.</p></li><li><p>In the Photo DB data model, the <tt class="computeroutput">ph_custom_photo_fields</tt> table
defines attributes for the photographs owned by a specific user, and tables
named according to the convention
-"<tt>ph_user_<user_id>_custom_info</tt>" are used to
+"<tt class="computeroutput">ph_user_<user_id>_custom_info</tt>" are used to
store values for those attributes.</p></li></ul></div><p>In addition, there are some instances where we are not using this model
-but <span class="emphasis"><em>should</em></span>, e.g. the <tt>users_preferences</tt> table, which
+but <span class="emphasis"><em>should</em></span>, e.g. the <tt class="computeroutput">users_preferences</tt> table, which
stores preferences for registered users in columns such as
-<tt>prefer_text_only_p</tt> and <tt>dont_spam_me_p</tt>. The
-"standard" way for an OpenACS 3.x-based application to add to the list
-of user preferences is to add a column to the <tt>users_preferences</tt>
+<tt class="computeroutput">prefer_text_only_p</tt> and <tt class="computeroutput">dont_spam_me_p</tt>. The
+"standard" way for an OpenACS 3.x-based application to add to the list
+of user preferences is to add a column to the <tt class="computeroutput">users_preferences</tt>
table (exactly the kind of data model change that has historically
complicated the process of upgrading to a more recent OpenACS version).</p><p>The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups
-system. It defines a table called <tt>acs_attributes</tt> that record
+system. It defines a table called <tt class="computeroutput">acs_attributes</tt> that record
what attributes belong to which object types, and how the attributes are
stored. As before, attributes can either be stored in helper tables, or in a
single central skinny table. The developer makes this choice on a case by
@@ -177,53 +176,53 @@
skinny tables because doing so allows developers and users to dynamically
update the set of attributes stored on an object without updating the data
model at the code level. The bottom line: Helper tables are more functional
-and more efficient, skinny tables are more flexible but limited.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-relation-types"></a>Relation Types</h4></div></div><p>Many OpenACS 3.x modules use <span class="emphasis"><em>mapping tables</em></span> to model relationships
+and more efficient, skinny tables are more flexible but limited.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-relation-types"></a>Relation Types</h4></div></div><div></div></div><p>Many OpenACS 3.x modules use <span class="emphasis"><em>mapping tables</em></span> to model relationships
between application objects. Again, the 3.x user/groups system provides the
canonical example of this design style. In that system, there was a single
-table called <tt>user_group_map</tt> that kept track of which users
+table called <tt class="computeroutput">user_group_map</tt> that kept track of which users
belonged to what groups. In addition, as we discussed in the previous
-section, the system used the <tt>user_group_member_fields</tt> and
-<tt>user_group_member_fields_map</tt> tables to allow developers to
+section, the system used the <tt class="computeroutput">user_group_member_fields</tt> and
+<tt class="computeroutput">user_group_member_fields_map</tt> tables to allow developers to
attach custom attributes to group members. In fact, these attributes were not
really attached to the users, but to the fact that a user was a member of a
particular group - a subtle but important distinction.</p><p>In OpenACS 4, <span class="emphasis"><em>relation types</em></span> generalize this mechanism. Relation
types allow developers to define general mappings from objects of a given
type T, to other objects of a given type R. Each relation type is a subtype
-of <tt>acs_object</tt>, extended with extra attributes that store
+of <tt class="computeroutput">acs_object</tt>, extended with extra attributes that store
constraints on the relation, and the types of objects the relation actually
maps. In turn, each instance of a relation type is an object that represents
-a single fact of the form "the object t of type T is related to the
-object r of type R." That is, each instance of a relation type is
+a single fact of the form "the object t of type T is related to the
+object r of type R." That is, each instance of a relation type is
essentially just a pair of objects.</p><p>Relation types generalize mapping tables. For example, the 3.x user/groups
data model can be largely duplicated using a single relation type describing
-the "group membership" relation. Group types would then be subtypes
+the "group membership" relation. Group types would then be subtypes
of this membership relation type. Group type attributes would be attached to
the relation type itself. Group member attributes would be attached to
instances of the membership relation. Finally, the mapping table would be
replaced by a central skinny table that the relation type system defines.</p><p>Relation types should be used when you want to be able to attach data to
-the "fact" that object X and object Y are related to each other. On
+the "fact" that object X and object Y are related to each other. On
the face of it, they seem like a redundant mechanism however, since one could
easily create a mapping table to do the same thing. The advantage of
registering this table as a relation type is that in principle the OpenACS 4
object system could use the meta data in the types table to do useful things
in a generic way on all relation types. But this mechanism doesn't really
exist yet.</p><p>Relation types are a somewhat abstract idea. To get a better feel for
-them, you should just skip to the <a href="object-system-design.html#object-system-design-relsmodel">data model</a>.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-summary"></a>Summary and Design Considerations</h3></div></div><p>The OpenACS 4 Object Model is designed to generalize and unify the following
+them, you should just skip to the <a href="object-system-design.html#object-system-design-relsmodel">data model</a>.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-summary"></a>Summary and Design Considerations</h3></div></div><div></div></div><p>The OpenACS 4 Object Model is designed to generalize and unify the following
mechanisms that are repeatedly implemented in OpenACS-based systems to manage
-generic and application specific metadata:</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-why-not-objdb"></a>Why not Object Databases?</h4></div></div><p>The presence of a framework for subtyping and inheritance always brings up
+generic and application specific metadata:</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-why-not-objdb"></a>Why not Object Databases?</h4></div></div><div></div></div><p>The presence of a framework for subtyping and inheritance always brings up
the question of why we don't just use an object database. The main reason
is that all of the major object database vendors ship products that are
effectively tied to some set of object oriented programming languages. Their
idea is to provide tight language-level integration to lower the
-"impedance mismatch" between the database and the language.
+"impedance mismatch" between the database and the language.
Therefore, database objects and types are generally directly modeled on
language level objects and types. Of course, this makes it nearly impossible
to interact with the database from a language that does not have this tight
coupling, and it limits the data models that we can write to ideas that are
expressible in the host language. In particular, we lose many of the best
features of the relational database model. This is a disaster from an ease of
use standpoint.
- </p><p>The "Object relational" systems provide an interesting
+ </p><p>The "Object relational" systems provide an interesting
alternative. Here, some notion of subtyping is embedded into an existing SQL
or SQL-like database engine. Examples of systems like this include the new
Informix, PostgreSQL 7, and Oracle has something like this too. The main
@@ -234,7 +233,7 @@
practice. Finally, object databases are not as widely used as traditional
relational systems. They have not been tested as extensively and their
scalability to very large databases is not proven (though some will disagree
-with this statement).</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-oracle"></a>Oracle</h4></div></div><p>The conclusion: the best design is to add a limited notion of subtyping to
+with this statement).</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-oracle"></a>Oracle</h4></div></div><div></div></div><p>The conclusion: the best design is to add a limited notion of subtyping to
our existing relational data model. By doing this, we retain all the power of
the relational data model while gaining the object oriented features we need
most.</p><p>In the context of OpenACS 4, this means using the object model to make our
@@ -247,7 +246,7 @@
designed to support, for example, a huge type tree like the Java runtime
libraries might define.</p><p>This last point cannot be over-stressed: <span class="strong">the object model is not
meant to be used for large scale application data storage</span>. It is
-meant to represent and store metadata, not application data.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-datamodel"></a>Data Model</h3></div></div><p>Like most data models, the OpenACS Core data model has two levels:</p><div class="orderedlist"><ol type="1"><li><p>The <span class="emphasis"><em>knowledge level</em></span> (i.e. the metadata model)</p></li><li><p>The <span class="emphasis"><em>operational level</em></span> (i.e. the concrete data model)</p></li></ol></div><p>
+meant to represent and store metadata, not application data.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-datamodel"></a>Data Model</h3></div></div><div></div></div><p>Like most data models, the OpenACS Core data model has two levels:</p><div class="orderedlist"><ol type="1"><li><p>The <span class="emphasis"><em>knowledge level</em></span> (i.e. the metadata model)</p></li><li><p>The <span class="emphasis"><em>operational level</em></span> (i.e. the concrete data model)</p></li></ol></div><p>
You can browse the data models themselves from here:
</p><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top">
acs-metadata-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-objects-create.sql&package_key=acs-kernel" target="_top">
@@ -258,12 +257,12 @@
the SQL definitions of many tables. Generally, these match the actual
definitions in the existing data model but they are meant to reflect design
information, not implementation. Some less relevant columns may be left out,
-and things like constraint names are not included.</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-knowledge-level"></a>Knowledge-Level Model</h4></div></div><p>The knowledge level data model for OpenACS objects centers around three tables
+and things like constraint names are not included.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-knowledge-level"></a>Knowledge-Level Model</h4></div></div><div></div></div><p>The knowledge level data model for OpenACS objects centers around three tables
that keep track of object types, attributes, and relation types. The first
-table is <tt>acs_object_types</tt>, shown here in an abbreviated
+table is <tt class="computeroutput">acs_object_types</tt>, shown here in an abbreviated
form:</p><pre class="programlisting">
-<tt>create table acs_object_types (
+<tt class="computeroutput">create table acs_object_types (
object_type varchar(100) not null primary key,
supertype references acs_object_types (object_type),
abstract_p char(1) default 'f' not null
@@ -278,22 +277,22 @@
</pre><p>This table contains one row for every object type in the system. The key
things to note about this table are:</p><div class="itemizedlist"><ul type="disc"><li><p>For every type, we store metadata for how to display this type in certain
-contexts (<tt>pretty_name</tt> and <tt>pretty_plural</tt>).</p></li><li><p>If the type is a subtype, then its parent type is stored in the column
-<tt>supertype</tt>.</p></li><li><p>We support a notion of "abstract" types that contain no
+contexts (<tt class="computeroutput">pretty_name</tt> and <tt class="computeroutput">pretty_plural</tt>).</p></li><li><p>If the type is a subtype, then its parent type is stored in the column
+<tt class="computeroutput">supertype</tt>.</p></li><li><p>We support a notion of "abstract" types that contain no
instances (as of 9/2000 this is not actually used). These types exist only to
-be subtyped. An example might be a type representing "shapes" that
+be subtyped. An example might be a type representing "shapes" that
contains common characteristics of all shapes, but which is only used to
create subtypes that represent real, concrete shapes like circles, squares,
and so on.</p></li><li><p>Every type defines a table in which one can find one row for every
-instance of this type (<tt>table_name</tt>, <tt>id_column</tt>).</p></li><li><p><tt>type_extension_table</tt> is for naming a table that stores extra
-generic attributes.</p></li></ul></div><p>The second table we use to describe types is <tt>acs_attributes</tt>.
+instance of this type (<tt class="computeroutput">table_name</tt>, <tt class="computeroutput">id_column</tt>).</p></li><li><p><tt class="computeroutput">type_extension_table</tt> is for naming a table that stores extra
+generic attributes.</p></li></ul></div><p>The second table we use to describe types is <tt class="computeroutput">acs_attributes</tt>.
Each row in this table represents a single attribute on a specific object
-type (e.g. the "password" attribute of the "user" type).
+type (e.g. the "password" attribute of the "user" type).
Again, here is an abbreviated version of what this table looks like. The
actual table used in the implementation is somewhat different and is
discussed in a separate document.</p><pre class="programlisting">
-<tt>create table acs_attributes (
+<tt class="computeroutput">create table acs_attributes (
attribute_id integer not null primary key
object_type not null references acs_object_types (object_type),
attribute_name varchar(100) not null,
@@ -312,35 +311,35 @@
</tt>
</pre><p>The following points are important about this table:</p><div class="itemizedlist"><ul type="disc"><li><p>Every attribute has a unique identifier.</p></li><li><p>Every attribute is associated with an object type.</p></li><li><p>We store various things about each attribute for presentation
-(<tt>pretty_name</tt>, <tt>sort_order</tt>).</p></li><li><p>The <tt>data_type</tt> column stores type information on this
+(<tt class="computeroutput">pretty_name</tt>, <tt class="computeroutput">sort_order</tt>).</p></li><li><p>The <tt class="computeroutput">data_type</tt> column stores type information on this
attribute. This is not the SQL type of the attribute; it is just a human
readable name for the type of data we think the attribute holds (e.g.
-"String", or "Money"). This might be used later to
-generate a user interface.</p></li><li><p>The <tt>sort_order</tt> column stores information about how to sort
-the attribute values.</p></li><li><p>Attributes can either be stored explicitly in a table ("type
-specific storage") or in a skinny table ("generic storage").
+"String", or "Money"). This might be used later to
+generate a user interface.</p></li><li><p>The <tt class="computeroutput">sort_order</tt> column stores information about how to sort
+the attribute values.</p></li><li><p>Attributes can either be stored explicitly in a table ("type
+specific storage") or in a skinny table ("generic storage").
In most cases, an attribute maps directly to a column in the table identified
-by the <tt>table_name</tt> of the corresponding object type, although, as
+by the <tt class="computeroutput">table_name</tt> of the corresponding object type, although, as
mentioned above, we sometimes store attribute values as key-value pairs in a
-"skinny" table. However, when you ask the question "What are
-the attributes of this type of object?", you don't really care about
+"skinny" table. However, when you ask the question "What are
+the attributes of this type of object?", you don't really care about
how the values for each attribute are stored (in a column or as key-value
-pairs); you expect to receive the complete list of all attributes.</p></li><li><p>The <tt>max_n_values</tt> and <tt>min_n_values</tt> columns
+pairs); you expect to receive the complete list of all attributes.</p></li><li><p>The <tt class="computeroutput">max_n_values</tt> and <tt class="computeroutput">min_n_values</tt> columns
encode information about the number of values an attribute may hold.
-Attributes can be defined to hold 0 or more total values.</p></li><li><p>The <tt>static_p</tt> flag indicates whether this attribute value is
+Attributes can be defined to hold 0 or more total values.</p></li><li><p>The <tt class="computeroutput">static_p</tt> flag indicates whether this attribute value is
shard by all instances of a type, as with static member fields in C++. Static
attribute are like group level attributes in OpenACS 3.x.</p></li></ul></div><p>The final part of the knowledge level model keeps track of relationship
types. We said above that object relationships are used to generalize the 3.x
notion of <span class="emphasis"><em>group member fields</em></span>. These were fields that a developer
could store on each member of a group, but which were contextualized to the
-membership relation. That is, they were really "attached" to the
+membership relation. That is, they were really "attached" to the
fact that a user was a member of a particular group, and not really attached
to the user. This is a subtle but important distinction, because it allowed
the 3.x system to store multiple sets of attributes on a given user, one set
for each group membership relation in which they participated.</p><p>In OpenACS 4, this sort of data can be stored as a relationship type, in <a name="object-system-design-relsmodel"></a>
-<tt>acs_rel_types</tt>. The key parts of this table look like this:</p><pre class="programlisting">
+<tt class="computeroutput">acs_rel_types</tt>. The key parts of this table look like this:</p><pre class="programlisting">
-<tt>create table acs_rel_types (
+<tt class="computeroutput">create table acs_rel_types (
rel_type varchar(100) not null
references acs_object_types(object_type),
object_type_one not null
@@ -357,28 +356,28 @@
</tt>
</pre><p>Things to note about this table:</p><div class="itemizedlist"><ul type="disc"><li><p>The main part of this table records the fact that the relation is between
-instances of <tt>object_type_one</tt> and instances of
-<tt>object_type_two</tt>. Therefore, each instance of this relation type
-will be a pair of objects of the appropriate types.</p></li><li><p>The <tt>role</tt> columns store human readable names for the roles
-played by each object in the relation (e.g. "employee" and
-"employer"). Each role must appear in the
-<tt>acs_rel_roles</tt>.</p></li><li><p>The <tt>min_n_rels_one</tt> column, and its three friends allow the
+instances of <tt class="computeroutput">object_type_one</tt> and instances of
+<tt class="computeroutput">object_type_two</tt>. Therefore, each instance of this relation type
+will be a pair of objects of the appropriate types.</p></li><li><p>The <tt class="computeroutput">role</tt> columns store human readable names for the roles
+played by each object in the relation (e.g. "employee" and
+"employer"). Each role must appear in the
+<tt class="computeroutput">acs_rel_roles</tt>.</p></li><li><p>The <tt class="computeroutput">min_n_rels_one</tt> column, and its three friends allow the
programmer to specify constraints on how many objects any given object can be
-related to on either side of the relation.</p></li></ul></div><p>This table is easier to understand if you also know how the <a href="object-system-design.html#object-system-design-acs-rels"><tt>acs_rels</tt> table</a> works.</p><p>To summarize, the <tt>acs_object_types</tt> and
-<tt>acs_attributes</tt> tables store metadata that describes every object
+related to on either side of the relation.</p></li></ul></div><p>This table is easier to understand if you also know how the <a href="object-system-design.html#object-system-design-acs-rels"><tt class="computeroutput">acs_rels</tt> table</a> works.</p><p>To summarize, the <tt class="computeroutput">acs_object_types</tt> and
+<tt class="computeroutput">acs_attributes</tt> tables store metadata that describes every object
type and attribute in the system. These tables generalize the group types
-data model in OpenACS 3.x. The <tt>acs_rel_types</tt> table stores
+data model in OpenACS 3.x. The <tt class="computeroutput">acs_rel_types</tt> table stores
information about relation types.</p><p>This part of the data model is somewhat analogous to the data dictionary
in Oracle. The information stored here is primarily metadata that describes
the data stored in the <a href="object-system-design.html#objects-design-op-level" title="Operational-level Data Model">operational level</a> of the data
-model, which is discussed next.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-op-level"></a>Operational-level Data Model</h4></div></div><p>The operational level data model centers around the
-<tt>acs_objects</tt> table. This table contains a single row for every
-instance of the type <tt>acs_object</tt>. The table contains the
+model, which is discussed next.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-op-level"></a>Operational-level Data Model</h4></div></div><div></div></div><p>The operational level data model centers around the
+<tt class="computeroutput">acs_objects</tt> table. This table contains a single row for every
+instance of the type <tt class="computeroutput">acs_object</tt>. The table contains the
object's unique identifier, a reference to its type, security
information, and generic auditing information. Here is what the table looks
like:</p><pre class="programlisting">
-<tt>create table acs_objects (
+<tt class="computeroutput">create table acs_objects (
object_id integer not null,
object_type not null
references acs_object_types (object_type),
@@ -396,15 +395,15 @@
</pre><p>As we said in Section III, security contexts are hierarchical and also
modeled as objects. There is another table called
-<tt>acs_object_context_index</tt> that stores the context hierarchy.</p><p>Other tables in the core data model store additional information related
-to objects. The table <tt>acs_attribute_values</tt> and
-<tt>acs_static_attr_values</tt> are used to store attribute values that
+<tt class="computeroutput">acs_object_context_index</tt> that stores the context hierarchy.</p><p>Other tables in the core data model store additional information related
+to objects. The table <tt class="computeroutput">acs_attribute_values</tt> and
+<tt class="computeroutput">acs_static_attr_values</tt> are used to store attribute values that
are not stored in a helper table associated with the object's type. The
former is used for instance attributes while the latter is used for
-class-wide "static" values. These tables have the same basic form,
+class-wide "static" values. These tables have the same basic form,
so we'll only show the first:</p><pre class="programlisting">
-<tt>create table acs_attribute_values (
+<tt class="computeroutput">create table acs_attribute_values (
object_id not null
references acs_objects (object_id) on delete cascade,
attribute_id not null
@@ -414,10 +413,10 @@
);
</tt>
-</pre><p>Finally, the table <tt>acs_rels</tt> <a name="object-system-design-acs-rels"></a>is used to store object pairs
+</pre><p>Finally, the table <tt class="computeroutput">acs_rels</tt> <a name="object-system-design-acs-rels"></a>is used to store object pairs
that are instances of a relation type.</p><pre class="programlisting">
-<tt>create table acs_rels (
+<tt class="computeroutput">create table acs_rels (
rel_id not null
references acs_objects (object_id)
primary key
@@ -431,31 +430,31 @@
);
</tt>
-</pre><p>This table is somewhat subtle:</p><div class="itemizedlist"><ul type="disc"><li><p><tt>rel_id</tt> is the ID of an <span class="emphasis"><em>instance</em></span> of some relation
+</pre><p>This table is somewhat subtle:</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput">rel_id</tt> is the ID of an <span class="emphasis"><em>instance</em></span> of some relation
type. We do this so we can store all the mapping tables in this one
-table.</p></li><li><p><tt>rel_type</tt> is the ID of the relation type to which this object
+table.</p></li><li><p><tt class="computeroutput">rel_type</tt> is the ID of the relation type to which this object
belongs.</p></li><li><p>The next two object IDs are the IDs of the objects being mapped.</p></li></ul></div><p>All this table does is store one row for every pair of objects that
we'd like to attach with a relation. Any additional attributes that
we'd like to attach to this pair of objects is specified in the
attributes of the relation type, and could be stored in any number of places.
As in the 3.x user/groups system, these places include helper tables or
-generic skinny tables.</p><p>This table, along with <tt>acs_attributes</tt> and
-<tt>acs_attribute_values</tt> generalize the old user/group tables
-<tt>user_group_map</tt>, <tt>user_group_member_fields_map</tt> and
-<tt>user_group_member_fields</tt>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-discussion"></a>Summary and Discussion</h4></div></div><p>The core tables in the OpenACS 4 data model store information about instances
-of object types and relation types. The <tt>acs_object</tt> table
+generic skinny tables.</p><p>This table, along with <tt class="computeroutput">acs_attributes</tt> and
+<tt class="computeroutput">acs_attribute_values</tt> generalize the old user/group tables
+<tt class="computeroutput">user_group_map</tt>, <tt class="computeroutput">user_group_member_fields_map</tt> and
+<tt class="computeroutput">user_group_member_fields</tt>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-discussion"></a>Summary and Discussion</h4></div></div><div></div></div><p>The core tables in the OpenACS 4 data model store information about instances
+of object types and relation types. The <tt class="computeroutput">acs_object</tt> table
provides the central location that contains a single row for every object in
the system. Services can use this table along with the metadata in stored in
the knowledge level data model to create, manage, query and manipulate
-objects in a uniform manner. The <tt>acs_rels</tt> table has an analogous
+objects in a uniform manner. The <tt class="computeroutput">acs_rels</tt> table has an analogous
role in storing information on relations.</p><p>These are all the tables that we'll discuss in this document. The rest
of the Kernel data model is described in the documents for <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>, the <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a> system and for the <a href="groups-design.html" title="OpenACS 4 Groups Design">groups</a> system.</p><p>Some examples of how these tables are used in the system can be found in
-the discussion of the API, which comes next.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-api"></a>API</h3></div></div><p>Now we'll examine each piece of the API in detail. Bear in mind that
-the Object Model API is defined primarily through PL/SQL packages.</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-object-types"></a>Object Types and Attributes</h4></div></div><p>The object system provides an API for creating new object types and then
-attaching attributes to them. The procedures <tt>create_type</tt> and
-<tt>drop_type</tt> are used to create and delete type definitions.</p><p>The two calls show up in the package <tt>acs_object_type</tt>.</p><pre class="programlisting">
+the discussion of the API, which comes next.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-api"></a>API</h3></div></div><div></div></div><p>Now we'll examine each piece of the API in detail. Bear in mind that
+the Object Model API is defined primarily through PL/SQL packages.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-object-types"></a>Object Types and Attributes</h4></div></div><div></div></div><p>The object system provides an API for creating new object types and then
+attaching attributes to them. The procedures <tt class="computeroutput">create_type</tt> and
+<tt class="computeroutput">drop_type</tt> are used to create and delete type definitions.</p><p>The two calls show up in the package <tt class="computeroutput">acs_object_type</tt>.</p><pre class="programlisting">
-<tt> procedure create_type (
+<tt class="computeroutput"> procedure create_type (
object_type in acs_object_types.object_type%TYPE,
pretty_name in acs_object_types.pretty_name%TYPE,
pretty_plural in acs_object_types.pretty_plural%TYPE,
@@ -476,11 +475,11 @@
);
</tt>
-</pre><p>Here the <tt>cascade_p</tt> argument indicates whether dropping a type
+</pre><p>Here the <tt class="computeroutput">cascade_p</tt> argument indicates whether dropping a type
should also remove all its subtypes from the system.</p><p>We define a similar interface for defining attributes in the package
-<tt>acs_attribute</tt>:</p><pre class="programlisting">
+<tt class="computeroutput">acs_attribute</tt>:</p><pre class="programlisting">
-<tt> function create_attribute (
+<tt class="computeroutput"> function create_attribute (
object_type in acs_attributes.object_type%TYPE,
attribute_name in acs_attributes.attribute_name%TYPE,
datatype in acs_attributes.datatype%TYPE,
@@ -506,7 +505,7 @@
</pre><p>In addition, the following two calls are available for attaching extra
annotations onto attributes:</p><pre class="programlisting">
-<tt> procedure add_description (
+<tt class="computeroutput"> procedure add_description (
object_type in acs_attribute_descriptions.object_type%TYPE,
attribute_name in acs_attribute_descriptions.attribute_name%TYPE,
description_key in acs_attribute_descriptions.description_key%TYPE,
@@ -521,17 +520,17 @@
</tt>
</pre><p>At this point, what you must do to hook into the object system from your
-own data model becomes clear:</p><div class="itemizedlist"><ul type="disc"><li><p>Create a table that will store the instances of the new type.</p></li><li><p>Call <tt>acs_object_type.create_type()</tt> to fill in the metadata
+own data model becomes clear:</p><div class="itemizedlist"><ul type="disc"><li><p>Create a table that will store the instances of the new type.</p></li><li><p>Call <tt class="computeroutput">acs_object_type.create_type()</tt> to fill in the metadata
table on this new type. If you want your objects to appear in the
-<tt>acs_objects</tt> table, then your new type must be a subtype of
-<tt>acs_object</tt>.</p></li><li><p>Call <tt>acs_attribute.create_attribute()</tt> to fill in information
+<tt class="computeroutput">acs_objects</tt> table, then your new type must be a subtype of
+<tt class="computeroutput">acs_object</tt>.</p></li><li><p>Call <tt class="computeroutput">acs_attribute.create_attribute()</tt> to fill in information
on the attributes that this type defines.</p></li></ul></div><p>So, suppose we are writing a new version of the ticket tracker for 4.0. We
probably define a table to store tickets in, and each ticket might have an ID
and a description. If we want each ticket to be an object, then
-<tt>ticket_id</tt> must reference the <tt>object_id</tt> column in
-<tt>acs_objects</tt>:</p><pre class="programlisting">
+<tt class="computeroutput">ticket_id</tt> must reference the <tt class="computeroutput">object_id</tt> column in
+<tt class="computeroutput">acs_objects</tt>:</p><pre class="programlisting">
-<tt>create table tickets (
+<tt class="computeroutput">create table tickets (
ticket_id references acs_objects (object_id),
description varchar(512),
...
@@ -541,7 +540,7 @@
</pre><p>In addition to defining the table, we need this extra PL/SQL code to hook
into the object type tables:</p><pre class="programlisting">
-<tt>declare
+<tt class="computeroutput">declare
attr_id acs_attributes.attribute_id%TYPE;
begin
acs_object_type.create_type (
@@ -572,19 +571,19 @@
automatically be hooked into every generic object service that exists. Better
still, this code need not be changed as new services are added. As an aside,
the most important service that requires you to subtype
-<tt>acs_object</tt> is <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-objects"></a>Objects</h4></div></div><p>The next important piece of the API is defined in the
-<tt>acs_object</tt> package, and is concerned with creating and managing
+<tt class="computeroutput">acs_object</tt> is <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-objects"></a>Objects</h4></div></div><div></div></div><p>The next important piece of the API is defined in the
+<tt class="computeroutput">acs_object</tt> package, and is concerned with creating and managing
objects. This part of the API is designed to take care of the mundane
bookkeeping needed to create objects and query their attributes.
Realistically however, limitations in PL/SQL and Oracle will make it hard to
build generic procedures for doing large scale queries in the object system,
so developers who need to do this will probably have to be fairly familiar
-with the data model at a lower level.</p><p>The function <tt>acs_object.new()</tt> makes a new object for you. The
-function <tt>acs_object.del()</tt> deletes an object. As before, this
+with the data model at a lower level.</p><p>The function <tt class="computeroutput">acs_object.new()</tt> makes a new object for you. The
+function <tt class="computeroutput">acs_object.del()</tt> deletes an object. As before, this
is an abbreviated interface with all the long type specs removed. See the
data model or developer's guide for the full interface.</p><pre class="programlisting">
-<tt> function new (
+<tt class="computeroutput"> function new (
object_id in acs_objects.object_id%TYPE default null,
object_type in acs_objects.object_type%TYPE
default 'acs_object',
@@ -604,10 +603,10 @@
</pre><p>Next, we define some generic functions to manipulate attributes. Again,
these interfaces are useful to an extent, but for large scale queries,
it's likely that developers would have to query the data model directly,
-and then encapsulate their queries in procedures.</p><p>For names, the <tt>default_name</tt> function is used if you don't
+and then encapsulate their queries in procedures.</p><p>For names, the <tt class="computeroutput">default_name</tt> function is used if you don't
want to define your own name function.</p><pre class="programlisting">
-<tt> function name (
+<tt class="computeroutput"> function name (
object_id in acs_objects.object_id%TYPE
) return varchar;
@@ -620,7 +619,7 @@
</pre><p>The following functions tell you where attributes are stored, and fetch
single attributes for you.</p><pre class="programlisting">
-<tt> procedure get_attribute_storage (
+<tt class="computeroutput"> procedure get_attribute_storage (
object_id_in in acs_objects.object_id%TYPE,
attribute_name_in in acs_attributes.attribute_name%TYPE,
v_column out varchar2,
@@ -640,15 +639,15 @@
);
</tt>
-</pre><p>The main use of the <tt>acs_object</tt> package is to create
+</pre><p>The main use of the <tt class="computeroutput">acs_object</tt> package is to create
application objects and make them available for services via the
-<tt>acs_objects</tt> table. To do this, you just have to make sure you
-call <tt>acs_object.new()</tt> on objects that you wish to appear in the
-<tt>acs_objects</tt> table. In addition, all such objects must be
-instances of some subtype of <tt>acs_object</tt>.</p><p>Continuing the ticket example, we might define the following sort of
+<tt class="computeroutput">acs_objects</tt> table. To do this, you just have to make sure you
+call <tt class="computeroutput">acs_object.new()</tt> on objects that you wish to appear in the
+<tt class="computeroutput">acs_objects</tt> table. In addition, all such objects must be
+instances of some subtype of <tt class="computeroutput">acs_object</tt>.</p><p>Continuing the ticket example, we might define the following sort of
procedure for creating a new ticket:</p><pre class="programlisting">
-<tt> function new_ticket (
+<tt class="computeroutput"> function new_ticket (
package_id in tickets.ticket_id%TYPE
default null,
description in tickets.description%TYPE default '',
@@ -675,23 +674,23 @@
application need only do three things:</p><div class="itemizedlist"><ul type="disc"><li><p>Define a data model to describe application objects. This can just be a
normal SQL table.</p></li><li><p>Create an object type, using code like in the example from the previous
section.</p></li><li><p>Make sure application objects are created using
-<tt>acs_object.new()</tt> in addition to whatever SQL code is needed to
+<tt class="computeroutput">acs_object.new()</tt> in addition to whatever SQL code is needed to
insert a new row into the application data model.</p></li></ul></div><p>One of the design goals of OpenACS 4 was to provide a straightforward and
consistent mechanism to provide applications with general services. What we
have seen here is that three simple steps and minimal changes in the
application data model are sufficient to make sure that application objects
-are represented in the <tt>acs_objects</tt> table. Subsequently, all of
+are represented in the <tt class="computeroutput">acs_objects</tt> table. Subsequently, all of
the general services in OpenACS 4 (i.e. permissions, general comments, and so on)
-are written to work with any object that appears in <tt>acs_objects</tt>.
+are written to work with any object that appears in <tt class="computeroutput">acs_objects</tt>.
Therefore, in general these three steps are sufficient to make OpenACS 4 services
-available to your application.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-relat-types"></a>Relation Types</h4></div></div><p>The relations system defines two packages: <tt>acs_rel_type</tt> for
-creating and managing relation types, and <tt>acs_rel</tt> for relating
+available to your application.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-relat-types"></a>Relation Types</h4></div></div><div></div></div><p>The relations system defines two packages: <tt class="computeroutput">acs_rel_type</tt> for
+creating and managing relation types, and <tt class="computeroutput">acs_rel</tt> for relating
objects.</p><p>These two procedures just insert and remove roles from the
-<tt>acs_rel_roles</tt> table. This table stores the legal relationship
-"roles" that can be used when creating relation types. Examples of
-roles are, say, "member", or "employer".</p><pre class="programlisting">
+<tt class="computeroutput">acs_rel_roles</tt> table. This table stores the legal relationship
+"roles" that can be used when creating relation types. Examples of
+roles are, say, "member", or "employer".</p><pre class="programlisting">
-<tt> procedure create_role (
+<tt class="computeroutput"> procedure create_role (
role in acs_rel_roles.role%TYPE
);
@@ -700,10 +699,10 @@
);
</tt>
-</pre><p>The main functions in the <tt>acs_rel_type</tt> package are used to
+</pre><p>The main functions in the <tt class="computeroutput">acs_rel_type</tt> package are used to
create and drop relation types.</p><pre class="programlisting">
-<tt> procedure create_type (
+<tt class="computeroutput"> procedure create_type (
rel_type in acs_rel_types.rel_type%TYPE,
pretty_name in acs_object_types.pretty_name%TYPE,
pretty_plural in acs_object_types.pretty_plural%TYPE,
@@ -731,10 +730,10 @@
);
</tt>
-</pre><p>Finally, the <tt>acs_rel</tt> package provides an API that you use to
+</pre><p>Finally, the <tt class="computeroutput">acs_rel</tt> package provides an API that you use to
create and destroy instances of a relation type:</p><pre class="programlisting">
-<tt> function new (
+<tt class="computeroutput"> function new (
rel_id in acs_rels.rel_id%TYPE default null,
rel_type in acs_rels.rel_type%TYPE default 'relationship',
object_id_one in acs_rels.object_id_one%TYPE,
@@ -755,7 +754,7 @@
explicitly creating a table. First, we create a helper table to store state
on each membership fact:</p><pre class="programlisting">
-<tt>create table membership_rels (
+<tt class="computeroutput">create table membership_rels (
rel_id constraint membership_rel_rel_id_fk
references acs_rels (rel_id)
constraint membership_rel_rel_id_pk
@@ -769,7 +768,7 @@
</pre><p>Then, we create a new object type to describe groups.</p><pre class="programlisting">
-<tt> acs_object_type.create_type (
+<tt class="computeroutput"> acs_object_type.create_type (
object_type => 'group',
pretty_name => 'Group',
pretty_plural => 'Groups',
@@ -781,15 +780,15 @@
</tt>
</pre><p>In this example, we've made groups a subtype of
-<tt>acs_object</tt> to make the code simpler. The actual data model is
+<tt class="computeroutput">acs_object</tt> to make the code simpler. The actual data model is
somewhat different. Also, we've assumed that there is a helper table
-called <tt>groups</tt> to store information on groups, and that there is
-a helper table called <tt>group_types</tt> that has been defined to store
-extra attributes on groups.</p><p>Now, assuming we have another object type called <tt>person</tt> to
+called <tt class="computeroutput">groups</tt> to store information on groups, and that there is
+a helper table called <tt class="computeroutput">group_types</tt> that has been defined to store
+extra attributes on groups.</p><p>Now, assuming we have another object type called <tt class="computeroutput">person</tt> to
represent objects that can be group members, we define the following
relationship type for group membership:</p><pre class="programlisting">
-<tt> acs_rel_type.create_role ('member');
+<tt class="computeroutput"> acs_rel_type.create_role ('member');
acs_rel_type.create_type (
rel_type => 'membership_rel',
@@ -808,10 +807,10 @@
All this function does is create a new instance of the membership relation
type and then insert the membership state into the helper table that we
define above. In the actual implementation, this function is implemented in
-the <tt>membership_rel</tt> package. Here we just define an independent
+the <tt class="computeroutput">membership_rel</tt> package. Here we just define an independent
function:</p><pre class="programlisting">
-<tt>function member_add (
+<tt class="computeroutput">function member_add (
rel_id in membership_rels.rel_id%TYPE default null,
rel_type in acs_rels.rel_type%TYPE default 'membership_rel',
group in acs_rels.object_id_one%TYPE,
@@ -843,7 +842,7 @@
</pre><p>Another simple function can be defined to remove a member from a
group:</p><pre class="programlisting">
-<tt> procedure member_delete (
+<tt class="computeroutput"> procedure member_delete (
rel_id in membership_rels.rel_id%TYPE
)
is
@@ -855,11 +854,11 @@
end;
</tt>
-</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="objects-design-discuss"></a>Summary and Discussion</h4></div></div><p>The Object Model's API and data model provides a small set of simple
+</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-discuss"></a>Summary and Discussion</h4></div></div><div></div></div><p>The Object Model's API and data model provides a small set of simple
procedures that allow applications to create object types, object instances,
and object relations. Most of the data model is straightforward; the relation
type mechanism is a bit more complex, but in return it provides functionality
-on par with the old user/groups system in a more general way.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>Nothing here yet.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-authors"></a>Authors</h3></div></div><p><a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> generated this document
+on par with the old user/groups system in a more general way.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><div></div></div><p>Nothing here yet.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-authors"></a>Authors</h3></div></div><div></div></div><p><a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> generated this document
from material culled from other documents by <a href="mailto:mcyoon@arsdigita.com" target="_top">Michael Yoon</a>, <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a> and <a href="mailto:rhs@arsdigita.com" target="_top">Rafael Schloming</a>. But, any remaining lies
-are his and his alone.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-revision-hist"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/09/2000</td><td>Pete Su</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta</td><td>9/30/2000</td><td>Kai Wu</td></tr><tr><td>0.3</td><td>Edited for ACS 4.0.1, fixed some mistakes, removed use of term
-"OM"</td><td>11/07/2000</td><td>Pete Su</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Object Model Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Permissions Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/object-system-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
+are his and his alone.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-revision-hist"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/09/2000</td><td>Pete Su</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta</td><td>9/30/2000</td><td>Kai Wu</td></tr><tr><td>0.3</td><td>Edited for ACS 4.0.1, fixed some mistakes, removed use of term
+"OM"</td><td>11/07/2000</td><td>Pete Su</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Object Model Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Permissions Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/object-system-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,46 +1,45 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Object Model Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="kernel-overview.html" title="Overview"><link rel="next" href="object-system-design.html" title="OpenACS 4 Object Model Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="object-system-requirements"></a>OpenACS 4 Object Model Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Object Model Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="kernel-overview.html" title="Overview"><link rel="next" href="object-system-design.html" title="OpenACS 4 Object Model Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-system-requirements"></a>OpenACS 4 Object Model Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-"></a>I. Introduction</h3></div></div><p>A major goal in OpenACS 4 is to unify and normalize many of the core services
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-"></a>I. Introduction</h3></div></div><div></div></div><p>A major goal in OpenACS 4 is to unify and normalize many of the core services
of the system into a coherent common data model and API. In the past, these
services were provided to applications in an ad-hoc and irregular fashion.
Examples of such services include:</p><div class="itemizedlist"><ul type="disc"><li><p>General Comments</p></li><li><p>User/groups</p></li><li><p>Attribute storage in user/groups</p></li><li><p>General Permissions</p></li><li><p>Site wide search</p></li><li><p>General Auditing</p></li></ul></div><p>All of these services involve relating extra information and services to
application data objects, examples of which include:</p><div class="itemizedlist"><ul type="disc"><li><p>Bboard messages</p></li><li><p>A user home page</p></li><li><p>A ticket in the Ticket Tracker</p></li><li><p>A photograph in the PhotoDB</p></li></ul></div><p>In the past, developers had to use ad-hoc and inconsistent schemes to
-interface to the various "general" services mentioned above. Since
+interface to the various "general" services mentioned above. Since
each service used its own scheme for storing its metadata and mapping this
data to application objects, we could not implement any kind of centralized
management system or consistent administrative pages for all the services.
Consequently, a large amount of duplicate code appeared throughout the system
-for dealing with these services.</p><p>Unifying and "normalizing" these interfaces, to minimize the
+for dealing with these services.</p><p>Unifying and "normalizing" these interfaces, to minimize the
amount of code repetition in applications, is a primary goal of OpenACS 4. Thus
the Object Model (OM, also referred to later as the object system) is
concerned primarily with the storage and management of <span class="emphasis"><em>metadata</em></span>, on
-any object within a given instance of OpenACS 4. The term "metadata"
+any object within a given instance of OpenACS 4. The term "metadata"
refers to any extra data the OM stores on behalf of the application - outside
of the application's data model - in order to enable certain generic
-services. The term "object" refers to any entity being represented
+services. The term "object" refers to any entity being represented
within the OpenACS, and typically corresponds to a single row within the
-relational database.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-vision"></a>Vision Statement</h3></div></div><p>The OpenACS 4 Object Model must address five high-level requirements that
+relational database.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>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.</p><p><span class="strong">Object Identifiers for General Services</span></p><p>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 <tt>(user_id, group_id, scope)</tt> triple combination
+Many modules use a <tt class="computeroutput">(user_id, group_id, scope)</tt> triple combination
for the purpose of recording ownership information on objects for access
-control. User/groups also uses <tt>(user_id, group_id)</tt> pairs in its
-<tt>user_group_map</tt> table as a way to identify data associated with a
+control. User/groups also uses <tt class="computeroutput">(user_id, group_id)</tt> pairs in its
+<tt class="computeroutput">user_group_map</tt> table as a way to identify data associated with a
single membership relation.</p><p>Also in OpenACS 3.x, many utility modules exist that do nothing more than
attach some extra attributes to existing application data. For example,
general comments maintains a mapping table that maps application
-"page" data (static or dynamic) to one or more user comments on the
+"page" data (static or dynamic) to one or more user comments on the
page, by constructing a unique identifier for each page. This identifier is
usually a combination of the table in which the data is stored, and the value
of the primary key value for the particular page. This idiom is referred to
-as the "(on_which_table + on_what_id)" method for identifying
+as the "(on_which_table + on_what_id)" method for identifying
application data. General comments stores its map from pages to comments
-using a "(on_which_table + on_what_id)" key, plus the id of the
+using a "(on_which_table + on_what_id)" key, plus the id of the
comment itself.</p><p>All of these composite key constructions are implicit object identifiers:
they build a unique ID out of other pieces of the data model. The problem is
that their definition and use is ad-hoc and inconsistent. This makes the
@@ -49,9 +48,9 @@
mechanism for tagging application objects with unique identifiers.</p><p><span class="strong">Support for Unified Access Control</span></p><p>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.</p><p>"Scope" is a term best explained by example. Consider some
-hypothetical rows in the <tt>address_book</tt> table:</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">...</span></td><td><span class="strong"><tt>scope</tt></span></td><td><span class="strong"><tt>user_id</tt></span></td><td><span class="strong"><tt>group_id</tt></span></td><td><span class="strong">...</span></td></tr><tr><td>...</td><td><tt>user</tt></td><td><tt>123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt>group</tt></td><td>�</td><td><tt>456</tt></td><td>...</td></tr><tr><td>...</td><td><tt>public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote></div><p>The first row represents an entry in User 123's personal address book,
+on, a notion of "scoping" was introduced into the core data
+model.</p><p>"Scope" is a term best explained by example. Consider some
+hypothetical rows in the <tt class="computeroutput">address_book</tt> table:</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">...</span></td><td><span class="strong"><tt class="computeroutput">scope</tt></span></td><td><span class="strong"><tt class="computeroutput">user_id</tt></span></td><td><span class="strong"><tt class="computeroutput">group_id</tt></span></td><td><span class="strong">...</span></td></tr><tr><td>...</td><td><tt class="computeroutput">user</tt></td><td><tt class="computeroutput">123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt class="computeroutput">group</tt></td><td>�</td><td><tt class="computeroutput">456</tt></td><td>...</td></tr><tr><td>...</td><td><tt class="computeroutput">public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote></div><p>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.</p><p>In this way, the scoping columns identify the security context in which a
@@ -67,7 +66,7 @@
with a single piece of data, instead of the old composite keys described
above.</p><p><span class="strong">Extensible Data Models</span></p><p>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 <tt>users</tt> table is the best case
+increasing number of modules. The <tt class="computeroutput">users</tt> table is the best case
in point: it became full of columns that exist for various special
applications (e.g. user portraits), but that aren't really related to
each other in any way except that they store information on users, i.e. the
@@ -93,23 +92,23 @@
extensions, since such changes are difficult or dangerous to make at runtime,
and can make updating the system difficult. Some example applications in OpenACS
3.x with modifiable data models include:</p><div class="itemizedlist"><ul type="disc"><li><p>User/groups: developers and users can attach custom data to group types,
-groups, and members of groups.</p></li><li><p>In the Ecommerce data model, the <tt>ec_custom_product_fields</tt>
+groups, and members of groups.</p></li><li><p>In the Ecommerce data model, the <tt class="computeroutput">ec_custom_product_fields</tt>
table defines attributes for catalog products, and the
-<tt>ec_custom_product_field_values</tt> table stores values for those
-attributes.</p></li><li><p>In the PhotoDB data model, the <tt>ph_custom_photo_fields</tt> table
+<tt class="computeroutput">ec_custom_product_field_values</tt> table stores values for those
+attributes.</p></li><li><p>In the PhotoDB data model, the <tt class="computeroutput">ph_custom_photo_fields</tt> table
defines attributes for the photographs owned by a specific user, and tables
named according to the convention
-"<tt>ph_user_<user_id>_custom_info</tt>" are used to
+"<tt class="computeroutput">ph_user_<user_id>_custom_info</tt>" are used to
store values for those attributes.</p></li></ul></div><p>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.</p><p><span class="strong">Generic Relations</span></p><p>Many OpenACS applications define simple relationships between application
objects, and tag those relationships with extra data. In OpenACS 3.x, this was
done using <span class="emphasis"><em>mapping tables</em></span>. The user/groups module has the most
highly developed data model for this purpose, using a single table called
-<tt>user_group_map</tt> that mapped users to groups. In addition, it uses
-the the <tt>user_group_member_fields</tt> and
-<tt>user_group_member_fields_map</tt> tables to allow developers to
+<tt class="computeroutput">user_group_map</tt> that mapped users to groups. In addition, it uses
+the the <tt class="computeroutput">user_group_member_fields</tt> and
+<tt class="computeroutput">user_group_member_fields_map</tt> tables to allow developers to
attach custom attributes to group members. In fact, these custom attributes
were not really attached to the users, but to the fact that a user was a
member of a particular group - a subtle but important distinction. As a
@@ -121,17 +120,17 @@
Relation types are themselves object types that do nothing but represent
relations. They can be used by applications that previously used user/groups
for the same purpose, but without the extraneous, artificial
-dependencies.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-system-overview"></a>System Overview</h3></div></div><p>The Object Model package is a combination of data model and a procedural
+dependencies.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-system-overview"></a>System Overview</h3></div></div><div></div></div><p>The Object Model package is a combination of data model and a procedural
API for manipulating application objects within an OpenACS instance. The OM
allows developers to describe a hierarchical system of <span class="emphasis"><em>object types</em></span>
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.</p><p>The OM data model forms the main part of the OpenACS 4 Kernel data model. The
-other parts of the Kernel data model include:</p><div class="itemizedlist"><ul type="disc"><li><p>Parties and Groups</p></li><li><p>Permissions</p></li></ul></div><p>Each of these is documented elsewhere at length.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><p>(Pending as of 8/27/00)</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-design.html">OpenACS 4 Object Model Design</a></p></li><li><p><a href="objects.html">OpenACS Data Models and the Object System</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-data-model"></a>Requirements: Data Model</h3></div></div><p>The data model for the object system provides support for the following
+other parts of the Kernel data model include:</p><div class="itemizedlist"><ul type="disc"><li><p>Parties and Groups</p></li><li><p>Permissions</p></li></ul></div><p>Each of these is documented elsewhere at length.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><div></div></div><p>(Pending as of 8/27/00)</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-links"></a>Related Links</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-design.html">OpenACS 4 Object Model Design</a></p></li><li><p><a href="objects.html">OpenACS Data Models and the Object System</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-data-model"></a>Requirements: Data Model</h3></div></div><div></div></div><p>The data model for the object system provides support for the following
kinds of schema patterns that are used by many existing OpenACS modules:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">10.0 Object Identification and Storage</span></span></dt><dd><p>Object identification is a central mechanism in the new metadata system.
The fact that every object has a known unique identifier means that the core
can deal with all objects in a generic way. Thus the only action required of
-an application to obtain any general service is to "hook into" the
+an application to obtain any general service is to "hook into" the
object system.</p><p>In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for
objects that they manage. Generally, these unique IDs are built from other
IDs that happen to be in the data model. Because there is no consistency in
@@ -196,7 +195,7 @@
object (see requirement 10.20 above) and the attribute name.</p><p><span class="strong">40.20 Inherited Attributes</span></p><p>The system should allow for the automatic retrieval of inherited attribute
values, for an object belonging to a subtype.</p><p><span class="strong">40.30. Constraints on Attributes</span></p><p>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.</p></dd><dt><span class="term"><span class="strong">50.0 Object Contexts</span></span></dt><dd><p>In OpenACS 3.x, there was a notion of "scope" for application
+application specific integrity rules.</p></dd><dt><span class="term"><span class="strong">50.0 Object Contexts</span></span></dt><dd><p>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.</p><p>The OpenACS 4 Object Model provides a generalized notion of scope that allows
@@ -206,21 +205,21 @@
permissions from its context.</p><p>The context data model also forms the basis of the <a href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements">subsites system</a>, and is
a basic part of the <a href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">permissions system</a>,
described in separate documents.</p><p>The context data model should provide the following facilities:</p><p><span class="strong">50.10 Unique ID</span></p><p>Every context should have a unique ID in the system.</p><p><span class="strong">50.20 Tree Structure</span></p><p>The data model should support a tree structured organization of contexts.
-That is, contexts can be logically "contained" within other
+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).</p><p><span class="strong">50.30 Data Model Constraints</span></p><p>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.</p><p><span class="strong">Note:</span></p><p>The current system interprets the NULL context as meaning the default
-"site-wide" context in some sense. I wanted to note this fact for
+"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).</p></dd><dt><span class="term"><span class="strong">55.0 Object Relations</span></span></dt><dd><p>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.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-api"></a>Requirements: API</h3></div></div><p>The API should let programmers accomplish the following actions:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">60.0 Object Type Creation</span></span></dt><dd><p><span class="strong">60.10 Create a New Object Type</span></p><p>The object system API should provide a procedure call that creates a new
+"object X is related to object Y by relationship R," and also be
+able to attach attributes to these facts.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-api"></a>Requirements: API</h3></div></div><div></div></div><p>The API should let programmers accomplish the following actions:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong">60.0 Object Type Creation</span></span></dt><dd><p><span class="strong">60.10 Create a New Object Type</span></p><p>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.</p><p><span class="strong">60.20 Create a New Object Subtype</span></p><p>The object system API should provide a procedure call for creating
+model. We call this operation "instantiating" an object.</p><p><span class="strong">60.20 Create a New Object Subtype</span></p><p>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
@@ -233,15 +232,15 @@
an error to delete types that have dependent subtypes. This API is subject to
the constraints laid out in the data model.</p><p><span class="strong">80.10.10</span></p><p>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
+object type. This is similar to a "delete cascade" constraint in
SQL.</p></dd><dt><span class="term"><span class="strong">90.0 Object Instance Creation and Destruction</span></span></dt><dd><p>The system must provide API calls to manage the creation and destruction
of object instances.</p><p><span class="strong">90.10 Create an Instance of an Object Type</span></p><p>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.</p><p><span class="strong">90.20 Delete an Object Instance</span></p><p>The OM should provide an API call for object deletion. Objects can be
deleted only when no other objects in the system refer to them. Since it
-might not be practical to provide a mechanism like "delete cascade"
+might not be practical to provide a mechanism like "delete cascade"
here in a reliable way, providing such a facility in the system is
optional.</p></dd><dt><span class="term"><span class="strong">94.0 Object Relation Creation and Destruction</span></span></dt><dd><p>The system must provide API calls to manage the creation and destruction
of object relations.</p></dd><dt><span class="term"><span class="strong">94.10 Create an Object Relation</span></span></dt><dd><p>The OM must provide an API call to declare that two objects are related to
@@ -259,10 +258,10 @@
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
+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.</p><p><span class="strong">Note:</span> Is the API the only way to obtain values? How does
-this integrate with application level SQL queries?</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/10/2000</td><td>Bryan Quinn</td></tr><tr><td>0.2</td><td>Major re-write</td><td>08/11/2000</td><td>Pete Su</td></tr><tr><td>0.3</td><td>Draft completed after initial reviews</td><td>08/22/2000</td><td>Pete Su</td></tr><tr><td>0.4</td><td>Edited, updated to conform to requirements template, pending freeze</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>�</td><td>Final edits before freeze</td><td>08/24/2000</td><td>Pete Su</td></tr><tr><td>0.5</td><td>Edited for consistency</td><td>08/27/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>Put Object ID stuff first, because it makes more sense</td><td>08/28/2000</td><td>Pete Su</td></tr><tr><td>0.7</td><td>Added requirement that knowledge-level objects must be moveable between
+this integrate with application level SQL queries?</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/10/2000</td><td>Bryan Quinn</td></tr><tr><td>0.2</td><td>Major re-write</td><td>08/11/2000</td><td>Pete Su</td></tr><tr><td>0.3</td><td>Draft completed after initial reviews</td><td>08/22/2000</td><td>Pete Su</td></tr><tr><td>0.4</td><td>Edited, updated to conform to requirements template, pending freeze</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>�</td><td>Final edits before freeze</td><td>08/24/2000</td><td>Pete Su</td></tr><tr><td>0.5</td><td>Edited for consistency</td><td>08/27/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>Put Object ID stuff first, because it makes more sense</td><td>08/28/2000</td><td>Pete Su</td></tr><tr><td>0.7</td><td>Added requirement that knowledge-level objects must be moveable between
databases.</td><td>08/29/2000</td><td>Richard Li</td></tr><tr><td>0.8</td><td>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.</td><td>09/06/2000</td><td>Pete Su</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release.</td><td>09/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Object Model Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/object-system-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/objects.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/objects.html 30 Sep 2003 12:10:01 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/objects.html 14 Oct 2003 11:02:58 -0000 1.14
@@ -1,11 +1,10 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Data Models and the Object System</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="packages.html" title="OpenACS 5.0.0d Packages"><link rel="next" href="request-processor.html" title="The Request Processor"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="objects"></a>OpenACS Data Models and the Object System</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Data Models and the Object System</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="packages.html" title="OpenACS 5.0.0a1 Packages"><link rel="next" href="request-processor.html" title="The Request Processor"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="objects"></a>OpenACS Data Models and the Object System</h2></div></div><div></div></div><div class="authorblurb"><p>
By Pete Su
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="objects-overview"></a>Overview</h3></div></div><p>
-Developing data models in OpenACS 5.0.0d is much like developing data models
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="objects-overview"></a>Overview</h3></div></div><div></div></div><p>
+Developing data models in OpenACS 5.0.0a1 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
@@ -30,12 +29,12 @@
</p><div class="itemizedlist"><ul type="opencircle"><li style="list-style-type: circle"><p>Define access control policies on notes.</p></li><li style="list-style-type: circle"><p>Attach user comments on notes.</p></li><li style="list-style-type: circle"><p>Allow users to define custom fields to store on their notes.</p></li><li style="list-style-type: circle"><p>Automatically generate input forms or output displays for notes.</p></li><li style="list-style-type: circle"><p>Allow other applications to use notes in ways we don't know of yet.</p></li></ul></div><p>
In OpenACS, the key to enabling these types of services on your
application data is to take advantage of the Object System. The first
-question, then, is "Just what are objects, and what do
-you use them for anyway?". The short answer: objects are anything
+question, then, is "Just what are objects, and what do
+you use them for anyway?". The short answer: objects are anything
represented in the application's data model that will need to be
managed by any central service in OpenACS, or that may be reusable in
the context of future applications. Every object in the system is
-represented using a row in the <tt>acs_objects</tt> table. This
+represented using a row in the <tt class="computeroutput">acs_objects</tt> table. This
table defines all the standard attributes that are stored on every
object, including its system-wide unique ID, object type, and some
generic auditing columns.
@@ -47,19 +46,19 @@
</p><div class="itemizedlist"><ul type="disc"><li><p>The <a href="permissions.html">Permissions System</a> lets you
track who is allowed to do what to the rows
in an application table, and gives you an easy way to enforce
- this from Tcl.</p></li><li><p>Every object has an attribute called <tt>context_id</tt>
+ this from Tcl.</p></li><li><p>Every object has an attribute called <tt class="computeroutput">context_id</tt>
that provides a way to trivially specify both the default
- permissions for an object, and the intended "scope" of an
- object. Just set the <tt>context_id</tt> to the controlling
+ permissions for an object, and the intended "scope" of an
+ object. Just set the <tt class="computeroutput">context_id</tt> to the controlling
object and forget about it.</p></li><li><p>And most importantly, any future object-level service - from
a general-comments replacement to personalized ranking - will
- become available to your application "for free."</p></li></ul></div><p>
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="objects-how-to-use"></a>How to Use Objects</h3></div></div><p>
+ become available to your application "for free."</p></li></ul></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="objects-how-to-use"></a>How to Use Objects</h3></div></div><div></div></div><p>
Using ACS objects is straightforward: all that's required are a few
extra steps in the design of your application data model.
</p><p>
In order to hook our Notes application into the object system, we
-make some calls to use our <tt>notes</tt> table as the basis for a
+make some calls to use our <tt class="computeroutput">notes</tt> table as the basis for a
new <span class="emphasis"><em>object type</em></span>. 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
@@ -68,21 +67,21 @@
define the programming interface to the data model.
</p><p>
The object type itself is described using data in the
-<tt>acs_object_types</tt> and
-<tt>acs_attributes</tt> tables, which play a role
+<tt class="computeroutput">acs_object_types</tt> and
+<tt class="computeroutput">acs_attributes</tt> tables, which play a role
similar to the data dictionary in Oracle. As in Java, object types can
inherit attributes from a parent type, so the type system forms a
hierarchy. Unlike Java, Oracle does not support this inheritance
transparently, so we have to make sure we add our own bookkeeping code to
keep everything consistent. Below you'll find the code needed to describe a
-new object type called <tt>notes</tt> in your
+new object type called <tt class="computeroutput">notes</tt> in your
system.
</p><p>
Fire up your text editor and open the
-<tt>ROOT/packages/notes/sql/oracle/notes-create.sql</tt> (<tt>ROOT/packages/notes/sql/postgresql/notes-create.sql</tt> for the PG version) file created
-when we <a href="packages.html" title="OpenACS 5.0.0d Packages">created the package</a>. Then, do the following:
-</p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2978448"></a>Describe the new type to the type system</h4></div></div><p>
-First, add an entry to the <tt>acs_object_types</tt> table with the following PL/SQL call:
+<tt class="computeroutput">ROOT/packages/notes/sql/oracle/notes-create.sql</tt> (<tt class="computeroutput">ROOT/packages/notes/sql/postgresql/notes-create.sql</tt> for the PG version) file created
+when we <a href="packages.html" title="OpenACS 5.0.0a1 Packages">created the package</a>. Then, do the following:
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2843281"></a>Describe the new type to the type system</h4></div></div><div></div></div><p>
+First, add an entry to the <tt class="computeroutput">acs_object_types</tt> table with the following PL/SQL call:
</p><pre class="programlisting">
begin
acs_object_type.create_type (
@@ -98,18 +97,18 @@
show errors;
</pre><p>
This PL/SQL call tells the system that we would like to use the table
-<tt>NOTES</tt> as the basis for a new object type called
-<tt>note</tt>. This type is a subtype of the
-<tt>acs_object</tt> type, which means that we want to inherit all
+<tt class="computeroutput">NOTES</tt> as the basis for a new object type called
+<tt class="computeroutput">note</tt>. This type is a subtype of the
+<tt class="computeroutput">acs_object</tt> type, which means that we want to inherit all
of the basic attributes of all ACS objects. As mentioned, it will take
some work on our part to make this happen, since Oracle can't do it
automatically. In general, most basic applications will define types
-that are simple subtypes of <tt>acs_object</tt>.
+that are simple subtypes of <tt class="computeroutput">acs_object</tt>.
</p><p>
-Add entries to the <tt>acs_attributes</tt> table to describe
+Add entries to the <tt class="computeroutput">acs_attributes</tt> table to describe
the data attributes of the new type. This data can eventually be used
to do things like automatically generate user interfaces to manipulate
-the <tt>notes</tt> table, though that functionality isn't yet
+the <tt class="computeroutput">notes</tt> table, though that functionality isn't yet
available.
</p><pre class="programlisting">
declare
@@ -135,17 +134,17 @@
show errors;
</pre><p>
We can stop here and not bother to register the usual OpenACS 3.x
-attributes of <tt>creation_user</tt>, <tt>creation_date</tt>
-and <tt>last_modified</tt>, since the object type
-<tt>acs_object</tt> already defines these attributes. Again,
-because the new type <tt>note</tt> is a subtype of
-<tt>acs_object</tt>, it will inherit these attributes, so there is
+attributes of <tt class="computeroutput">creation_user</tt>, <tt class="computeroutput">creation_date</tt>
+and <tt class="computeroutput">last_modified</tt>, since the object type
+<tt class="computeroutput">acs_object</tt> already defines these attributes. Again,
+because the new type <tt class="computeroutput">note</tt> is a subtype of
+<tt class="computeroutput">acs_object</tt>, it will inherit these attributes, so there is
no need for us to define them.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2987746"></a>Define a table in which to store your objects</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2843399"></a>Define a table in which to store your objects</h4></div></div><div></div></div><p>
The next thing we do is make a small modification to the data model to
-reflect the fact that each row in the <tt>notes</tt> table
+reflect the fact that each row in the <tt class="computeroutput">notes</tt> table
represents something that is not only an object of type
-<tt>note</tt>, but also an <tt>acs_object</tt>. The new table
+<tt class="computeroutput">note</tt>, but also an <tt class="computeroutput">acs_object</tt>. The new table
definition looks like this:
</p><pre class="programlisting">
create table notes (
@@ -155,18 +154,18 @@
body varchar(1024)
)
</pre><p>
-The usual <tt>creation_date</tt> and
-<tt>modified_date</tt> columns are absent since they already exist
-in <tt>acs_objects</tt>. Also, note the constraint we have added
-to reference the <tt>acs_objects</tt> table, which makes clear
-that since <tt>note</tt> is a subtype of <tt>acs_object</tt>,
+The usual <tt class="computeroutput">creation_date</tt> and
+<tt class="computeroutput">modified_date</tt> columns are absent since they already exist
+in <tt class="computeroutput">acs_objects</tt>. Also, note the constraint we have added
+to reference the <tt class="computeroutput">acs_objects</tt> table, which makes clear
+that since <tt class="computeroutput">note</tt> is a subtype of <tt class="computeroutput">acs_object</tt>,
every row in the notes table must have a corresponding row in the
-<tt>acs_objects</tt> table. This is the fundamental means by which
+<tt class="computeroutput">acs_objects</tt> table. This is the fundamental means by which
we model inheritance; it guarantees that any services that
-use the <tt>acs_objects</tt> table to find objects will
+use the <tt class="computeroutput">acs_objects</tt> table to find objects will
transparently find any objects that are instances of any subtype of
-<tt>acs_objects</tt>.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2987870"></a>Define a package for type specific procedures</h4></div></div><p>
+<tt class="computeroutput">acs_objects</tt>.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2842306"></a>Define a package for type specific procedures</h4></div></div><div></div></div><p>
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:
@@ -198,30 +197,30 @@
calls, since we haven't mentioned them before. These parameters are
needed to fill out information that will be stored about the object
that's not stored directly in the table you defined. The OpenACS Object
-System defines these attributes on the type <tt>acs_object</tt>
+System defines these attributes on the type <tt class="computeroutput">acs_object</tt>
since all objects should have these attributes. Internally, there are
tables that store this information for you. Most of the data is pretty
self-explanatory and reflects attributes that existed in the earlier
-OpenACS 3.x data models, with the exception of the <tt>context_id</tt>
+OpenACS 3.x data models, with the exception of the <tt class="computeroutput">context_id</tt>
attribute.
</p><p>
-The <tt>context_id</tt> attribute stores the ID of an object that
+The <tt class="computeroutput">context_id</tt> attribute stores the ID of an object that
represents the default security domain to which the object belongs. It
is used by the <a href="permissions.html" title="Groups, Context, Permissions">permissions</a> system in
this way: if no permissions are explicitly attached to the object,
then the object inherits its permissions from the context. For
example, if I had told you how to use the <a href="permissions.html" title="Groups, Context, Permissions">permissions</a> system to specify that an
-object OBJ was "read only", then any other object that used OBJ as its
-context would also be "read only" by default. We'll talk about this more
+object OBJ was "read only", then any other object that used OBJ as its
+context would also be "read only" by default. We'll talk about this more
later.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2987972"></a>Define a package body for type specific procedures</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2842397"></a>Define a package body for type specific procedures</h4></div></div><div></div></div><p>
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
-<tt>acs_object.new</tt> to insert a row into
-<tt>acs_objects</tt>, before inserting a row into the
-<tt>notes</tt>. Similarly, when we delete a row from
-<tt>note</tt>, we have to be sure to delete the corresponding
-<tt>acs_object</tt> row.
+<tt class="computeroutput">acs_object.new</tt> to insert a row into
+<tt class="computeroutput">acs_objects</tt>, before inserting a row into the
+<tt class="computeroutput">notes</tt>. Similarly, when we delete a row from
+<tt class="computeroutput">note</tt>, we have to be sure to delete the corresponding
+<tt class="computeroutput">acs_object</tt> row.
</p><pre class="programlisting">
create or replace package body note
as
@@ -274,14 +273,14 @@
/
show errors;
</pre><p>
-That's pretty much it! As long as you use the <tt>note.new</tt>
-function to create notes, and the <tt>note.delete</tt> function to
+That's pretty much it! As long as you use the <tt class="computeroutput">note.new</tt>
+function to create notes, and the <tt class="computeroutput">note.delete</tt> function to
delete them, you'll be assured that the relationship each
-<tt>note</tt> has with its corresponding <tt>acs_object</tt>
+<tt class="computeroutput">note</tt> has with its corresponding <tt class="computeroutput">acs_object</tt>
is preserved.
</p><p>
The last thing to do is to make a file
-<tt>ROOT/packages/notes/sql/notes-drop.sql</tt> so it's easy to
+<tt class="computeroutput">ROOT/packages/notes/sql/notes-drop.sql</tt> so it's easy to
drop the data model when, say, you're testing:
</p><pre class="programlisting">
begin
@@ -292,17 +291,17 @@
drop package note;
drop table notes;
-</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="objects-when-to-use-objects"></a>When to Use Objects</h3></div></div><p>
+</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="objects-when-to-use-objects"></a>When to Use Objects</h3></div></div><div></div></div><p>
While it is hard to give general design advice without
knowing anything about a particular application, you should follow the
following rule of thumb when deciding when to hook part of your data
model to the object system:
</p><p>
Anything in your data model that needs to be available to general OpenACS
services such as user comments, permissions, and so on should be a
-subtype of <tt>acs_object</tt>. In addition, if you want your data
+subtype of <tt class="computeroutput">acs_object</tt>. In addition, if you want your data
model to take advantage of attributes that exist in some object type
-that is a subtype of <tt>acs_object</tt>, then you should use the
+that is a subtype of <tt class="computeroutput">acs_object</tt>, then you should use the
object system.
</p><p>
For example, for most applications, you will want to use objects to
@@ -312,34 +311,34 @@
kind of design decision is mostly made on an
application-by-application basis, but this is a good baseline from
which to start.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="objects-design-guidance"></a>Design Guidance</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="objects-design-guidance"></a>Design Guidance</h3></div></div><div></div></div><p>
In this section we cover some overall guidelines for designing data
models that are meant to be integrated with the OpenACS object
system.
</p><p>
-There are two basic rules you should follow when designing OpenACS 5.0.0d data
+There are two basic rules you should follow when designing OpenACS 5.0.0a1 data
models:
</p><div class="orderedlist"><ol type="1"><li><p>
-Never utilize fields in the <tt>acs_objects</tt> table in
+Never utilize fields in the <tt class="computeroutput">acs_objects</tt> table in
application specific ways. That is, never assign any
application-specific semantics to this data. In the notes
-application, we use the <tt>creation_date</tt> and
-<tt>last_modified</tt> fields, but this is OK since we do not
+application, we use the <tt class="computeroutput">creation_date</tt> and
+<tt class="computeroutput">last_modified</tt> fields, but this is OK since we do not
assign any application-specific meaning to these fields.
</p></li><li><p>
In particular, never assign any application specific semantics to the
-<tt>context_id</tt> attribute of an object. This field is used for
+<tt class="computeroutput">context_id</tt> attribute of an object. This field is used for
a very specific purpose by the permissions system, and using this
field in <span class="emphasis"><em>any other way whatsoever</em></span> is guaranteed to make your
application act strangely.
</p><p>
As we'll see later, the Notes example will point each note object's
-<tt>context_id</tt> to the package instance in which the note was
+<tt class="computeroutput">context_id</tt> to the package instance in which the note was
created. The idea will be that in a real site, the administrator would
create one package instance for every separate set of Notes (say, one
-per user). The instance would "own" all of the notes that it created,
+per user). The instance would "own" all of the notes that it created,
and the administrator would be able to use the package instance as
the basis for access control, which is convenient.
</p></li></ol></div><p>
@@ -357,43 +356,43 @@
that the data model is trying to support.
</p><p>
Another less important reason for these two rules is to not introduce
-any joins against the <tt>acs_objects</tt> table in SQL queries in
+any joins against the <tt class="computeroutput">acs_objects</tt> table in SQL queries in
your application that you do not absolutely need.
</p><p>
In the Notes example, the result of applying these rules is that we
-are careful to define our own attribute for <tt>owner_id</tt>
-rather than overloading <tt>creation_user</tt> from the objects
-table. But, since we will probably use <tt>creation_date</tt> and
+are careful to define our own attribute for <tt class="computeroutput">owner_id</tt>
+rather than overloading <tt class="computeroutput">creation_user</tt> from the objects
+table. But, since we will probably use <tt class="computeroutput">creation_date</tt> and
so on for their intended purposes, we don't bother to define our own
attributes to store that data again. This will entail joins with
-<tt>acs_objects</tt> but that's OK because it makes the overall
+<tt class="computeroutput">acs_objects</tt> but that's OK because it makes the overall
data model cleaner. The real lesson is that deciding exactly how and
when to use inherited attributes is fairly straightforward, but
requires a good amount of thought at design time even for simple
applications.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="objects-summary"></a>Summary</h3></div></div><p>
-Hooking into the OpenACS 5.0.0d object system brings the application developer
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="objects-summary"></a>Summary</h3></div></div><div></div></div><p>
+Hooking into the OpenACS 5.0.0a1 object system brings the application developer
numerous benefits, and doing it involves only four easy steps:
</p><div class="itemizedlist"><ul type="opencircle"><li style="list-style-type: circle"><p>
Describe the a new object type to the system. Most new application
-types will be subtypes of the built-in type <tt>acs_object</tt>.
+types will be subtypes of the built-in type <tt class="computeroutput">acs_object</tt>.
</p></li><li style="list-style-type: circle"><p>
Define a table to store application object data.
</p></li><li style="list-style-type: circle"><p>
Define a PL/SQL package to store procedures related to the new
-type. You have to define at least a function called <tt>new</tt>
+type. You have to define at least a function called <tt class="computeroutput">new</tt>
to create new application objects and a procedure called
-<tt>delete</tt> to delete them.
+<tt class="computeroutput">delete</tt> to delete them.
</p></li><li style="list-style-type: circle"><p>
Define a package body that contains the implementations of the PL/SQL
procedures defined above.
</p></li><li style="list-style-type: circle"><p>
Try not to write queries in your application that join against
-<tt>acs_objects</tt>. This means you should never use the fields
-in <tt>acs_objects</tt> for application-specific purposes. This is
-especially true for the <tt>context_id</tt> field.
+<tt class="computeroutput">acs_objects</tt>. This means you should never use the fields
+in <tt class="computeroutput">acs_objects</tt> for application-specific purposes. This is
+especially true for the <tt class="computeroutput">context_id</tt> field.
</p></li></ul></div><p>
-</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 5.0.0d Packages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The Request Processor</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/objects.html#comments">View comments on this page at openacs.org</a></center></body></html>
+</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 5.0.0a1 Packages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The Request Processor</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/objects.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v
diff -u -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/openacs-overview.html 20 Aug 2003 16:20:16 -0000 1.8
+++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 14 Oct 2003 11:02:58 -0000 1.9
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="previous" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="next" href="release-notes.html" title="OpenACS Release Notes"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><th width="60%" align="center">Chapter�1.�High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="openacs-overview"></a>Overview</h2></div></div><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="previous" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="next" href="release-notes.html" title="OpenACS Release Notes"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><th width="60%" align="center">Chapter�1.�High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs-overview"></a>Overview</h2></div></div><div></div></div><p>
OpenACS (Open Architecture Community System) is an
advanced toolkit for building scalable, community-oriented
web applications. If you're thinking of building an
@@ -29,21 +28,21 @@
their work available under the <a href="http://dev.openacs.org/about/licensing/" target="_top">GPL</a>,
making all of this possible.
</p><p>
- “The ArsDigita Community System (ACS) is a toolkit of software
+ “<span class="quote">The ArsDigita Community System (ACS) is a toolkit of software
that will help you build Web services with a collaborative dimension,
ranging from knowledge management within companies to B2C ecommerce
to product support and community among the customers. The software is
free and open-source and has been tested in heavy use since
- 1995.” - Philip Greenspun
+ 1995.</span>” - Philip Greenspun
</p><p>
OpenACS was born when Don Baccus, Ben Adida, et al decided
to port ACS from Oracle to PostgreSQL, thus making it a
fully open-source solution.
</p><p>
- OpenACS 5.0.0d is the next generation of the web toolkit. It's based on
+ OpenACS 5.0.0a1 is the next generation of the web toolkit. It's based on
ACS 4, but no longer follows ArsDigita development. Unlike ACS
(which required Oracle) and OpenACS 3.x (which required PostgreSQL),
- OpenACS 5.0.0d allows you to use either database. It's also built in such
+ OpenACS 5.0.0a1 allows you to use either database. It's also built in such
a way to allow enterprising hackers (in the good sense of
the word) to extend it to other databases. Don Baccus leads
the development and numerous developers and non-developers
Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 14 Oct 2003 11:02:58 -0000 1.4
@@ -1,7 +1,6 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Unpack the OpenACS tarball</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="next" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="openacs-unpack"></a>Unpack the OpenACS tarball</h2></div></div><p>The OpenACS tarball contains sample configuration files
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Unpack the OpenACS tarball</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="next" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs-unpack"></a>Unpack the OpenACS tarball</h2></div></div><div></div></div><p>The OpenACS tarball contains sample configuration files
for some of the packages listed below. In order to access those
- files, unpack the tarball now.</p><pre class="screen">[root@yourserver root]# <b><tt>cd /tmp</tt></b>
-[root@yourserver tmp]# <b><tt>tar xzf openacs-5.0.0d.tgz</tt></b>
-<pre class="action">cd /tmp
-tar xzf openacs-5.0.0d.tgz</pre></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix�B.�Install additional supporting software </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Initialize CVS (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/openacs-unpack.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ files, unpack the tarball now.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /tmp</tt></b>
+[root@yourserver tmp]# <b class="userinput"><tt>tar xzf openacs-5.0.0a1.tgz</tt></b>
+<pre class="action"><span class="action">cd /tmp
+tar xzf openacs-5.0.0a1.tgz</span></pre></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix�B.�Install additional supporting software </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Initialize CVS (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/openacs-unpack.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/openacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/openacs.html 20 Aug 2003 16:20:16 -0000 1.10
+++ openacs-4/packages/acs-core-docs/www/openacs.html 14 Oct 2003 11:02:58 -0000 1.11
@@ -1,22 +1,20 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install OpenACS 5.0.0d</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="aolserver.html" title="Install AOLserver 3.3oacs1"><link rel="next" href="credits.html" title="Credits"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="openacs"></a>Install OpenACS 5.0.0d</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install OpenACS 5.0.0a1</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="aolserver.html" title="Install AOLserver 3.3oacs1"><link rel="next" href="credits.html" title="Credits"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs"></a>Install OpenACS 5.0.0a1</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="openacs-setup"></a>Set up the file system for an OpenACS Service</h3></div></div><div class="orderedlist"><ol type="1"><li><p><a name="make-web-directory"></a>The reference install stores all OpenACS services in
- <tt>/web</tt>, with one subdirectory per
- service. The first time you install a service, you must create
- that directory and set its permissions:</p><pre class="screen">[root@yourserver root]# <b><tt>mkdir /web</tt></b>
-[root@yourserver root]# <b><tt>chgrp web /web</tt></b>
-[root@yourserver root]# <b><tt>chmod 770 /web</tt></b>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openacs-setup"></a>Set up the file system for an OpenACS Service</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p><a name="make-web-directory"></a>The reference install stores all OpenACS services in
+ <tt class="computeroutput">/var/lib/aolserver</tt>, with one subdirectory per service. The first time you install a service, you must create
+ that directory and set its permissions:</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>mkdir /var/lib/aolserver</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chgrp web /var/lib/aolserver</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chmod 770 /var/lib/aolserver</tt></b>
[root@yourserver root]#
-<pre class="action">mkdir /web
-chgrp web /web
-chmod 770 /web</pre></pre></li><li><p><a name="install-openacs-download"></a>You should already have downloaded the OpenACS tarball
- to the <tt>/tmp</tt> directory. If
+<pre class="action"><span class="action">mkdir /var/lib/aolserver
+chgrp web /var/lib/aolserver
+chmod 770 /var/lib/aolserver</span></pre></pre></li><li><p><a name="install-openacs-download"></a>You should already have downloaded the OpenACS tarball
+ to the <tt class="computeroutput">/tmp</tt> directory. If
not, <a href="individual-programs.html#openacs-download">download the OpenACS
tarball</a> and save it in
- <tt>/tmp</tt> and proceed:</p></li><li><p><a name="install-aolserver-user-accounts"></a>Set up your user account.</p><p>
+ <tt class="computeroutput">/tmp</tt> and proceed:</p></li><li><p><a name="install-aolserver-user-accounts"></a>Set up your user account.</p><p>
AOLserver needs to be started as the root user if you want to use
port 80. Once it starts, though, it will drop the root privileges and
run as another user, which you must specify on the command line. It's
@@ -29,36 +27,36 @@
for each different service. A service name should be a single
word, <span class="emphasis"><em>letters and numbers only</em></span>. If the name
of your site is one word, that would be a good choice. For
- example "<span class="replaceable">service0</span>" might be the service name for the
- <a href="http://service0.net/" target="_top"><span class="replaceable">service0</span>.net</a>
- community.</p><p>For the 5.0.0d-P and 5.0.0d-O Reference Platform,
- we'll use a server named <span class="replaceable">service0</span> and
- a user named <span class="replaceable">service0</span>. We'll leave the password
+ example "<span class="replaceable"><span class="replaceable">service0</span></span>" might be the service name for the
+ <a href="http://service0.net/" target="_top"><span class="replaceable"><span class="replaceable">service0</span></span>.net</a>
+ community.</p><p>For the 5.0.0a1-P and 5.0.0a1-O Reference Platform,
+ we'll use a server named <span class="replaceable"><span class="replaceable">service0</span></span> and
+ a user named <span class="replaceable"><span class="replaceable">service0</span></span>. We'll leave the password
blank for increased security. The only way to log in will be
with ssh certificates. The only people who should log in are
developers for that specific instance. Add this user, and put
- it in the <tt>web</tt> group so that it
+ it in the <tt class="computeroutput">web</tt> group so that it
can use database commands associated with that group.
- </p><pre class="screen">[root@yourserver root]# <b><tt>useradd -g web <span class="replaceable">service0</span> -d /home/<span class="replaceable">service0</span></tt></b>
+ </p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>useradd -g web <span class="replaceable"><span class="replaceable">service0</span></span> -d /home/<span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
[root@yourserver root]#</pre><p>Set up database environment variables. They are
necessary for working with the database.
-</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>emacs .bashrc</tt></b></pre><p>Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.</p><div class="itemizedlist"><ul type="disc"><li><p>PostGreSQL:</p><pre class="programlisting">export LD_LIBRARY_PATH=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
+</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>emacs .bashrc</tt></b></pre><p>Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.</p><div class="itemizedlist"><ul type="disc"><li><p>PostGreSQL:</p><pre class="programlisting">export LD_LIBRARY_PATH=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
export PATH=$PATH:/usr/local/pgsql/bin</pre></li><li><p>Oracle. These environment variables are specific for a local Oracle
installation communicating via IPC. If you are connecting to a remote
Oracle installation, you'll need to adjust these appropriately. Also,
make sure that the '8.1.7' matches your Oracle version.
</p><pre class="programlisting">export ORACLE_BASE=/ora8/m01/app/oracle
-export ORACLE_HOME=$ORACLE_BASE/product/<span class="replaceable">8.1.7</span>
+export ORACLE_HOME=$ORACLE_BASE/product/<span class="replaceable"><span class="replaceable">8.1.7</span></span>
export PATH=$PATH:$ORACLE_HOME/bin
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
export ORACLE_SID=ora8
export ORACLE_TERM=vt100
export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre></li></ul></div><p>Test this by logging out and back in as
- <tt><span class="replaceable">service0</span></tt> and checking the paths.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
+ <tt class="computeroutput"><span class="replaceable"><span class="replaceable">service0</span></span></tt> and checking the paths.</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver src]# <b><tt>su - <b><tt><span class="replaceable">service0</span></tt></b></tt></b>
-[postgres@yourserver pgsql]$ <b><tt>env | grep PATH</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>su - <b class="userinput"><tt><span class="replaceable"><span class="replaceable">service0</span></span></tt></b></tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>env | grep PATH</tt></b>
</pre><p>For PostGreSQL, you should see:</p><pre class="screen">
LD_LIBRARY_PATH=LD_LIBRARY_PATH=:/usr/local/pgsql/lib
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin</pre><p>For Oracle:</p><pre class="screen">ORACLE_BASE=/ora8/m01/app/oracle
@@ -67,56 +65,56 @@
LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib
ORACLE_SID=ora8
ORACLE_TERM=vt100
-ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
+ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver root]#</pre></li><li><p><a name="unpack-openacs"></a>Unpack the OpenACS tarball and rename it to <tt>service0</tt>. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>cd /web</tt></b>
-[service0@yourserver web]$ <b><tt>tar xzf /tmp/openacs-5.0.0d.tgz</tt></b>
-[service0@yourserver web]$ <b><tt>mv openacs-5.0.0d <span class="replaceable">service0</span></tt></b>
-[service0@yourserver web]$ <b><tt>chmod -R 700 <span class="replaceable">service0</span></tt></b>
-[service0@yourserver web]$ <b><tt>ls -al</tt></b>
+[root@yourserver root]#</pre></li><li><p><a name="unpack-openacs"></a>Unpack the OpenACS tarball and rename it to <tt class="computeroutput">service0</tt>. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cd /var/lib/aolserver</tt></b>
+[service0@yourserver aolserver]$ <b class="userinput"><tt>tar xzf /tmp/openacs-5.0.0a1.tgz</tt></b>
+[service0@yourserver aolserver]$ <b class="userinput"><tt>mv openacs-5.0.0a1 <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver aolserver]$ <b class="userinput"><tt>chmod -R 700 <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver aolserver]$ <b class="userinput"><tt>ls -al</tt></b>
total 3
drwxrwx--- 3 root web 1024 Mar 29 16:41 .
drwxr-xr-x 25 root root 1024 Mar 29 16:24 ..
drwx------ 7 service0 web 1024 Jan 6 14:36 service0
-[service0@yourserver web]$ <b><tt>exit</tt></b>
+[service0@yourserver aolserver]$ <b class="userinput"><tt>exit</tt></b>
logout
[root@yourserver root]#
-<pre class="action">su - service0
-cd /web
-tar xzf /tmp/openacs-5.0.0d.tgz
-mv openacs-5.0.0d service0
+<pre class="action"><span class="action">su - service0
+cd /var/lib/aolserver
+tar xzf /tmp/openacs-5.0.0a1.tgz
+mv openacs-5.0.0a1 service0
chmod -R 700 service0/
-exit</pre></pre></li><li><p><a href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL">Add the Service to CVS</a> (OPTIONAL)</p></li><li><p>(This step should be obsoleted by the 5.0.0 tarball, as
+exit</span></pre></pre></li><li><p><a href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL">Add the Service to CVS</a> (OPTIONAL)</p></li><li><p>(This step should be obsoleted by the 5.0.0 tarball, as
these directories will be included in the tarball)Set up several additional directories in the service root:
- <tt>etc</tt> is for configuration and control files, <tt>log</tt> is for error and request (web page hit) log files, and <tt>database-backup</tt> is for database backup files. If you did the CVS step, note that these new directories are excluded from that step so that you can decide whether or not you want your logs and config files in source control.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>mkdir /web/<span class="replaceable">service0</span>/etc /web/<span class="replaceable">service0</span>/log /web/<span class="replaceable">service0</span>/database-backup</tt></b>
-[service0@yourserver web]$ <b><tt>exit</tt></b>
+ <tt class="computeroutput">etc</tt> is for configuration and control files, <tt class="computeroutput">log</tt> is for error and request (web page hit) log files, and <tt class="computeroutput">database-backup</tt> is for database backup files. If you did the CVS step, note that these new directories are excluded from that step so that you can decide whether or not you want your logs and config files in source control.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/log /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup</tt></b>
+[service0@yourserver aolserver]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver web]#
-<pre class="action">su - service0
-mkdir /web/<span class="replaceable">service0</span>/etc /web/<span class="replaceable">service0</span>/log /web/<span class="replaceable">service0</span>/database-backup
-exit</pre></pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-prepare-oracle"></a>Prepare Oracle for OpenACS</h3></div></div><p>If you won't be using Oracle, skip to <a href="openacs.html#install-openacs-prepare-postgres" title="Prepare PostgreSQL for an OpenACS Service">the section called “Prepare PostgreSQL for an OpenACS Service”</a></p><p>
+[root@yourserver aolserver]#
+<pre class="action"><span class="action">su - service0
+mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/log /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/database-backup
+exit</span></pre></pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-prepare-oracle"></a>Prepare Oracle for OpenACS</h3></div></div><div></div></div><p>If you won't be using Oracle, skip to <a href="openacs.html#install-openacs-prepare-postgres" title="Prepare PostgreSQL for an OpenACS Service">Section�, “Prepare PostgreSQL for an OpenACS Service”</a></p><p>
You should be sure that your user account
- (e.g. <tt><span class="replaceable">service0</span></tt>) is in the
- <tt>dba</tt> group.
+ (e.g. <tt class="computeroutput"><span class="replaceable"><span class="replaceable">service0</span></span></tt>) is in the
+ <tt class="computeroutput">dba</tt> group.
</p><div class="orderedlist"><ol type="1"><li><p>
Verify membership by typing
- <tt>groups</tt> when you login:
+ <tt class="computeroutput">groups</tt> when you login:
</p><pre class="programlisting">
-<span class="replaceable">service0</span>:~$ groups
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$ groups
dba web</pre><p>
If you do not see these groups, take the following action:
</p><pre class="programlisting">
-<span class="replaceable">service0</span>:~$ su -
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$ su -
Password: ************
-root:~# adduser <span class="emphasis"><em><span class="replaceable">service0</span></em></span> dba</pre><p>
+root:~# adduser <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span> dba</pre><p>
If you get an error about an undefined group, then add that group
manually:
@@ -125,15 +123,15 @@
root:~# groupadd dba
root:~# groupadd web</pre><p>
- Make sure to logout as <tt>root</tt> when
+ Make sure to logout as <tt class="computeroutput">root</tt> when
you are finished with this step and log back in as
your regular user.
</p></li><li><p>
Connect to Oracle using
- <tt>svrmgrl</tt> and login:
+ <tt class="computeroutput">svrmgrl</tt> and login:
</p><pre class="programlisting">
-<span class="replaceable">service0</span>:~$ svrmgrl
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$ svrmgrl
SVRMGR> connect internal
Connected.</pre><p>
@@ -156,31 +154,31 @@
Using the above output, you should determine where
to store your tablespace. As a general rule, you'll want to
store your tablespace on a mount point under the
- <tt>/ora8</tt> directory that is separate
+ <tt class="computeroutput">/ora8</tt> directory that is separate
from the Oracle system data files. By default, the Oracle system
- is on <tt>m01</tt>, so we will use
- <tt>m02</tt>. This enables your Oracle
+ is on <tt class="computeroutput">m01</tt>, so we will use
+ <tt class="computeroutput">m02</tt>. This enables your Oracle
system and database files to be on separate disks for optimized
performance. For more information on such a configuration, see
<a href="http://philip.greenspun.com/panda/databases-choosing" target="_top">Chapter
12</a> of <a href="http://philip.greenspun.com/panda/" target="_top">Philip's
book</a>. For this example, we'll use
- <tt>/ora8/m02/oradata/ora8/</tt>.
+ <tt class="computeroutput">/ora8/m02/oradata/ora8/</tt>.
</p></li><li><p>
Create the directory for the datafile; to do this,
- exit from <tt>svrmgrl</tt> and login as
- <tt>root</tt> for this step: </p><pre class="programlisting">
+ exit from <tt class="computeroutput">svrmgrl</tt> and login as
+ <tt class="computeroutput">root</tt> for this step: </p><pre class="programlisting">
SVRMGR> exit
-<span class="replaceable">service0</span>:~$ su -
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$ su -
Password: ************
root:~# mkdir -p /ora8/m02/oradata/ora8/
-root:~# chown <span class="emphasis"><em><span class="replaceable">service0</span></em></span>.web /ora8/m02/oradata/ora8
+root:~# chown <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>.web /ora8/m02/oradata/ora8
root:~# chmod 775 /ora8/m02/oradata/ora8
root:~# exit
-<span class="replaceable">service0</span>:~$</pre></li><li><p>
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$</pre></li><li><p>
Create a tablespace for the service. It is important that the
- tablespace can <tt>autoextend</tt>. This
+ tablespace can <tt class="computeroutput">autoextend</tt>. 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
@@ -189,11 +187,11 @@
tablespace.
</p><pre class="programlisting">
-<span class="replaceable">service0</span>:~$ svrmgrl
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$ svrmgrl
SVRMGR> connect internal;
-SVRMGR> create tablespace <span class="emphasis"><em><span class="replaceable">service0</span></em></span>
- datafile '/ora8/m02/oradata/ora8/<span class="emphasis"><em><span class="replaceable">service0</span></em></span>01.dbf'
+SVRMGR> create tablespace <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>
+ datafile '/ora8/m02/oradata/ora8/<span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>01.dbf'
size 50M
autoextend on
next 10M
@@ -202,26 +200,26 @@
uniform size 32K;</pre></li><li><p>
Create a database user for this service. Give the
user access to the tablespace and rights to connect. We'll use
- <tt><span class="replaceable">service0</span>password</tt> as our password.</p><p>
+ <tt class="computeroutput"><span class="replaceable"><span class="replaceable">service0</span></span>password</tt> as our password.</p><p>
Write down what you specify as <span class="emphasis"><em>service_name</em></span>
- (i.e. <tt><span class="replaceable">service0</span></tt>) and
+ (i.e. <tt class="computeroutput"><span class="replaceable"><span class="replaceable">service0</span></span></tt>) and
<span class="emphasis"><em>database_password</em></span>
- (i.e. <tt><span class="replaceable">service0</span>password</tt>). You
+ (i.e. <tt class="computeroutput"><span class="replaceable"><span class="replaceable">service0</span></span>password</tt>). You
will need this information for configuring exports and
AOLserver.
</p><pre class="programlisting">
-SVRMGR> create user <span class="emphasis"><em><span class="replaceable">service0</span></em></span> identified by <span class="emphasis"><em><span class="replaceable">service0</span>password</em></span> default tablespace <span class="emphasis"><em><span class="replaceable">service0</span></em></span>
-temporary tablespace temp quota unlimited on <span class="emphasis"><em><span class="replaceable">service0</span></em></span>;
-SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to <span class="emphasis"><em><span class="replaceable">service0</span></em></span>;
-SVRMGR> revoke unlimited tablespace from <span class="emphasis"><em><span class="replaceable">service0</span></em></span>;
-SVRMGR> alter user <span class="emphasis"><em><span class="replaceable">service0</span></em></span> quota unlimited on <span class="emphasis"><em><span class="replaceable">service0</span></em></span>;
+SVRMGR> create user <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span> identified by <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span>password</em></span> default tablespace <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>
+temporary tablespace temp quota unlimited on <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>;
+SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>;
+SVRMGR> revoke unlimited tablespace from <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>;
+SVRMGR> alter user <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span> quota unlimited on <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>;
SVRMGR> exit;</pre><p>
Your table space is now ready. In case you are trying to delete a
- previous OpenACS installation, consult these commands in <a href="database-management.html#install-openacs-delete-tablespace" title="Deleting a tablespace">the section called “Deleting a tablespace”</a> below.
+ previous OpenACS installation, consult these commands in <a href="database-management.html#install-openacs-delete-tablespace" title="Deleting a tablespace">Section�, “Deleting a tablespace”</a> below.
</p></li><li><p>
Make sure that you can login to Oracle using your
<span class="emphasis"><em>service_name</em></span> account: </p><pre class="programlisting">
-<span class="replaceable">service0</span>:~$ sqlplus <span class="emphasis"><em><span class="replaceable">service0</span></em></span>/<span class="emphasis"><em><span class="replaceable">service0</span>password</em></span>
+<span class="replaceable"><span class="replaceable">service0</span></span>:~$ sqlplus <span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>/<span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span>password</em></span>
SQL> select sysdate from dual;
SYSDATE
@@ -232,41 +230,41 @@
You should see today's date in a format 'YYYY-MM-DD.'
If you can't login, try redoing step 1 again. If the date is
in the wrong format, make sure you followed the steps outlined in
- <a href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">the section called “Troubleshooting Oracle Dates”</a>
- </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-prepare-postgres"></a>Prepare PostgreSQL for an OpenACS Service</h3></div></div><div class="orderedlist"><ol type="1"><li><p><a name="create-service-db-user"></a>Create a user in the database matching the service name.</p><pre class="screen">[root@yourserver root]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>createuser <span class="replaceable">service0</span></tt></b>
-Shall the new user be allowed to create databases? (y/n) <b><tt>y</tt></b>
-Shall the new user be allowed to create more new users? (y/n) <b><tt>y</tt></b>
+ <a href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">Section�, “Troubleshooting Oracle Dates”</a>
+ </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-prepare-postgres"></a>Prepare PostgreSQL for an OpenACS Service</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p><a name="create-service-db-user"></a>Create a user in the database matching the service name.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - postgres</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>createuser <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+Shall the new user be allowed to create databases? (y/n) <b class="userinput"><tt>y</tt></b>
+Shall the new user be allowed to create more new users? (y/n) <b class="userinput"><tt>y</tt></b>
CREATE USER
-[postgres@yourserver pgsql]$ <b><tt>exit</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver root]#</pre></li><li><p><a name="create-database"></a>Create a database with the same name as our service name, <span class="replaceable">service0</span>.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>createdb -E UNICODE <span class="replaceable">service0</span></tt></b>
+[root@yourserver root]#</pre></li><li><p><a name="create-database"></a>Create a database with the same name as our service name, <span class="replaceable"><span class="replaceable">service0</span></span>.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>createdb -E UNICODE <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
CREATE DATABASE
[service0@yourserver service0]$
-<pre class="action">su - <span class="replaceable">service0</span>
-createdb -E UNICODE <span class="replaceable">service0</span></pre></pre></li><li><p>Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user.</p><a class="indexterm" name="id2962087"></a><pre class="screen">[service0@yourserver service0]$ <b><tt>export EDITOR=emacs;crontab -e</tt></b></pre><p>Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.</p><pre class="programlisting">0 1 * * * /usr/local/pgsql/bin/vacuumdb --analyze <span class="replaceable">service0</span></pre></li><li><p><a href="install-full-text-search.html#install-openfts-postgres" title="Install OpenFTS prerequisites in PostGreSQL instance">Add Full Text Search Support</a> (OPTIONAL)</p></li><li><a name="db-setup-exit"></a><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
+<pre class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">service0</span></span>
+createdb -E UNICODE <span class="replaceable"><span class="replaceable">service0</span></span></span></pre></pre></li><li><p>Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user.</p><a class="indexterm" name="id2827345"></a><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>export EDITOR=emacs;crontab -e</tt></b></pre><p>Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.</p><pre class="programlisting">0 1 * * * /usr/local/pgsql/bin/vacuumdb --analyze <span class="replaceable"><span class="replaceable">service0</span></span></pre></li><li><p><a href="install-full-text-search.html#install-openfts-postgres" title="Install OpenFTS prerequisites in PostGreSQL instance">Add Full Text Search Support</a> (OPTIONAL)</p></li><li><a name="db-setup-exit"></a><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>exit</tt></b>
logout
-[root@yourserver root]# </pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-configure-aol"></a>Configure an AOLserver Service for OpenACS</h3></div></div><div class="orderedlist"><ol type="1"><li><p><a name="configure-config-tcl"></a>
+[root@yourserver root]# </pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-configure-aol"></a>Configure an AOLserver Service for OpenACS</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p><a name="configure-config-tcl"></a>
The AOLserver architecture lets you run an arbitrary number of
virtual servers. A virtual server is an HTTP service running on a
specific port, e.g. port 80. In order for OpenACS to work, you
need to configure a virtual server. The Reference Platform
uses a configuration file included in the OpenACS tarball,
- <tt>/web/<span class="replaceable">service0</span>/etc/config.tcl</tt>.
- Open it in an editor to adjust the parameters.</p><a class="indexterm" name="id2962225"></a><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>cd /web/<span class="replaceable">service0</span>/etc</tt></b>
-[service0@yourserver etc]# <b><tt>emacs config.tcl</tt></b>
+ <tt class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/config.tcl</tt>.
+ Open it in an editor to adjust the parameters.</p><a class="indexterm" name="id2827455"></a><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>su - <span class="replaceable"><span class="replaceable">service0</span></span></tt></b>
+[service0@yourserver service0]$ <b class="userinput"><tt>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc</tt></b>
+[service0@yourserver etc]# <b class="userinput"><tt>emacs config.tcl</tt></b>
</pre><p>
- You can continue without changing any values in the file. However, if you don't change <tt>address</tt> to match the computer's ip address, you won't be able to browse to your server from other machines.
+ You can continue without changing any values in the file. However, if you don't change <tt class="computeroutput">address</tt> to match the computer's ip address, you won't be able to browse to your server from other machines.
</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>httpport</em></span> - If you want your
server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.</p></li><li><p><span class="emphasis"><em>httpsport</em></span> - This is the
port for https requests. The Reference Platform https port is
8443. If http port is set to 80, httpsport should be 143 to
match the standard.</p></li><li><p>
- <span class="emphasis"><em>address</em></span> - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.</p></li><li><p><span class="emphasis"><em>server</em></span> - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses <span class="replaceable">service0</span>.
+ <span class="emphasis"><em>address</em></span> - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.</p></li><li><p><span class="emphasis"><em>server</em></span> - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses <span class="replaceable"><span class="replaceable">service0</span></span>.
</p></li><li><p><span class="emphasis"><em>db_name</em></span> - In almost all cases,
this can be kept as a reference to $server. If for some reason,
@@ -281,56 +279,56 @@
started, but for more options, read the <a href="http://aolserver.com/docs/admin/config.html" target="_top">AOLServer
docs</a>.
</p></li><li><p><a href="install-full-text-search.html#enable-openfts" title="Enable OpenFTS in config.tcl">Enable OpenFTS Full Text Search</a> (OPTIONAL)</p></li><li><p><a href="maintenance-web.html#install-ssl" title="Installing SSL Support">Install nsopenssl
- for SSL support.</a> (OPTIONAL)</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="verify-aolserver-startup"></a>Verify AOLserver startup</h3></div></div><div class="orderedlist"><ol type="1"><li><p><a name="start-aolserver"></a>
+ for SSL support.</a> (OPTIONAL)</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="verify-aolserver-startup"></a>Verify AOLserver startup</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p><a name="start-aolserver"></a>
Kill any current running AOLserver processes and start a new
one. If you are using Oracle, rather than PostgreSQL, replace
- <tt>nsd-postgres</tt> with
- <tt>nsd-oracle</tt>).</p><p>If you want to use port 80, there are complications.
+ <tt class="computeroutput">nsd-postgres</tt> with
+ <tt class="computeroutput">nsd-oracle</tt>).</p><p>If you want to use port 80, there are complications.
First, Aolserver must be root to use system ports such as
80, but refuses to run as root for security reasons. Thus
you must start as root and specify a non-root user ID and
Group ID which Aolserver will switch to after claiming the
port. To do so, find the UID and GID of the
- <span class="replaceable">service0</span> user via
- <tt>grep <span class="replaceable">service0</span>
+ <span class="replaceable"><span class="replaceable">service0</span></span> user via
+ <tt class="computeroutput">grep <span class="replaceable"><span class="replaceable">service0</span></span>
/etc/passwd</tt> and then put those numbers into
- the command line via <tt>-u
- <span class="replaceable">501</span> -g
- <span class="replaceable">502</span></tt>. Second, if you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do <tt>ps -auxw | grep
- nsd</tt> and selectively kill by job number.</p><pre class="screen">[service0@yourserver etc]$ <b><tt>killall nsd</tt></b>
+ the command line via <tt class="computeroutput">-u
+ <span class="replaceable"><span class="replaceable">501</span></span> -g
+ <span class="replaceable"><span class="replaceable">502</span></span></tt>. Second, if you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do <tt class="computeroutput">ps -auxw | grep
+ nsd</tt> and selectively kill by job number.</p><pre class="screen">[service0@yourserver etc]$ <b class="userinput"><tt>killall nsd</tt></b>
nsd: no process killed
-[service0@yourserver service0]$<b><tt> /usr/local/aolserver/bin/nsd-postgres -t /web/<span class="replaceable">service0</span>/etc/config.tcl</tt></b>
+[service0@yourserver service0]$<b class="userinput"><tt> /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/config.tcl</tt></b>
[service0@yourserver service0]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file...
[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.</pre></li><li><p><a name="connect-to-aolserver"></a>
Attempt to connect to the service from a web browser. You should specify a URL like:
- </p><tt>http://<span class="replaceable">yourserver.test</span>:8000</tt><p>
+ </p><tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>:8000</tt><p>
You should see a page that looks like <a href="files/openacs-start.html" target="_top">this</a>. If you <a href="cvs-service-import.html" title="Add the Service to CVS - OPTIONAL">imported your files into
cvs</a>, now that you know it worked you can erase the temp
- directory with <tt>rm -rf /web/service0.orig</tt>.
+ directory with <tt class="computeroutput">rm -rf /var/lib/aolserver/service0.orig</tt>.
</p><p>
If you don't see the login page, view your error log
- (<tt>/web/<span class="replaceable">service0</span>/log/<span class="replaceable">service0</span>-error.log</tt>)
+ (<tt class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/log/<span class="replaceable"><span class="replaceable">service0</span></span>-error.log</tt>)
to make sure the service is starting without any
problems. The most common errors here are trying to start a
port 80 server while not root, failing to connect because of
a firewall, and aolserver failing to start due to
permissions errors or missing files. If you need to make
changes, don't forget to kill any running servers with
- <b><tt>killall nsd</tt></b>.
+ <b class="userinput"><tt>killall nsd</tt></b>.
</p></li><li><p><a href="maintenance-web.html#install-openacs-keepalive" title="">Automate
- AOLserver keepalive</a> (OPTIONAL)</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-using-installer"></a>Configure a Service with the OpenACS Installer</h3></div></div><p>
+ AOLserver keepalive</a> (OPTIONAL)</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-using-installer"></a>Configure a Service with the OpenACS Installer</h3></div></div><div></div></div><p>
Now that you've got AOLserver up and running, let's install OpenACS
- 5.0.0d.
+ 5.0.0a1.
</p><div class="itemizedlist"><ul type="disc"><li><p>
You should see a page from the webserver titled
- <tt>OpenACS Installation:
+ <tt class="computeroutput">OpenACS Installation:
Welcome</tt>. You will be warned if your version of
the database driver is out of date, if AOLserver cannot connect
to the database, if any modules are missing or out-of-date, or if
there are any problems with filesystem permissions on the server
side. But if everything is fine, you can click
- <tt>Next</tt> to proceed to load the
+ <tt class="computeroutput">Next</tt> to proceed to load the
OpenACS Kernel data model.
</p></li><li><p>
@@ -343,44 +341,44 @@
Loading package .info files ... this will take a few minutes</pre><p>
This will really take a few minutes. Have faith! Finally, another
- <tt>Next</tt> button will appear at the
+ <tt class="computeroutput">Next</tt> button will appear at the
bottom - click it.
</p></li><li><p>
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
- <tt>Next</tt>.
+ errors. Eventually, the page will display "Generating secret
+ tokens" and then "Done"- click
+ <tt class="computeroutput">Next</tt>.
</p></li><li><p>
- You should see a page, "OpenACS Installation: Create
- Administrator" with form fields to define the OpenACS site
+ You should see a page, "OpenACS Installation: Create
+ Administrator" with form fields to define the OpenACS site
administrator. Fill out the fields as appropriate, and click
- <tt>Create User</tt>.
+ <tt class="computeroutput">Create User</tt>.
</p></li><li><p>
- You should see a page, "OpenACS Installation: Set System
- Information" allowing you to name your service. Fill out the
- fields as appropriate, and click <tt>Set System
+ You should see a page, "OpenACS Installation: Set System
+ Information" allowing you to name your service. Fill out the
+ fields as appropriate, and click <tt class="computeroutput">Set System
Information</tt>
</p></li><li><p>
- You'll see the final Installer page, "OpenACS
- Installation: Complete." It will tell you that the server is
+ You'll see the final Installer page, "OpenACS
+ Installation: Complete." It will tell you that the server is
being restarted; note that unless you already set up a way for
AOLServer to restart itself (ie. inittab or daemontools),
you'll need to manually restart your service.
- </p><pre class="screen">[service0@yourserver service0]$ <b><tt>/usr/local/aolserver/bin/nsd-postgres -t /web/<span class="emphasis"><em><span class="replaceable">service0</span></em></span>/config.tcl</tt></b></pre></li><li><p>
+ </p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>/usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<span class="emphasis"><em><span class="replaceable"><span class="replaceable">service0</span></span></em></span>/config.tcl</tt></b></pre></li><li><p>
Give the server a few minutes to start up. Then
reload the final page above. You should see the front page, with
an area to login near the upper right. Congratulations, OpenACS
- 5.0.0d is now up and running!
+ 5.0.0a1 is now up and running!
</p></li><li><p>Install Full Text Search (OPTIONAL). If you have <a href="install-full-text-search.html#install-openfts" title="Install OpenFTS module">installed OpenFTS</a> and enabled
OpenFTS, you can now <a href="install-full-text-search.html#install-fts-engine" title="Install Full Text Search Engine">install</a> the OpenFTS Driver package and
- Full Text Search Engine package in the OpenACS service.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2916160"></a>Next Steps</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>This is a good time to make a <a href="backup-recovery.html#snapshot-backup" title="Snapshot backup and recovery">backup</a> of your service. If this is a
+ Full Text Search Engine package in the OpenACS service.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2829226"></a>Next Steps</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>This is a good time to make a <a href="backup-recovery.html#snapshot-backup" title="Snapshot backup and recovery">backup</a> of your service. If this is a
production site, you should set up <a href="backup-recovery.html#automated-backup" title="Automated Backup (OPTIONAL)">automatic nightly backups</a>.</p></li><li><p>If you want traffic reports, <a href="maintenance-web.html#analog-setup" title="Set up Log Analysis Reports - OPTIONAL">set up analog</a> or another log
processing program.</p></li><li><p>Follow the instruction on the home page to
change the appearance of your service or add more
Index: openacs-4/packages/acs-core-docs/www/oracle.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/oracle.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/oracle.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Oracle 8.1.7</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="linux-installation.html" title="Install Linux and supporting software"><link rel="next" href="postgres.html" title="Install PostGreSQL"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="linux-installation.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="oracle"></a>Install Oracle 8.1.7</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install Oracle 8.1.7</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="linux-installation.html" title="Install Linux and supporting software"><link rel="next" href="postgres.html" title="Install PostGreSQL"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="linux-installation.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="oracle"></a>Install Oracle 8.1.7</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -9,15 +8,15 @@
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
- OpenACS 5.0.0d does not yet work with Oracle 9i
+ OpenACS 5.0.0a1 does not yet work with Oracle 9i
</p><p>
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 <a href="http://openacs.org/new-file-storage/one-file?file_id=273" target="_top">document</a>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-getit"></a>Acquire Oracle 8.1.7 Enterprise Edition</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-getit"></a>Acquire Oracle 8.1.7 Enterprise Edition</h3></div></div><div></div></div><p>
You can obtain the software through a variety of methods (You'll need
to become a member of <a href="http://technet.oracle.com" target="_top">technet.oracle.com</a>, which is
@@ -61,34 +60,34 @@
It used to be possible to get a free CD by mail, but
I can no longer find the link for that option.
- </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-keepinmind"></a>Things to Keep in Mind</h3></div></div><p>
+ </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-keepinmind"></a>Things to Keep in Mind</h3></div></div><div></div></div><p>
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 <a href="oracle.html#install-oracle-defaults" title="Defaults">the section called “Defaults”</a>.
+ later. For a guide to the defaults, please see <a href="oracle.html#install-oracle-defaults" title="Defaults">Section�, “Defaults”</a>.
</p><p>
For additional resources/documentation, please see this <a href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0003o2&topic_id=11&topic=OpenACS" target="_top">thread</a>
and <a href="http://openacs.org/forums/message-view?message_id=67108" target="_top">Andrew
Piskorski's mini-guide</a>..
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-preinstall"></a>Pre-Installation Tasks</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-preinstall"></a>Pre-Installation Tasks</h3></div></div><div></div></div><p>
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
- <tt>root</tt> user. We recommend entering the
- X window system as a normal user and then doing a <tt>su
+ <tt class="computeroutput">root</tt> user. We recommend entering the
+ X window system as a normal user and then doing a <tt class="computeroutput">su
-</tt>. This command gives you full root access.
</p><div class="itemizedlist"><ul type="disc"><li><p>
Login as a non-root user and start X by typing
- <tt>startx</tt>
+ <tt class="computeroutput">startx</tt>
</p><pre class="programlisting">
joeuser:~$ startx</pre><p>
@@ -104,12 +103,12 @@
</p></li><li><p>
- Create and setup the <tt>oracle</tt>
- group and <tt>oracle</tt> account
+ Create and setup the <tt class="computeroutput">oracle</tt>
+ group and <tt class="computeroutput">oracle</tt> account
</p><p>
- We need to create a user <tt>oracle</tt>,
+ We need to create a user <tt class="computeroutput">oracle</tt>,
which is used to install the product, as well as starting and
stopping the database.
@@ -127,13 +126,13 @@
Setup the installation location for Oracle. While Oracle can
reside in a variety of places in the file system, OpenACS has
- adopted <tt>/ora8</tt> as the base
+ adopted <tt class="computeroutput">/ora8</tt> as the base
directory.
</p><p>
<span class="strong">Note:</span> the Oracle install needs
- about 1 GB free on <tt>/ora8</tt> to
+ about 1 GB free on <tt class="computeroutput">/ora8</tt> to
install successfully.
</p><pre class="programlisting">
@@ -143,22 +142,22 @@
root:/ora8# chown -R oracle.dba /ora8
root:/ora8# exit</pre></li><li><p>
- Set up the <tt>oracle</tt> user's
+ Set up the <tt class="computeroutput">oracle</tt> user's
environment
</p><div class="itemizedlist"><ul type="circle"><li><p>
Log in as the user
- <tt>oracle</tt> by typing the
+ <tt class="computeroutput">oracle</tt> by typing the
following:
</p><pre class="programlisting">
joeuser:~$ su - oracle
Password: ********</pre></li><li><p>
Use a text editor to edit the
- <tt>.bash_profile</tt> file in the
- <tt>oracle</tt> account home
+ <tt class="computeroutput">.bash_profile</tt> file in the
+ <tt class="computeroutput">oracle</tt> account home
directory.
</p><pre class="programlisting">
@@ -167,7 +166,7 @@
You may get this error trying to start emacs:
</p><pre class="programlisting">
-Xlib: connection to ":0.0" refused by server
+Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server
emacs: Cannot connect to X server :0.
Check the DISPLAY environment variable or use `-d'.
@@ -192,7 +191,7 @@
Add the following lines (substituting your
Oracle version number as needed) to
- <tt>.bash_profile</tt>:
+ <tt class="computeroutput">.bash_profile</tt>:
</p><pre class="programlisting">
export ORACLE_BASE=/ora8/m01/app/oracle
@@ -205,9 +204,9 @@
umask 022</pre><p>
- Save the file by typing <tt>CTRL-X
+ Save the file by typing <tt class="computeroutput">CTRL-X
CTRL-S</tt> and then exit by typing
- <tt>CTRL-X
+ <tt class="computeroutput">CTRL-X
CTRL-C</tt>. Alternatively, use the menus.
</p></li></ul></div><p>
@@ -230,11 +229,11 @@
</p><pre class="programlisting">
oracle:~$ exit</pre></li><li><p>
- Log back in as <tt>oracle</tt> and double
+ Log back in as <tt class="computeroutput">oracle</tt> and double
check that your environment variables are as intended. The
- <tt>env</tt> command lists all of the
+ <tt class="computeroutput">env</tt> command lists all of the
variables that are set in your environment, and
- <tt>grep</tt> shows you just the lines
+ <tt class="computeroutput">grep</tt> shows you just the lines
you want (those with ORA in it).
</p><pre class="programlisting">
@@ -251,47 +250,47 @@
ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data</pre><p>
If not, try adding the files to
- <tt>~/.bashrc</tt> instead of
- <tt>.bash_profile</tt>. Then logout and
+ <tt class="computeroutput">~/.bashrc</tt> instead of
+ <tt class="computeroutput">.bash_profile</tt>. Then logout and
log back in again. Also, be certain you are doing
- <tt>su - oracle</tt> and not just
- <tt>su oracle</tt>. The
- <tt>-</tt> means that
- <tt>.bashrc</tt> and
- <tt>.bash_profile</tt> will be
+ <tt class="computeroutput">su - oracle</tt> and not just
+ <tt class="computeroutput">su oracle</tt>. The
+ <tt class="computeroutput">-</tt> means that
+ <tt class="computeroutput">.bashrc</tt> and
+ <tt class="computeroutput">.bash_profile</tt> will be
evaluated.
</p><p>
- Make sure that <tt>/bin</tt>,
- <tt>/usr/bin</tt>, and
- <tt>/usr/local/bin</tt> are in your path
+ Make sure that <tt class="computeroutput">/bin</tt>,
+ <tt class="computeroutput">/usr/bin</tt>, and
+ <tt class="computeroutput">/usr/local/bin</tt> are in your path
by typing:
</p><pre class="programlisting">
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</pre><p>
If they are not, then add them to the
- <tt>.bash_profile</tt> by changing the
+ <tt class="computeroutput">.bash_profile</tt> by changing the
PATH statement above to
- <tt>PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin</tt>
+ <tt class="computeroutput">PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin</tt>
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-install"></a>Installing Oracle 8.1.7 Server</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
- Log in as <tt>oracle</tt> and
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-install"></a>Installing Oracle 8.1.7 Server</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+ Log in as <tt class="computeroutput">oracle</tt> and
start X if not already running. Start a new terminal:
</p><pre class="programlisting">
joeuser:~$ xhost +localhost
joeuser:~$ su - oracle
Password: **********
oracle:~$ export DISPLAY=localhost:0.0</pre></li><li><p>
- Find the <tt>runInstaller</tt> script
+ Find the <tt class="computeroutput">runInstaller</tt> script
</p><div class="itemizedlist"><ul type="circle"><li><p>
If you are installing Oracle from a CD-ROM, it is located in
- the <tt>install/linux</tt> path from
+ the <tt class="computeroutput">install/linux</tt> path from
the cd-rom mount point
</p><pre class="programlisting">
@@ -301,7 +300,7 @@
oracle:~$ cd /mnt/cdrom</pre></li><li><p>
If you are installing from the tarball, the install script is
- located in the <tt>Oracle8iR2</tt>
+ located in the <tt class="computeroutput">Oracle8iR2</tt>
directory that was created when you expanded the archive.
</p><pre class="programlisting">
@@ -314,7 +313,7 @@
doc index.htm install runInstaller stage starterdb</pre><p>
If you don't see
- <tt>runInstaller</tt>, you are in the
+ <tt class="computeroutput">runInstaller</tt>, you are in the
wrong directory.
</p></li><li><p>
@@ -326,73 +325,73 @@
A window will open that welcomes you to the 'Oracle Universal
Installer' (OUI). Click on
- "<tt>Next</tt>"
+ "<tt class="computeroutput">Next</tt>"
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Some people have had trouble with this step on RedHat 7.3 and 8.0. If
so, try the following steps before calling
- <b>./runInstaller</b>:
+ <b class="command">./runInstaller</b>:
</p><div class="orderedlist"><ol type="1"><li><p>
Execute the following command:
- <b>/usr/i386-glib21-linux/bin/i386-glibc21-linux-env.sh</b>
+ <b class="command">/usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh</b>
</p></li><li><p>
- Type <b>export LD_ASSUME_KERNEL=2.2.5</b>
+ Type <b class="command">export LD_ASSUME_KERNEL=2.2.5</b>
</p></li></ol></div></div></li><li><p>
- The "File Locations" screen in the OUI:
+ The "File Locations" screen in the OUI:
</p><div class="itemizedlist"><ul type="circle"><li><p>
- "Source" path should have been
- prefilled with "(wherever you mounted the
- CDROM)<tt>/stage/products.jar</tt>"
+ "Source" path should have been
+ prefilled with "(wherever you mounted the
+ CDROM)<tt class="computeroutput">/stage/products.jar</tt>"
</p></li><li><p>
- "destination" path says
- "<tt>/ora8/m01/app/oracle/product/8.1.7</tt>"
+ "destination" path says
+ "<tt class="computeroutput">/ora8/m01/app/oracle/product/8.1.7</tt>"
</p><p>
If the destination is not correct it is because your
environment variables are not set properly. Make sure you
- logged on as <tt>oracle</tt> using
- <tt>su - oracle</tt>. If so, edit the
- <tt>~/.bash_profile</tt> as you
- did in <a href="oracle.html#install-oracle-preinstall" title="Pre-Installation Tasks">the section called “Pre-Installation Tasks”</a>
+ logged on as <tt class="computeroutput">oracle</tt> using
+ <tt class="computeroutput">su - oracle</tt>. If so, edit the
+ <tt class="computeroutput">~/.bash_profile</tt> as you
+ did in <a href="oracle.html#install-oracle-preinstall" title="Pre-Installation Tasks">Section�, “Pre-Installation Tasks”</a>
</p></li><li><p>
- Click "Next" (a pop up window will display Loading
+ Click "Next" (a pop up window will display Loading
Product information).
</p></li></ul></div></li><li><p>
- The "Unix Group Name" screen in the OUI:
+ The "Unix Group Name" screen in the OUI:
</p><div class="itemizedlist"><div class="itemizedlist"><ul type="disc"><li><p>
Debian users need to link
- <tt>/bin/awk</tt> to
- <tt>/usr/bin/awk</tt> before
+ <tt class="computeroutput">/bin/awk</tt> to
+ <tt class="computeroutput">/usr/bin/awk</tt> before
running the script below
</p><pre class="programlisting">
joueser:~$ su -
root:~# ln -s /usr/bin/awk /bin/awk</pre></li></ul></div><ul type="circle"><li><p>
The Unix Group name needs to be set to
- '<tt>oinstall</tt>' ( we made
+ '<tt class="computeroutput">oinstall</tt>' ( we made
this Unix group earlier ).
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li><li><p>
@@ -414,162 +413,162 @@
root:~# exit
joeuser:~$ exit</pre></li><li><p>
- Click "Retry"
+ Click "Retry"
</p></li></ul></div></li><li><p>
- The "Available Products" screen in the OUI:
+ The "Available Products" screen in the OUI:
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "Oracle 8i Enterprise Edition 8.1.7.1.0"
+ Select "Oracle 8i Enterprise Edition 8.1.7.1.0"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Installation Types" screen
+ The "Installation Types" screen
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select the "Custom" installation type.
+ Select the "Custom" installation type.
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Available Product Components" screen
+ The "Available Product Components" screen
</p><div class="itemizedlist"><ul type="circle"><li><p>
- In addition to the defaults, make sure that "Oracle SQLJ
- 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and
- "Linux Documentation 8.1.7.0.0" are also checked.
+ In addition to the defaults, make sure that "Oracle SQLJ
+ 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and
+ "Linux Documentation 8.1.7.0.0" are also checked.
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li><li><p>
A progress bar will appear for about 1 minute.
</p></li></ul></div></li><li><p>
- The "Component Locations" screen in the OUI
+ The "Component Locations" screen in the OUI
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Click on the "Java Runtime Environment 1.1.8" It
+ Click on the "Java Runtime Environment 1.1.8" It
should have the path
- "<tt>/ora8/m01/app/oracle/jre/1.1.8</tt>"
+ "<tt class="computeroutput">/ora8/m01/app/oracle/jre/1.1.8</tt>"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li><li><p>
A progress bar will appear for about 1 minute.
</p></li></ul></div></li><li><p>
- The "Privileged Operation System Groups" screen in the
+ The "Privileged Operation System Groups" screen in the
OUI
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Enter "dba" for "Database Administrator
- (OSDBA) Group"
+ Enter "dba" for "Database Administrator
+ (OSDBA) Group"
</p></li><li><p>
- Enter "dba" for the "Database Operator
- (OSOPER) Group"
+ Enter "dba" for the "Database Operator
+ (OSOPER) Group"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li><li><p>
A progress bar will appear for about 1 minute.
</p></li></ul></div></li><li><p>
- The "Authentication Methods" screen
+ The "Authentication Methods" screen
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The next screen is "Choose JDK home directory"
+ The next screen is "Choose JDK home directory"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Keep the default path: <tt>/usr/local/java</tt>
+ Keep the default path: <tt class="computeroutput">/usr/local/java</tt>
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Create a Database" screen in the OUI
+ The "Create a Database" screen in the OUI
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "No" as we will do this later, after some
+ Select "No" as we will do this later, after some
important configuration changes.
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The next screen is "Oracle Product Support"
+ The next screen is "Oracle Product Support"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- TCP should be checked with "Status" listed as
+ TCP should be checked with "Status" listed as
Required
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Summary" screen in the OUI
+ The "Summary" screen in the OUI
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Check the "Space Requirements" section to verify
+ Check the "Space Requirements" section to verify
you have enough disk space for the install.
</p></li><li><p>
- Check that "(144 products)" is in the "New
- Installations" section title.
+ Check that "(144 products)" is in the "New
+ Installations" section title.
</p></li><li><p>
- Click "Install"
+ Click "Install"
</p></li><li><p>
A progress bar will appear for about 20 - 30 minutes. Now is a
good time to take a break.
</p></li><li><p>
- A "Setup Privileges" window will popup towards the
+ A "Setup Privileges" window will popup towards the
end of the installation asking you to run a script as
- <tt>root</tt>
+ <tt class="computeroutput">root</tt>
</p></li><li><p>
Run the script. Switch to the oracle user first
to set the environment appropriately and then do
- <b>su</b> to get root privileges, while keeping
+ <b class="command">su</b> to get root privileges, while keeping
the oracle user's enviroment.
</p><pre class="programlisting">
joeuser:~$ su - oracle
@@ -590,7 +589,7 @@
Enter the full pathname of the local bin directory: [/usr/local/bin]:
-<tt>Press ENTER here to accept default of /usr/local/bin</tt>
+<tt class="computeroutput">Press ENTER here to accept default of /usr/local/bin</tt>
Creating /etc/oratab file...
@@ -608,93 +607,93 @@
</p></li></ul></div><pre class="programlisting">
root:~# exit
joeuser:~$ exit</pre></li><li><p>
- Go back to the pop-up window and click "OK"
+ Go back to the pop-up window and click "OK"
</p></li><li><p>
- The "Configuration Tools" screen in the OUI
+ The "Configuration Tools" screen in the OUI
</p><div class="itemizedlist"><ul type="circle"><li><p>
This window displays the config tools that will automatically
be launched.
</p></li></ul></div></li><li><p>
- The "Welcome" screen in the "net 8 Configuration
- Assistant"
+ The "Welcome" screen in the "net 8 Configuration
+ Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Make sure the "Perform Typical installation" is
+ Make sure the "Perform Typical installation" is
<span class="strong">not</span> selected.
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li><li><p>
- The "Directory Service Access" screen in the
- "Net 8 Configuration Assistant"
+ The "Directory Service Access" screen in the
+ "Net 8 Configuration Assistant"
</p></li><li><p>
- Select "No"
+ Select "No"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Listener Configuration, Listener Name" screen in
- the "Net 8 Configuration Assistant"
+ The "Listener Configuration, Listener Name" screen in
+ the "Net 8 Configuration Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Accept the default listener name of "LISTENER"
+ Accept the default listener name of "LISTENER"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Listener Configuration, Select
- Protocols" screen in the "Net 8 Configuration
- Assistant"
+ The "Listener Configuration, Select
+ Protocols" screen in the "Net 8 Configuration
+ Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- The only choice in "Select protocols:" should be
- "TCP/IP"
+ The only choice in "Select protocols:" should be
+ "TCP/IP"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Listener Configuration TCP/IP Protocol" screen in
- the "Net 8 Configuration Assistant"
+ The "Listener Configuration TCP/IP Protocol" screen in
+ the "Net 8 Configuration Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
Default Port should be 1521 and selected.
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Listener Configuration, More Listeners" screen in
- the "Net 8 Configuration Assistant"
+ The "Listener Configuration, More Listeners" screen in
+ the "Net 8 Configuration Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "No"
+ Select "No"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Listener Configuration Done" screen in the
- "Net 8 Configuration Assistant"
+ The "Listener Configuration Done" screen in the
+ "Net 8 Configuration Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Naming Methods Configuration" screen
- in the "Net 8 Configuration Assistant"
+ The "Naming Methods Configuration" screen
+ in the "Net 8 Configuration Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "No"
+ Select "No"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Done" screen in the "Net 8 Configuration
- Assistant"
+ The "Done" screen in the "Net 8 Configuration
+ Assistant"
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Click "Finish"
+ Click "Finish"
</p></li></ul></div></li><li><p>
- The "End of Installation" screen in the OUI
+ The "End of Installation" screen in the OUI
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Click "Exit"
+ Click "Exit"
</p></li><li><p>
- Click "Yes" on the confirmation pop up window.
+ Click "Yes" on the confirmation pop up window.
</p></li><li><p>
The Oracle Universal Installer window should have disappeared!
</p></li></ul></div></li></ul></div><p>
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.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-create"></a>Creating the First Database</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-create"></a>Creating the First Database</h3></div></div><div></div></div><p>
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.
- </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>RedHat 7.3 and 8.0 users: Before running <b>dbassist</b>, do the following.</p><div class="orderedlist"><ol type="1"><li><p>
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>RedHat 7.3 and 8.0 users: Before running <b class="command">dbassist</b>, do the following.</p><div class="orderedlist"><ol type="1"><li><p>
Download the <a href="http://otn.oracle.com/software/products/oracle8i/htdocs/linuxsoft.html" target="_top">glibc
- patch</a> from Oracle Technet into <tt>/tmp</tt>.
+ patch</a> from Oracle Technet into <tt class="computeroutput">/tmp</tt>.
</p></li><li><p>
cd $ORACLE_HOME
</p></li><li><p>
@@ -703,165 +702,165 @@
./setup_stubs
</p></li></ol></div></div><div class="itemizedlist"><ul type="disc"><li><p>
Make sure you are running X. Open up a terminal and
- <tt>su</tt> to oracle and then run the
- <tt>dbassist</tt> program.
+ <tt class="computeroutput">su</tt> to oracle and then run the
+ <tt class="computeroutput">dbassist</tt> program.
</p><pre class="programlisting">
joeuser:~$ xhost +localhost
joeuser:~$ su - oracle
Password: *********
oracle:~$ export DISPLAY=localhost:0.0
oracle:~$ dbassist</pre></li><li><p>
- The "Welcome" screen in the Oracle Database
+ The "Welcome" screen in the Oracle Database
Configuration Agent (ODCA)
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "Create a database"
+ Select "Create a database"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Select database type" screen in the ODCA
+ The "Select database type" screen in the ODCA
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "Custom"
+ Select "Custom"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "Primary Database Type" window in ODCA
+ The "Primary Database Type" window in ODCA
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "Multipurpose"
+ Select "Multipurpose"
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- The "concurrent users" screen of the ODCA
+ The "concurrent users" screen of the ODCA
</p><div class="itemizedlist"><ul type="circle"><li><p>
- Select "60" concurrent users.
+ Select "60" concurrent users.
</p></li><li><p>
- Click "Next"
+ Click "Next"
</p></li></ul></div></li><li><p>
- Select "<tt>Dedicated Server
- Mode</tt>", click
- "<tt>Next</tt>"
+ Select "<tt class="computeroutput">Dedicated Server
+ Mode</tt>", click
+ "<tt class="computeroutput">Next</tt>"
</p></li><li><p>
Accept all of the options, and click
- <tt>Next</tt> Oracle Visual
+ <tt class="computeroutput">Next</tt> Oracle Visual
Information Retrieval may be grayed out. If so, you can ignore
it; just make sure that everything else is checked.
</p></li><li><p>
- For "Global Database Name", enter
- "<tt>ora8</tt>"; for
- "SID", also enter
- "<tt>ora8</tt>" (it should do
- this automatically). Click <tt>"Change
+ For "Global Database Name", enter
+ "<tt class="computeroutput">ora8</tt>"; for
+ "SID", also enter
+ "<tt class="computeroutput">ora8</tt>" (it should do
+ this automatically). Click <tt class="computeroutput">"Change
Character Set</tt> and select
- <tt>UTF8</tt>. Click
- "<tt>Next</tt>".
+ <tt class="computeroutput">UTF8</tt>. Click
+ "<tt class="computeroutput">Next</tt>".
</p></li><li><p>
Accept the defaults for the next screen (control file
location). Click
- "<tt>Next</tt>"
+ "<tt class="computeroutput">Next</tt>"
</p></li><li><p>
- Go to the "temporary" and
- "rollback" tabs, and change the Size
+ Go to the "temporary" and
+ "rollback" tabs, and change the Size
(upper-right text box) to
- <tt>150</tt>MB. Click
- "<tt>Next</tt>"
+ <tt class="computeroutput">150</tt>MB. Click
+ "<tt class="computeroutput">Next</tt>"
</p></li><li><p>
Increase the redo log sizes to
- <tt>10000K</tt> each. Click
- "<tt>Next</tt>"
+ <tt class="computeroutput">10000K</tt> each. Click
+ "<tt class="computeroutput">Next</tt>"
</p></li><li><p>
Use the default checkpoint interval & timeout. Click
- "<tt>Next</tt>"
+ "<tt class="computeroutput">Next</tt>"
</p></li><li><p>
- Increase "<tt>Processes</tt>"
- to <tt>100</tt>;
- "<tt>Block Size</tt>" to
- <tt>4096</tt> (better for small Linux
+ Increase "<tt class="computeroutput">Processes</tt>"
+ to <tt class="computeroutput">100</tt>;
+ "<tt class="computeroutput">Block Size</tt>" to
+ <tt class="computeroutput">4096</tt> (better for small Linux
boxes; use 8192 for a big Solaris machine).
</p></li><li><p>
Accept the defaults for the Trace File Directory. Click
- "<tt>Next</tt>"
+ "<tt class="computeroutput">Next</tt>"
</p></li><li><p>
- Finally, select "<tt>Save information to a shell
- script</tt>" and click
- "<tt>Finish</tt>" (We're
+ Finally, select "<tt class="computeroutput">Save information to a shell
+ script</tt>" and click
+ "<tt class="computeroutput">Finish</tt>" (We're
going to examine the contents of this file before creating our
database.)
</p></li><li><p>
- Click the "<tt>Save</tt>"
+ Click the "<tt class="computeroutput">Save</tt>"
button. Oracle will automatically save it to the correct
directory and with the correct file name. This will likely be
- <tt>/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh</tt>
+ <tt class="computeroutput">/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh</tt>
</p></li><li><p>
It will alert you that the script has been saved
successfully.
</p></li><li><p>
Now we need to customize the database configuration a bit. While
- still logged on as <tt>oracle</tt>, edit
+ still logged on as <tt class="computeroutput">oracle</tt>, edit
the database initialization script (run when the db loads). The
scripts are kept in
- <tt>$ORACLE_HOME/dbs</tt> and the name of
+ <tt class="computeroutput">$ORACLE_HOME/dbs</tt> and the name of
the script is usually
- <tt>init</tt><span class="emphasis"><em>SID</em></span><tt>.ora</tt>
+ <tt class="computeroutput">init</tt><span class="emphasis"><em>SID</em></span><tt class="computeroutput">.ora</tt>
where <span class="emphasis"><em>SID</em></span> is the SID of your
database. Assuming your
- <tt>$ORACLE_HOME</tt> matches our default
+ <tt class="computeroutput">$ORACLE_HOME</tt> matches our default
of
- <tt>/ora8/m01/app/oracle/product/8.1.7</tt>,
+ <tt class="computeroutput">/ora8/m01/app/oracle/product/8.1.7</tt>,
the following will open the file for editing.
</p><pre class="programlisting">
oracle:~$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora</pre></li><li><p>
Add the following line to the end:
</p><pre class="programlisting">
-nls_date_format = "YYYY-MM-DD"</pre></li><li><p>
- Now find the <tt>open_cursors</tt> line
+nls_date_format = "YYYY-MM-DD"</pre></li><li><p>
+ Now find the <tt class="computeroutput">open_cursors</tt> line
in the file. If you're using
- <tt>emacs</tt> scroll up to the top of
- the buffer and do <tt>CTRL-S</tt> and
- type <tt>open_cursors</tt> to find the
- line. The default is <tt>100</tt>. Change
- it to <tt>500</tt>.
+ <tt class="computeroutput">emacs</tt> scroll up to the top of
+ the buffer and do <tt class="computeroutput">CTRL-S</tt> and
+ type <tt class="computeroutput">open_cursors</tt> to find the
+ line. The default is <tt class="computeroutput">100</tt>. Change
+ it to <tt class="computeroutput">500</tt>.
</p><pre class="programlisting">
open_cursors = 500</pre></li><li><p>
- Save the file. In emacs, do <tt>CTRL-X
+ Save the file. In emacs, do <tt class="computeroutput">CTRL-X
CTRL-S</tt> to save followed by
- <tt>CTRL-X CTRL-C</tt> to exit or use
+ <tt class="computeroutput">CTRL-X CTRL-C</tt> to exit or use
the menu.
</p></li><li><p>
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
- <tt>CRTL-ALT-BACKSPACE</tt>, but make
+ <tt class="computeroutput">CRTL-ALT-BACKSPACE</tt>, 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
- <tt>CRTL-ALT-F1</tt>. Then login as
- <tt>oracle</tt>.
+ <tt class="computeroutput">CRTL-ALT-F1</tt>. Then login as
+ <tt class="computeroutput">oracle</tt>.
</p></li><li><p>
Change to the directory where the database creation script is and
run it:
</p><pre class="programlisting">
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</pre><p>
In some instances, Oracle will save the file to
- <tt>/ora8/m01/app/oracle/product/8.1.7/assistants/dbca</tt>
+ <tt class="computeroutput">/ora8/m01/app/oracle/product/8.1.7/assistants/dbca</tt>
Try running the script there if your first attempt does not
succeed.
</p></li><li><p>
Your database will now be built. It will take > 1 hour - no
fooling. You will see lots of errors scroll by (like:
- "ORA-01432: public synonym to be dropped does not
- exist") Fear not, this is normal.
+ "ORA-01432: public synonym to be dropped does not
+ exist") Fear not, this is normal.
</p><p>
Eventually, you'll be returned to your shell prompt. In the
meantime, relax, you've earned it.
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="istall-oracle-test"></a>Acceptance Test</h3></div></div><p>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="istall-oracle-test"></a>Acceptance Test</h3></div></div><div></div></div><p>
For this step, open up a terminal and
- <tt>su</tt> to
- <tt>oracle</tt> as usual. You should be
+ <tt class="computeroutput">su</tt> to
+ <tt class="computeroutput">oracle</tt> as usual. You should be
running X and Netscape (or other web browser) for this phase.
</p><div class="itemizedlist"><ul type="disc"><li><p>
- You need to download the "Oracle Acceptance Test" file.
+ You need to download the "Oracle Acceptance Test" file.
It's available <a href="files/acceptance-sql.txt" target="_top">here</a> and at <a href="http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt" target="_top">http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt</a>.
- Save the file to <tt>/tmp</tt>
+ Save the file to <tt class="computeroutput">/tmp</tt>
</p></li><li><p>
In the oracle shell, copy the file.
</p><pre class="programlisting">
@@ -870,15 +869,15 @@
your term and type the following:
</p><pre class="programlisting">
oracle:~$ sqlplus system/manager</pre><p>
- SQL*Plus should startup. If you get an <tt>ORA-01034:
+ SQL*Plus should startup. If you get an <tt class="computeroutput">ORA-01034:
Oracle not Available</tt> error, it is because your
Oracle instance is not running. You can manually start it as
- the <tt>oracle</tt> user.</p><pre class="programlisting">
+ the <tt class="computeroutput">oracle</tt> user.</p><pre class="programlisting">
oracle:~$ svrmgrl
SVRMGR> connect internal
SVRMGR> startup</pre></li><li><p>
Now that you're into SQL*Plus, change the default passwords
- for system, sys, and ctxsys to "alexisahunk" (or to
+ for system, sys, and ctxsys to "alexisahunk" (or to
something you'll remember):
</p><pre class="programlisting">
SQL> alter user system identified by alexisahunk;
@@ -888,7 +887,7 @@
</p><pre class="programlisting">
SQL> select sysdate from dual;</pre><p>
If you don't see a date that fits the format
- <tt>YYYY-MM-DD</tt>, please read <a href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">the section called “Troubleshooting Oracle Dates”</a>.
+ <tt class="computeroutput">YYYY-MM-DD</tt>, please read <a href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">Section�, “Troubleshooting Oracle Dates”</a>.
</p></li><li><p>
At this point we are going to hammer your database with an
intense acceptance test. This usually takes around 30 minutes.
@@ -903,7 +902,7 @@
2000-06-10
SQL></pre><p>
- Many people encounter an error regarding <tt>maximum
+ Many people encounter an error regarding <tt class="computeroutput">maximum
key length</tt>:
</p><pre class="programlisting">
ERROR at line 1:
@@ -912,66 +911,66 @@
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
- <tt>4096</tt>. For instructions on how to
- do this, see <a href="oracle.html#install-oracle-create" title="Creating the First Database">the section called “Creating the First Database”</a> above. You
+ <tt class="computeroutput">4096</tt>. For instructions on how to
+ do this, see <a href="oracle.html#install-oracle-create" title="Creating the First Database">Section�, “Creating the First Database”</a> above. You
can set the parameter using the
- <tt>dbassist</tt> program or by setting
- the <tt>DB_BLOCK_SIZE</tt> parameter in
+ <tt class="computeroutput">dbassist</tt> program or by setting
+ the <tt class="computeroutput">DB_BLOCK_SIZE</tt> parameter in
your database's creation script.
</p><p>
If there were no errors, then consider yourself fortunate. Your
Oracle installation is working.
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-automating"></a>Automating Startup & Shutdown</h3></div></div><p>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-automating"></a>Automating Startup & Shutdown</h3></div></div><div></div></div><p>
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.
</p><div class="itemizedlist"><ul type="disc"><li><p>
Oracle includes a script called
- <tt>dbstart</tt> that can be used to
+ <tt class="computeroutput">dbstart</tt> 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 <a href="files/dbstart.txt" target="_top">dbstart</a> to
- <tt>/tmp</tt>. Then, as
- <tt>oracle</tt>, do the following:
+ <tt class="computeroutput">/tmp</tt>. Then, as
+ <tt class="computeroutput">oracle</tt>, do the following:
</p><pre class="programlisting">
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</pre></li><li><p>
While you're logged in as
- <tt>oracle</tt>, you should configure the
- <tt>oratab</tt> file to load your
+ <tt class="computeroutput">oracle</tt>, you should configure the
+ <tt class="computeroutput">oratab</tt> file to load your
database at start. Edit the file
- <tt>/etc/oratab</tt>:
+ <tt class="computeroutput">/etc/oratab</tt>:
</p><div class="itemizedlist"><ul type="circle"><li><p>You will see this line. </p><pre class="programlisting">
ora8:/ora8/m01/app/oracle/product/8.1.7:N</pre><p>
By the way, if you changed the service name or have multiple
databases, the format of this file is:
</p><p>
- <span class="emphasis"><em><tt>service_name:$ORACLE_HOME:Y || N
+ <span class="emphasis"><em><tt class="computeroutput">service_name:$ORACLE_HOME:Y || N
(for autoload)</tt></em></span>
</p></li><li><p>
- Change the last letter from "N" to
- "Y". This tells Oracle that you want the database
+ Change the last letter from "N" to
+ "Y". This tells Oracle that you want the database
to start when the machine boots. It should look like this.
</p><pre class="programlisting">
ora8:/ora8/m01/app/oracle/product/8.1.7:Y</pre></li><li><p>
Save the file & quit the terminal.
</p></li></ul></div></li><li><p>
You need a script to automate startup and shutdown. Save <a href="files/oracle8i.txt" target="_top">oracle8i.txt</a> in
- <tt>/tmp</tt>. Then login as
- <tt>root</tt> and install the
+ <tt class="computeroutput">/tmp</tt>. Then login as
+ <tt class="computeroutput">root</tt> and install the
script. (Debian users: substitute
- <tt>/etc/init.d</tt> for
- <tt>/etc/rc.d/init.d</tt> throughout
+ <tt class="computeroutput">/etc/init.d</tt> for
+ <tt class="computeroutput">/etc/rc.d/init.d</tt> throughout
this section)
</p><pre class="programlisting">
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 755 /etc/rc.d/init.d/oracle8i</pre></li><li><p>
Test the script by typing the following commands and checking the
- output. (Debian Users: as root, do <tt>mkdir
+ output. (Debian Users: as root, do <tt class="computeroutput">mkdir
/var/lock/subsys</tt> first)
</p><pre class="programlisting">
root:~# /etc/rc.d/init.d/oracle8i stop
@@ -993,7 +992,7 @@
ORACLE instance shut down.
SVRMGR>
Server Manager complete.
-Database "ora8" shut down.
+Database "ora8" shut down.
root:~# /etc/rc.d/init.d/oracle8i start
Oracle 8i auto start/stop
@@ -1014,9 +1013,9 @@
Database opened.
SQL> Disconnected
-Database "ora8" warm started.
+Database "ora8" warm started.
-Database "ora8" warm started.</pre></li><li><p>
+Database "ora8" warm started.</pre></li><li><p>
If it worked, then run these commands to make the startup and
shutdown automatic.
</p><div class="itemizedlist"><ul type="circle"><li><p>Red Hat users:</p><pre class="programlisting">
@@ -1081,7 +1080,7 @@
and full site search.
</p><p>
Download these three scripts into
- <tt>/tmp</tt>
+ <tt class="computeroutput">/tmp</tt>
</p><div class="itemizedlist"><ul type="circle"><li><p>
<a href="files/startlsnr.txt" target="_top">startlsnr.txt</a>
</p></li><li><p>
@@ -1090,7 +1089,7 @@
<a href="files/listener8i.txt" target="_top">listener8i.txt</a>
</p></li></ul></div><p>
Now issue the following commands (still as
- <tt>root</tt>).
+ <tt class="computeroutput">root</tt>).
</p><pre class="programlisting">
root:~# su - oracle
oracle:~$ cp /tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
@@ -1150,8 +1149,8 @@
normally. Login into the database using the listener naming
convention.
</p><p>
- <tt>sqlplus</tt>
- <span class="emphasis"><em><tt>username/password/@SID</tt></em></span>
+ <tt class="computeroutput">sqlplus</tt>
+ <span class="emphasis"><em><tt class="computeroutput">username/password/@SID</tt></em></span>
</p><pre class="programlisting">
root:~# su - oracle
oracle:~$ sqlplus system/alexisahunk@ora8
@@ -1165,15 +1164,15 @@
SQL> exit
oracle:~$ exit
root:~#</pre><div class="itemizedlist"><ul type="circle"><li><p>RedHat users:</p><p>
- Now run <tt>chkconfig</tt> on the
- <tt>listener8i</tt> script.
+ Now run <tt class="computeroutput">chkconfig</tt> on the
+ <tt class="computeroutput">listener8i</tt> script.
</p><pre class="programlisting">
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</pre></li><li><p>Debian users:</p><p>
- Now run <tt>update-rc.d</tt> on the
- <tt>listener8i</tt> script.
+ Now run <tt class="computeroutput">update-rc.d</tt> on the
+ <tt class="computeroutput">listener8i</tt> script.
</p><pre class="programlisting">
root:~# update-rc.d listener8i defaults 21 19
Adding system startup for /etc/init.d/listener8i ...
@@ -1198,30 +1197,30 @@
SQL> exit</pre></li></ul></div><p>
Congratulations, your installation of Oracle 8.1.7 is
complete.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-troubleshooting"></a>Troubleshooting Oracle Dates</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-troubleshooting"></a>Troubleshooting Oracle Dates</h3></div></div><div></div></div><p>
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
- <tt>'YYYY-MM-DD'</tt>.
+ <tt class="computeroutput">'YYYY-MM-DD'</tt>.
</p><p>
To fix this, you should include the following line in
- <tt>$ORACLE_HOME/dbs/init</tt><span class="emphasis"><em>SID</em></span><tt>.ora</tt>
+ <tt class="computeroutput">$ORACLE_HOME/dbs/init</tt><span class="emphasis"><em>SID</em></span><tt class="computeroutput">.ora</tt>
or for the default case,
- <tt>$ORACLE_HOME/dbs/initora8.ora</tt>
+ <tt class="computeroutput">$ORACLE_HOME/dbs/initora8.ora</tt>
</p><pre class="programlisting">
-nls_date_format = "YYYY-MM-DD"</pre><p>
+nls_date_format = "YYYY-MM-DD"</pre><p>
You test whether this solved the problem by firing up
- <tt>sqlplus</tt> and typing:
+ <tt class="computeroutput">sqlplus</tt> and typing:
</p><pre class="programlisting">
SQL> select sysdate from dual;</pre><p>
You should see back a date like
- <tt>2000-06-02</tt>. If some of the date is
- chopped off, i.e. like <tt>2000-06-0</tt>,
+ <tt class="computeroutput">2000-06-02</tt>. If some of the date is
+ chopped off, i.e. like <tt class="computeroutput">2000-06-0</tt>,
everything is still fine. The problem here is that
- <tt>sqlplus</tt> is simply truncating the
+ <tt class="computeroutput">sqlplus</tt> is simply truncating the
output. You can fix this by typing:
</p><pre class="programlisting">
SQL> column sysdate format a15
@@ -1248,13 +1247,13 @@
Setting this environment variable will override the date
setting. Either delete this line and login again or add the following
entry to your login scripts <span class="emphasis"><em>after</em></span> the
- <tt>nls_lang</tt> line:
+ <tt class="computeroutput">nls_lang</tt> line:
</p><pre class="programlisting">
export nls_date_format = 'YYYY-MM-DD'</pre><p>
Log back in again. If adding the
- <tt>nls_date_format</tt> line doesn't
+ <tt class="computeroutput">nls_date_format</tt> line doesn't
help, you can ask for advice in our <a href="http://www.openacs.org/bboard/" target="_top">OpenACS forum</a>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-procs"></a>Useful Procedures</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-procs"></a>Useful Procedures</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
Dropping a tablespace
</p><div class="itemizedlist"><ul type="circle"><li><p>
Run sqlplus as the dba:
@@ -1271,9 +1270,9 @@
</p><pre class="programlisting">
SQL> drop tablespace <span class="emphasis"><em>table_space_name</em></span> including contents cascade constraints;</pre></li></ul></div></li></ul></div><p>
For more information on Oracle, please consult the <a href="http://oradoc.photo.net/" target="_top">documentation</a>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-defaults"></a>Defaults</h3></div></div><p>We used the following defaults while installing Oracle.</p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Value</th><th>Reason</th></tr></thead><tbody><tr><td>ORACLE_HOME</td><td>/ora8/m01/app/oracle/product/8.1.7</td><td>This is the default Oracle installation directory.</td></tr><tr><td>ORACLE_SERVICE</td><td>ora8</td><td>The service name is a domain-qualified identifier for
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-defaults"></a>Defaults</h3></div></div><div></div></div><p>We used the following defaults while installing Oracle.</p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Value</th><th>Reason</th></tr></thead><tbody><tr><td>ORACLE_HOME</td><td>/ora8/m01/app/oracle/product/8.1.7</td><td>This is the default Oracle installation directory.</td></tr><tr><td>ORACLE_SERVICE</td><td>ora8</td><td>The service name is a domain-qualified identifier for
your Oracle server.</td></tr><tr><td>ORACLE_SID</td><td>ora8</td><td>This is an identifier for your Oracle server.</td></tr><tr><td>ORACLE_OWNER</td><td>oracle</td><td>The user who owns all of the oracle files.</td></tr><tr><td>ORACLE_GROUP</td><td>dba</td><td>The special oracle group. Users in the dba group are
- authorized to do a <tt>connect
+ authorized to do a <tt class="computeroutput">connect
internal</tt> within
- <tt>svrmgrl</tt> to gain full system
+ <tt class="computeroutput">svrmgrl</tt> to gain full system
access to the Oracle system.</td></tr></tbody></table></div></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="linux-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr><tr><td width="40%" align="left">Install Linux and supporting software </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install PostGreSQL</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/oracle.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/packages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/packages.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/packages.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,20 +1,19 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 5.0.0d Packages</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="next" href="objects.html" title="OpenACS Data Models and the Object System"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="packages"></a>OpenACS 5.0.0d Packages</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 5.0.0a1 Packages</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="next" href="objects.html" title="OpenACS Data Models and the Object System"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packages"></a>OpenACS 5.0.0a1 Packages</h2></div></div><div></div></div><div class="authorblurb"><p>
By Pete Su and Bryan Quinn
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-overview"></a>Overview</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-overview"></a>Overview</h3></div></div><div></div></div><p>
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
for packaging software, conventions for the file system and naming
that must be followed, and step by step instructions for creating a
- new package for the "Notes" example package.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-why-package"></a>Why package your software?</h3></div></div><p>
+ new package for the "Notes" example package.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-why-package"></a>Why package your software?</h3></div></div><div></div></div><p>
To answer this question, we should examine how OpenACS servers were
organized in the past. We will assume throughout this document that
- the page root for your server is called <tt>ROOT</tt>. In OpenACS
+ the page root for your server is called <tt class="computeroutput">ROOT</tt>. In OpenACS
3.2.x and earlier, a typical server might have a file system behind it
that looked something like this:
</p><pre class="programlisting">
@@ -52,16 +51,16 @@
</pre><p>
In previous versions of OpenACS, you wrote a new application like this:
</p><div class="orderedlist"><ol type="1"><li><p>Put all Tcl library procedures under
- <tt>server-root/tcl</tt>.</p></li><li><p>Put all User viewable content under
- <tt>server-root/www</tt>.</p></li><li><p>Put all Admin content under <tt>/admin/package-key/</tt>.
+ <tt class="computeroutput">server-root/tcl</tt>.</p></li><li><p>Put all User viewable content under
+ <tt class="computeroutput">server-root/www</tt>.</p></li><li><p>Put all Admin content under <tt class="computeroutput">/admin/package-key/</tt>.
</p></li></ol></div><p>
This structure is very simple, and worked well in a world where
OpenACS was basically a single monolithic entity. But, this organization
made it difficult to distribute modules as independent packages, because
the pieces of each module are strewn all over the tree in at least 3
or 4 different areas.
</p><p>
- Here is how an OpenACS 5.0.0d server is laid out:
+ Here is how an OpenACS 5.0.0a1 server is laid out:
</p><pre class="programlisting">
ROOT/
@@ -105,7 +104,7 @@
misc pages
</pre><p>
Note that a major reorganization has happened here. The diagram only
- expands the structure of the <tt>bboard/</tt> package directory,
+ expands the structure of the <tt class="computeroutput">bboard/</tt> package directory,
but all the others are basically the same. Each package encapsulates
all of its data model, library code, logic, adminstration pages and
user pages in a single part of the file tree. This organization has
@@ -125,8 +124,8 @@
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 5.0.0d, this tool is called the APM.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-apm"></a>The APM</h3></div></div><p>
+ removal. In OpenACS 5.0.0a1, this tool is called the APM.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-apm"></a>The APM</h3></div></div><div></div></div><p>
The APM is used to create, maintain, and install packages. It takes
care of copying all of the files and registering the package in the
system. The APM is responsible for:
@@ -147,17 +146,17 @@
</p><p>
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 5.0.0d that take advantage of the APM's package
+ management features in OpenACS 5.0.0a1 that take advantage of the APM's package
instance model. The two most important of these are <span class="emphasis"><em>subsites</em></span>,
and the <span class="emphasis"><em>site map</em></span> tool, which can be used to map applications to
one or more arbitrary URLs in a running site.
</p><p>
We will also discuss how to organize your files and queries so
they work with the OpenACS Query Dispatcher.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-looks"></a>What a Package Looks Like</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-looks"></a>What a Package Looks Like</h3></div></div><div></div></div><p>
<a class="indexterm" name="baby"></a>
To illustrate the general structure of a package, let's see what the
- package for the "notes" application should look like. This is shown in
+ package for the "notes" application should look like. This is shown in
the diagram below:
</p><pre class="programlisting">
@@ -216,7 +215,7 @@
</pre><p>
All file locations are relative to the package root, which in this
- case is <tt>ROOT/packages/notes</tt>. The following table
+ case is <tt class="computeroutput">ROOT/packages/notes</tt>. The following table
describes in detail what each of the files up in the diagram contain.
</p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>File Type</th><th>Its Use</th><th>Naming Convention</th></tr></thead><tbody><tr><td>Data Model Creation Script</td><td>
Contains the SQL that creates the necessary data model and
@@ -226,11 +225,11 @@
the script must be under the appropriate directory for
the database you are developing your package for
(hopefully all OpenACS-supported databases :-))
- </td><td><tt>sql/<database>/notes-create.sql</tt></td></tr><tr><td>Data Model Drop Script</td><td>Contains the SQL that removes the data model and PL/SQL
+ </td><td><tt class="computeroutput">sql/<database>/notes-create.sql</tt></td></tr><tr><td>Data Model Drop Script</td><td>Contains the SQL that removes the data model and PL/SQL
packages generated by the creation script. The name must
match the convention below or the package will not be
installed correctly.
- </td><td><tt>sql/<database>/notes-drop.sql</tt></td></tr><tr><td>Data Model File</td><td>Any .sql file that does not match the naming convention above
+ </td><td><tt class="computeroutput">sql/<database>/notes-drop.sql</tt></td></tr><tr><td>Data Model File</td><td>Any .sql file that does not match the naming convention above
is recognized as a data model file. It is useful to separate
the SQL in the creation and drop scripts into several
files and then have the scripts source the other data model
@@ -239,71 +238,71 @@
scripts. See the <a href="http://oradoc.photo.net/ora816/sqlplus.816/a75664/ch83.htm#1011677" target="_top">
Oracle SQL*Plus documentation</a> for examples. In
PostgreSQL the same is acomplished by including <span class="emphasis"><em>\i</em></span>.
- </td><td><tt>sql/<database>/*.sql</tt></td></tr><tr><td>Data Model Upgrade Scripts</td><td>
+ </td><td><tt class="computeroutput">sql/<database>/*.sql</tt></td></tr><tr><td>Data Model Upgrade Scripts</td><td>
Contain changes to the data model between versions. The APM
can automatically load the appropriate upgrade scripts when
upgrading to a new version of a package.
- </td><td><tt>sql/<database>/upgrade/upgrade-<old>-<new>.sql</tt></td></tr><tr><td>
+ </td><td><tt class="computeroutput">sql/<database>/upgrade/upgrade-<old>-<new>.sql</tt></td></tr><tr><td>
SQL92 Query Files
</td><td>
Files with queries that are supported by all
databases. These are usually SQL92 queries. Notice that
the .xql filename must match the name of the .tcl file
that uses those queries.
- </td><td><tt>
+ </td><td><tt class="computeroutput">
*.xql
</tt></td></tr><tr><td>
Oracle-specific Query Files
</td><td>
Files with queries that are Oracle-specific. Notice that
the .xql filename must match the name of the .tcl file
that uses those queries.
- </td><td><tt>
+ </td><td><tt class="computeroutput">
*-oracle.xql
</tt></td></tr><tr><td>
PostgreSQL-specific Query Files
</td><td>
Files with queries that are PostgreSQL-specific. Notice that
the .xql filename must match the name of the .tcl file
that uses those queries.
- </td><td><tt>
+ </td><td><tt class="computeroutput">
*-postgresql.xql
</tt></td></tr><tr><td>Tcl Library Files</td><td>
The Tcl library files include a set of procedures that provide
an application programming interface (API) for the package to
utilize.
- </td><td><tt>tcl/notes-procs.tcl</tt></td></tr><tr><td>Tcl Initialization</td><td>The initialization files are used to run Tcl procedures that
+ </td><td><tt class="computeroutput">tcl/notes-procs.tcl</tt></td></tr><tr><td>Tcl Initialization</td><td>The initialization files are used to run Tcl procedures that
should only be sourced once on startup. Examples of
statements to put here are registered filters or procedures.
Tcl initialization files are sourced once on server startup
after all of the Tcl library files are sourced.
- </td><td><tt>tcl/notes-init.tcl</tt></td></tr><tr><td>Administration UI</td><td>The administration UI is used to administer the instances of
+ </td><td><tt class="computeroutput">tcl/notes-init.tcl</tt></td></tr><tr><td>Administration UI</td><td>The administration UI is used to administer the instances of
the package. For example, the bboard administration UI is
used to create new forums, moderate postings, and create new
- categories for bboard postings.</td><td><tt>www/admin/*</tt></td></tr><tr><td>Administration UI Index Page</td><td>Every package administration UI must have an index page. In
- most cases, this is <tt>index.tcl</tt> but it can be
- any file with the name <tt>index</tt>, such as
- index.html or index.adp.</td><td><tt>www/admin/index.tcl</tt></td></tr><tr><td>Regression Tests</td><td>Every package should have a set of regression tests that
+ categories for bboard postings.</td><td><tt class="computeroutput">www/admin/*</tt></td></tr><tr><td>Administration UI Index Page</td><td>Every package administration UI must have an index page. In
+ most cases, this is <tt class="computeroutput">index.tcl</tt> but it can be
+ any file with the name <tt class="computeroutput">index</tt>, such as
+ index.html or index.adp.</td><td><tt class="computeroutput">www/admin/index.tcl</tt></td></tr><tr><td>Regression Tests</td><td>Every package should have a set of regression tests that
verify that it is in working operation.
These tests should be able to be run at any time after the package has
been installed and report helpful error messages when there is
- a fault in the system.</td><td><tt>www/admin/tests/</tt></td></tr><tr><td>Regression Test Index Page</td><td>The regression test directory must have an index page that
+ a fault in the system.</td><td><tt class="computeroutput">www/admin/tests/</tt></td></tr><tr><td>Regression Test Index Page</td><td>The regression test directory must have an index page that
displays all of the tests available and provides information
on how to run them. This file can have any extension, as long
- as its name is <tt>index</tt>.</td><td><tt>/www/admin/tests/index.html</tt></td></tr><tr><td>Documentation</td><td>Every package must include a full set of documentation that
+ as its name is <tt class="computeroutput">index</tt>.</td><td><tt class="computeroutput">/www/admin/tests/index.html</tt></td></tr><tr><td>Documentation</td><td>Every package must include a full set of documentation that
includes requirements and design documents, and user-level and
- developer-level documentation where appropriate.</td><td><tt>/www/doc/</tt></td></tr><tr><td>Documentation Index Page</td><td>The documentation directory must include a static HTML file with the name
- of <tt>index.html</tt>.</td><td><tt>/www/doc/index.html</tt></td></tr><tr><td>UI Logic Scripts</td><td>Packages provide a UI for users to access the system. The UI
+ developer-level documentation where appropriate.</td><td><tt class="computeroutput">/www/doc/</tt></td></tr><tr><td>Documentation Index Page</td><td>The documentation directory must include a static HTML file with the name
+ of <tt class="computeroutput">index.html</tt>.</td><td><tt class="computeroutput">/www/doc/index.html</tt></td></tr><tr><td>UI Logic Scripts</td><td>Packages provide a UI for users to access the system. The UI
is split into Logic and Templates. The logic scripts
perform database queries and prepare variables for
- presentation by the associated templates.</td><td><tt>/www/*.tcl</tt></td></tr><tr><td>UI Templates</td><td>Templates are used to control the presentation of the UI.
+ presentation by the associated templates.</td><td><tt class="computeroutput">/www/*.tcl</tt></td></tr><tr><td>UI Templates</td><td>Templates are used to control the presentation of the UI.
Templates receive a set of data sources from the logic scripts
- and prepare them for display to the browser.</td><td><tt>/www/*.adp</tt></td></tr><tr><td>UI Index Page</td><td>The UI must have an index page composed of a logic script
- called <tt>index.tcl</tt> and a template called
- <tt>index.adp</tt>.</td><td><tt>/www/index.tcl</tt></td></tr><tr><td>Package Specification File</td><td>The package specification file is an XML file generated and
+ and prepare them for display to the browser.</td><td><tt class="computeroutput">/www/*.adp</tt></td></tr><tr><td>UI Index Page</td><td>The UI must have an index page composed of a logic script
+ called <tt class="computeroutput">index.tcl</tt> and a template called
+ <tt class="computeroutput">index.adp</tt>.</td><td><tt class="computeroutput">/www/index.tcl</tt></td></tr><tr><td>Package Specification File</td><td>The package specification file is an XML file generated and
maintained by the OpenACS Package Manager (APM). It specifies
information about the package including its parameters and its
- files.</td><td><tt>notes.info</tt></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-making-a-package"></a>Making a Package</h3></div></div><p>
+ files.</td><td><tt class="computeroutput">notes.info</tt></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-making-a-package"></a>Making a Package</h3></div></div><div></div></div><p>
Here is how you make a package.
</p><div class="orderedlist"><ol type="1"><li><p>Login as a site-wide administrator on your web service.
</p></li><li><p>Go to the package manager on your server. The URL is <a href="/acs-admin/apm" target="_top">/acs-admin/apm</a>.
@@ -318,27 +317,27 @@
distinguish it from all the others. It is used as a database key to
keep track of the package and as the name of the directory in the file
system where all the files related to your package will live. Example
- package keys in the current system include: <tt>bboard</tt>,
- <tt>acs-kernel</tt> and so on. For the example application, we
- will use the package key <tt>notes</tt>.
+ package keys in the current system include: <tt class="computeroutput">bboard</tt>,
+ <tt class="computeroutput">acs-kernel</tt> and so on. For the example application, we
+ will use the package key <tt class="computeroutput">notes</tt>.
</p></dd><dt><span class="term">Package Name
</span></dt><dd><p>
This is a short human readable name for your package. For our example,
- we will use the name "Notes".
+ we will use the name "Notes".
</p></dd><dt><span class="term">Package Plural
</span></dt><dd><p>
If your package name is a nice singular noun, this should be the
plural form of it. I assume the plural form is used when multiple
instances of the package are used by a single service. We'll talk more
about package instances later. Our example apllication doesn't really
- have a good plural name. So just make it also be "Notes".
+ have a good plural name. So just make it also be "Notes".
</p></dd><dt><span class="term">Package Type
</span></dt><dd><p>
Generally we think of packages as either being <span class="emphasis"><em>applications</em></span>,
meaning that the package is meant primarily for use by end-users, or
<span class="emphasis"><em>services</em></span> meaning that the package is meant to be a reusable
- library of code, to be used by other packages. <tt>bboard</tt> is
- a good example of an application, while <tt>acs-templating</tt> is
+ library of code, to be used by other packages. <tt class="computeroutput">bboard</tt> is
+ a good example of an application, while <tt class="computeroutput">acs-templating</tt> is
a good example of a service. Our example is an application, so pick
that.
</p></dd><dt><span class="term">Package URL
@@ -354,47 +353,47 @@
</p></dd><dt><span class="term">Summary and Description
</span></dt><dd><p>
Enter a short summary and longer description of what the Notes
- application will do. That is, something like "this application keeps
- short textual notes in the database", and so on.
+ application will do. That is, something like "this application keeps
+ short textual notes in the database", and so on.
</p></dd></dl></div><p>
- </p></li><li><p>Click the button "Create Package".
+ </p></li><li><p>Click the button "Create Package".
</p></li><li><p>At this point, APM will create a directory called
- <tt>ROOT/packages/notes</tt>.
+ <tt class="computeroutput">ROOT/packages/notes</tt>.
</p></li><li><p>
The directory that APM created will be empty except for the
- <tt>notes.info</tt> file. Create a file
+ <tt class="computeroutput">notes.info</tt> file. Create a file
called
- <tt>ROOT/packages/notes/sql/oracle/notes-create.sql</tt>. We'll
+ <tt class="computeroutput">ROOT/packages/notes/sql/oracle/notes-create.sql</tt>. We'll
fill this file with our <a href="objects.html" title="OpenACS Data Models and the Object System">data model</a>
very soon. Create a file called
- <tt>ROOT/packages/notes/sql/oracle/notes-drop.sql</tt>. This
+ <tt class="computeroutput">ROOT/packages/notes/sql/oracle/notes-drop.sql</tt>. This
will contain the instructions to drop the data model. To be
complete, you would also create the PostgreSQL versions of these
files as well in
- <tt>ROOT/packages/notes/sql/postgresql/notes-create.sql</tt>
+ <tt class="computeroutput">ROOT/packages/notes/sql/postgresql/notes-create.sql</tt>
and
- <tt>ROOT/packages/notes/sql/postgresql/notes-drop.sql</tt>.
+ <tt class="computeroutput">ROOT/packages/notes/sql/postgresql/notes-drop.sql</tt>.
</p><p>
After you do this, go back to the main APM page. From there,
- click the link called "notes" to go to the management
- page for the new package. Now click the link called "Manage
- file information", then the "Scan the
- <tt>packages/notes</tt> directory for
- additional files in this package" link on that page to scan
+ click the link called "notes" to go to the management
+ page for the new package. Now click the link called "Manage
+ file information", then the "Scan the
+ <tt class="computeroutput">packages/notes</tt> directory for
+ additional files in this package" link on that page to scan
the file system for new files. This will bring you do a page
that lists all the files you just added and lets you add them to
- the <tt>notes</tt> package.
+ the <tt class="computeroutput">notes</tt> package.
</p><p>
- Note that while the <tt>.sql</tt> files
+ Note that while the <tt class="computeroutput">.sql</tt> files
have been added to the packge, they <span class="emphasis"><em>have not</em></span>
been loaded into the database. For the purposes of development,
you have to load the data model by hand, because while OpenACS
has automatic mechanisms for loading and reloading
- <tt>.tcl</tt> files for code, it does not
+ <tt class="computeroutput">.tcl</tt> files for code, it does not
do the same thing for data model files.
- </p></li><li><p>Now go back to the main management page for the <tt>notes</tt>
- If your package has parameters, create them using the "Manage
- Parameter Information" link.</p></li><li><p>The new package has been created and installed in the server. At
+ </p></li><li><p>Now go back to the main management page for the <tt class="computeroutput">notes</tt>
+ If your package has parameters, create them using the "Manage
+ Parameter Information" link.</p></li><li><p>The new package has been created and installed in the server. At
this point, you should add your package files to your CVS repository.
I'll assume that you have set up your development repository according
to the standards described in
@@ -409,58 +408,58 @@
% cd sql
% cvs add *.sql
% cd ROOT/packages/notes
-% cvs commit -m "add new package for notes"
+% cvs commit -m "add new package for notes"
</pre></li><li><p>
Now you can start developing the package. In addition to writing code,
you should also consider the tasks outlined in the <a href="http://acs40.arsdigita.com/acs40-project-central/package-submission.html" target="_top">package submission guidelines</a>.
- </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-subsites"></a>The Site Map and Package Instances</h3></div></div><p>
+ </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-subsites"></a>The Site Map and Package Instances</h3></div></div><div></div></div><p>
At this point, you are probably excited to see your new package in
action. But, we haven't added any user visible pages yet. By
convention, user visible pages go in the
- <tt>ROOT/packages/notes/www</tt> directory. So go there and add a
- file called <tt>hello.html</tt> with some text in it. Now we have
+ <tt class="computeroutput">ROOT/packages/notes/www</tt> directory. So go there and add a
+ file called <tt class="computeroutput">hello.html</tt> with some text in it. Now we have
to make the user pages visible in the site. Since we didn't put the
- pages underneath <tt>ROOT/www</tt> they will not appear on their
+ pages underneath <tt class="computeroutput">ROOT/www</tt> they will not appear on their
own. What we have to do is <span class="emphasis"><em>mount</em></span> the application into the site
map. That is, we have to define the URL from which the application
will serve its pages. This process is slightly more complex than in
OpenACS 3.x, but also much more flexible.
</p><p>
In OpenACS 3.x, everything in the site was implicitly mounted underneath
- <tt>ROOT/www</tt>. AOLserver automatically took any URL like
- <tt>/foo/bar/moo/baz.html</tt> and mapped it to the file
- <tt>ROOT/www/foo/bar/moo/baz.html</tt>. This was conveniently
+ <tt class="computeroutput">ROOT/www</tt>. AOLserver automatically took any URL like
+ <tt class="computeroutput">/foo/bar/moo/baz.html</tt> and mapped it to the file
+ <tt class="computeroutput">ROOT/www/foo/bar/moo/baz.html</tt>. This was conveniently
simple, but lacked flexibility. In particular, it was difficult to
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.
</p><p>
- In OpenACS 5.0.0d, administrators can define an arbitrary mapping between the
+ In OpenACS 5.0.0a1, 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 <span class="emphasis"><em>site map</em></span> and entries in the
site map are called <span class="emphasis"><em>site nodes</em></span>. Each site node maps a URL to an
OpenACS object. Since package instances are objects, the site map allows
us to easily map package instances to URLs. As we said before, each
instance of an application has its own set of parameters and
runs from its own URL within the site. What this means is that even
- though all the code for the <tt>notes</tt> application lives in
- <tt>ROOT/packages/notes</tt>, the application itself can run from
+ though all the code for the <tt class="computeroutput">notes</tt> application lives in
+ <tt class="computeroutput">ROOT/packages/notes</tt>, the application itself can run from
any number of locations in the site. This allows developers and
administrators to build sites that look to the user like a collection
of many indedendent applications that actually run on a single shared
code base. The <a href="request-processor.html" title="The Request Processor">request-processor</a> document shows
you how OpenACS figures out which instance of your application was
- requested by the user at any given time. The <a href="subsites.html" title="Writing OpenACS 5.0.0d Application Pages">page development</a> tutorial shows you how to use this
+ requested by the user at any given time. The <a href="subsites.html" title="Writing OpenACS 5.0.0a1 Application Pages">page development</a> tutorial shows you how to use this
information in your user interface.
</p><p>
- In order to make the new <tt>notes</tt> application visible to
+ In order to make the new <tt class="computeroutput">notes</tt> application visible to
users, we have to mount it in the site map. You do this by going to
the <a href="/admin/site-map" target="_top">Site Map</a> page, which is by
- default available at <tt>/acs-admin/site-map</tt>. Use the
- interface here to add a new sub-folder called <tt>notes</tt> to
- the root of the site, then click "new application" to mount a new
- instance of the <tt>notes</tt> application to the site. Name the
- new instance <tt>notes-1</tt>.
+ default available at <tt class="computeroutput">/acs-admin/site-map</tt>. Use the
+ interface here to add a new sub-folder called <tt class="computeroutput">notes</tt> to
+ the root of the site, then click "new application" to mount a new
+ instance of the <tt class="computeroutput">notes</tt> application to the site. Name the
+ new instance <tt class="computeroutput">notes-1</tt>.
</p><p>
Then type this URL into your browser:
@@ -470,15 +469,15 @@
</pre><p>
Now you should see the contents of the page that you added. What has
- happened is that all URLs that start with <tt>/notes</tt> have
+ happened is that all URLs that start with <tt class="computeroutput">/notes</tt> have
been mapped in such a way as to serve content from the directory
- <tt>ROOT/packages/notes/www</tt>. At this point, you can
+ <tt class="computeroutput">ROOT/packages/notes/www</tt>. At this point, you can
experiment with the site map by mounting multiple instances of the not
yet written Notes application at various places in the site. In a
later document, we'll see how to write your application so that the
code can detect from what URL it was invoked. This is the key
- to supporting <a href="subsites.html" title="Writing OpenACS 5.0.0d Application Pages">subsites</a>.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-summary"></a>Summary</h3></div></div><p>
+ to supporting <a href="subsites.html" title="Writing OpenACS 5.0.0a1 Application Pages">subsites</a>.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-summary"></a>Summary</h3></div></div><div></div></div><p>
The APM performs the following tasks in an OpenACS site:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Manages creation, installation, and removal of packages from the
@@ -493,4 +492,4 @@
</p></li><li><p>
Writes out package distribution files for other people to download and
install. We'll cover this later.
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="packages-add-reading"></a>Additional Reading</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="apm-design.html">OpenACS 5.0.0d Package Manager Design</a></p></li><li><p><a href="apm-requirements.html">OpenACS 5.0.0d Package Manager Requirements</a></p></li><li><p><a href="http://acs40.arsdigita.com/acs40-project-central/package-submission.html" target="_top">Package submission guidelines</a></p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�11.�Development Reference </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS Data Models and the Object System</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/packages.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="packages-add-reading"></a>Additional Reading</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="apm-design.html">OpenACS 5.0.0a1 Package Manager Design</a></p></li><li><p><a href="apm-requirements.html">OpenACS 5.0.0a1 Package Manager Requirements</a></p></li><li><p><a href="http://acs40.arsdigita.com/acs40-project-central/package-submission.html" target="_top">Package submission guidelines</a></p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�11.�Development Reference </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS Data Models and the Object System</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/packages.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/parties.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/parties.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/parties.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,21 +1,20 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Parties in OpenACS 5.0.0d</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="subsites.html" title="Writing OpenACS 5.0.0d Application Pages"><link rel="next" href="permissions-tediously-explained.html" title="OpenACS 4.x Permissions Tediously Explained"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="parties"></a>Parties in OpenACS 5.0.0d</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Parties in OpenACS 5.0.0a1</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="subsites.html" title="Writing OpenACS 5.0.0a1 Application Pages"><link rel="next" href="permissions-tediously-explained.html" title="OpenACS 4.x Permissions Tediously Explained"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="parties"></a>Parties in OpenACS 5.0.0a1</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="parties-intro"></a>Introduction</h3></div></div><p>While many applications must deal with individuals and many applications
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="parties-intro"></a>Introduction</h3></div></div><div></div></div><p>While many applications must deal with individuals and many applications
must deal with groups, most applications must deal with individuals
<span class="emphasis"><em>or</em></span> groups. It is often the case with such applications that in many
respects both individuals and groups are treated in an identical manner. It
is this latter class of application that makes it extremely useful to model
individuals and groups as specializations of one supertype. This concept is
so commonly used throughout human language and thought that we don't even
need to invent for it some bizarre and specialized terminology. This
-supertype is called a "party".</p><p>A classic example use of the "party" supertype is evident
+supertype is called a "party".</p><p>A classic example use of the "party" supertype is evident
in a common address book. A typical person's address book might contain
the address of his doctor, and his cable company. So what do we label the
first field in an entry in his address book? It isn't a person, and it
-isn't a company. It is a "party".</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="parties-data-model"></a>The Data Model</h3></div></div><p>Most developers who do significant work with the OpenACS will become
+isn't a company. It is a "party".</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="parties-data-model"></a>The Data Model</h3></div></div><div></div></div><p>Most developers who do significant work with the OpenACS will become
intimately familiar with the parties data model, and probably extend it on
many occasions. For this reason the parties developer guide will begin with
an introduction to the data model.</p><p><span class="strong">Parties</span></p><p>The central table in the parties data model is the parties table itself.
@@ -24,7 +23,7 @@
permissions may granted and revoked on parties and auditing information is
stored in the acs objects table.</p><pre class="programlisting">
-<tt>create table parties (
+<tt class="computeroutput">create table parties (
party_id not null
constraint parties_party_id_fk references
acs_objects (object_id)
@@ -47,7 +46,7 @@
Also note that an individual need not be known to the system as a user. A
user is in fact a further specialized form of an individual.</p><pre class="programlisting">
-<tt>create table persons (
+<tt class="computeroutput">create table persons (
person_id not null
constraint persons_person_id_fk
references parties (party_id)
@@ -64,16 +63,16 @@
in the users table then there must be a row in the persons table and a row in
the parties table.</p><p>One of the interesting benefits of decomposing all the information
associated with a user into the four tables (acs_objects, parties, persons,
-users) is that it is now possible to "nuke" a user from a live
+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 5.0.0d data model references the persons or
+because wherever possible the OpenACS 5.0.0a1 data model references the persons or
parties table, <span class="strong">not</span> 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
references is to a user and not to an individual.</p><pre class="programlisting">
-<tt>create table users (
+<tt class="computeroutput">create table users (
user_id not null
constraint users_user_id_fk
references persons (person_id)
@@ -107,7 +106,7 @@
is another piece to the groups data model that records relations between
parties and groups.</p><pre class="programlisting">
-<tt>create table groups (
+<tt class="computeroutput">create table groups (
group_id not null
constraint groups_group_id_fk
references parties (party_id)
@@ -118,7 +117,7 @@
</pre><p><span class="strong">Group Relations</span></p><p>One surprise here is that there are actually two relations involved. One
is the normal membership relation between parties and groups. A party may be
-a "member" of a group. The other relation is a composition
+a "member" of a group. The other relation is a composition
relation between two groups. To fully understand why two relations are
necessary, and the situations in which each is appropriate, let's
consider an example. Greenpeace is an organization that can have as members
@@ -129,7 +128,7 @@
itself. Now let's consider a multinational corporation. This corporation
might have a U.S. division and a European division. A member of either the
U.S. or European division is automatically a member of the company. In this
-situation the U.S. and European divisions are "components" of
+situation the U.S. and European divisions are "components" of
the company, i.e., membership <span class="emphasis"><em>is</em></span> transitive with respect to
composition. Having a membership relation between groups and parties, and
having a composition relation between groups and groups allows us to easily
@@ -141,7 +140,7 @@
member. This is because there is a distinction between direct membership and
indirect membership (membership via some component or sub component).</p><pre class="programlisting">
-<tt>create or replace package membership_rel
+<tt class="computeroutput">create or replace package membership_rel
as
function new (
@@ -191,7 +190,7 @@
good idea to not give them the option to create a composition relation that
would result in a cycle.</p><pre class="programlisting">
-<tt>create or replace package composition_rel
+<tt class="computeroutput">create or replace package composition_rel
as
function new (
@@ -212,12 +211,12 @@
show errors
</tt>
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="parties-views"></a>Views</h3></div></div><p>The data model described above does a reasonable job of representing many
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="parties-views"></a>Views</h3></div></div><div></div></div><p>The data model described above does a reasonable job of representing many
of the situations one is likely to encounter when modeling organizational
structures, but we still need to be able to efficiently answer questions like
-"what members are in this group and all of its components?", and
-"of what groups is this party a member either directly or
-indirectly?". Composition relations allow you to describe an arbitrary
+"what members are in this group and all of its components?", and
+"of what groups is this party a member either directly or
+indirectly?". Composition relations allow you to describe an arbitrary
Directed Acyclic Graph (DAG) between a group and its components. For these
reasons the party system provides a bunch of views that take advantage of the
internal representation of group relations to answer questions like these
@@ -232,7 +231,7 @@
container_id. The rel_id might be useful for retrieving or updating standard
auditing info for the relation.</p><pre class="programlisting">
-<tt>create or replace view group_component_map
+<tt class="computeroutput">create or replace view group_component_map
as select group_id, component_id, container_id, rel_id
...
</tt>
@@ -241,15 +240,15 @@
Note that this view will return all membership relations regardless of
membership state.</p><pre class="programlisting">
-<tt>create or replace view group_member_map
+<tt class="computeroutput">create or replace view group_member_map
as select group_id, member_id, container_id, rel_id
...
</tt>
</pre><p>The group_approved_member_map is the same as the group_member_map except
it only returns entries that relate to approved members.</p><pre class="programlisting">
-<tt>create or replace view group_approved_member_map
+<tt class="computeroutput">create or replace view group_approved_member_map
as select group_id, member_id, container_id, rel_id
...
</tt>
@@ -258,7 +257,7 @@
direct membership and indirect membership. It simply returns all members of a
group including members of components. (It is the transitive closure.)</p><pre class="programlisting">
-<tt>create or replace view group_distinct_member_map
+<tt class="computeroutput">create or replace view group_distinct_member_map
as select group_id, member_id
...
</tt>
@@ -271,20 +270,20 @@
view will have four rows for that party, one for each member, and one from
the party to itself.</p><pre class="programlisting">
-<tt>create or replace view party_member_map
+<tt class="computeroutput">create or replace view party_member_map
as select party_id, member_id
...
</tt>
</pre><p>This view is the same as above except that when it expands groups, it only
pays attention to approved members.</p><pre class="programlisting">
-<tt>create or replace view party_approved_member_map
+<tt class="computeroutput">create or replace view party_approved_member_map
as select party_id, member_id
...
</tt>
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="parties-extending-data-model"></a>Extending The Parties Data Model</h3></div></div><p>As is, the parties data model can represent some fairly sophisticated real
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="parties-extending-data-model"></a>Extending The Parties Data Model</h3></div></div><div></div></div><p>As is, the parties data model can represent some fairly sophisticated real
world situations, and a lot of work has been put into making this efficient,
but it is foolish to assume that this data model is sufficient for every
application. It therefore seems likely that developers will want to extend
@@ -299,7 +298,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.</p><p><span class="strong">Specializing Groups</span></p><p>If one were to build an intranet application on top of the 5.0.0d party
+store any extra information relevant to the MENSA community.</p><p><span class="strong">Specializing Groups</span></p><p>If one were to build an intranet application on top of the 5.0.0a1 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,4 +312,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 <a href="object-identity.html" target="_top">object identity</a>, 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.</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr><tr><td width="40%" align="left">Writing OpenACS 5.0.0d Application Pages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS 4.x Permissions Tediously Explained</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/parties.html#comments">View comments on this page at openacs.org</a></center></body></html>
+table or the groups table.</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr><tr><td width="40%" align="left">Writing OpenACS 5.0.0a1 Application Pages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS 4.x Permissions Tediously Explained</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/parties.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/permissions-design.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/permissions-design.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,12 +1,11 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Permissions Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements"><link rel="next" href="groups-requirements.html" title="OpenACS 4 Groups Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions-design"></a>OpenACS 4 Permissions Design</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Permissions Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements"><link rel="next" href="groups-requirements.html" title="OpenACS 4 Groups Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-design"></a>OpenACS 4 Permissions Design</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a> and <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl in <tt>packages/acs-kernel</tt></p></li><li><p><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top">
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl in <tt class="computeroutput">packages/acs-kernel</tt></p></li><li><p><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top">
SQL file</a></p></li><li><p><a href="images/permissions-er.png" target="_top">ER diagram</a>
-</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-intro"></a>Introduction</h3></div></div><p>The goal of the Permissions system is to provide generic means to both
+</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-intro"></a>Introduction</h3></div></div><div></div></div><p>The goal of the Permissions system is to provide generic means to both
programmers and site administrators to designate operations (methods) as
requiring permissions, and then to check, grant, or revoke permissions via a
consistent interface. For example, we might decide that the transaction that
@@ -23,66 +22,66 @@
those package objects on which a user has certain permissions.</p><p>For site administrators and other authorized users, the Permissions UI
provides a means to aggregate the primitive operations (methods) made
available by the programmer into logical privileges (like read, write, and
-admin) that can be granted and revoked.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-history"></a>Historical Considerations</h3></div></div><p>In earlier versions of the OpenACS, permissions and access control was handled
+admin) that can be granted and revoked.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-history"></a>Historical Considerations</h3></div></div><div></div></div><p>In earlier versions of the OpenACS, permissions and access control was handled
on a module-by-module basis, often even on a page-by-page basis. For example,
a typical module might allow any registered user to access its pages
read-only, but only allow members of a certain group to make changes. The way
this group was determined also varied greatly between modules. Some modules
-used "roles", while others did not. Other modules did all access
+used "roles", while others did not. Other modules did all access
control based simply on coded rules regarding who can act on a given database
row based on the information in that row.</p><p>Problems resulting from this piecemeal approach to permissions and access
control were many, the two major ones being inconsistency, and
repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified,
consistent permissions system that both programmers and administrators can
-readily use.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-competitors"></a>Competitive Analysis</h3></div></div><p><span class="emphasis"><em>None available as of 10/2000.</em></span></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>The core of the permissions data model is quite simple. Unfortunately, the
+readily use.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-competitors"></a>Competitive Analysis</h3></div></div><div></div></div><p><span class="emphasis"><em>None available as of 10/2000.</em></span></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><div></div></div><p>The core of the permissions data model is quite simple. Unfortunately, the
hierarchical nature of default permissions entails quite a number of tree
queries which could slow the system down. Since every page will have at least
one permissions check, a number of views and auxiliary tables
(de-normalizations of the data model) have been created to speed up access
queries. As a consequence, speed of updates are decreased and requirements
-for additional storage space increase.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-data-model"></a>Data Model Discussion</h3></div></div><p>As described in section V., the core of the permissions data model is
+for additional storage space increase.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-data-model"></a>Data Model Discussion</h3></div></div><div></div></div><p>As described in section V., the core of the permissions data model is
simple, though a number of views and auxiliary tables exist to ensure
-adequate performance. The core model consists of five tables:</p><div class="variablelist"><dl><dt><span class="term"><tt>acs_methods</tt>
+adequate performance. The core model consists of five tables:</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">acs_methods</tt>
-</span></dt><dd><p>The set of all defined methods.</p></dd><dt><span class="term"><tt>acs_privileges</tt>
+</span></dt><dd><p>The set of all defined methods.</p></dd><dt><span class="term"><tt class="computeroutput">acs_privileges</tt>
-</span></dt><dd><p>The set of all defined privileges.</p></dd><dt><span class="term"><tt>acs_privilege_method_rules</tt>
+</span></dt><dd><p>The set of all defined privileges.</p></dd><dt><span class="term"><tt class="computeroutput">acs_privilege_method_rules</tt>
</span></dt><dd><p>A relation describing the set of methods <span class="strong">directly</span>
-associated with each privilege.</p></dd><dt><span class="term"><tt>acs_privilege_hierarchy</tt>
+associated with each privilege.</p></dd><dt><span class="term"><tt class="computeroutput">acs_privilege_hierarchy</tt>
</span></dt><dd><p>A relation describing which privileges <span class="strong">directly</span>
-"contain" other privileges.</p></dd><dt><span class="term"><tt>acs_permissions</tt>
+"contain" other privileges.</p></dd><dt><span class="term"><tt class="computeroutput">acs_permissions</tt>
</span></dt><dd><p>A table with one (<span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>privilege</em></span>)
row for every privilege <span class="strong">directly</span> granted on any object in
the system - this is a denormalization of
-<tt>acs_privilege_method_rules</tt> and
-<tt>acs_privilege_hierarchy</tt></p></dd></dl></div><p>There are also a number of views to make it easier to ask specific
+<tt class="computeroutput">acs_privilege_method_rules</tt> and
+<tt class="computeroutput">acs_privilege_hierarchy</tt></p></dd></dl></div><p>There are also a number of views to make it easier to ask specific
questions about permissions. For example, a number of the above tables
-describe "direct" or explicit permissions. Inheritance and default
+describe "direct" or explicit permissions. Inheritance and default
values can, however, introduce permissions which are not directly specified.
(For example, read access on a bboard allows read access on all the messages
in the bboard.)</p><p>The following views provide flattened versions of inherited
-information:</p><div class="variablelist"><dl><dt><span class="term"><tt>acs_privilege_method_map</tt>
+information:</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">acs_privilege_method_map</tt>
</span></dt><dd><p>Map of privileges to the methods they contain either directly or because
-of another privilege which is included (at any depth).</p></dd><dt><span class="term"><tt>acs_object_grantee_priv_map</tt>
+of another privilege which is included (at any depth).</p></dd><dt><span class="term"><tt class="computeroutput">acs_object_grantee_priv_map</tt>
</span></dt><dd><p>Relation on (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>privilege</em></span>) for
-privileges from <tt>acs_privileges</tt>) granted directly on the object, or
-on the context of the object (at any depth).</p></dd><dt><span class="term"><tt>acs_object_party_privilege_map</tt>
+privileges from <tt class="computeroutput">acs_privileges</tt>) granted directly on the object, or
+on the context of the object (at any depth).</p></dd><dt><span class="term"><tt class="computeroutput">acs_object_party_privilege_map</tt>
</span></dt><dd><p>Relation on (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>privilege</em></span>) for
-privileges directly from <tt>acs_object_grantee_priv_map</tt> or also because
-a party is a member of a group (at any depth).</p></dd><dt><span class="term"><tt>acs_object_party_method_map</tt>
+privileges directly from <tt class="computeroutput">acs_object_grantee_priv_map</tt> or also because
+a party is a member of a group (at any depth).</p></dd><dt><span class="term"><tt class="computeroutput">acs_object_party_method_map</tt>
</span></dt><dd><p>Relation with every (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>method</em></span>)
-tuple implied by the above trees.</p></dd></dl></div><p>In general, <span class="strong">only <tt>acs_object_party_method_map</tt></span>
+tuple implied by the above trees.</p></dd></dl></div><p>In general, <span class="strong">only <tt class="computeroutput">acs_object_party_method_map</tt></span>
should be used for queries from other modules. The other views are
intermediate steps in building that query.</p><p>The data model also includes two simple PL/SQL procedures
-(<tt>acs_permission.grant_permission</tt> and
-<tt>acs_permission.revoke_permission</tt>) for granting and revoking a
+(<tt class="computeroutput">acs_permission.grant_permission</tt> and
+<tt class="computeroutput">acs_permission.revoke_permission</tt>) for granting and revoking a
specific privilege for a specific user on a specific object.</p><p>To sum up, the PL/SQL procedures are meant to be used to grant or revoke
permissions. The five base tables represent the basic data model of the
system, with a set of views provided to convert them into a format suitable
@@ -92,50 +91,50 @@
which:</p><div class="itemizedlist"><ul type="disc"><li><p>parties get the privileges of any groups they are directly or indirectly
a member of</p></li><li><p>privileges get associated with the methods of any other privileges they
have taken methods from (at any level) (see
-<tt>acs_privilege_hierarchy</tt>)</p></li><li><p>objects get access control from direct grants, or inherit permissions
-from their context (unless the "don't inherit" flag is
-set)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-transactions"></a>Legal Transactions</h3></div></div><p>There are three essential areas in which all transactions in the
-permissions system fall:</p><div class="itemizedlist"><ul type="disc"><li><p>Modification of methods and privileges</p></li><li><p>Modification of permissions</p></li><li><p>Queries on permissions</p></li></ul></div><p><span class="strong">"Modification of methods and privileges."</span> This
+<tt class="computeroutput">acs_privilege_hierarchy</tt>)</p></li><li><p>objects get access control from direct grants, or inherit permissions
+from their context (unless the "don't inherit" flag is
+set)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-transactions"></a>Legal Transactions</h3></div></div><div></div></div><p>There are three essential areas in which all transactions in the
+permissions system fall:</p><div class="itemizedlist"><ul type="disc"><li><p>Modification of methods and privileges</p></li><li><p>Modification of permissions</p></li><li><p>Queries on permissions</p></li></ul></div><p><span class="strong">"Modification of methods and privileges."</span> 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.</p><p>These steps involve directly manipulating the <tt>acs_methods</tt>,
-<tt>acs_privileges</tt>, and <tt>acs_privilege_method_rules</tt> tables. A
+administrator chooses to change permissions policy.</p><p>These steps involve directly manipulating the <tt class="computeroutput">acs_methods</tt>,
+<tt class="computeroutput">acs_privileges</tt>, and <tt class="computeroutput">acs_privilege_method_rules</tt> tables. A
web page for manipulating these features should be limited to site-wide
-administrators.</p><p><span class="strong">"Modification of permissions"</span> - involves fairly
+administrators.</p><p><span class="strong">"Modification of permissions"</span> - 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
-<tt>acs_permissions.grant_permission</tt>, and revocation via
-<tt>acs_permissions.revoke_permission</tt>. These directly manipulate the
-<tt>acs_permissions</tt> table.</p><p>Web pages for making these changes are available to all users, so they
+"grant" and "revoke". Granting permissions is done via
+<tt class="computeroutput">acs_permissions.grant_permission</tt>, and revocation via
+<tt class="computeroutput">acs_permissions.revoke_permission</tt>. These directly manipulate the
+<tt class="computeroutput">acs_permissions</tt> table.</p><p>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 <tt>administer_privileges</tt> method
-permission on that object.</p><p><span class="strong">"Queries on permissions"</span> - by far the most
+an object, the user must have the <tt class="computeroutput">administer_privileges</tt> method
+permission on that object.</p><p><span class="strong">"Queries on permissions"</span> - by far the most
common operation is querying the permissions database. Several kinds of
-questions are commonly asked: First, and most commonly, "Can this party
-perform this method on this object?" Two Tcl functions are provided to
+questions are commonly asked: First, and most commonly, "Can this party
+perform this method on this object?" Two Tcl functions are provided to
answer this - one which returns a boolean, the other of which results in an
error page. These tcl functions directly access the
-<tt>acs_object_party_method_map</tt>.</p><p>The second most commonly asked question occurs when a list of objects is
+<tt class="computeroutput">acs_object_party_method_map</tt>.</p><p>The second most commonly asked question occurs when a list of objects is
being displayed, often in order to provide appropriate UI functionality:
-"For this party, what methods are available on these objects?"
+"For this party, what methods are available on these objects?"
Here, the SQL query needs to filter based on whether the party/user can
perform some operation on the object. This is done via a join or sub-select
-against <tt>acs_object_party_method_map</tt>, or by calling the Tcl functions
+against <tt class="computeroutput">acs_object_party_method_map</tt>, or by calling the Tcl functions
for appropriate methods.</p><p>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 <tt>acs_permissions</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-api"></a>API</h3></div></div><p>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.</p><p><span class="strong">Tables</span></p><p><tt>acs_methods</tt>, <tt>acs_privileges</tt>, and
-<tt>acs_privilege_method_rules</tt> manage the set of permissions in the
+by querying against <tt class="computeroutput">acs_permissions</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-api"></a>API</h3></div></div><div></div></div><p>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.</p><p><span class="strong">Tables</span></p><p><tt class="computeroutput">acs_methods</tt>, <tt class="computeroutput">acs_privileges</tt>, and
+<tt class="computeroutput">acs_privilege_method_rules</tt> 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.</p><p>The main table for queries is <tt>acs_object_party_method_map</tt>, which
+introduce new permissions into the system.</p><p>The main table for queries is <tt class="computeroutput">acs_object_party_method_map</tt>, which
contains (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>method</em></span>) triples for all
-allowed operations in the system.</p><p>Also of interest for queries is <tt>acs_permissions</tt>, which lists
-directly granted privileges. Neither <tt>acs_object_party_method_map</tt>
-(which is a view) nor <tt>acs_permissions</tt> should be updated
-directly.</p><p><span class="strong">PL/SQL Procedures</span></p><p><tt>acs_permissions.grant_permission</tt> introduces new permissions for
+allowed operations in the system.</p><p>Also of interest for queries is <tt class="computeroutput">acs_permissions</tt>, which lists
+directly granted privileges. Neither <tt class="computeroutput">acs_object_party_method_map</tt>
+(which is a view) nor <tt class="computeroutput">acs_permissions</tt> should be updated
+directly.</p><p><span class="strong">PL/SQL Procedures</span></p><p><tt class="computeroutput">acs_permissions.grant_permission</tt> introduces new permissions for
an object. It should be given an (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>,
<span class="emphasis"><em>privilege</em></span>) triple, and will always succeed. If the permission is
already in the system, no change occurs. The interface for this procedure
@@ -145,7 +144,7 @@
grantee_id acs_permissions.grantee_id%TYPE,
privilege acs_permissions.privilege%TYPE
);
-</pre><p><tt>acs_permissions.revoke_permission</tt> removes a permission entry
+</pre><p><tt class="computeroutput">acs_permissions.revoke_permission</tt> removes a permission entry
given a triple. It always succeeds--if a permission does not exist, nothing
changes. The interface for this procedure is:</p><pre class="programlisting">
procedure revoke_permission (
@@ -154,34 +153,34 @@
privilege acs_permissions.privilege%TYPE
);
</pre><p>These procedures are defined in <a href="http://acs40.arsdigita.com/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top">
-<tt>permissions-create.sql</tt></a></p><p><span class="strong">Tcl Procedures</span></p><p>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
+<tt class="computeroutput">permissions-create.sql</tt></a></p><p><span class="strong">Tcl Procedures</span></p><p>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.</p><p>To receive a true or false value, Tcl code should call:</p><pre class="programlisting">
ad_permission_p $object_id $object_type $method -user_id $user_id
-</pre><p>If the <tt>user_id</tt> argument is left out, then the currently logged in
+</pre><p>If the <tt class="computeroutput">user_id</tt> argument is left out, then the currently logged in
user is checked. To create an error page, Tcl code should call:</p><pre class="programlisting">
ad_require_permission $object_id $object_type $method
-</pre><p>These procedures are defined in <tt>acs-permissions-procs.tcl</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-ui"></a>User Interface</h3></div></div><p>All users of the permissions system are the same at the user-interface
-level. If you have the <tt>administer_privileges</tt> method permission on an
+</pre><p>These procedures are defined in <tt class="computeroutput">acs-permissions-procs.tcl</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-ui"></a>User Interface</h3></div></div><div></div></div><p>All users of the permissions system are the same at the user-interface
+level. If you have the <tt class="computeroutput">administer_privileges</tt> method permission on an
object, then you may edit privileges for that object with the UI.</p><p>The UI currently provides a list of all granted permissions on the object.
If the user wishes to revoke privileges, she may select a set of grants,
choose revoke, confirm their deletion, and be returned to the same page after
those privileges have been revoked.</p><p>Granting permissions currently (as of 10/2000) works by providing a list
of all possible permissions and a list of all parties in the system. (For
large sites, some future search mechanism will be necessary.) After choosing
-privileges to grant, the user is returned to the "edit privileges for
-one object" screen.</p><p>If it makes sense, the system will also display a checkbox which the user
+privileges to grant, the user is returned to the "edit privileges for
+one object" screen.</p><p>If it makes sense, the system will also display a checkbox which the user
may select to toggle whether permissions are inherited from the object's
context.</p><p>There are a number of potential future enhancements for the permissions
-UI, outlined below.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-configure"></a>Configuration/Parameters</h3></div></div><p>There are no configuration options for the permissions system.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>The most important future changes to the Permissions system are likely to
+UI, outlined below.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-configure"></a>Configuration/Parameters</h3></div></div><div></div></div><p>There are no configuration options for the permissions system.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><div></div></div><p>The most important future changes to the Permissions system are likely to
be in the UI:</p><div class="itemizedlist"><ul type="disc"><li><p>There should be a page displaying a list of all objects for which the
current user is allowed to administer privileges.</p></li><li><p>Users should be able to view the permissions on any object, or perhaps on
-objects which they have the "read_permissions" method. This would
+objects which they have the "read_permissions" method. This would
allow them to see what grants are affecting their objects through
-inheritance.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-authors"></a>Authors</h3></div></div><div class="variablelist"><dl><dt><span class="term">System creator
+inheritance.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-authors"></a>Authors</h3></div></div><div></div></div><div class="variablelist"><dl><dt><span class="term">System creator
</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">System owner
</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">Documentation author
-</span></dt><dd><p><a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a></p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/11/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta release</td><td>10/04/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Permissions Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Groups Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
+</span></dt><dd><p><a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a></p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/11/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta release</td><td>10/04/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Permissions Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Groups Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 14 Oct 2003 11:02:58 -0000 1.12
@@ -1,12 +1,11 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Permissions Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="object-system-design.html" title="OpenACS 4 Object Model Design"><link rel="next" href="permissions-design.html" title="OpenACS 4 Permissions Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions-requirements"></a>OpenACS 4 Permissions Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Permissions Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="object-system-design.html" title="OpenACS 4 Object Model Design"><link rel="next" href="permissions-design.html" title="OpenACS 4 Permissions Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-requirements"></a>OpenACS 4 Permissions Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:jmp@arsdigita.com" target="_top">John McClary Prevost</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-intro"></a>Introduction</h3></div></div><p>This document records requirements for the OpenACS 4 Permissions system, a
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-intro"></a>Introduction</h3></div></div><div></div></div><p>This document records requirements for the OpenACS 4 Permissions system, a
component of the OpenACS 4 Kernel. The Permissions system is meant to unify and
-centralize the handling of access and control on a given OpenACS 4 system.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-vision"></a>Vision Statement</h3></div></div><p>Any multi-user software system must address the general problem of
-permissions, or "who can do what, on what." On web services, which
+centralize the handling of access and control on a given OpenACS 4 system.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>Any multi-user software system must address the general problem of
+permissions, or "who can do what, on what." On web services, which
typically involve large numbers of users belonging to different groups,
permissions handling is a critical need: access to content, services, and
information generally must be controlled. The OpenACS 4 Permissions system is
@@ -20,54 +19,54 @@
a typical module might allow any registered user to access its pages
read-only, but only allow members of a certain group to make changes. The way
this group was determined also varied greatly between modules. Some modules
-used "roles", while others did not. Other modules did all access
+used "roles", while others did not. Other modules did all access
control based simply on coded rules regarding who can act on a given database
row based on the information in that row.</p><p>Problems resulting from this piecemeal approach to permissions and access
control were many, the two major ones being inconsistency, and
repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified,
consistent permissions system that both programmers and administrators can
-readily use.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-system-overview"></a>System Overview</h3></div></div><p>The OpenACS 4 Permissions system has two main pieces: first, an API for
+readily use.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-system-overview"></a>System Overview</h3></div></div><div></div></div><p>The OpenACS 4 Permissions system has two main pieces: first, an API for
developers to readily handle access control in their applications. The second
piece of the system is a UI meant primarily for (subsite) administrators to
grant and revoke permissions to system entities under their control.</p><p>Consistency is a key characteristic of the Permissions system - both for a
common administrative interface, and easily deployed and maintained access
control. The system must be flexible enough to support every access model
required in OpenACS applications, but not so flexible that pieces will go unused
-or fall outside the common administrative interfaces.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-"></a>Use Cases and User Scenarios</h3></div></div><p><span class="strong">Terminology</span></p><p>The primary question an access control system must answer is a three-way
+or fall outside the common administrative interfaces.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-"></a>Use Cases and User Scenarios</h3></div></div><div></div></div><p><span class="strong">Terminology</span></p><p>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:</p><p>The subject of the sentence is "<span class="strong">party</span>" - a
+context of OpenACS Permissions, our simple sentence is, "Can this party
+perform this operation on this target?" Definitions:</p><p>The subject of the sentence is "<span class="strong">party</span>" - 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).</p><p>The object of the sentence is "<span class="strong">target</span>" - this
+may represent many users (or no users at all).</p><p>The object of the sentence is "<span class="strong">target</span>" - 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.</p><p>The verb of the sentence is "operation" - a behavior on the OpenACS
+entity/object here is anything that can be put under access control.</p><p>The verb of the sentence is "operation" - a behavior on the OpenACS
system subject to control, this word is used to represent the fact that a
single operation may be part of many larger actions the system wants to
-perform. If "foo" is an operation, than we sometimes refer to the
-foo "privilege" to mean that a user has the privilege to perform
+perform. If "foo" is an operation, than we sometimes refer to the
+foo "privilege" to mean that a user has the privilege to perform
that operation.</p><p>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?</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="permissions-design.html">OpenACS 4 Permissions Design</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-func-req"></a>Functional Requirements</h3></div></div><p><span class="strong">10.0 Granularity</span></p><p>The system must support access control down to the level of a single
+instance?</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-links"></a>Related Links</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="permissions-design.html">OpenACS 4 Permissions Design</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-func-req"></a>Functional Requirements</h3></div></div><div></div></div><p><span class="strong">10.0 Granularity</span></p><p>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).</p><p><span class="strong">20.0 Operations</span></p><p>The system itself must be able to answer the essential permissions
-question as well as several derived questions.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.10 Basic Access Check</span></p><p>The system must be able to answer the question, "May party P perform
-operation O on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.20 Allowed Parties Check</span></p><p>The system must be able to answer the question, "Which parties may
-perform operation O on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.30 Allowed Operations Check</span></p><p>The system must be able to answer the question, "Which operations may
-party P perform on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.40 Allowed Targets Check</span></p><p>The system must be able to answer the question, "Upon which targets
-may party P perform operation O?"</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-behave-req"></a>Behavioral Requirements</h3></div></div><p><span class="strong">40.0 Scale of Privileges</span></p><p>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"
+question as well as several derived questions.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.10 Basic Access Check</span></p><p>The system must be able to answer the question, "May party P perform
+operation O on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.20 Allowed Parties Check</span></p><p>The system must be able to answer the question, "Which parties may
+perform operation O on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.30 Allowed Operations Check</span></p><p>The system must be able to answer the question, "Which operations may
+party P perform on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.40 Allowed Targets Check</span></p><p>The system must be able to answer the question, "Upon which targets
+may party P perform operation O?"</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-behave-req"></a>Behavioral Requirements</h3></div></div><div></div></div><p><span class="strong">40.0 Scale of Privileges</span></p><p>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.</p><p><span class="strong">50.0 Aggregation of Operations (Privileges)</span></p><p>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.</p><p><span class="strong">60.0 Aggregation of Parties (Groups)</span></p><p>The system must allow aggregation of parties. The exact method used for
-aggregation will probably be addressed by the OpenACS 4 "Groups"
+"read" to mean too many things.</p><p><span class="strong">50.0 Aggregation of Operations (Privileges)</span></p><p>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.</p><p><span class="strong">60.0 Aggregation of Parties (Groups)</span></p><p>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.</p><p><span class="strong">70.0 Scope of Access Control</span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">70.10 Context</span></p><p>There must be a method for objects to receive default access control from
@@ -83,10 +82,10 @@
(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).</p><p>In particular, constraining a <tt>SELECT</tt> to return only rows the
-current user has access to should not be much slower than the <tt>SELECT</tt>
+targets check (20.40).</p><p>In particular, constraining a <tt class="computeroutput">SELECT</tt> to return only rows the
+current user has access to should not be much slower than the <tt class="computeroutput">SELECT</tt>
on its own.</p><p><span class="strong">120.0 Ease of Use</span></p><p>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.</p><p>In particular, constraining a <tt>SELECT</tt> to return only rows the
-current user has access to should not add more than one line to a query.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/17/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Revised, updated with new terminology</td><td>8/25/2000</td><td>John Prevost</td></tr><tr><td>0.3</td><td>Edited, reformatted to conform to requirements template, pending
+small and simple.</p><p>In particular, constraining a <tt class="computeroutput">SELECT</tt> to return only rows the
+current user has access to should not add more than one line to a query.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/17/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Revised, updated with new terminology</td><td>8/25/2000</td><td>John Prevost</td></tr><tr><td>0.3</td><td>Edited, reformatted to conform to requirements template, pending
freeze.</td><td>8/26/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Edited for ACS 4 Beta release.</td><td>10/03/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Object Model Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Permissions Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 20 Aug 2003 16:20:16 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 14 Oct 2003 11:02:58 -0000 1.7
@@ -1,7 +1,6 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4.x Permissions Tediously Explained</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="parties.html" title="Parties in OpenACS 5.0.0d"><link rel="next" href="object-identity.html" title="Object Identity"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions-tediously-explained"></a>OpenACS 4.x Permissions Tediously Explained</h2></div></div><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4.x Permissions Tediously Explained</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="parties.html" title="Parties in OpenACS 5.0.0a1"><link rel="next" href="object-identity.html" title="Object Identity"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-tediously-explained"></a>OpenACS 4.x Permissions Tediously Explained</h2></div></div><div></div></div><p>
by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello
- </p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-tedious-overview"></a>Overview</h3></div></div><p>
+ </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-overview"></a>Overview</h3></div></div><div></div></div><p>
The general permissions system has a relatively complex data model in OpenACS 4.x.
Developers who haven't had the time to learn the internals of the data model
may end up writing seemingly correct code that crashes their system in
@@ -15,9 +14,9 @@
system internals.
</p><p>
In OpenACS 4.x, most of the interesting tables are expected to extend (subtype)
- the <tt>acs_objects</tt> table, i.e. they are expected to have an integer
- primary key column that references the <tt>object_id</tt> column of
- <tt>acs_objects</tt>.
+ the <tt class="computeroutput">acs_objects</tt> table, i.e. they are expected to have an integer
+ primary key column that references the <tt class="computeroutput">object_id</tt> column of
+ <tt class="computeroutput">acs_objects</tt>.
</p><a name="acs_objects"></a><pre class="programlisting">
create table <span class="bold"><b>acs_objects</b></span> (
object_id integer
@@ -43,14 +42,14 @@
);
</pre><p>
This means that any interesting entity (object)
- in the system has an entry in the <tt>acs_objects</tt>. This
+ in the system has an entry in the <tt class="computeroutput">acs_objects</tt>. This
allows developers to define relationships between any two entities <span class="emphasis"><em>A</em></span>
and <span class="emphasis"><em>B</em></span> by defining a relationship between their corresponding entries
- in the <tt>acs_objects</tt> table. One of the applications of this
+ in the <tt class="computeroutput">acs_objects</tt> table. One of the applications of this
powerful capability is the general permissions system.
</p><p>
- At the heart of the permission system are two tables: <tt>acs_privileges</tt>
- and <tt>acs_permissions</tt>.
+ At the heart of the permission system are two tables: <tt class="computeroutput">acs_privileges</tt>
+ and <tt class="computeroutput">acs_permissions</tt>.
</p><a name="acs_privileges"></a><pre class="programlisting">
create table <span class="bold"><b>acs_privileges</b></span> (
privilege varchar2(100) not null
@@ -73,20 +72,20 @@
primary key (object_id, grantee_id, privilege)
);
</pre><p>
- The <tt>acs_privileges</tt> table stores
+ The <tt class="computeroutput">acs_privileges</tt> table stores
named privileges like <span class="emphasis"><em>read</em></span>,
<span class="emphasis"><em>write</em></span>, <span class="emphasis"><em>delete</em></span>, <span class="emphasis"><em>create</em></span>, and
- <span class="emphasis"><em>admin</em></span>. The <tt>acs_permissions</tt>
+ <span class="emphasis"><em>admin</em></span>. The <tt class="computeroutput">acs_permissions</tt>
table stores assertions of the form:
</p><p>
- Who (<tt>grantee_id</tt>) can do what (<tt>privilege</tt>)
- on which object (<tt>object_id</tt>).
+ Who (<tt class="computeroutput">grantee_id</tt>) can do what (<tt class="computeroutput">privilege</tt>)
+ on which object (<tt class="computeroutput">object_id</tt>).
</p><p>
The naive approach to managing system security would be to require application developers
to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users
who have the <span class="emphasis"><em>read</em></span> privilege on all objects, then we would need to store 100,000,000
entries of the form:
- </p><div class="table"><a name="id2955192"></a><p class="title"><b>Table�11.1.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object_id</th><th align="center">grantee_id</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">object_id_1</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_n</td><td align="center">'read'</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2849194"></a><p class="title"><b>Table�11.1.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object_id</th><th align="center">grantee_id</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">object_id_1</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_n</td><td align="center">'read'</td></tr></tbody></table></div><p>
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
@@ -98,42 +97,42 @@
necessity to explicitly maintain security information for every single
object. There are three kinds of hierarchies involved.
These are discussed in the following sections.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-tedious-context-hierarchy"></a>Context Hierarchy</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-context-hierarchy"></a>Context Hierarchy</h3></div></div><div></div></div><p>
Suppose objects <span class="emphasis"><em>A</em></span>, <span class="emphasis"><em>B</em></span>, ...,
and <span class="emphasis"><em>F</em></span> form the following hierarchy.
- </p><div class="table"><a name="id2900800"></a><p class="title"><b>Table�11.2.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="3" align="center"><span class="bold"><b>A</b></span><p>
- <tt>object_id=10</tt>
+ </p><div class="table"><a name="id2850069"></a><p class="title"><b>Table�11.2.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="3" align="center"><span class="bold"><b>A</b></span><p>
+ <tt class="computeroutput">object_id=10</tt>
</p></td></tr><tr><td colspan="2" align="center"><span class="bold"><b>B</b></span><p>
- <tt>object_id=20</tt>
+ <tt class="computeroutput">object_id=20</tt>
</p></td><td align="center"><span class="bold"><b>C</b></span><p>
- <tt>object_id=30</tt>
+ <tt class="computeroutput">object_id=30</tt>
</p></td></tr><tr><td align="center"><span class="bold"><b>D</b></span><p>
- <tt>object_id=40</tt>
+ <tt class="computeroutput">object_id=40</tt>
</p></td><td align="center"><span class="bold"><b>E</b></span><p>
- <tt>object_id=50</tt>
+ <tt class="computeroutput">object_id=50</tt>
</p></td><td align="center"><span class="bold"><b>F</b></span><p>
- <tt>object_id=60</tt>
+ <tt class="computeroutput">object_id=60</tt>
</p></td></tr></tbody></table></div><p>
- This can be represented in the <tt>
+ This can be represented in the <tt class="computeroutput">
<a href="permissions-tediously-explained.html#acs_objects">acs_objects</a></tt> table
by the following entries:
- </p><div class="table"><a name="id2898303"></a><p class="title"><b>Table�11.3.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object_id</th><th align="center">context_id</th></tr></thead><tbody><tr><td align="center">20</td><td align="center">10</td></tr><tr><td align="center">30</td><td align="center">10</td></tr><tr><td align="center">40</td><td align="center">20</td></tr><tr><td align="center">50</td><td align="center">20</td></tr><tr><td align="center">60</td><td align="center">30</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2850269"></a><p class="title"><b>Table�11.3.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object_id</th><th align="center">context_id</th></tr></thead><tbody><tr><td align="center">20</td><td align="center">10</td></tr><tr><td align="center">30</td><td align="center">10</td></tr><tr><td align="center">40</td><td align="center">20</td></tr><tr><td align="center">50</td><td align="center">20</td></tr><tr><td align="center">60</td><td align="center">30</td></tr></tbody></table></div><p>
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 <a href="http://www.oradoc.com/ora817/server.817/a85397/expressi.htm#1023748" target="_top">CONNECT BY</a> 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 <span class="emphasis"><em>read</em></span> privilege on objects
<span class="emphasis"><em>A</em></span>, ..., <span class="emphasis"><em>F</em></span>, we only need to record one entry in the
- <tt><a href="permissions-tediously-explained.html#acs_permissions">acs_permissions</a></tt> table.
- </p><div class="table"><a name="id2898462"></a><p class="title"><b>Table�11.4.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object</th><th align="center">grantee</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">Joe</td><td align="center">read</td></tr></tbody></table></div><p>
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_permissions">acs_permissions</a></tt> table.
+ </p><div class="table"><a name="id2850426"></a><p class="title"><b>Table�11.4.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object</th><th align="center">grantee</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">Joe</td><td align="center">read</td></tr></tbody></table></div><p>
The fact that Joe can also read <span class="emphasis"><em>B</em></span>, <span class="emphasis"><em>C</em></span>,
..., and <span class="emphasis"><em>F</em></span> can be derived by ascertaining that these objects
are children of <span class="emphasis"><em>A</em></span> by traversing the context hierarchy.
As it turns out, hierarchical queries are expensive. As
Rafael Schloming put it so aptly, <span class="emphasis"><em>Oracle can't deal with hierarchies for shit.</em></span>
</p><p>
One way to solve this problem is to cache a flattened view of the context tree like so:
- </p><div class="table"><a name="id2898586"></a><p class="title"><b>Table�11.5.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object</th><th align="center">ancestor</th><th align="center">n_generations</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">A</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">B</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">C</td><td align="center">C</td><td align="center">0</td></tr><tr><td align="center">C</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">D</td><td align="center">0</td></tr><tr><td align="center">D</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">E</td><td align="center">E</td><td align="center">0</td></tr><tr><td align="center">E</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">E</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">F</td><td align="center">F</td><td align="center">0</td></tr><tr><td align="center">F</td><td align="center">C</td><td align="center">1</td></tr><tr><td align="center">F</td><td align="center">A</td><td align="center">2</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2850550"></a><p class="title"><b>Table�11.5.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center">object</th><th align="center">ancestor</th><th align="center">n_generations</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">A</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">B</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">C</td><td align="center">C</td><td align="center">0</td></tr><tr><td align="center">C</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">D</td><td align="center">0</td></tr><tr><td align="center">D</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">E</td><td align="center">E</td><td align="center">0</td></tr><tr><td align="center">E</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">E</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">F</td><td align="center">F</td><td align="center">0</td></tr><tr><td align="center">F</td><td align="center">C</td><td align="center">1</td></tr><tr><td align="center">F</td><td align="center">A</td><td align="center">2</td></tr></tbody></table></div><p>
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 <span class="emphasis"><em>n</em></span>, then the number of entries
@@ -143,7 +142,7 @@
Despite its potentially great storage costs, maintaining a
flattened representation of the context tree is exactly what OpenACS 4.x
does. The flattened context tree is stored in the
- <tt>acs_object_context_index</tt> table.
+ <tt class="computeroutput">acs_object_context_index</tt> table.
</p><a name="acs_object_context_index"></a><pre class="programlisting">
create table <span class="bold"><b>acs_object_context_index</b></span> (
object_id
@@ -154,7 +153,7 @@
constraint acs_obj_context_idx_anc_id_fk references <a href="permissions-tediously-explained.html#acs_objects">acs_objects</a>(object_id),
n_generations integer
not null
- constraint acs_obj_context_idx_n_gen_ck check (n_generations >= 0),
+ constraint acs_obj_context_idx_n_gen_ck check (n_generations <span class="markup">></span>= 0),
constraint acs_object_context_index_pk
primary key (object_id, ancestor_id)
) organization index;
@@ -168,8 +167,8 @@
has, and <span class="strong">exponentially</span>
with respect to the depth of the context tree.
</p><p>
- The <tt>acs_object_context_index</tt> is kept in sync with the
- <tt><a href="permissions-tediously-explained.html#acs_objects">acs_objects</a></tt>
+ The <tt class="computeroutput">acs_object_context_index</tt> is kept in sync with the
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_objects">acs_objects</a></tt>
table by triggers like this:
</p><pre class="programlisting">
create or replace trigger acs_objects_context_id_in_tr
@@ -199,40 +198,40 @@
end if;
end;
</pre><p>
- One final note about <tt>
+ One final note about <tt class="computeroutput">
<a href="permissions-tediously-explained.html#acs_objects">acs_objects</a></tt>. By setting
- an object's <tt>security_inherit_p</tt> column to 'f', you can stop permissions
+ an object's <tt class="computeroutput">security_inherit_p</tt> 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 <span class="emphasis"><em>C</em></span> and <span class="emphasis"><em>F</em></span>.
- </p><div class="table"><a name="id2904529"></a><p class="title"><b>Table�11.6.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="3" align="center"><div class="literallayout"><p><br>
+ </p><div class="table"><a name="id2853662"></a><p class="title"><b>Table�11.6.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="3" align="center"><div class="literallayout"><p><br>
<span class="bold"><b>A</b></span><br>
-<tt>object_id=10</tt><br>
+<tt class="computeroutput">object_id=10</tt><br>
<span class="emphasis"><em>readable�by�Joe</em></span><br>
������</p></div></td></tr><tr><td colspan="2" align="center"><div class="literallayout"><p><br>
<span class="bold"><b>B</b></span><br>
-<tt>object_id=20</tt><br>
+<tt class="computeroutput">object_id=20</tt><br>
<span class="emphasis"><em>readable�by�Joe</em></span><br>
��������������</p></div></td><td align="center"><div class="literallayout"><p><br>
<span class="bold"><b>C</b></span><br>
-<tt>object_id=30</tt><br>
+<tt class="computeroutput">object_id=30</tt><br>
security_inherit_p�=�'f'<br>
<span class="emphasis"><em>not�readable�by�Joe</em></span><br>
������</p></div></td></tr><tr><td align="center"><div class="literallayout"><p><br>
<span class="bold"><b>D</b></span><br>
-<tt>object_id=40</tt><br>
+<tt class="computeroutput">object_id=40</tt><br>
������</p></div></td><td align="center"><div class="literallayout"><p><br>
<span class="bold"><b>E</b></span><br>
-<tt>object_id=50</tt><br>
+<tt class="computeroutput">object_id=50</tt><br>
������</p></div></td><td align="center"><div class="literallayout"><p><br>
<span class="bold"><b>F</b></span><br>
-<tt>object_id=60</tt><br>
+<tt class="computeroutput">object_id=60</tt><br>
security_inherit_p�=�'f'<br>
<span class="emphasis"><em>not�readable�by�Joe</em></span><br>
- ������</p></div></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-tedious-privilege-hierarchy"></a>Privilege Hierarchy</h3></div></div><p>
+ ������</p></div></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-privilege-hierarchy"></a>Privilege Hierarchy</h3></div></div><div></div></div><p>
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:
- </p><div class="table"><a name="id2904803"></a><p class="title"><b>Table�11.7.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"></colgroup><thead><tr><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">create_category</td></tr><tr><td align="center">create_forum</td></tr><tr><td align="center">create_message</td></tr><tr><td align="center">delete_category</td></tr><tr><td align="center">delete_forum</td></tr><tr><td align="center">delete_message</td></tr><tr><td align="center">moderate_forum</td></tr><tr><td align="center">read_category</td></tr><tr><td align="center">read_forum</td></tr><tr><td align="center">read_message</td></tr><tr><td align="center">write_category</td></tr><tr><td align="center">write_forum</td></tr><tr><td align="center">write_message</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2853885"></a><p class="title"><b>Table�11.7.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"></colgroup><thead><tr><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">create_category</td></tr><tr><td align="center">create_forum</td></tr><tr><td align="center">create_message</td></tr><tr><td align="center">delete_category</td></tr><tr><td align="center">delete_forum</td></tr><tr><td align="center">delete_message</td></tr><tr><td align="center">moderate_forum</td></tr><tr><td align="center">read_category</td></tr><tr><td align="center">read_forum</td></tr><tr><td align="center">read_message</td></tr><tr><td align="center">write_category</td></tr><tr><td align="center">write_forum</td></tr><tr><td align="center">write_message</td></tr></tbody></table></div><p>
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 <span class="emphasis"><em>read</em></span>, <span class="emphasis"><em>write</em></span>, <span class="emphasis"><em>delete</em></span>,
@@ -241,9 +240,9 @@
privilege to which the first four privileges are tied. To give
a more detailed example, the Bboard privileges are structured
as follows.
- </p><div class="table"><a name="id2904988"></a><p class="title"><b>Table�11.8.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="13" align="center">admin</td></tr><tr><td colspan="3" align="center">create</td><td colspan="3" align="center">delete</td><td colspan="3" align="center">read</td><td colspan="3" align="center">write</td><td rowspan="2" align="center" valign="middle">moderate forum</td></tr><tr><td align="center">create category</td><td align="center">create forum</td><td align="center">create message</td><td align="center">delete category</td><td align="center">delete forum</td><td align="center">delete message</td><td align="center">read category</td><td align="center">read forum</td><td align="center">read message</td><td align="center">write category</td><td align="center">write forum</td><td align="center">write message</td></tr></tbody></table></div><p>
+ </p><div class="table"><a name="id2854071"></a><p class="title"><b>Table�11.8.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="13" align="center">admin</td></tr><tr><td colspan="3" align="center">create</td><td colspan="3" align="center">delete</td><td colspan="3" align="center">read</td><td colspan="3" align="center">write</td><td rowspan="2" align="center" valign="middle">moderate forum</td></tr><tr><td align="center">create category</td><td align="center">create forum</td><td align="center">create message</td><td align="center">delete category</td><td align="center">delete forum</td><td align="center">delete message</td><td align="center">read category</td><td align="center">read forum</td><td align="center">read message</td><td align="center">write category</td><td align="center">write forum</td><td align="center">write message</td></tr></tbody></table></div><p>
The parent-child relationship between privileges is represented in
- the <tt>acs_privilege_hierarchy</tt> table:
+ the <tt class="computeroutput">acs_privilege_hierarchy</tt> table:
</p><a name="acs_privilege_hierarchy"></a><pre class="programlisting">
create table <span class="bold"><b>acs_privilege_hierarchy</b></span> (
privilege
@@ -284,10 +283,10 @@
reasonably small, there is no pressing need to cache the flattened ansector-descendant
view of the privilege hierarchy in a specially maintained table like
it is done in the case of the context hierarchy.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-tedious-party-hierarchy"></a>Party Hierarchy</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-party-hierarchy"></a>Party Hierarchy</h3></div></div><div></div></div><p>
Now for the third hierarchy playing a promiment role in the permission system. The party
data model is set up as follows.
- </p><div class="table"><a name="id2905350"></a><p class="title"><b>Table�11.9.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="2" align="center"><a href="permissions-tediously-explained.html#tedious-parties">parties</a></td></tr><tr><td align="center"><a href="permissions-tediously-explained.html#persons">persons</a></td><td rowspan="2" align="center" valign="top"><a href="permissions-tediously-explained.html#groups">groups</a></td></tr><tr><td align="center"><a href="permissions-tediously-explained.html#users">users</a></td></tr></tbody></table></div><a name="tedious-parties"></a><pre class="programlisting">
+ </p><div class="table"><a name="id2855166"></a><p class="title"><b>Table�11.9.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"></colgroup><tbody><tr><td colspan="2" align="center"><a href="permissions-tediously-explained.html#tedious-parties">parties</a></td></tr><tr><td align="center"><a href="permissions-tediously-explained.html#persons">persons</a></td><td rowspan="2" align="center" valign="top"><a href="permissions-tediously-explained.html#groups">groups</a></td></tr><tr><td align="center"><a href="permissions-tediously-explained.html#users">users</a></td></tr></tbody></table></div><a name="tedious-parties"></a><pre class="programlisting">
create table <span class="bold"><b>parties</b></span> (
party_id
not null
@@ -326,9 +325,9 @@
group_name varchar2(100) not null
);
</pre><p>
- Recall that the <tt>grantee_id</tt> column of the
+ Recall that the <tt class="computeroutput">grantee_id</tt> column of the
<a href="permissions-tediously-explained.html#acs_permissions">acs_permissions</a> table references
- <tt>parties.party_id</tt>.
+ <tt class="computeroutput">parties.party_id</tt>.
This means that you can grant a privilege on an object to a party, person, user, or group.
Groups represent aggregations of parties. The most common scenario that you are likely
to encounter is a group that is a collection of users, although you could also
@@ -339,7 +338,7 @@
a group named <span class="emphasis"><em>Pranksters</em></span>, you can assign membership to Pete,
Poly, and Penelope. The fact that these users are members of the
<span class="emphasis"><em>Pranksters</em></span> group will be recorded in the
- <tt>membership_rels</tt> and <tt>acs_rels</tt> tables:
+ <tt class="computeroutput">membership_rels</tt> and <tt class="computeroutput">acs_rels</tt> tables:
</p><a name="acs_rels"></a><pre class="programlisting">
create table <span class="bold"><b>acs_rels</b></span> (
rel_id
@@ -369,9 +368,9 @@
check (member_state in ('approved', 'banned', 'rejected', 'deleted'))
);
</pre><p>
- The <tt><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>
+ The <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>
table entries would look like so:
- </p><div class="table"><a name="id2905776"></a><p class="title"><b>Table�11.10.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center"><tt>rel_type</tt></th><th align="center"><tt>object_one</tt></th><th align="center"><tt>object_two</tt></th></tr></thead><tbody><tr><td align="center">
+ </p><div class="table"><a name="id2855544"></a><p class="title"><b>Table�11.10.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center"><tt class="computeroutput">rel_type</tt></th><th align="center"><tt class="computeroutput">object_one</tt></th><th align="center"><tt class="computeroutput">object_two</tt></th></tr></thead><tbody><tr><td align="center">
membership_rel
</td><td align="center">
Pranksters
@@ -395,8 +394,8 @@
of <span class="emphasis"><em>Pranksters</em></span>. We say that the <span class="emphasis"><em>Pranksters</em></span> group
is <span class="strong">composed</span> of
groups <span class="emphasis"><em>Merry Pranksters</em></span> and <span class="emphasis"><em>Sad Pranksters</em></span>. This
- information is stored in the <tt><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>
- and <tt>composition_rels</tt> tables.
+ information is stored in the <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>
+ and <tt class="computeroutput">composition_rels</tt> tables.
</p><a name="composition_rels"></a><pre class="programlisting">
create table <span class="bold"><b>composition_rels</b></span> (
rel_id
@@ -405,8 +404,8 @@
);
</pre><p>
The relevant entries in the
- <tt><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt> look like so.
- </p><div class="table"><a name="id2906016"></a><p class="title"><b>Table�11.11.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center"><tt>rel_type</tt></th><th align="center"><tt>object_one</tt></th><th align="center"><tt>object_two</tt></th></tr></thead><tbody><tr><td align="center">
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt> look like so.
+ </p><div class="table"><a name="id2855764"></a><p class="title"><b>Table�11.11.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center"><tt class="computeroutput">rel_type</tt></th><th align="center"><tt class="computeroutput">object_one</tt></th><th align="center"><tt class="computeroutput">object_two</tt></th></tr></thead><tbody><tr><td align="center">
composition_rel
</td><td align="center">
Pranksters
@@ -472,17 +471,17 @@
primary key (member_id, group_id, rel_id)
) organization index;
</pre><p>
- The <tt>group_component_index</tt> table stores a flattened representation of the
- group composition hierarchy that is maintained in sync with the <tt><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>
- and <tt>composition_rels</tt> tables through triggers.
+ The <tt class="computeroutput">group_component_index</tt> table stores a flattened representation of the
+ group composition hierarchy that is maintained in sync with the <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>
+ and <tt class="computeroutput">composition_rels</tt> tables through triggers.
</p><p>
- As far as the <tt>group_member_index</tt> table goes, I am not sure I understand its
+ As far as the <tt class="computeroutput">group_member_index</tt> table goes, I am not sure I understand its
purpose. It maintains group-member relationships that are resolved with respect
to group composition. Note that information stored in
- <tt><a href="permissions-tediously-explained.html#group_member_index">group_member_index</a></tt> can be trivially derived by joining
- <tt><a href="permissions-tediously-explained.html#membership_rels">membership_rels</a></tt>,
- <tt><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>,
- and <tt><a href="permissions-tediously-explained.html#group_component_index">group_component_index</a></tt>. Here
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#group_member_index">group_member_index</a></tt> can be trivially derived by joining
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#membership_rels">membership_rels</a></tt>,
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_rels">acs_rels</a></tt>,
+ and <tt class="computeroutput"><a href="permissions-tediously-explained.html#group_component_index">group_component_index</a></tt>. Here
is a view that does it. (This view is <span class="emphasis"><em>not</em></span> part of the OpenACS Kernel data model.)
</p><pre class="programlisting">
create or replace view group_member_view
@@ -507,8 +506,8 @@
mr.rel_id = r.rel_id
and r.object_id_one = gci.component_id;
</pre><p>
- A heuristic way to verify that <tt>group_member_view</tt> is essentially identical
- to <tt><a href="permissions-tediously-explained.html#group_member_index">group_member_index</a></tt> is to compute the
+ A heuristic way to verify that <tt class="computeroutput">group_member_view</tt> is essentially identical
+ to <tt class="computeroutput"><a href="permissions-tediously-explained.html#group_member_index">group_member_index</a></tt> is to compute the
symmetric difference between the two:
</p><pre class="programlisting">
select
@@ -531,12 +530,12 @@
</pre><p>
The query returns no rows. The important point is, if we
have a flattened view of the composition hierarchy -- like one provided
- by the <tt><a href="permissions-tediously-explained.html#group_component_index">group_component_index</a></tt> table --
+ by the <tt class="computeroutput"><a href="permissions-tediously-explained.html#group_component_index">group_component_index</a></tt> table --
membership relationship resolution can be computed trivially with no hierarchical
queries involved. There is no need to keep the view in a denormalized
table, unless doing so results in substantial performance gains.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-tedious-putting-all-together"></a>Putting It All Together</h3></div></div><p>
- Security information is queried by calling the <tt>acs_permission.permission_p</tt>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-putting-all-together"></a>Putting It All Together</h3></div></div><div></div></div><p>
+ Security information is queried by calling the <tt class="computeroutput">acs_permission.permission_p</tt>
function in OpenACS 4.x.
</p><pre class="programlisting">
create or replace package body acs_permission
@@ -563,13 +562,13 @@
end acs_permission;
</pre><p>
The function simply queries
- <tt><a href="permissions-tediously-explained.html#acs_object_party_privilege_map">acs_object_party_privilege_map</a></tt>,
+ <tt class="computeroutput"><a href="permissions-tediously-explained.html#acs_object_party_privilege_map">acs_object_party_privilege_map</a></tt>,
which is a humongous view that joins three flattened hierarchies:
the context tree, the privilege hierarchy,
the party composition (and membership) hierarchy. As such,
it contains an extremely large number of rows. About
the only kind of query you can run against it is the one
- performed by the <tt>acs_permission.permission_p</tt>
+ performed by the <tt class="computeroutput">acs_permission.permission_p</tt>
function. Anything other than that would take forever to
finish or would ultimately result in an Oracle error.
</p><p>
@@ -593,9 +592,9 @@
for rec in cur
loop
acs_permission.revoke_permission (
- object_id => rec.object_id,
- grantee_id => rec.party_id,
- privilege => 'foo_create'
+ object_id =<span class="markup">></span> rec.object_id,
+ grantee_id =<span class="markup">></span> rec.party_id,
+ privilege =<span class="markup">></span> 'foo_create'
);
end loop;
@@ -605,7 +604,7 @@
end;
/
</pre><p>
- The <tt>acs_permission.revoke_permission</tt> function merely runs a
+ The <tt class="computeroutput">acs_permission.revoke_permission</tt> function merely runs a
delete statement like so:
</p><pre class="programlisting">
delete from
@@ -615,9 +614,9 @@
and grantee_id = revoke_permission.grantee_id
and privilege = revoke_permission.privilege;
</pre><p>
- Note that in the above example, <tt>acs_permissions</tt> had only
+ Note that in the above example, <tt class="computeroutput">acs_permissions</tt> had only
one entry that needed to be deleted:
- </p><div class="table"><a name="id2906731"></a><p class="title"><b>Table�11.12.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center"><tt>object_id</tt></th><th align="center"><tt>grantee_id</tt></th><th align="center"><tt>privilege</tt></th></tr></thead><tbody><tr><td align="center">
+ </p><div class="table"><a name="id2856401"></a><p class="title"><b>Table�11.12.�</b></p><table cellspacing="0" border="1"><colgroup><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th align="center"><tt class="computeroutput">object_id</tt></th><th align="center"><tt class="computeroutput">grantee_id</tt></th><th align="center"><tt class="computeroutput">privilege</tt></th></tr></thead><tbody><tr><td align="center">
default_context
</td><td align="center">
registered_users
@@ -626,8 +625,8 @@
</td></tr></tbody></table></div><p>
The above script would never get around to deleting this entry because it had
to loop through a gazillion rows in the humongous
- <tt>acs_object_party_privilege_map</tt> view.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-tedious-appendix"></a>Appendix: Various View Definitions</h3></div></div><a name="acs_object_party_privilege_map"></a><pre class="programlisting">
+ <tt class="computeroutput">acs_object_party_privilege_map</tt> view.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-appendix"></a>Appendix: Various View Definitions</h3></div></div><div></div></div><a name="acs_object_party_privilege_map"></a><pre class="programlisting">
create or replace view <span class="bold"><b>acs_object_party_privilege_map</b></span>
as
select
@@ -690,4 +689,4 @@
container_id
from
<a href="permissions-tediously-explained.html#group_member_index">group_member_index</a>;
- </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr><tr><td width="40%" align="left">Parties in OpenACS 5.0.0d </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Object Identity</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions-tediously-explained.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr><tr><td width="40%" align="left">Parties in OpenACS 5.0.0a1 </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Object Identity</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions-tediously-explained.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/permissions.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/permissions.html 14 Oct 2003 11:02:58 -0000 1.13
@@ -1,32 +1,31 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Groups, Context, Permissions</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="templates.html" title="Using Templates in OpenACS 5.0.0d"><link rel="next" href="subsites.html" title="Writing OpenACS 5.0.0d Application Pages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions"></a>Groups, Context, Permissions</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Groups, Context, Permissions</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="templates.html" title="Using Templates in OpenACS 5.0.0a1"><link rel="next" href="subsites.html" title="Writing OpenACS 5.0.0a1 Application Pages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions"></a>Groups, Context, Permissions</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-overview"></a>Overview</h3></div></div><p>
-The OpenACS 5.0.0d Permissions system allows developers and administrators to
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-overview"></a>Overview</h3></div></div><div></div></div><p>
+The OpenACS 5.0.0a1 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
-<tt>acs_objects</tt> table can be access-controlled via a simple
+<tt class="computeroutput">acs_objects</tt> table can be access-controlled via a simple
PL/SQL or Tcl interface. The permissions system manages a data model
that then allows scripts to check permissions using another simple
API call.
</p><p>
Although this may all sound easy and wonderful, no developer or
administrator would want to <span class="emphasis"><em>explicitly</em></span> set access control
rights for <span class="emphasis"><em>every user</em></span> and <span class="emphasis"><em>every object</em></span> on a
-site. Therefore, OpenACS 5.0.0d has two auxiliary mechanisms for making this
+site. Therefore, OpenACS 5.0.0a1 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
<span class="emphasis"><em>object context</em></span>, which allows applications to group objects
together into larger security domains. The rest of this document will
talk about each of these parts, and how they fit together with the
permissions system.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-groups"></a>Groups</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-groups"></a>Groups</h3></div></div><div></div></div><p>
In OpenACS 3.x, the groups system allowed developers and administrators to
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 5.0.0d object type system,
+contained a meta-data system much like the OpenACS 5.0.0a1 object type system,
but that's not relevant right now.)
</p><p>
The 3.x groups system, while very useful, was limited in few ways. The
@@ -48,10 +47,10 @@
member of Greenpeace, its members are not necessarily members of
Greenpeace.
</p><p>
-OpenACS 5.0.0d solves both of these modeling problems by introducing a new
+OpenACS 5.0.0a1 solves both of these modeling problems by introducing a new
abstraction called a <span class="emphasis"><em>party</em></span>. Parties have a recursive
definition, and we can illustrate how it works with the following
-simplified data model. First, we define the <tt>parties</tt>
+simplified data model. First, we define the <tt class="computeroutput">parties</tt>
table, where each party has an email address and a URL for contact
information.
</p><pre class="programlisting">
@@ -79,9 +78,9 @@
)
</pre><p>
-The <tt>users</tt> table is also defined in this data model as a
-subtype of <tt>person</tt>. It contains many of the basic columns
-that the old OpenACS 3.x <tt>users</tt> table contained.
+The <tt class="computeroutput">users</tt> table is also defined in this data model as a
+subtype of <tt class="computeroutput">person</tt>. It contains many of the basic columns
+that the old OpenACS 3.x <tt class="computeroutput">users</tt> table contained.
</p><p>
Finally, we define two relations, one for group <span class="emphasis"><em>membership</em></span> and
one for group <span class="emphasis"><em>composition</em></span>. The composition relation allows us
@@ -104,7 +103,7 @@
The full details of the groups data model is beyond the scope of this
tutorial - I've just given you what you need to understand how
permissions work. For further detail, you can look at <a href="parties.html">Parties in OpenACS 4</a> or <a href="groups-design.html">OpenACS 4 Groups Design</a>.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-permissions"></a>Permissions</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-permissions"></a>Permissions</h3></div></div><div></div></div><p>
NOTE: Much more detailed information about the permissions system
and how to use it is available in the
<a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a> document.
@@ -114,18 +113,18 @@
already know what parties and objects are, but we don't know what
privileges are.
</p><p>
-In OpenACS 5.0.0d, a privilege models the right to perform some operation on
+In OpenACS 5.0.0a1, 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 5.0.0d,
+read. write or execute privileges on files and directories. In OpenACS 5.0.0a1,
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
+called "admin". Then if we grant a user this privilege she is
automatically granted all the child privileges that the privilege
-contains. The OpenACS 5.0.0d kernel data model actually defines these
+contains. The OpenACS 5.0.0a1 kernel data model actually defines these
privileges as follows:
</p><pre class="programlisting">
@@ -147,7 +146,7 @@
</pre><p>
To give a user permission to perform a particular operation on a
particular object you call
-<tt>acs_permission.grant_permission</tt> like this:
+<tt class="computeroutput">acs_permission.grant_permission</tt> like this:
</p><pre class="programlisting">
@@ -164,12 +163,12 @@
to every object individually: in many cases, we'd prefer controlling
permissions to large groups of objects in the site, all at once. We
use contexts to achieve this goal.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-object-context"></a>Object Context</h3></div></div><p>
-In OpenACS 5.0.0d, an object context is a generalization of the scoping
-mechanism introduced in OpenACS 3.x. "Scoping" and "scope" are terms best
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-object-context"></a>Object Context</h3></div></div><div></div></div><p>
+In OpenACS 5.0.0a1, 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
-<tt>address_book</tt> table:
-</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>...</th><th><tt>scope</tt></th><th><tt>user_id</tt></th><th><tt>group_id</tt></th><th>...</th></tr></thead><tbody><tr><td>...</td><td><tt>user</tt></td><td><tt>123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt>group</tt></td><td>�</td><td><tt>456</tt></td><td>...</td></tr><tr><td>...</td><td><tt>public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote></div><p>
+<tt class="computeroutput">address_book</tt> table:
+</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>...</th><th><tt class="computeroutput">scope</tt></th><th><tt class="computeroutput">user_id</tt></th><th><tt class="computeroutput">group_id</tt></th><th>...</th></tr></thead><tbody><tr><td>...</td><td><tt class="computeroutput">user</tt></td><td><tt class="computeroutput">123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt class="computeroutput">group</tt></td><td>�</td><td><tt class="computeroutput">456</tt></td><td>...</td></tr><tr><td>...</td><td><tt class="computeroutput">public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote></div><p>
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
@@ -180,26 +179,26 @@
person <span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public
(itself a group of people).
</p><p>
-In OpenACS 5.0.0d, rather than breaking the world into a limited set of scopes,
+In OpenACS 5.0.0a1, rather than breaking the world into a limited set of scopes,
every object lives in a single <span class="emphasis"><em>context</em></span>. 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
explicitly attached to it, then the system will look at the
-<tt>context_id</tt> column in <tt>acs_objects</tt> and check
+<tt class="computeroutput">context_id</tt> column in <tt class="computeroutput">acs_objects</tt> and check
the context object there for permissions. Two things control the scope
of this search: the structure of the context hierarchy itself, and the
-value of the <tt>security_inherit_p</tt> flag in each object. If
-this flag is set to <tt>'t'</tt>, then the automatic search
+value of the <tt class="computeroutput">security_inherit_p</tt> flag in each object. If
+this flag is set to <tt class="computeroutput">'t'</tt>, then the automatic search
through the context happens, otherwise it does not. You might set this
-field to <tt>'f'</tt> if you want to override the default
+field to <tt class="computeroutput">'f'</tt> if you want to override the default
permissions in a subtree of some context.
</p><p> A good example of how to use this hierarchy is in the bboard
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 5.0.0d,
+privileges whenever we create a message, which is tedious. In OpenACS 5.0.0a1,
a reasonable thing to do is to create an object representing a forum,
-and point the <tt>context_id</tt> field of a new message at the
+and point the <tt class="computeroutput">context_id</tt> field of a new message at the
forum. Then, suppose we grant every user in the system read-access to
this forum. By default, they will automatically have read-access to
the new message we just inserted, since the system automatically
@@ -213,24 +212,24 @@
hierarchy for a hypothetical site:
</p><div class="blockquote"><blockquote class="blockquote"><div><img src="images/context-hierarchy.gif"></div></blockquote></div><p>
A few things to note here. First, the top two contexts in the picture
-are "magic" in some sense because they are created by default by OpenACS
-for a specific purpose. The object <tt>default_context</tt>
+are "magic" in some sense because they are created by default by OpenACS
+for a specific purpose. The object <tt class="computeroutput">default_context</tt>
represents the root of the context hierarchy for the entire site. All
permission searches walk up the tree to this point and then stop. If
you grant permissions on this object, then by default those
permissions will hold for every object in the system, regardless of
which subsite they happen to live in. The object
-<tt>security_context_root</tt> has a slightly different role. If
+<tt class="computeroutput">security_context_root</tt> has a slightly different role. If
some object has no permissions attached to it, and its value for
-<tt>security_inherit_p</tt> is <tt>'f'</tt>, or
-<tt>context_id</tt> is null, then we use this context by default.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-example"></a>Example</h3></div></div><p>
+<tt class="computeroutput">security_inherit_p</tt> is <tt class="computeroutput">'f'</tt>, or
+<tt class="computeroutput">context_id</tt> is null, then we use this context by default.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-example"></a>Example</h3></div></div><div></div></div><p>
At this point, you should either go and download the Notes example
code from the package repository, or check it out of the ArsDigita CVS
repository and add it to your server. The package is called
-"notes". To check it out from CVS, read the <a href="http://acs40.arsdigita.com/acs40-project-central/client-build.html" target="_top">these instructions</a> on how to use anonymous checkouts and then
-checkout the module <tt>acs-packages/notes</tt>:
+"notes". To check it out from CVS, read the <a href="http://acs40.arsdigita.com/acs40-project-central/client-build.html" target="_top">these instructions</a> on how to use anonymous checkouts and then
+checkout the module <tt class="computeroutput">acs-packages/notes</tt>:
</p><pre class="programlisting">
@@ -240,7 +239,7 @@
</pre><p>
After you have downloaded the package, look at the
-<tt>index.tcl</tt> page in the <tt>www</tt> directory. You can also
+<tt class="computeroutput">index.tcl</tt> page in the <tt class="computeroutput">www</tt> directory. You can also
look at the code <a href="http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-packages/notes/www/index.tcl?rev=1.3&content-type=text/x-cvsweb-markup" target="_top">in your browser</a>. The code should look something like this:
</p><pre class="programlisting">
@@ -289,8 +288,8 @@
</pre><p>
This example shows both the Tcl and PL/SQL APIs for checking
-permissions. The Tcl proc <tt>ad_permission_p</tt> and the PL/SQL
-function <tt>acs_permission.permission_p</tt> both return a flag
+permissions. The Tcl proc <tt class="computeroutput">ad_permission_p</tt> and the PL/SQL
+function <tt class="computeroutput">acs_permission.permission_p</tt> both return a flag
indicating whether the current user has permission to perform the
given action. By default, the Tcl procedure extracts the user_id out
of the request environment, while the SQL procedure takes it as an
@@ -306,9 +305,9 @@
see notes that we are allowed to see.
</p><p>
Next, look at the <a href="http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-packages/notes/www/index.adp?rev=1.1&content-type=text/x-cvsweb-markup" target="_top">index.adp</a>. It is pretty complicated.
-The main part of this page uses a <tt>multiple</tt> template
+The main part of this page uses a <tt class="computeroutput">multiple</tt> template
tag. If you want to experiment, you can replace the main body of the
-<tt>multiple</tt> tag with this:
+<tt class="computeroutput">multiple</tt> tag with this:
</p><pre class="programlisting">
<multiple name=notes>
@@ -331,7 +330,7 @@
</pre><p>
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 <tt>if</tt> tag is something that the OpenACS 5.0.0d template system
+The <tt class="computeroutput">if</tt> tag is something that the OpenACS 5.0.0a1 template system
defines for you to support conditional presentation. The <a href="/doc/acs-templating/developer-guide.html" target="_top">templates developer guide</a> provides more information about this.
</p><p>
If you study the rest of the system, you will also notice that the
@@ -344,8 +343,8 @@
implement a user interface that allowed the user to explicitly attach
permissions to notes that she wanted to make public or whatever. But
that's beyond the scope of this example.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="permissions-summary"></a>Summary</h3></div></div><p>
-OpenACS 5.0.0d defines three separate mechanisms for specifying access control
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-summary"></a>Summary</h3></div></div><div></div></div><p>
+OpenACS 5.0.0a1 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,
@@ -355,4 +354,4 @@
</p><p>
In the next section, we'll look at a more complex page for adding and
editing notes, and discuss these issues further.
-</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr><tr><td width="40%" align="left">Using Templates in OpenACS 5.0.0d </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Writing OpenACS 5.0.0d Application Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions.html#comments">View comments on this page at openacs.org</a></center></body></html>
+</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr><tr><td width="40%" align="left">Using Templates in OpenACS 5.0.0a1 </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Writing OpenACS 5.0.0a1 Application Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/permissions.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/postgres.html 20 Aug 2003 16:20:16 -0000 1.10
+++ openacs-4/packages/acs-core-docs/www/postgres.html 14 Oct 2003 11:02:58 -0000 1.11
@@ -1,129 +1,128 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install PostGreSQL</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="oracle.html" title="Install Oracle 8.1.7"><link rel="next" href="aolserver.html" title="Install AOLserver 3.3oacs1"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="postgres"></a>Install PostGreSQL</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Install PostGreSQL</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux"><link rel="previous" href="oracle.html" title="Install Oracle 8.1.7"><link rel="next" href="aolserver.html" title="Install AOLserver 3.3oacs1"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><th width="60%" align="center">Chapter�4.�Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="postgres"></a>Install PostGreSQL</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><p>Skip this section if you will run only Oracle.</p><p>OpenACS 5.0.0d will run with PostGreSQL 7.2.x or 7.3.2. It
+ </p></div><p>Skip this section if you will run only Oracle.</p><p>OpenACS 5.0.0a1 will run with PostGreSQL 7.2.x or 7.3.2. It
has not been fully tested with 7.3.2; 7.2.4 is the recommended
version of PostgreSQL to use.</p><div class="itemizedlist"><ul type="disc"><li><p><a name="install-postgres-rpm"></a><b>Using the Red Hat RPM.�</b>Red Hat users: If you install PostGreSQL 7.3.2 from the Red Hat 9 RPM, you
can skip a few steps. These shell commands add a link so that the
data directory appears to be in the same place as in a source
install; start the service; create a new group for web service
users, and modify the postgres user's
environment (<a href="postgres.html#install-postgres-env">more
- information</a>):</p><pre class="screen">[root@yourserver root]# <b><tt>ln -s /var/lib/pgsql/data /usr/local/pgsql/data</tt></b>
-[root@yourserver root]# <b><tt>service postgresql start</tt></b>
+ information</a>):</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>ln -s /var/lib/pgsql/data /usr/local/pgsql/data</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>service postgresql start</tt></b>
Initializing database:
[ OK ]
Starting postgresql service: [ OK ]
-[root@yourserver root]# <b><tt>echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile</tt></b>
-[root@yourserver root]# <b><tt>echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile</tt></b>
-[root@yourserver root]# <b><tt>groupadd web</tt></b>
-[root@yourserver root]# <b><tt>su - postgres</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>groupadd web</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>su - postgres</tt></b>
-bash-2.05b$
-<pre class="action">
+<pre class="action"><span class="action">
ln -s /var/lib/pgsql/data /usr/local/pgsql/data
service postgresql start
-echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
-echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
+echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
+echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
groupadd web
-su - postgres</pre></pre><p>... and then skip to <a href="quick.html#install-plpgsql" title="">3</a>. Something similar may work for other binary packages as well.</p></li></ul></div><div class="orderedlist"><ol type="1"><li><p><b>Unpack PostGreSQL.�</b>If you have not downloaded the postgresql tarball to
- <tt>/tmp/postgresql-7.2.4.tar.gz</tt>,
- <a href="individual-programs.html#source-postgresql">get it</a>.</p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/postgresql-7.2.4.tar.gz</tt></b>
+su - postgres</span></pre></pre><p>... and then skip to <a href="postgres.html#install-plpgsql" title="">6</a>. Something similar may work for other binary packages as well.</p></li></ul></div><div class="orderedlist"><ol type="1"><li><p><b>Unpack PostGreSQL.�</b>If you have not downloaded the postgresql tarball to
+ <tt class="computeroutput">/tmp/postgresql-7.2.4.tar.gz</tt>,
+ <a href="individual-programs.html#source-postgresql">get it</a>.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>cd /usr/local/src</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>tar xzf /tmp/postgresql-7.2.4.tar.gz</tt></b>
[root@yourserver src]#
-<pre class="action">cd /usr/local/src
-tar xzf /tmp/postgresql-7.2.4.tar.gz</pre></pre></li><li><p><b>Create the Postgres user.�</b>
+<pre class="action"><span class="action">cd /usr/local/src
+tar xzf /tmp/postgresql-7.2.4.tar.gz</span></pre></pre></li><li><p><b>Create the Postgres user.�</b>
Create a user and group (if you haven't done so before) for
PostgreSQL. This is the account that PostgreSQL will run as
since it will not run as root. Since nobody will log in
directly as that user, we'll leave the password blank.
- </p><pre class="screen">[root@yourserver src]# <b><tt>groupadd web</tt></b>
-[root@yourserver src]# <b><tt>useradd -g web -d /usr/local/pgsql postgres</tt></b>
-[root@yourserver src]# <b><tt>mkdir -p /usr/local/pgsql</tt></b>
-[root@yourserver src]# <b><tt>chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.2.4</tt></b>
-[root@yourserver src]# <b><tt>chmod 750 /usr/local/pgsql</tt></b>
+ </p><pre class="screen">[root@yourserver src]# <b class="userinput"><tt>groupadd web</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>useradd -g web -d /usr/local/pgsql postgres</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>mkdir -p /usr/local/pgsql</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.2.4</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>chmod 750 /usr/local/pgsql</tt></b>
[root@yourserver src]#
-<pre class="action">groupadd web
+<pre class="action"><span class="action">groupadd web
useradd -g web -d /usr/local/pgsql postgres
mkdir -p /usr/local/pgsql
chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.2.4
-chmod 750 /usr/local/pgsql</pre></pre></li><li><a name="install-postgres-env"></a><p><b>Set up postgres's environment variables.�</b>They are necessary for the executable to find its supporting
+chmod 750 /usr/local/pgsql</span></pre></pre></li><li><a name="install-postgres-env"></a><p><b>Set up postgres's environment variables.�</b>They are necessary for the executable to find its supporting
libraries. For convenience, we'll simply append the necessary
- lines to the postgres shell config file.</p><pre class="screen">[root@yourserver src]# <b><tt>echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc</tt></b>
-[root@yourserver src]# <b><tt>echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc</tt></b>
-<pre class="action">echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc
-echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc</pre></pre><p>Test this by logging in as
- <tt>postgres</tt> and checking the
- paths; you should see <tt>/usr/local/pgsql/bin</tt></p><pre class="screen">[root@yourserver src]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>env | grep PATH</tt></b>
+ lines to the postgres shell config file.</p><pre class="screen">[root@yourserver src]# <b class="userinput"><tt>echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc</tt></b>
+<pre class="action"><span class="action">echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc
+echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc</span></pre></pre><p>Test this by logging in as
+ <tt class="computeroutput">postgres</tt> and checking the
+ paths; you should see <tt class="computeroutput">/usr/local/pgsql/bin</tt></p><pre class="screen">[root@yourserver src]# <b class="userinput"><tt>su - postgres</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>env | grep PATH</tt></b>
LD_LIBRARY_PATH=:/usr/local/pgsql/lib
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin
-[postgres@yourserver pgsql]$ <b><tt>exit</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>exit</tt></b>
</pre></li><li><a name="install-postgres-compile"></a><p><b>Compile and install PostgreSQL.�</b>
- Change to the postgres user and run <tt>./configure</tt> to set the compilation options automatically. This is the point at which you can
+ Change to the postgres user and run <tt class="computeroutput">./configure</tt> 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<a class="indexterm" name="id2969953"></a> support, add the flags <tt>--enable-locale</tt> and <tt>--enable-multibyte</tt>. If you want to see what the other possibilities are, run <tt>./configure --help</tt>.
- </p><pre class="screen">[root@yourserver src]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$<b><tt> cd /usr/local/src/postgresql-7.2.4</tt></b>
-[postgres@yourserver postgresql-7.2.4]$ <b><tt>./configure</tt></b>
+ Unicode<a class="indexterm" name="id2820861"></a> support, add the flags <tt class="computeroutput">--enable-locale</tt> and <tt class="computeroutput">--enable-multibyte</tt>. If you want to see what the other possibilities are, run <tt class="computeroutput">./configure --help</tt>.
+ </p><pre class="screen">[root@yourserver src]# <b class="userinput"><tt>su - postgres</tt></b>
+[postgres@yourserver pgsql]$<b class="userinput"><tt> cd /usr/local/src/postgresql-7.2.4</tt></b>
+[postgres@yourserver postgresql-7.2.4]$ <b class="userinput"><tt>./configure</tt></b>
creating cache ./config.cache
checking host system type... i686-pc-linux-gnu
(many lines omitted>
linking ./src/makefiles/Makefile.linux to src/Makefile.port
linking ./src/backend/port/tas/dummy.s to src/backend/port/tas.s
-[postgres@yourserver postgresql-7.2.4]$ <b><tt>make all</tt></b>
+[postgres@yourserver postgresql-7.2.4]$ <b class="userinput"><tt>make all</tt></b>
make -C doc all
make[1]: Entering directory `/usr/local/src/postgresql-7.2.4/doc'
(many lines omitted)
make[1]: Leaving directory `/usr/local/src/postgresql-7.2.4/src'
All of PostgreSQL successfully made. Ready to install.
-[postgres@yourserver postgresql-7.2.4]$ <b><tt>make install</tt></b>
+[postgres@yourserver postgresql-7.2.4]$ <b class="userinput"><tt>make install</tt></b>
make -C doc install
make[1]: Entering directory `/usr/local/src/postgresql-7.2.4/doc'
(many lines omitted)
Thank you for choosing PostgreSQL, the most advanced open source database
engine.
-<pre class="action">su - postgres
+<pre class="action"><span class="action">su - postgres
cd /usr/local/src/postgresql-7.2.4
./configure
make all
-make install</pre></pre></li><li><a name="install-postgres-startup"></a><p><b>Start PostgreSQL.�</b>
- The <tt>initdb</tt> command initializes the
- database. <tt>pg_ctl</tt> is used to start up
+make install</span></pre></pre></li><li><a name="install-postgres-startup"></a><p><b>Start PostgreSQL.�</b>
+ The <tt class="computeroutput">initdb</tt> command initializes the
+ database. <tt class="computeroutput">pg_ctl</tt> is used to start up
PostgreSQL.
- </p><pre class="screen">[postgres@yourserver tsearch]$ <b><tt>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</tt></b>
-The files belonging to this database system will be owned by user "postgres".
+ </p><pre class="screen">[postgres@yourserver tsearch]$ <b class="userinput"><tt>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</tt></b>
+The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.
(17 lines omitted)
or
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
-[postgres@yourserver tsearch]$ <b><tt>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start</tt></b>
+[postgres@yourserver tsearch]$ <b class="userinput"><tt>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start</tt></b>
postmaster successfully started
[postgres@yourserver tsearch]$
-<pre class="action">/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
-/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start</pre></pre><p>
+<pre class="action"><span class="action">/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start</span></pre></pre><p>
PostgreSQL errors will be logged in
- <tt>/usr/local/pgsql/data/server.log</tt>
+ <tt class="computeroutput">/usr/local/pgsql/data/server.log</tt>
</p></li><li><a name="install-plpgsql"></a><p><b>Install Pl/pgSQL.�</b>Set up plpgsq and allow your user to have
access. Plpgsql is a PL/SQL-like language. We add it to
template1, which is the template from which all new
databases are created. We can verify that it was created
- with the createlang command in list mode.</p><pre class="screen">[postgres@yourserver pgsql]$ <b><tt>createlang plpgsql template1</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>createlang -l template1</tt></b>
+ with the createlang command in list mode.</p><pre class="screen">[postgres@yourserver pgsql]$ <b class="userinput"><tt>createlang plpgsql template1</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>createlang -l template1</tt></b>
Procedural languages
Name | Trusted?
---------+----------
plpgsql | t
(1 row)
[postgres@yourserver pgsql]$
-<pre class="action">createlang plpgsql template1
-createlang -l template1</pre></pre></li><li><a name="install-postgres-test"></a><p><b>Test PostgreSQL (OPTIONAL).�</b>Create a database and try some simple commands. The output should be as shown.
- </p><pre class="screen">[postgres@yourserver pgsql]$ <b><tt>createdb mytestdb</tt></b>
+<pre class="action"><span class="action">createlang plpgsql template1
+createlang -l template1</span></pre></pre></li><li><a name="install-postgres-test"></a><p><b>Test PostgreSQL (OPTIONAL).�</b>Create a database and try some simple commands. The output should be as shown.
+ </p><pre class="screen">[postgres@yourserver pgsql]$ <b class="userinput"><tt>createdb mytestdb</tt></b>
CREATE DATABASE
-[postgres@yourserver pgsql]$ <b><tt>psql mytestdb</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>psql mytestdb</tt></b>
Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
@@ -132,24 +131,24 @@
\g or terminate with semicolon to execute query
\q to quit
-mytestdb=# <b><tt>select current_timestamp;</tt></b>
+mytestdb=# <b class="userinput"><tt>select current_timestamp;</tt></b>
timestamptz
-------------------------------
2003-03-07 22:18:29.185413-08
(1 row)
-mytestdb=# <b><tt>create function test1() returns integer as 'begin return 1; end;' language 'plpgsql';</tt></b>
+mytestdb=# <b class="userinput"><tt>create function test1() returns integer as 'begin return 1; end;' language 'plpgsql';</tt></b>
CREATE
-mytestdb=#<b><tt> select test1();</tt></b>
+mytestdb=#<b class="userinput"><tt> select test1();</tt></b>
test1
-------
1
(1 row)
-mytestdb=# <b><tt>\q</tt></b>
-[postgres@yourserver pgsql]$<b><tt> dropdb mytestdb</tt></b>
+mytestdb=# <b class="userinput"><tt>\q</tt></b>
+[postgres@yourserver pgsql]$<b class="userinput"><tt> dropdb mytestdb</tt></b>
DROP DATABASE
-[postgres@yourserver pgsql]$ <b><tt>exit</tt></b>
+[postgres@yourserver pgsql]$ <b class="userinput"><tt>exit</tt></b>
logout
[root@yourserver src]#</pre></li><li><p><a name="install-postgres-startonboot"></a>Set PostgreSQL to start on boot. First, we copy the
@@ -160,42 +159,42 @@
changes runlevels, postgresql goes to the appropriate
state. Red Hat and Debian and SuSE each work a little
differently.
- </p><div class="itemizedlist"><ul type="disc"><li><p>Red Hat RPM:</p><p>The init script is already installed; just turn it on for the appropriate run levels.</p><pre class="screen">[root@yourserver root]# <b><tt>chkconfig --level 345 postgresql on</tt></b>
-[root@yourserver root]# </pre></li><li><p>Red Hat from source:</p><pre class="screen">[root@yourserver src]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql</tt></b>
-[root@yourserver src]# <b><tt>chown root.root /etc/rc.d/init.d/postgresql</tt></b>
-[root@yourserver src]# <b><tt>chmod 755 /etc/rc.d/init.d/postgresql</tt></b>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>Red Hat RPM:</p><p>The init script is already installed; just turn it on for the appropriate run levels.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>chkconfig --level 345 postgresql on</tt></b>
+[root@yourserver root]# </pre></li><li><p>Red Hat from source:</p><pre class="screen">[root@yourserver src]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>chown root.root /etc/rc.d/init.d/postgresql</tt></b>
+[root@yourserver src]# <b class="userinput"><tt>chmod 755 /etc/rc.d/init.d/postgresql</tt></b>
[root@yourserver src]#
-<pre class="action">cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+<pre class="action"><span class="action">cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
chown root.root /etc/rc.d/init.d/postgresql
-chmod 755 /etc/rc.d/init.d/postgresql</pre></pre><p>Test the script.</p><pre class="screen">[root@yourserver root]# <b><tt>service postgresql stop</tt></b>
+chmod 755 /etc/rc.d/init.d/postgresql</span></pre></pre><p>Test the script.</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>service postgresql stop</tt></b>
Stopping PostgreSQL: ok
[root@yourserver root]# </pre><p>If PostgreSQL successfully stopped, then use the following
command to make sure that the script is run appropriately at boot
and shutdown. And turn it back on because we'll use
it later.
- </p><pre class="screen">[root@yourserver root]# <b><tt>chkconfig --add postgresql</tt></b>
-[root@yourserver root]# <b><tt>chkconfig --level 345 postgresql on</tt></b>
-[root@yourserver root]# <b><tt>chkconfig --list postgresql</tt></b>
+ </p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>chkconfig --add postgresql</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chkconfig --level 345 postgresql on</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>chkconfig --list postgresql</tt></b>
postgresql 0:off 1:off 2:on 3:on 4:on 5:on 6:off
-[root@yourserver root]# <b><tt>service postgresql start</tt></b>
+[root@yourserver root]# <b class="userinput"><tt>service postgresql start</tt></b>
Starting PostgreSQL: ok
[root@yourserver root]#
-<pre class="action">chkconfig --add postgresql
+<pre class="action"><span class="action">chkconfig --add postgresql
chkconfig --level 345 postgresql on
chkconfig --list postgresql
-service postgresql start</pre></pre></li><li><p>Debian:</p><pre class="screen">root:~# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql</tt></b>
-root:~# <b><tt>chown root.root /etc/init.d/postgresql</tt></b>
-root:~# <b><tt>chmod 755 /etc/init.d/postgresql</tt></b>
-root:~# <pre class="action">
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+service postgresql start</span></pre></pre></li><li><p>Debian:</p><pre class="screen">root:~# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql</tt></b>
+root:~# <b class="userinput"><tt>chown root.root /etc/init.d/postgresql</tt></b>
+root:~# <b class="userinput"><tt>chmod 755 /etc/init.d/postgresql</tt></b>
+root:~# <pre class="action"><span class="action">
+cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
chown root.root /etc/init.d/postgresql
-chmod 755 /etc/init.d/postgresql</pre></pre><p>Test the script</p><pre class="screen">root:~# <b><tt>/etc/init.d/postgresql stop</tt></b>
+chmod 755 /etc/init.d/postgresql</span></pre></pre><p>Test the script</p><pre class="screen">root:~# <b class="userinput"><tt>/etc/init.d/postgresql stop</tt></b>
Stopping PostgreSQL: ok
root:~# </pre><p>If PostgreSQL successfully stopped, then use the following
command to make sure that the script is run
appropriately at boot and shutdown.</p><pre class="screen">
-root:~# <b><tt>update-rc.d postgresql defaults</tt></b>
+root:~# <b class="userinput"><tt>update-rc.d postgresql defaults</tt></b>
Adding system startup for /etc/init.d/postgresql ...
/etc/rc0.d/K20postgresql -> ../init.d/postgresql
/etc/rc1.d/K20postgresql -> ../init.d/postgresql
@@ -204,50 +203,50 @@
/etc/rc3.d/S20postgresql -> ../init.d/postgresql
/etc/rc4.d/S20postgresql -> ../init.d/postgresql
/etc/rc5.d/S20postgresql -> ../init.d/postgresql
-root:~# <b><tt>/etc/init.d/postgresql start</tt></b>
+root:~# <b class="userinput"><tt>/etc/init.d/postgresql start</tt></b>
Starting PostgreSQL: ok
root:~#</pre></li><li><p>SuSE:</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
I have received reports that SuSE 8.0 is different from
previous versions. Instead of installing the boot scripts in
- <tt>/etc/rc.d/init.d/</tt>, they should
- be placed in <tt>/etc/init.d/</tt>. If
+ <tt class="computeroutput">/etc/rc.d/init.d/</tt>, they should
+ be placed in <tt class="computeroutput">/etc/init.d/</tt>. If
you're using SuSE 8.0, delete the
- <tt>rc.d/</tt> part in each of the
+ <tt class="computeroutput">rc.d/</tt> part in each of the
following commands.
- </p></div><pre class="screen">root:~# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql</tt></b>
-root:~# <b><tt>chown root.root /etc/rc.d/init.d/postgresql</tt></b>
-root:~# <b><tt>chmod 755 /etc/rc.d/init.d/postgresql</tt></b></pre><p>
+ </p></div><pre class="screen">root:~# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql</tt></b>
+root:~# <b class="userinput"><tt>chown root.root /etc/rc.d/init.d/postgresql</tt></b>
+root:~# <b class="userinput"><tt>chmod 755 /etc/rc.d/init.d/postgresql</tt></b></pre><p>
Test the script.
- </p><pre class="screen">root:~# <b><tt>/etc/rc.d/init.d/postgresql stop</tt></b>
+ </p><pre class="screen">root:~# <b class="userinput"><tt>/etc/rc.d/init.d/postgresql stop</tt></b>
Stopping PostgreSQL: ok</pre><p>
If PostgreSQL successfully stopped, then use the following
command to make sure that the script is run appropriately at boot
and shutdown.
- </p><pre class="screen">root:~# <b><tt>cd /etc/rc.d/init.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>ln -s /etc/rc.d/init.d/postgresql K20postgresql</tt></b>
-root:/etc/rc.d/init.d# <b><tt>ln -s /etc/rc.d/init.d/postgresql S20postgresql </tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp K20postgresql rc2.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp S20postgresql rc2.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp K20postgresql rc3.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp S20postgresql rc3.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp K20postgresql rc4.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp S20postgresql rc4.d </tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp K20postgresql rc5.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>cp S20postgresql rc5.d</tt></b>
-root:/etc/rc.d/init.d# <b><tt>rm K20postgresql</tt></b>
-root:/etc/rc.d/init.d# <b><tt>rm S20postgresql</tt></b>
+ </p><pre class="screen">root:~# <b class="userinput"><tt>cd /etc/rc.d/init.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>ln -s /etc/rc.d/init.d/postgresql K20postgresql</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>ln -s /etc/rc.d/init.d/postgresql S20postgresql </tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp K20postgresql rc2.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp S20postgresql rc2.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp K20postgresql rc3.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp S20postgresql rc3.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp K20postgresql rc4.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp S20postgresql rc4.d </tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp K20postgresql rc5.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>cp S20postgresql rc5.d</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>rm K20postgresql</tt></b>
+root:/etc/rc.d/init.d# <b class="userinput"><tt>rm S20postgresql</tt></b>
root:/etc/rc.d/init.d# </pre><p>
Test configuration.
- </p><pre class="screen">root:/etc/rc.d/init.d # <b><tt>cd</tt></b>
-root:~ # <b><tt>/etc/rc.d/init.d/rc2.d/S20postgresql start</tt></b>
+ </p><pre class="screen">root:/etc/rc.d/init.d # <b class="userinput"><tt>cd</tt></b>
+root:~ # <b class="userinput"><tt>/etc/rc.d/init.d/rc2.d/S20postgresql start</tt></b>
Starting PostgreSQL: ok
root:~ # </pre></li></ul></div><p>
@@ -259,11 +258,11 @@
little. This usually isn't a problem as Red Hat defaults to runlevel 3)
</p></li><li><p><b>Tune postgres. (OPTIONAL).�</b>The default values for PostGreSQL are very conservative; we can safely change some of them and improve performance.</p><div class="orderedlist"><ol type="a"><li><p>Change the kernel parameter for maximum shared memory
- segment size to 128Mb:</p><pre class="screen">[root@yourserver root]# <b><tt>echo 134217728 >/proc/sys/kernel/shmmax</tt></b>
+ segment size to 128Mb:</p><pre class="screen">[root@yourserver root]# <b class="userinput"><tt>echo 134217728 >/proc/sys/kernel/shmmax</tt></b>
[root@yourserver root]#</pre><p>Make that change permanent by editing
- <tt>emacs /etc/sysctl.conf</tt> to
+ <tt class="computeroutput">emacs /etc/sysctl.conf</tt> to
add these lines at the end:</p><pre class="programlisting"># increase shared memory limit for postgres
-kernel.shmmax = 134217728</pre></li><li><p>Edit the PostGreSQL config file, <tt>/usr/local/pgsql/data/postgresql.conf</tt>, to use more memory. These values should improve performance in most cases. (<a href="http://openacs.org/forums/message-view?message_id=94071" target="_top">more information</a>)</p><pre class="programlisting"># Shared Memory Size
+kernel.shmmax = 134217728</pre></li><li><p>Edit the PostGreSQL config file, <tt class="computeroutput">/usr/local/pgsql/data/postgresql.conf</tt>, to use more memory. These values should improve performance in most cases. (<a href="http://openacs.org/forums/message-view?message_id=94071" target="_top">more information</a>)</p><pre class="programlisting"># Shared Memory Size
#
shared_buffers = 15200 # 2*max_connections, min 16
@@ -276,7 +275,7 @@
#
wal_files = 3 # range 0-64
checkpoint_segments = 3 # in logfile segments (16MB each), min 1
-</pre><p>Restart postgres (<tt>service postgres restart</tt>) so that the changes take effect.</p></li></ol></div></li></ol></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-moreinfo"></a>more information about PostgreSQL</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+</pre><p>Restart postgres (<tt class="computeroutput">service postgres restart</tt>) so that the changes take effect.</p></li></ol></div></li></ol></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-postgres-moreinfo"></a>more information about PostgreSQL</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.postgresql.org/idocs/" target="_top">Official PostgreSQL
Docs</a>
Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,68 +1,67 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Programming with AOLserver</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="object-identity.html" title="Object Identity"><link rel="next" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Programming with AOLserver</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="object-identity.html" title="Object Identity"><link rel="next" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:michael@arsdigita.com" target="_top">Michael Yoon</a>, <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> and <a href="http://www.pinds.com/lars" target="_top">Lars Pind</a>.
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-global"></a>The <tt>global</tt> command</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-global"></a>The <tt class="computeroutput">global</tt> command</h3></div></div><div></div></div><p>
When using AOLserver, remember that there are effectively <span class="emphasis"><em>two</em></span> types
of global namespace, not one:
</p><div class="orderedlist"><ol type="1"><li><p><span class="emphasis"><em>Server</em></span>-global: As you'd expect, there is
only one server-global namespace per server, and variables set within it can
be accessed by any Tcl code running subsequently, in any of the server's
-threads. To set/get server-global variables, use AOLserver 3's <a href="http://www.aolserver.com/docs/nsv.adp" target="_top"><tt>nsv</tt> API</a>
-(which supersedes <tt>ns_share</tt> from the pre-3.0 API).
+threads. To set/get server-global variables, use AOLserver 3's <a href="http://www.aolserver.com/docs/nsv.adp" target="_top"><tt class="computeroutput">nsv</tt> API</a>
+(which supersedes <tt class="computeroutput">ns_share</tt> from the pre-3.0 API).
</p></li><li><p><span class="emphasis"><em>Script</em></span>-global: Each Tcl script (ADP, Tcl page,
registered proc, filter, etc.) executing within an AOLserver thread has its
own global namespace. Any variable set in the top level of a script is, by
definition, script-global, meaning that it is accessible only by subsequent
code in the same script and only for the duration of the current script
execution.</p></li></ol></div><p>
-The Tcl built-in command <a href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/global.htm" target="_top"><tt>global</tt></a>
+The Tcl built-in command <a href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/global.htm" target="_top"><tt class="computeroutput">global</tt></a>
accesses script-global, <span class="emphasis"><em>not</em></span> server-global, variables from within a
procedure. This distinction is important to understand in order to use
-<tt>global</tt> correctly when programming AOLserver.
+<tt class="computeroutput">global</tt> correctly when programming AOLserver.
</p><p>Also, AOLserver purges all script-global variables in a thread (i.e., Tcl
interpreter) between HTTP requests. If it didn't, that would affect (and
complicate) our use of script-global variables dramatically, which would then
be better described as <span class="emphasis"><em>thread</em></span>-global variables. Given
-AOLserver's behaviour, however, "script-global" is a more
-appropriate term.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-sched-procs"></a>Threads and Scheduled Procedures</h3></div></div><p>
-<tt>ns_schedule_proc</tt> and <tt>ad_schedule_proc</tt> each take a
-<tt>-thread</tt> flag to cause a scheduled procedure to run
+AOLserver's behaviour, however, "script-global" is a more
+appropriate term.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-sched-procs"></a>Threads and Scheduled Procedures</h3></div></div><div></div></div><p>
+<tt class="computeroutput">ns_schedule_proc</tt> and <tt class="computeroutput">ad_schedule_proc</tt> each take a
+<tt class="computeroutput">-thread</tt> flag to cause a scheduled procedure to run
asychronously, in its own thread. It almost always seems like a good idea to
specify this switch, but there's a problem.
-</p><p>It turns out that whenever a task scheduled with <tt>ns_schedule_proc
--thread</tt> or <tt>ad_schedule_proc -thread t</tt> is run, AOLserver
+</p><p>It turns out that whenever a task scheduled with <tt class="computeroutput">ns_schedule_proc
+-thread</tt> or <tt class="computeroutput">ad_schedule_proc -thread t</tt> is run, AOLserver
creates a brand new thread and a brand new interpreter, and reinitializes the
procedure table (essentially, loads all procedures that were created during
server initialization into the new interpreter). This happens <span class="emphasis"><em>every
time</em></span> the task is executed - and it is a very expensive process that
should not be taken lightly!</p><p>The moral: if you have a lightweight scheduled procedure
-which runs frequently, don't use the <tt>-thread</tt>
+which runs frequently, don't use the <tt class="computeroutput">-thread</tt>
switch.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>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 <a href="apm-design.html" title="OpenACS 5.0.0d Package Manager Design">APM</a> watch
+startup (e.g. using the <a href="apm-design.html" title="OpenACS 5.0.0a1 Package Manager Design">APM</a> watch
facility), that will not be reflected in the scheduled
-thread.</em></span></p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-return"></a>Using <tt>return</tt></h3></div></div><p>
-The <tt>return</tt> command in Tcl returns control to the caller procedure.
+thread.</em></span></p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-return"></a>Using <tt class="computeroutput">return</tt></h3></div></div><div></div></div><p>
+The <tt class="computeroutput">return</tt> command in Tcl returns control to the caller procedure.
This definition allows nested procedures to work properly. However, this
-definition also means that nested procedures cannot use <tt>return</tt> to
+definition also means that nested procedures cannot use <tt class="computeroutput">return</tt> to
end an entire thread. This situation is most common in exception conditions
that can be triggered from inside a procedure e.g., a permission denied
exception. At this point, the procedure that detects invalid permission wants
to write an error message to the user, and completely abort execution of the
-caller thread. <tt>return</tt> doesn't work, because the procedure may be
-nested several levels deep. We therefore use <a href="/api-doc/proc-view?proc=ad%5fscript%5fabort" target="_top"><tt>ad_script_abort</tt></a>
-to abort the remainder of the thread. Note that using <tt>return</tt> instead
-of <tt>ad_script_abort</tt> may raise some security issues: an attacker could
+caller thread. <tt class="computeroutput">return</tt> doesn't work, because the procedure may be
+nested several levels deep. We therefore use <a href="/api-doc/proc-view?proc=ad%5fscript%5fabort" target="_top"><tt class="computeroutput">ad_script_abort</tt></a>
+to abort the remainder of the thread. Note that using <tt class="computeroutput">return</tt> instead
+of <tt class="computeroutput">ad_script_abort</tt> may raise some security issues: an attacker could
call a page that performed some DML statement, pass in some arguments, and
get a permission denied error -- but the DML statement would still be
-executed because the thread was not stopped. Note that <tt>return -code
+executed because the thread was not stopped. Note that <tt class="computeroutput">return -code
return</tt> can be used in circumstances where the procedure will only be
called from two levels deep.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-more-values"></a>Returning More Than One Value From a Function</h3></div></div><p>
-Many functions have a single return value. For instance, <a href="/api-doc/proc-view?proc=empty%5fstring%5fp" target="_top"><tt>empty_string_p</tt></a>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-more-values"></a>Returning More Than One Value From a Function</h3></div></div><div></div></div><p>
+Many functions have a single return value. For instance, <a href="/api-doc/proc-view?proc=empty%5fstring%5fp" target="_top"><tt class="computeroutput">empty_string_p</tt></a>
returns a number: 1 or 0. Other functions need to return a composite value.
For instance, consider a function that looks up a user's name and email
address, given an ID. One way to implement this is to return a three-element
@@ -77,33 +76,33 @@
</pre><p>AOLserver/Tcl generally has three mechanisms that we like, for returning
more than one value from a function. When to use which depends on the
circumstances.</p><p>Using Arrays and Pass-By-Value</p><p>
-The one we generally prefer is returning an <a href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/array.htm#M8" target="_top"><tt>array
+The one we generally prefer is returning an <a href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/array.htm#M8" target="_top"><tt class="computeroutput">array
get</tt></a>-formatted list. It has all the nice properties of
pass-by-value, and it uses Tcl arrays, which have good native support.
</p><pre class="programlisting">
ad_proc ad_get_user_info { user_id } {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
return [list \
- name "$first_names $last_name" \
+ name "$first_names $last_name" \
email $email \
- namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" \
- emaillink "<a href=\"mailto:$email\">$email</a>"]
+ namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" \
+ emaillink "<a href=\"mailto:$email\">$email</a>"]
}
array set user_info [ad_get_user_info $user_id]
-doc_body_append "$user_info(namelink) ($user_info(emaillink))"
+doc_body_append "$user_info(namelink) ($user_info(emaillink))"
</pre><p>
You could also have done this by using an array internally and using
-<tt>array get</tt>:
+<tt class="computeroutput">array get</tt>:
</p><pre class="programlisting">
ad_proc ad_get_user_info { user_id } {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
- set user_info(name) "$first_names $last_name"
+ set user_info(name) "$first_names $last_name"
set user_info(email) $email
- set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
- set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
+ set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
+ set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
return [array get user_info]
}
@@ -119,7 +118,7 @@
milisecond. The time depends almost completely on the number of entries, and
almost not at all on the size of the entries.</em></span></p></blockquote></div><p>
You implement pass-by-reference in Tcl by taking the name of an array
-as an argument and <tt>upvar</tt> it.
+as an argument and <tt class="computeroutput">upvar</tt> it.
</p><pre class="programlisting">
ad_proc ad_get_user_info {
@@ -128,30 +127,30 @@
} {
upvar $array user_info
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
- set user_info(name) "$first_names $last_name"
+ set user_info(name) "$first_names $last_name"
set user_info(email) $email
- set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
- set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
+ set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
+ set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
}
ad_get_user_info -array user_info $user_id
-doc_body_append "$user_info(namelink) ($user_info(emaillink))"
+doc_body_append "$user_info(namelink) ($user_info(emaillink))"
</pre><p>We prefer pass-by-value over pass-by-reference. Pass-by-reference makes
the code harder to read and debug, because changing a value in one place has
side effects in other places. Especially if have a chain of
-<tt>upvar</tt>s through several layers of the call stack, you'll have
-a hard time debugging.</p><p>Multisets: Using <tt>ns_set</tt>s and Pass-By-Reference</p><p>
+<tt class="computeroutput">upvar</tt>s through several layers of the call stack, you'll have
+a hard time debugging.</p><p>Multisets: Using <tt class="computeroutput">ns_set</tt>s and Pass-By-Reference</p><p>
An array is a type of <span class="emphasis"><em>set</em></span>, which means you can't have multiple
entries with the same key. Data structures that can have multiple entries for
the same key are known as a <span class="emphasis"><em>multiset</em></span> or <span class="emphasis"><em>bag</em></span>.
</p><p>If your data can have multiple entries with the same key,
-you should use the AOLserver built-in <a href="http://www.aolserver.com/docs/tcldev/tapi-120.htm#197598" target="_top"><tt>
+you should use the AOLserver built-in <a href="http://www.aolserver.com/docs/tcldev/tapi-120.htm#197598" target="_top"><tt class="computeroutput">
ns_set</tt></a>. You can also do a case-insensitive lookup on an
-<tt>ns_set</tt>, something you can't easily do on an array. This is
+<tt class="computeroutput">ns_set</tt>, something you can't easily do on an array. This is
especially useful for things like HTTP headers, which happen to have these
-exact properties.</p><p>You always use pass-by-reference with <tt>ns_set</tt>s, since they
+exact properties.</p><p>You always use pass-by-reference with <tt class="computeroutput">ns_set</tt>s, since they
don't have any built-in way of generating and reconstructing themselves
from a string representation. Instead, you pass the handle to the set.</p><pre class="programlisting">
@@ -160,34 +159,34 @@
user_id
} {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
- ns_set put $set name "$first_names $last_name"
+ ns_set put $set name "$first_names $last_name"
ns_set put $set email $email
- ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
- ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>"
+ ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
+ ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>"
}
set user_info [ns_set create]
ad_get_user_info -set $user_info $user_id
-doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
+doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
</pre><p>
-We don't recommend <tt>ns_set</tt> as a general mechanism for passing
+We don't recommend <tt class="computeroutput">ns_set</tt> as a general mechanism for passing
sets (as opposed to multisets) of data. Not only do they inherently use
pass-by-reference, which we dis-like, they're also somewhat clumsy to
use, since Tcl doesn't have built-in syntactic support for them.
-</p><p>Consider for example a loop over the entries in a <tt>ns_set</tt> as
+</p><p>Consider for example a loop over the entries in a <tt class="computeroutput">ns_set</tt> as
compared to an array:</p><pre class="programlisting">
# ns_set variant
set size [ns_set size $myset]
for { set i 0 } { $i < $size } { incr i } {
- puts "[ns_set key $myset $i] = [ns_set value $myset $i]"
+ puts "[ns_set key $myset $i] = [ns_set value $myset $i]"
}
# array variant
foreach name [array names myarray] {
- puts "$myarray($name) = $myarray($name)"
+ puts "$myarray($name) = $myarray($name)"
}
</pre><p>
@@ -207,9 +206,9 @@
]
</pre><p>
-<tt>ns_set</tt>s are designed to be lightweight, so memory consumption
-should not be a problem. However, when using <tt>ns_set get</tt> to
+<tt class="computeroutput">ns_set</tt>s are designed to be lightweight, so memory consumption
+should not be a problem. However, when using <tt class="computeroutput">ns_set get</tt> to
perform lookup by name, they perform a linear lookup, whereas arrays use a
-hash table, so <tt>ns_set</tt>s are slower than arrays when the number of
+hash table, so <tt class="computeroutput">ns_set</tt>s are slower than arrays when the number of
entries is large.
</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr><tr><td width="40%" align="left">Object Identity </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Chapter�12.�Engineering Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/programming-with-aolserver.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 20 Aug 2003 16:20:16 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 14 Oct 2003 11:02:59 -0000 1.4
@@ -1,9 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Add PSGML commands to emacs init file (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"><link rel="next" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="psgml-for-emacs"></a>Add PSGML commands to emacs init file (OPTIONAL)</h2></div></div><p><a class="indexterm" name="id2992045"></a>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Add PSGML commands to emacs init file (OPTIONAL)</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="install-more-software.html" title="Appendix�B.�Install additional supporting software"><link rel="previous" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"><link rel="next" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><th width="60%" align="center">Appendix�B.�Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-for-emacs"></a>Add PSGML commands to emacs init file (OPTIONAL)</h2></div></div><div></div></div><p><a class="indexterm" name="id2838965"></a>
If you plan to write or edit any documentation with emacs, install a
customized emacs configuration file with DocBook commands in the skeleton
directory, so it will be used for all new users. The file also
fixes the backspace -> help mis-mapping that often occurs in
- terminals.</p><pre class="screen">[root@yourserver tmp]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs</tt></b>
-cp: overwrite `/etc/skel/.emacs'? <b><tt>y</tt></b>
+ terminals.</p><pre class="screen">[root@yourserver tmp]# <b class="userinput"><tt>cp /tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs</tt></b>
+cp: overwrite `/etc/skel/.emacs'? <b class="userinput"><tt>y</tt></b>
[root@yourserver tmp]# </pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr><tr><td width="40%" align="left">Initialize CVS (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Daemontools (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/psgml-for-emacs.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/psgml-mode.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,54 +1,53 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using PSGML mode in Emacs</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="next" href="filename.html" title="Detailed Design Documentation Template"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using PSGML mode in Emacs</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="next" href="filename.html" title="Detailed Design Documentation Template"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div><div></div></div><div class="authorblurb"><p>
By <a href="mailto:lutter@arsdigita.com" target="_top">David Lutterkort</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-whatisit"></a>What it is</h3></div></div><p>PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-whatisit"></a>What it is</h3></div></div><div></div></div><p>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. <span class="emphasis"><em>If</em></span> you give it the right DTD, that is. But even without a DTD,
-it can save you some typing since pressing <tt>C-c/</tt> will close an open
-tag automatically.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-getit"></a>Where to get it</h3></div></div><p>Most newer emacsen come with PSGML mode preinstalled. You can find out
-whether your emacs has it with the <tt>locate-library</tt> command. In Emacs,
-type <tt>M-x locate-library</tt> and enter <tt>psgml</tt>. Emacs will tell
+it can save you some typing since pressing <tt class="computeroutput">C-c/</tt> will close an open
+tag automatically.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-getit"></a>Where to get it</h3></div></div><div></div></div><p>Most newer emacsen come with PSGML mode preinstalled. You can find out
+whether your emacs has it with the <tt class="computeroutput">locate-library</tt> command. In Emacs,
+type <tt class="computeroutput">M-x locate-library</tt> and enter <tt class="computeroutput">psgml</tt>. Emacs will tell
you if it found it or not.</p><p>If you don't have PSGML preinstalled in your Emacs, there are two
things you can do:</p><div class="orderedlist"><ol type="1"><li><p>On Linux: Get the <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm" target="_top">
psgml rpm</a> from <a href="http://sources.redhat.com/docbook-tools/" target="_top">RedHat's
docbook-tools</a> and install it as usual.</p></li><li><p>On other systems: Get the tarball from the <a href="http://www.lysator.liu.se/~lenst/about_psgml/" target="_top">PSGML Website.</a>
-Unpack it and follow the install instructions.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-catalogs"></a>Using <tt>CATALOG</tt> files</h3></div></div><p>The easiest way to teach PSGML mode about a DTD is by adding it to your
-own <tt>CATALOG</tt>. Here is an example of how you can set that up for the
+Unpack it and follow the install instructions.</p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-catalogs"></a>Using <tt class="computeroutput">CATALOG</tt> files</h3></div></div><div></div></div><p>The easiest way to teach PSGML mode about a DTD is by adding it to your
+own <tt class="computeroutput">CATALOG</tt>. Here is an example of how you can set that up for the
Docbook XML DTD.</p><div class="orderedlist"><ol type="1"><li><p>Get the <a href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a>
zip archive from <a href="http://docbook.org/" target="_top">docbook.org</a></p></li><li><p>Go somewhere in your working directory and do </p><pre class="programlisting">
mkdir -p dtd/docbook-xml
cd dtd/docbook-xml
unzip -a <docbook XML DTD zip archive>
-</pre></li><li><p>Create a file with the name <tt>CATALOG</tt> in the <tt>dtd</tt>
+</pre></li><li><p>Create a file with the name <tt class="computeroutput">CATALOG</tt> in the <tt class="computeroutput">dtd</tt>
directory and put the line </p><pre class="programlisting">
- CATALOG "docbook-xml/docbook.cat"
+ CATALOG "docbook-xml/docbook.cat"
</pre><p>
-in it. By maintaining your own <tt>CATALOG</tt>, it is easy to add more
+in it. By maintaining your own <tt class="computeroutput">CATALOG</tt>, it is easy to add more
DTD's without changing your emacs settings. (<span class="emphasis"><em>How about that HTML 4.01 DTD you
always wanted to get from <a href="http://www.w3.org/TR/html4/" target="_top">W3C</a> ? The
DTD is in the zip archives and tarballs available on the site.</em></span></p></li></ol></div><p>That's it. Now you are ready to tell emacs all about PSGML mode and
-that funky <tt>CATALOG</tt></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div><p>If you installed PSGML mode in a non-standard location, e.g., somewhere in
-your home directory, you need to add this to the <tt>load-path</tt> by adding
-this line to your <tt>.emacs</tt> file:</p><pre class="programlisting">
- (add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
+that funky <tt class="computeroutput">CATALOG</tt></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div><div></div></div><p>If you installed PSGML mode in a non-standard location, e.g., somewhere in
+your home directory, you need to add this to the <tt class="computeroutput">load-path</tt> by adding
+this line to your <tt class="computeroutput">.emacs</tt> file:</p><pre class="programlisting">
+ (add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
-</pre><p>To let PSGML mode find your <tt>CATALOG</tt> and to enable PSGML mode for
-all your editing, add these lines to your <tt>.emacs</tt>:</p><pre class="programlisting">
+</pre><p>To let PSGML mode find your <tt class="computeroutput">CATALOG</tt> and to enable PSGML mode for
+all your editing, add these lines to your <tt class="computeroutput">.emacs</tt>:</p><pre class="programlisting">
(require 'psgml)
- (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode))
- (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode))
- (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode))
- (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode))
+ (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode))
+ (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode))
+ (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode))
+ (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode))
- (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
+ (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
</pre><p>If you want font-locking and indentation, you can also add these lines
-into the <tt>.emacs</tt> file:</p><pre class="programlisting">
+into the <tt class="computeroutput">.emacs</tt> file:</p><pre class="programlisting">
(setq sgml-markup-faces '((start-tag . font-lock-function-name-face)
(end-tag . font-lock-function-name-face)
(comment . font-lock-comment-face)
@@ -60,28 +59,28 @@
(setq sgml-set-face t)
(setq-default sgml-indent-data t)
;; Some convenient key definitions:
- (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type)
- (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info)
- (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity))))
+ (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type)
+ (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info)
+ (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity))))
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-doctype"></a>What is a <tt>DOCTYPE</tt> ?</h3></div></div><p>All SGML and XML documents that should conform to a DTD have to declare a
-doctype. For the docbook XML, all your <tt>.xml</tt> files whould start with
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-doctype"></a>What is a <tt class="computeroutput">DOCTYPE</tt> ?</h3></div></div><div></div></div><p>All SGML and XML documents that should conform to a DTD have to declare a
+doctype. For the docbook XML, all your <tt class="computeroutput">.xml</tt> files whould start with
the line</p><pre class="programlisting">
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd">
+ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd">
</pre><p>If your document is only part of a larger XML document, you can tell PSGML
mode about it by <span class="emphasis"><em>appending</em></span> the following lines to your file. In this
case, do <span class="emphasis"><em>not</em></span> include a DOCTYPE declaration in your file.</p><pre class="programlisting">
<!--
Local Variables:
- sgml-parent-document: ("top.xml" "book" "sect1")
+ sgml-parent-document: ("top.xml" "book" "sect1")
End:
-->
</pre><p>Which says that the parent of this document can be found in the file
-<tt>top.xml</tt>, that the element in the parent that will enclose the
-current document is a <tt>book</tt> and that the current file's topmost
-element is a <tt>sect1</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-usage"></a>How to use it</h3></div></div><p>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:</p><div class="informaltable"><table cellspacing="0" border="0"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Command</th></tr></thead><tbody><tr><td><tt>C-c C-e</tt></td><td>Insert an element. Uses completion and only lets you insert elements that
-are valid</td></tr><tr><td><tt>C-c C-a</tt></td><td>Edit attributes of enclosing element.</td></tr><tr><td><tt>C-c C-x C-i</tt></td><td>Show information about the document's DTD.</td></tr><tr><td><tt>C-c C-x C-e</tt></td><td>Describe element. Shows for one element which elements can be parents,
-what its contents can be and lists its attributes.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-reading"></a>Further reading</h3></div></div><p>Start with the <a href="docbook-primer.html">OpenACS Documentation Guide</a></p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation Guide </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Detailed Design Documentation Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/psgml-mode.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<tt class="computeroutput">top.xml</tt>, that the element in the parent that will enclose the
+current document is a <tt class="computeroutput">book</tt> and that the current file's topmost
+element is a <tt class="computeroutput">sect1</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-usage"></a>How to use it</h3></div></div><div></div></div><p>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:</p><div class="informaltable"><table cellspacing="0" border="0"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Command</th></tr></thead><tbody><tr><td><tt class="computeroutput">C-c C-e</tt></td><td>Insert an element. Uses completion and only lets you insert elements that
+are valid</td></tr><tr><td><tt class="computeroutput">C-c C-a</tt></td><td>Edit attributes of enclosing element.</td></tr><tr><td><tt class="computeroutput">C-c C-x C-i</tt></td><td>Show information about the document's DTD.</td></tr><tr><td><tt class="computeroutput">C-c C-x C-e</tt></td><td>Describe element. Shows for one element which elements can be parents,
+what its contents can be and lists its attributes.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-reading"></a>Further reading</h3></div></div><div></div></div><p>Start with the <a href="docbook-primer.html">OpenACS Documentation Guide</a></p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation Guide </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Detailed Design Documentation Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/psgml-mode.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/quick.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/quick.html,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/quick.html 20 Aug 2003 16:20:16 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/quick.html 14 Oct 2003 11:02:59 -0000 1.3
@@ -1,231 +1,13 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�2.�Quick Install</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="next" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="software-versions.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="quick"></a>Chapter�2.�Quick Install</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�2.�Quick Install</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="next" href="software-versions.html" title="Chapter�3.�Prerequisite Software"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="software-versions.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="quick"></a>Chapter�2.�Quick Install</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:docs@openacs.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="install-purpose"></a>Purpose of this document</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="install-purpose"></a>Purpose of this document</h3></div></div><div></div></div><p>
This page describes a minimal installation of OpenACS with
PostGreSQL (not Oracle). It will produce a working OpenACS
installation in under an hour. It excludes source control,
full text search, ssl, managed services (daemontools),
DocBook, and qmail.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2952161"></a>For Red Hat 9</h3></div></div><div class="orderedlist"><ol type="1"><li><p>Install PostGreSQL 7.3.2 from RPM. Select
- <tt>Menu > System Settings > Add/Remove
- Applications</tt> and select <tt>Database Server</tt>.</p></li><li><p><a name="install-postgres-rpm"></a><b>Using the Red Hat RPM.�</b>Red Hat users: If you install PostGreSQL 7.3.2 from the Red Hat 9 RPM, you
- can skip a few steps. These shell commands add a link so that the
- data directory appears to be in the same place as in a source
- install; start the service; create a new group for web service
- users, and modify the postgres user's
- environment (<a href="postgres.html#install-postgres-env">more
- information</a>):</p></li><li><a name="install-plpgsql"></a><p><b>Install Pl/pgSQL.�</b>Set up plpgsq and allow your user to have
- access. Plpgsql is a PL/SQL-like language. We add it to
- template1, which is the template from which all new
- databases are created. We can verify that it was created
- with the createlang command in list mode.</p><pre class="screen">[postgres@yourserver pgsql]$ <b><tt>createlang plpgsql template1</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>createlang -l template1</tt></b>
-Procedural languages
- Name | Trusted?
----------+----------
- plpgsql | t
-(1 row)
-
-[postgres@yourserver pgsql]$
-<pre class="action">createlang plpgsql template1
-createlang -l template1</pre></pre></li><li><a name="aolserver-tarball"></a><p><b>Unpack the Aolserver tarball.�</b>Download the <a href="individual-programs.html#source-aolserver">aolserver tarball</a> to <tt>/tmp/aolserver3.3oacs1.tar.gz</tt>. As <tt>root</tt>, untar
- <tt>aolserver3.3oacs1.tar.gz</tt>
- into <tt>/usr/local/src</tt>.
- </p><pre class="screen">[root@yourserver root]# <b><tt>cd /usr/local/src</tt></b>
-[root@yourserver src]# <b><tt>tar xzf /tmp/aolserver3.3oacs1.tar.gz</tt></b>
-[root@yourserver src]#
-<pre class="action">cd /usr/local/src
-tar xzf /tmp/aolserver3.3oacs1.tar.gz</pre></pre></li><li><a name="install-aolserver-compile"></a><p><b>Compile AOLserver.�</b>Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.</p><pre class="screen">root@yourserver root]# <b><tt>mkdir -p /usr/local/aolserver</tt></b>
-[root@yourserver root]# <b><tt>cd /usr/local/src/aolserver</tt></b>
-[root@yourserver aolserver]# <b><tt>./conf-clean</tt></b>
-cat: BUILD-MODULES: No such file or directory
-Done.
-[root@yourserver aolserver]#<pre class="action">mkdir -p /usr/local/aolserver
-cd /usr/local/src/aolserver
-./conf-clean</pre></pre><p>
- If you are using Oracle, edit
- <tt>conf-db</tt> and change
- <tt>postgresql</tt> to
- <tt>oracle</tt>, or to the word
- <tt>both</tt> if you want both drivers
- installed. In order to get nsoracle to compile, you may
- need to su - oracle, and then su (without the -) root to set
- the environment variables properly.
- </p><p><tt>conf-inst</tt> should contain the
- location where AOLserver is to be installed. Overwrite the
- tarball's default value with our default value, <tt>/usr/local/aolserver</tt>:</p><pre class="screen">[root@yourserver aolserver]# <b><tt>echo "/usr/local/aolserver" > conf-inst</tt></b>
-[root@yourserver aolserver]#</pre><p><tt>conf-make</tt> should contain the
- name of the GNU Make command on your system. It defaults to
- <tt>gmake</tt>.</p><p>Set an environment variable that the nspostgres driver
- Makefile needs to compile correctly and run
- <tt>conf</tt>, which compiles
- AOLserver, the default modules, and the database driver, and
- installs them.</p><p>(Debian Users working with AOLserver 3.3+ad13 and
- postgresql from apt-get may need to
- make these symlinks: <tt>ln -s
- /usr/include/postgresql/ /usr/include/pgsql</tt>
- and <tt>ln -s /usr/lib/postgresql /usr/local/pgsql</tt>)</p><pre class="screen">[root@yourserver aolserver]# <b><tt>export POSTGRES=/usr/local/pgsql; ./conf</tt></b>
-Building in /usr/local/aolserver
-with the following modules:
-aolserver
-nscache
-nsrewrite
-nssha1
-nsxml
-pgdriver
-==================================================================
-Starting Build Sat Mar 8 10:28:26 PST 2003
-Running gmake in aolserver/; output in log/aolserver.log
-<span class="emphasis"><em>(several minute delay here)</em></span>
-Running gmake in nscache/; output in log/nscache.log
-Running gmake in nsrewrite/; output in log/nsrewrite.log
-Running gmake in nssha1/; output in log/nssha1.log
-Running gmake in nsxml/; output in log/nsxml.log
-Running gmake in nspostgres/; output in log/nspostgres.log
-Creating ...
-==================================================================
-Done Building Sat Mar 8 10:31:35 PST 2003
-[root@yourserver aolserver]# </pre><p>
- This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in <tt>/usr/local/src/aolserver/log</tt>. If you run into problems running AOLserver, check these files for build errors.</p></li><li><a name="aolserver-db-wrapper"></a><p><b>Add a database-specific wrapper script.�</b>This script
- sets database environment variables before starting
- AOLserver; this allows the AOLserver instance can
- communicate with the database. There is one script each for
- Oracle and PostGreSQL. They don't conflict, so if you plan
- to use both databases, install both.</p><div class="itemizedlist"><ul type="disc"><li><p>Oracle</p><pre class="screen">[root@yourserver aolserver]# <b><tt>cd /usr/local/aolserver/bin</tt></b>
-[root@yourserver bin]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</tt></b>
-[root@yourserver bin]# <b><tt>chmod 750 nsd-oracle</tt></b>
-[root@yourserver bin]#
-<pre class="action">cd /usr/local/aolserver/bin
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
-chmod 750 nsd-oracle</pre></pre></li><li><p>PostGreSQL</p><pre class="screen">[root@yourserver aolserver]# <b><tt>cd /usr/local/aolserver/bin</tt></b>
-[root@yourserver bin]# <b><tt>cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</tt></b>
-[root@yourserver bin]# <b><tt>chmod 755 nsd-postgres</tt></b>
-[root@yourserver bin]#
-<pre class="action">cd /usr/local/aolserver/bin
-cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
-chmod 755 nsd-postgres</pre></pre></li></ul></div></li><li><p><a name="make-web-directory"></a>The reference install stores all OpenACS services in
- <tt>/web</tt>, with one subdirectory per
- service. The first time you install a service, you must create
- that directory and set its permissions:</p><pre class="screen">[root@yourserver root]# <b><tt>mkdir /web</tt></b>
-[root@yourserver root]# <b><tt>chgrp web /web</tt></b>
-[root@yourserver root]# <b><tt>chmod 770 /web</tt></b>
-[root@yourserver root]#
-<pre class="action">mkdir /web
-chgrp web /web
-chmod 770 /web</pre></pre></li><li><p><a name="install-openacs-download"></a>You should already have downloaded the OpenACS tarball
- to the <tt>/tmp</tt> directory. If
- not, <a href="individual-programs.html#openacs-download">download the OpenACS
- tarball</a> and save it in
- <tt>/tmp</tt> and proceed:</p></li><li><p><a name="install-aolserver-user-accounts"></a>Set up your user account.</p><p>
- AOLserver needs to be started as the root user if you want to use
- port 80. Once it starts, though, it will drop the root privileges and
- run as another user, which you must specify on the command line. It's
- important that this user has as few privileges as possible. Why?
- Because if an intruder somehow breaks in through AOLserver, you don't
- want her to have any ability to do damage to the rest of your
- server.</p><p>At the same time, AOLserver needs to have write access to
- some files on your system in order for OpenACS to function
- properly. So, we'll run AOLserver with a different user account
- for each different service. A service name should be a single
- word, <span class="emphasis"><em>letters and numbers only</em></span>. If the name
- of your site is one word, that would be a good choice. For
- example "<span class="replaceable">service0</span>" might be the service name for the
- <a href="http://service0.net/" target="_top"><span class="replaceable">service0</span>.net</a>
- community.</p><p>For the 5.0.0d-P and 5.0.0d-O Reference Platform,
- we'll use a server named <span class="replaceable">service0</span> and
- a user named <span class="replaceable">service0</span>. We'll leave the password
- blank for increased security. The only way to log in will be
- with ssh certificates. The only people who should log in are
- developers for that specific instance. Add this user, and put
- it in the <tt>web</tt> group so that it
- can use database commands associated with that group.
- </p><pre class="screen">[root@yourserver root]# <b><tt>useradd -g web <span class="replaceable">service0</span> -d /home/<span class="replaceable">service0</span></tt></b>
-[root@yourserver root]#</pre><p>Set up database environment variables. They are
- necessary for working with the database.
-</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>emacs .bashrc</tt></b></pre><p>Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.</p><div class="itemizedlist"><ul type="disc"><li><p>PostGreSQL:</p><pre class="programlisting">export LD_LIBRARY_PATH=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
-export PATH=$PATH:/usr/local/pgsql/bin</pre></li><li><p>Oracle. These environment variables are specific for a local Oracle
- installation communicating via IPC. If you are connecting to a remote
- Oracle installation, you'll need to adjust these appropriately. Also,
- make sure that the '8.1.7' matches your Oracle version.
-</p><pre class="programlisting">export ORACLE_BASE=/ora8/m01/app/oracle
-export ORACLE_HOME=$ORACLE_BASE/product/<span class="replaceable">8.1.7</span>
-export PATH=$PATH:$ORACLE_HOME/bin
-export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
-export ORACLE_SID=ora8
-export ORACLE_TERM=vt100
-export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre></li></ul></div><p>Test this by logging out and back in as
- <tt><span class="replaceable">service0</span></tt> and checking the paths.</p><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
-logout
-[root@yourserver src]# <b><tt>su - <b><tt><span class="replaceable">service0</span></tt></b></tt></b>
-[postgres@yourserver pgsql]$ <b><tt>env | grep PATH</tt></b>
-</pre><p>For PostGreSQL, you should see:</p><pre class="screen">
-LD_LIBRARY_PATH=LD_LIBRARY_PATH=:/usr/local/pgsql/lib
-PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin</pre><p>For Oracle:</p><pre class="screen">ORACLE_BASE=/ora8/m01/app/oracle
-ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
-PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/ora8/m01/app/oracle/product/8.1.7/bin
-LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib
-ORACLE_SID=ora8
-ORACLE_TERM=vt100
-ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
-logout
-
-[root@yourserver root]#</pre></li><li><p><a name="unpack-openacs"></a>Unpack the OpenACS tarball and rename it to <tt>service0</tt>. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>cd /web</tt></b>
-[service0@yourserver web]$ <b><tt>tar xzf /tmp/openacs-5.0.0d.tgz</tt></b>
-[service0@yourserver web]$ <b><tt>mv openacs-5.0.0d <span class="replaceable">service0</span></tt></b>
-[service0@yourserver web]$ <b><tt>chmod -R 700 <span class="replaceable">service0</span></tt></b>
-[service0@yourserver web]$ <b><tt>ls -al</tt></b>
-total 3
-drwxrwx--- 3 root web 1024 Mar 29 16:41 .
-drwxr-xr-x 25 root root 1024 Mar 29 16:24 ..
-drwx------ 7 service0 web 1024 Jan 6 14:36 service0
-[service0@yourserver web]$ <b><tt>exit</tt></b>
-logout
-
-[root@yourserver root]#
-<pre class="action">su - service0
-cd /web
-tar xzf /tmp/openacs-5.0.0d.tgz
-mv openacs-5.0.0d service0
-chmod -R 700 service0/
-exit</pre></pre></li><li><p><a name="create-service-db-user"></a>Create a user in the database matching the service name.</p><pre class="screen">[root@yourserver root]# <b><tt>su - postgres</tt></b>
-[postgres@yourserver pgsql]$ <b><tt>createuser <span class="replaceable">service0</span></tt></b>
-Shall the new user be allowed to create databases? (y/n) <b><tt>y</tt></b>
-Shall the new user be allowed to create more new users? (y/n) <b><tt>y</tt></b>
-CREATE USER
-[postgres@yourserver pgsql]$ <b><tt>exit</tt></b>
-logout
-
-[root@yourserver root]#</pre></li><li><p><a name="create-database"></a>Create a database with the same name as our service name, <span class="replaceable">service0</span>.</p><pre class="screen">[root@yourserver root]# <b><tt>su - <span class="replaceable">service0</span></tt></b>
-[service0@yourserver service0]$ <b><tt>createdb -E UNICODE <span class="replaceable">service0</span></tt></b>
-CREATE DATABASE
-[service0@yourserver service0]$
-<pre class="action">su - <span class="replaceable">service0</span>
-createdb -E UNICODE <span class="replaceable">service0</span></pre></pre></li><li><a name="db-setup-exit"></a><pre class="screen">[service0@yourserver service0]$ <b><tt>exit</tt></b>
-logout
-
-[root@yourserver root]# </pre></li><li><p><a name="start-aolserver"></a>
- Kill any current running AOLserver processes and start a new
- one. If you are using Oracle, rather than PostgreSQL, replace
- <tt>nsd-postgres</tt> with
- <tt>nsd-oracle</tt>).</p><p>If you want to use port 80, there are complications.
- First, Aolserver must be root to use system ports such as
- 80, but refuses to run as root for security reasons. Thus
- you must start as root and specify a non-root user ID and
- Group ID which Aolserver will switch to after claiming the
- port. To do so, find the UID and GID of the
- <span class="replaceable">service0</span> user via
- <tt>grep <span class="replaceable">service0</span>
- /etc/passwd</tt> and then put those numbers into
- the command line via <tt>-u
- <span class="replaceable">501</span> -g
- <span class="replaceable">502</span></tt>. Second, if you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do <tt>ps -auxw | grep
- nsd</tt> and selectively kill by job number.</p><pre class="screen">[service0@yourserver etc]$ <b><tt>killall nsd</tt></b>
-nsd: no process killed
-[service0@yourserver service0]$<b><tt> /usr/local/aolserver/bin/nsd-postgres -t /web/<span class="replaceable">service0</span>/etc/config.tcl</tt></b>
-[service0@yourserver service0]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file...
-[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.</pre></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"></div><p>After completing installation and restarting the server, go to <a href="http://localhost:8000" target="_top">http://localhost:8000</a> for configuration and customization instructions. You can upgrade a Quick Install with source control, full text search, backup/recovery, and other production features by walking through the <a href="unix-install" target="_top">Installation documentation</a> and doing the steps marked OPTIONAL.</p></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="software-versions.html">Next</a></td></tr><tr><td width="40%" align="left">Part�II.�Administrator's Guide </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Chapter�3.�Prerequisite Software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/quick.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2822087"></a>For Red Hat 9</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p>Install PostGreSQL 7.3.2 from RPM. Select
+ <tt class="computeroutput">Menu > System Settings > Add/Remove
+ Applications</tt> and select <tt class="computeroutput">Database Server</tt>.</p></li><li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div></div><div></div></div><p>After completing installation and restarting the server, go to <a href="http://localhost:8000" target="_top">http://localhost:8000</a> for configuration and customization instructions. You can upgrade a Quick Install with source control, full text search, backup/recovery, and other production features by walking through the <a href="unix-install" target="_top">Installation documentation</a> and doing the steps marked OPTIONAL.</p></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="software-versions.html">Next</a></td></tr><tr><td width="40%" align="left">Part�II.�Administrator's Guide </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Chapter�3.�Prerequisite Software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/quick.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/release-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v
diff -u -r1.15 -r1.16
--- openacs-4/packages/acs-core-docs/www/release-notes.html 20 Aug 2003 16:20:16 -0000 1.15
+++ openacs-4/packages/acs-core-docs/www/release-notes.html 14 Oct 2003 11:02:59 -0000 1.16
@@ -1,21 +1,86 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Release Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="previous" href="openacs-overview.html" title="Overview"><link rel="next" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><th width="60%" align="center">Chapter�1.�High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="release-notes"></a>OpenACS Release Notes</h2></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="release-notes-5-0-0"></a>Version 5.0.0</h3></div></div><div class="authorblurb"><p>
- by <a href="mailto:dhogaza@pacifier.com" target="_top">Don Baccus</a><br>
- OpenACS docs are written by the named authors, and may be edited
- by OpenACS documentation staff.
- </p></div><p>
- This is a pre-alpha release of OpenACS 5.0.0.
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Release Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="general-documents.html" title="Chapter�1.�High level information: What is OpenACS?"><link rel="previous" href="openacs-overview.html" title="Overview"><link rel="next" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><th width="60%" align="center">Chapter�1.�High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="release-notes"></a>OpenACS Release Notes</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-0a1"></a>Version 5.0.0 alpha1</h3></div></div><div></div></div><p>
+ This is the first alpha release of OpenACS 5.0.0. This
+ release has a number of severe bugs, and is not suitable for
+ production systems. It has passed several release criteria,
+ including that it installs successfully and that all automated
+ tests succeed.
</p><p>
Please report bugs using our
<a href="http://openacs.org/bugtracker/openacs/" target="_top">
Bug Tracker</a> at the <a href="http://openacs.org/" target="_top">OpenACS website</a>.
</p><p>
You may want to begin by reading our installation documentation for
- <a href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux">Chapter�4</a>. Note that the Windows documentation is
- not current for OpenACS 5.0.0d, but an alternative is to use John
+ <a href="unix-install.html" title="Chapter�4.�Installing on Unix/Linux">Chapter�4, <i>Installing on Unix/Linux</i></a>. Note that the Windows documentation is
+ not current for OpenACS 5.0.0a1, but an alternative is to use John
Sequeira's <a href="http://www.pobox.com/~johnseq/projects/oasisvm/" target="_top">Oasis VM
project</a>.
</p><p>
After installation, the full documentation set can be found by visiting
http://[your-host]/doc.
- </p></div><div class="cvstag">($Id$)</div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2808108"></a>Version 4.6.3</h3></div></div><p><a href="release-notes-4-6-3.html" target="_top">Release Notes for 4.6.3</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2808125"></a>Version 4.6.2</h3></div></div><p><a href="release-notes-4-6-2.html" target="_top">Release Notes for 4.6.2</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2808142"></a>Version 4.6</h3></div></div><p><a href="release-notes-4-6.html" target="_top">Release Notes for 4.6</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2808159"></a>Version 4.5</h3></div></div><p><a href="release-notes-4-5.html" target="_top">Release Notes for 4.5</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> Part�II.�Administrator's Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/release-notes.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p><p>
+ New features in this release:
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ Internationalization support.
+
+ A message catalog to store translated text, localization of
+ dates, number formatting, timezone conversion, etc. Allows
+ you to serve your users in their language.
+ </p></li><li><p>
+ External authenticaiton.
+
+ Integrate with outside user databases through e.g. LDAP, RADIUS, Kerberos, MS Active Directory.
+ Imports user information through IMS Enterprise 1.1 format. Easily extended to support other
+ authentication, password management, account creation, and account import mechanisms.
+
+ This includes improvements to the basic cookie handling, so logins can be expired without the
+ user's identity being completely lost. You can set login to expire after a certain period
+ (e.g. 8 hours, then password must be refreshed), or you can have all issues login cookies
+ expired at once, e.g. if you have left a permanent login cookie on a public machine somewhere.
+ </p></li><li><p>
+ User interface enhancements.
+
+ All pages, including site-wide and subsite admin pages, will be
+ templated, so they can be styled using master template and
+ site-wide stylesheets.
+
+ We have a new default-master template, which includes links to
+ administration, your workspace, and login/logout, and is rendered
+ using CSS.
+
+ And there's a new community template
+ (/packages/acs-subsite/www/group-master), which provides useful
+ navigation to the applications and administrative UI in a
+ subsite.
+
+ In addition, there's new, simpler UI for managing members of a
+ subsite, instantiating and mounting applications, setting
+ permissions, parameters, etc.
+
+ Site-wide admin as also seen the addition of a new simpler
+ software install UI to replace the APM for non-developer users,
+ and improved access to parameters, internationalization,
+ automated testing, service contracts, etc.
+
+ The list builder has been added for easily generating templated
+ tables and lists, with features such as filtering, sorting,
+ actions on multiple rows with checkboxes, etc. Most of all, it's
+ fast to use, and results in consistently-looking,
+ consistently-behaving, templated tables.
+ </p></li><li><p>
+ Automated testing.
+
+ The automated testing framework has been improved significantly,
+ and there are automated tests for a number of packages.
+ </p></li><li><p>
+ Security enhancements.
+
+ HTML quoting now happens in the templating system, greatly
+ minimizing the chance that users can sneak malicious HTML
+ into the pages of other users.
+ </p></li><li><p>
+ Oracle 9i support.
+ </p></li><li><p>
+ Who's online feature.
+ </p></li><li><p>
+ Spell checking.
+ </p></li></ul></div></div><div class="cvstag">($Id$)</div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2816622"></a>Version 4.6.3</h3></div></div><div></div></div><p><a href="release-notes-4-6-3.html" target="_top">Release Notes for 4.6.3</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2814621"></a>Version 4.6.2</h3></div></div><div></div></div><p><a href="release-notes-4-6-2.html" target="_top">Release Notes for 4.6.2</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2814639"></a>Version 4.6</h3></div></div><div></div></div><p><a href="release-notes-4-6.html" target="_top">Release Notes for 4.6</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2814656"></a>Version 4.5</h3></div></div><div></div></div><p><a href="release-notes-4-5.html" target="_top">Release Notes for 4.5</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> Part�II.�Administrator's Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/release-notes.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/request-processor.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/request-processor.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/request-processor.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,33 +1,32 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The Request Processor</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="objects.html" title="OpenACS Data Models and the Object System"><link rel="next" href="db-api.html" title="The OpenACS Database Access API"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="request-processor"></a>The Request Processor</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The Request Processor</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="objects.html" title="OpenACS Data Models and the Object System"><link rel="next" href="db-api.html" title="The OpenACS Database Access API"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="request-processor"></a>The Request Processor</h2></div></div><div></div></div><div class="authorblurb"><p>
By Pete Su
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-overview"></a>Overview</h3></div></div><p>
-This document is a brief introduction to the OpenACS 5.0.0d Request Processor;
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-overview"></a>Overview</h3></div></div><div></div></div><p>
+This document is a brief introduction to the OpenACS 5.0.0a1 Request Processor;
more details can be found in the <a href="rp-design.html">OpenACS 4 Request Processor Design</a>. Here we cover the high level concepts behind the
system, and implications and usage for the application developer.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-thenewway"></a>Request Processor</h3></div></div><p>
-The 5.0.0d Request Processor is a global filter and set of Tcl procs that
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-thenewway"></a>Request Processor</h3></div></div><div></div></div><p>
+The 5.0.0a1 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 <tt>http://someserver.com/notes/somepage.adp</tt>.
+request like <tt class="computeroutput">http://someserver.com/notes/somepage.adp</tt>.
-</p><div class="mediaobject"><img src="images/rp-flow.gif" align="center" longdesc="ld-id2965882.html"><div class="longdesc-link" align="right"><br clear="all"><span class="longdesc-link">[<a href="ld-id2965882.html" target="longdesc">D</a>]</span></div></div><p>
+</p><div class="mediaobject" align="center"><img src="images/rp-flow.gif" align="middle" longdesc="ld-id2841779.html"><div class="longdesc-link" align="right"><br clear="all"><span class="longdesc-link">[<a href="ld-id2841779.html" target="longdesc">D</a>]</span></div></div><p>
</p><div class="variablelist"><dl><dt><span class="term">Stage 1: Search Site Map</span></dt><dd><p>
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 <a href="packages.html">Packages</a>, and further
-discussed in <a href="subsites.html" title="Writing OpenACS 5.0.0d Application Pages">the section called “Writing OpenACS 5.0.0d Application Pages”</a>). This data model maps URLs to objects representing
+discussed in <a href="subsites.html" title="Writing OpenACS 5.0.0a1 Application Pages">Section�, “Writing OpenACS 5.0.0a1 Application Pages”</a>). This data model maps URLs to objects representing
content, and these objects are typically package instances.
</p><p>
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 <tt>ad_conn</tt> procedure,
-which is described in detail in <a href="rp-design.html">OpenACS 4 Request Processor Design</a>. The <a href="subsites.html" title="Writing OpenACS 5.0.0d Application Pages">page
+environment can be queried using the <tt class="computeroutput">ad_conn</tt> procedure,
+which is described in detail in <a href="rp-design.html">OpenACS 4 Request Processor Design</a>. The <a href="subsites.html" title="Writing OpenACS 5.0.0a1 Application Pages">page
development</a> tutorial shows you how to use this interface to make
your pages aware of which instance was requested.
</p></dd><dt><span class="term">Stage 2: Authentication</span></dt><dd><p>
@@ -38,9 +37,9 @@
extracts or sets up new session tokens for the user.
</p></dd><dt><span class="term">Stage 3: Authorization</span></dt><dd><p>
Next, the Request Processor checks if the user has appropriate access
-privileges to the requested part of the site. In OpenACS 5.0.0d, access control
+privileges to the requested part of the site. In OpenACS 5.0.0a1, access control
is dictated by the <a href="permissions" target="_top">permissions system</a>. In
-this case, the RP checks if the user has "read" priviledges on the
+this case, the RP checks if the user has "read" priviledges on the
object in the site map specified by the URL. This object is typically
a package instance, but it could easily be something more granular,
such as whehter the user can view a particular piece of content within
@@ -49,16 +48,16 @@
</p></dd><dt><span class="term">Stage 4: URL Processing, File Search</span></dt><dd><p>
Finally, the Request Processor finds the file we intend to serve,
searching the filesystem to locate the actual file that corresponds to
-an abstract URL. It searches for files with predefined "magic"
-extensions, i.e. files that end with: <tt>.html</tt>,
-<tt>.tcl</tt> and <tt>.adp</tt>.
+an abstract URL. It searches for files with predefined "magic"
+extensions, i.e. files that end with: <tt class="computeroutput">.html</tt>,
+<tt class="computeroutput">.tcl</tt> and <tt class="computeroutput">.adp</tt>.
</p><p>
If the RP can't find any matching files with the expected extensions,
-it will look for virtual-url-handler files, or <tt>.vuh</tt>
-files. A <tt>.vuh</tt> file will be executed as if it were a Tcl
+it will look for virtual-url-handler files, or <tt class="computeroutput">.vuh</tt>
+files. A <tt class="computeroutput">.vuh</tt> file will be executed as if it were a Tcl
file, but with the tail end of the URL removed. This allows the code
-in the <tt>.vuh</tt> file to act like a registered procedure for
-an entire subtree of the URL namespace. Thus a <tt>.vuh</tt> file
+in the <tt class="computeroutput">.vuh</tt> file to act like a registered procedure for
+an entire subtree of the URL namespace. Thus a <tt class="computeroutput">.vuh</tt> file
can be thought of as a replacement for filters and registered procs,
except that they integrate cleanly and correctly with the RP's URL
mapping mechanisms. The details of how to use these files are
@@ -67,64 +66,64 @@
Once the appropriate file is found, it is either served directly if
it's static content, or sent to the template system or the standard
Tcl interpreter if it's a dynamic page.
-</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-basicapi"></a>Basic API</h3></div></div><p>
+</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-basicapi"></a>Basic API</h3></div></div><div></div></div><p>
Once the flow of control reaches a dynamic page, the Request Processor
has populated the environment of the request with several pieces of
useful information. The RP's environment is accessible through the
-<tt>ad_conn</tt> interface, and the following calls should be
+<tt class="computeroutput">ad_conn</tt> interface, and the following calls should be
useful to you when developing dynamic pages:
-</p><div class="variablelist"><dl><dt><span class="term"><tt>[ad_conn user_id]</tt>
+</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">[ad_conn user_id]</tt>
</span></dt><dd><p>
The ID of the user associated with this request. By convention this is
zero if there is no user.
-</p></dd><dt><span class="term"><tt>[ad_conn session_id]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn session_id]</tt>
</span></dt><dd><p>
The ID of the session associated with this request.
-</p></dd><dt><span class="term"><tt>[ad_conn url]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn url]</tt>
</span></dt><dd><p>
The URL associated with the request.
-</p></dd><dt><span class="term"><tt>[ad_conn urlv]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn urlv]</tt>
</span></dt><dd><p>
The URL associated with the request, represented as a list instead of
a single string.
-</p></dd><dt><span class="term"><tt>[ad_conn file]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn file]</tt>
</span></dt><dd><p>
The actual local filesystem path of the file that is being served.
-</p></dd><dt><span class="term"><tt>[ad_conn object_url]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn object_url]</tt>
</span></dt><dd><p>
If the URL refers to a site map object, this is the URL to the root
of the tree where the object is mounted.
-</p></dd><dt><span class="term"><tt>[ad_conn package_url]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn package_url]</tt>
</span></dt><dd><p>
If the URL refers to a package instance, this is the URL to the root
of the tree where the package is mounted.
-</p></dd><dt><span class="term"><tt>[ad_conn extra_url]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn extra_url]</tt>
</span></dt><dd><p>
If we found the URL in the site map, this is the tail of the URL
following the part that matched a site map entry.
-</p></dd><dt><span class="term"><tt>[ad_conn object_id]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn object_id]</tt>
</span></dt><dd><p>
If the URL refers to a site map object, this is the ID of that object.
-</p></dd><dt><span class="term"><tt>[ad_conn package_id]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn package_id]</tt>
</span></dt><dd><p>
If the URL refers to a package instance, this is the ID of that
package instance.
-</p></dd><dt><span class="term"><tt>[ad_conn package_key]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn package_key]</tt>
</span></dt><dd><p>
If the URL refers to a package instance, this is the unique key name
of the package.
-</p></dd><dt><span class="term"><tt>[ad_conn path_info]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn path_info]</tt>
</span></dt><dd><p>
In a .vuh file, path_info is the trailing part of the URL not matched
Index: openacs-4/packages/acs-core-docs/www/requirements-template.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/requirements-template.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/requirements-template.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,8 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>System/Application Requirements Template</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="filename.html" title="Detailed Design Documentation Template"><link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="requirements-template"></a>System/Application Requirements Template</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a></p><br>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>System/Application Requirements Template</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="filename.html" title="Detailed Design Documentation Template"><link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="requirements-template"></a>System/Application Requirements Template</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div><div></div></div><p>
<span class="emphasis"><em>Briefly explain to the reader what this document is for, whether
it records the requirements for a new system, a client application, a
toolkit subsystem, etc. Remember your audience: fellow programmers,
@@ -11,35 +10,35 @@
everywhere, write clearly and precisely; for requirements
documentation, write at a level that any intelligent layperson can
understand.</em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>
<span class="emphasis"><em>Very broadly, describe how the system meets a need of a business,
group, the OpenACS as a whole, etc. Make sure that technical and
non-technical readers alike would understand what the system would do
and why it's useful. Whenever applicable, you should explicitly state
what the business value of the system is. </em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div><div></div></div><p>
<span class="emphasis"><em>Discuss the high-level breakdown of the components that make up
the system. You can go by functional areas, by the main transactions
the system allows, etc. </em></span>
</p><p>
<span class="emphasis"><em>You should also state the context and dependencies of the system
here, e.g. if it's an application-level package for OpenACS 4, briefly
describe how it uses kernel services, like permissions or subsites. </em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div><div></div></div><p>
<span class="emphasis"><em>Determine the types or classes of users who would use the
system, and what their experience would be like at a high-level.
Sketch what their experience would be like and what actions they would
take, and how the system would support them.</em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div><div></div></div><p>
<span class="emphasis"><em>Describe other systems or services that are comparable to what
you're building. If applicable, say why your implementation will be
superior, where it will match the competition, and where/why it will
lack existing best-of-breed capabilities. This section is also in the
Design doc, so write about it where you deem most appropriate.</em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-links"></a>Related Links</h3></div></div><p>Include all pertinent links to supporting and related material,
- such as: </p><div class="itemizedlist"><ul type="disc"><li><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li><li><p> Design document</p></li><li><p> Developer's guide</p></li><li><p> User's guide</p></li><li><p> Other-cool-system-related-to-this-one document</p></li><li><p> Test plan </p></li><li><p> Competitive system(s)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-links"></a>Related Links</h3></div></div><div></div></div><p>Include all pertinent links to supporting and related material,
+ such as: </p><div class="itemizedlist"><ul type="disc"><li><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li><li><p> Design document</p></li><li><p> Developer's guide</p></li><li><p> User's guide</p></li><li><p> Other-cool-system-related-to-this-one document</p></li><li><p> Test plan </p></li><li><p> Competitive system(s)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div><div></div></div><p>
<span class="emphasis"><em>The main course of the document, requirements. Break up the
requirements sections (A, B, C, etc.) as needed. Within each section,
create a list denominated with unique identifiers that reflect any
@@ -61,7 +60,7 @@
</p></blockquote></div></li></ul></div><p>
For guidelines writing requirements, take a
<a href="http://www.arsdigita.com/ad-sepg/process/requirements-quality.html" target="_top">look
- at the quality standards</a>, along with a good example, such as <a href="apm-requirements.html">OpenACS 5.0.0d Package Manager Requirements</a>.
+ at the quality standards</a>, along with a good example, such as <a href="apm-requirements.html">OpenACS 5.0.0a1 Package Manager Requirements</a>.
</p><p>
Besides writing requirements in natural language, consider using the
following techniques as needed:
@@ -74,11 +73,11 @@
suited to handle combinations of inputs. </p></li><li><p> Flowcharts - easy to draw and understand, suited for event and
decision driven systems. UML is the industry standard here.</p></li><li><p> Entity-Relationship diagrams - a necessary part of Design
documents, sometimes a high-level ER diagram is useful for
- requirements as well.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div><p>
+ requirements as well.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div><div></div></div><p>
<span class="emphasis"><em>Although in theory coding comes after design, which comes after
requirements, we do not, and perhaps should not, always follow such a
rigid process (a.k.a. the waterfall lifecyle). Often, there is a
pre-existing system or prototype first, and thus you may want to write
some thoughts on implementation, for aiding and guiding yourself or
other programmers. </em></span>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-revision-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr><tr><td width="40%" align="left">Detailed Design Documentation Template </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Release Version Numbering</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/requirements-template.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-revision-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th class="revisionheader">Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td class="revisionbody">0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr><tr><td width="40%" align="left">Detailed Design Documentation Template </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Release Version Numbering</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/requirements-template.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/rp-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/rp-design.html 20 Aug 2003 16:20:16 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/rp-design.html 14 Oct 2003 11:02:59 -0000 1.12
@@ -1,19 +1,18 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Request Processor Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements"><link rel="next" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="rp-design"></a>OpenACS 4 Request Processor Design</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Request Processor Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements"><link rel="next" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rp-design"></a>OpenACS 4 Request Processor Design</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-procs.tcl" target="_top">
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-procs.tcl" target="_top">
/packages/acs-kernel/tcl/request-processor-procs.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-init.tcl" target="_top">
/packages/acs-kernel/tcl/request-processor-init.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/site-nodes-procs.tcl" target="_top">
/packages/acs-kernel/tcl/site-nodes-procs.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/site-nodes-init.tcl" target="_top">
/packages/acs-kernel/tcl/site-nodes-init.tcl</a></p></li><li><p><a href="/doc/sql/display-sql?package_key=acs-kernel&url=site-nodes-create.sql" target="_top">
-/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-intro"></a>Introduction</h3></div></div><p>The request processor is the set of procs that responds to every HTTP
+/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-intro"></a>Introduction</h3></div></div><div></div></div><p>The request processor is the set of procs that responds to every HTTP
request made to the OpenACS. The request processor must authenticate the
connecting user, and make sure that he is authorized to perform the given
request. If these steps succeed, then the request processor must locate the
file that is associated with the specified URL, and serve the content it
-provides to the browser.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-related-systems"></a>Related Systems</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="apm-design.html">OpenACS 5.0.0d Package Manager Design</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-terminology"></a>Terminology</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+provides to the browser.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-related-systems"></a>Related Systems</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="apm-design.html">OpenACS 5.0.0a1 Package Manager Design</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-terminology"></a>Terminology</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
<span class="strong">pageroot</span> -- 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.</p></li><li><p><span class="strong">global pageroot</span>
@@ -31,7 +30,7 @@
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.</p></li><li><p><span class="strong">concrete file</span> or <span class="strong">concrete path</span> -- A file
-or path that actually references something in the filesystem.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-system-overview"></a>System Overview</h3></div></div><p><span class="strong">Package Lookup</span></p><p>One of the first things the request processor must do is to determine
+or path that actually references something in the filesystem.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-system-overview"></a>System Overview</h3></div></div><div></div></div><p><span class="strong">Package Lookup</span></p><p>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
@@ -75,7 +74,7 @@
special distinction is required between sitewide procs and package specific
procs when using this facility. It is also much less prone to overlap and
confusion than the use of registered procs, especially in an environment with
-many packages installed.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-site-nodes"></a>Site Nodes</h3></div></div><p>The request processor manages the mappings from URL patterns to package
+many packages installed.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-site-nodes"></a>Site Nodes</h3></div></div><div></div></div><p>The request processor manages the mappings from URL patterns to package
instances with the site_nodes data model. Every row in the site_nodes table
represents a fully qualified URL. A package can be mounted on any node in
this data model. When the request processor performs a URL lookup, it
@@ -88,15 +87,15 @@
performed by starting with the full request URI and successively stripping
off the rightmost path components until a match is reached. This way the time
required to lookup a URL is proportional to the length of the URL, not to the
-number of entries in the mapping.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-design-req-env"></a>Request Environment</h3></div></div><p>The request environment is managed by the procedure
+number of entries in the mapping.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-req-env"></a>Request Environment</h3></div></div><div></div></div><p>The request environment is managed by the procedure
<span class="strong">ad_conn</span>. 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.</p><div class="informaltable"><table cellspacing="0" border="0"><colgroup><col><col></colgroup><tbody><tr><td colspan="2"><span class="strong">Request processor</span></td></tr><tr><td valign="top"><tt>[ad_conn urlv]</tt></td><td valign="top">A list containing each element of the URL</td></tr><tr><td valign="top"><tt>[ad_conn url]</tt></td><td valign="top">The URL associated with the request.</td></tr><tr><td valign="top"><tt>[ad_conn file]</tt></td><td valign="top">The filepath including filename of the file being served</td></tr><tr><td valign="top"><tt>[ad_conn request]</tt></td><td valign="top">The number of requests since the server was last started</td></tr><tr><td valign="top"><tt>[ad_conn start_clicks]</tt></td><td valign="top">The system time when the RP starts handling the request</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Session System Variables</span>: set in
-sec_handler, check security with ad_validate_security_info</td></tr><tr><td valign="top"><tt>[ad_conn session_id]</tt></td><td valign="top">The unique session_id coming from the sequence
-<tt>sec_id_seq</tt></td></tr><tr><td valign="top"><tt>[ad_conn user_id]</tt></td><td valign="top">User_id of a person if the person is logged in. Otherwise, it is
-blank</td></tr><tr><td valign="top"><tt>[ad_conn sec_validated]</tt></td><td valign="top">This becomes "secure" when the connection uses SSL</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Database API</span></td></tr><tr><td valign="top"><tt>[ad_conn db,handles]</tt></td><td valign="top">What are the list of handles available to AOL?</td></tr><tr><td valign="top"><tt>[ad_conn db,n_handles_used]</tt></td><td valign="top">How many database handles are currently used?</td></tr><tr><td valign="top"><tt>[ad_conn db,last_used]</tt></td><td valign="top">Which database handle did we use last?</td></tr><tr><td valign="top"><tt>[ad_conn db,transaction_level,$db]</tt></td><td valign="top">Specifies what transaction level we are in</td></tr><tr><td valign="top"><tt>[ad_conn db,db_abort_p,$dbh]</tt></td><td valign="top">Whether the transaction is aborted</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">APM</span></td></tr><tr><td valign="top"><tt>[ad_conn xml_loaded_p]</tt></td><td valign="top">Checks whether the XML parser is loaded so that it only gets loaded once.
-Set in apm_load_xml_packages</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Packages</span></td></tr><tr><td valign="top"><tt>[ad_conn package_id]</tt></td><td valign="top">The package_id of the package associated with the URL.</td></tr><tr><td valign="top"><tt>[ad_conn package_url]</tt></td><td valign="top">The URL on which the package is mounted.</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Miscellaneous</span></td></tr><tr><td valign="top"><tt>[ad_conn system_p]</tt></td><td valign="top">If true then the request has been made to one of the special directories
+ad_conn subsumes the functionality of ns_conn.</p><div class="informaltable"><table cellspacing="0" border="0"><colgroup><col><col></colgroup><tbody><tr><td colspan="2"><span class="strong">Request processor</span></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn urlv]</tt></td><td valign="top">A list containing each element of the URL</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn url]</tt></td><td valign="top">The URL associated with the request.</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn file]</tt></td><td valign="top">The filepath including filename of the file being served</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn request]</tt></td><td valign="top">The number of requests since the server was last started</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn start_clicks]</tt></td><td valign="top">The system time when the RP starts handling the request</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Session System Variables</span>: set in
+sec_handler, check security with ad_validate_security_info</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn session_id]</tt></td><td valign="top">The unique session_id coming from the sequence
+<tt class="computeroutput">sec_id_seq</tt></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn user_id]</tt></td><td valign="top">User_id of a person if the person is logged in. Otherwise, it is
+blank</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn sec_validated]</tt></td><td valign="top">This becomes "secure" when the connection uses SSL</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Database API</span></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn db,handles]</tt></td><td valign="top">What are the list of handles available to AOL?</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn db,n_handles_used]</tt></td><td valign="top">How many database handles are currently used?</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn db,last_used]</tt></td><td valign="top">Which database handle did we use last?</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn db,transaction_level,$db]</tt></td><td valign="top">Specifies what transaction level we are in</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn db,db_abort_p,$dbh]</tt></td><td valign="top">Whether the transaction is aborted</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">APM</span></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn xml_loaded_p]</tt></td><td valign="top">Checks whether the XML parser is loaded so that it only gets loaded once.
+Set in apm_load_xml_packages</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Packages</span></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn package_id]</tt></td><td valign="top">The package_id of the package associated with the URL.</td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn package_url]</tt></td><td valign="top">The URL on which the package is mounted.</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Miscellaneous</span></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn system_p]</tt></td><td valign="top">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.</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Documentation</span></td></tr><tr><td valign="top"><tt>[ad_conn api_page_documentation_mode_p]</tt></td><td valign="top">�</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Request Processor Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Documenting Tcl Files: Page Contracts and Libraries</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/rp-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
+authorization has been performed.</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong">Documentation</span></td></tr><tr><td valign="top"><tt class="computeroutput">[ad_conn api_page_documentation_mode_p]</tt></td><td valign="top">�</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Request Processor Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Documenting Tcl Files: Page Contracts and Libraries</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/rp-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v
diff -u -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/rp-requirements.html 28 Jun 2003 05:07:02 -0000 1.10
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 14 Oct 2003 11:02:59 -0000 1.11
@@ -1,15 +1,14 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Request Processor Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="security-notes.html" title="OpenACS 4 Security Notes"><link rel="next" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="rp-requirements"></a>OpenACS 4 Request Processor Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Request Processor Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="security-notes.html" title="OpenACS 4 Security Notes"><link rel="next" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rp-requirements"></a>OpenACS 4 Request Processor Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-intro"></a>Introduction</h3></div></div><p>The following is a requirements document for the OpenACS 4.0 request
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-intro"></a>Introduction</h3></div></div><div></div></div><p>The following is a requirements document for the OpenACS 4.0 request
processor. The major enhancements in the 4.0 version include a more
sophisticated directory mapping system that allows package pageroots to be
mounted at arbitrary urls, and tighter integration with the database to allow
-for flexible user controlled url structures, and subsites.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-vision"></a>Vision Statement</h3></div></div><p>Most web servers are designed to serve pages from exactly one static
+for flexible user controlled url structures, and subsites.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>Most web servers are designed to serve pages from exactly one static
pageroot. This restriction can become cumbersome when trying to build a web
-toolkit full of reusable and reconfigurable components.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-system-overview"></a>System Overview</h3></div></div><p>The request processor's functionality can be split into two main
+toolkit full of reusable and reconfigurable components.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-system-overview"></a>System Overview</h3></div></div><div></div></div><p>The request processor's functionality can be split into two main
pieces.</p><div class="orderedlist"><ol type="1"><li><p>Set up the environment in which a server side script expects to run. This
includes things like:</p><div class="itemizedlist"><ul type="disc"><li><p>Initialize common variables associated with a request.</p></li><li><p>Authenticate the connecting party.</p></li><li><p>Check that the connecting party is authorized to proceed with the
request.</p></li><li><p>Invoke any filters associated with the request URI.</p></li></ul></div></li><li><p>Determine to which entity the request URI maps, and deliver the content
@@ -19,7 +18,7 @@
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.</p></li></ol></div><p>It is essential that any errors that occur during the above steps be
-reported to developers in an easily decipherable manner.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-links"></a>Related Links</h3></div></div><p><a href="rp-design.html">OpenACS 4 Request Processor Design</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-req"></a>Requirements</h3></div></div><p><span class="strong">10.0 Multiple Pageroots</span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">10.10</span> Pageroots may be combined into one URL space.</p><p><span class="strong">10.20</span> Pageroots may be mounted at more than one location in the URL
+reported to developers in an easily decipherable manner.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-links"></a>Related Links</h3></div></div><div></div></div><p><a href="rp-design.html">OpenACS 4 Request Processor Design</a></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-req"></a>Requirements</h3></div></div><div></div></div><p><span class="strong">10.0 Multiple Pageroots</span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">10.10</span> Pageroots may be combined into one URL space.</p><p><span class="strong">10.20</span> Pageroots may be mounted at more than one location in the URL
space.</p></blockquote></div><p><span class="strong">20.0 Application Context</span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">20.10</span> 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.</p></blockquote></div><p><span class="strong">30.0 Authentication</span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong">30.10</span> The request processor must be able to verify that the connecting
Index: openacs-4/packages/acs-core-docs/www/security-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/security-design.html 20 Aug 2003 16:20:16 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/security-design.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,10 +1,9 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Security Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="security-requirements.html" title="OpenACS 4 Security Requirements"><link rel="next" href="security-notes.html" title="OpenACS 4 Security Notes"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="security-design"></a>OpenACS 4 Security Design</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Security Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="security-requirements.html" title="OpenACS 4 Security Requirements"><link rel="next" href="security-notes.html" title="OpenACS 4 Security Notes"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-design"></a>OpenACS 4 Security Design</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>, <a href="mailto:ashah@arsdigita.com" target="_top">Archit Shah</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="security-requirements.html">OpenACS 4 Security Requirements</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-design-intro"></a>Introduction</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="security-requirements.html">OpenACS 4 Security Requirements</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-intro"></a>Introduction</h3></div></div><div></div></div><p>
This document explains security model design for OpenACS 4. The security system
with the OpenACS core must authenticate users in both secure and insecure
environments. In addition, this subsystem provides sessions on top of the
@@ -20,15 +19,15 @@
</p></li><li><p>SSL with server authentication: <a href="http://home.netscape.com/eng/ssl3/ssl-toc.html" target="_top">SSL v3</a> </p><p>SSL provides the client with a guarantee that the server is
actually the server it is advertised as being. It also provides a secure
transport.
-</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-design-design"></a>Design</h3></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="sessions"></a>Sessions</h4></div></div><p>
+</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-design"></a>Design</h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sessions"></a>Sessions</h4></div></div><div></div></div><p>
A session is defined as a series of clicks in which no two clicks are
separated by more than some constant. This constant is the parameter
SessionTimeout. Using the expiration time on the signatures of the signed
cookies, we can verify when the cookie was issued and determine if two
requests are part of the same session. It is important to note that the
expiration time set in the cookie protocol is not trusted. Only the time
inserted by the signed cookie mechanism is trusted.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="authentication"></a>Authentication</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="authentication"></a>Authentication</h4></div></div><div></div></div><p>
Two levels of access can be granted: insecure and secure. This grant lasts
for the remainder of the particular session. Secure authentication tokens are
only issued over secured connections.
@@ -42,86 +41,86 @@
password can be sniffed from the system, after which the sniffer can apply
for a secure authentication token. However, the basic architecture here lays
the foundation for a secure system and can be easily adapted to a more secure
-authentication system by forcing all logins to occur over HTTPS.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="authentication-details"></a>Details</h4></div></div><p>The authentication system issues up to four signed cookies (see below),
+authentication system by forcing all logins to occur over HTTPS.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="authentication-details"></a>Details</h4></div></div><div></div></div><p>The authentication system issues up to four signed cookies (see below),
with each cookie serving a different purpose. These cookies are:</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">name</span></td><td><span class="strong">value</span></td><td><span class="strong">max-age</span></td><td><span class="strong">secure?</span></td></tr><tr><td>ad_session_id</td><td>session_id,user_id</td><td>SessionTimeout</td><td>no</td></tr><tr><td>ad_user_login</td><td>user_id</td><td>Infinity</td><td>no</td></tr><tr><td>ad_user_login_secure</td><td>user_id,random</td><td>Infinity</td><td>yes</td></tr><tr><td>ad_secure_token</td><td>session_id,user_id,random</td><td>SessionLifetime</td><td>yes</td></tr></tbody></table></div></blockquote></div><div class="itemizedlist"><ul type="disc"><li><p>ad_session_id</p><div class="itemizedlist"><ul type="circle"><li><p>reissued on any hit separated by more than SessionRenew seconds from the
previous hit that received a cookie</p></li><li><p>is valid only for SessionTimeout seconds</p></li><li><p>is the canonical source for the session ID in ad_conn</p></li></ul></div></li><li><p>ad_user_login</p><div class="itemizedlist"><ul type="circle"><li><p>is used for permanent logins</p></li></ul></div></li><li><p>ad_user_login_secure</p><div class="itemizedlist"><ul type="circle"><li><p>is used for permanent secure logins</p></li><li><p>contains random garbage (ns_time) to prevent attack against the secure
hash</p></li></ul></div></li><li><p>ad_secure_token
</p><div class="itemizedlist"><ul type="circle"><li><p>is a session-level cookie from the browser's standpoint</p></li><li><p>its signature expires in SessionLifetime seconds</p></li><li><p>contains random garbage (ns_time) to prevent attack against the secure
-hash</p></li><li><p>user_id is extraneous</p></li></ul></div></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="authentication-process"></a>Authentication Process</h4></div></div><p>The Tcl function (<tt>sec_handler</tt>) is called by the request
+hash</p></li><li><p>user_id is extraneous</p></li></ul></div></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="authentication-process"></a>Authentication Process</h4></div></div><div></div></div><p>The Tcl function (<tt class="computeroutput">sec_handler</tt>) is called by the request
processor to authenticate the user. It first checks the
-<tt>ad_session_id</tt> cookie. If there is no valid session in progress,
-a new session is created with <tt>sec_setup_session</tt>. If the user
-has permanent login cookies (<tt>ad_user_login</tt> and
-<tt>ad_user_login_secure</tt>), then they are looked at to determine what
+<tt class="computeroutput">ad_session_id</tt> cookie. If there is no valid session in progress,
+a new session is created with <tt class="computeroutput">sec_setup_session</tt>. If the user
+has permanent login cookies (<tt class="computeroutput">ad_user_login</tt> and
+<tt class="computeroutput">ad_user_login_secure</tt>), then they are looked at to determine what
user the session should be authorized as. Which cookie is examined is
determined by whether or not the request is on a secure connection. If
neither cookie is present, then a session is created without any
-authentication. If the <tt>ad_session_id</tt> cookie is valid, the
-user_id and session_id are pulled from it and put into ad_conn.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="secure-connections"></a>Authenticating Secure Connections</h4></div></div><p>Secure connections are authenticated slightly differently. The function
-<tt>ad_secure_conn_p</tt> is used to determine whether or not the URL
+authentication. If the <tt class="computeroutput">ad_session_id</tt> cookie is valid, the
+user_id and session_id are pulled from it and put into ad_conn.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="secure-connections"></a>Authenticating Secure Connections</h4></div></div><div></div></div><p>Secure connections are authenticated slightly differently. The function
+<tt class="computeroutput">ad_secure_conn_p</tt> is used to determine whether or not the URL
being accessed is requires a secure login. The function simply checks if the
-location begins with "https". (This is safe because the location is
-set during the server initialization.)</p><p>If secure authentication is required, the <tt>ad_secure_token</tt>
+location begins with "https". (This is safe because the location is
+set during the server initialization.)</p><p>If secure authentication is required, the <tt class="computeroutput">ad_secure_token</tt>
cookie is checked to make sure its data matches the data stored in
-<tt>ad_session_id</tt>. This is true for all pages except those that are
+<tt class="computeroutput">ad_session_id</tt>. This is true for all pages except those that are
part of the login process. On these pages, the user can not yet have received
-the appropriate <tt>ad_secure_token</tt> cookie, so no check against it
+the appropriate <tt class="computeroutput">ad_secure_token</tt> cookie, so no check against it
is performed. The set of pages that skip that processing are determined by
-determined by <tt>ad_login_page</tt>. Since the
-<tt>ad_secure_token</tt> cookie is a session cookie, it is deleted by the
+determined by <tt class="computeroutput">ad_login_page</tt>. Since the
+<tt class="computeroutput">ad_secure_token</tt> cookie is a session cookie, it is deleted by the
browser when the browser exits. Since an attacker could conceivably store the
secure cookie in a replay attack (since expiration date is not validated),
the data in the secure cookie is never used to set any data in ad_conn;
user_id and session_id is set from the ad_session_id cookie.</p><p>It is important to note that the integrity of secure authentication rests
-on the two Tcl function <tt>ad_secure_conn_p</tt> and
-<tt>ad_login_page</tt>. If <tt>ad_secure_conn_p</tt> is false, secure
-authentication is not required. If <tt>ad_login_page</tt> is false,
-secure authentication is not required.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="login-process"></a>Login Process</h4></div></div><p>The Tcl function <tt>ad_user_login</tt> does two things. First it
+on the two Tcl function <tt class="computeroutput">ad_secure_conn_p</tt> and
+<tt class="computeroutput">ad_login_page</tt>. If <tt class="computeroutput">ad_secure_conn_p</tt> is false, secure
+authentication is not required. If <tt class="computeroutput">ad_login_page</tt> is false,
+secure authentication is not required.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="login-process"></a>Login Process</h4></div></div><div></div></div><p>The Tcl function <tt class="computeroutput">ad_user_login</tt> does two things. First it
performs the appropriate manipulation of the permanent login cookies, and
then it updates the current session to reflect the new user_id. The
manipulation of the permanent login cookies is based on 3 factors:</p><div class="itemizedlist"><ul type="disc"><li><p>previous login: other user, same user</p></li><li><p>permanent: was a permanent login requested?</p></li><li><p>secure: is this a secure connection?</p></li></ul></div><p>
Both the secure and insecure permanent login cookie can have one of three
actions taken on it:
-</p><div class="itemizedlist"><ul type="disc"><li><p>set: cookie with no expiration is set</p></li><li><p>delete: set to "" with max age of 0, so it is expired
+</p><div class="itemizedlist"><ul type="disc"><li><p>set: cookie with no expiration is set</p></li><li><p>delete: set to "" with max age of 0, so it is expired
immediately</p></li><li><p>nothing: if the cookie is present, it remains</p></li></ul></div><p>
The current state of the permanent login cookies is not taken into account
when determining the appropriate action.
-</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong">previous login state</span></td><td><span class="strong">permanent login requested</span></td><td><span class="strong">secure connection</span></td><td><span class="strong">action on insecure</span></td><td><span class="strong">action on secure</span></td></tr><tr><td>other</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>same</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>other</td><td>y</td><td>n</td><td>set</td><td>delete</td></tr><tr><td>same</td><td>y</td><td>n</td><td>set</td><td>nothing</td></tr><tr><td>same</td><td>n</td><td>y</td><td>nothing</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>y</td><td>delete</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr><tr><td>same</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr></tbody></table></div></blockquote></div><p><tt>ad_user_login</tt>
-calls<tt>sec_setup_session</tt> which actually calls
-<tt>sec_generate_session_id_cookie</tt> to generate the
+</p><div class="blockquote"><blockquote class="blockquote"><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong">previous login state</span></td><td><span class="strong">permanent login requested</span></td><td><span class="strong">secure connection</span></td><td><span class="strong">action on insecure</span></td><td><span class="strong">action on secure</span></td></tr><tr><td>other</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>same</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>other</td><td>y</td><td>n</td><td>set</td><td>delete</td></tr><tr><td>same</td><td>y</td><td>n</td><td>set</td><td>nothing</td></tr><tr><td>same</td><td>n</td><td>y</td><td>nothing</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>y</td><td>delete</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr><tr><td>same</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr></tbody></table></div></blockquote></div><p><tt class="computeroutput">ad_user_login</tt>
+calls<tt class="computeroutput">sec_setup_session</tt> which actually calls
+<tt class="computeroutput">sec_generate_session_id_cookie</tt> to generate the
new cookie with refer to the appropriate user_id. If the connection is secure
-the <tt>ad_secure_token</tt> cookie is generated by a
-call to <tt>sec_generate_secure_token_cookie</tt>. This
+the <tt class="computeroutput">ad_secure_token</tt> cookie is generated by a
+call to <tt class="computeroutput">sec_generate_secure_token_cookie</tt>. This
function is only called from
-<tt>sec_setup_session</tt>. Only
-<tt>sec_handler</tt> and
-<tt>sec_setup_session</tt> call
-<tt>sec_generate_session_id_cookie</tt>.
+<tt class="computeroutput">sec_setup_session</tt>. Only
+<tt class="computeroutput">sec_handler</tt> and
+<tt class="computeroutput">sec_setup_session</tt> call
+<tt class="computeroutput">sec_generate_session_id_cookie</tt>.
-</p><p><tt>ad_user_logout</tt> logs the user out by deleting all 4 cookies
-that are used by the authentication system.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="session-creation"></a>Session Creation</h4></div></div><p>The creation and setup of sessions is handled in
-<tt>sec_setup_session</tt>, which is called either to
-create a new session from <tt>sec_handler</tt> or from
-<tt>ad_user_login</tt> when there is a change in
+</p><p><tt class="computeroutput">ad_user_logout</tt> logs the user out by deleting all 4 cookies
+that are used by the authentication system.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="session-creation"></a>Session Creation</h4></div></div><div></div></div><p>The creation and setup of sessions is handled in
+<tt class="computeroutput">sec_setup_session</tt>, which is called either to
+create a new session from <tt class="computeroutput">sec_handler</tt> or from
+<tt class="computeroutput">ad_user_login</tt> when there is a change in
authorization level. The session management code must do two things: insure that
session-level data does not float between users, and update the users table
-which has columns for <tt>n_sessions</tt>,
-<tt>last_visit</tt>, and
-<tt>second_to_last_visit</tt>.</p><p>If there is no session already setup on this hit, a new session is
-created. This happens when <tt>sec_setup_session</tt> is
-called from <tt>sec_handler</tt>. If the login is from a
+which has columns for <tt class="computeroutput">n_sessions</tt>,
+<tt class="computeroutput">last_visit</tt>, and
+<tt class="computeroutput">second_to_last_visit</tt>.</p><p>If there is no session already setup on this hit, a new session is
+created. This happens when <tt class="computeroutput">sec_setup_session</tt> is
+called from <tt class="computeroutput">sec_handler</tt>. If the login is from a
user to another user, a new session is created, otherwise, the current session
is continued, simply with a higher authorization state. This allows for data
associated with a session to be carried over when a user logs in.</p><p>The users table is updated by
-<tt>sec_update_user_session_info</tt> which is called
+<tt class="computeroutput">sec_update_user_session_info</tt> which is called
when an existing session is assigned a non-zero user_id, or when a session is
-created with a non-zero user_id.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="passwords"></a>Passwords</h4></div></div><p><tt>ad_user_login</tt> assumes a password check has already been
+created with a non-zero user_id.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="passwords"></a>Passwords</h4></div></div><div></div></div><p><tt class="computeroutput">ad_user_login</tt> assumes a password check has already been
performed (this will change in the future). The actual check is done by
-<tt>ad_check_password</tt>. The database stores a salt and a hash of the
+<tt class="computeroutput">ad_check_password</tt>. The database stores a salt and a hash of the
password concatenated with the salt. Updating the password
-(<tt>ad_change_password</tt>) simply requires getting a new salt
+(<tt class="computeroutput">ad_change_password</tt>) simply requires getting a new salt
(ns_time) concatenating and rehashing. Both the salt and the hashed password
-field are updated.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="performance-enhancements"></a>Performance Enhancements</h4></div></div><p>A session is labeled by a session_id sequence. Creating a session merely
+field are updated.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="performance-enhancements"></a>Performance Enhancements</h4></div></div><div></div></div><p>A session is labeled by a session_id sequence. Creating a session merely
requires incrementing the session_id sequence. We do two things to improve the
performance of this process. First, sequence values are precomputed and cached
in the Oracle SGA. In addition, sequence values are incremented by 100 with each
@@ -130,41 +129,41 @@
command per thread. This minimizes lock contention for the session ID sequence
and also minimizes the number of DB requests, since each thread can allocate 100
sessions before requiring another DB hit. This cache works by keeping two
-counters: <tt>tcl_max_value</tt> and
-<tt>tcl_current_sequence_id</tt>. When
-<tt>tcl_current_sequence_id</tt> is greater than
-<tt>tcl_max_value</tt> a new value is requested from the
-db and <tt>tcl_max_value</tt> is incremented by
+counters: <tt class="computeroutput">tcl_max_value</tt> and
+<tt class="computeroutput">tcl_current_sequence_id</tt>. When
+<tt class="computeroutput">tcl_current_sequence_id</tt> is greater than
+<tt class="computeroutput">tcl_max_value</tt> a new value is requested from the
+db and <tt class="computeroutput">tcl_max_value</tt> is incremented by
100. This is done on a per-thread basis so that no locking is required.
</p><p>In addition, two procedures are dynamically generated at startup in
-<tt>security-init.tcl</tt>. These two procedures use
-<tt>ad_parameter</tt> to obtain the constant value of a given parameter;
+<tt class="computeroutput">security-init.tcl</tt>. These two procedures use
+<tt class="computeroutput">ad_parameter</tt> to obtain the constant value of a given parameter;
these values are used to dynamically generate a procedure that returns a
constant. This approach avoids (relatively) expensive calls to
-<tt>ad_parameter</tt> in <tt>sec_handler</tt>. The impact of this
+<tt class="computeroutput">ad_parameter</tt> in <tt class="computeroutput">sec_handler</tt>. The impact of this
approach is that these parameters cannot be dynamically changed at runtime
-and require a server restart.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="session-properties"></a>Session Properties</h4></div></div><p>
+and require a server restart.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="session-properties"></a>Session Properties</h4></div></div><div></div></div><p>
Session properties are stored in a single table that maps session IDs to
named session properties and values. This table is periodically purged. For
maximum performance, the table is created with nologging turned on and new
extents are allocated in 50MB increments to reduce fragmentation. This table
-is swept periodically by <tt>sec_sweep_session</tt> which removes
+is swept periodically by <tt class="computeroutput">sec_sweep_session</tt> which removes
sessions whose first hit was more than SessionLifetime seconds (1 week by
default) ago. Session properties are removed through that same process with
cascading delete.
-</p></div><div class="sect4" lang="en"><div class="titlepage"><div><h5 class="title"><a name="secure-session-properties"></a>Secure Session Properties</h5></div></div><p>Session properties can be set as secure. In this case,
-<tt>ad_set_client_property</tt> will fail if the connection is not
-secure. <tt>ad_get_client_property</tt> will behave as if the property
-had not been set if the property was not set securely.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="digital-signatures"></a>Digital Signatures & Signed Cookies</h4></div></div><p>
+</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="secure-session-properties"></a>Secure Session Properties</h5></div></div><div></div></div><p>Session properties can be set as secure. In this case,
+<tt class="computeroutput">ad_set_client_property</tt> will fail if the connection is not
+secure. <tt class="computeroutput">ad_get_client_property</tt> will behave as if the property
+had not been set if the property was not set securely.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="digital-signatures"></a>Digital Signatures & Signed Cookies</h4></div></div><div></div></div><p>
Signed cookies are implemented using the generic secure digital signature
mechanism. This mechanism guarantees that the user can not tamper with (or
construct a value of his choice) without detection. In addition, it provides
the optional facility of timing out the signature so it is valid for only a
certain period of time. This works by simply including an expiration time as
part of the value that is signed.
-</p><p>The signature produced by <tt>ad_sign</tt> is the Tcl list of
-<tt>token_id,expire_time,hash</tt>, where hash =
+</p><p>The signature produced by <tt class="computeroutput">ad_sign</tt> is the Tcl list of
+<tt class="computeroutput">token_id,expire_time,hash</tt>, where hash =
SHA1(value,token_id,expire_time,secret_token). The secret_token is a forty
character randomly generated string that is never sent to any user agent. The
scheme consists of one table:</p><pre class="programlisting">
@@ -176,7 +175,7 @@
token_timestamp sysdate
);
-</pre><p><tt>ad_verify_signature</tt> takes a value and a signature and
+</pre><p><tt class="computeroutput">ad_verify_signature</tt> takes a value and a signature and
verifies that the signature was generated using that value. It works simply
by taking the token_id and expire_time from the signature, and regenerating
the hash using the supplied value and the secret_token corresponding to the
@@ -188,21 +187,21 @@
signature, RFC 2109 specifies an optional max age that is returned to the
client. For most cookies, this max age matches the expiration date of the
cookie's signature. The standard specifies that when the max age is not
-included, the cookie should be "discarded when the user agent
-exits." Because we can not trust the client to do this, we must specify
+included, the cookie should be "discarded when the user agent
+exits." Because we can not trust the client to do this, we must specify
a timeout for the signature. The SessionLifetime parameter is used for this
purpose, as it represents the maximum possible lifetime of a single
-session.</p><p>RFC 2109 specifies this optional "secure" parameter which
-mandates that the user-agent use "secure means" to contact the
+session.</p><p>RFC 2109 specifies this optional "secure" parameter which
+mandates that the user-agent use "secure means" to contact the
server when transmitting the cookie. If a secure cookie is returned to the
client over https, then the cookie will never be transmitted over insecure
-means.</p><div class="sect4" lang="en"><div class="titlepage"><div><h5 class="title"><a name="signature-performance"></a>Performance</h5></div></div><p>Performance is a key goal of this implementation of signed cookies. To
+means.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="signature-performance"></a>Performance</h5></div></div><div></div></div><p>Performance is a key goal of this implementation of signed cookies. To
maximize performance, we will use the following architecture. At the lowest
-level, we will use the <tt>secret_tokens</tt> table as the canonical set
+level, we will use the <tt class="computeroutput">secret_tokens</tt> table as the canonical set
of secret tokens. This table is necessary for multiple servers to maintain
the same set of secret tokens. At server startup, a random subset of these
secret tokens will be loaded into an ns_cache called
-<tt>secret_tokens</tt>. When a new signed cookie is requested, a random
+<tt class="computeroutput">secret_tokens</tt>. When a new signed cookie is requested, a random
token_id is returned out of the entire set of cached token_ids. In addition,
a thread-persistent cache called tcl_secret_tokens is maintained on a
per-thread basis.</p><p>Thus, the L2 ns_cache functions as a server-wide LRU cache that has a
@@ -215,31 +214,31 @@
all secret tokens. Note that this is <span class="strong">not</span> an LRU cache
because there is no cache eviction policy per se -- the cache is cleared when
the thread is destroyed by AOLserver.
-</p></div><div class="sect4" lang="en"><div class="titlepage"><div><h5 class="title"><a name="signature-security"></a>Security</h5></div></div><p>Storing information on a client always presents an additional security
+</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="signature-security"></a>Security</h5></div></div><div></div></div><p>Storing information on a client always presents an additional security
risk.</p><p>Since we are only validating the information and not trying to protect it
as a secret, we don't use salt. Cryptographic salt is useful if you are
-trying to protect information from being read (e.g., hashing passwords).</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="external-ssl"></a>External SSL</h4></div></div><p>
+trying to protect information from being read (e.g., hashing passwords).</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="external-ssl"></a>External SSL</h4></div></div><div></div></div><p>
External SSL mechanisms (firewall, dedicated hardware, etc.) can be used by
creating two pools of AOLservers. In one pool the servers should be
configured with the location parameter of nssock module set to
-"https://yourservername". The servers in the other pool are
+"https://yourservername". The servers in the other pool are
configured as normal. The external SSL agent should direct SSL queries to the
pool of secure servers, and it should direct non-SSL queries to the insecure
servers.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="PRNG"></a>PRNG</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="PRNG"></a>PRNG</h4></div></div><div></div></div><p>
The pseudorandom number generator depends primarily on ns_rand, but is also
seeded with ns_time and the number of page requests served since the server
was started. The PRNG takes the SHA1(seed,ns_rand,ns_time,requests,clicks),
and saves the first 40 bits as the seed for the next call to the PRNG in a
thread-persistent global variable. The remaining 120 bits are rehashed to
produce 160 bits of output.
-</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-design-api"></a>API</h3></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="login-password-api"></a>Login/Password</h4></div></div><p>
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-api"></a>API</h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="login-password-api"></a>Login/Password</h4></div></div><div></div></div><p>
<span class="strong">ad_user_login <span class="emphasis"><em>user_id</em></span></span> Logs the user in as user
<span class="emphasis"><em>user_id</em></span>. Optional forever flag determines whether or not permanent
cookies are issued.
</p><p><span class="strong">ad_user_logout</span> Logs the user out.</p><p><span class="strong">ad_check_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>password</em></span></span>
returns 0 or 1.</p><p><span class="strong">ad_change_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>new
-password</em></span></span></p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="signature-api"></a>Digital Signatures and Signed Cookies</h4></div></div><p>
+password</em></span></span></p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="signature-api"></a>Digital Signatures and Signed Cookies</h4></div></div><div></div></div><p>
<span class="strong">ad_sign <span class="emphasis"><em>value</em></span></span> Returns the digital signature of this
value. Optional parameters allow for the specification of the <span class="emphasis"><em>secret</em></span>
used, the <span class="emphasis"><em>token_id</em></span> used and the <span class="emphasis"><em>max_age</em></span> for the signature.
@@ -250,17 +249,17 @@
<span class="strong">ad_set_signed_cookie <span class="emphasis"><em>name</em></span> <span class="emphasis"><em>data</em></span></span> Sets a
signed cookie <span class="emphasis"><em>name</em></span> with value <span class="emphasis"><em>data</em></span>. </p><p><span class="strong">ad_get_signed_cookie <span class="emphasis"><em>name</em></span></span> Gets the signed cookie
<span class="emphasis"><em>name</em></span>. It raises an error if the cookie has been tampered with, or if
-its expiration time has passed.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="session-property-api"></a>Session Properties</h4></div></div><p><span class="strong">ad_set_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span>
+its expiration time has passed.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="session-property-api"></a>Session Properties</h4></div></div><div></div></div><p><span class="strong">ad_set_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span>
<span class="emphasis"><em>data</em></span></span> Sets a session property with <span class="emphasis"><em>name</em></span> to value
<span class="emphasis"><em>data</em></span> for the module <span class="emphasis"><em>module</em></span>. The optional secure flag
specifies the property should only be set if the client is authorized for
-secure access (<tt>ad_secure_conn_p</tt> is true). There is also an optional
+secure access (<tt class="computeroutput">ad_secure_conn_p</tt> is true). There is also an optional
<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p><p><span class="strong">ad_get_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span>
<span class="emphasis"><em>data</em></span></span> Gets a session property with <span class="emphasis"><em>name</em></span> to for the
module <span class="emphasis"><em>module</em></span>. The optional secure flag specifies the property
should only be retrieved if the client is authorized for secure access
-(<tt>ad_secure_conn_p</tt> is true). There is also an optional
-<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="parameters"></a>Parameters</h4></div></div><p>
+(<tt class="computeroutput">ad_secure_conn_p</tt> is true). There is also an optional
+<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="parameters"></a>Parameters</h4></div></div><div></div></div><p>
<span class="strong">SessionTimeout</span> the maximum time in seconds (default 1200)
between requests that are part of the same session </p><p><span class="strong">SessionRenew</span> the time in seconds (default 300) between
reissue of the session cookie. The minimum time that can pass after a session
@@ -269,30 +268,30 @@
set on a single page even if there are multiple images that are being
downloaded.</p><p><span class="strong">SessionLifetime</span> the maximum possible lifetime of a
session in seconds (default 604800 = 7 days)</p><p><span class="strong">NumberOfCachedSecretTokens</span> the number of secret tokens to
-cache. (default 100)</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-design-future"></a>Future Improvements</h3></div></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="PRNG-impl"></a>PRNG implementation</h4></div></div><p>
+cache. (default 100)</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-future"></a>Future Improvements</h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="PRNG-impl"></a>PRNG implementation</h4></div></div><div></div></div><p>
The pseudorandom number generator used in the OpenACS is cryptographically weak,
-and depends primarily on the randomness of the <tt>ns_rand</tt> function
+and depends primarily on the randomness of the <tt class="computeroutput">ns_rand</tt> function
for its randomness. The implementation of the PRNG could be substantially
improved.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="ad_user_login"></a><tt>ad_user_login</tt></h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ad_user_login"></a><tt class="computeroutput">ad_user_login</tt></h4></div></div><div></div></div><p>
Add a password argument. It is non-optimal to make the default behavior to
assume that the password was provided.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="secret-tokens"></a>Secret Tokens</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="secret-tokens"></a>Secret Tokens</h4></div></div><div></div></div><p>
The secret tokens pool is currently static. Ideally, this pool should be
changed on a random but regular basis, and the number of secret_tokens
increased as the number of users come to the web site.
</p><p>Since the security of the entire system depends on the secret tokens pool,
access to the secret tokens table should be restricted and accessible via a
strict PL/SQL API. This can be done by revoking standard SQL permissions on
the table for the AOLserver user and giving those permissions to a PL/SQL
-package.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="robots"></a>Robots</h4></div></div><p>
+package.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="robots"></a>Robots</h4></div></div><div></div></div><p>
Deferring session to creation until the second hit from a browser seems to be
a good way of preventing a lot of overhead processing for robots. If we do
this, send cookie on first hit to test if cookies are accepted, then actually
allocate on second hit. To preserve a record of the first hit of the session,
just include any info about that first hit in the probe cookie sent. Look at
how usca_p (user session cookie attempted) is used in OpenACS 3.x ecommerce.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="client-property-future"></a>Client properties</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="client-property-future"></a>Client properties</h4></div></div><div></div></div><p>
Currently there are only session properties. Because sessions have a maximum
life, properties have a maximum life. It would be nice to expand the
interface to allow for more persistent properties. In the past, there was a
@@ -305,7 +304,7 @@
can be shared between concurrent sessions). The applications should have
control over the deletion patterns, but should not be able to ignore the
amount of data stored.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="session-information"></a>Session information</h4></div></div><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="session-information"></a>Session information</h4></div></div><div></div></div><p>
It would be nice to keep some info about sessions: first hit, last hit, and
URLs visited come to mind. Both logging and API for accessing this info would
be nice. WimpyPoint is an application that already wants to use this
@@ -314,7 +313,7 @@
analyzers (leaving it in server memory for applications to access). Putting
it into the database at all is probably too big a hammer. Certainly putting
it into the database on every hit is too big a hammer.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="cookieless-sessions"></a>Cookieless Sessions</h4></div></div><p>Two trends drive the requirement for removing cookie dependence. WAP
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cookieless-sessions"></a>Cookieless Sessions</h4></div></div><div></div></div><p>Two trends drive the requirement for removing cookie dependence. WAP
browsers that do not have cookies, and publc perceptions of cookies as an
invasion of privacy. The rely on the cookies mechanism in HTTP to distinguish
one request from the next, and we trust it to force requests from the same
@@ -333,21 +332,21 @@
Both of these problems can be mitigated by doing detection of cookie support
(see the section on robot detection). To help deal with the first problem, One
could also make the restriction that secure sessions are only allowed over
-cookied HTTP.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-design-vulnerability"></a>Vulnerability Analysis</h3></div></div><p>
+cookied HTTP.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-vulnerability"></a>Vulnerability Analysis</h3></div></div><div></div></div><p>
This section is not meant to be a comprehensive analysis of the
vulnerabilities of the security system. Listed below are possible attack
points for the system; these vulnerabilities are currently theoretical in
nature. The major cryptographic vulnerability of the system stems from the
pseudorandom nature of the random number generators used in the system.
</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">Cryptographically weak PRNG</span> see
-above.</p></li><li><p><span class="strong">Dependence on <tt>sample</tt>
+above.</p></li><li><p><span class="strong">Dependence on <tt class="computeroutput">sample</tt>
SQL command</span> The list of random token that are placed in the secret
tokens cache is randomly chosen by the Oracle
-<tt>sample</tt> command. This command may not be
+<tt class="computeroutput">sample</tt> 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.</p></li><li><p><span class="strong">Dependence on
-<tt>ns_rand</tt></span> The actual token that is
+<tt class="computeroutput">ns_rand</tt></span> The actual token that is
chosen from the cache to be used is chosen by a call to
-<tt>ns_rand</tt>.</p></li><li><p><span class="strong"><tt>ad_secure_conn_p</tt></span>
+<tt class="computeroutput">ns_rand</tt>.</p></li><li><p><span class="strong"><tt class="computeroutput">ad_secure_conn_p</tt></span>
As discussed above, the security of the secure sessions authentication system is
dependent upon this function.</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Security Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Security Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/security-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/security-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/security-notes.html 20 Aug 2003 16:20:17 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/security-notes.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,13 +1,12 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Security Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="security-design.html" title="OpenACS 4 Security Design"><link rel="next" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="security-notes"></a>OpenACS 4 Security Notes</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Security Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="security-design.html" title="OpenACS 4 Security Design"><link rel="next" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-notes"></a>OpenACS 4 Security Notes</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p>
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.
-</p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-notes-https-sessions"></a>HTTPS and the sessions system</h3></div></div><p>
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-notes-https-sessions"></a>HTTPS and the sessions system</h3></div></div><div></div></div><p>
If a user switches to HTTPS after logging into the system via HTTP, the user
must obtain a secure token. To insure security, the <span class="emphasis"><em>only way</em></span> to
@@ -22,21 +21,21 @@
issues a secure token, the method of authentication must be as strong as the
method of transmission.</p><p>If a developer truly does not want such a level of protection, this system
can be disabled via source code modification only. This can be accomplished
-by commenting out the following lines in the <tt>sec_handler</tt>
-procedure defined in <tt>security-procs.tcl</tt>:</p><pre class="programlisting">
+by commenting out the following lines in the <tt class="computeroutput">sec_handler</tt>
+procedure defined in <tt class="computeroutput">security-procs.tcl</tt>:</p><pre class="programlisting">
if { [ad_secure_conn_p] && ![ad_login_page] } {
- set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]]
+ set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]]
if { [empty_string_p $s_token_cookie] || [string compare $s_token_cookie [lindex [sec_get_session_info $session_id] 2]] != 0 } {
# token is incorrect or nonexistent, so we force relogin.
- ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]"
+ ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]"
}
}
</pre><p>The source code must also be edited if the user login pages have been
moved out of an OpenACS system. This information is contained by the
-<tt>ad_login_page</tt> procedure in <tt>security-procs.tcl</tt>:</p><pre class="programlisting">
+<tt class="computeroutput">ad_login_page</tt> procedure in <tt class="computeroutput">security-procs.tcl</tt>:</p><pre class="programlisting">
ad_proc -private ad_login_page {} {
@@ -45,7 +44,7 @@
} {
set url [ad_conn url]
- if { [string match "*register/*" $url] || [string match "/index*" $url] } {
+ if { [string match "*register/*" $url] || [string match "/index*" $url] } {
return 1
}
@@ -55,5 +54,5 @@
</pre><p>
The set of string match expressions in the procedure above should be extended
appropriately for other registration pages. This procedure does not use
-<tt>ad_parameter</tt> or regular expressions for performance reasons, as
+<tt class="computeroutput">ad_parameter</tt> or regular expressions for performance reasons, as
it is called by the request processor. </p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Security Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Request Processor Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/security-notes.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/security-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/security-requirements.html 20 Aug 2003 16:20:17 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html 14 Oct 2003 11:02:59 -0000 1.12
@@ -1,19 +1,18 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Security Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="i18n.html" title="Internationalization"><link rel="next" href="security-design.html" title="OpenACS 4 Security Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="security-requirements"></a>OpenACS 4 Security Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Security Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="i18n.html" title="Internationalization"><link rel="next" href="security-design.html" title="OpenACS 4 Security Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-requirements"></a>OpenACS 4 Security Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-requirements-intro"></a>Introduction</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-intro"></a>Introduction</h3></div></div><div></div></div><p>
This document lists the requirements for the security system for the OpenACS.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-requirements-vision"></a>Vision Statement</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>
Virtually all web sites support personalized content based on user identity.
The level of personalization may be as simple as displaying the name of the
user on certain pages or can be as sophisticated as dynamically recommending
sections of site that the user may be interested in based on prior browsing
history. In any case, the user's identity must be validated and made
available to the rest of the system. In addition, sites such as ecommerce
vendors require that the user identity be securely validated.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="security-requirements-system-overview"></a>Security System Overview</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-system-overview"></a>Security System Overview</h3></div></div><div></div></div><p>
The security system consists of a number of subsystems.
</p><p><span class="strong">Signed Cookies</span></p><p>
Cookies play a key role in storing user information. However, since they are
Index: openacs-4/packages/acs-core-docs/www/software-versions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/software-versions.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/software-versions.html 20 Aug 2003 16:20:17 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/software-versions.html 14 Oct 2003 11:02:59 -0000 1.5
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�3.�Prerequisite Software</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="quick.html" title="Chapter�2.�Quick Install"><link rel="next" href="compatibility-matrix.html" title="Compatibility Matrix"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="quick.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="compatibility-matrix.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="software-versions"></a>Chapter�3.�Prerequisite Software</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="compatibility-matrix.html">Compatibility Matrix</a></dt><dt><a href="individual-programs.html">Individual Programs</a></dt></dl></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�3.�Prerequisite Software</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="quick.html" title="Chapter�2.�Quick Install"><link rel="next" href="compatibility-matrix.html" title="Compatibility Matrix"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="quick.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="compatibility-matrix.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="software-versions"></a>Chapter�3.�Prerequisite Software</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="compatibility-matrix.html">Compatibility Matrix</a></dt><dt><a href="individual-programs.html">Individual Programs</a></dt></dl></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/subsites-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/subsites-design.html 20 Aug 2003 16:20:17 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/subsites-design.html 14 Oct 2003 11:02:59 -0000 1.12
@@ -1,11 +1,10 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Subsites Design Document</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements"><link rel="next" href="apm-requirements.html" title="OpenACS 5.0.0d Package Manager Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="subsites-design"></a>OpenACS 4 Subsites Design Document</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Subsites Design Document</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements"><link rel="next" href="apm-requirements.html" title="OpenACS 5.0.0a1 Package Manager Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites-design"></a>OpenACS 4 Subsites Design Document</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p><span class="emphasis"><em>*Note* This document has not gone through the any of the
required QA process yet. It is being tagged as stable due to high
-demand.</em></span></p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-intro"></a>Introduction</h3></div></div><p>An OpenACS 4 subsite is a managed suite of applications that work together for
+demand.</em></span></p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-essentials"></a>Essentials</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-intro"></a>Introduction</h3></div></div><div></div></div><p>An OpenACS 4 subsite is a managed suite of applications that work together for
a particular user community. This definition covers a very broad range of
requirements: from a Geocities style homepage where a user can install
whatever available application he wants (e.g. a single user could have their
@@ -18,35 +17,35 @@
the Request Processor. Since the design and implementation directly
associated with subsites is actually minimal, a discussion of subsites design
is, in fact, a discussion of how core OpenACS 4 components implicitly support
-subsites as a whole.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-hist-considerations"></a>Historical Considerations</h3></div></div><p>The subsites problem actually has several quite diverse origins. It was
+subsites as a whole.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-hist-considerations"></a>Historical Considerations</h3></div></div><div></div></div><p>The subsites problem actually has several quite diverse origins. It was
originally recognized as a toolkit feature in the form of
-"scoping". The basic concept behind scoping was to allow one scoped
+"scoping". The basic concept behind scoping was to allow one scoped
OpenACS installation to behave as multiple unscoped OpenACS installations so that one
OpenACS install could serve multiple communities. Each piece of application data
-was tagged with a "scope" consisting of the (user_id, group_id,
+was tagged with a "scope" consisting of the (user_id, group_id,
scope) triple. In practice the highly denormalized data models that this
method uses produced large amounts of very redundant code and in general made
-it an extremely cumbersome process to "scopify" a module.</p><p>Before the advent of scoping there were several cases of client projects
+it an extremely cumbersome process to "scopify" a module.</p><p>Before the advent of scoping there were several cases of client projects
implementing their own version of scoping in special cases. One example being
the wineaccess multi-retailer ecommerce. (Remember the other examples and get
details. Archnet?, iluvcamp?)</p><p>The requirements of all these different projects vary greatly, but the one
consistent theme among all of them is the concept that various areas of the
web site have their own private version of a module. Because this theme is so
dominant, this is the primary problem that the OpenACS4 implementation of
-subsites addresses.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-competitors"></a>Competitive Analysis</h3></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>The current implementation of package instances and subsites allows
+subsites addresses.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-competitors"></a>Competitive Analysis</h3></div></div><div></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><div></div></div><p>The current implementation of package instances and subsites allows
extremely flexible URL configurations. This has the benefit of allowing
multiple instances of the same package to be installed in one subsite, but
can potentially complicate the process of integrating packages with each
other since it is likely people will want packages that live at non standard
URLs to operate together. This requirement would cause some packages to have
more configuration options than normal since hard-coding the URLs would not
-be feasible anymore.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-api"></a>API</h3></div></div><p>This section will cover all the APIs relevant to subsites, and so will
+be feasible anymore.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-api"></a>API</h3></div></div><div></div></div><p>This section will cover all the APIs relevant to subsites, and so will
consist of portions of the APIs of several systems.</p><p><span class="strong">Packages</span></p><p>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)</p><pre class="programlisting">
-<tt>create or replace package apm_package
+<tt class="computeroutput">create or replace package apm_package
as
function new (
@@ -111,7 +110,7 @@
node URL. The object_id column contains the object mounted on the URL
represented by the node. In most cases this will be a package instance.</p><pre class="programlisting">
-<tt>create table site_nodes (
+<tt class="computeroutput">create table site_nodes (
node_id constraint site_nodes_node_id_fk
references acs_objects (object_id)
constraint site_nodes_node_id_pk
@@ -139,7 +138,7 @@
</pre><p>The following package is provided for creating nodes.</p><pre class="programlisting">
-<tt>create or replace package site_node
+<tt class="computeroutput">create or replace package site_node
as
-- Create a new site node. If you set directory_p to be 'f' then you
@@ -186,28 +185,28 @@
specific site node, the following request processor APIs can be used to allow
the package to serve content appropriate to the package instance.</p><pre class="programlisting">
-<tt>[ad_conn node_id]
+<tt class="computeroutput">[ad_conn node_id]
[ad_conn package_id]
[ad_conn package_url]
</tt>
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-data-model"></a>Data Model Discussion</h3></div></div><p>The subsites implementation doesn't really have it's own data
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-data-model"></a>Data Model Discussion</h3></div></div><div></div></div><p>The subsites implementation doesn't really have it's own data
model, although it depends heavily on the site-nodes data model, and the APM
-data model.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-ui"></a>User Interface</h3></div></div><p>The primary elements of the subsite user interface consist of the subsite
+data model.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-ui"></a>User Interface</h3></div></div><div></div></div><p>The primary elements of the subsite user interface consist of the subsite
admin pages. These pages are divided up into two areas: Group administration,
and the site map. The group administration pages allow a subsite
administrator to create and modify groups. The site map pages allow a subsite
administrator to install, remove, configure, and control access to packages.
The site map interface is the primary point of entry for most of the things a
-subsite administrator would want to do.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-config"></a>Configuration/Parameters</h3></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>The current subsites implementation addresses the most basic functionality
+subsite administrator would want to do.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-config"></a>Configuration/Parameters</h3></div></div><div></div></div><p>...</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><div></div></div><p>The current subsites implementation addresses the most basic functionality
required for subsites. It is likely that as developers begin to use the
subsites system for more sophisticated projects, it will become necessary to
develop tools to help build tightly integrated packages. The general area
-this falls under is "inter-package communication". An actual
+this falls under is "inter-package communication". An actual
implementation of this could be anything from clever use of configuration
parameters to lots of package level introspection. Another area that is
-currently underdeveloped is the ability to "tar up" and distribute
+currently underdeveloped is the ability to "tar up" and distribute
a particular configuration of site nodes/packages. As we build more
fundamental applications that can be applied in more general areas, this
feature will become more and more in demand since more problems will be
-solvable by configuration instead of coding.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-authors"></a>Authors</h3></div></div><p><a href="mailto:rhs@mit.edu" target="_top">rhs@mit.edu</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Subsites Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 5.0.0d Package Manager Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/subsites-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
+solvable by configuration instead of coding.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-authors"></a>Authors</h3></div></div><div></div></div><p><a href="mailto:rhs@mit.edu" target="_top">rhs@mit.edu</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Subsites Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 5.0.0a1 Package Manager Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/subsites-design.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 20 Aug 2003 16:20:17 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 14 Oct 2003 11:02:59 -0000 1.12
@@ -1,32 +1,31 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Subsites Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="groups-design.html" title="OpenACS 4 Groups Design"><link rel="next" href="subsites-design.html" title="OpenACS 4 Subsites Design Document"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="subsites-requirements"></a>OpenACS 4 Subsites Requirements</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS 4 Subsites Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="groups-design.html" title="OpenACS 4 Groups Design"><link rel="next" href="subsites-design.html" title="OpenACS 4 Subsites Design Document"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites-requirements"></a>OpenACS 4 Subsites Requirements</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a> and <a href="mailto:dennis@arsdigita.com" target="_top">Dennis Gregorovic</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-intro"></a>Introduction</h3></div></div><p>The following is a requirements document for OpenACS 4 Subsites, part of the
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-intro"></a>Introduction</h3></div></div><div></div></div><p>The following is a requirements document for OpenACS 4 Subsites, part of the
OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve
multiple user communities, by enabling the suite of available OpenACS
-applications to be customized for defined user communities.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-vision"></a>Vision Statement</h3></div></div><p>Many online communities are also collections of discrete subcommunities,
+applications to be customized for defined user communities.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-vision"></a>Vision Statement</h3></div></div><div></div></div><p>Many online communities are also collections of discrete subcommunities,
reflecting real-world relationships. For example, a corporate
intranet/extranet website serves both units within the company (e.g.,
offices, departments, teams, projects) and external parties (e.g., customers,
partners, vendors). Subsites enable a single OpenACS instance to provide each
-subcommunity with its own "virtual website," by assembling OpenACS
+subcommunity with its own "virtual website," by assembling OpenACS
packages that together deliver a feature set tailored to the needs of the
-subcommunity.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-system-overview"></a>System Overview</h3></div></div><p>The OpenACS subsite system allows a single OpenACS installation to serve multiple
+subcommunity.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-system-overview"></a>System Overview</h3></div></div><div></div></div><p>The OpenACS subsite system allows a single OpenACS installation to serve multiple
communities. At an implementation level this is primarily accomplished by
-having an application "scope" its content to a particular package
+having an application "scope" its content to a particular package
instance. The <a href="rp-design.html" title="OpenACS 4 Request Processor Design">request
processor</a> then figures out which package_id a particular URL references
-and then provides this information through the <tt>ad_conn</tt> api (<tt>[ad_conn
-package_id]</tt>, <tt>[ad_conn package_url]</tt>).</p><p>The other piece of the subsite system is a subsite package that provides
-subsite admins a "control panel" for administering their subsite.
+and then provides this information through the <tt class="computeroutput">ad_conn</tt> api (<tt class="computeroutput">[ad_conn
+package_id]</tt>, <tt class="computeroutput">[ad_conn package_url]</tt>).</p><p>The other piece of the subsite system is a subsite package that provides
+subsite admins a "control panel" for administering their subsite.
This is the same package used to provide all the community core functionality
-available at the "main" site which is in fact simply another
-subsite.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><p>The Subsites functionality is intended for use by two different classes of
+available at the "main" site which is in fact simply another
+subsite.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><div></div></div><p>The Subsites functionality is intended for use by two different classes of
users:</p><div class="orderedlist"><ol type="1"><li><p>Package programmers (referred to as 'the programmer') must
develop subcommunity-aware applications.</p></li><li><p>Site administrators (referred to as 'the administrator') use
-subsites to provide tailored "virtual websites" to different
+subsites to provide tailored "virtual websites" to different
subcommunities.</p></li></ol></div><p>Joe Programmer is working on the bboard package and wants to make it
subsite-aware. Using [ad_conn package_id], Joe adds code that only displays
bboard messages associated with the current package instance. Joe is happy to
@@ -41,18 +40,18 @@
http://www.company.com/offices/boston/bboard, and similarly for the Austin
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.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></p></li><li><p>Test plan (Not available yet)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-api"></a>Requirements: Programmer's API</h3></div></div><p>A subsite API is required for programmers to ensure their packages are
+defaults.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-links"></a>Related Links</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></p></li><li><p>Test plan (Not available yet)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-api"></a>Requirements: Programmer's API</h3></div></div><div></div></div><p>A subsite API is required for programmers to ensure their packages are
subsite-aware. The following functions should be sufficient for this:</p><p><span class="strong">10.10.0 Package creation</span></p><p>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.</p><p><span class="strong">10.20.0 Package deletion</span></p><p>The system must provide an API call to delete a package and all related
objects in the subsite's context.</p><p><span class="strong">10.30.0 Object's package information</span></p><p>Given an object ID, the system must provide an API call to determine the
package (ID) to which the object belongs.</p><p><span class="strong">10.40.0 URL from package</span></p><p>Given a package (ID), the system must provide an API call to return the
canonical URL for that package.</p><p><span class="strong">10.50.0 Main subsite's package_id</span></p><p>The system must provide an API call to return a package ID corresponding
-to the main subsite's package ID (the degenerate subsite).</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-ui"></a>Requirements: The User Interface</h3></div></div><p><span class="strong">The Programmer's User Interface</span></p><p>There is no programmer's UI, other than the API described above.</p><p><span class="strong">The Administrator's User Interface</span></p><p>The UI for administrators is a set of HTML pages that are used to drive
+to the main subsite's package ID (the degenerate subsite).</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-ui"></a>Requirements: The User Interface</h3></div></div><div></div></div><p><span class="strong">The Programmer's User Interface</span></p><p>There is no programmer's UI, other than the API described above.</p><p><span class="strong">The Administrator's User Interface</span></p><p>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.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">20.10.0 Package creation</span></p><p><span class="strong">20.10.1</span> The administrator should be able to create a
package and make it available at a URL underneath the subsite.</p></li><li><p><span class="strong">20.20.0 Package deactivation</span></p><p><span class="strong">20.20.1</span> The administrator should be able to deactivate
any package, causing it to be inaccessible to users.</p><p><span class="strong">20.20.5</span> Deactivating a package makes the package no
longer accessible, but it does not remove data created within the context of
-that package.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/18/2000</td><td>Dennis Gregorovic</td></tr><tr><td>0.2</td><td>Edited, reviewed</td><td>08/29/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Groups Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Subsites Design Document</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/subsites-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
+that package.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-rev-history"></a>Revision History</h3></div></div><div></div></div><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong">Document Revision #</span></td><td><span class="strong">Action Taken, Notes</span></td><td><span class="strong">When?</span></td><td><span class="strong">By Whom?</span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/18/2000</td><td>Dennis Gregorovic</td></tr><tr><td>0.2</td><td>Edited, reviewed</td><td>08/29/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Groups Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Subsites Design Document</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/subsites-requirements.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/subsites.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/subsites.html 20 Aug 2003 16:20:17 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/subsites.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,22 +1,21 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Writing OpenACS 5.0.0d Application Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="permissions.html" title="Groups, Context, Permissions"><link rel="next" href="parties.html" title="Parties in OpenACS 5.0.0d"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="subsites"></a>Writing OpenACS 5.0.0d Application Pages</h2></div></div><div class="authorblurb"><p><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Writing OpenACS 5.0.0a1 Application Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="permissions.html" title="Groups, Context, Permissions"><link rel="next" href="parties.html" title="Parties in OpenACS 5.0.0a1"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites"></a>Writing OpenACS 5.0.0a1 Application Pages</h2></div></div><div></div></div><div class="authorblurb"><p><p>
By <a href="http://planitia.org/" target="_top">Rafael H. Schloming</a>
and <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
</p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-overview"></a>Overview</h3></div></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-overview"></a>Overview</h3></div></div><div></div></div><p>
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 5.0.0d. First, we'll talk about the code needed to make
+development in OpenACS 5.0.0a1. 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 5.0.0d. While these seem like unrelated
+form-based user interfaces in OpenACS 5.0.0a1. 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.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-instances"></a>Application Instances and Subsites</h3></div></div><p>
-As you will recall from the <a href="packages.html" title="OpenACS 5.0.0d Packages">packages</a> tutorial, the Request
-Processor (RP) and Package Manager (APM) in OpenACS 5.0.0d allow site
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-instances"></a>Application Instances and Subsites</h3></div></div><div></div></div><p>
+As you will recall from the <a href="packages.html" title="OpenACS 5.0.0a1 Packages">packages</a> tutorial, the Request
+Processor (RP) and Package Manager (APM) in OpenACS 5.0.0a1 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
@@ -25,63 +24,63 @@
particular URL. The tutorial also showed how a given URL is
translated into a physical file to serve using the site map. We'll
repeat this description here, assuming that you have mounted an
-instance of Notes at the URL <tt>/notes</tt> as we did in the <a href="packages.html#packages-looks" title="What a Package Looks Like">packages-example</a>:
+instance of Notes at the URL <tt class="computeroutput">/notes</tt> as we did in the <a href="packages.html#packages-looks" title="What a Package Looks Like">packages-example</a>:
</p><div class="itemizedlist"><ul type="disc"><li><p>
-AOLserver receives your request for the URL <tt>/notes/somepage</tt>.
+AOLserver receives your request for the URL <tt class="computeroutput">/notes/somepage</tt>.
</p></li><li><p>
This URL is passed to the request processor.
</p></li><li><p>
The RP looks up the URL in the site map, and sees that the object
-mounted at that location is an instance of the <tt>notes</tt>
+mounted at that location is an instance of the <tt class="computeroutput">notes</tt>
application.
</p></li><li><p>
The RP asks the package manager where in the file system the Notes
package lives. In the standard case, this would be
-<tt>ROOT/packages/notes</tt>.
+<tt class="computeroutput">ROOT/packages/notes</tt>.
</p></li><li><p>
The RP translates the URL to serve a page relative to the page root of
the application, which is
-<tt>ROOT/packages/notes/www/</tt>. Therefore, the page that is
-finally served is <tt>ROOT/packages/notes/www/hello.html</tt>,
+<tt class="computeroutput">ROOT/packages/notes/www/</tt>. Therefore, the page that is
+finally served is <tt class="computeroutput">ROOT/packages/notes/www/hello.html</tt>,
which is what we wanted.
</p></li></ul></div><p>
What is missing from this description is a critical fact for
application developers: In addition to working out what file to serve,
the RP also stores information about which package instance the file
belongs to into the AOLserver connection environment. The following
-<tt>ad_conn</tt> interfaces can be used to extract this
+<tt class="computeroutput">ad_conn</tt> interfaces can be used to extract this
information:
-</p><div class="variablelist"><dl><dt><span class="term"><tt>[ad_conn package_url]</tt></span></dt><dd><p>
+</p><div class="variablelist"><dl><dt><span class="term"><tt class="computeroutput">[ad_conn package_url]</tt></span></dt><dd><p>
If the URL refers to a package instance, this is the URL to the root
of the tree where the package is mounted.
-</p></dd><dt><span class="term"><tt>[ad_conn package_id]</tt></span></dt><dd><p>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn package_id]</tt></span></dt><dd><p>
If the URL refers to a package instance, this is the ID of that
package instance.
-</p></dd><dt><span class="term"><tt>[ad_conn package_key]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn package_key]</tt>
</span></dt><dd><p>
If the URL refers to a package instance, this is the unique key name
of the package.
-</p></dd><dt><span class="term"><tt>[ad_conn extra_url]</tt>
+</p></dd><dt><span class="term"><tt class="computeroutput">[ad_conn extra_url]</tt>
</span></dt><dd><p>
If we found the URL in the site map, this is the tail of the URL
following the part that matched a site map entry.
</p></dd></dl></div><p>
In the Notes example, we are particularly interested in the
-<tt>package_id</tt> field. If you study the data model and code,
+<tt class="computeroutput">package_id</tt> field. If you study the data model and code,
you'll see why. As we said before in the <a href="objects.html" title="OpenACS Data Models and the Object System">data modeling</a> tutorial, the Notes application points the
-<tt>context_id</tt> of each Note object that it creates to the
-package instance that created it. That is, the <tt>context_id</tt>
-corresponds exactly to the <tt>package_id</tt> that comes in from
+<tt class="computeroutput">context_id</tt> of each Note object that it creates to the
+package instance that created it. That is, the <tt class="computeroutput">context_id</tt>
+corresponds exactly to the <tt class="computeroutput">package_id</tt> that comes in from
the RP. This is convenient because it allows the administrator and the
owner of the package to easily define access control policies for all
the notes in a particular instance just my setting permissions on the
package instance itself.
</p><p>
The code for adding and editing notes, in
-<tt>notes/www/add-edit.tcl</tt>, shows how this works. At the top
-of the page, we extract the <tt>package_id</tt> and use it to do
+<tt class="computeroutput">notes/www/add-edit.tcl</tt>, shows how this works. At the top
+of the page, we extract the <tt class="computeroutput">package_id</tt> and use it to do
permission checks:
</p><pre class="programlisting">
@@ -90,11 +89,11 @@
if {[info exists note_id]} {
ad_require_permission $note_id write
- set context_bar [ad_context_bar "Edit Note"]
+ set context_bar [ad_context_bar "Edit Note"]
} else {
ad_require_permission $package_id create
- set context_bar [ad_context_bar "New Note"]
+ set context_bar [ad_context_bar "New Note"]
}
</pre><p>
@@ -103,7 +102,7 @@
for each action.
</p><p>
Later, when we actually create a note, the SQL that we run ensures
-that the <tt>context_id</tt> is set the right way:
+that the <tt class="computeroutput">context_id</tt> is set the right way:
</p><pre class="programlisting">
db_dml new_note {
@@ -127,25 +126,25 @@
without generating a lot of duplicated HTML in your pages. It also
encapsulates most of the common logic that we use in dealing with
forms, which we'll discuss next.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-using-forms"></a>Using Forms</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-using-forms"></a>Using Forms</h3></div></div><div></div></div><p>
The forms API is pretty simple: You use calls in the
-<tt>template::form</tt> namespace in your Tcl script to create
+<tt class="computeroutput">template::form</tt> namespace in your Tcl script to create
form elements. The final template page then picks this stuff up and
lays the form out for the user. The form is set up to route submit
buttons and whatnot back to the same Tcl script that set up the
form, so your Tcl script will also contain the logic needed to process
these requests.
</p><p>
So, given this outline, here is a breakdown of how the forms code
-works in the <tt>add-edit.tcl</tt> page. First, we create a form object
-called <tt>new_note</tt>:
+works in the <tt class="computeroutput">add-edit.tcl</tt> page. First, we create a form object
+called <tt class="computeroutput">new_note</tt>:
</p><pre class="programlisting">
template::form create new_note
</pre><p>
All the forms related code in this page will refer back to this
-object. In addition, the <tt>adp</tt> part of this page does
+object. In addition, the <tt class="computeroutput">adp</tt> part of this page does
nothing but display the form object:
</p><pre class="programlisting">
@@ -156,7 +155,7 @@
<hr>
<center>
-<formtemplate id="new_note"></formtemplate>
+<formtemplate id="new_note"></formtemplate>
</center>
</pre><p>
@@ -179,9 +178,9 @@
}
</pre><p>
-The <tt>if_request</tt> call returns true if we are asking the
+The <tt class="computeroutput">if_request</tt> call returns true if we are asking the
page to render the form for the first time. That is, we are rendering
-the form to ask the user for input. The <tt>tcl</tt> part of a
+the form to ask the user for input. The <tt class="computeroutput">tcl</tt> part of a
form page can be called in 3 different states: the initial request,
the initial submission, and the validated submission. These states
reflect the typical logic of a forms based page in OpenACS:
@@ -194,16 +193,16 @@
Finally, control passes to the page that performs the update in the
database.
</p></li></ul></div><p>
-The rest of the <tt>if</tt> condition figures out if we are
+The rest of the <tt class="computeroutput">if</tt> condition figures out if we are
creating a new note or editing an existing note. If
-<tt>note_id</tt> is passed to us from the calling page, we assume
+<tt class="computeroutput">note_id</tt> is passed to us from the calling page, we assume
that we are editing an existing note. In this case, we do a database
query to grab the data for the note so we can populate the form with
it.
</p><p>
The next two calls create form elements where the user can insert or
edit the title and body of the Note. The interface to
-<tt>template::element</tt> is pretty straightforward.
+<tt class="computeroutput">template::element</tt> is pretty straightforward.
</p><p>
Finally, the code at the bottom of the page performs the actual
database updates when the form is submitted and validated:
@@ -237,7 +236,7 @@
}
}
- ad_returnredirect "."
+ ad_returnredirect "."
}
</pre><p>
@@ -246,7 +245,7 @@
the HTML rendering, input validation and database transaction logic on
your behalf. This means that you can write pages without duplicating
all of that code in every set of pages that uses forms.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-how-it-all-fits"></a>How it All Fits</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-how-it-all-fits"></a>How it All Fits</h3></div></div><div></div></div><p>
To watch all of this work, use the installer to update the Notes
package with the new code that you grabbed out of CVS or the package
repository, mount an instance of Notes somewhere in your server and
@@ -257,15 +256,15 @@
visible to that user. The end result is a site where users can come
and write notes to themselves.
</p><p>
-This is a good example of the leverage available in the OpenACS 5.0.0d
+This is a good example of the leverage available in the OpenACS 5.0.0a1
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.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="subsites-summary"></a>Summary</h3></div></div><p>
-In OpenACS 5.0.0d, application pages and scripts can be aware of the package
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-summary"></a>Summary</h3></div></div><div></div></div><p>
+In OpenACS 5.0.0a1, 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,4 +276,4 @@
</p><p>
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.
-</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr><tr><td width="40%" align="left">Groups, Context, Permissions </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Parties in OpenACS 5.0.0d</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/subsites.html#comments">View comments on this page at openacs.org</a></center></body></html>
+</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr><tr><td width="40%" align="left">Groups, Context, Permissions </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Parties in OpenACS 5.0.0a1</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/subsites.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/tcl-doc.html 20 Aug 2003 16:20:17 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,10 +1,9 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Documenting Tcl Files: Page Contracts and Libraries</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Documenting Tcl Files: Page Contracts and Libraries</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter�13.�Kernel Documentation"><link rel="previous" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><th width="60%" align="center">Chapter�13.�Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> on 3 July 2000
<br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div><p>In versions of the OpenACS prior to 3.4, <a href="/doc/standards" target="_top">the standard
+ </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div><div></div></div><p>In versions of the OpenACS prior to 3.4, <a href="/doc/standards" target="_top">the standard
place</a> to document Tcl files (both Tcl pages and Tcl library files) was in
a comment at the top of the file:</p><pre class="programlisting">
#
@@ -18,44 +17,44 @@
#
</pre><p>
In addition, the inputs expected by a Tcl page (i.e., form variables) would
-be enumerated in a call to <tt>ad_page_variables</tt>, in effect,
+be enumerated in a call to <tt class="computeroutput">ad_page_variables</tt>, in effect,
documenting the page's argument list.
</p><p>The problem with these practices is that the documentation is only
accessible by reading the source file itself. For this reason, ACS 3.4
introduces a new API for documenting Tcl files and, on top of that, a
-web-based user interface for browsing the documentation:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><tt><a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></tt></span>: Every Tcl page
+web-based user interface for browsing the documentation:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><tt class="computeroutput"><a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></tt></span>: Every Tcl page
has a <span class="strong">contract</span> that explicitly defines what inputs the page
-expects (with more precision than <tt>ad_page_variables</tt>) and
+expects (with more precision than <tt class="computeroutput">ad_page_variables</tt>) and
incorporates metadata about the page (what used to live in the top-of-page
-comment). Like <tt>ad_page_variables</tt>, <tt>ad_page_contract</tt>
-also sets the specified variables in the context of the Tcl page.</p></li><li><p><span class="strong"><tt><a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library">ad_library</a></tt></span>: To be
+comment). Like <tt class="computeroutput">ad_page_variables</tt>, <tt class="computeroutput">ad_page_contract</tt>
+also sets the specified variables in the context of the Tcl page.</p></li><li><p><span class="strong"><tt class="computeroutput"><a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library">ad_library</a></tt></span>: To be
called at the top of every library file (i.e., all files in the
-<tt>/tcl/</tt> directory under the server root and
-<tt>*-procs.tcl</tt> files under <tt>/packages/</tt>).</p></li></ul></div><p>
+<tt class="computeroutput">/tcl/</tt> directory under the server root and
+<tt class="computeroutput">*-procs.tcl</tt> files under <tt class="computeroutput">/packages/</tt>).</p></li></ul></div><p>
This has the following benefits:
</p><div class="itemizedlist"><ul type="disc"><li><p>Facilitates automatic generation of human-readable documentation.</p></li><li><p>Promotes security, by introducing a standard and automated way to check
inputs to scripts for correctness.</p></li><li><p>Allows graphical designers to determine easily how to customize
sites' UIs, e.g., what properties are available in templates.</p></li><li><p>Allows the request processor to be intelligent: a script can specify in
its contract which type of abstract document it
returns, and the request processor can transform it automatically into
something useful to a particular user agent. (Don't worry about this for
-now - it's not complete for ACS 3.4.)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div><p>
-Currently <tt>ad_page_contract</tt> serves mostly as a replacement for
-<tt>ad_page_variables</tt>. Eventually, it will be integrated closely
+now - it's not complete for ACS 3.4.)</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div><div></div></div><p>
+Currently <tt class="computeroutput">ad_page_contract</tt> serves mostly as a replacement for
+<tt class="computeroutput">ad_page_variables</tt>. Eventually, it will be integrated closely
with the documents API so that each script's contract will document
precisely the set of properties available to graphical designers in
templates. (Document API integration is subject to change, so we don't
decsribe it here yet; for now, you can just consider
-<tt>ad_page_contract</tt> a newer, better, documented
-<tt>ad_page_variables</tt>.)
-</p><p>Let's look at an example usage of <tt>ad_page_contract</tt>:</p><pre class="programlisting">
+<tt class="computeroutput">ad_page_contract</tt> a newer, better, documented
+<tt class="computeroutput">ad_page_variables</tt>.)
+</p><p>Let's look at an example usage of <tt class="computeroutput">ad_page_contract</tt>:</p><pre class="programlisting">
# /packages/acs-kernel/api-doc/www/package-view.tcl
ad_page_contract {
version_id:integer
public_p:optional
kind
- { format "html" }
+ { format "html" }
} {
Shows APIs for a particular package.
@@ -73,83 +72,83 @@
</pre><p>
Note that:
-</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">By convention, <tt>ad_page_contract</tt> should be preceded
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong">By convention, <tt class="computeroutput">ad_page_contract</tt> should be preceded
by a comment line containing the file's path</span>. The comment is on
line 1, and the contract starts on line 2.
-</p></li><li><p><span class="strong"><tt>ad_page_contract</tt></span>'s first argument is
-the list of expected arguments from the HTTP query (<tt>version_id</tt>,
-<tt>public_p</tt>, <tt>kind</tt>, and <tt>format</tt>). Like
-<tt>ad_page_variables</tt>, <tt>ad_page_contract</tt> sets the
+</p></li><li><p><span class="strong"><tt class="computeroutput">ad_page_contract</tt></span>'s first argument is
+the list of expected arguments from the HTTP query (<tt class="computeroutput">version_id</tt>,
+<tt class="computeroutput">public_p</tt>, <tt class="computeroutput">kind</tt>, and <tt class="computeroutput">format</tt>). Like
+<tt class="computeroutput">ad_page_variables</tt>, <tt class="computeroutput">ad_page_contract</tt> sets the
corresponding Tcl variables when the page is executed.
</p></li><li><p><span class="strong">Arguments can have defaults</span>, specified using the same
-syntax as in the Tcl <tt>proc</tt> (a two-element list where the first
+syntax as in the Tcl <tt class="computeroutput">proc</tt> (a two-element list where the first
element is the parameter name and the second argument is the default value).
</p></li><li><p><span class="strong">Arguments can have flags</span>, specified by following the
name of the query argument with a colon and one or more of the following
-strings (separated by commas): </p><div class="itemizedlist"><ul type="circle"><li><p><span class="strong"><tt>optional</tt></span>: the query argument doesn't
+strings (separated by commas): </p><div class="itemizedlist"><ul type="circle"><li><p><span class="strong"><tt class="computeroutput">optional</tt></span>: the query argument doesn't
need to be provided; if it's not, the variable for that argument simply
won't be set. For instance, if I call the script above without a
-<tt>public_p</tt> in the query, then in the page body <tt>[info exists
+<tt class="computeroutput">public_p</tt> in the query, then in the page body <tt class="computeroutput">[info exists
public_p]</tt> will return 0.
-</p></li><li><p><span class="strong"><tt>integer</tt></span>: the argument must be an integer
-(<tt>ad_page_contract</tt> will fail and display and error if not). This
+</p></li><li><p><span class="strong"><tt class="computeroutput">integer</tt></span>: the argument must be an integer
+(<tt class="computeroutput">ad_page_contract</tt> will fail and display and error if not). This
flag, like the next, is intended to prevent clients from fudging query
arguments to trick scripts into executing arbitrary SQL.
-</p></li><li><p><span class="strong"><tt>sql_identifier</tt></span>: the argument must be a SQL
-identifier (i.e., <tt>[string is wordchar $the_query_var]</tt> must
+</p></li><li><p><span class="strong"><tt class="computeroutput">sql_identifier</tt></span>: the argument must be a SQL
+identifier (i.e., <tt class="computeroutput">[string is wordchar $the_query_var]</tt> must
return true).
-</p></li><li><p><span class="strong"><tt>trim</tt></span>: the argument will be [string
+</p></li><li><p><span class="strong"><tt class="computeroutput">trim</tt></span>: the argument will be [string
trim]'ed.
-</p></li><li><p><span class="strong"><tt>multiple</tt></span>: the argument may be specified
+</p></li><li><p><span class="strong"><tt class="computeroutput">multiple</tt></span>: the argument may be specified
arbitrarily many times in the query string, and the variable will be set to a
list of all those values (or an empty list if it's unspecified). This is
-analogous to the <tt>-multiple-list</tt> flag to
-<tt>ad_page_variables</tt>, and is useful for handling form input
-generated by <tt><SELECT MULTIPLE></tt> tags and checkboxes. </p><p>For instance, if <tt>dest_user_id:multiple</tt> is specified in the
+analogous to the <tt class="computeroutput">-multiple-list</tt> flag to
+<tt class="computeroutput">ad_page_variables</tt>, and is useful for handling form input
+generated by <tt class="computeroutput"><SELECT MULTIPLE></tt> tags and checkboxes. </p><p>For instance, if <tt class="computeroutput">dest_user_id:multiple</tt> is specified in the
contract, and the query string is</p><pre class="programlisting">
?dest_user_id=913&dest_user_id=891&dest_user_id=9
</pre><p>
-then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.
+then <tt class="computeroutput">$dest_user_id</tt> is set to <tt class="computeroutput">[list 913 891 9]</tt>.
-</p></li><li><p><span class="strong"><tt>array</tt></span>: the argument may be specified
+</p></li><li><p><span class="strong"><tt class="computeroutput">array</tt></span>: the argument may be specified
arbitrarily many times in the query string, with parameter names with
-suffixes like <tt>_1</tt>, <tt>_2</tt>, <tt>_3</tt>, etc. The
+suffixes like <tt class="computeroutput">_1</tt>, <tt class="computeroutput">_2</tt>, <tt class="computeroutput">_3</tt>, etc. The
variable is set to a list of all those values (or an empty list if none are
-specified). </p><p>For instance, if <tt>dest_user_id:array</tt> is specified in the
+specified). </p><p>For instance, if <tt class="computeroutput">dest_user_id:array</tt> is specified in the
contract, and the query string is</p><pre class="programlisting">
?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
</pre><p>
-then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.</p></li></ul></div></li><li><p><span class="strong">You can provide structured, HTML-formatted documentation for your
+then <tt class="computeroutput">$dest_user_id</tt> is set to <tt class="computeroutput">[list 913 891 9]</tt>.</p></li></ul></div></li><li><p><span class="strong">You can provide structured, HTML-formatted documentation for your
contract</span>. Note that format is derived heavily from Javadoc: a
general description of the script's functionality, followed optionally by
-a series of named attributes tagged by at symbols (<tt>@</tt>). You are
+a series of named attributes tagged by at symbols (<tt class="computeroutput">@</tt>). You are
encouraged to provide:
</p><div class="itemizedlist"><ul type="circle"><li><p>A description of the functionality of the page. If the description
contains more than one sentence, the first sentence should be a brief
summary.
-</p></li><li><p>A <span class="strong"><tt>@param</tt></span> tag for each allowable query
+</p></li><li><p>A <span class="strong"><tt class="computeroutput">@param</tt></span> tag for each allowable query
argument. The format is </p><pre class="programlisting">
@param <span class="emphasis"><em>parameter-name</em></span> <span class="emphasis"><em>description...</em></span>
-</pre></li><li><p>An <span class="strong"><tt>@author</tt></span> tag for each author. Specify the
-author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><tt>@creation-date</tt></span> tag indicating when the
-script was first created.</p></li><li><p>A <span class="strong"><tt>@cvs-id</tt></span> tag containing the page's CVS
-identification string. Just use <tt>$Id: tcl-documentation.html,v 1.2
+</pre></li><li><p>An <span class="strong"><tt class="computeroutput">@author</tt></span> tag for each author. Specify the
+author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><tt class="computeroutput">@creation-date</tt></span> tag indicating when the
+script was first created.</p></li><li><p>A <span class="strong"><tt class="computeroutput">@cvs-id</tt></span> tag containing the page's CVS
+identification string. Just use <tt class="computeroutput">$Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $</tt> when creating the file, and CVS will
substitute an appropriate string when you check the file in.</p></li></ul></div><p>
- These <tt>@</tt> tags are optional, but highly recommended!</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-ad-library"></a>ad_library</h3></div></div><p>
-<tt>ad_library</tt> provides a replacement for the informal documentation
+ These <tt class="computeroutput">@</tt> tags are optional, but highly recommended!</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-ad-library"></a>ad_library</h3></div></div><div></div></div><p>
+<tt class="computeroutput">ad_library</tt> provides a replacement for the informal documentation
(described above) found at the beginning of every Tcl page. Instead of:
</p><pre class="programlisting">
@@ -180,11 +179,11 @@
</pre><p>
Note that format is derived heavily from Javadoc: a general description of
the script's functionality, followed optionally by a series of named
-attributes tagged by at symbols (<tt>@</tt>). HTML formatting is allowed.
+attributes tagged by at symbols (<tt class="computeroutput">@</tt>). HTML formatting is allowed.
You are encouraged to provide:
-</p><div class="itemizedlist"><ul type="disc"><li><p>An <span class="strong"><tt>@author</tt></span> tag for each author. Specify the
-author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><tt>@creation-date</tt></span> tag indicating when the
-script was first created.</p></li><li><p>A <span class="strong"><tt>@cvs-id</tt></span> tag containing the page's CVS
-identification string. Just use <tt>$Id: tcl-documentation.html,v 1.2
+</p><div class="itemizedlist"><ul type="disc"><li><p>An <span class="strong"><tt class="computeroutput">@author</tt></span> tag for each author. Specify the
+author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><tt class="computeroutput">@creation-date</tt></span> tag indicating when the
+script was first created.</p></li><li><p>A <span class="strong"><tt class="computeroutput">@cvs-id</tt></span> tag containing the page's CVS
+identification string. Just use <tt class="computeroutput">$Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $</tt> when creating the file, and CVS will
substitute an appropriate string when you check the file in.</p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Request Processor Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Bootstrapping OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tcl-doc.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/templates.html 20 Aug 2003 16:20:17 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/templates.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,9 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using Templates in OpenACS 5.0.0d</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="db-api.html" title="The OpenACS Database Access API"><link rel="next" href="permissions.html" title="Groups, Context, Permissions"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="templates"></a>Using Templates in OpenACS 5.0.0d</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using Templates in OpenACS 5.0.0a1</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="db-api.html" title="The OpenACS Database Access API"><link rel="next" href="permissions.html" title="Groups, Context, Permissions"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="templates"></a>Using Templates in OpenACS 5.0.0a1</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="templates-overview"></a>Overview</h3></div></div><p>
-The OpenACS 5.0.0d Template System (ATS) is designed to allow developers to
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="templates-overview"></a>Overview</h3></div></div><div></div></div><p>
+The OpenACS 5.0.0a1 Template System (ATS) is designed to allow developers to
cleanly separate <span class="emphasis"><em>application logic</em></span> from <span class="emphasis"><em>display
logic</em></span>. The intent is to have all of the logic related to
manipulating the database and other application state data in one
@@ -13,12 +12,12 @@
graphic designers to work more independently.
</p><p>
In ATS, you write two files for every user-visible page in the
-system. One is a plain <tt>.tcl</tt> file and the other is a
-special <tt>.adp</tt> file. The <tt>.tcl</tt> file runs a
+system. One is a plain <tt class="computeroutput">.tcl</tt> file and the other is a
+special <tt class="computeroutput">.adp</tt> file. The <tt class="computeroutput">.tcl</tt> file runs a
script that sets up a set of name/value bindings that we call <span class="emphasis"><em>data
sources</em></span>. These <a href="/doc/acs-templating/guide/data.html" target="_top">data sources</a> are generally the results of Tcl and/or database queries
or some combination thereof. The template system automatically makes
-them available to the <tt>.adp</tt> file, or the display part of
+them available to the <tt class="computeroutput">.adp</tt> file, or the display part of
the template, which is written in a combination of HTML, special
template related tags, and data source substitutions.
</p><p>
@@ -29,7 +28,7 @@
actually add notes to the database, how to provide a separate instance
of the Notes application to every user and how to design appropriate
access control policies for the system.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="templates-entering-notes"></a>Entering Notes</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="templates-entering-notes"></a>Entering Notes</h3></div></div><div></div></div><p>
In order for the Notes application to be useful, we have to allow
users to enter data into the database. Typically, this takes two
pages: one that displays a form for data entry, and another page that
@@ -39,10 +38,10 @@
the system since we won't be displaying much data, but we'll cover
more on that end later.
</p><p>
-The <tt>.tcl</tt> file for the form entry template is pretty
+The <tt class="computeroutput">.tcl</tt> file for the form entry template is pretty
simple. Here, the only thing we need from the database is a new ID for
the note object to be inserted. Open up a file called
-<tt>note-add.tcl</tt> in the <tt>ROOT/packages/notes/www</tt>
+<tt class="computeroutput">note-add.tcl</tt> in the <tt class="computeroutput">ROOT/packages/notes/www</tt>
directory, and put the following code in it:
</p><pre class="programlisting">
@@ -69,74 +68,74 @@
where forum_id = :user_id
}
-set page_title "Add a note for $user_name"
-set submit_label "Add"
-set target "note-add-2"
+set page_title "Add a note for $user_name"
+set submit_label "Add"
+set target "note-add-2"
set note_id [db_nextval acs_object_id_seq]
-ad_return_template "note-add"
+ad_return_template "note-add"
</pre><p>
Some things to note about this code:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The procedure <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a> is
-always the first thing a <tt>.tcl</tt> file calls, if it's under
+always the first thing a <tt class="computeroutput">.tcl</tt> file calls, if it's under
the www/ directory (i.e. not a Tcl library file). It does validation
of input values from the HTTP request (i.e. form variables) and in
-this case, the <tt>-properties</tt> clause is used to set up the
-data sources that we will ship over to the <tt>.adp</tt> part of
+this case, the <tt class="computeroutput">-properties</tt> clause is used to set up the
+data sources that we will ship over to the <tt class="computeroutput">.adp</tt> part of
the page. In this case, we only use the simplest possible kind of data
-source, called a <tt>onevalue</tt>, which hold just a single
+source, called a <tt class="computeroutput">onevalue</tt>, which hold just a single
string value. Later on, we'll see how to use more powerful kinds of
data sources for representing multiple rows from an SQL query. You
also include overall documentation for the page in the contract, and
OpenACS has automatic tools that extract this documentation and make it
browsable.
</p></li><li><p>
-After being declared in the <tt>ad_page_contract</tt>, each
+After being declared in the <tt class="computeroutput">ad_page_contract</tt>, each
property is just a simple Tcl variable. The template system passes the
-final value of the variable to the <tt>.adp</tt> template when the
-<tt>.tcl</tt> file is processed.
+final value of the variable to the <tt class="computeroutput">.adp</tt> template when the
+<tt class="computeroutput">.tcl</tt> file is processed.
</p></li><li><p>
-The call <tt>ad_return_template</tt> tells the template system
-what <tt>.adp</tt> template page to fetch to display the
+The call <tt class="computeroutput">ad_return_template</tt> tells the template system
+what <tt class="computeroutput">.adp</tt> template page to fetch to display the
properties that have been processed. By default, the template system
-will look for a file by the same name as the <tt>.tcl</tt> file
-that just ran, but with an <tt>.adp</tt> extension.
+will look for a file by the same name as the <tt class="computeroutput">.tcl</tt> file
+that just ran, but with an <tt class="computeroutput">.adp</tt> extension.
</p></li></ul></div><p>
-Next we write the corresponding <tt>.adp</tt> page. This page
+Next we write the corresponding <tt class="computeroutput">.adp</tt> page. This page
outputs HTML for the form, and also contains placeholders whose values
-are substituted in from the properties set up by the <tt>.tcl</tt>
-file. Create a file called <tt>note-add.adp</tt> in your editor,
+are substituted in from the properties set up by the <tt class="computeroutput">.tcl</tt>
+file. Create a file called <tt class="computeroutput">note-add.adp</tt> in your editor,
and insert this text:
</p><pre class="programlisting">
-<master src="master">
-<property name="title">@page_title@</property>
-<property name="context_bar">@context_bar@</property>
+<master src="master">
+<property name="title">@page_title@</property>
+<property name="context_bar">@context_bar@</property>
<form action=@target@>
<p>Title:
-<input type="text" name="title" value="">
+<input type="text" name="title" value="">
</p>
<p>Body:
-<input type="text" name="title" value="">
+<input type="text" name="title" value="">
</p>
<p>
<center>
-<input type=submit value="@submit_label@">
+<input type=submit value="@submit_label@">
</center>
</p>
</form>
</pre><p>
The main point to note here is: when you want to substitute a value
-into a page, you put the name of the data source between two "@"
+into a page, you put the name of the data source between two "@"
characters. Another point to note is the use of a master template:
Master templates allow you do centralize display code that is used
throughout an application in a single file. In this case, we intend to
have a master template that does the standard page headers and footers
-for us - create the <tt>master.adp</tt> file, which looks like
+for us - create the <tt class="computeroutput">master.adp</tt> file, which looks like
this:
</p><pre class="programlisting">
@@ -145,25 +144,25 @@
<%= [eval ad_context_bar $context_bar] %>
<hr>
<slave>
-<br clear="all">
+<br clear="all">
<%= [ad_footer] %>
</pre><p>
The main subtlety in this code is the inline Tcl code for running
procs to build the header, footer, context bar, etc. Also, note the
property substitutions that happen here, the values of which are set
-up in the <tt><property></tt> tags in the slave page.
+up in the <tt class="computeroutput"><property></tt> tags in the slave page.
</p><p>
After putting all these files into
-<tt>ROOT/packages/notes/www</tt>, you should be able to go to
-<tt>/notes/</tt> URL for your server and see the input form.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="templates-summary"></a>Summary</h3></div></div><p>
+<tt class="computeroutput">ROOT/packages/notes/www</tt>, you should be able to go to
+<tt class="computeroutput">/notes/</tt> URL for your server and see the input form.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="templates-summary"></a>Summary</h3></div></div><div></div></div><p>
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 5.0.0d, the
-logic part of the page is just a <tt>.tcl</tt> that sets up
+queries and application logic, and another for display. In OpenACS 5.0.0a1, the
+logic part of the page is just a <tt class="computeroutput">.tcl</tt> that sets up
<span class="emphasis"><em>data sources</em></span> that are used by the display part of the page. The
-display part of the page is an <tt>.adp</tt> file with some
+display part of the page is an <tt class="computeroutput">.adp</tt> 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
Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 20 Aug 2003 16:20:17 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 14 Oct 2003 11:02:59 -0000 1.5
@@ -1,18 +1,17 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Advanced Topics</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-debug.html" title="Debugging and Automated Testing"><link rel="next" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tutorial-advanced"></a>Advanced Topics</h2></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>This section is a work in progress.</p></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Advanced Topics</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-debug.html" title="Debugging and Automated Testing"><link rel="next" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-advanced"></a>Advanced Topics</h2></div></div><div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>This section is a work in progress.</p></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2966023"></a>Overview</h3></div></div><p>This tutorial covers topics which are not essential to
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2837386"></a>Overview</h3></div></div><div></div></div><p>This tutorial covers topics which are not essential to
creating a minimal working package. Each section can be used
independently of all of the others; all sections assume that
you've completed the basic tutorial.</p><div class="itemizedlist"><ul type="disc"><li><p>How to enforce security so that users can't
change other users records</p></li><li><p>How to use the content management tables so that
... what?</p></li><li><p>How to change the default stylesheets for Form
Builder HTML forms.</p></li><li><p>How to make your package searchable with OpenFTS/Oracle</p></li><li><p>How to make your package send email notifications</p></li><li><p>How to prepare pagelets for inclusion in other pages</p></li><li><p>How and when to put procedures in a tcl procedure library</p></li><li><p>How to add general_comments to your pages</p></li><li><p>More on ad_form - data validation, other stuff.
(plan to draw from Jon Griffin's doc)</p></li><li><p>How and when to implement caching</p></li><li><p>partialquery in xql</p></li><li><p>How to use the html/text entry widget to get the
- "does this look right" confirm page </p></li><li><p>APM package dependencies</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2959129"></a>Delete with confirmation</h3></div></div><p>We need a way to delete records. We'll create a
- recursive confirmation page.</p><p>Add this column to the table_def in index.tcl</p><pre class="programlisting">{delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}}</pre><p>Create the delete confirmation/execution page.</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs note-delete.tcl</tt></b></pre><pre class="programlisting">ad_page_contract {
+ "does this look right" confirm page </p></li><li><p>APM package dependencies</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2837099"></a>Delete with confirmation</h3></div></div><div></div></div><p>We need a way to delete records. We'll create a
+ recursive confirmation page.</p><p>Add this column to the table_def in index.tcl</p><pre class="programlisting">{delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}}</pre><p>Create the delete confirmation/execution page.</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs note-delete.tcl</tt></b></pre><pre class="programlisting">ad_page_contract {
A page that gets confirmation and then delete notes.
@author joel@aufrecht.org
@@ -23,64 +22,64 @@
confirm_p:optional
}
-set title "Delete Note"
+set title "Delete Note"
if {![exists_and_not_null confirm_p]} {
# first pass, not confirmed. Display a form for confirmation
set note_name [db_string get_name { *SQL }]
- set title "Delete $note_name"
+ set title "Delete $note_name"
template::form::create note-del-confirm
template::element::create note-del-confirm note_id -value $note_id -widget hidden
template::element::create note-del-confirm confirm_p -value 1 -widget hidden
template::element::create note-del-confirm submit \
- -label "Confirm deletion of $note_name" \
+ -label "Confirm deletion of $note_name" \
-widget submit
} else {
# second pass, confirmed. Call the database to delete the record
db_1row do_delete { *SQL* }
- ad_returnredirect "index"
+ ad_returnredirect "index"
ad_script_abort
}</pre><p>This page requires a
-<tt>note_id</tt> to determine which record
+<tt class="computeroutput">note_id</tt> to determine which record
should be deleted. It also looks for a confirmation variable, which
should initially be absert. If it is absent, we create a form to
allow the user to confirm the deletion. Note that in
-<tt>entry-edit.tcl</tt> we used <tt>ad_form</tt> to access the Form Template
+<tt class="computeroutput">entry-edit.tcl</tt> we used <tt class="computeroutput">ad_form</tt> to access the Form Template
commands; here, we call them directly because we don't need the extra
features of ad_form. The form calls itself, but
with hidden variables carrying both
-<tt>note_id</tt> and
-<tt>confirm_p</tt>. If confirm_p is present,
+<tt class="computeroutput">note_id</tt> and
+<tt class="computeroutput">confirm_p</tt>. If confirm_p is present,
we delete the record, set redirection back to the index, and abort
-script execution.</p><p>The database commands:</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs note-delete.xql</tt></b></pre><pre class="programlisting"><?xml version="1.0"?>
+script execution.</p><p>The database commands:</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs note-delete.xql</tt></b></pre><pre class="programlisting"><?xml version="1.0"?>
<queryset>
- <fullquery name="do_delete">
+ <fullquery name="do_delete">
<querytext>
select samplenote__delete(:note_id)
</querytext>
</fullquery>
- <fullquery name="get_name">
+ <fullquery name="get_name">
<querytext>
select samplenote__name(:note_id)
</querytext>
</fullquery>
-</queryset></pre><p>And the adp page:</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs note-delete.adp</tt></b></pre><pre class="programlisting"><master>
-<property name="title">@title@</property>
-<property name="context">{@title@}</property>
+</queryset></pre><p>And the adp page:</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs note-delete.adp</tt></b></pre><pre class="programlisting"><master>
+<property name="title">@title@</property>
+<property name="context">{@title@}</property>
<h2>@title@</h2>
-<formtemplate id="note-del-confirm"></formtemplate>
+<formtemplate id="note-del-confirm"></formtemplate>
</form></pre><p>The ADP is very simple. The
-<tt>formtemplate</tt> tag outputs the HTML
-form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2918539"></a>General_comments</h3></div></div><p>You can track comments for any ACS Object. Here we'll track
+<tt class="computeroutput">formtemplate</tt> tag outputs the HTML
+form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2837247"></a>General_comments</h3></div></div><div></div></div><p>You can track comments for any ACS Object. Here we'll track
comments for notes. On the notes.tcl/adp pair, which is used to
display individual notes, we want to put a link to add comments at
the bottom of the screen. If there are any comments, we want to
show them.</p><p>First, we need to generate a url for adding comments. In notes.tcl:</p><pre class="programlisting">
-set comment_add_url "[general_comments_package_url]comment-add?[export_vars {
+set comment_add_url "[general_comments_package_url]comment-add?[export_vars {
{ object_id $note_id }
{ object_name $title }
- { return_url "[ad_conn url]?[ad_conn query]"}
-}]"
+ { return_url "[ad_conn url]?[ad_conn query]"}
+}]"
</pre><p>This calls a global, public tcl function that the
general_comments package registered, to get its url. You then
embed in that url the id of the note and its title, and set the
@@ -91,14 +90,14 @@
show the contents of the comments, instead of just the fact that
there are comments. Then you pass the note id, which is also the
acs_object id.</p><p>We put our two new variables in the notes.adp
- page.</p><pre class="programlisting"><a href="@comment_add_url@">Add a comment</a>
-@comments_html@</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2918618"></a>Prepare the package for distribution.</h3></div></div><p>Browse to the package manager. Click on
- <tt><span class="guilabel">tutorialapp</span></tt>.</p><p>Click on <tt><span class="guilabel">Generate a distribution file
+ page.</p><pre class="programlisting"><a href="@comment_add_url@">Add a comment</a>
+@comments_html@</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2837318"></a>Prepare the package for distribution.</h3></div></div><div></div></div><p>Browse to the package manager. Click on
+ <tt class="computeroutput"><span class="guilabel"><span class="guilabel">tutorialapp</span></span></tt>.</p><p>Click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Generate a distribution file
for this package from the
- filesystem</span></tt>.
+ filesystem</span></span></tt>.
</p><p>Click on the file size
- (<tt><span class="guilabel">37.1KB</span></tt>)
- after the label <tt><span class="guilabel">Distribution
- File:</span></tt> and save the file to
- /tmp.</p><p><a class="indexterm" name="id2940810"></a>
+ (<tt class="computeroutput"><span class="guilabel"><span class="guilabel">37.1KB</span></span></tt>)
+ after the label <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Distribution
+ File:</span></span></tt> and save the file to
+ /tmp.</p><p><a class="indexterm" name="id2837365"></a>
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr><tr><td width="40%" align="left">Debugging and Automated Testing </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Chapter�11.�Development Reference</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tutorial-advanced.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/tutorial-database.html 20 Aug 2003 16:20:17 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.html 14 Oct 2003 11:02:59 -0000 1.5
@@ -1,20 +1,19 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Setting Up Database Objects</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-newpackage.html" title="Creating a Package"><link rel="next" href="tutorial-pages.html" title="Creating Web Pages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tutorial-database"></a>Setting Up Database Objects</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Setting Up Database Objects</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-newpackage.html" title="Creating a Package"><link rel="next" href="tutorial-pages.html" title="Creating Web Pages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-database"></a>Setting Up Database Objects</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2950935"></a>Code the data model</h3></div></div><p>We create all database objects with scripts in the
- <tt>samplenote/sql/</tt> directory. All
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2833194"></a>Code the data model</h3></div></div><div></div></div><p>We create all database objects with scripts in the
+ <tt class="computeroutput">samplenote/sql/</tt> directory. All
database scripts are database-specific and are thus in either
- the <tt>samplenote/sql/oracle</tt> or
- <tt>samplenote/sql/postgresql</tt>.
+ the <tt class="computeroutput">samplenote/sql/oracle</tt> or
+ <tt class="computeroutput">samplenote/sql/postgresql</tt>.
Packages can support Oracle, PostgreSQL, or both. </p><p>The first file will be
- <tt>samplenote-create.sql</tt>. The
+ <tt class="computeroutput">samplenote-create.sql</tt>. The
package manager requires a file with the name
- <tt><span class="replaceable">packagekey</span>-create.sql</tt>,
+ <tt class="computeroutput"><span class="replaceable"><span class="replaceable">packagekey</span></span>-create.sql</tt>,
which it will run automatically when the package in installed.
This file should create all tables and views.</p><p>Our package is going to store all of its information in
- one table. It takes more than just a <tt>CREATE
+ one table. It takes more than just a <tt class="computeroutput">CREATE
TABLE</tt> command, however, because we want to
integrate our table with the OpenACS system. By making each
record in our table an OpenACS object, we gain access to the
@@ -25,22 +24,22 @@
Comments are located within the source code, with each comment
preceeding the relevant code. (<a href="objects.html" target="_top">More
info about ACS Objects</a>)</p><p>First, create the necessary subdirectories and add them
- cvs as you go.</p><pre class="screen">[service0@yourserver samplenote]$<b><tt> cd /web/service0/packages/samplenote</tt></b>
-[service0@yourserver samplenote]$ <b><tt>mkdir sql</tt></b>
-[service0@yourserver samplenote]$ <b><tt>cvs add sql</tt></b>
+ cvs as you go.</p><pre class="screen">[service0@yourserver samplenote]$<b class="userinput"><tt> cd /web/service0/packages/samplenote</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>mkdir sql</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cvs add sql</tt></b>
Directory /cvsroot/service0/packages/samplenote/sql added to the repository
-[service0@yourserver samplenote]$ <b><tt>cd sql/</tt></b>
-[service0@yourserver sql]$ <b><tt>mkdir postgresql</tt></b>
-[service0@yourserver sql]$ <b><tt>cvs add postgresql</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cd sql/</tt></b>
+[service0@yourserver sql]$ <b class="userinput"><tt>mkdir postgresql</tt></b>
+[service0@yourserver sql]$ <b class="userinput"><tt>cvs add postgresql</tt></b>
Directory /cvsroot/service0/packages/samplenote/sql/postgresql added to the repository
-[service0@yourserver sql]$ <b><tt>cd postgresql/</tt></b></pre><p>We break out the sql commands into several files that can
+[service0@yourserver sql]$ <b class="userinput"><tt>cd postgresql/</tt></b></pre><p>We break out the sql commands into several files that can
be called independently, and then call all of the create files
from the master create file. The top of each sql file has some
standard comments, including doc tags such as
- <tt>@author</tt> which will be picked up
+ <tt class="computeroutput">@author</tt> which will be picked up
by the API browser. The string
- <tt>$Id$</tt> will automatically be
- expanded when the file is checked in to cvs.</p><pre class="screen">[service0@yourserver postgresql]$ <b><tt>emacs samplenote-create.sql</tt></b></pre><p>Paste this into the file and save and close.</p><div class="figure"><a name="id2948352"></a><p class="title"><b>Figure�10.2.�Database Creation Script - master create file</b></p><pre class="programlisting">--
+ <tt class="computeroutput">$Id$</tt> will automatically be
+ expanded when the file is checked in to cvs.</p><pre class="screen">[service0@yourserver postgresql]$ <b class="userinput"><tt>emacs samplenote-create.sql</tt></b></pre><p>Paste this into the file and save and close.</p><div class="figure"><a name="id2838584"></a><p class="title"><b>Figure�10.2.�Database Creation Script - master create file</b></p><pre class="programlisting">--
-- packages/samplenote/sql/postgresql/samplenote-create.sql
--
-- @author rhs@mit.edu
@@ -50,7 +49,7 @@
--
\i samplenote-table-create.sql
-\i samplenote-functions-create.sql</pre></div><p>Create the file to create the database table.</p><pre class="screen">[service0@yourserver postgresql]$ <b><tt>emacs samplenote-table-create.sql</tt></b></pre><p>Paste this into the file and save and close.</p><div class="figure"><a name="id2948399"></a><p class="title"><b>Figure�10.3.�Database Creation Script - table</b></p><pre class="programlisting">--
+\i samplenote-functions-create.sql</pre></div><p>Create the file to create the database table.</p><pre class="screen">[service0@yourserver postgresql]$ <b class="userinput"><tt>emacs samplenote-table-create.sql</tt></b></pre><p>Paste this into the file and save and close.</p><div class="figure"><a name="id2827935"></a><p class="title"><b>Figure�10.3.�Database Creation Script - table</b></p><pre class="programlisting">--
-- packages/samplenote/sql/postgresql/samplenote-table-create.sql
--
-- @author rhs@mit.edu
@@ -93,7 +92,7 @@
null, -- type_extension_table
''samplenote__name'' -- name_method
);
-</pre></div><p>Create the file to create the functions used to manipulate records.</p><pre class="screen">[service0@yourserver postgresql]$ <b><tt>emacs samplenote-functions-create.sql</tt></b></pre><p>Paste this into the file and save and close.</p><div class="figure"><a name="id2873380"></a><p class="title"><b>Figure�10.4.�Database Creation Script - functions</b></p><pre class="programlisting">--
+</pre></div><p>Create the file to create the functions used to manipulate records.</p><pre class="screen">[service0@yourserver postgresql]$ <b class="userinput"><tt>emacs samplenote-functions-create.sql</tt></b></pre><p>Paste this into the file and save and close.</p><div class="figure"><a name="id2838534"></a><p class="title"><b>Figure�10.4.�Database Creation Script - functions</b></p><pre class="programlisting">--
-- packages/samplenote/sql/postgresql/samplenote-functions-create.sql
--
-- @author rhs@mit.edu
@@ -112,7 +111,7 @@
Creation ip is optional
Context id, required, is the id of the package instance. This allows
segregation of records by package instance, required to make the package
-"package-aware."
+"package-aware."
define_function_args prepares the function to be used by a tcl wrapper function. */
</em></span>
select define_function_args('samplenote__new','note_id,title,body,creation_date,creation_user,creation_ip,context_id');
@@ -188,7 +187,7 @@
end;
' language 'plpgsql';
</pre></div><p>Create a database file to drop everything if the package
- is uninstalled.</p><pre class="screen">[service0@yourserver postgresql]$ <b><tt>emacs samplenote-drop.sql</tt></b></pre><div class="figure"><a name="id2873486"></a><p class="title"><b>Figure�10.5.�Database deletion script</b></p><pre class="programlisting">-- packages/samplenote/sql/samplenote-drop.sql
+ is uninstalled.</p><pre class="screen">[service0@yourserver postgresql]$ <b class="userinput"><tt>emacs samplenote-drop.sql</tt></b></pre><div class="figure"><a name="id2835266"></a><p class="title"><b>Figure�10.5.�Database deletion script</b></p><pre class="programlisting">-- packages/samplenote/sql/samplenote-drop.sql
-- drop script
--
-- @author rhs@mit.edu
@@ -224,11 +223,11 @@
select acs_object_type__drop_type(
'samplenote',
't'
- );</pre></div><p>Add the database files to cvs.</p><pre class="screen">[service0@yourserver postgresql]$<b><tt> cvs add *.sql</tt></b>
+ );</pre></div><p>Add the database files to cvs.</p><pre class="screen">[service0@yourserver postgresql]$<b class="userinput"><tt> cvs add *.sql</tt></b>
cvs add: scheduling file `samplenote-create.sql' for addition
cvs add: scheduling file `samplenote-drop.sql' for addition
cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver samplenote]$ <b><tt>cvs commit -m "new database files"</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cvs commit -m "new database files"</tt></b>
cvs commit: Examining .
cvs commit: Examining sql
cvs commit: Examining sql/postgresql
@@ -239,7 +238,7 @@
done
<span class="emphasis"><em>(many lines omitted)</em></span>
done
-[service0@yourserver samplenote]$</pre><p>Run the create script manually to add your tables and functions.</p><pre class="screen">[service0@yourserver samplenote]$ <b><tt>cd sql/postgresql/</tt></b>
-[service0@yourserver postgresql]$ <b><tt>psql -f samplenote-create.sql</tt></b>
-[service0@yourserver postgresql]$</pre><p>If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.</p><p>If there are errors creating the functions, you can re-run the function creation file directly after fixing it, because all of the functions are created with <tt>create or replace</tt> commands. This will also make it easier to fix mistakes within the functions that aren't apparent until the functions are used. And it will make upgrades easier.</p><p>Once you get the same output as shown above, test the drop script:</p><pre class="screen">[service0@yourserver postgresql]$ <b><tt>psql -f samplenote-drop.sql</tt></b>
+[service0@yourserver samplenote]$</pre><p>Run the create script manually to add your tables and functions.</p><pre class="screen">[service0@yourserver samplenote]$ <b class="userinput"><tt>cd sql/postgresql/</tt></b>
+[service0@yourserver postgresql]$ <b class="userinput"><tt>psql -f samplenote-create.sql</tt></b>
+[service0@yourserver postgresql]$</pre><p>If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.</p><p>If there are errors creating the functions, you can re-run the function creation file directly after fixing it, because all of the functions are created with <tt class="computeroutput">create or replace</tt> commands. This will also make it easier to fix mistakes within the functions that aren't apparent until the functions are used. And it will make upgrades easier.</p><p>Once you get the same output as shown above, test the drop script:</p><pre class="screen">[service0@yourserver postgresql]$ <b class="userinput"><tt>psql -f samplenote-drop.sql</tt></b>
[service0@yourserver postgresql]$</pre><p>Once both scripts are working without errors, run the create script one last time and proceed.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr><tr><td width="40%" align="left">Creating a Package </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Creating Web Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tutorial-database.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.html 20 Aug 2003 16:20:17 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html 14 Oct 2003 11:02:59 -0000 1.5
@@ -1,28 +1,129 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Debugging and Automated Testing</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-pages.html" title="Creating Web Pages"><link rel="next" href="tutorial-advanced.html" title="Advanced Topics"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tutorial-debug"></a>Debugging and Automated Testing</h2></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>This section is a work in progress.</p></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Debugging and Automated Testing</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-pages.html" title="Creating Web Pages"><link rel="next" href="tutorial-advanced.html" title="Advanced Topics"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-debug"></a>Debugging and Automated Testing</h2></div></div><div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>This section is a work in progress.</p></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2926057"></a>Debugging</h3></div></div><p><b>PostgreSQL.�</b>You can work directly with the database to do debugging
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2832991"></a>Debugging</h3></div></div><div></div></div><p><b>Developer Support.�</b>The Developer Support package adds several goodies: debug
+ information for every page; the ability to log comments to the
+ page instead of the error log, and fast user switching so that you
+ can test pages as anonymous and as dummy users without logging
+ in and out.</p><p><b>PostgreSQL.�</b>You can work directly with the database to do debugging
steps like looking directly at tables and testing stored
procedures. <span class="bold"><b>Start emacs. Type
- <b><tt>M-x sql-postgres</tt></b>. Press enter for
- server name and use <b><tt>openacs-dev</tt></b> for
+ <b class="userinput"><tt>M-x sql-postgres</tt></b>. Press enter for
+ server name and use <b class="userinput"><tt>openacs-dev</tt></b> for
database name. You can use C-(up arrow) and C-(down arrow)
- for command history.</b></span></p><p>Hint: "Parse error near *" usually means that an xql file
+ for command history.</b></span>
+</p><p>Hint: "Parse error near *" usually means that an xql file
wasn't recognized, because the tcl file is choking on the *SQL*
- placeholder that it falls back on.</p><p><b>Watching the server log.�</b>NOTE: explain how to add tcl to directly write your own log outputTo set up real-time monitoring of the Aolserver error
- log, <span class="bold"><b>type <pre class="screen">less /usr/local/aolserver/log/openacs-dev-error.log</pre></b></span>
+ placeholder that it falls back on.</p><p><b>Watching the server log.�</b>NOTE: explain how to add tcl to directly write your own
+ log output</p><p>To set up real-time monitoring of the Aolserver error
+ log, <span class="bold"><b>type</b></span> </p><pre class="screen">less /usr/local/aolserver/log/openacs-dev-error.log</pre><p>
</p><div class="literallayout"><p>F�to�show�new�log�entries�in�real�time�(like�tail�-f)<br>
C-c�to�stop�and�F�to�start�it�up�again.�<br>
G�goes�to�the�end.<br>
?�searches�backward�<br>
/�searches�forward.�<br>
����������</p></div><p>
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2926146"></a>Manual testing</h3></div></div><p>Make a list of basic tests to make sure it works</p><div class="segmentedlist"><table border="0"><thead><tr><th>Test Num</th><th>Action</th><th>Expected Result</th></tr></thead><tbody><tr><td>001</td><td>Browse to the index page while not logged in and
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2837802"></a>Manual testing</h3></div></div><div></div></div><p>Make a list of basic tests to make sure it works</p><div class="segmentedlist"><table border="0"><thead><tr><th>Test Num</th><th>Action</th><th>Expected Result</th></tr></thead><tbody><tr><td>001</td><td>Browse to the index page while not logged in and
while one or more notes exist.</td><td>No edit or delete or add links should appear.</td></tr><tr><td>002</td><td>Browse to the index page while logged in. An Edit
link should appear. Click on it. Fill out the form and
click Submit.</td><td>The text added in the form should be visible on the
index page.</td></tr></tbody></table></div><p>Other things to test: try to delete someone else's
note. Try to delete your own note. Edit your own note.
- Search for a note.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2990057"></a>Write automated tests</h3></div></div><p><a class="indexterm" name="id2990065"></a>(Forthcoming.)</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr><tr><td width="40%" align="left">Creating Web Pages </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Advanced Topics</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tutorial-debug.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ Search for a note.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2838404"></a>Write automated tests</h3></div></div><div></div></div><div class="authorblurb"><p>
+ by <a href="mailto:simon@collaboraid.net" target="_top">Simon Carstensen</a><br>
+ OpenACS docs are written by the named authors, and may be edited
+ by OpenACS documentation staff.
+ </p></div><p><a class="indexterm" name="id2838423"></a>It seems to me that a lot of
+people have been asking for some guidelines on how to write automated
+tests. I've done several tests by now and have found the process to be
+extremely easy and useful. It's a joy to work with automated testing
+once you get the hang of it.</p><p>I just wrote a test script for the acs-service-contract package and
+thought I'd might as well post a step-by-step run-through, since some
+people have been asking for this. Here goes.
+</p><div class="orderedlist"><ol type="1"><li><p>Create the directory that will contain the test
+ script(s):</p><pre class="screen">
+$ cd /web/simon/packages/acs-service-contract/tcl
+$ mkdir test
+</pre></li><li><p>Create the .tcl library that holds the test
+ procs:</p><pre class="screen">
+$ cd test
+$ emacs acs-service-contract-procs.tcl
+</pre></li><li><p>Write the tests. This is obviously the big step
+ :)</p><p>
+The script should first call ad_library like any normal -procs.tcl file:
+</p><pre class="screen">ad_library {
+ ...
+}
+</pre><p>To create a test case you call
+<tt class="computeroutput">aa_register_case test_case_name.</tt>.
+Once you've created the test case you start writing the needed logic.
+Let's say you just wrote an API for adding and deleting notes in the
+notes packages and wanted to test that. You'd probably want to write a
+test that first creates a note, then verifies that it was inserted,
+then perhaps deletes it again, and finally verifies that it is
+gone.</p><p>
+Naturally this means you'll be adding a lot of bogus data to the
+database, which you're not really interested in having there. To avoid
+this I usually do two things. I always put all my test code inside a
+call to aa_run_with_teardown which basically means that all the
+inserts, deletes, and updates will be rolled back once the test has
+been executed. A very useful feature. Instead of inserting bogus data
+like: <tt class="computeroutput">set name "Simon"</tt>, I tend to generate a random script in order avoid inserting a value that's already in the database:
+</p><pre class="screen">set name [ad_generate_random_string]
+</pre><p>
+<i class="parameter"><tt>Here's how the test case looks so far:</tt></i>
+
+</p><pre class="screen">aa_register_case acs_sc_impl_new_from_spec {
+
+ aa_run_with_teardown \
+ -rollback \
+ -testcode {
+ ... logic ...
+ }
+}
+</pre><p>Now let's look at the actual test code. That's the code that
+goes inside <tt class="computeroutput">-testcode {}</tt>.
+In my case I had added a new column to acs_sc_impls (pretty_name),
+which meant that I had to change the datamodel and the Tcl API to
+support this new change. To make sure I didn't screw up, I wrote a test
+that created a new service contract, then a new implementation of that
+contract, and called acs_sc::impl::get to check that the data in the
+new column had been added correctly and then finally verified that the
+pretty_name was actually what I had tried to insert. It looked
+something like this:
+</p><pre class="screen">set spec {
+ name "foo_contract"
+ description "Blah blah"
+ ...
+}
+
+# Create service contract
+acs_sc::contract::new_from_spec -spec $spec
+
+set spec {
+ name "foo_impl"
+ description "Blah blah blah"
+ pretty_name "Foo Implementation"
+ ...
+}
+
+# Create implementation
+set impl_id [acs_sc::impl::new_from_spec -spec $spec]
+
+# Get the values of the implementation we just created
+acs_sc::impl::get -impl_id $impl_id -array impl
+
+#Verify that the pretty_name column has the correct value
+aa_equals "did column pretty_name get set correctly?" $impl(pretty_name) "Foo Implementation"
+</pre><p>Now you might not know how acs-service-contract works, but that
+doesn't matter. I'm basically inserting data into the database, then
+querying for the database to check that it got inserted and then
+finally, using aa_equals, I compare the result with what I inserted to
+verify that everything is correct.</p><p>
+There are number of other useful procs for determening whether a test case was successful or not, namely:
+</p><pre class="screen">aa_true "is this true?" [expr ![empty_string $foo]]
+aa_false "is this true?" [empty_string $foo]
+</pre><p>There a number of other useful procs and I will encourage you to
+look at the few packages for which tests have already been implemented.
+That is perhaps the best documentation we have so far.</p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr><tr><td width="40%" align="left">Creating Web Pages </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Advanced Topics</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tutorial-debug.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 20 Aug 2003 16:20:17 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 14 Oct 2003 11:02:59 -0000 1.5
@@ -1,49 +1,48 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Creating a Package</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="next" href="tutorial-database.html" title="Setting Up Database Objects"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-database.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tutorial-newpackage"></a>Creating a Package</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Creating a Package</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="next" href="tutorial-database.html" title="Setting Up Database Objects"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-database.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-newpackage"></a>Creating a Package</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2948480"></a>Overview</h3></div></div><p>To start developing new code in OpenACS, we build a new
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2834879"></a>Overview</h3></div></div><div></div></div><p>To start developing new code in OpenACS, we build a new
package. A package is a a discrete collection of web
pages, tcl code, and database tables and procedures. A package
can be installed, upgraded, and removed. It communicates with
other packages through an API. This chapter walks you through the
minimum steps to create a useful package, including writing
documentation, setting up database tables and procedures,
writing web pages, debugging, and automatic regression testing.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2948500"></a>Before you begin</h3></div></div><p>You will need:</p><div class="itemizedlist"><ul type="disc"><li><p>A computer with a working installation of OpenACS
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2825791"></a>Before you begin</h3></div></div><div></div></div><p>You will need:</p><div class="itemizedlist"><ul type="disc"><li><p>A computer with a working installation of OpenACS
4.6. If you don't have this, see <a href="install-overview.html">Installation Overview</a>.
</p></li><li><p>Example files, which are included in the
-standard OpenACS 5.0.0d distribution.
- </p></li></ul></div><div class="figure"><a name="id2948533"></a><p class="title"><b>Figure�10.1.�Assumptions in this section</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><span class="replaceable">yourserver.test</span></td></tr><tr><td>URL of your server</td><td><span class="replaceable">http://yourserver.test:8000</span></td></tr><tr><td>Name of development account</td><td><span class="replaceable">service0</span></td></tr><tr><td>New Package key</td><td><span class="replaceable">samplenote</span></td></tr></tbody></table></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2948619"></a>Use the APM to initialize a new package</h3></div></div><p>We use the <a href="packages.html" target="_top">ACS Package Manager</a> (APM) to add, remove, and
+standard OpenACS 5.0.0a1 distribution.
+ </p></li></ul></div><div class="figure"><a name="id2825824"></a><p class="title"><b>Figure�10.1.�Assumptions in this section</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><span class="replaceable"><span class="replaceable">yourserver.test</span></span></td></tr><tr><td>URL of your server</td><td><span class="replaceable"><span class="replaceable">http://yourserver.test:8000</span></span></td></tr><tr><td>Name of development account</td><td><span class="replaceable"><span class="replaceable">service0</span></span></td></tr><tr><td>New Package key</td><td><span class="replaceable"><span class="replaceable">samplenote</span></span></td></tr></tbody></table></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2820711"></a>Use the APM to initialize a new package</h3></div></div><div></div></div><p>We use the <a href="packages.html" target="_top">ACS Package Manager</a> (APM) to add, remove, and
upgrade packages. It handles package meta-data, such as lists of
files that belong in the package. Each package is uniquely
identified by a package key. To start developing a new
package, use the APM to create an empty package with our new
- package key, <span class="replaceable">samplenote</span>. This will create
+ package key, <span class="replaceable"><span class="replaceable">samplenote</span></span>. This will create
the initial directories, meta-information files, and database
entries for a new package. (<a href="apm-requirements.html" target="_top">More info on APM</a>)
-</p><div class="orderedlist"><ol type="1"><li><p>Browse to <tt>http://<span class="replaceable">yourserver</span>:8000/acs-admin/apm</tt>.
-</p></li><li><p>Click <tt>Create a New Package</tt>.</p><p>Fill in the fields listed below. Tab through the rest.
+</p><div class="orderedlist"><ol type="1"><li><p>Browse to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>:8000/acs-admin/apm</tt>.
+</p></li><li><p>Click <tt class="computeroutput">Create a New Package</tt>.</p><p>Fill in the fields listed below. Tab through the rest.
(Some will change automatically. Don't mess with those.)
</p><div class="itemizedlist"><ul type="disc"><li><p>
- <tt>Package Key</tt>:
- <b><tt>samplenote</tt></b></p></li><li><p>
- <tt>Package Name</tt>:
- <b><tt>Notes</tt></b>
+ <tt class="computeroutput">Package Key</tt>:
+ <b class="userinput"><tt>samplenote</tt></b></p></li><li><p>
+ <tt class="computeroutput">Package Name</tt>:
+ <b class="userinput"><tt>Notes</tt></b>
</p></li><li><p>
- <tt>Package Plural</tt>:
- <b><tt>Notes</tt></b></p></li><li><p>
- <tt>Initial Version</tt>:
- <b><tt>0.1d</tt></b>
- </p></li><li><p><tt>Summary</tt>:
- <b><tt>This is my first package.</tt></b>
+ <tt class="computeroutput">Package Plural</tt>:
+ <b class="userinput"><tt>Notes</tt></b></p></li><li><p>
+ <tt class="computeroutput">Initial Version</tt>:
+ <b class="userinput"><tt>0.1d</tt></b>
+ </p></li><li><p><tt class="computeroutput">Summary</tt>:
+ <b class="userinput"><tt>This is my first package.</tt></b>
</p></li></ul></div><p>At the bottom, click
- <tt><span class="guibutton">Create Package</span></tt>.
+ <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Create Package</span></span></tt>.
</p></li></ol></div><p>This creates a package rooted at
- <tt>/web/<span class="replaceable">service0</span>/packages/<span class="replaceable">samplenote</span></tt>.
- This is the "home directory" of our new package, and all
- files in the package will be within this directory.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2992341"></a>Mount the package in the site map</h3></div></div><p>In order to see your work in progress, you must create a
+ <tt class="computeroutput">/web/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">samplenote</span></span></tt>.
+ This is the "home directory" of our new package, and all
+ files in the package will be within this directory.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2833270"></a>Mount the package in the site map</h3></div></div><div></div></div><p>In order to see your work in progress, you must create a
map between the URL space of incoming requests and the package.
You do this by mounting the package in the Site Map. This
creates a link between the incoming URL and an
@@ -53,52 +52,52 @@
code and tables. This requires that a package be developed
<span class="emphasis"><em>package-aware</em></span>. You'll see how to do that
in this tutorial.</p><div class="orderedlist"><ol type="1"><li><p>Browse to
-<tt>http://yourserver.test:8000/admin/site-map/</tt>.</p></li><li><p>Click the <tt><span class="guilabel">new sub
- folder</span></tt> link on the top row in the
- Site Map table.</p></li><li><p>Type <b><tt>note</tt></b>
-and click <tt><span class="guibutton">New</span></tt>. </p></li><li><p>This creates a new row called
-<tt>note</tt>. In the new row, click the <tt><span class="guilabel">new
-application</span></tt> link</p></li><li><p>Type <b><tt>Sample Note</tt></b> where
+<tt class="computeroutput">http://yourserver.test:8000/admin/site-map/</tt>.</p></li><li><p>Click the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">new sub
+ folder</span></span></tt> link on the top row in the
+ Site Map table.</p></li><li><p>Type <b class="userinput"><tt>note</tt></b>
+and click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></tt>. </p></li><li><p>This creates a new row called
+<tt class="computeroutput">note</tt>. In the new row, click the <tt class="computeroutput"><span class="guilabel"><span class="guilabel">new
+application</span></span></tt> link</p></li><li><p>Type <b class="userinput"><tt>Sample Note</tt></b> where
it says
-<tt><span class="guilabel">untitled</span></tt>, choose
-<tt><span class="guilabel">Notes</span></tt> from the drop-down list, and
-click <tt><span class="guibutton">New</span></tt>.
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">untitled</span></span></tt>, choose
+<tt class="computeroutput"><span class="guilabel"><span class="guilabel">Notes</span></span></tt> from the drop-down list, and
+click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></tt>.
</p></li></ol></div><p>By mounting the package, we've caused all requests to
- <tt>http://yourserver.test:8000/note</tt>
- to be satisfied from the files at <tt>/web/service0/packages/samplenote/www</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2992541"></a>Write the Requirements and Design Specs</h3></div></div><p>It's time to document. For the tutorial we'll use
+ <tt class="computeroutput">http://yourserver.test:8000/note</tt>
+ to be satisfied from the files at <tt class="computeroutput">/web/service0/packages/samplenote/www</tt>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2838630"></a>Write the Requirements and Design Specs</h3></div></div><div></div></div><p>It's time to document. For the tutorial we'll use
pre-written documentation. When creating a package
from scratch, start by copying the documentation template from
- <tt>/web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml</tt>
+ <tt class="computeroutput">/web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml</tt>
to
- <tt>yourpackage/www/docs/xml/index.xml</tt>.</p><p>You then edit that file with emacs to write the
+ <tt class="computeroutput">yourpackage/www/docs/xml/index.xml</tt>.</p><p>You then edit that file with emacs to write the
requirements and design sections, generate the html, and start
coding. Store any supporting files, like page maps or schema
- diagrams, in the <tt>www/doc/xml</tt>
+ diagrams, in the <tt class="computeroutput">www/doc/xml</tt>
directory, and store png or jpg versions of supporting files in the
- <tt>www/doc</tt> directory.</p><p>For this tutorial, you should instead install the
+ <tt class="computeroutput">www/doc</tt> directory.</p><p>For this tutorial, you should instead install the
pre-written documentation files for the tutorial app. Log in
- as <span class="replaceable">service0</span>, create the standard
- directories, and copy the prepared documentation:</p><pre class="screen">[service0@yourserver service0]$ <b><tt>cd /web/service0/packages/samplenote/</tt></b>
-[service0@yourserver samplenote]$ <b><tt>mkdir -p www/doc/xml</tt></b>
-[service0@yourserver samplenote]$ <b><tt>cd www/doc/xml</tt></b>
-[service0@yourserver xml]$ <b><tt>cp /web/service0/packages/acs-core-docs/www/files/samplenote/* .</tt></b>
+ as <span class="replaceable"><span class="replaceable">service0</span></span>, create the standard
+ directories, and copy the prepared documentation:</p><pre class="screen">[service0@yourserver service0]$ <b class="userinput"><tt>cd /web/service0/packages/samplenote/</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>mkdir -p www/doc/xml</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cd www/doc/xml</tt></b>
+[service0@yourserver xml]$ <b class="userinput"><tt>cp /web/service0/packages/acs-core-docs/www/files/samplenote/* .</tt></b>
[service0@yourserver xml]$</pre><p> OpenACS uses DocBook for documentation. DocBook is
an XML standard for semantic markup of documentation. That
means that the tags you use indicate meaning, not intended
appearance. The style sheet will determine appearance. You
will edit the text in an xml file, and then process the file
- into html for reading.</p><p>Open the file <tt>index.xml</tt>
+ into html for reading.</p><p>Open the file <tt class="computeroutput">index.xml</tt>
in emacs. Examine the file. Find the version history (look for the tag
- <tt><revhistory></tt>). Add a
+ <tt class="computeroutput"><revhistory></tt>). Add a
new record to the document version history. Look for the
- <tt><authorgroup></tt> tag and
+ <tt class="computeroutput"><authorgroup></tt> tag and
add yourself as a second author. Save and exit. For tips on
editing SGML files in emacs, see <a href="docbook-primer.html">OpenACS Documentation Guide</a></p><p>Process the xml file to create html documentation. The
html documentation, including supporting files such as pictures,
- is stored in the <tt>www/docs/</tt>
+ is stored in the <tt class="computeroutput">www/docs/</tt>
directory. A Makefile is provided to generate html from the xml, and copy all of the
supporting files. If Docbook is set up correctly, all you need
- to do is:</p><pre class="screen">[service0@yourserver xml]$<b><tt> make</tt></b>
+ to do is:</p><pre class="screen">[service0@yourserver xml]$<b class="userinput"><tt> make</tt></b>
cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
Writing requirements-introduction.html for sect1(requirements-introduction)
Writing requirements-overview.html for sect1(requirements-overview)
@@ -115,24 +114,24 @@
Writing bi01.html for bibliography
Writing index.html for book
[service0@yourserver xml]$</pre><p>Verify that the documentation was generated and reflects
- your changes by browsing to <tt>http://<span class="replaceable">yoursite</span>:8000/samplenote/doc</tt></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2892582"></a>Add the new package to CVS</h3></div></div><p>Before you do any more work, make sure that your work is
- protected by putting it all into cvs. The <tt>cvs
+ your changes by browsing to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yoursite</span></span>:8000/samplenote/doc</tt></p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2838800"></a>Add the new package to CVS</h3></div></div><div></div></div><p>Before you do any more work, make sure that your work is
+ protected by putting it all into cvs. The <tt class="computeroutput">cvs
add</tt> command is not recursive, so you'll have to
traverse the directory tree manually and add as you go. (<a href="http://www.piskorski.com/docs/cvs-conventions.html" target="_top">More on
- CVS</a>)</p><pre class="screen">[service0@yourserver xml]$ <b><tt>cd ..</tt></b>
-[service0@yourserver doc]$ <b><tt>cd ..</tt></b>
-[service0@yourserver www]$ <b><tt>cd ..</tt></b>
-[service0@yourserver samplenote]$ <b><tt>cd ..</tt></b>
-[service0@yourserver packages]$ <b><tt>cvs add samplenote/</tt></b>
+ CVS</a>)</p><pre class="screen">[service0@yourserver xml]$ <b class="userinput"><tt>cd ..</tt></b>
+[service0@yourserver doc]$ <b class="userinput"><tt>cd ..</tt></b>
+[service0@yourserver www]$ <b class="userinput"><tt>cd ..</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cd ..</tt></b>
+[service0@yourserver packages]$ <b class="userinput"><tt>cvs add samplenote/</tt></b>
Directory /cvsroot/service0/packages/samplenote added to the repository
-[service0@yourserver packages]$ <b><tt>cd samplenote/</tt></b>
-[service0@yourserver samplenote]$ <b><tt>cvs add www</tt></b>
+[service0@yourserver packages]$ <b class="userinput"><tt>cd samplenote/</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cvs add www</tt></b>
Directory /cvsroot/service0/packages/samplenote/www added to the repository
-[service0@yourserver samplenote]$ <b><tt>cd www</tt></b>
-[service0@yourserver www]$ <b><tt>cvs add doc</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cd www</tt></b>
+[service0@yourserver www]$ <b class="userinput"><tt>cvs add doc</tt></b>
Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
-[service0@yourserver www]$ <b><tt>cd doc</tt></b>
-[service0@yourserver doc]$ <b><tt>cvs add *</tt></b>
+[service0@yourserver www]$ <b class="userinput"><tt>cd doc</tt></b>
+[service0@yourserver doc]$ <b class="userinput"><tt>cvs add *</tt></b>
cvs add: cannot add special file `CVS'; skipping
cvs add: scheduling file `admin-guide.html' for addition
cvs add: scheduling file `bi01.html' for addition
@@ -157,13 +156,13 @@
cvs add: scheduling file `user-interface.png' for addition
Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver doc]$ <b><tt>cd xml</tt></b>
-[service0@yourserver xml]$ <b><tt>cvs add Makefile index.xml</tt></b>
+[service0@yourserver doc]$ <b class="userinput"><tt>cd xml</tt></b>
+[service0@yourserver xml]$ <b class="userinput"><tt>cvs add Makefile index.xml</tt></b>
cvs add: scheduling file `Makefile' for addition
cvs add: scheduling file `index.xml' for addition
cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver xml]$<b><tt> cd ../../..</tt></b>
-[service0@yourserver samplenote]$ <b><tt>cvs commit -m "new package"</tt></b>
+[service0@yourserver xml]$<b class="userinput"><tt> cd ../../..</tt></b>
+[service0@yourserver samplenote]$ <b class="userinput"><tt>cvs commit -m "new package"</tt></b>
cvs commit: Examining .
cvs commit: Examining www
cvs commit: Examining www/doc
Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.html 20 Aug 2003 16:20:17 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html 14 Oct 2003 11:02:59 -0000 1.5
@@ -1,19 +1,18 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Creating Web Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-database.html" title="Setting Up Database Objects"><link rel="next" href="tutorial-debug.html" title="Debugging and Automated Testing"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-database.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-debug.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tutorial-pages"></a>Creating Web Pages</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Creating Web Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="tutorial.html" title="Chapter�10.�Development Tutorial"><link rel="previous" href="tutorial-database.html" title="Setting Up Database Objects"><link rel="next" href="tutorial-debug.html" title="Debugging and Automated Testing"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-database.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-debug.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-pages"></a>Creating Web Pages</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2928718"></a>Build the "Index" page</h3></div></div><p>Each user-visible page in your package has, typically,
- three parts. The <tt>xql</tt> file contains any database queries, the
- <tt>tcl</tt> file holds the procedural logic for the page and does things
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2830289"></a>Build the "Index" page</h3></div></div><div></div></div><p>Each user-visible page in your package has, typically,
+ three parts. The <tt class="computeroutput">xql</tt> file contains any database queries, the
+ <tt class="computeroutput">tcl</tt> file holds the procedural logic for the page and does things
like check permissions, invoke the database queries, and modify
- variables, and the <tt>adp</tt> page
+ variables, and the <tt class="computeroutput">adp</tt> page
holds html. The default page in any directory is
- <tt>index</tt>, so we'll build that
+ <tt class="computeroutput">index</tt>, so we'll build that
first, starting with the tcl file:
-</p><pre class="screen">[service0@yourserver samplenote]$<b><tt> mkdir /web/service0/packages/samplenote/www</tt></b>
-[service0@yourserver samplenote]$<b><tt> cd /web/service0/packages/samplenote/www</tt></b>
-[service0@yourserver www]$ <b><tt>emacs index.tcl</tt></b></pre><p>Paste this into the file.</p><pre class="programlisting">ad_page_contract {
+</p><pre class="screen">[service0@yourserver samplenote]$<b class="userinput"><tt> mkdir /web/service0/packages/samplenote/www</tt></b>
+[service0@yourserver samplenote]$<b class="userinput"><tt> cd /web/service0/packages/samplenote/www</tt></b>
+[service0@yourserver www]$ <b class="userinput"><tt>emacs index.tcl</tt></b></pre><p>Paste this into the file.</p><pre class="programlisting">ad_page_contract {
This is the main page for the package. It displays all of the Notes and provides links to edit them and to create new Notes.
@author rhs@mit.edu
@@ -29,36 +28,36 @@
}
# define the columns in the table
set table_def {
- {title "Note"}
- {body "Contents"}
- {edit "" {} {<td><a href="note-edit?note_id=$note_id">Edit</a></td>}}
+ {title "Note"}
+ {body "Contents"}
+ {edit "" {} {<td><a href="note-edit?note_id=$note_id">Edit</a></td>}}
}
# construct an html table from the samplenotes database table
set table_html [ad_table -Torderby $orderby notes_query { *SQL* } $table_def]</pre><p> There are several things to
note about the file:</p><div class="itemizedlist"><ul type="disc"><li><p>The page begins with an
- <tt><a href="/api-doc/proc-view?proc=ad%5fpage%5fcontract" target="_top">ad_page_contract</a></tt> function.
+ <tt class="computeroutput"><a href="/api-doc/proc-view?proc=ad%5fpage%5fcontract" target="_top">ad_page_contract</a></tt> function.
This is where we declare the input and output variables and
their types and restrictions. It's also where we document the
page, including descriptions of the parameters and return.
(<a href="/doc/tcl-doc.html" target="_top">More information about TCL
pages and page contracts</a>)</p></li><li><p>We have one input variable,
- <tt>orderby</tt>, which is optional
- and defaults to <tt>title</tt>.</p></li><li><p>We have one output variable, <tt>table_html</tt></p></li><li><p>We populate the table_html variable with a function call, <tt><a href="/api-doc/proc-view?proc=ad%5f_table" target="_top">ad_table</a></tt>, which does most of the work of generating an html table from a database recordset. We pass it several parameters:</p><div class="variablelist"><dl><dt><span class="term">-Torderby $orderby</span></dt><dd><p>If the user has selected a column for sorting, this passes that information to the function.</p></dd><dt><span class="term">notes_query</span></dt><dd><p>This is the name of the SQL query that we'll put in the xql file.</p></dd><dt><span class="term">{ *SQL* }</span></dt><dd><p>This is a dummy placeholder. It's possible to put sql directly in the tcl file, but this is deprecated because it's harder to make portable.</p></dd><dt><span class="term">$table_def</span></dt><dd><p>Here we pass in the variable we just constructed; it contains a list of column names and display titles.</p></dd></dl></div></li></ul></div><p>Put the database query into a separate file. If the
+ <tt class="computeroutput">orderby</tt>, which is optional
+ and defaults to <tt class="computeroutput">title</tt>.</p></li><li><p>We have one output variable, <tt class="computeroutput">table_html</tt></p></li><li><p>We populate the table_html variable with a function call, <tt class="computeroutput"><a href="/api-doc/proc-view?proc=ad%5f_table" target="_top">ad_table</a></tt>, which does most of the work of generating an html table from a database recordset. We pass it several parameters:</p><div class="variablelist"><dl><dt><span class="term">-Torderby $orderby</span></dt><dd><p>If the user has selected a column for sorting, this passes that information to the function.</p></dd><dt><span class="term">notes_query</span></dt><dd><p>This is the name of the SQL query that we'll put in the xql file.</p></dd><dt><span class="term">{ *SQL* }</span></dt><dd><p>This is a dummy placeholder. It's possible to put sql directly in the tcl file, but this is deprecated because it's harder to make portable.</p></dd><dt><span class="term">$table_def</span></dt><dd><p>Here we pass in the variable we just constructed; it contains a list of column names and display titles.</p></dd></dl></div></li></ul></div><p>Put the database query into a separate file. If the
database query is exactly the same for Oracle and PostgreSQL, it
can go into a file with the same name as the tcl file but an xql
- extension, e.g., <tt>index.xql</tt>. If
+ extension, e.g., <tt class="computeroutput">index.xql</tt>. If
it is database-specific, it goes in
- <tt>index-oracle.xql</tt> or
- <tt>index-postgresql.xql</tt>. The
+ <tt class="computeroutput">index-oracle.xql</tt> or
+ <tt class="computeroutput">index-postgresql.xql</tt>. The
format is the same in each case, an XML structure that contains
- the SQL query. Create the file now.</p><pre class="screen">[service0@yourserver www]$<b><tt> emacs index.xql</tt></b></pre><p>Note that the
- <tt>name</tt> parameter of the
- <tt>fullquery</tt> tag exactly matches
+ the SQL query. Create the file now.</p><pre class="screen">[service0@yourserver www]$<b class="userinput"><tt> emacs index.xql</tt></b></pre><p>Note that the
+ <tt class="computeroutput">name</tt> parameter of the
+ <tt class="computeroutput">fullquery</tt> tag exactly matches
the SQL query name specified in the
- <tt>ad_table</tt> call. Also, the SQL query ends with a tcl function call that generates a SQL ORDER BY clause using several TCL variables. </p><pre class="programlisting"><?xml version="1.0"?>
+ <tt class="computeroutput">ad_table</tt> call. Also, the SQL query ends with a tcl function call that generates a SQL ORDER BY clause using several TCL variables. </p><pre class="programlisting"><?xml version="1.0"?>
<queryset>
- <fullquery name="notes_query">
+ <fullquery name="notes_query">
<querytext>
select note_id,
title,
@@ -67,26 +66,26 @@
[ad_order_by_from_sort_spec $orderby $table_def]
</querytext>
</fullquery>
-</queryset></pre><p>Create the user-visible page.</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs index.adp</tt></b></pre><p>The first line indicates that this page should be rendered within the the master template, which defaults to <tt>/web/service0/www/default-master</tt>. The second line passes a <tt>title</tt> variable to the master template. The third line inserts the contents of the variable <tt>table_html</tt>. The last line is a link to a page we haven't created yet.</p><pre class="programlisting"><master>
-<property name="title">Sample Notes</property>
+</queryset></pre><p>Create the user-visible page.</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs index.adp</tt></b></pre><p>The first line indicates that this page should be rendered within the the master template, which defaults to <tt class="computeroutput">/web/service0/www/default-master</tt>. The second line passes a <tt class="computeroutput">title</tt> variable to the master template. The third line inserts the contents of the variable <tt class="computeroutput">table_html</tt>. The last line is a link to a page we haven't created yet.</p><pre class="programlisting"><master>
+<property name="title">Sample Notes</property>
@table_html@
-<p><a href="note-edit">Add a note</a></p></pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2914976"></a>Making the APM load your files</h3></div></div><p>Before we can test these files, we have to notify the
+<p><a href="note-edit">Add a note</a></p></pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2841987"></a>Making the APM load your files</h3></div></div><div></div></div><p>Before we can test these files, we have to notify the
package manager that they exist. (More precisely, the tcl and
adp will work fine as-is, but the xql file will not be
- recognized until we tell the APM about it.).</p><div class="itemizedlist"><ul type="disc"><li><p> Go to <tt>http://yourserver.test:8000/acs-admin/apm</tt></p></li><li><p>Click on the <tt>samplenote</tt> link</p></li><li><p>Click <tt>Manage file information</tt></p></li><li><p>
+ recognized until we tell the APM about it.).</p><div class="itemizedlist"><ul type="disc"><li><p> Go to <tt class="computeroutput">http://yourserver.test:8000/acs-admin/apm</tt></p></li><li><p>Click on the <tt class="computeroutput">samplenote</tt> link</p></li><li><p>Click <tt class="computeroutput">Manage file information</tt></p></li><li><p>
Check the values in the file type column for your files. A
question mark means the APM doesn't recognize the file
type and probably means you have mistyped a filename.
</p></li><li><p>
At the bottom of the file list page - click on the
- <tt>watch all files</tt> link.
+ <tt class="computeroutput">watch all files</tt> link.
Unlike adp and tcl pages, xql pages get cached. (And new
xql files don't get loaded when they're watched or the
server is restarted.) Watching an xql file causes the APM
to load the contents of the XQL into memory so that it can
be used, and to reload it whenever the file is changed.
The watch will last until the server is restarted.
- </p></li></ul></div><p>Now that the APM is aware of your files, check to make sure that the self-documenting code is working.</p><div class="itemizedlist"><ul type="disc"><li><p>Browse to <tt>http://yourserver.test:8000/api-doc/</tt></p></li><li><p>Click <tt>Notes 0.1d</tt></p></li><li><p>Click <tt>Content Pages</tt></p></li><li><p>Click <tt>index.tcl</tt> and examine the results.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2910349"></a>Test the index page</h3></div></div><p>Go to <tt>http://<span class="replaceable">yourserver.test:8000</span>/note/</tt>. You should see this:</p><pre class="screen">
+ </p></li></ul></div><p>Now that the APM is aware of your files, check to make sure that the self-documenting code is working.</p><div class="itemizedlist"><ul type="disc"><li><p>Browse to <tt class="computeroutput">http://yourserver.test:8000/api-doc/</tt></p></li><li><p>Click <tt class="computeroutput">Notes 0.1d</tt></p></li><li><p>Click <tt class="computeroutput">Content Pages</tt></p></li><li><p>Click <tt class="computeroutput">index.tcl</tt> and examine the results.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2838065"></a>Test the index page</h3></div></div><div></div></div><p>Go to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test:8000</span></span>/note/</tt>. You should see this:</p><pre class="screen">
Sample Notes
Your Workspace : Main Site : Sample Note
@@ -95,39 +94,39 @@
Add a note.
foo@yourserver.test
-</pre><p>Since our table is empty, it's a pretty boring page. So next we'll make it possible to add records. </p><p>If you get any other output, such as an error message, skip to <a href="tutorial-debug.html" title="Debugging and Automated Testing">the section called “Debugging and Automated Testing”</a>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2910399"></a>Add the add/edit page</h3></div></div><p>We'll create a single page to handle both adding and
+</pre><p>Since our table is empty, it's a pretty boring page. So next we'll make it possible to add records. </p><p>If you get any other output, such as an error message, skip to <a href="tutorial-debug.html" title="Debugging and Automated Testing">Section�, “Debugging and Automated Testing”</a>.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2838109"></a>Add the add/edit page</h3></div></div><div></div></div><p>We'll create a single page to handle both adding and
editing records. In this recursive approach, the same tcl
function can present a blank HTML form, present the same form
pre-loaded with an existing record, and handle the resulting
submission of either updated or new records. This recursive
approach reduces the total amount of code and files. First,
- create the tcl:</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs note-edit.tcl</tt></b></pre><p>Paste and save and edit:</p><pre class="programlisting">ad_page_contract {
+ create the tcl:</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs note-edit.tcl</tt></b></pre><p>Paste and save and edit:</p><pre class="programlisting">ad_page_contract {
Simple add/edit form for samplenote.
} {
note_id:integer,optional
}
set user_id [ad_maybe_redirect_for_registration]
-set title "Add a note"
+set title "Add a note"
if {[exists_and_not_null note_id]} {
- set title "Edit a note"
+ set title "Edit a note"
}
ad_form -name note -form {
note_id:key
{title:text
- {label "Title"}
+ {label "Title"}
}
{body:text(textarea)
- {label "Body"}
+ {label "Body"}
}
} -select_query_name note_query -new_data {
db_1row do_insert { *SQL* }
} -edit_data {
db_dml do_update { *SQL* }
} -after_submit {
-ad_returnredirect "index"
-}</pre><p>We use <tt><a href="/api-doc/proc-view?proc=ad_form" target="_top">ad_form</a></tt>
+ad_returnredirect "index"
+}</pre><p>We use <tt class="computeroutput"><a href="/api-doc/proc-view?proc=ad_form" target="_top">ad_form</a></tt>
to automate most of the work here. Ad_form is a wrapper for the
<a href="/api-doc/proc-view?proc=template%3a%3aform" target="_top">template
functions</a> for creating HTML forms. These functions should
@@ -136,45 +135,45 @@
the appearance of forms. </p><p>The page takes a single, optional input parameter,
note_id. If it's present, ad_form will assume that we're editing
an existing record, look up that record, and pre-populate the
- form. We'll also check and change the page title if necessary. We check user_id with <tt><a href="/api-doc/proc-view?proc=ad_maybe_redirect_for_registration" target="_top">ad_maybe_redirect_for_registration</a></tt>,
+ form. We'll also check and change the page title if necessary. We check user_id with <tt class="computeroutput"><a href="/api-doc/proc-view?proc=ad_maybe_redirect_for_registration" target="_top">ad_maybe_redirect_for_registration</a></tt>,
which will redirect to the login page (with an automatic return
path to bring them back after login or registration) if the
visitor isn't logged in. Then we call ad_form, specifying the
primary key of the table, the fields we want to edit, and
- functions for insert and update.</p><p>Next, we create the database functions.</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs note-edit.xql</tt></b></pre><pre class="programlisting"><?xml version="1.0"?>
+ functions for insert and update.</p><p>Next, we create the database functions.</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs note-edit.xql</tt></b></pre><pre class="programlisting"><?xml version="1.0"?>
<queryset>
- <fullquery name="do_insert">
+ <fullquery name="do_insert">
<querytext>
select samplenote__new(null,:title, :body,null,:user_id,null,null)
</querytext>
</fullquery>
- <fullquery name="do_update">
+ <fullquery name="do_update">
<querytext>
update samplenote
set title = :title,
body = :body
where note_id = :note_id
</querytext>
</fullquery>
- <fullquery name="note_query">
+ <fullquery name="note_query">
<querytext>
select title,
body
from samplenote
where note_id = :note_id
</querytext>
</fullquery>
-</queryset></pre><p>Create the user-visible page:</p><pre class="screen">[service0@yourserver www]$ <b><tt>emacs note-edit.adp</tt></b></pre><pre class="programlisting"><master>
-<property name="title">@title@</property>
-<property name="context">{@title@}</property>
-<formtemplate id="note"></formtemplate>
+</queryset></pre><p>Create the user-visible page:</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>emacs note-edit.adp</tt></b></pre><pre class="programlisting"><master>
+<property name="title">@title@</property>
+<property name="context">{@title@}</property>
+<formtemplate id="note"></formtemplate>
</pre><p>The property tags are passed to the master template, which
uses their values to set the page title and context bar
(breadcrumb trail). We use the same variable,
- <tt>title</tt>, for both variables but
+ <tt class="computeroutput">title</tt>, for both variables but
wrap it in curly brackets for context so that the spaces aren't
interpreted separators. The formtemplate tag outputs the form
- html with the matching name.</p><p>Go to the APM as before and reload. Then test all this by going to the package home page and adding and editing a few records.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2930303"></a>Adding files to cvs</h3></div></div><p>Put your new work into source control.</p><pre class="screen">[service0@yourserver www]$ <b><tt>cvs add *.adp *.tcl *.xql</tt></b>
+ html with the matching name.</p><p>Go to the APM as before and reload. Then test all this by going to the package home page and adding and editing a few records.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2838275"></a>Adding files to cvs</h3></div></div><div></div></div><p>Put your new work into source control.</p><pre class="screen">[service0@yourserver www]$ <b class="userinput"><tt>cvs add *.adp *.tcl *.xql</tt></b>
cvs add: cannot add special file `CVS'; skipping
cvs add: doc/CVS already exists
cvs add: scheduling file `index.adp' for addition
@@ -184,7 +183,7 @@
cvs add: scheduling file `note-edit.tcl' for addition
cvs add: scheduling file `note-edit.xql' for addition
cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver www]$ <b><tt> cvs commit -m "new work"</tt></b>
+[service0@yourserver www]$ <b class="userinput"><tt> cvs commit -m "new work"</tt></b>
/cvsroot/service0/packages/samplenote/www/note-edit.xql~,v <-- note-edit.xql
<span class="emphasis"><em>(many lines omitted)</em></span>
initial revision: 1.1
Index: openacs-4/packages/acs-core-docs/www/tutorial.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/tutorial.html 28 Jun 2003 05:07:03 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/tutorial.html 14 Oct 2003 11:02:59 -0000 1.4
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�10.�Development Tutorial</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="next" href="tutorial-newpackage.html" title="Creating a Package"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="tutorial"></a>Chapter�10.�Development Tutorial</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="tutorial-newpackage.html">Creating a Package</a></dt><dt><a href="tutorial-database.html">Setting Up Database Objects</a></dt><dt><a href="tutorial-pages.html">Creating Web Pages</a></dt><dt><a href="tutorial-debug.html">Debugging and Automated Testing</a></dt><dt><a href="tutorial-advanced.html">Advanced Topics</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr><tr><td width="40%" align="left">Part�III.�For OpenACS Package Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Creating a Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tutorial.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�10.�Development Tutorial</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="previous" href="acs-package-dev.html" title="Part�III.�For OpenACS Package Developers"><link rel="next" href="tutorial-newpackage.html" title="Creating a Package"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><th width="60%" align="center">Part�III.�For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="tutorial"></a>Chapter�10.�Development Tutorial</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="tutorial-newpackage.html">Creating a Package</a></dt><dt><a href="tutorial-database.html">Setting Up Database Objects</a></dt><dt><a href="tutorial-pages.html">Creating Web Pages</a></dt><dt><a href="tutorial-debug.html">Debugging and Automated Testing</a></dt><dt><a href="tutorial-advanced.html">Advanced Topics</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr><tr><td width="40%" align="left">Part�III.�For OpenACS Package Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Creating a Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/tutorial.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/unix-install.html 20 Aug 2003 16:20:17 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/unix-install.html 14 Oct 2003 11:02:59 -0000 1.12
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�4.�Installing on Unix/Linux</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="individual-programs.html" title="Individual Programs"><link rel="next" href="install-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="unix-install"></a>Chapter�4.�Installing on Unix/Linux</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="linux-installation.html">Install Linux and supporting software</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostGreSQL</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3oacs1</a></dt><dt><a href="openacs.html">Install OpenACS 5.0.0d</a></dt><dt><a href="credits.html">Credits</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Individual Programs </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/unix-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�4.�Installing on Unix/Linux</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="individual-programs.html" title="Individual Programs"><link rel="next" href="install-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="unix-install"></a>Chapter�4.�Installing on Unix/Linux</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="linux-installation.html">Install Linux and supporting software</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostGreSQL</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3oacs1</a></dt><dt><a href="openacs.html">Install OpenACS 5.0.0a1</a></dt><dt><a href="credits.html">Credits</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Individual Programs </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/unix-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/upgrade-detail.html 20 Aug 2003 16:20:17 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/upgrade-detail.html 14 Oct 2003 11:02:59 -0000 1.7
@@ -1,5 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Support for upgrades.</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="upgrade.html" title="Chapter�8.�Upgrading"><link rel="previous" href="upgrade.html" title="Chapter�8.�Upgrading"><link rel="next" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><th width="60%" align="center">Chapter�8.�Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="maintenance.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="upgrade-detail"></a>Support for upgrades.</h2></div></div><div class="authorblurb"><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Support for upgrades.</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="upgrade.html" title="Chapter�8.�Upgrading"><link rel="previous" href="upgrade.html" title="Chapter�8.�Upgrading"><link rel="next" href="maintenance.html" title="Chapter�9.�Maintenance"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><th width="60%" align="center">Chapter�8.�Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="maintenance.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-detail"></a>Support for upgrades.</h2></div></div><div></div></div><div class="authorblurb"><p>
by <a href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -8,18 +7,18 @@
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.</p><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="upgrade-4.5-to-4.6"></a>Checklist</h3></div></div><p>The required platform for OpenACS 4.6 is the same as
+ OpenACS prior to 4.5, upgrading will require manual effort.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="upgrade-4.5-to-4.6"></a>Checklist</h3></div></div><div></div></div><p>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.</p><div class="itemizedlist"><ul type="circle"><li style="list-style-type: circle"><p>A computer with OpenACS 4.5.</p></li><li style="list-style-type: circle"><p><a href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 4.6 tarball</a></p></li><li style="list-style-type: circle"><p>Required for Full Text Search on PostGreSQL: <a href="http://openfts.sourceforge.net" target="_top">OpenFTS 0.3.2</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2873661"></a>Overview</h3></div></div><p>OpenACS consists of files and a database schema. The files
+ OpenACS 4.6 does not support PostGreSQL 7.3.</p><div class="itemizedlist"><ul type="circle"><li style="list-style-type: circle"><p>A computer with OpenACS 4.5.</p></li><li style="list-style-type: circle"><p><a href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 4.6 tarball</a></p></li><li style="list-style-type: circle"><p>Required for Full Text Search on PostGreSQL: <a href="http://openfts.sourceforge.net" target="_top">OpenFTS 0.3.2</a></p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2828943"></a>Overview</h3></div></div><div></div></div><p>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.</p><div class="figure"><a name="id2873680"></a><p class="title"><b>Figure�8.1.�Assumptions in this section</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>name of OpenACS user</td><td><span class="replaceable">nsadmin</span></td></tr><tr><td>OpenACS server name</td><td><span class="replaceable">openacs-dev</span></td></tr><tr><td>Root of OpenACS file tree</td><td><span class="replaceable">/web/openacs-dev</span></td></tr><tr><td>Database backup directory</td><td><span class="replaceable">/backup/openacs/</span></td></tr></tbody></table></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2948725"></a><a class="indexterm" name="id2948728"></a>Upgrading on Linux/Unix</h3></div></div><div class="orderedlist"><ol type="1"><li><p><b>Make a Backup.�</b>Back up the database and file system (see <a href="backup-recovery.html#snapshot-backup" title="Snapshot backup and recovery">the section called “Snapshot backup and recovery”</a>).</p></li><li><p><b>OPTIONAL: Upgrade OpenFTS.�</b>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 -
+ complete.</p><div class="figure"><a name="id2828962"></a><p class="title"><b>Figure�8.1.�Assumptions in this section</b></p><div class="informaltable"><table cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>name of OpenACS user</td><td><span class="replaceable"><span class="replaceable">nsadmin</span></span></td></tr><tr><td>OpenACS server name</td><td><span class="replaceable"><span class="replaceable">openacs-dev</span></span></td></tr><tr><td>Root of OpenACS file tree</td><td><span class="replaceable"><span class="replaceable">/web/openacs-dev</span></span></td></tr><tr><td>Database backup directory</td><td><span class="replaceable"><span class="replaceable">/backup/openacs/</span></span></td></tr></tbody></table></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2829046"></a><a class="indexterm" name="id2829048"></a>Upgrading on Linux/Unix</h3></div></div><div></div></div><div class="orderedlist"><ol type="1"><li><p><b>Make a Backup.�</b>Back up the database and file system (see <a href="backup-recovery.html#snapshot-backup" title="Snapshot backup and recovery">Section�, “Snapshot backup and recovery”</a>).</p></li><li><p><b>OPTIONAL: Upgrade OpenFTS.�</b>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.
-</p><div class="orderedlist"><ol type="a"><li><p>Uninstall the old OpenFTS Engine</p><div class="orderedlist"><ol type="i"><li><p><span class="bold"><b>Browse to <tt>http://<span class="replaceable">yourserver</span>/openfts</tt>.</b></span>
-</p></li><li><p><span class="bold"><b>Click <tt><span class="guilabel">Administration</span></tt>.</b></span></p></li><li><p><span class="bold"><b>Click <tt><span class="guibutton">Drop OpenFTS Engine</span></tt></b></span></p></li></ol></div></li><li><p>Build and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.)</p><pre class="screen">cd /usr/local/src/
+</p><div class="orderedlist"><ol type="a"><li><p>Uninstall the old OpenFTS Engine</p><div class="orderedlist"><ol type="i"><li><p><span class="bold"><b>Browse to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/openfts</tt>.</b></span>
+</p></li><li><p><span class="bold"><b>Click <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></tt>.</b></span></p></li><li><p><span class="bold"><b>Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Drop OpenFTS Engine</span></span></tt></b></span></p></li></ol></div></li><li><p>Build and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.)</p><pre class="screen">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/
@@ -37,64 +36,64 @@
cd tsearch/
make
make install
-exit</pre><p>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.</p><pre class="screen">[root@localhost root]# <b><tt>su - nsadmin</tt></b>
-[nsadmin@localhost dev]$ <b><tt>psql <span class="replaceable">openacs-dev</span> -f /usr/local/pgsql/share/contrib/openfts.sql</tt></b>
+exit</pre><p>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.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - nsadmin</tt></b>
+[nsadmin@localhost dev]$ <b class="userinput"><tt>psql <span class="replaceable"><span class="replaceable">openacs-dev</span></span> -f /usr/local/pgsql/share/contrib/openfts.sql</tt></b>
CREATE
CREATE
-[nsadmin@localhost dev]$ <b><tt>psql <span class="replaceable">openacs-dev</span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</tt></b>
+[nsadmin@localhost dev]$ <b class="userinput"><tt>psql <span class="replaceable"><span class="replaceable">openacs-dev</span></span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</tt></b>
BEGIN
CREATE
(~30 more lines)
-[nsadmin@localhost dev]$ <b><tt>exit</tt></b>
+[nsadmin@localhost dev]$ <b class="userinput"><tt>exit</tt></b>
[root@localhost root]#
-<pre class="action">su - nsadmin
-psql <span class="replaceable">openacs-dev</span> -f /usr/local/pgsql/share/contrib/openfts.sql
-psql <span class="replaceable">openacs-dev</span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
-exit</pre></pre></li></ol></div></li><li><p><b>Stop the server.�</b></p><pre class="screen">[root@localhost root]# <b><tt>svc -d /service/<span class="replaceable">openacs-dev</span></tt></b></pre></li><li><p><b>Upgrade the file tree.�</b>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.</p><div class="itemizedlist"><ul type="disc"><li><p><b>Upgrading files without CVS.�</b>Unpack the tarball into a new directory and copy its contents on top of your working directory.</p><pre class="screen">[root@localhost root]# <b><tt>su - nsadmin</tt></b>
-[nsadmin@localhost aolserver]$ <b><tt>cd /web</tt></b>
-[nsadmin@localhost web]$ <b><tt>tar xzf /tmp/openacs-4-6.tgz</tt></b>
-[nsadmin@localhost web]$ <b><tt>cp -r openacs-4-6/* openacs-4</tt></b>
-[nsadmin@localhost openacs-upgrade]$ <b><tt>exit</tt></b>
+<pre class="action"><span class="action">su - nsadmin
+psql <span class="replaceable"><span class="replaceable">openacs-dev</span></span> -f /usr/local/pgsql/share/contrib/openfts.sql
+psql <span class="replaceable"><span class="replaceable">openacs-dev</span></span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
+exit</span></pre></pre></li></ol></div></li><li><p><b>Stop the server.�</b></p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>svc -d /service/<span class="replaceable"><span class="replaceable">openacs-dev</span></span></tt></b></pre></li><li><p><b>Upgrade the file tree.�</b>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.</p><div class="itemizedlist"><ul type="disc"><li><p><b>Upgrading files without CVS.�</b>Unpack the tarball into a new directory and copy its contents on top of your working directory.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - nsadmin</tt></b>
+[nsadmin@localhost aolserver]$ <b class="userinput"><tt>cd /web</tt></b>
+[nsadmin@localhost web]$ <b class="userinput"><tt>tar xzf /tmp/openacs-4-6.tgz</tt></b>
+[nsadmin@localhost web]$ <b class="userinput"><tt>cp -r openacs-4-6/* openacs-4</tt></b>
+[nsadmin@localhost openacs-upgrade]$ <b class="userinput"><tt>exit</tt></b>
[root@localhost root]#
-<pre class="action">su - nsadmin
+<pre class="action"><span class="action">su - nsadmin
cd /web
tar xzf /tmp/openacs-4-6.tgz
cp -r openacs-4-6/* openacs-4
-exit</pre></pre></li><li><p><b>Upgrading files with CVS.�</b></p><div class="orderedlist"><ol type="a"><li><p>Unpack the new files into a working directory.</p><pre class="screen">[root@localhost root]# <b><tt>su - nsadmin</tt></b>
-[nsadmin@localhost aolserver]$ <b><tt>cd /tmp</tt></b>
-[nsadmin@localhost tmp]$ <b><tt>tar xzv openacs-4-6.tgz</tt></b>
-[nsadmin@localhost tmp]$ <b><tt>cd openacs-4.6</tt></b>
-</pre><p>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</p><pre class="screen">[nsadmin@localhost openacs-4.6]$ <b><tt> cvs import -m "upgrade to OpenACS 4.6" openacs
-OpenACS openacs-4-6</tt></b></pre><p>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.</p><pre class="screen">[nsadmin@localhost openacs-4.6]$ <b><tt> cd /web</tt></b>
-[nsadmin@localhost tmp]$ <b><tt>mkdir openacs-upgrade</tt></b>
-[nsadmin@localhost tmp]$ <b><tt>cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > cvs.txt 2>&1</tt></b>
+exit</span></pre></pre></li><li><p><b>Upgrading files with CVS.�</b></p><div class="orderedlist"><ol type="a"><li><p>Unpack the new files into a working directory.</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>su - nsadmin</tt></b>
+[nsadmin@localhost aolserver]$ <b class="userinput"><tt>cd /tmp</tt></b>
+[nsadmin@localhost tmp]$ <b class="userinput"><tt>tar xzv openacs-4-6.tgz</tt></b>
+[nsadmin@localhost tmp]$ <b class="userinput"><tt>cd openacs-4.6</tt></b>
+</pre><p>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</p><pre class="screen">[nsadmin@localhost openacs-4.6]$ <b class="userinput"><tt> cvs import -m "upgrade to OpenACS 4.6" openacs
+OpenACS openacs-4-6</tt></b></pre><p>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.</p><pre class="screen">[nsadmin@localhost openacs-4.6]$ <b class="userinput"><tt> cd /web</tt></b>
+[nsadmin@localhost tmp]$ <b class="userinput"><tt>mkdir openacs-upgrade</tt></b>
+[nsadmin@localhost tmp]$ <b class="userinput"><tt>cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > cvs.txt 2>&1</tt></b>
(CVS feedback here)
-<pre class="action">su - nsadmin
+<pre class="action"><span class="action">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
+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
-</pre></pre></li><li><p>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 <tt>M-x sort-lines</tt> 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.</p></li><li><p>Once you've fixed any conflicts, commit the new code
- to your local tree. </p><pre class="screen">[nsadmin@localhost tmp]$ <b><tt>cd openacs-upgrade</tt></b>
-[nsadmin@localhost openacs-upgrade]$ <b><tt>cvs commit -m "Upgraded to 4.6"</tt></b>
-<pre class="action">cd openacs-upgrade
-cvs commit -m "Upgraded to 4.6"</pre></pre></li><li><p>Update your working tree with the new
+</span></pre></pre></li><li><p>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 <tt class="computeroutput">M-x sort-lines</tt> 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.</p></li><li><p>Once you've fixed any conflicts, commit the new code
+ to your local tree. </p><pre class="screen">[nsadmin@localhost tmp]$ <b class="userinput"><tt>cd openacs-upgrade</tt></b>
+[nsadmin@localhost openacs-upgrade]$ <b class="userinput"><tt>cvs commit -m "Upgraded to 4.6"</tt></b>
+<pre class="action"><span class="action">cd openacs-upgrade
+cvs commit -m "Upgraded to 4.6"</span></pre></pre></li><li><p>Update your working tree with the new
files. The CVS flags ensure that new directories are created and pruned directories destroyed.</p><pre class="screen">
-[nsadmin@localhost openacs-upgrade]$ <b><tt>cd /web/<span class="replaceable">openacs-dev</span></tt></b>
-[nsadmin@localhost openacs-dev]$ <b><tt>cvs up -Pd</tt></b>
+[nsadmin@localhost openacs-upgrade]$ <b class="userinput"><tt>cd /web/<span class="replaceable"><span class="replaceable">openacs-dev</span></span></tt></b>
+[nsadmin@localhost openacs-dev]$ <b class="userinput"><tt>cvs up -Pd</tt></b>
(CVS feedback)
-[nsadmin@localhost openacs-dev]$ <b><tt>exit</tt></b>
+[nsadmin@localhost openacs-dev]$ <b class="userinput"><tt>exit</tt></b>
[root@localhost root]#
-<pre class="action">cd /web/<span class="replaceable">openacs-dev</span>
+<pre class="action"><span class="action">cd /web/<span class="replaceable"><span class="replaceable">openacs-dev</span></span>
cvs up -Pd
-exit</pre></pre></li></ol></div></li></ul></div></li><li><p><b>Start the server.�</b></p><pre class="screen">[root@localhost root]# <b><tt>svc -u /service/<span class="replaceable">openacs-dev</span></tt></b></pre></li><li><p><b>Use APM to upgrade the database.�</b></p><div class="orderedlist"><ol type="a"><li><p>Browse to the package manager, <tt>http://<span class="replaceable">yourserver</span>/acs-admin/apm</tt>.</p></li><li><p>Click <tt><span class="guilabel">Install packages.</span></tt></p></li><li><p>Select the packages you want to install. This should
+exit</span></pre></pre></li></ol></div></li></ul></div></li><li><p><b>Start the server.�</b></p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>svc -u /service/<span class="replaceable"><span class="replaceable">openacs-dev</span></span></tt></b></pre></li><li><p><b>Use APM to upgrade the database.�</b></p><div class="orderedlist"><ol type="a"><li><p>Browse to the package manager, <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/acs-admin/apm</tt>.</p></li><li><p>Click <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Install packages.</span></span></tt></p></li><li><p>Select the packages you want to install. This should
be everything that says
- <tt>upgrade</tt>, plus any new
+ <tt class="computeroutput">upgrade</tt>, plus any new
packages you want. It's safest to upgrade the kernel by
itself, and then come back and upgrade the rest of the
- desired packages in a second pass.</p></li><li><p>On the next screen, click <tt><span class="guibutton">Install Packages</span></tt></p></li><li><p>When prompted, restart the server:</p><pre class="screen">[root@localhost root]# <b><tt>restart-aolserver <span class="replaceable">openacs-dev</span></tt></b></pre></li><li><p>Wait a minute, then browse to the package manager, <tt>http://<span class="replaceable">yourserver</span>/acs-admin/apm</tt>.</p></li><li><p>Check that the kernel upgrade worked by clicking <tt><span class="guilabel">All</span></tt> and making sure that <tt>acs-kernel</tt> version is 5.0.0d.</p></li></ol></div></li><li><p><b>OPTIONAL: Install the new OpenFTS Engine.�</b>If you want to upgrade the OpenFTS Engine, do these
+ desired packages in a second pass.</p></li><li><p>On the next screen, click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Install Packages</span></span></tt></p></li><li><p>When prompted, restart the server:</p><pre class="screen">[root@localhost root]# <b class="userinput"><tt>restart-aolserver <span class="replaceable"><span class="replaceable">openacs-dev</span></span></tt></b></pre></li><li><p>Wait a minute, then browse to the package manager, <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/acs-admin/apm</tt>.</p></li><li><p>Check that the kernel upgrade worked by clicking <tt class="computeroutput"><span class="guilabel"><span class="guilabel">All</span></span></tt> and making sure that <tt class="computeroutput">acs-kernel</tt> version is 5.0.0a1.</p></li></ol></div></li><li><p><b>OPTIONAL: Install the new OpenFTS Engine.�</b>If you want to upgrade the OpenFTS Engine, do these
steps. (You must have already upgraded the OpenFTS driver to
- 0.3.2.)</p><div class="orderedlist"><ol type="a"><li><p>Browse to <tt>http://<span class="replaceable">yourserver</span>/admin/site-map</tt></p></li><li><p>On the <tt>openfts</tt> line, click on <tt><span class="guilabel">set parameters</span></tt>.</p></li><li><p>Change the value of <tt>openfts_tcl_src_path</tt> from <tt>/usr/local/src/Search-OpenFTS-tcl-0.2/</tt> to <tt>/usr/local/src/Search-OpenFTS-tcl-0.3.2/</tt></p></li><li><p>Click <tt><span class="guibutton">Set Parameters</span></tt></p></li><li><pre class="screen">[root@localhost root]# restart-aolserver <span class="replaceable">openacs-dev</span></pre></li><li><p>Browse to <tt>http://<span class="replaceable">yourserver</span>/openfts</tt></p></li><li><p><span class="bold"><b>Click <tt><span class="guilabel">Administration</span></tt>.</b></span></p></li><li><p><span class="bold"><b>Click <tt><span class="guibutton">Initialize OpenFTS Engine</span></tt></b></span></p></li></ol></div></li><li><p><b>Rollback.�</b>If anything goes wrong, <a href="backup-recovery.html#rollback-database">roll back</a> to the backup snapshot.</p></li></ol></div></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�8.�Upgrading </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Chapter�9.�Maintenance</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/upgrade-detail.html#comments">View comments on this page at openacs.org</a></center></body></html>
+ 0.3.2.)</p><div class="orderedlist"><ol type="a"><li><p>Browse to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/admin/site-map</tt></p></li><li><p>On the <tt class="computeroutput">openfts</tt> line, click on <tt class="computeroutput"><span class="guilabel"><span class="guilabel">set parameters</span></span></tt>.</p></li><li><p>Change the value of <tt class="computeroutput">openfts_tcl_src_path</tt> from <tt class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.2/</tt> to <tt class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.3.2/</tt></p></li><li><p>Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Set Parameters</span></span></tt></p></li><li><pre class="screen">[root@localhost root]# restart-aolserver <span class="replaceable"><span class="replaceable">openacs-dev</span></span></pre></li><li><p>Browse to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/openfts</tt></p></li><li><p><span class="bold"><b>Click <tt class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></tt>.</b></span></p></li><li><p><span class="bold"><b>Click <tt class="computeroutput"><span class="guibutton"><span class="guibutton">Initialize OpenFTS Engine</span></span></tt></b></span></p></li></ol></div></li><li><p><b>Rollback.�</b>If anything goes wrong, <a href="backup-recovery.html#rollback-database">roll back</a> to the backup snapshot.</p></li></ol></div></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�8.�Upgrading </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Chapter�9.�Maintenance</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/upgrade-detail.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/upgrade.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/upgrade.html 20 Aug 2003 16:20:17 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/upgrade.html 14 Oct 2003 11:02:59 -0000 1.7
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�8.�Upgrading</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="configure.html" title="Chapter�7.�Configuring a New Service"><link rel="next" href="upgrade-detail.html" title="Support for upgrades."><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configure.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-detail.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="upgrade"></a>Chapter�8.�Upgrading</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="upgrade-detail.html">Support for upgrades.</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configure.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-detail.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�7.�Configuring a New Service </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Support for upgrades.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/upgrade.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�8.�Upgrading</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="configure.html" title="Chapter�7.�Configuring a New Service"><link rel="next" href="upgrade-detail.html" title="Support for upgrades."><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configure.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-detail.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="upgrade"></a>Chapter�8.�Upgrading</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="upgrade-detail.html">Support for upgrades.</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configure.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-detail.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�7.�Configuring a New Service </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Support for upgrades.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/upgrade.html#comments">View comments on this page at openacs.org</a></center></body></html>
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 -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/win-install.html 28 Jun 2003 05:07:03 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/win-install.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,2 +1 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�5.�Installing on Windows</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="credits.html" title="Credits"><link rel="next" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="win-install"></a>Chapter�5.�Installing on Windows</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Credits </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Windows2000</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/win-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�5.�Installing on Windows</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part�II.�Administrator's Guide"><link rel="previous" href="credits.html" title="Credits"><link rel="next" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><th width="60%" align="center">Part�II.�Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="win-install"></a>Chapter�5.�Installing on Windows</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Credits </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Windows2000</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/win-install.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/win2k-installation.html 20 Aug 2003 16:20:17 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/win2k-installation.html 14 Oct 2003 11:02:59 -0000 1.13
@@ -1,16 +1,15 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Installation Guide for Windows2000</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="previous" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="next" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><th width="60%" align="center">Chapter�5.�Installing on Windows</th><td width="20%" align="right"> <a accesskey="n" href="mac-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="win2k-installation"></a>OpenACS Installation Guide for Windows2000</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:mburke@arsdigita.com" target="_top">Matthew Burke</a> and <a href="mailto:curtisg@arsdigita.com" target="_top">Curtis Galloway</a></p><br>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Installation Guide for Windows2000</title><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="previous" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="next" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><th width="60%" align="center">Chapter�5.�Installing on Windows</th><td width="20%" align="right"> <a accesskey="n" href="mac-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="win2k-installation"></a>OpenACS Installation Guide for Windows2000</h2></div></div><div></div></div><div class="authorblurb"><p><p>By <a href="mailto:mburke@arsdigita.com" target="_top">Matthew Burke</a> and <a href="mailto:curtisg@arsdigita.com" target="_top">Curtis Galloway</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p><span class="strong">NOTE:</span> These instructions were
valid for ACS v4, but have not been tested with OpenACS. Currently
- (8/2002), the best option to get OpenACS 5.0.0d running on Windows
+ (8/2002), the best option to get OpenACS 5.0.0a1 running on Windows
is to use <a href="http://vmware.com" target="_top">VMware</a> and John
Sequeira's <a href="http://www.pobox.com/~johnseq/projects/oasisvm/" target="_top">Oasis VM
distribution</a>
</p><div class="itemizedlist"><ul type="disc"><li><p>Source: <a href="http://software.arsdigita.com/dist" target="_top">http://software.arsdigita.com/dist</a></p></li><li><p>Bug reports: <a href="mailto:acs-bugs@arsdigita.com" target="_top">acs-bugs@arsdigita.com</a></p></li><li><p>Philosophy: <a href="http://photo.net/wtr/thebook/community" target="_top">http://photo.net/wtr/thebook/community</a>
(the community chapter of <span class="emphasis"><em>Philip and Alex's Guide to Web
- Publishing</em></span>)</p></li><li><p>Technical background: <a href="http://photo.net/wtr/thebook/" target="_top">http://photo.net/wtr/thebook/</a></p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-overview"></a>Overview</h3></div></div><p>
+ Publishing</em></span>)</p></li><li><p>Technical background: <a href="http://photo.net/wtr/thebook/" target="_top">http://photo.net/wtr/thebook/</a></p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-overview"></a>Overview</h3></div></div><div></div></div><p>
With the recent release of a win32 version of AOLserver, it is now
possible to run the OpenACS on Windows2000 and Windows98. This document
explains the steps necessary to get the OpenACS installed and running on your
@@ -22,25 +21,25 @@
for the Win32 platform, which contains patches for several problems we
have come across in the default AOLserver binary distribution. See <a href="/aol3" target="_top">the ArsDigita AOLserver 3 distribution page</a> for
details.</p><p>You can download the binary distribution from <a href="http://arsdigita.com/download" target="_top">the ArsDigita download page</a>
- under "ArsDigita AOLserver 3 Binary Distribution for Win32."
+ under "ArsDigita AOLserver 3 Binary Distribution for Win32."
Please read the release notes in the distribution for configuration notes
- specific to the version you are downloading.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-prerequisites"></a>Prerequisites</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Windows 2000 or Windows 98</p></li><li><p><a href="http://www.winzip.com" target="_top">WinZip</a> or any tool that can
+ specific to the version you are downloading.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-prerequisites"></a>Prerequisites</h3></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>Windows 2000 or Windows 98</p></li><li><p><a href="http://www.winzip.com" target="_top">WinZip</a> or any tool that can
extract gzipped/tarred archives.</p></li><li><p><a href="ftp://ftp.blarg.net/users/amol/zsh" target="_top">zsh</a> (free;
included in the binary distribution). If this link is broken try <a href="http://www.zsh.org" target="_top">http://www.zsh.org</a>.</p></li><li><p><a href="http://www.oracle.com" target="_top">Oracle 8</a> relational database
management system</p></li><li><p><a href="http://www.aolserver.com" target="_top">AOLserver</a> (free)</p></li><li><p><a href="http://arsdigita.com/free-tools/oracle-driver" target="_top">ArsDigita
Oracle driver for AOLserver</a> (free)</p></li></ul></div><p> It is helpful if you have Oracle interMedia Text for full-text searches.
We're also trying to make our system work with the PLS System,
available free from <a href="http://www.pls.com" target="_top">http://www.pls.com</a>.
-</p><p>Although the <tt>zsh</tt> shell is the only command-line tool
+</p><p>Although the <tt class="computeroutput">zsh</tt> shell is the only command-line tool
required to install the OpenACS, if you are a UNIX person used to typing
- <tt>ls</tt> instead of <tt>dir</tt> you'll get along much
+ <tt class="computeroutput">ls</tt> instead of <tt class="computeroutput">dir</tt> you'll get along much
better with the Cygwin toolkit from RedHat (available at <a href="http://sourceware.cygnus.com/cygwin" target="_top">http://sourceware.cygnus.com/cygwin</a>).
This is a development library and set of tools that gives you a very
UNIX-like environment under Windows. In particular, it includes
- <tt>bash</tt>, <tt>gzip</tt> and <tt>tar</tt>, which you can
- use to perform the OpenACS installation instead of WinZip and zsh.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-oracle"></a>Your Oracle installation</h3></div></div><p>
- When you install Oracle, a good rule of thumb is "every default
- setting is wrong." We will not discuss Oracle configuration here
+ <tt class="computeroutput">bash</tt>, <tt class="computeroutput">gzip</tt> and <tt class="computeroutput">tar</tt>, which you can
+ use to perform the OpenACS installation instead of WinZip and zsh.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-oracle"></a>Your Oracle installation</h3></div></div><div></div></div><p>
+ When you install Oracle, a good rule of thumb is "every default
+ setting is wrong." We will not discuss Oracle configuration here
except to mention that the OpenACS requires Oracle's NLS_DATE_FORMAT
parameter be set to 'YYYY-MM-DD'. Fixing this depends on whether
Oracle Administration Assistant for Windows NT (<span class="emphasis"><em>yes,
@@ -50,208 +49,208 @@
select the Oracle Home for the database you wish to use.</p></li><li><p>Bring up its properties dialog and add a parameter NLS_DATE_FORMAT
with value 'YYYY-MM-DD' (<span class="emphasis"><em>without the
quotes</em></span>)</p></li><li><p>Verify the date format by logging into the database using SQL Plus
- and run the following query: <tt>select sysdate from
+ and run the following query: <tt class="computeroutput">select sysdate from
dual;</tt></p></li></ol></div><p>Otherwise you will need to perform a little registry surgery as
- follows:</p><div class="orderedlist"><ol type="1"><li><p>Run <tt>regedit</tt> and navigate down the registry keys to
- <tt>HKEY_LOCAL_MACHINE\Software\ORACLE</tt>.</p></li><li><p>
- Choose the appropriate subtree; this will be <tt>HOME0</tt> if
+ follows:</p><div class="orderedlist"><ol type="1"><li><p>Run <tt class="computeroutput">regedit</tt> and navigate down the registry keys to
+ <tt class="computeroutput">HKEY_LOCAL_MACHINE\Software\ORACLE</tt>.</p></li><li><p>
+ Choose the appropriate subtree; this will be <tt class="computeroutput">HOME0</tt> if
you only have on einstallation of Oracle.
</p><div class="blockquote"><blockquote class="blockquote"><p>
If you are an Oracle achiever and have more than one Oracle
- installation on your machine, you will see <tt>HOME0, HOME1,
+ installation on your machine, you will see <tt class="computeroutput">HOME0, HOME1,
HOME2</tt>, etc. Choose the subtree that corresponds to the
Oracle installtion you wish to use with the OpenACS.
</p></blockquote></div><p>
- </p></li><li><p>If the <tt>NLS_DATE_FORMAT</tt> key is already present,
+ </p></li><li><p>If the <tt class="computeroutput">NLS_DATE_FORMAT</tt> key is already present,
double-click on its value and change it to 'YYYY-MM-DD'
(<span class="emphasis"><em>without the quotes</em></span>). If the key does not
- exist, choose <tt>Edit->New->String Value</tt> from the menu
- and type <tt>NLS_DATE_FORMAT</tt> for the name of the new value to
+ exist, choose <tt class="computeroutput">Edit->New->String Value</tt> from the menu
+ and type <tt class="computeroutput">NLS_DATE_FORMAT</tt> for the name of the new value to
create it. Then double-click on the empty value to change it.</p></li><li><p>Verify the date format by logging into the database using SQL Plus
- and run the following query: <tt>select sysdate from
+ and run the following query: <tt class="computeroutput">select sysdate from
dual;</tt></p></li></ol></div><p>For more information on Oracle configuration look at <a href="http://photo.net/wtr/oracle-tips" target="_top">http://photo.net/wtr/oracle-tips</a>
or search the <a href="http://photo.net/bboard/q-and-a?topic=web/db" target="_top">Web/db Q&A
- Forum</a>. One other note: the "nuke a user" admin page and
- Intermedia won't run unless you set <tt>open_cursors = 500</tt>
+ Forum</a>. One other note: the "nuke a user" admin page and
+ Intermedia won't run unless you set <tt class="computeroutput">open_cursors = 500</tt>
for your database. For more information on Oracle configuration look at
<a href="http://photo.net/wtr/oracle-tips.html" target="_top">http://photo.net/wtr/oracle-tips.html</a>
or search the <a href="http://photo.net/bboard/q-and-a.tcl?topic=web/db" target="_top">Web/db Q&A
- Forum</a>. One other note: the "nuke a user" admin page and
- Intermedia won't run unless you set <tt>open_cursors = 500</tt>
- for your database.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-acs-binary"></a>The ArsDigita binary installation</h3></div></div><p>
- Extract the ArsDigita AOLserver distribution onto the <tt>C:</tt>
- drive into the default <tt>aol30</tt> directory. You can install it
+ Forum</a>. One other note: the "nuke a user" admin page and
+ Intermedia won't run unless you set <tt class="computeroutput">open_cursors = 500</tt>
+ for your database.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-acs-binary"></a>The ArsDigita binary installation</h3></div></div><div></div></div><p>
+ Extract the ArsDigita AOLserver distribution onto the <tt class="computeroutput">C:</tt>
+ drive into the default <tt class="computeroutput">aol30</tt> directory. You can install it
on any drive, but it will make your life easier if you keep the AOLserver
binary and your OpenACS instance on the same drive. For the rest of these
- instructions, we'll assume that you used drive <tt>C:</tt>.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-untar-acs"></a>Untar the OpenACS</h3></div></div><p>
- We recommend rooting webserver content in <tt>c:\web</tt>. Since most
+ instructions, we'll assume that you used drive <tt class="computeroutput">C:</tt>.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-untar-acs"></a>Untar the OpenACS</h3></div></div><div></div></div><p>
+ We recommend rooting webserver content in <tt class="computeroutput">c:\web</tt>. Since most
servers these days are expected to run multiple services from multiple IP
- addresses, each server gets a subdirectory from <tt>c:\web</tt>. For
- example, <tt>http://scorecard.org</tt> would be rooted at
- <tt>c:\web\scorecard</tt> on one of our machines and if
- <tt>http://jobdirect.com</tt> were on the same box then it would be
- at <tt>c:\web\jobdirect</tt>.
+ addresses, each server gets a subdirectory from <tt class="computeroutput">c:\web</tt>. For
+ example, <tt class="computeroutput">http://scorecard.org</tt> would be rooted at
+ <tt class="computeroutput">c:\web\scorecard</tt> on one of our machines and if
+ <tt class="computeroutput">http://jobdirect.com</tt> were on the same box then it would be
+ at <tt class="computeroutput">c:\web\jobdirect</tt>.
</p><p>For the sake of argument, we're going to assume that your service
- is called "yourdomain", is going to be at
- <tt>http://yourdomain.com</tt> and is rooted at
- <tt>c:\web\yourdomain</tt> in the Windows 2000 file system. Note that
+ is called "yourdomain", is going to be at
+ <tt class="computeroutput">http://yourdomain.com</tt> and is rooted at
+ <tt class="computeroutput">c:\web\yourdomain</tt> in the Windows 2000 file system. Note that
you'll find our definitions files starting out with
- "yourdomain.com".</p><div class="itemizedlist"><ul type="disc"><li><p>download the OpenACS (see <a href="#source" target="_top">above</a>) into
- <tt>c:\temp\acs.tar.gz</tt></p></li><li><p>use WinZip (or equivalent) to extract the files to
- <tt>c:\web\yourdomain</tt></p></li></ul></div><p>
- You'll now find that <tt>c:\web\yourdomain\www</tt> contains the
- document root and <tt>c:\web\yourdomain\tcl</tt> contains Tcl scripts
+ "yourdomain.com".</p><div class="itemizedlist"><ul type="disc"><li><p>download the OpenACS (see <a href="#source" target="_top">above</a>) into
+ <tt class="computeroutput">c:\temp\acs.tar.gz</tt></p></li><li><p>use WinZip (or equivalent) to extract the files to
+ <tt class="computeroutput">c:\web\yourdomain</tt></p></li></ul></div><p>
+ You'll now find that <tt class="computeroutput">c:\web\yourdomain\www</tt> contains the
+ document root and <tt class="computeroutput">c:\web\yourdomain\tcl</tt> contains Tcl scripts
that are loaded when the AOLserver starts up.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-data-model"></a>Feeding Oracle the Data Model</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-data-model"></a>Feeding Oracle the Data Model</h3></div></div><div></div></div><p>
The entire server will behave in an unhappy manner if it connects to
Oracle and finds that, for example, the users table does not exist. Thus
you need to connect to Oracle as whatever user the AOLserver will connect
as, and feed Oracle the table definitions.
</p><div class="itemizedlist"><ul type="disc"><li><p>
- load the <tt>states</tt>, <tt>country_codes</tt> and
- <tt>counties</tt> tables using the <tt>load-geo-tables</tt>
- shell script in the <tt>c:\web\yourdomain\www\install</tt>
+ load the <tt class="computeroutput">states</tt>, <tt class="computeroutput">country_codes</tt> and
+ <tt class="computeroutput">counties</tt> tables using the <tt class="computeroutput">load-geo-tables</tt>
+ shell script in the <tt class="computeroutput">c:\web\yourdomain\www\install</tt>
directory. You will need to open a console window and run </p><pre class="programlisting">
zsh load-geo-tables foo/foopassword
</pre><p>
- You most likely will see a slew of "Commit point reached . . .
- " messages. This does not indicate a problem.
+ You most likely will see a slew of "Commit point reached . . .
+ " messages. This does not indicate a problem.
</p></li><li><p>
- cd to <tt>c:\web\yourdomain\www\doc\sql</tt> and feed Oracle the
+ cd to <tt class="computeroutput">c:\web\yourdomain\www\doc\sql</tt> and feed Oracle the
.sql files that you find there. There is a meta-loader file,
load-data-model.sql, that includes the other files in the proper
order. To use it, open a console window and run
</p><pre class="programlisting">
sqlplus foo/foopassword < load-data-model.sql
</pre></li><li><p>
If you have interMedia installed, while still in
- <tt>c:\web\yourdomain\www\doc\sql</tt>, run
+ <tt class="computeroutput">c:\web\yourdomain\www\doc\sql</tt>, run
</p><pre class="programlisting">
zsh load-site-wide-search foo foopassword ctxsys-password
</pre><p>
- Note that there's no slash between <tt>foo</tt> and
- <tt>foopassword</tt> here. The third argument,
- <tt>ctxsys-password</tt>, is the password for interMedia
+ Note that there's no slash between <tt class="computeroutput">foo</tt> and
+ <tt class="computeroutput">foopassword</tt> here. The third argument,
+ <tt class="computeroutput">ctxsys-password</tt>, is the password for interMedia
Text's special ctxsys user.
- </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-aolserver"></a>Configuring AOLServer</h3></div></div><p>You will need two configuration files. The first is a Tcl file with
+ </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-aolserver"></a>Configuring AOLServer</h3></div></div><div></div></div><p>You will need two configuration files. The first is a Tcl file with
configuration information for AOLserver. This should be called
- <tt>yourdomain</tt> and should be located in
- <tt>c:\aolserve3_0</tt>. The second is an .ini file that configures
+ <tt class="computeroutput">yourdomain</tt> and should be located in
+ <tt class="computeroutput">c:\aolserve3_0</tt>. The second is an .ini file that configures
the OpenACS and is discussed <a href="#ini" target="_top">below</a>. Note that pathnames in
- <tt>yourdomain</tt> must use forward slashes rather than the Windows
- back slashes. This is also true for the .ini file.</p><p>The following items must be defined in <tt>yourdomain</tt>:</p><div class="itemizedlist"><ul type="disc"><li><p>three database pools: main, subquery, and log. They must be named
- as such. The default pool will be "main".</p></li><li><p>the auxconfig directory which contains the .ini file:
- <tt>c:\web\yourdomain\parameters</tt></p></li><li><p>the pageroot: <tt>c:\web\yourdomain\www</tt></p></li><li><p>the directory containing the TclLibrary:
- <tt>c:\web\yourdomain\tcl</tt></p></li></ul></div><p>
+ <tt class="computeroutput">yourdomain</tt> must use forward slashes rather than the Windows
+ back slashes. This is also true for the .ini file.</p><p>The following items must be defined in <tt class="computeroutput">yourdomain</tt>:</p><div class="itemizedlist"><ul type="disc"><li><p>three database pools: main, subquery, and log. They must be named
+ as such. The default pool will be "main".</p></li><li><p>the auxconfig directory which contains the .ini file:
+ <tt class="computeroutput">c:\web\yourdomain\parameters</tt></p></li><li><p>the pageroot: <tt class="computeroutput">c:\web\yourdomain\www</tt></p></li><li><p>the directory containing the TclLibrary:
+ <tt class="computeroutput">c:\web\yourdomain\tcl</tt></p></li></ul></div><p>
You can use <a href="/doc/files/winnsd.txt" target="_top">our template file</a> as a starting
point (<span class="emphasis"><em>you'll need to save this file with a rather than .txt
extension</em></span>).
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="wint2install-configure-acs"></a>Configuring OpenACS itself</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="wint2install-configure-acs"></a>Configuring OpenACS itself</h3></div></div><div></div></div><p>
If you want a system that works, go to
- <tt>c:\web\yourdomain\parameters</tt> and copy <tt>ad.ini</tt> to
- <tt>yourdomain.ini</tt> (<span class="emphasis"><em>or any other name different from
- <tt>ad.ini</tt></em></span>). You don't actually have to delete
- <tt>ad.ini</tt>.
-</p><p>Each section of <tt>yourdomain.ini</tt> has a hardcoded
- "yourservername" in the name (e.g.
- <tt>[ns/server/yourservername/acs]</tt>). This means that the OpenACS
+ <tt class="computeroutput">c:\web\yourdomain\parameters</tt> and copy <tt class="computeroutput">ad.ini</tt> to
+ <tt class="computeroutput">yourdomain.ini</tt> (<span class="emphasis"><em>or any other name different from
+ <tt class="computeroutput">ad.ini</tt></em></span>). You don't actually have to delete
+ <tt class="computeroutput">ad.ini</tt>.
+</p><p>Each section of <tt class="computeroutput">yourdomain.ini</tt> has a hardcoded
+ "yourservername" in the name (e.g.
+ <tt class="computeroutput">[ns/server/yourservername/acs]</tt>). This means that the OpenACS
will ignore your configuration settings unless your AOLserver name
- happens to be "yourservername". Therefore you must go through
- <tt>yourdomain.ini</tt> and change "yourservername" to
+ happens to be "yourservername". Therefore you must go through
+ <tt class="computeroutput">yourdomain.ini</tt> and change "yourservername" to
whatever you're calling this particular AOLserver (<span class="emphasis"><em>look at the
- server name in the <tt>nsd</tt> file for a reference</em></span>).</p><p>Unless you want pages that advertise a community called
- "Yourdomain Network" owned by
- "webmaster@yourdomain.com", you'll probably want to edit
- the text of <tt>yourdomain.ini</tt> to change system-wide parameters.
+ server name in the <tt class="computeroutput">nsd</tt> file for a reference</em></span>).</p><p>Unless you want pages that advertise a community called
+ "Yourdomain Network" owned by
+ "webmaster@yourdomain.com", you'll probably want to edit
+ the text of <tt class="computeroutput">yourdomain.ini</tt> to change system-wide parameters.
If you want to see how some of these are used, a good place to look is
- <tt>c:\web\yourdomain\tcl\ad-defs</tt>. The Tcl function,
- <tt>ad_parameter</tt>, is used to grab parameter values from the .ini
- file.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="wi2kinstall-starting-service"></a>Starting the Service</h3></div></div><p>
+ <tt class="computeroutput">c:\web\yourdomain\tcl\ad-defs</tt>. The Tcl function,
+ <tt class="computeroutput">ad_parameter</tt>, is used to grab parameter values from the .ini
+ file.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="wi2kinstall-starting-service"></a>Starting the Service</h3></div></div><div></div></div><p>
Now you're ready to start things up. Before installing as a Windows
service, you might want to test the setup for configuration errors. Open
- up a console window and go to <tt>c:\aol30</tt>. Then run
+ up a console window and go to <tt class="computeroutput">c:\aol30</tt>. Then run
</p><pre class="programlisting">
bin\nsd -ft yourdomain.tcl
</pre><p> This will print all the AOLserver messages to the console so you can see
them.
</p><p>Try to connect to your new server with a web browser. If you see the
- message "Error in serving group pages", you probably forgot to
- copy the ad.ini file in <tt>c:\web\yourdomain\parameters</tt> If
+ message "Error in serving group pages", you probably forgot to
+ copy the ad.ini file in <tt class="computeroutput">c:\web\yourdomain\parameters</tt> If
everything seems ok, you can kill the server with Control-c and then
issue the following command to install as a Windows service:</p><pre class="programlisting">
bin\nsd -I -s yourdomain -t yourdomain.tcl
</pre><p> You can now configure error recovery and other Windows aspects of the
service from the Services control panel. If you make further changes to
- <tt>yourdomain</tt> or <tt>yourdomain.ini</tt> you should stop
+ <tt class="computeroutput">yourdomain</tt> or <tt class="computeroutput">yourdomain.ini</tt> you should stop
and start the service from the Services control panel.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-configure-permissions"></a>Configuring Permissions</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-configure-permissions"></a>Configuring Permissions</h3></div></div><div></div></div><p>
Now, you need to protect the proper administration directories of the
OpenACS. You decide the policy although we recommend requiring the admin
directories be accessible only via an SSL connection. Here are the
directories to consider protecting:
</p><div class="itemizedlist"><ul type="disc"><li><p>/doc (or at least /doc/sql/ since some AOLserver configurations
will allow a user to execute SQL files)</p></li><li><p>/admin</p></li><li><p>any private admin dirs for a module you might have written that are
- not underneath the /admin directory</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-add-yourself"></a>Adding Yourself as a User and Making Yourself a Sysadmin</h3></div></div><p>
+ not underneath the /admin directory</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-add-yourself"></a>Adding Yourself as a User and Making Yourself a Sysadmin</h3></div></div><div></div></div><p>
The ArsDigita Community System will define two users: system and
anonymous. It will also define a user group of system administrators.
You'll want to add yourself as a user (at /register/ ) and then add
yourself as as member of the site-wide administration group. Start by
logging out as yourself and logging in as the system user (email of
- "system"). Change the system user's password. Visit the
- <tt>https://yourservername.com/admin/ug/</tt> directory and add your
+ "system"). Change the system user's password. Visit the
+ <tt class="computeroutput">https://yourservername.com/admin/ug/</tt> directory and add your
personal user as a site-wide administrator. Now you're bootstrapped!
</p><p>If you do not know what the system user's password is connect to
Oracle using SQL Plus and run the following query:</p><pre class="programlisting">
select password from users where last_name = 'system';
-</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-closing-down-access"></a>Closing Down Access</h3></div></div><p>
- The OpenACS ships with a user named "anonymous" (email
- "anonymous") to serve as a content owner. If you're
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-closing-down-access"></a>Closing Down Access</h3></div></div><div></div></div><p>
+ The OpenACS ships with a user named "anonymous" (email
+ "anonymous") to serve as a content owner. If you're
operating a restricted-access site, make sure to change the anonymous
user's password. In recent versions of the OpenACS you cannot log into
- "anonymous" because the account does not have a valid user
+ "anonymous" because the account does not have a valid user
state. Log in as a sysadmin and change the anonymous user's password
- from <tt>https://yourservername/admin/users</tt>. You should read the
+ from <tt class="computeroutput">https://yourservername/admin/users</tt>. You should read the
documentation for <a href="user-registration" target="_top">user registration and
access control</a> and decide what the appropriate user state is for
anonymous on your site.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-where-is-what"></a>Where to Find What</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-where-is-what"></a>Where to Find What</h3></div></div><div></div></div><p>
A few pointers:
</p><div class="itemizedlist"><ul type="disc"><li><p>the /register directory contains the login and registration
scripts. You can easily redirect someone to /register/index to have
them login or register.</p></li><li><p>the /pvt directory is for user-specific pages. They can only be
- accessed by people who have logged in.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-make-sure-it-works"></a>Making sure that it works</h3></div></div><p>
+ accessed by people who have logged in.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-make-sure-it-works"></a>Making sure that it works</h3></div></div><div></div></div><p>
Run the acceptance tests in <a href="/doc/acceptance-test" target="_top">/doc/acceptance-test</a>
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-multiple-acs"></a>Running Multiple Instances of the OpenACS</h3></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="win2kinstall-multiple-acs"></a>Running Multiple Instances of the OpenACS</h3></div></div><div></div></div><p>
You can run multiple instances of the OpenACS on a physical machine but they
must each be set up as a separate Windows service. Each instance of the
OpenACS must have its own:
</p><div class="itemizedlist"><ul type="disc"><li><p>Oracle tablespace and a user account with the appropriate
permissions on that tablespace. Each of these tablespaces must have the
OpenACS data model loaded.</p></li><li><p>file with the appropriate settings including server name,
auxconfig, ipaddress, and port.</p></li><li><p>Copy of the acs files in an appropriate directory under
- <tt>c:\web</tt>.</p></li></ul></div><p> Suppose you wish to run two services: <tt>lintcollectors.com</tt> and
- <tt>iguanasdirect.com</tt>. You would need the following:
-</p><div class="itemizedlist"><ul type="disc"><li><p>an Oracle tablespace, <tt>lintcollectors</tt> with a user
- <tt>lintcollectors</tt> and password <tt>secretlint</tt></p></li><li><p>an Oracle tablespace, <tt>iguanasdirect</tt> with a user
- <tt>iguanasdirect</tt> and password <tt>secretiguanas</tt></p></li></ul></div><p> For each of these tablespaces/users you would load the OpenACS data model as
- described <a href="#data" target="_top">above</a>. Then in <tt>c:\aolserver3_0</tt>
- create files for each service, i.e. <tt>lintcollectors</tt> and
- <tt>iguanasdirect</tt>. These files would point to their respective
- pageroots, <tt>c:\web\lintcollectors\www</tt> and
- <tt>c:\web\iguanasdirect\www</tt>; their respective auxconfigdirs,
- <tt>c:\web\lintcollectors\parameters</tt> and
- <tt>c:\web\iguanasdirect\parameters</tt>; etc. In the respective
- auxconfigdirs would be the files <tt>lintcollectors.ini</tt> and
- <tt>iguanasdirect.ini</tt>.
-</p><p>Now open a console window and go to <tt>c:\aol30</tt>. You'll
+ <tt class="computeroutput">c:\web</tt>.</p></li></ul></div><p> Suppose you wish to run two services: <tt class="computeroutput">lintcollectors.com</tt> and
+ <tt class="computeroutput">iguanasdirect.com</tt>. You would need the following:
+</p><div class="itemizedlist"><ul type="disc"><li><p>an Oracle tablespace, <tt class="computeroutput">lintcollectors</tt> with a user
+ <tt class="computeroutput">lintcollectors</tt> and password <tt class="computeroutput">secretlint</tt></p></li><li><p>an Oracle tablespace, <tt class="computeroutput">iguanasdirect</tt> with a user
+ <tt class="computeroutput">iguanasdirect</tt> and password <tt class="computeroutput">secretiguanas</tt></p></li></ul></div><p> For each of these tablespaces/users you would load the OpenACS data model as
+ described <a href="#data" target="_top">above</a>. Then in <tt class="computeroutput">c:\aolserver3_0</tt>
+ create files for each service, i.e. <tt class="computeroutput">lintcollectors</tt> and
+ <tt class="computeroutput">iguanasdirect</tt>. These files would point to their respective
+ pageroots, <tt class="computeroutput">c:\web\lintcollectors\www</tt> and
+ <tt class="computeroutput">c:\web\iguanasdirect\www</tt>; their respective auxconfigdirs,
+ <tt class="computeroutput">c:\web\lintcollectors\parameters</tt> and
+ <tt class="computeroutput">c:\web\iguanasdirect\parameters</tt>; etc. In the respective
+ auxconfigdirs would be the files <tt class="computeroutput">lintcollectors.ini</tt> and
+ <tt class="computeroutput">iguanasdirect.ini</tt>.
+</p><p>Now open a console window and go to <tt class="computeroutput">c:\aol30</tt>. You'll
start up the two services as follows:</p><pre class="programlisting">
bin\nsd -I -s lintcollectors -t lintcollectors.tcl
bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl
</pre><p> In the services control panel you should see two services:
- <tt>AOLserver-lintcollectors</tt> and
- <tt>AOLserver-iguanasdirect</tt>.
+ <tt class="computeroutput">AOLserver-lintcollectors</tt> and
+ <tt class="computeroutput">AOLserver-iguanasdirect</tt>.
</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="mac-install.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�5.�Installing on Windows </td><td width="20%" align="center"><a accesskey="u" href="win-install.html">Up</a></td><td width="40%" align="right"> Chapter�6.�Installing on a Macintosh</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/win2k-installation.html#comments">View comments on this page at openacs.org</a></center></body></html>
Index: openacs-4/packages/acs-core-docs/www/xml/variables.ent
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/variables.ent,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/variables.ent 21 Aug 2003 08:10:06 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/variables.ent 14 Oct 2003 11:00:53 -0000 1.2
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1" ?>
-<!ENTITY version "5.0.0d">
-<!ENTITY tarballpath "openacs-5.0.0d">
-<!ENTITY cvsversiontag "openacs-5-0-0d">
+<!ENTITY version "5.0.0a1">
+<!ENTITY tarballpath "openacs-5.0.0a1">
+<!ENTITY cvsversiontag "openacs-5-0-0a1">
<!ENTITY majorversion "5">
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml,v
diff -u -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 1 Oct 2003 16:11:34 -0000 1.8
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 14 Oct 2003 11:00:53 -0000 1.9
@@ -48,14 +48,15 @@
</sect2>
END OF TEMPLATE -->
- <sect2 id="release-notes-5-0-0">
- <title>Version 5.0.0</title>
- <authorblurb>
- by <ulink url="mailto:dhogaza@pacifier.com">Don Baccus</ulink>
- </authorblurb>
-
+ <sect2 id="release-notes-5-0-0a1">
+ <title>Version 5.0.0 alpha1</title>
+
<para>
- This is a pre-alpha release of OpenACS 5.0.0.
+ This is the first alpha release of OpenACS 5.0.0. This
+ release has a number of severe bugs, and is not suitable for
+ production systems. It has passed several release criteria,
+ including that it installs successfully and that all automated
+ tests succeed.
</para>
<para>
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/Attic/compatibility.xml,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml 14 Oct 2003 10:03:23 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml 14 Oct 2003 11:03:00 -0000 1.7
@@ -69,7 +69,7 @@
<entry namest="4.5" nameend="4.6.3" align="center">Verified</entry>
</row>
<row>
- <entry>7.3.2</entry>
+ <entry>7.3.2 - 7.3.4</entry>
<entry namest="3.2.5" nameend="4.6.2" align="center">Incompatible</entry>
<entry namest="4.6.3" nameend="4.6.3"
align="center">Mostly compatible (news is broken)</entry>