README File for DB2 WWW Connection Version 1 for VM
The instructions on this page cause the following to be installed on
your VM system:
- The DB2 WWW for VM facility
- Demonstration programs and data that show you how to use the
DB2 WWW for VM facility
This page contains the following sections:
Requirements
You need the following to install DB2 WWW for VM:
- About 750 4Kb blocks of permanent storage on your VM system for
use by the web server
- About 750 4Kb blocks of temporary storage on your VM system for
use during installation
- The DB2/VM database name for a database to hold the sample program
data
- The CONNECT password for the SQLDBA userid on that DB2/VM database
- The ability to bring down the web server and log on to the
server virtual machine
- For VM:Webserver using root domain MDISK, the minimum version
level is 1.2 (VM:Webserver 1.1 can be used with root domain set to
CMS or SFS.)
- For Enterprize Web, the minimum version level is 1.3
- For WEBSHARE, the minimum version level is 2.4
Downloading DB2 WWW for VM
- You will use the VMARC compression utility to unpack the software you download.
If you need the VMARC MODULE, follow the instructions on the
http://www.vm.ibm.com/download
page to obtain it.
- Download the compressed file containing DB2 WWW Connection for VM from
the IBM web site to your PC. This compressed file contains multiple files
that you must unpack.
- LOGON to the web server virtual machine and bring down the server
to the CMS READY; prompt.
- Create an empty temporary work minidisk or directory
at least 750 4Kb blocks in size.
Access the temporary work area as the A filemode.
- Upload the compressed file from your PC to the A filemode in
BINARY.
- Run the compressed file through this pipeline to restore a fixed record
format:
PIPE < DB2WWW VMARC A ¦ fblock 80 00 ¦ > DB2WWW VMARC A F 80
This pipeline produces a file named DB2WWW VMARC.
- Unpack DB2WWW VMARC using the VMARC utility:
VMARC UNPK DB2WWW VMARC A
Installing DB2 WWW for VM
The instructions in this section make these assumptions about the file
system structure on your server:
- HTML files reside in your web server's root directory.
- GIF files reside in your web server's /images directory.
- CGI REXX programs reside in your web server's /cgi-bin directory.
If your system's file structure is different, you will need to change
the instructions to match your environment.
- Copy files from the temporary minidisk or directory to your web server:
- Copy all files with filetype HTM to your web server's root directory.
- Copy all files with filetype GIF to your web server's /images directory.
- Copy the DB2WWW CGI file to your web server's /cgi-bin directory.
(Note: If you are using VM:Webserver, copy DB2WWW VIWEXEC or
DB2WWW WRKEXEC instead.)
Which files to move where is specific to the way your web server
is configured. Possible configurations follow:
If You Are Using VM:Webserver
- Copy all files with filetypes HTM, GIF, and VIWEXEC
from the temporary minidisk or directory to the
current minidisk or SFS directory defined by the CONFIG PORT
command.
(Note: If you are using a VM:Webserver worker, copy
DB2WWW WRKEXEC instead of DB2WWW VIWEXEC.)
- Add these lines to the VMWEBSRV DIRMAP file on that minidisk or
SFS directory:
DIR cgi-bin CGIBIN
DIR images IMAGES
Use those lines to create VMWEBSRV DIRMAP if it doesn't exist.
- Create the IMAGES DIRMAP file with these contents:
FILE *.gif = GIF
- Create the CGIBIN DIRMAP file with these contents:
FILE DB2WWW = VIWEXEC
FILE DB2WWW.EXE = VIWEXEC
If You Are Using Webshare
- Copy all files with filetypes HTM, GIF, or CGI
from the temporary minidisk or directory to the
web root minidisk or SFS directory.
- In the WEBSHARE FILELIST file, add a line for each HTM file
copied from the temporary area. Specify the filename, filetype,
and filemode.
- In the WEBSHARE FILELIST file, add a line for the IMAGES
directory. It has this form:
IMAGES * *
- Create an IMAGES FILELIST file containing a line for each GIF
file copied from the temporary area.
Specify the filename, filetype, and filemode.
- Add this line to the HTBIN FILELIST file to serve the DB2WWW REXX
CGI program:
DB2WWW *CGI * db2www.exe
- Copy the files with filetype D2W to a minidisk
present in the CMS search order, or to an SFS directory. If
SFS is used, insure that the web server machine or VM:Webserver
worker machine has read access
to the D2W files. An SFS directory holding the D2W files does
not have to be accessed in the server search order. The location of
the D2W files is specified as a parameter in the DB2WWW INI file
as described below.
- Copy the files listed below to your web server machine. Place them
on any minidisk or directory present in the CMS search order.
- CPIPE MODULE
- DB2WWWA MODULE
- DB2WWW MODULE
- DB2WWW INI
- If VM:Webserver worker machines are to be used, copy
the files listed above to your VM:Webserver worker machine.
Place them on any minidisk or directory
present in the CMS search order.
- Modify the DB2WWW INI file so that the MACRO_PATH line reflects the
location of the D2W macro files. Place the INI file on any
minidisk or directory present in the CMS search order.
If a VM:Webserver worker machine is used, the DB2WWW INI file must
be present in that machine's search order.
- If the macro files are on a specific minidisk or directory:
- MACRO_PATH cms:filemode (Example: MACRO_PATH cms:B)
- If the macro files are in CMS search order:
- MACRO_PATH cms:* (Example: MACRO_PATH cms:*)
- If the macro files are on an accessed or unaccessed SFS directory:
- MACRO_PATH sf:dirid (Example: MACRO_PATH sf:VMSYSU:VMUSER.TEST.WEBROOT)
- Place these commands in the PROFILE EXEC of the web server machine so
that they are issued when the web server virtual machine is initialized:
'CPIPE'
/* Initialize the CPIPE pipeline stage */
'CP LINK ....'
/* Link to the SQL PRODUCTION disk */
'ACCESS ....'
/* Access the SQL PRODUCTION disk (or SFS directory) */
'SET LANGUAGE ( USER ADD ARI'
/* Associate SQL message repository */
'EXEC SQLINIT DBNAME(mydb)' /* Initialize the SQL connection */
/* with default server mydb */
By convention, the PRODUCTION disk is linked at virtual address 195,
and is ACCESSed as filemode Q. Your conventions may be different.
If a VM:Webserver worker machine is used, place the same commands in
that machine's PROFILE EXEC.
- If the DB2/VM database is not available when the web server is
initialized, simply re-issue the SQLINIT command in the web server
machine, when the DB2/VM database machine does become available.
- The demonstration programs contain code that assumes your system's
directory structure follows the model described above.
If your environment is different, you must modify the URL paths
in the sample HTM and D2W files to reflect your system's directory
structure.
Optimizing DB2 WWW Performance VM
The DB2WWW MODULE runs at least twice for every DB2WWW transaction.
The overhead of bringing the MODULE file into virtual memory and establishing
a C run-time execution environment for each execution can be excessive.
However, if sufficient virtual memory is available in the web server virtual
machine, the program modules can be preloaded in such a way that the execution
overhead is minimized.
To preload the program modules, place these commands in the PROFILE EXEC
of the web server machine:
'NUCXLOAD DB2WWW ( PERM'
'NUCXLOAD DB2WWWA ( PERM'
These commands ensure that the modules stay resident in the server address
space and the C execution environment is retained across module
invocations.
Installing the DB2 WWW Database Package
- ACCESS the SQL PRODUCTION minidisk or SFS directory and issue the
SQLINIT command using the DBNAME parameter for the database to be used
by DB2WWW.
- Install the supplied DB2WWW PACKAGE file
by modifying the DBSETUP SYSIN file to set the correct SQLDBA password
and running the DBSETUP EXEC. Change the SQLDBAPW token on the
first line of the DBSETUP SYSIN file to the correct password for
your environment.
Running this EXEC creates two SQL userids.
The first, D2WUSER, is used to access the database from the sample
programs.
The second, D2WOWNER, owns the demonstration program tables
and the DB2WWW package.
- Repeat this step for every database to be used by a DB2WWW application.
LI>
Installing a Sample DB2 WWW Database
- Create the DB2WWW demonstration program database tables by running
TABCREAT EXEC. Access to the tables is granted to PUBLIC.
- Load the DB2SQL demonstration table data by running TABLOAD EXEC.
- ACCESS the minidisk or directory where you loaded the D2W
files. Set the database variable in the sample programs by running
the
SETDBNAM filemode dbname
command, where filemode contains the installed D2W files
and dbname contains the name of the database.
- Re-IPL CMS in the web server virtual machine to execute the
new lines in the PROFILE EXEC and start up the web server
system.
- If running VM:Webserver, issue this
command to define the VIWEXEC filetype that the
DB2WWW REXX CGI program uses:
CONFIG FILETYPE ADD VIWEXEC CGI ENVIRONMENT SVMMACRO AUTHHEADERPASSED YES
Post-Installation
- Discard the temporary minidisk or SFS directory which was
used during the installation process.
- Run the demonstration programs by pointing your web browser at URL
http://your_server/celdemo.htm.
- Read the Application Developer's Guide by pointing your web
browser at URL
http://your_server/db2wdoc.htm.