$ zcat owarepl.tar.Z | tar xvf -If you are using Windows NT you will use the above mentioned WinZip application to uncompress/untar the file. Follow its directions for use. When it prompts you "owarepl.tar.Z appears to contain owarepl.tar, uncompress to a temporary directory" answer YES.
This will create the following subdirectory tree:
ssize_t wRBClientRead( void *WRBCtx, char *szData, int nBytes );Please correct the header file and recompile. On many platforms, you may get warnings when compiling about type mismatches (char * and unsigned char *), they are allright. Also, some platforms will warn about the above type mismatch (int and int *) but that is allright as well.
You must add a couple of mandatory settings in the svXXXX.app file as well as map the cartridge. The mapping for the cartridge will look something like:
; [Apps] DBAUTH PATH_TO_INSTALL/owarepl.so owarepl_entry 0 100You will, of course, replace the PATH_TO_INSTALL with the full path to where you untarred the files to. For example, on my system it is:
; solaris entry: DBAUTH /usr/oracle/ows2/sample/owarepl/solbin/owarepl.so owarepl_entry 0 100 ; NT entry: DBAUTH C:\orant\ows20\sample\owarepl\ntbin\owarepl.dll owarepl_entry 0 100 * NOTE: /usr/oracle and c:\orant are MY oracle homes. You may have different values for these.You will also need to set up a 'DBAUTH' section in the svXXXX.app file. It will look like (you can get the following from the example subdirectory to include in your svXXXX.app file)
[DBAUTH] owa.cfg = /usr/oracle/ows2/admin/owa.cfg server.cfg = /usr/oracle/ows2/admin/svdbaut2.cfg authenticate = owa_dba another_web_agent web_authent_prefix = web$ dirSeparator = / ;debugModules = all ;webAgentName_filedir = /tmp/xxx ;timingsTable = ows2.timings ;timingsModules = all ;timingsModules = CGI-ENV RETURN-PAGE EXEC-BLOCK DESCRIBE DESCRIBE GET-IMAGE BUILD-ARGLIST TOTAL GET-IMAGE-FILE PROCESS-SSI DO-SSI-BLOCK ;pre_webAgentName = some_function ;post_webAgentName = some_procedure ;webAgentName_image_tname = some_table_name *NOTE: /usr/oracle is MY oracle home, yours will be different.The following explains each of the variables above:
| Variable | Mandatory | Meaning |
|---|---|---|
| owa.cfg | YES | Full file name (no relative paths, please) to the location of the owa.cfg file. Will normally be $ORACLE_HOME/ows2/admin/owa.cfg but you may have moved it. |
| server.cfg | YES | Full file name (no relative paths, please) to the location of the svXXXX.cfg file where XXXX is the name of your listener. For example, my listener name is dbaut2 in the above exampleM |
| authenticate | NO | A list of web agent names (DCD names) separated by TABS or SPACES (no commas) that will use database authentication. All other web agents NOT listed here will use the normal method for logging into the database (i.e. they will get their username/passwords from the owa.cfg file). |
| web_authent_prefix | NO | This is equivalent to the OPS$ style of prefix used with OS authentication. We wanted to be able to easily separate our 'web' users from our regular users. We set our web_authent_prefix to web$. This will cause the string 'WEB$' to be prefixed to whatever userid the client supplied. You can comment this out (use a ;) and no prefix will be applied. |
| dirSeparator | YES | This will either be / on UNIX or \ on NT. For portability reasons.... |
| debugModules | NO | A list of modules to 'debug'. I debug using WRBLogMessage which will
write to a file name $ORACLE_HOME/ows2/log/wrb_DBAUTH_12345.log (where
12345 will be some arbitrary number assigned at runtime). This will help
in tracking down configuration issues. You can either debug all modules
(as above debugModules = all) or you can debug individual modules by listing
them. For example, if you do an ls *.pc in the src directory, you will
see that startup.c and logon.c are two 'modules'. To debug them (see what
they are doing) you would set:
debugModules = startup.c logon.c |
| webagentName_filedir | NO | If you want uploaded files to go into a file system subdirectory for
a given web agent instead of INTO the database, you will set this variable.
You will not set 'webagentName' but rather replace that with the name of
your DCD. For example, to allow ows-bin to upload files into the subdirectory
/tmp/ows-bin you would:
ows-bin_filedir = /tmp/ows-binPlease note the lack of a trailing directory separator, it is intentional. Don't put a trailing / or \ on the directory name. |
| timingsTable | NO | Our web agent has the ability to collect detailed timing stats down to the hundredths of a second for all web operations. These stats go into a table named 'timings.' The definition of the timings table is in owarepl.sql found in the owarepl/sql subdirectory. If you install this table and want timings, you will set the timingsTable variable equal to the owner.tablename. For example, my timings table is owned by ows2 and is called timings. |
| timingsModules | NO | This allows you to filter the level at which you want to collect timings.
If you set this to all, all timings will be collected. You may also set
a specific set of timings to capture. For example, if you
timingsModules = TOTAL EXEC-BLOCKYou will collect stats for the TOTAL execution time (from the time the user connects until they get the whole page) and the time spent executing just the PL/SQL code for the web agent. The difference between these two times is the overhead my code vs the overhead the web imposed. Some of the things that take time are parsing the cgi-environment, loading large files that are uploaded, describing invalid procedures, and so on. A complete list of modules is in the example directory in the svdbauth.app file. Their meanings are listed in the table below. |
| pre_WebAentName | NO | This allows you to set up a function to be invoked for a given webagent before it's routine is run. See this page for a more descriptive discussion of this feature. |
| post_WebAentName | NO | This allows you to set up a procedure to be invoked for a given webagent after it's routine is run. See this page for a more descriptive discussion of this feature. |
| WebAentName_image_tname | NO | This allows you to override the default table name "IMAGE" used to
upload/download images with. For example:
ows-bin_image_tname = MyDocumentTableWould cause the cartridge to use the database table MyDocumentTable for images retrieval and storage instead of using the table named IMAGE. See this page for more information. |
| webAgentname_use_lob | NO | This allows you to tell us to use a BLOB instead of a LONG RAW when
doing an upload/download. You would set:
ows-bin_use_lob = Y Would cause the cartridge to use dbms_lob.read/write to access the BLOB column instead of a long raw. Please make sure to create the IMAGE table with a column called IMAGE of type BLOB for this as well. |
| defaultRealm | NO | The name of the realm to return for this cartridge. by default,
each web agent would return its own name as the realm. If you use
>1 web agent on your site, this will cause people to have to log in over
and over (once for each DCD) when using DBAUTH. If you set a defaultRealm,
all web agents will return the same realm allowing your users to enter
their password once.
defaultReam = someRealmName |
| reUseConnect | NO | This will allow the cartridge to maintain a connection to the database from call to call. This is only useful if you do not use database authentication. It can improve performance. |
| webAgentname_argv_only | NO | added new [DBAUTH] parameter dcdname_argv_only. If you set this (eg:
ows-bin_argv_only = TRUE) in the svXXXX.app file, then instead of passing
in named parameters to the pl/sql routines, we will put them into a pair
of pl/sql tables in the new cgi_args package. see argv.sql in the owarepl/sql
directory for the package definition of cgi_args and a sample pl/sql routine
that accesses the arg list (showenv). I will put all of the names of the
inputs into the cgi_args.argNam array and their corresponding values into
the cgi_args.argVal array. This setting applies to the whole DCD. So if
you set ows-bin_argv_only in the [DBAUTH] section, none of the pl/sql routines
invoked with a URL of /ows-bin/owa will ever get passed inputs, their inputs
will be in the cgi_args package instead. You can have 2 DCD's that point
to the same database account so if only some of your routines need this
feature, you should set up 2 DCD's that point to the same account, that
way you could have:
/ows-bin/owa/foobar?x=5 with foobar defined as procedure foobar( x in varchar2 ); and /ows-bin-argv/owa/barfoo?x=5 with barfoo defined as procedure barfoo; (assuming ows-bin_argv_only was NOT set and ows-bin-argv_argv_only WAS set) |
The following is a list of values that may be used with "timingsModules =" to get timing statistics:
If you are using OAS3.x or 4.x, you can skip this section.
The directions found in owas3.html and
oas4.html
already covered this.
It is extremely easy to get your existing web agents on the DBAUTH cartridge. The will work unchanged from the original OWA but will now be able to do file upload/download, use an <ORACLE> tag, use database authentication, collect stats, etc.
All you need to do is change OWA to DBAUTH and remove the trailing /owa from the DCD Name. For example, if you svXXXX.app file has:
/ows-bin/owa OWA /usr/oracle/ows2/binYou will change that to:
/ows-bin DBAUTH /usr/oracle/ows2/binThats it. Period. Done.
Perhaps the easiest way to configure you .app file however is to add an entry such as:
/wa DBAUTH /usr/oracle/ows2/binInstead of modifying each existing web agent. Then, you can delete all of the OWA entries for each individual DCD. Since you mapped /wa to the cartridge, you can enter urls like:
/wa/webagent1/owa/xxx /wa/webagent2/ows/yyywithout having to map webagent1 and webagent2 separately. All you need to do in the future is create DCD entries. They are automagically mapped.
This script creates:
For more information on how this works read the OWA Blobs page from the CGI version of these applications
The first step will be to take the owarepl (owarepl.exe on NT) executable and create symbolic links (copy on NT) as such:
$ cd $ORACLE_HOME/ows/bin $ mv owa owa.old $ cp ../../../owarepl . $ ln -s owarepl owa $ ln -s owarepl owai $ ln -s owarepl owaigz $ ln -s owarepl owassi $ ln -s owarepl owaup or on windows NT C:> cd \orant\ows10\bin C:> rename owa.exe owa.old C:> copy ..\..\..\owarepl.exe . C:> copy owarepl.exe owa.exe C:> copy owarepl.exe owai.exe C:> copy owarepl.exe owagz.exe C:> copy owarepl.exe owassi.exe C:> copy owarepl.exe owaup.exeThen, you will need to make sure that one of the 2 following environment variables are set correctly:
OWS_APPFILE OWA_CGI_APPFILEThe variable OWS_APPFILE will be set by the Oracle Webserver v2.x. If you are using OWS2.x, you will not need to set any environment variables. If you are using OWS1.x or some other vendors webserver, this environment variable must be set before starting the webserver.
This environment variable points to the fully qualified file name that is the '.app' file for the webserver. Under version 2.x, this file name might look like:
OWS_APPFILE = /usr/oracle/ows2/admin/svtest.appIf you are not using OWS2.x, you must set the environment variable OWA_CGI_APPFILE to be a fully qualified filename. This filename should point to a file that contains the [DBAUTH] section see this for an example of what that section contains. This will allow the CGI-BIN version (which is really the cartridge code with a CGI-BIN wrapper) to process as though it was the cartridge version.
For Windows NT you need to set the environment variable OWA_CGI_APPFILE in the control panel under SYSTEM. Set a SYSTEM environment variable and restart the server. That appears to be the only way to get the OWS to inherit an environment variable.
[DBAUTH] owa.cfg = c:\orant\ows20\admin\owa.cfg server.cfg = c:\orant\ows20\admin\svwebsvr.cfg authenticate = stats ;web_authent_prefix = web$ dirSeparator = \ ;timingsTable = ows2.timings ;timingsModules = TOTAL debugModules = all ;debugPath = c:\orant\ows20\log\The debugModules setting will cause lots and lots of informative messages to be written to a file called wrb_DBAUTH_xxxxx.log where xxxxx will be replaced with some unique thread number. These files will by default go into the $ORACLE_HOME/owsxx/log directory. You can control where they are created by setting the debugPath variable (on Windows NT I recommend you set this path regardless of where logging will take place).
This file will contain all of the information I will need to debug an issue. It will be the first thing I ask for. It is a clear text file, by reading it yourself, you may very well be able to determine what the problem is.