<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>OpenACS 4 Porting Resources</title>
</head>
<body bgcolor=white>
<h2>OpenACS 4 Porting Resources</h2>
<hr>
<h3>Goal</h3>
<blockquote>
This is an attempt to compile in one location all the resources that
a porter would need to get started (and unstuck from time to
time). With your help, this document will get updated as we come upon
and squash more problems.
</blockquote>
<h3>Essentials</h3>
<blockquote>
These documents are absolute must reads.
<dl>
<dt><a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=120">Porting Guidelines</a> </dt>
<dd>This document describes the basic changes that will be needed
in the Oracle datamodel </dd><br>
<dt><a href="http://openacs.org/wp/display/10/">OpenACS Package
Manager Wimpy Point</a> </dt>
<dd>This is a multipage document that describes how the package
manager functions. It also describes the first steps that the
porter needs to take. </dd><br>
<dt><a href="http://openacs.org/4/query-dispatcher">The Query
Dispatcher</a> </dt>
<dd>The Query Dispatcher is the key to db-independence in OpenACS 4
and this document will help you understand it. The last section on
dynamic queries is not completed, but that info is in the OpenACS
Package Manager Wimpy Point above. </dd><br>
<dt><a href="http://www.brasileiro.net/postgres/porting/">Oracle to
Postgres Porting Guide</a> </dt>
<dd>Explains major differences between Oracle 8i and Postgres. </dd><br>
</dl>
</blockquote>
<h3>FAQ</h3>
<blockquote>
<dl>
<dt><i>How do I install OpenACS 4? </i></dt>
<dd>The <a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=114">Brief
OpenACS 4 Installation Guide</a> provides a skeleton framework to
getting OpenACS 4 working on your machine
</dd><br>
<dt><i>How do I upgrade to Postgres 7.1? </i></dt>
<dd>Read Pascal Scheffer's <a
href="http://pascal.scheffers.net/openacs/pgupdate/">guide to
upgrading Postgres from 7.0 to 7.1</a> </dd><br>
<dt><i>How do I get the latest CVS? How do I commit changes? </i></dt>
<dd><a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=100">OpenACS
CVS HOWTO</a> </dd><br>
<dt><i>Where do I get the Query Extractor? </i></dt>
<dd>Download the <a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=79">Query
Extractor.</a> This tool will extract queries from aD packages and
do a lot of the porting work for you. Documentation on how to use
it is in the /doc directory once you extract the tar file. </dd><br>
<dt><i>How do I use the new Content Repository? </i></dt>
<dd>Read the <a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=124">Content
Repository HOWTO</a> </dd><br>
<dt><i>What packages are available for porting? </i></dt>
<dd>Read the <a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=77">OpenACS
4 Status</a> document to see which packages still need to be
ported. You can also find out how far along other packages are
coming. Be sure to update your status with Don frequently. </dd><br>
<dt><i>What goes in which .xql file again? </i></dt>
<dd>Try this <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0001uA&topic_id=12&topic=OpenACS%204%2e0%20Design">post</a>
</dd><br>
<dt><i>Are we using any naming/style conventions? </i></dt>
<dd>In PL/PGSQL functions, we're using 'p_' prefixes for arguments
to the function and 'v_' prefixes for other local variables. Also,
for function calls, we're trying to keep comments that explain the
purpose of the arguments. For example:
<pre><blockquote>workflow.add_place (
workflow_key => 'ttracker_wf',
place_key => 'end',
place_name => 'Closed',
sort_order => 4
);
<b>becomes</b>
select workflow__add_place (
'ttracker_wf', -- workflow_key
'end', -- place_key
'Closed', -- place_name
4 -- sort_order
);
</blockquote></pre>
</dd><br>
<dt><i>I found a 'connect by'. What do I do with it? </i></dt>
<dd><a
href="http://openacs.org/new-file-storage/one-file?file_id=123">Read
this document</a> </dd><br>
<dt><i>How do I port outer joins? </i></dt>
<dd>Check out these bboard posts: <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00028O&topic_id=OpenACS&topic=">Post 1</a>
<a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0002A0&topic_id=12&topic=OpenACS%204%2e0%20Design">Post
2</a> <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00027U&topic_id=12&topic=OpenACS%204%2e0%20Design">Post
3</a> </dd><br>
<dt><i>How do I deal with dynamic queries? </i></dt> <dd>Well you
should have read <a
href="http://openacs.org/wp/display-edit/10/72.wimpy">this</a> in
the WP. Plus here's a <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0001h5&topic_id=12&topic=OpenACS%204%2e0%20Design">bboard
post</a>. <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00027d&topic_id=OpenACS&topic=">And
another</a>.</dd><br>
<dt><i>One of the functions that I have to port has more than 16
parameters, but PG's limit is 16. </i></dt>
<dd>Bummer, huh? Hopefully PG will increase the default number of
parameters, but until that happens, we need to workaround it. Look
throughout the code to see how the function is called. Are some of
the parameters always the same? Then go ahead and take those
parameters out and set them explicitly in the function's body. If
that's still not enough, then you'll have to overload the function
with different sets of parameters. See
packages/acs-content-repository/sql/postgresql/content-item.sql to
see how Dan ported content_item__new. </dd><br>
<dt><i>How should I name my sequences so they're consistent between
Oracle and PG </i></dt>
<dd>See this <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00027v&topic_id=12&topic=OpenACS%204%2e0%20Design">post.</a>
</dd><br>
<dt><i>How do I call PL/PGSQL functions?</i></dt>
<dd>Check out this <a
href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00024T&topic_id=12&topic=OpenACS%204%2e0%20Design">post</a></dd><br>
<dt><i>Can I see a function's source code while in psql? </i></dt>
<dd>Yup, this has the advantage of showing you line numbers, which are sometimes spit up by PG error messages: <br><code>openacs=# select * from acs_func_defs where fname='acs_object__new'</code> </dd><br>
<dt><i>I've looked at some ported packages and I've noted that
ported queries are in the .xql files, but are also still in the
.tcl files. Is that right? </i></dt>
<dd>Yup, at least for now. At some point we may take the queries
out and perhaps replace them with some other information, such as
which variables get set with that particular query. As long as the
proper queries are in the .xql file, the query dispatcher will
ignore the query in the .tcl file. </dd><br>
<dt><i>How does the permissions system work? </i></dt>
<dd><a
href="http://openacs.org/new-file-storage/one-file-redirect-latest?file_id=146">ACS
4 Permissions Tediously explained</a> </dd><br>
<dt><i>I just wanna see how work is progressing. </i></dt>
<dd>You can <a
href="http://openacs.org/sdm/package-repository.tcl?package_id=9">browse
the CVS</a> or download a <a
href="http://openacs.org/sdm/nightly-tarballs.tcl?package_id=9">nightly
tarball</a>. </dd><br>
<dt><i>Where are all the porters? </i></dt>
<dd>Why on IRC of course. We're on #openacs on the
OpenProjectsNet. Feel free to drop by, whether or not you're a
porter! You can read some <a
href="http://blogspace.com/openacs/chatlogs">old logs</a>.</dd><br>
</dl>
</blockquote>
<h3>A Day in the Life of a Porter</h3>
<blockquote>
Let me make a feeble attempt at describing how to port a package.
<ol>
<li>Install OpenACS 4, Pick an unported package and ask Don if
anyone else is porting it. </li>
<li>Go into <code>/packages/my-package/sql</code>. If there are
already 2 directories (<code>oracle</code> and
<code>postgresql</code>), then you're all set. If not copy all the
files in <code>sql/</code> to <code>sql/oracle/</code> and
duplicate the <code>sql/oracle</code> directory to
<code>sql/postgresql</code>. Your tree should now look like:
<pre><blockquote>my-package
sql
oracle
my-package-create.sql
my-package-drop.sql
postgresql
my-package-create.sql
my-package-drop.sql
</blockquote></pre>
</li>
<li>Port the datamodel scripts: my-package-create.sql and
my-package-drop.sql. It is to your advantage to make sure that
my-package-drop.sql is working. It'll make your life easier when
you want to test your package. </li>
<li>Download and untar the query extractor. Read the docs. In
short, edit the file config/openacs_tools.conf. Edit the following
parameters to match your installation:
<ul>
<li><code>packages_dir: /web/openacs-4/packages</code> -
<i>Where is your packages directory</i> </li>
<li><code>packageslist: my-package</code> - <i>Which packages
you want to extract</i> </li>
<li><code>sql_xml_outputdir:/home/nsadmin/openacs_tools/xml</code>
- <i>Where you want the output to go</i> </li>
</ul>
</li>
<li>Run the extractor: <code>bin/AcsSqlExtractor</code> </li>
<li>The queries will now be in <code>xml/my-package</code> and you
can copy them to your OpenACS installation </li>
<li>Now fire up OpenACS in your browser and make your way over to
<code>/acs-admin/apm</code>. Click on 'Install Packages'. It may
take a while to build a list of available packages. </li>
<li>In emacs, open up a shell and do a <code>tail -f </code> on
your OpenACS 4 error log </li>
<li>Install and enable my-package. The APM will then run your
create script. If you're lucky, everything will work fine and you
can move to the next step. If not, try to figure out how far
along it got, using either the output in the browser or the
output in your error log. Once you find what choked, fix the
create script. Then go into psql and drop everything that was
created before it choked so that your install is free of all
remnants of 'my-package'. Then go back to the browser and try to
reinstall the package. If it still doesn't work, debug, purge and
retry. Again and again until it works. This is the first place
where an effective drop script comes in handy. If the installer
chokes, just find where it chokes, fix the bug, feed your drop
script to psql and reinstall.
</li>
<li>Restart OpenNSD/AOLServer</li>
<li>Go back to the APM (<code>/acs-admin/apm</code>). Your package
should be listed there. Click on it. </li>
<li>Check that PostgreSQL shows up in the 'Database Support'
column. Then click on 'Manage File Information' </li>
<li>At the bottom of the page, click on 'Scan for new files' and
then add the new files to your project. When you're done, go back
to my-package APM info page and click on 'Write an XML Spec
File...'. This updates the info file. </li>
<li>Also on the packages APM page, there's a link to 'Manage
Dependency Info'. Make sure that this is up-to-date and correct
otherwise users will have difficulty loading or using your
package. So, if while porting, you realize that your package uses
acs-mail or has templating queries from acs-templating, be sure
to add those packages as dependencies.</li>
<li>Next, go through each and every .xql file that the query
extractor created and do all your fixes. Fix outer joins, fix
decode statements, fix pl/sql blocks, etc. Feel free to post to
the bboard or on IRC for help. Remember the goal is to make
queries SQL92 compliant and get them in the script.xql file. If
they have any PG specific features, they go in
-postgresql.xql. Oracle specific features -> -oracle.xql </li>
<li>Once you're done with all the .xql files, do a quick run
through all the .tcl files to make sure that there are no
unported queries. Some queries do not get picked up by the query
extractor, and you'll have to port those yourself. </li>
<li>Once you're done, load your package on the site-map and bang
away. If you can, test the oracle and postgres versions. This is
where a functioning drop script really comes in handy because
you'll want to drop and recreate your package repeatedly. </li>
</ol>
<p>
Throughout this process, you'll occasionally come to the point when
you want to alter a table or alter a function. If so, go ahead and
do it in psql. You don't need to drop your db and reload the entire
datamodel. For example, if you just want to change one function,
drop that function and recreate it with your fix. The package will
now run your new function. If you want to drop a table, it may be a
little more complicated, but at most, you can drop your package
with your package drop script and then reload your fixed create
script. There's no need to reload the datamodel or even reinstall
from the APM. Of course, once you're done, it's probably a good
idea to do a full fresh install to make sure that you haven't
inadvertently broken anything.
</p>
<p>
<i>When to commit changes</i>: After getting the datamodel-create
script working properly and then extracting queries, I update the
.info file and make my first commit. Then I gradually commit as I'm
porting the .xql files.
</p>
<p>
This is a very rough draft and I'm sure all of you have tips that
you're just dying to impart, so please feel free to let 'em out!
</p>
</blockquote>
<h3>History</h3>
<blockquote>
<table width="80%" border=1>
<tr>
<th>Date </th>
<th width="80%">Action </th>
</tr>
<tr>
<td align="center">2001-07-13 </td>
<td>First Revision </td>
</tr>
</table>
</blockquote>
<hr>
<address><a href="mailto:vkurup@massmed.org">Vinod Kurup</a></address>
<!-- Created: Thu Jul 12 22:22:25 EDT 2001 --> <!-- hhmts start --> Last
modified: Fri Jul 13 01:59:18 EDT 2001 <!-- hhmts end -->
</body>
</html>