Forum OpenACS Q&A: OpenACS General Stuff

I've had OpenACS running for about five days now and so far so good.
The depth and functionality of OpenACS is impressive and I can see the
tremendous amount of work that must be involved with porting OpenACS
from the Oracle based ACS. So far I'm completely overwhelmed by the
size and complexity of this thing. I'm slowly beginning to understand
how OpenACS works but I'm still lacking in some basic areas. I'm
hoping that the users of this form can point me in the right
direction, but before I ask any questions a bit of background. I'm not
a web nerd/expert by any stretch of the imagination, my formal
background is in industrial controls creating large scale integrated
production lines that you see in automotive, packaging and plastics
factories. Nine months ago I knew nothing about linux, firewalls,
Oracle, Postgres, Sql, networks, switches and/or what the hell
ethernet was. Since that time I've read at least 15 books on these
various subjects and I've been able to setup a small server farm
consisting of four Ppro servers and an Intel 510-T switch. At present
I have, Apache, Aolserver, postgres, Oracle, Samba, a Linux firewall
system and OpenACS running on various machines that I use as test
beds. This was at best a very difficult task starting from ground zero
with only some Windows NT experience. I'm telling you this because I'm
nothing more that a newbie that will more often than not ask some
stupid questions that may be more that obvious to the people with
loads of experience in the Web/database field. Please do not flame the
crap out of me for asking about things that may be obvious, just point
me in the right direction and I'll take care of the rest.
Ok now for the questions. First I've been poking at
OpenACS for a full day now and I have a few questions about the TCL
variables that are used throughout OpenACS. For example what is
[ad_parmeter SpecialIndexPage content] or [ad_header[ad_system_name] ?
Is there a document that describes what these things are and what they
are used for? Also how do *.ADP pages fit into the picture and is
there any documentation on how they are used with OpenAcs and
Aolserver. Next and last in the Postgres database for OpenAcs I see
two types of information when using the /d command. Both tables and
sequence, I understand what a table is and how to use it but what is a
sequence?

Please note that I haven't used the OpenACS, but I think the answers to your questions are common to both the OpenACS and ACS Classic so I will give it a stab.

"For example what is [ad_parmeter SpecialIndexPage content] or [ad_header[ad_system_name] ? Is there a document that describes what these things are and what they are used for?"

ad_parameter and ad_header are both procedures defined in the file /web/[your_service_name]/packages/acs-core/defs-procs.tcl. You can find a searchable directory of every procedure defined in the ACS installed on your site by going to the page http://[www.your-web-address.com]/doc/procs. For example, the definitions for the procs for the arsdigita.com site are available at http://www.arsdigita.com/doc/procs.

"[ad_parameter SpecialIndexPage content]" will return the value of the SpecialIndexPage configuration parameter in the content subsections of your your-service-name.ini file.

[ad_header[ad_system_name]] creates a header for the page with system name as the page title. See the docs for details.

You can find documentation on ADP's in Chapter 2 of the AOLserver Tcl Developer's Guide, available at http://www.aolserver.com/doc/3.0/tcldev/tcldev.htm.

A sequence is simply a sequence of numbers. Often you will want to have a unique number to use as a key for a row in a table. Many RDBMS's provide a built-in sequence generator. For example, to create a sequence in Oracle:

Yes, reading Philip's book is a very good idea, though you must read it with a bit of skepticism because aD is doing some things quite differently nowadays than one would imagine from reading it.

That's the problem with books (or any written document) - they get written, the world changes, and they rarely get edited.

But 90% of what's said there still applies to aD's work, though sometimes more in general than in specific.

Adp pages are currently AOL's preferred way to create dynamic web pages, rather than Tcl scripts. aD doesn't adhere to that philosophy, and in particular writes pages which do lots of work but generate little or no HTML in Tcl, a choice I agree with. Adp pages are certainly a lot easier to work with for pages which contain a lot of HTML. They're more readable, making it easier for third parties to whack their way through them when trying to understand your code.

Tcl pages are a small program that optionally generate HTML using ns_write statements, or (current thinking) by building a string and returning it at page completion (more efficient). Adp pages are HTML pages that can contain embedded snippets of Tcl, including code to dynamically generate HTML based on (say) database contents. If the Tcl is much smaller than the HTML, as mentioned above Adp pages are easier to read as most of the file is pure HTML, and the small snippets of Tcl stick out like a sore thumb. On the other hand, if little or no HTML is being generated (as when inserting form contents into the database) an Adp page looks like one giant Tcl snippet, and is no easier to read than a plain old Tcl script file.

Don't worry about us flaming you - you've learned an impressive amount of stuff on your own over the last few months and you'll certainly learn a lot more.