.JSP Hello!
DataBean
Database
Figure 13. Conceptual overview of JSP page
There are three key things about this new function you should understand: 1. For WCSuite V4.1, at least initially, this new function is applicable to only two display environments: a. The CategoryDisplay function, which is used to display category pages b. The ProductDisplay function, which is used to display product pages 2. It is an entirely new architecture from the C++ architecture illustrated in 1.2.1.9, “Customizable command set” on page 11. That architecture, known as the NC 2 architecture in some circles, will remain for at least another release of
18
IBM WebSphere Commerce Suite V4.1 for OS/390
the product past WCSuite V4.1, but the strategic direction is definitely in the Java direction. 3. The command URL used to invoke the JSP page is different from the command URL used to invoke the standard NC 2 architecture. This difference is illustrated in Figure 14.
http:///webapp/commerce/servlet/ProductDisplay This maps to the JSP support, This maps to the standard NC support http:///webapp/commerce/command/ProductDisplay
Figure 14. Different URL command structure used for JSP than for standard WCSuite command
The architecture is not fully developed or documented, so for the time being it is not open to customization and extension by you. Eventually it will be, and perhaps it will be before the next release of the product, but for now it is not. This function is based on the use of “Servlets” (Java programs that run on the server rather than the client) and as such it requires that WebSphere Application Server (WAS) be part of your environment. An overview of what components are required for WebSphere Commerce Suite is provided in 1.2.3, “The system components of a WCSuite solution” on page 21. The process of installing, configuring, and testing these components together is documented in Chapter 2, “Prerequisites, installation and configuration” on page 29. 1.2.2.6 Multiple shopping carts The shopping cart in WebSphere Commerce Suite is more correctly called the “interest item list,” but everyone still calls it the “shopping cart.” In Net.Commece Version 3.1.2 there was only one shopping cart per customer. With WCSuite V4.1, that’s been extended (through extensions in the database) to permit any number of shopping carts per customer. New commands have been added that allow you to take a product and add it to a given shopping cart or all shopping carts. This feature will be used by site designers who see a need for permitting customers to have multiple carts. Some site designers may decide that one cart is adequate, and that’s certainly okay to do. 1.2.2.7 Catalog improvements This feature is actually an extension to the database to facilitate the association of products to one another in relationships such as “cross sell” and “upsell.” The relationships, once defined in the database, may then be queried for and displayed using Net.Data. There’s not a great deal more to this than that. 1.2.2.8 Order flow improvements This enhancement focuses on the ability to do quick orders, quick buys and reorders. Each of these revolve around two key concepts:
Chapter 1. An overview of WebSphere Commerce Suite OS/390
19
• Marking an existing order as a “template” and then using that “template” for other orders. This permits you to take the information associated with an existing order and copy it to a new order, which like any copy operation can save effort since much of the necessary information can be re-used. • A new command called OrderCopy, which is a very long and complex command used to copy the orders you’ve previously marked as templates. This feature is really intended for the skilled WCSuite site architect who is very familiar with the command structure and knows the order structure in the database quite well. 1.2.2.9 Mass Import utility improvements The Mass Import utility that came with Net.Commerce Version 3.1.2 was functional, but was limited in two key ways: 1. It could only import to a set number of tables, and those tables were restricted to only the product catalog related tables. 2. The performance of the utility limited the usefulness of it for input file sizes beyond a point. For very large customers with tens or hundreds of thousands of products, this performance profile rendered Mass Import unusable. To answer these concerns, the Mass Import utility was enhanced on both the input side (to allow more tables to be loaded), and on the output side (to enhance performance).Figure 15 illustrates what the structure is now.
Loading using SQL update and insert statements
XML Format
Extended Delimited
Mass Import
Database
V3.1.2 Delimited
Provides Backward Compatibility
Intermediate files in DB2 Load Utility Format
Figure 15. Mass Import utility input and output methods
On the input side, two new input file formats have been provided. The key benefit of these two formats is that they allow you to define any number of tables (even custom tables of your creation) and import to those tables. The two new formats are:
20
IBM WebSphere Commerce Suite V4.1 for OS/390
• XML: This format uses XML tags to define the table schema of the database to which you will import data, as well as XML tags to define the data being imported. Each running of Mass Import using the XML option requires that three files be availabile to the utility: a DTD file (Data Tag Definition), which defines the XML tags to be used; a Definition file, which defines the table layouts and uses XML tags defined in the DTD file; and an input file that contains the data, wrapped in XML tags, that will be loaded into the tables. • “Extended” Delimited: This looks very similar to the delimited format from Net.Commerce V3.1.2 except that it’s been extended to allow you to define additional tables into which to load data. Each running of Mass Import using this extended delimited format requires that two files be available to the utility: a Definition file, which defines the table layouts, and an input file that contains the actual data to be loaded. For the sake of backward compatibility with any input files you might have from Net.Commerce V3.1.2 for OS/390, the utility will accept that format as well. On the output side you have two different methods you may employ to get the data into the database: • Method = SQL: When this method is used, the Mass Import utility will make a connection to DB2 and then use SQL insert and update commands to load the data into the database. This is the same method used by the Net.Commerce V3.1.2 utility, but it’s been enhanced to perform better. • Method = DB2LOAD: When this method is used, the Mass Import utility will generate intermediate files in DB2 Load Utility format based on the input table definitions and data you provide the utility. The intermediate files include a JCL job stream and a column-offset data input file for each table to be loaded. It’s then up to you to submit the JCL, which invokes DB2 Load Utility to actually put the data into the tables. This method is provided because DB2 Load is a very high performance method of putting data into DB2.
1.2.3 The system components of a WCSuite solution The picture shown in Figure 16 on page 22 illustrates the pieces to the puzzle for a WebSphere Commerce Suite V4.1 for OS/390 solution.
Chapter 1. An overview of WebSphere Commerce Suite OS/390
21
S/390 DB2 V6
Net.Data V2.2
Type 2 JDBC
Websphere Commerce Suite Version 4.1
HTTP Server
Pers. Server
WAS SE V3.0.2
JDK 1.1.8
OS/390 V2.7
RRS
Websphere Commerce Studio (Win NT)
Figure 16. System components of a WebSphere Commerce Suite V4.1 solution
Not all of the components are strictly required: it depends on what functions of WCSuite you’re looking to use. Table 1 on page 23 summarizes the relationship of the components to the functions of WebSphere Commerce Suite V4.1 for OS/390 that we covered in 1.2.2, “Significant new function added with WCSuite V4.1 OS/390” on page 13. We don’t have the OS/390 operating system and the HTTP server in the table because they’re required under all circumstances (well, not all: the Mass Import utility doesn’t require the HTTP Server).
22
IBM WebSphere Commerce Suite V4.1 for OS/390
Table 1. Relationship between components and functions of WebSphere Commerce Suite V4.1
Net Data
RRS
DB2
Multiple shopping carts
n1 n n n n n
n n n n n n
Catalog improvements
n
n
n
Order flow improvements
n
n n6
n
Basic functions Job scheduler Auctions JSP pages Personalization
Mass import
JDK
WAS
JDBC
n n
n2 n4
n n
Pers. Server
WCS Studio
n
n3 n5
n n n n
Notes: 1 With WCSuite V4.1, the attachment facility between the Director code and DB2 has been change from CAF to RRSAF. Therefore, any function that requires the Director code to be involved requires RRS. 2 JSP page support uses servlets, which requires WAS. WAS is also required if you “publish” JSP pages from Studio environment, since a servlet acts as the “catcher” for the publishing process. 3 Strictly speaking, you don’t have to use the Studio to create JSP pages. But the references to the databeans are in the Studio’s pulldowns, so it makes it a much easier process. 4 The personalization server is a Java program, and as such doesn’t itself require WAS. However, the Rules Builder is part of the WebSphere Commerce Studio, and to “publish” the rule sets to the OS/390 system you need to have WAS. This is because a servlet acts as the “catcher” for the publishing process, and servlets require WAS. 5 To construct the rule sets or personalization, you must use the Blaze Rules Builder, which is part of the WebSphere Commerce Studio package. 6 The observant reader may wonder why WAS isn’t required for the XML support of Mass Import. The reason is that the Mass Import utility uses the C++ XML parser and therefore the XML parser from WAS isn’t required.
We discuss how to verify that all these pieces of the puzzle are working together in Chapter 2, “Prerequisites, installation and configuration” on page 29.
1.2.4 The overall architecture We have now come to the point where we’ll draw a big complex picture that tries to incorporate all the main points. Figure 17 on page 24 is this picture, and it illustrates the architecture of the WebSphere Commerce Suite V4.1 for OS/390 product.
Chapter 1. An overview of WebSphere Commerce Suite OS/390
23
WCSuite Server
10
HTML, Javascript
11
NCADMIN Admin. Utility
DB2 6
5
Child Daemon
CMNCONF ISPF Cfg. Tool
Process Task
Net Data
Child Daemon
8
"Backend" System
7
...
To database Child Daemon
4 Main Daemon
13
Servlet
Websphere Application Server
14
JSP
JDK
15
Pers. Engine
3 2
3270
1
9
Administrator HTML
Net.Commerce API Director
12
Web Server Internet
Shopper HTML
Figure 17. WebSphere Commerce Suite V4.1 for OS/390 overall architecture
Let's walk through each of the highlighted components shown in Figure 17: 1. The front-end of the entire system is the Webserver. (At one time called the Domino Go Webserver, it has been renamed the IBM HTTP Server, which is part of the WebSphere Application Server and which has been bundled with OS/390 V2R6). The Webserver receives the inbound HTTP requests from the browser and determines what should be done with each request: • Requests for static HTML pages are handled by the Webserver, which retrieves the HTML (and whatever image files might be associated with it) and delivers the page to the browser. In this scenario WCSuite is not involved at all. • Requests that include a WCSuite command are passed from the Webserver to the WCSuite Director, which is discussed next, or to the WebSphere Application Server if the command is one of the new Java commands (see #12). 2. The WCSuite Director is an implementation of the Go Webserver API interface (GWAPI), and is the portal through which the Webserver communicates with the WCSuite application. A GWAPI implementation is provided with WCSuite rather than a more traditional CGI implementation because of the superior performance characteristics of GWAPI. The WCSuite director actually runs in the Webserver's address space. 3. The WCSuite Director communicates across TCP sockets to the WCSuite application itself. The ports across which this communication occurs are determined by a configuration parameter set with the CMNCONF configuration utility. Generally, these ports are set at some high number (above 10000). It registers the ports in the /etc/services file.
24
IBM WebSphere Commerce Suite V4.1 for OS/390
4. The processing inside of WCSuite is handled by a main daemon and some number of child daemons. The main daemon passes off all requests to the child daemons on a round-robin basis. The number of child daemons is determined by a configuration parameter set by the configuration program. The default is 2 children, and the maximum number is 50. The more child daemons defined, the more work that can be accomplished. The child daemon, when executing a command, will do one of three things: • Access the database directly to extract information • Run a Net.Data macro that extracts information from the database and combines it with HTML to be issued back to the browser • Run a program, known as an API task, that either accesses the database or accesses other systems to complete the sales transaction. 5. Net.Data is a program that, at a high level, issues a SQL query against the database and wraps HTML around the results. 6. The WCSuite database consists of more than 200 tables arranged in a very structured model. The WCSuite database contains not just information about categories and products, but also information used to control the operation of the WCSuite application itself. 7. An API Task (now called a “Process Task”) is a program that runs to perform some function, such as checking the level of inventory, or calculating shipping charges. 8. Much of the business data in the world today exists on MVS or OS/390 systems, and many customers wish to access that data directly using exits from the WCSuite system. The API tasks just discussed are valuable for that reason: they allow programmers to come out of WCSuite processing and access these systems, returning control to WCSuite with the desired information. 9. Administrators are simply people with the knowledge and authority to add and modify information in the WCSuite database. The primary tool used to do this is a browser that accesses the administrative utility of WCSuite. 10.The NCADMIN administrative utility is a set of Javascript and HTML forms that provide an interface to the information contained in the database. 11.The CMNCONF configuration utility is a 3270-based tool that configures the “instances” of WCSuite. Instances are simply copies of WCSuite that run on the OS/390 system. Multiple instances may run at the same time, and they may either have their own database, or share a common database. 12.If the inbound URL specifies one of the new Java-based commands, the Webserver will pass the command over to the WebSphere Application Server so that the servlet that represents the command may be invoked. With WCSuite V4.1, two Java servlet commands are provided: ProductDisplay and CategoryDisplay. 13.The command is implemented in the form of a Java servlet, which will be invoked and run under the control of WAS. The servlet will contain the logic that implements the behavior of the command. The servlet will have access to the WCSuite database to query for necessary information from the database.
Chapter 1. An overview of WebSphere Commerce Suite OS/390
25
14.For the two servlet-based commands supplied with WCSuite V4.1, a JSP will be invoked by the servlet to render the dynamic HTML that will be presented back to the shopper. 15.For the Personalization feature of WCSuite, the “rules engine” runs as a Java program. If a rule is interrogated and invoked, it will be through this rules engine.
1.3 Why use OS/390 instead of other platforms? This question really boils down to what’s important to the customer. All of the platforms on which WebSphere Commerce Suite runs have their strengths and weaknesses. OS/390 is no different. The following list summarizes what we think are the key strengths of OS/390 and should be considered when evaluating the platform choice for WCSuite:
• Proximity to the backend data system If the business data resides on OS/390 and you can locate your commerce application on the same system, then you can take advantage of shorter code path network access protocols to get at that data. The more efficiency you can squeeze from the transfer of data the better the site will perform.
• Proven application platform Many S/390 customers have years of experience running rock-solid applications on S/390. To them, the skill necessary to keep an application up and running on S/390 is relatively second-nature, so the inclusion of a web-based commerce application is a good fit.
• Highly secure environment Through the years the OS/390 environment has been equipped with a very strong set of security tools (such as RACF). Because the WCSuite for OS/390 product operates in this same environment, it uses these services. Properly configured, an OS/390 Web environment is practically impenetrable.
• Very high “top end” for throughput S/390 systems are renowned for having impressive throughput characteristics. With sufficient attention paid to sizing and tuning a WCSuite solution on S/390, you can construct a site with impressive performance characteristics. And if the need exists for true 24 x 7 uptime, Parallel Sysplex can enable that better than any other clustering technology available today. Hosting a WCSuite solution on OS/390 provides many benefits, as this outline suggests, but for some customers another platform might be a better choice. IBM offers solutions across the entire spectrum of server platforms.
1.4 Our assumption of your understanding of WCSuite functions This first chapter was dedicated to providing an overview of the WebSphere Commerce Suite product, but it was never intended to be the definitive source of information. As we were planning this redbook, we faced a fairly common dilemma when writing any documentation: how much prior knowledge can we assume our readers will have? The trap authors of technical documentation often fall into is feeling as if they should explain everything, and in doing so create an enormous document that is difficult to read or use.
26
IBM WebSphere Commerce Suite V4.1 for OS/390
We have intentionally decided to not fall into that trap. Instead, we concentrated this redbook on several specific areas based on the assumption of your skills as shown in Figure 18.
Specific WCSuite OS/390 Operating Considerations This redbook will focus on these issues
Specific WCSuite OS/390 System Administration
Generic WCSuite Function Knowledge
This redbook will assume you already possess these skills
Generic UNIX Skills
Generic Web Skills (HTML, Webserver)
Generic OS/390 System Programmer Skills
Figure 18. Focus of this redbook
The fourth box from the bottom (the one marked with a star) is the one we struggled with the most. We decided to assume you already have a good knowledge of WebSphere Commerce Suite functions like auctions, personalization, the use of the administrative function, and so forth. We reached this decision because a good deal of excellent documentation and education already exists that covers those topic (see Appendix D, “Related publications and resources” on page 209). We make some reference to these things, particularly in Chapter 5, “Using WebSphere Commerce Studio” on page 127, but we chose not to make this redbook a complete tutorial on every functional aspect of WCSuite.
Chapter 1. An overview of WebSphere Commerce Suite OS/390
27
28
IBM WebSphere Commerce Suite V4.1 for OS/390
Chapter 2. Prerequisites, installation and configuration This chapter is dedicated to the topics of installing, configuring, and verifying the function of the various components of a WebSphere Commerce Suite for OS/390 system. There are quite a few pieces to the puzzle (as we illustrated in Figure 1.2.3 on page 21), so the key to this is to take a logical approach. We show you how to install the product, and then configure and verify in a logical manner that things work the way they’re supposed to.
2.1 Prerequisite software To permit your solution to operate, some prerequisite software is needed. Figure 19 illustrates what’s required.
S/390 DB2 V6
Net.Data V2.2
Type 2 JDBC
Websphere Commerce Suite Version 4.1
HTTP Server
Pers. Server
Must apply: UQ47696 UQ47697 UQ48212 UQ48213
WAS SE V3.0.2
JDK 1.1.8 RRSAF
OS/390 V2.7
Websphere Commerce Studio (Win NT)
Logger
Figure 19. Prerequisite software for WebSphere Commerce Suite V4.1 for OS/390
The picture tells the story graphically. Table 2 provides some supporting information. Table 2. Prerequisite software information
© Copyright IBM Corp. 2000
Prerequisite Software
Program Number
OS/390 V2R7, R8, R9
5647-A01
When or Why Required Documented minimum level. A lower level of the operating system (down to V2R4) would probably function, but the minimum level of OS/390 that is supported with WCSuite V4.1 is OS/390 V2R7.
29
Prerequisite Software
Program Number
When or Why Required
RRSAF (Recoverable Resource Services Attachment Facility)
(part of OS/390 operating system)
Both the WebSphere Commerce Suite and the WebSphere Application Server use RRSAF to access the DB2 database. This facility must be started on the OS/390 system to configure and use the WCSuite product.
Logger
(part of OS/390 operating system)
Required by RRSAF. If you have a Sysplex environment, you can log to the Coupling Facility; if you have a standalone system you can log to DASD.
HTTP Server V5.1 or V5.2
(part of OS/390 operating system)
Minimum level required by WebSphere Commerce Suite V4.1 in support of it’s “GWAPI” API code. The Webserver comes bundled with the OS/390 operating system; with OS/390 V2R7 came HTTP Server V5.1. OS/390 V2R8 had HTTP Server 5.2 bundled with it; OS/390 V2R9 came with HTTP Server 5.3.
JDK 1.1.8
5655-A46
Provides Java runtime environment for WAS SE V3.0.2, which is required for JSP page support and publishing from the Studio to OS/3290. Also provides Java runtime environment for Blaze Rules Server used for personalization support.
WebSphere Application Server Standard Edition Version 3.0.2
5655-A98
Required by servlets that provide JSP page support; required by servlet that provides “catcher” duties when publishing material from Studio to OS/390. Not strictly required for Blaze Rules Server (Java program, not servlet), but it is required if you wish to publish Rulesets from the NT-based Studio to OS/390.
5645-DB2
Supplied database schema is defined with triggers, which requires DB2 V6 at a minimum. Trying to run WCSuite V4.1 with DB2 V5 will not work: the database-create step will fail because the trigger definitions in the script will be unrecognized. Removing the trigger definitions from the schema script would disable necessary function, so that is not a workaround. Use DB2 V6.
(part of DB2 subsystem)
Required to support database access by Java servlets and Databeans in JSP page support; required to support database access by Blaze Rules Server for personalization support. Also required by Servlet that provides “catcher” duties when publishing material from Studio to OS/390.
Requires PTFs UQ43991 and UQ44522
IBM DB2 Version 6 Requires PTFs UQ41672, AQ39665, UQ43899, AQ39411 and UQ45727.
Type 2 JDBC (If you apply PTF UQ41672 to DB2 V6 with a Type 1 JDBC driver, it provides Type 2 JDBC support)
30
IBM WebSphere Commerce Suite V4.1 for OS/390
Prerequisite Software
Program Number
WebSphere Commere Studio on Windows NT
5648-C35
When or Why Required This is the development environment on which such tools as the Store Creator Wizard, Visual Age for Java and the Blaze Rules Creator are run. If you wish to use those tools for your site, then this is required. However, it is possible to avoid the use of this suite of tools, but it would be very difficult to use the new Java/JSP and Personalization functions.
Check with the system administrator to insure the various pieces of this puzzle are installed and available.
2.2 The installation process This step focuses on the SMP/E installation process. It is a fairly straightforward process, particularly for system programmers comfortable with SMP/E. Consult the Program Directory, GI10-8233, that comes with WebSphere Commerce Suite for detailed instructions on the installation process. Note
The TSO userid from which you perform the install needs to be UID(0) to effectively complete the CMNISMKD job. This job creates the HFS subdirectories and external links, and without UID(0), the job will not complete properly. The data sets and HFS system from this installation process will be those described in Table 3. Table 3. Data sets and HFS data sets created by installation process
Data Set Name
Type
Contains
hlq.SCMNBASE
PDS
The jobs received from the installation tape and used by the installation process.
hlq.SCMNDBRM
PDS
The Commerce Suite DBRM library
hlq.SCMNLMOD
PDS
The Commerce Suite executables
hlq.SCMNMENU
PDS
The CMNCONF configuration utility message library
hlq.SCMNPENU
PDS
The CMNCONF configuration utility panel library
hlq.SCMNSAMP
PDS
The Commerce Suite samples
/usr/lpp/CommerceSuite
HFS
The HFS in which the Commerce Suite programs reside, as well as sample HTML files, Net.Data macros and other files used by WCSuite.
Chapter 2. Prerequisites, installation and configuration
31
Important!
After installation is complete, apply the PTFs UQ47696, UQ47697, UQ48212 and UQ48213. The operation of WCSuite is seriously hampered without these PTFs. This redbook is written with the assumption these PTFs are applied. When you have completed the installation process, you simply have the files off the distribution tape and on your system. Further system preparation and configuration is needed, as discussed next in this chapter.
2.3 Post-installation configuration and verification process After the SMP/E installation process has been completed, there remains a list of things that you need to do to prepare and configure your system. The approach we outline in this book involves working through the configuration process in a logical way that builds upon each prior step. At key intervals we show how to verify that the work done to that point is functional. The process is illustrated in Figure 20.
1
2
System preparation work.
Configure JDBC Type 2 connection for DB2 access from WAS
Configure basic WCSuite instance
Configure WCSuite Java Servlet function
Verify basic WCSuite functionality
Verify sample JSP pages from Demomall work
Configure a proxy server configuration for using WCSuite Java functions
Create project in Commerce Studio and configure Studio to recognize S/390 system
Configure WebSphere Application Server (WAS) to run in second Webserver
Verify ability to publish simple project from Commerce Studio
Verify basic WAS Servlet functionality
Configure WCSuite "scheduler" and personalization function
3
4
5 Verify basic auction and personalization function
Figure 20. Logical process for configuration and verification of WCSuite system
As you can see in Figure 20, we are suggesting a five-step approach, with verification steps at the end of each step. This process will confirm the basic operation of the WCSuite system. Any further customization you wish to do for your site would be in addition to the steps outlined here.
32
IBM WebSphere Commerce Suite V4.1 for OS/390
2.4 Phase 1: Basic WCSuite function verification In this phase you verify that the basic system components are present, perform some system administration work, then test access to WCSuite using the basic functions provided by product. Follow the steps provided here.
2.4.1 Provide PUBLIC access for users Defining PUBLIC on the Userid directive of the Webserver’s configuration file (typically found at /etc/httpd.conf) provides a surrogate ID under which documents will be served to browsers. A commerce solution will imply many users — most of whom you do not know — accessing your site. Therefore, you will want to make certain the surrogate ID PUBLIC is used. PUBLIC is defined with very little authority. The section of httpd.conf where the Userid directive appears looks like this: # Example: UserId # UserId # UserId # UserId # UserId
PUBLIC %%CLIENT%% %%CERTIF%% %%SERVER%% %%CLIENT%%
This assumes that the ID PUBLIC has been established. If is has not, here are the RACF commands to do that: ADDGROUP GENERAL SUPGROUP(OMVSGRP) OMVS(GID(99)) ADDUSER PUBLIC DFLTGRP(GENERAL) NOTSO OMVS(UID(99))
The webserver’s ID (typically WEBSRV) needs to have surrogate authority over the PUBLIC ID for this all to work. So issue these RACF commands: RDEFINE SURROGATE BPX.SRV.PUBLIC UACC(NONE) PERMIT BPX.SRV.PUBLIC CLASS(SURROGAT) ID(WEBSRV) ACC(READ)
2.4.2 Enable program control on datasets If you have program control already defined, issue the command: RALTER PROGRAM * ADDMEM(‘hlq.SCMNLMOD’/’volser’/NOPADCHK) UACC(READ)
where hlq is the high-level qualifier for the WCSuite data sets you used at installation and volser is the volume-serial. (If this is the first time program control is turned on, issue RDEFINE rather than RALTER. The rest of the command would be the same.) To refresh the program control profile, issue: SETROPTS WHEN(PROGRAM) REFRESH
If not already done, you will need to turn on program control for the data sets containing the run-time libraries for DB2 (hlq.SDSNLOAD and hlq.SDSNEXIT), C++ and LE as well. Failure to program control a data set used by the HTTP Server results in an Error 500 message on the browser screen.
2.4.3 Create group ID and user ID under which WCSuite will run The recommended default group ID and user ID are CMNGRP and CMNSRV, respectively. To create the group ID, enter the following command: ADDGROUP CMNGRP SUPGROUP(SYS1) OMVS(GID(2))
Chapter 2. Prerequisites, installation and configuration
33
To create the user ID, enter the following four commands in the order shown: ADDUSER CMNSRV DFLTGRP(CMNGRP) OMVS(UID(0) HOME(‘/usr/lpp/CommerceSuite’) PROGRAM (‘/bin/sh’)) PERMIT BPX.DAEMON CLASS(FACILITY) ID(CMNSRV) ACCESS(READ) PERMIT BPX.SERVER CLASS(FACILITY) ID(CMNSRV) ACCESS(UPDATE) SETROPTS RACLIST(FACILITY) REFRESH
2.4.4 Update STEPLIB in Webserver’s start procedure This provides the Webserver access to the data sets it needs to run the WCSuite “director” component. In this example, the high-level qualifier for WCSuite is WCS41, and the high-level qualifier for the C++ Class Libraries is CBC. //STEPLIB // //
DD DSN=WCS41.SCMNLMOD,DISP=SHR DD DSN=CBC.SCLBDLL,DISP=SHR DD DSN=DSN610.SDSNLOAD,DISP=SHR
You do not need to do this if these data sets are defined in LNKLSTxx or PROGxx.
2.4.5 Update Webserver’s environment variables file The Webserver’s environment variables file is typically /etc/httpd.envvars. Update the NLSPATH variable to include: /usr/lpp/CommerceSuite/msg/en_US/%N
And update the LIBPATH variable to include: /usr/lpp/CommerceSuite/lib
You will need to stop and restart the Webserver to pick up this change, as well as the change made to the httpd.conf file.
2.4.6 Bind WCSuite DBRM plan Binding the WCSuite database plan allows a WCSuite instance the ability to communicate with its database. It is also critical because if you don’t do it, you won’t be able to create or load the database. A sample BIND job is supplied in the hlq.SCMNSAMP(CMNBIND) data set member. Simply modify the JCL according to the instructions provided in the comments and submit the job. A return code of 4 is normal.
2.4.7 Update WCSuite environment variables file The WCSuite product has its own environment variables file, which provides information about the environment to the WCSuite system. This gets a little tricky because there are four copies of the WCSuite environment variables file when the CMNCONF configuration program is finished. This step focuses on two things: 1. Updating the sample envvars file (called ncommerce.envsamp) to reflect your system environment. 2. Copying that updated sample to /etc and renaming it to ncommerce.envvars. This provides the CMNCONF utility an environment file which it will use to operate. Do the following three things in preparation for running CMNCONF:
34
IBM WebSphere Commerce Suite V4.1 for OS/390
1. Make a backup of the original ncommerce.envsamp found in the directory /usr/lpp/CommerceSuite/install directory. 2. Edit the original ncommerce.envsamp and make sure the settings in this file match your environment. IBM WebSphere Commerce Suite Pro Edition for OS/390 Configuration Guide Version 4.1 (SC27-0696) has information on the contents of this file. Generally, you won’t have to make too many changes unless you’ve installed the HTTP Server at something other than /usr/lpp/internet or WCSuite at something other than /usr/lpp/CommerceSuite.
3. Copy the ncommerce.envsamp to the /etc directory, and rename it ncommerce.envvars. This will provide the environment variables with which CMNCONF itself will run.
2.4.8 Create shared object files for CMNCONF Before you run CMNCONF, you need to create shared object files that point from the HFS to load module members in the hlq.SCMNLMOD data set. This only needs to be done once, immediately after installation. Do the following: 1. Go to an OMVS shell. 2. Switch to the /usr/lpp/CommerceSuite/lib directory. 3. Run the setupnc2.sh shell script located in that directory.
2.4.9 Prepare TSO environment to run CMNCONF panel application To run the CMNCONF program, you need to provide it two things: 1. Access to the WCSuite hlq.SCMNLMOD data set 2. Access to the WCSuite message (hlq.SCMNMENU) and panel (hlq.SCMNPENU) data sets
2.4.9.1 Access to SCMNLMOD This is accomplished either by placing hlq.SCMNLMOD in LNKLSTxx or PROGxx, or by activating it for your TSO session directly. In this redbook we’ll focus on the latter. (If you have the data set in LNKLST but have not yet activated the changes, then you can issue the TSOLIB command to temporarily activate it while you wait for LNKLST to be refreshed). From the TSO READY prompt ( not the ISPF Option 6 command line) issue the command: TSOLIB ACT DSN(‘hlq.SCMNLMOD’)
Then proceed into ISPF. The CMNCONF utility will now have access to its executables.
2.4.9.2 Access to message and panel libraries Provide your ISPF environment access to the WCSuite panel and message libraries for CMNCONF, as shown in Table 4 on page 36.
Chapter 2. Prerequisites, installation and configuration
35
Table 4. ISPF library concatenations
ISPF Library
WCSuite Data Set
ISPPLIB
hlq.SCMNPENU
ISPMLIB
hlq.SCMNMENU
This is done by concatenating the data sets to the ISPPLIB and ISPMLIB DD statements in your TSO logon procedure. As an alternative to updating your TSO logon procedure, you may also create a CLIST that performs LIBDEF commands to give your session access to the datasets. On our test system used to write this book, that CLIST was called NETCOM and it looked like this: /*REXX*/ trace e address "ISPEXEC" "CONTROL ERRORS RETURN" address "ISPEXEC" "LIBDEF ISPPLIB DATASET ID('CMN.SCMNPENU')" address "ISPEXEC" "LIBDEF ISPMLIB DATASET ID('CMN.SCMNMENU')" address "ISPEXEC" "LIBDEF ISPLLIB DATASET, ID('CMN.SCMNLMOD','DSN610.SDSNLOAD')"
Consult your system programmer if you are not certain where your logon procedure is, or how to create and invoke CLISTs.
2.4.10 Enable superuser if TSO ID is not UID(0) When you installed the WCSuite product, the directory tree off the mount point of /usr/lpp/CommerceSuite will have been created with permissions of 755 (“write” for the owner, “read” for the group and “read” for others). The CMNCONF program will attempt to create directories under /usr/lpp/CommerceSuite, and unless the TSO ID under which CMNCONF is running has the authority, the process will fail. The first indication of a problem will be a “Cannot create directory” message on the second System Configuration panel of CMNCONF. The easiest way around this is to run CMNCONF from a TSO ID with UID(0). However, even if your TSO ID’s OMVS segment does not have UID(0), it is possible to achieve superuser status for the TSO ID. This is done by turning on the BPX.SUPERUSER facility class of RACF and then defining your ID with READ access to the facility. Once done, you can toggle to superuser in ISHELL or OMVS. To run CMNCONF you must get yourself back to the ISPF Option 6 panel. Unfortunately, doing so sometimes results in your losing superuser status. To work around this and guarantee superuser for CMNCONF, use the process illustrated in Figure 21 on page 37.
36
IBM WebSphere Commerce Suite V4.1 for OS/390
1
"Enable Superuser" under "Setup" pulldown of ISHELL screen.
2 Split the screen
3 Run CMNCONF from this screen.
Figure 21. Splitting the screen and running CMNCONF
2.4.11 Prepare separate HFS and mount-point for configuration files By default, the CMNCONF utility will scatter configuration files into several different directories. This is illustrated in Figure 22.
/ (root)
ncconfig.dat
/etc
.conf .envvars
/NC
/usr/lpp/CommerceSuite
/html
This is the default. We will place our configuration files differently.
/en_US
/
db2www.ini ncommerce.conf scheduler.conf ncommerce.envvars
Figure 22. Where CMNCONF placed configuration files by default
Chapter 2. Prerequisites, installation and configuration
37
These are the configuration files for just the basic WCSuite functions. There are more when you bring into play the Java functionality. This gets to be a concern for customers for the following reasons: • It is confusing. • Customers generally want to locate all the configuration files in a single, separate directory, and have that directory be its own HFS system. This aids in backup and recovery, and for migrating environments across systems. Fortunately, this is possible with WCSuite, and is fairly simple. Do the following: 1. Create a directory in your HFS system that will serve as a mount-point for a separate HFS that will hold your configuration files. This can be anywhere in the directory structure, but the recommendation is that it not be in the /usr/lpp/CommerceSuite directory, and that it be located somewhere relatively low in the tree. For the sake of illustration, assume that directory is /u/cmnsrv/configs. 2. Make sure that directory has permission bits of 755, and all the directories leading up to that new directory have 755 or higher. When WCSuite goes looking for its configuration file, it has to be at read and execute on the files to operate. 3. Allocate a separate HFS and mount it at the /u/cmnsrv/configs directory. The HFS doesn’t have to be that large: the configuration files will end up being only a few thousand bytes. Now you have an isolated location for your configuration files, as illustrated in Figure 23.
Still in /etc ... can't avoid it.
/ (root)
/etc
ncconfig.dat ncommerce.envvars
All configuration files located in a single, separate directory that is also its own HFS.
/u /cmnsrv /configs
HFS
/usr/lpp/CommerceSuite
Figure 23. Single directory for configuration files
38
IBM WebSphere Commerce Suite V4.1 for OS/390
.conf .envvars ncommerce.conf ncommerce.envvars db2www.ini
Only system code is supplied in the /usr/lpp/CommerceSuite directory. Future maintenance from IBM will not disturb your configuration files.
The files do not yet exist, as you have not yet run the CMNCONF utility. But when you do run the utility, you will point to this directory as the location into which the files will be written.
Note 1 You may wish to configure your system to automount this HFS at IPL time. Otherwise, it will require you to manually mount it each time the system is IPLed. Note 2 The example we’ve shown you here (/u/cmnsrv/configs) works fine when you have only one instance of WCSuite configured. If you wish to utilize separate instances you will have to utilize separate directories for each instance’s configuration files. This is because each instance will use a file called ncommerce.conf, and to maintain uniqueness you will have to have them in separate directories. This can be easily accomodated by having sub-directories under the configs directory in our example: /u/cmnsrv/configs/inst1 and /u/cmnsrv/configs/inst2.
2.4.12 Configure an instance using the CMNCONF utility An instance of WebSphere Commerce Suite is a running copy of the program on your OS/390 system. The design of the product permits you to configure and run more than one instance within a single OS/390 operating system. The reasons for doing this vary; usually it’s done to provide different testing groups their own copy of WCSuite to start and stop and modify as they please. WCSuite instances are configured using the CMNCONF configuration utility. CMNCONF is an ISPF panel application that takes input from you and then makes the necessary updates on your system to allow an instance of WCSuite to run.
2.4.12.1 Overview of the CMNCONF configuration utility The CMNCONF configuration program is an ISPF panel-based application. It has four main sections; you create your configuration by stepping through the sections one at a time . Figure 24 on page 40 illustrates the flow of the program.
Chapter 2. Prerequisites, installation and configuration
39
System Configuration
Initial Panel 1. Create Instance 2. Modify Instance 3. Delete Instance
Options Panel 1. System Conf. 2. Access Cont. 3. DB Create 4. DB Load
Panel 1 of 3
Panel 2 of 3
Panel 3 of 3
And return to Options Panel
Access Control
Panel 1
And return to Options Panel
Database Create
Panel 1
And return to Options Panel
Database Load
Panel 1
And return to Options Panel
Figure 24. Flow of a CMNCONF configuration run
Note 1: Stepping through all four is typically only done on your first run, or when you are creating an entirely new instance. If you are modifying an instance, typically only options 1 and 2 are performed. Note 2: The configuration files are created and the updates to httpd.conf made after you press Enter on the Access Control (Option 2) panel. Note 3: We weren’t completely truthful in this picture: Options 4 (Database Load) has a second panel if you’re creating a custom database. But that’s not a commonly used option and we won’t cover it in this book. The output from CMNCONF is a set of configuration files, which is discussed in the next section.
2.4.12.2 Overview of CMNCONF configuration files created The purpose of the CMNCONF program is to create a set of configuration files that represent the instance of WCSuite. Figure 25 on page 41 illustrates the configuration file output from the CMNCONF program. Note
The illustration we provide in this book shows the placement of all the configuration files into a single directory. That is different from the default placement of the configuration files.
40
IBM WebSphere Commerce Suite V4.1 for OS/390
/ (root)
/etc
ncconfig.dat ncommerce.envvars httpd.conf services
1 2 3 4
/u /cmnsrv /configs
HFS
5 .conf .envvars 6 7 db2www.ini 8 ncommerce.conf 9 scheduler.conf 10 ncommerce.envvars
/usr/lpp/CommerceSuite
Figure 25. Directory and file output from the CMNCONF utility
Following is a brief description of these files. 1. The ncconfig.dat file is created by CMNCONF and it contains one line per WCSuite instance created. This is how CMNCONF knows what’s already been configured on the system. 2. The nccomerce.envvars file is an environment variables file that you hand-copy down to the /etc directory to give the CMNCONF program (which is a UNIX Systems Service program) an environment in which to run. The WCSuite product comes with a sample envvars file, and back in 2.3, “Post-installation configuration and verification process” on page 32 you were given instructions on updating this to match your system and then copying it over to /etc. 3. The httpd.conf file is the Webserver’s configuration file. The CMNCONF program will update this file with Pass and Service directives necessary to tell the Webserver how to communicate with the WCSuite product. You may point to this file anywhere in your HFS system. Typically the file resides in /etc, but many people isolate the Webserver’s configuration files just as we’re isolating our WCSuite configuration files. So it may be somewhere other than /etc. 4. The services file under the /etc directory is used to record TCP port numbers used by the various communication services on the system. The TCP ports across which the WCSuite director code talks with the main daemon code are registered in this file (see “The overall architecture” on page 23 for a description and picture of the director and daemon relationship). The CMNCONF program will create this file if it doesn’t exist, or it will simply update it with the port numbers if the file already exists.
Chapter 2. Prerequisites, installation and configuration
41
Note: There’s a potential problem here that you should be aware of. If your system utilizes a services file in an MVS PDS file and you have no /etc/services file, then CMNCONF will create the /etc/services file with its port values. Unfortunately, the search order used by OS/390 to locate the port information is UNIX Systems Servics first, and then MVS PDS. And if it finds the USS file it’ll stop looking and therefore not find your MVS PDS file. That means your TCP services defined in the MVS PDS file will not work 5. The .conf file is a configuration file for the “Server Controller.” It’s not really important that you understand what a Server Controller is, but it is important that you know this file exists, and that it is in this file that a pointer is made to the primary configuration file shown at points #8 and #9 in Figure 25 on page 41. The CONTROL_POOL_CONFIG directive in the .conf file is what points to the scheduler.conf configuration file, as well as the ncommerce.conf file There is a field on a CMNCONF utility panel that allows you to specify the directory into which this file will go. Since our objective is to place all of our configuration files into a single, separate directory, we will use that panel input field to specify the /u/cmnsrv/configs directory. 6. In the same directory in which the .conf file resides there is another copy of the environment variables file for WebSphere Commerce Suite. And just like for the configuration file, the name is made unique by appending the instance name to the file name. This envvars file supplies the Server Controller with the environment it needs to operate. 7. The initialization file for Net.Data is called db2www.ini. It is in this file that Net.Data finds information about the directories in which it will search for macros, as well as other information used by Net.Data. 8. The ncommerce.conf file is the primary configuration file for your instance. The “ncommerce” portion of this name is a reference to the Net.Commerce roots of the WebSphere Commerce Suite product. Much of the information you put into the fields of the CMNCONF ISPF panel application finds its way into this file. This file is referenced by a pointer in the .conf file. The CONTROL_POOL_CONFIG directive in the .conf file has a reference to the ncommerce.conf configuration file, as well as the scheduler.conf file. 9. The scheduler.conf file is used by the WCSuite Job Scheduler (see 1.2.2.1, “Job scheduler” on page 13 for a description of the function of the Job Scheduler). This file is referenced by a pointer in the .conf file. The CONTROL_POOL_CONFIG directive in the .conf file has a reference to the scheduler.conf configuration file, as well as the ncommerce.conf file. 10.Finally, there is yet another copy of the environment variables file and it is located in this directory as well (that makes a total of three copies of the envvars file). It should be identical to the other copies of the envvars file, and indeed the CMNCONF program uses a single “model” as its source for these files.
42
IBM WebSphere Commerce Suite V4.1 for OS/390
2.4.12.3 Starting CMNCONF and creating an instance You start CMNCONF by going to the ISPF Option 6 panel and entering the command CMNCONF. If you have performed all the tasks identified up to this point, you should get the screen shown in Figure 26.
CMNTAB---- CONFIGURING THE WEBSPHERE COMMERCE SUITE SYSTEM --- Row 1 to 2 of 2 COMMAND ===> ******************************************************************* * Licensed Materials - Property of IBM * * 5697-G05 * * (C) Copyright IBM Corp. 2000 All Rights Reserved * ******************************************************************* This panel allows you to configure a new instance of a WebSphere Commerce Suite Server or modify or delete the configuration of an existing instance.
1
Instance Operation ===> (1 = new, 2 = modify, 3 = delete) 2 Instance Name ===> Optional Config and Envar File Path for configuring a new instance: ===>
3 -------- Existing Instances --------------------------------------------------Name Host Name
4
******************************* Bottom of data ******************************** F1=HELP F2=SPLIT F3=END F4=RETURN F5=RFIND F6=RCHANGE F7=UP F8=DOWN F9=SWAP F10=LEFT F11=RIGHT F12=RETRIEVE
Figure 26. CMNTAB: The first panel of CMNCONF
The CMNTAB panel is the “Initial Panel.” This panel allows you to create new instances, modify existing instances, or delete instances. There are four input fields on this panel (referenced by number in Figure 26): 1. Instance Operation: This is where you specify what you wish to do with this invocation of CMNCONF. The choices are 1 for a new instance, 2 for modifying an existing instance (which would require you to then name the instance in the Instance Name field), and 3 for deleting an instance (which again would require you to name the instance). For a new instance, use 1. 2. Instance Name: You can name an instance anything that you would like, up to eight characters. Since the name will be used in the file name of two of the configuration files, the instance name cannot contain special characters that Unix Systems Services doesn’t allow for file or directory names. In our example the instance name is wcs41. By the way, like all Unix systems, the name is case-sensitive. 3. Optional Config and Envvars File Path : This is used to specify a directory in which a model configuration file resides. The idea is you can have a model configuration file populated with information for your site, and it’ll save you time filling in fields when you run CMNCONF. However, we have found that some of the information in the model input file doesn’t make it to the final configuration file, which means there’s a bug in the CMNCONF code. So we won’t make use of this feature. 4. Existing Instances: This field lists all the other instances already configured on the system. You can use F7 and F8 to scroll up and down in this list if it is
Chapter 2. Prerequisites, installation and configuration
43
long. The CMNCONF utility knows about other instances based on the information it finds in /etc/ncconfig.dat. When you press the enter key after filling in this information you are taken to the primary options panel of the CMNCONF utility, which is illustrated in Figure 27.
CMNMAIN----- WEBSPHERE COMMERCE SUITE INSTANCE CONFIGURATION MANAGER --------SELECT OPTION ===> Instance Name
===>
To configure a new instance of a WebSphere Commerce Suite Server, select choices 1 through 4 (except do not select 3 or 4 if you want to use an existing database). These panels prompt for information that is then used to update the various configuration files used by the WebSphere Commerce Suite Server instance and to create, load, or delete a WebSphere Commerce Suite database. 1. System Configuration - change settings of your WebSphere Commerce Suite instance 2. Access Control - change WebSphere Commerce Suite server directories 3. Database Create - create or delete a WebSphere Commerce Suite database 4. Database Load - load a WebSphere Commerce Suite database from del files Enter END COMMAND to return to the main panel.
F1=HELP F7=UP
F2=SPLIT F8=DOWN
F3=END F9=SWAP
F4=RETURN F10=LEFT
F5=RFIND F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 27. CMNMAIN: The main option panel
The CMNMAIN panel is the same thing as the “Options Panel” shown in Figure 24 on page 40. From here you simply select the option you wish to go to. You will return to this panel after completing each of the configuration steps.
2.4.12.4 CMNCONF System Configuration option This option has two panels associated with it. The first panel is illustrated in Figure 28.
44
IBM WebSphere Commerce Suite V4.1 for OS/390
CMNCNF1------------- SYSTEM CONFIGURATION - PART 1 OF 3 ----------------------COMMAND ===> Instance Name
1
===>
Web Server Instance Host Name ===> Port Number ===> Number of Processes ===> DB2 DB2 DB2 DB2
Subsystem Name Plan Name Database Owner Database Name
2 3
5
4
6 7
===> ===> ===> ===>
8
9 ===> Password Storage Server Controller Conf File ===>
(%%DB2%% or %%SAF%%)
10
Enter END COMMAND to return to the INSTANCE CONFIGURATION menu. F1=HELP F7=UP
F2=SPLIT F8=DOWN
F3=END F9=SWAP
F4=RETURN F10=LEFT
F5=RFIND F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 28. CMNCONF System Configuration Part 1 of 3 panel
A description of the fields in this panel follows. (The numbers included with the definitions refer to the notations in Figure 28.) 1. Instance Name: This field will be filled in for you based on the instance name you specified on the CMNTAB panel. 2. Webserver Instance Host Name: This field is used to specify the host name URL to be used by this instance of WCSuite. It must be in the form of a host name ( not dotted decimal IP address). Many people will simply use the host name of their IP stack for this field, and that is perfectly acceptable. However, for testing purposes you may wish to use a different host name. The Webserver will see the URL on the inbound request and associate it with the directives in httpd.conf for that host name. For the sake of illustration, assume you use the host name of the IP stack of your system. At the ITSO where this redbook was written the IP host name was wtsc54oe.itso.ibm.com. We used that for our “Webserver Instance Host Name” as well. 3. Port Number: This is the local TCP port across which the director code will communicate with the WCSuite server. If you look back to Figure 17 on page 24, this is the “3” reference tag on the illustration. The CMNCONF utility will pick a number relatively high in value as the starting point for the range of ports it will use. CMNCONF wil look in the /etc/services file (if one exists) to see if anything else on the system is using that range of port numbers. WCSuite will use as many ports as “Processes” (see next item in this list), plus one. In almost all cases you can simply accept the value CMNCONF comes up with. The only issue would be if you have another process on your system that uses a port in the range CMNCONF assigned. 4. Number of Processes: This refers to the number of child processes that will be run within the WCSuite server address space to handle work requests. This
Chapter 2. Prerequisites, installation and configuration
45
number defaults to 2, and may be up to 50 (although the online help says 99, don’t let that number go above 50). The more processes employed, the more work that can be handled. The more processes, the more resources consumed. (At this point we do not have information on the system resources consumed per process.) For your first configuration, accept the default of 2. 5. DB2 Subsystem Name: This is the DB2 subsystem name on which the WCSuite database will reside. Your system may have multiple DB2 subsystems, but the WCSuite database can only reside on one. Specify the subsystem name. For this redbook, the subsystem name was DB2P. 6. DB2 Plan Name: This value should match the value used when you bound the database plan back in 2.4.6, “Bind WCSuite DBRM plan” on page 34. The sample BIND job (CMNBIND) has a default value of mserver, so the default value of mserver in CMNCONF will match. If you changed the value in the BIND job, then change it here to match. 7. DB2 Database Owner: This value should match the name of the ID you created back in 2.4.3, “Create group ID and user ID under which WCSuite will run” on page 33. The example we provide in this redbook is CMNSRV. 8. DB2 Database Name: This value may be anything you wish, as long as the database name doesn’t already exist. For your first time, use DEMOMALL since that’s the sample mall we will have you load. 9. Password Storage: This value specifies where WCSuite will go to verify the password provided when a shopper logs into the system. There are two options: • %%DB2%% means WCSuite will go look in the SHOPPER table of the WCSuite database for the password. The userid/password combination is stored in SHOPPER when a user registers. • %%SAF%% means WCSuite will go look in RACF (or equivalent) for the password. Using this option implies additional manual updates to the httpd.conf file, which are not covered in this redbook. When you first install WCSuite, you should use %%DB2%%. It is far simpler and allows you to validate all the connections of the system first. Later, you may change this to access RACF if you wish. 10. Server Controller Conf File : This field is used to specify the name and location where CMNCONF will write out the “server controller configuration file”, which is the file referenced with the number 5 tag in Figure 25 on page 41. The default for this is /etc/NC/.conf, but since we are trying to force all the configuration files into a single directory, you should specify that directory. So for this example, this field would be filled in with: /u/cmnsrv/configs/wcs41.conf
When you are finished filling in the fields on this panel, press the Enter key to move to the next panel — panel 2 of 3 for System Configuration — which is shown in Figure 29.
46
IBM WebSphere Commerce Suite V4.1 for OS/390
CMNCNF2------------- SYSTEM CONFIGURATION - PART 2 OF 3 ----------------------COMMAND ===>
1 Locale Name Cache Control HTML Path
2
===> ===> ===>
(0 = disable, 1 = read/write, 2 = read only)
3 Web Server Config File
===>
Logging Level Log File Location
===> ===>
4 5 6
Enter END COMMAND to return to SYSTEM CONFIGURATION - PART 1 OF 2.
F1=HELP F7=UP
F2=SPLIT F8=DOWN
F3=END F9=SWAP
F4=RETURN F10=LEFT
F5=RFIND F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 29. CMNCONF System Configuration Part 2of 3 panel
The fields of the CMNCNF2 panel have the following meanings: 1. Locale Name: This defaults to en_US, and unless you’re very well versed in international language issues, leave it at en_US. 2. Cache Control: This controls the feature that caches the HTML output from Net.Data macros. It is a very nice feature for improving performance, but it is not something you want activated when you first start out with WCSuite. This value defaults to 1, which means caching will take place. Our recommendation is to set this to 0 initially, and change it to 1 or 2 only after you are comfortable with the operation of the WCSuite site. 3. HTML Path : This tells CMNCONF where to place the configuration files. It also defines the “document root” for the WCSuite instance. To achieve the single location for configuration files, you must specify that directory location here. In our example, that would be /u/cmnsrv/configs. 4. Webserver Config File: This tells CMNCONF where to go to get the HTTP Server’s configuration file. By default this is /etc/httpd.conf, but your system may have a different location and file name. Simply point to the file you use. 5. Logging Level: This controls the trace level for the WCSuite server. This defaults to 0 and should remain 0 unless you need to do some debugging. 6. Log File Location : By default the output from the server tracing (“logging level” set greater than zero) will go to the SRVOUT and SYSPRINT DD locations for the started task. You can reroute that trace output to HFS files by specifying a directory location here. For now, leave this blank. When you press the enter key you will be taken to the third panel of "System Configuration," which is shown in Figure 30.
Chapter 2. Prerequisites, installation and configuration
47
CMNCNF3------------- SYSTEM CONFIGURATION - PART 3 OF 3 ----------------------COMMAND ===> 1 Order Notification ===> OFF (ON or OFF) 2 Start Scheduler ===> NO (YES or NO) Config Personalization ===> NO (YES or NO) 3
4 5
Java settings below are required for Product Advisor and Studio Publisher JDBC DRIVER ===> ibm.sql.DB2Driver JDBC NET DRIVER ===> COM.ibm.db2.jdbc.app.DB2Driver JDBC URL ===> jdbc:db2os390:LOC1 JDBC NET URL ===> jdbc:db2:LOC1 DB Password ===> Verify DB Password ===> JRE Path ===> /usr/lpp/java/J1.1/bin
6
7
Java Class Path ===> /usr/lpp/java/J1.1/lib/classes.zip:/usr/lpp/db2/ db2610/classes/db2sqljclasses.zip:/usr/lpp/db2/classes/db2sqljruntime.zip:/usr/l pp/CommerceSuite/lib/pznadvserver.jar:/usr/lpp/CommerceSuite/lib/pznadvclient.ja r: Enter END COMMAND to return to SYSTEM CONFIGURATION - PART 2 OF 3.
F1=HELP F7=UP
F2=SPLIT F8=DOWN
F3=END F9=SWAP
F4=RETURN F10=LEFT
F5=RFIND F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 30. CMNCONF System Configuration 3 of 3
The fields of the CMNCNF3 panel are described as follows: 1. Order Notification: Controls whether the administrator will receive order notification messages if that facility is also configured using the NCADMIN tool. This redbook will not cover this topic. Leave this at the default of “Off.” 2. Start Scheduler: This is used to configure the scheduler function, which is critical to the auction facility and automated ordering. In 2.8, “Phase 5: WCSuite scheduler and personalization validation” on page 99 you will do this. For now, leave this set at its default of “No.” 3. Config Personalization : This is used to configure the personalization function. In 2.8, “Phase 5: WCSuite scheduler and personalization validation” on page 99 you will do this. For now, leave this set at its default of “No.” 4. JDBC information: These four fields are used to configure the JDBC connectivity for the instance of WCSuite. Review the information with the DB administrator to ensure the information is correct. Modify it to fit the JDBC environment at the location. 5. DB Password : The password for the ID under which the WCSuite instance runs (typically CMNSRV) will have a password in RACF. The WCSuite configuration file ncommerce.conf will have an encrypted string for DB_PASS that must match the password value found in RACF. These two fields are used to supply the CMNCONF program with the password so that it can be encrypted and placed in ncommerce.conf. Check with the security administrator to coordinate how the password for CMNSRV (which is a UID(0) ID and whose password will be guarded closely) can be entered here. 6. JRE Path : This field is used to point to where the “Java Runtime Environment” (JRE, also known as the JDK) is installed on this system. If the default value is not correct, modify it to match the system's JRE installation location.
48
IBM WebSphere Commerce Suite V4.1 for OS/390
7. Java Class Path : This field is used to provide a classpath for Java classes needed by WCSuite. The field is populated with directories and ZIP or JAR file names. Review the string to make sure the directories are correct. Press the Enter key and you will be returned to the CMNMAIN panel with a message indicating “Server Config Successful.” Warning
No output is written after completion of the “System Configuration” steps of CMNCONF. That occurs after the “Access Control” option is completed. If you make changes to the information contained in the System Configuration panels, always remember to do the Access Control step as well to make sure the changes are updated in the configuration files.
2.4.12.5 CMNCONF Access Control option
CMNACC1------------------------ ACCESS CONTROL -------------------------------COMMAND ===> Instance Name
===>
Macro Path
===>
WCS CGI-BIN Path
===>
Server Install Path
===>
Enter END COMMAND to return to the INSTANCE CONFIGURATION menu. F1=HELP F7=UP
F2=SPLIT F8=DOWN
F3=END F9=SWAP
F4=RETURN F10=LEFT
F5=RFIND F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 31. CMNCONF Access Control panel
The Access Control step is important because the output to the configuration files takes place after Access Control has completed. The fields on this panel default to what you should need, unless you have installed WCSuite in a directory other than /usr/lpp/CommerceSuite . Assuming you have not modified the default install path for WCSuite, just press the Enter key. You should get a message saying “Access Control Succeeded” and find yourself back at the CMNMAIN panel.
2.4.12.6 CMNCONF Database Create option There are two important things that must be done prior to attempting to create the database using CMNCONF: 1. The database plan must be bound. See 2.4.6, “Bind WCSuite DBRM plan” on page 34 for a description of that process.
Chapter 2. Prerequisites, installation and configuration
49
2. The DB2 subsystem must be running. Note
At the time of the writing of this Redbook, there appears to be a problem introduced with PTFs UQ47696, UQ47697, UQ48212 and UQ48213. A member of the hlq.SCMNSAMP dataset called DEMOMALL is missing. Without that member, you can’t create the database using this step. You will need to acquire a copy of that member before you can execute this step.
The panel used for creating the database is illustrated in Figure 32.
CMNDBC------- CREATE OR DELETE A WEBSPHERE COMMERCE SUITE DATABASE ----------COMMAND ===> This panel allows you to create or delete a WebSphere Commerce Suite database. Instance Name DB2 Database Owner Database Name
===> ===> ===>
Database Type
===>
(1 = demomall, 2 = base, 3 = custom)
Database Operation
===>
(1 = create, 2 = delete)
1 2
3
For Creating or Deleting a supplied (not custom) WebSphere Commerce Suite database: 4 Data Set Name ===> For Creating or Deleting a Custom Database: Custom Script Name ===> 5
Enter END COMMAND to return to the INSTANCE CONFIGURATION menu. F1=HELP F2=SPLIT F3=END F4=RETURN F5=RFIND F7=UP F8=DOWN F9=SWAP F10=LEFT F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 32. CMNCONF Database Create option panel
1. Instance Name , DB2 Database Owner and Database Name: We have combined these three fields into one explanation because on this panel they are not open for update. The values for these fields are filled in automatically by CMNCONF based on information you supplied in “System Configuration,” so you need not do anything with these fields on this panel. 2. Database Type: This field is used to specify the type of database you wish to create. WCSuite supplies two sample databases: • Demomall : This database will be populated with a half-dozen or so stores and some sample products when you run the “Database Load” option. We recommend tat you start with this database because it’s an excellent way of validating the basic functionality of WCSuite without having to do any customization. • Base Mall : This is a skeleton mall used as a starting point for further customization. This should only be used if you are very familiar with the operation of WCSuite. For your first configuration you should select 1 to create the Demomall database.
50
IBM WebSphere Commerce Suite V4.1 for OS/390
3. Database Operation: You may either create or delete a database using this panel of CMNCONF. When you are doing your first configuration, select 1 to create the database. 4. Data Set Name: This field is used to point to the data set that contains the definitions of the tables that comprise the database. This defaults to hlq.SCMNSAMP. The member name of DEMOMALL will be automatically assumed by CMNCONF. Therefore, change this to reflect the high-level qualifier you used when you installed WCSuite. 5. Custom Script Name : This field is used to point to a custom database SQL script to use to create a custom database. Custom databases are an advanced topic and beyond the scope of this book. Leave this field blank. Press the Enter key to proceed with the creation of the database. It will take several minutes to complete the operation, so be patient. Your TSO ID will remain occupied during this time period.
2.4.12.7 CMNCONF Database Load option Once the Demomall database has been created, it needs to be loaded. An empty database is of no use to WCSuite. The sample data to be loaded into the database you just created is supplied with WCSuite, and you can load it using the “Database Load” option. The panel is illustrated in Figure 33.
CMNDBL1------------- LOAD A WEBSPHERE COMMERCE SUITE DATABASE ---------------COMMAND ===> This panel allows you to load a WebSphere Commerce Suite database from del files extracted from a database. When loading a custom database, a second panel is displayed to obtain additional information. Instance Name DB2 Database Owner Database Name
===> ===> ===>
Database to Load Convert Del Files
===> ===>
Tables to Load
===>
1 (1 = demomall, 2 = base, 3 = custom) (1 = yes, 2 = no)
2
3
4
Enter END COMMAND to return to the INSTANCE CONFIGURATION menu.
F1=HELP F7=UP
F2=SPLIT F8=DOWN
F3=END F9=SWAP
F4=RETURN F10=LEFT
F5=RFIND F11=RIGHT
F6=RCHANGE F12=RETRIEVE
Figure 33. CMNCONF Database Load option panel
A description of these fields follows. 1. Instance Name , DB2 Database Owner and Database Name: We have combined these three fields into one explanation because on this panel they are not open for update. The values for these fields are filled in automatically by CMNCONF based on information you supplied in “System Configuration,” so you need not do anything with these fields on this panel. 2. Database to Load: Match the type of database that you created. In our example, it would be the Demomall, so choose 1. Chapter 2. Prerequisites, installation and configuration
51
3. Convert Del Files: This option is used when you are bringing in data files from another platform’s DB2 system. We are not doing that here, so take the default value of 2 for “no.” 4. Tables to Load: This field allows you to specify individual files you want to load. This is an advanced feature and not to be used without very careful consideration. Allow this to remain blank. Press the Enter key to proceed with the loading of the database. Just like with creating the database, this operation can take several minutes.
2.4.13 Grant DBADM to the Webserver’s userid This step is necessary so that the WCSuite Director code, which is provided as a Webserver API program (commonly referred to as a “GWAPI” program, which is a reference to the old “Domino G o Webserver API”), can access the WCSuite database. The Director runs in the Webserver’s address space and therefore operates under the authority of the Webserver’s userid. To do this, issue the following DB2 SQL command: grant dbadm on database to
Failure to do this will result in some rather random-looking failures. (There’s nothing random about them, of course, but it’ll appear that way when some things work and others don’t). This is an easy step to overlook.
2.4.14 Create your JCL start procedure WCSuite runs as a started task, so that implies a JCL start procedure. A sample is supplied with the code you installed, and you may copy that code and modify it.
2.4.14.1 Copy the sample JCL procedure The sample JCL is supplied in two locations: • In the hlq.SCMNSAMP(CMNMSERV) PDS member • In the /usr/lpp/CommerceSuite/install/cmnmserv.prc HFS file The sample JCL looks like this: //CMNMSERV PROC NETCPARM=’’, // LEPARM=’ENVAR(“_CEE_ENVFILE=/etc/NC/-INSTNAME-.envvars”)’ //* //* //*************************************************************// //* *// //* Licensed Materials - Property of IBM *// //* 5697-D32 *// //* *// //* (C) Copyright IBM Corp. 1997 All Rights Reserved. *// //* US Government Users Restricted Rights - Use, *// //* duplication or disclosure restricted by GSA ADP *// //* Schedule Contract with IBM Corp. *// //* *// //*************************************************************// //* This PROC starts a Net.Commerce server instance. *// //* *// //* . Change -INSTNAME- to the instance name defined for *// //* this server during configuration. *// //* *// //* . Change -XXXXXXX- to the high level qualifiers for *// //* Net.Commerce datasets. *// //* *// //* . Change -YYYYYYY- to the high level qualifiers for *// //* DB2 datasets. *//
52
IBM WebSphere Commerce Suite V4.1 for OS/390
//* *// //* . Change -ZZZZZZZ- to the high level qualifiers for *// //* Lotus Domino Go Webserver datasets. *// //* *// //* . Change -CCCCCCC- to the high level qualifiers for *// //* C++ Class Library datasets. *// //* *// //* . If this instance is using the Payment Server support, *// //* - change -BBBBBBB- to the high level qualifiers for *// //* Payment Server datasets and un-comment the record. *// //* *// //*************************************************************// //CMNMSERV EXEC PGM=CMNSRVRC, // PARM=(‘&LEPARM/&NETCPARM -i /etc/NC/-INSTNAME-.conf’), // REGION=0M,TIME=(1440) //* //STEPLIB DD DSN=-XXXXXXX-.SCMNLMOD,DISP=SHR // DD DSN=-YYYYYYY-.SDSNLOAD,DISP=SHR // DD DSN=-YYYYYYY-.SDSNEXIT,DISP=SHR // DD DSN=-CCCCCCC-.SCLBDLL,DISP=SHR //* DD DSN=-BBBBBBB-.SCOTLINK,DISP=SHR //* //SYSIN DD DUMMY //SRVOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //CEEDUMP DD SYSOUT=*
Copy the JCL to your system proc lib.
2.4.14.2 Modify the sample The sample JCL has commented instructions on what to change. To help clear up any possible confusion, Figure 34 illustrates which of the many configuration files you point to on the LEPARM and PARM statements in the JCL. This example assumes the directory structure we created in 2.4.11, “Prepare separate HFS and mount-point for configuration files” on page 37.
//CMNMSERV PROC NETCPARM=’’, // LEPARM=’ENVAR(“_CEE_ENVFILE=/u/cmnsrv/configs/wcs41.envvars”)’ //* //* //*************************************************************// (comments removed to save space) //*************************************************************// //CMNMSERV EXEC PGM=CMNSRVRC, // PARM=(‘&LEPARM/&NETCPARM -i /u/cmnsrv/configs/wcs41.conf’), // REGION=0M,TIME=(1440) //* //STEPLIB DD DSN=CMN.SCMNLMOD,DISP=SHR // DD DSN=DB2610.SDSNLOAD,DISP=SHR // DD DSN=DB2610.SDSNEXIT,DISP=SHR // DD DSN=SYS1.CPP.SCLBDLL,DISP=SHR //* DD DSN=-BBBBBBB-.SCOTLINK,DISP=SHR //* //SYSIN DD DUMMY HLQ's updated //SRVOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //CEEDUMP DD SYSOUT=*
/(root) /u/cmnsrv/configs
wcs41.conf wcs41.envvars ncommerce.conf ncommerce.envvars db2www.ini
Figure 34. Which configuration files to point to from JCL start procedure
Chapter 2. Prerequisites, installation and configuration
53
2.4.15 Create a STARTED class profile To associate a RACF userid under which the started task will run, you need to add the start procedure to the STARTED class. Do this with the following command (which assumes your JCL start procedure is named CMNMSERV and the userid is CMNSRV): RDEFINE STARTED CMNMSERV.** STDATA(USER(CMNSRV))
and then: SETROPTS RACLIST(STARTED) REFRESH
2.4.16 Enabling SSL on your Webserver WebSphere Commerce Suite will, by default, require you to have SSL (Secure Socket Layer) configured and working on your Webserver. While it is possible to disable WCSuite’s use of SSL, it’s somewhat difficult. It is also beyond the scope of this book to show you how to do it. So assume that SSL is required. Briefly explained, SSL is a way of encrypting the data that flows between a browser and a server. Through a defined set of request and response exchanges (known as the “handshake”), the browser and the server agree on the necessary details so that both sides know how to receive and read the encrypted data. The purpose of SSL is to prevent people who may be eavesdropping on the line from intercepting information and reading it. SSL is enabled on the Webserver through a combination of directives in the httpd.conf file and the existence of a certificate “keyring” on the system. The keyring is what holds the electronic certificates that are issued by the Webserver on your OS/390 system. These certificates tell the browser who the server is, and more important, it tells which “certificate authority” has “signed” the certificate. Your browser has a list of well-known “certificate authorities” coded into its security plug-in. If the certificate received from your server is signed by an authority not recognized by the browser, the browser will pop up a warning box telling you this fact. Figure 35 on page 55 illustrates keyring location and relationship of the directives in the httpd.conf file.
54
IBM WebSphere Commerce Suite V4.1 for OS/390
Webserver
httpd.conf
keyfile key.kdb sslmode on sslport 443
/ (root)
/usr/lpp/internet key.kdb
Key ring file
key.sth
Key ring password stash file
/server_root
Figure 35. The Webserver’s SSL keyring file locations
Note: The keyring file name doesn’t have to be “key.kdb,” nor does it have to reside in the /server_root directory of the Webserver. But these are the default settings and it illustrates the basic concept. If your system has these directives defined in httpd.conf and the keyring files are on the system, your system may already be configured for SSL. Connect to the home page of your Webserver, then place an “s” at the end of “http” (to form https :// ...) and re-issue the URL. If your Webserver is configured to support SSL, you should be able to see the session go to SSL. On Netscape you can see that by observing the little “lock” symbol in the lower-left corner of the screen. For Internet Explorer, you can right-click on the browser screen and then select the Properties option from the list. If you’re in SSL, you’ll see what’s illustrated in Figure 36 on page 56.
Chapter 2. Prerequisites, installation and configuration
55
Indication of SSL.
Figure 36. How to see if SSL is invoked on Internet Explorer browser
If SSL is not configured on your system, then you must configure it since WCSuite requires it. Refer to A.1, “Problems invoking SSL on Webserver” on page 183.
2.4.17 Restart the Webserver to pick up the changes to httpd.conf The CMNCONF program will have written some Pass and Service directives to the /etc/httpd conf file, and for those changes to take effect you need to recycle the Webserver. If the Webserver is already running, stop it with the command: p imwebsrv
and then restart it with the command: s imwebsrv
If it starts correctly, you should see the following console messages: IMW3536I SA 16777275 0.0.0.0:80 * * READY
2.4.18 Start the WebSphere Commerce Suite server Note
It is critical that DB2 be started prior to attempting to start WCSuite. If DB2 is not started, WCSuite will fail to start with the symptom described in A.3.1, “db2_load_caf failed return_code 8, reason_code f30002” on page 194.
Start the WCSuite server by issuing the command: s cmnmserv
56
IBM WebSphere Commerce Suite V4.1 for OS/390
at the system console. If it starts correctly, you should see the following console messages: CMN0411I THE Commerce Suite SERVER IS READY FOR CONNECTIONS 272
If you encounter problems starting WCSuite, consult A.3, “Problems starting the WCSuite server” on page 194 to see if the problem you are experiencing is explained.
2.4.19 Verify the basic operation of WebSphere Commerce Suite Verifying the “basic operation” of WCSuite involves making sure the essential components are in place. To do this, we’ll have you exercise a few WCSuite commands against the instance you just created, and in doing so you’ll verify things are working properly. Figure 37 illustrates what we’re looking to validate.
WCSuite Server
NCADMIN Admin. Utility
Process Task
Net Data
DB2 4
5 Child Daemon
Child Daemon
...
Child Daemon
Main Daemon 3 2
1
Administrator HTML
Net.Commerce API Director
Web Server Internet
Shopper HTML
Figure 37. Verifying the basic operation of a newly configured WCSuite instance
Let’s review what the objectives of this validation phase are. The actual commands used to verify this will come after. 1. The CMNCONF program will have written some directives to the Webserver’s httpd.conf file. We need to verify that they are taking effect. Being able to get to the Demomall’s “home page” will mean the Pass directives mapping the Demomall URL have taken effect. We must also verify that SSL for the Webserver has been correctly configured. By hardcoding an “s” on the http:// portion of the URL, we can test the SSL capabilities of the Webserver. 2. If the URL has a WCSuite command in it, then it will be necessary for the Webserver to pass the request over to the WCSuite Director code running in the Webserver’s address space. We need to verify that the Director is running Chapter 2. Prerequisites, installation and configuration
57
and that the passing of the URL is handled appropriately. Being able to successfully execute any WCSuite command will verify this. 3. The TCP ports across which the Director talks to the Main Daemon need to be checked. Successfully executing any WCSuite command will verify the connection between the Director and Main Daemon is good. 4. Getting to the DB2 database is the key to all of this. If you can successfully execute a WCSuite command that you know gets information from the database, then you’ll have verified that the connection to the database is good, and that the operation of the child processes, process tasks and Net.Data tasks all worked well. 5. Finally, exercising the administrative function of WCSuite accomplishes two things: it verifies that the administrative commands are working, and it validates the authentication routine of WCSuite. You can’t access this function without logging on to WCSuite, and if you can log on, then it validates the authentication process.
2.4.20 Checklist to validate basic WCSuite functionality The following is a list of specific URLs to issue from a browser to validate the basic functionality of the WCSuite server as illustrated in Figure 37 on page 57.
Note 1: For each of these URLs, is the host name you provided your instance on the “System Configuration Panel 1 of 2” screen of CMNCONF (see 2.4.12.4, “CMNCONF System Configuration option” on page 44 for a description of that process). Note 2: Use Netscape for this test. Internet Explorer will work for most of these tests, but Netscape is the supported browser for use with the Administrative function of WebSphere Commerce Suite. Note 3: If you encounter problems running these tests, consult A.4, “Problems accessing the Metropolitan Demomall” on page 195. http:///demomall/basemall.htm
If you receive the “Metropolitan Demomall” home page, this validates that the Pass directives in the /etc/httpd.conf file added by the CMNCONF program have been picked up by the Webserver and are active. https:///demomall/basemall.htm
Note the “s” on the https:// portion of this URL. That tells the Webserver to invoke SSL when issuing this HTML page. Watch the browser to insure SSL is invoked. On Netscape this is a small lock symbol in the lower left. See Figure 36 on page 56 for an illutration of what to look for on Internet Explorer. See 2.4.16, “Enabling SSL on your Webserver” on page 54 for information on that process. http:///webapp/commerce/command/ExecMacro/mall_dir.d2w/report
This command will execute the mall_dir.d2w Net.Data macro and will query the database for the stores located in the Metropolitan Demomall. If you get the “Mall Directory,” that means the Director code got the command, passed it across the local TCP port to the main daemon, Net.Data was invoked and it successfully connected to the database and received results from its query.
58
IBM WebSphere Commerce Suite V4.1 for OS/390
http:///webapp/commerce/command/InterestItemDisplay
This command will display the contents of your shopping cart. Your shopping cart will be empty at this point in time, but that won’t hinder the objective of this test. This command is, by default, designated as one for which WCSuite will automatically invoke SSL. Watch to insure SSL is indeed invoked. This command also results in a “Process Task” being run, so it validates that function as well. http:///ncadmin/
This command will bring up the WebSphere Commerce Suite’s administrative function logon panel. If you are successful in logging onto the facility, then it validates the authentication routines of WCSuite. The default userid and password for the administrative facility are: Userid ncadmin Password ncadmin On your first invocation of the NCADMIN administrative utility you will be forced to change the initial password.
2.4.21 Review: where you are after running these validation tests If you successfully ran all those tests on the first try, then you are indeed a skilled technician! Usually there’s something that goes wrong and needs fixing. (We tried to capture the common things in A.4, “Problems accessing the Metropolitan Demomall” on page 195.) Getting past this checkpoint means you may now turn your focus to the configuration issues related to the new functions of WCSuite V4.1: JSP support and personalization.
2.5 Phase 2: Proxy server configuration and validation The purpose of this phase is to configure a second Webserver to run the WebSphere Application Server (WAS) plugin. This second Webserver is where the servlets supplied with WCSuite V4.1 will run. These servlets provide the new functions of the Java/JSP pages and the publishing capability from Commerce Studio. This arrangement is illustrated in Figure 38 on page 60.
Chapter 2. Prerequisites, installation and configuration
59
Websphere Commerce Suite "Net.Commerce" base function like Net.Data and C++ command structure.
New function based on servlets, which run in WAS.
7 4
GWAPI Webserver
WAS Webserver
GWAPI Plugin
WAS 3.0.2 Plugin Port 8080 SSLPort 8081
Port 80 SSLPort 443
1
httpd.conf
3
httpd.conf
URL from browser
6
Service 2 : Proxy :
Service : 5
Figure 38. Proxy server configuration overview
We’ll explain what all the flows mean in a moment. But first, let’s answer this question: “Why in the world do we need to configure this?” It turns out that DB2 for OS/390 restricts the mixing of JDBC and other connection types (notably CAF) from within the same OS/390 address space. The WAS 3.0.2. plugin uses the RRS Attachment Facility (RRSAF) to connect to DB2. The WCSuite GWAPI plugin uses RRSAF as well, but the recommendation is to avoid mixing plugins from the same Webserver address space. To avoid this mixing, the WCSuite GWAPI plugin resides in its Webserver, and the WAS plugin resides in another Webserver. That being said, let’s turn to the diagram shown in Figure 38 and explain each of the numbered references. 1. A URL comes in from the shopper’s browser. That URL will have one of three formats: http:///static_page.html http:///webapp/commerce/command /ExecMacro ... http:///webapp/commerce/servlet /ProductDisplay ...
The first URL shown is one for a static resource, like an HTML page or JPG/GIF image file. That request will be served directly by the Webserver without WCSuite being involved. We won’t focus on that type of URL. The second and third URLs show requests for WCSuite commands to be executed. Notice how the two URLs are different: the second one has the string “command” in it, the third has the string “servlet.” The directives in the httpd.conf will determine what to do with the inbound URLs based on this string difference. That’s discussed next.
60
IBM WebSphere Commerce Suite V4.1 for OS/390
2. There are two directives in the httpd.conf file that we will focus on here: • Service: An inbound URL that matches the value specified on a Service directive will be routed for execution to the plugin (a program running in the Webserver’s address space and using the defined API of the Webserver) named on the directive. For WCSuite commands that conform to the “old” Net.Commerce-like style (in other words, commands that are not Java-based), the Service directive in the httpd.conf file looks for URLs with the string commerce/command/*. Any URL with that string will match and get routed to the WCSuite plugin, which is also known as the “Director code” or the “GWAPI code.” • Proxy: An inbound URL that matches the value specified on a Proxy directive will be routed to the host specified on the Proxy directive. For WCSuite commands based on the newer Java architecture, the Proxy directive looks for the string commerce/servlet/*. Those requests get routed to the other Webserver. 3. This flow illustrates a received URL that mapped to the Service directive, and thus is sent to the WCSuite GWAPI plugin. 4. This flow illustrates the interaction between the GWAPI plugin and the WCSuite server code. This is how the bulk of the WCSuite commands are handled. 5. A URL received that mapped to the Proxy directive gets routed over to the other Webserver. 6. The httpd.conf file of this second Webserver has its own Service directives. These Service directives are looking for the commerce/servlet/* string. When it finds one, it routes the request to the WAS 3.0.2 plugin for execution. 7. The WAS plugin has knowledge of the location of the WCSuite Java classes that contain the new Java-based commands and functions. The Java commands, servlets and JSPs will run under the control of WAS.
2.5.1 Create proxy configuration in GWAPI Webserver If you successfully validated the basic functions of WCSuite as detailed in 2.4.20, “Checklist to validate basic WCSuite functionality” on page 58, then you have the GWAPI Webserver functioning. However, the httpd.conf file of that Webserver is not yet configured to be a proxy server. Do the following: 1. Edit the httpd.conf file for the Webserver that has the GWAPI plugin configured and was used to validate the basic functions of WCSuite. 2. Add the following lines to the httpd.conf file. They must come after the block of updates made by CMNCONF at the top of the file (delimited by ###### IBM WebSphere Commerce Suite ######) and before the Pass /* directive located approximately half-way down the file: Proxy Proxy Proxy Proxy Proxy Proxy
/redbook/verify/* http://:8080/* /webapp/*jsp* http://:8080/*jsp* /webapp/commerce/servlet/* http://:8080/webapp/commerce/servlet/* /webapp/commerce/MerchantAdmin http://:8080/webapp/commerce/MerchantAdmin /webapp/examples/* http://:8080/webapp/examples/* *:443
Chapter 2. Prerequisites, installation and configuration
61
Where is the host name of the Webserver that will be running the WAS plugin. It may be the exact same host name as your GWAPI plugin Webserver, or a different one. This provides the GWAPI Webserver the ability to recognize an inbound URL and route it over to the WAS Webserver. The first Proxy statement will be used to verify the proxy configuration. 3. Edit the javelin.conf file for the GWAPI Webserver (this file will be found in the same directory as the httpd.conf file). Check the value for the PureProxy directive: it should be set to off. If the directive doesn’t exist, then add it; if the directive is set to on, then change it to off. 4. Stop and restart the GWAPI Webserver so the changes you have made will be picked up.
2.5.2 Create second Webserver to run WAS plugin The IBM HTTP Server (we have been calling it the Webserver throughout this redbook) is designed to allow multiple copies to run in the same OS/390 system. The process of setting up a second running copy of the Webserver is something beyond the scope of this book, so we will leave it to you to do that job. The key updates to the httpd.conf file of this second Webserver (which we’ll call the “WAS Webserver”) are as follows: Userid PUBLIC
The PUBLIC Userid is used so that incoming Web requests do not need to require the user to log on. Port 8080 sslport 8081
This defines the non-SSL listen port as 8080 and the SSL port as 8081. This is different from the GWAPI Webserver, which is running with non-SSL of 80 and SSL of 443. Start this second Webserver and make certain it comes up properly. You can verify this by issuing the following URL from a browser: http://:8080
2.5.3 Verify the proxy configuration We are going to verify the proxy configuration by issuing a URL to the GWAPI Webserver for an HTML file we know is only over on the WAS Webserver. If the HTML page is displayed, it means the URL was routed over and that the proxy configuration works. Do the following: 1. Browse the httpd.conf file of the WAS Webserver, and find the Pass /* directive which defines the “document root” of the this Webserver. It will have a format that looks something like this: Pass /* /usr/lpp/internet/pubs/*
62
IBM WebSphere Commerce Suite V4.1 for OS/390
Note the directory referenced on the Pass directive. That is where you are going to create the simple HTML file you will use to verify the proxy configuration is working. 2. Create and save a file in the document root of the WAS Webserver called redbook.html. Insert the following text: You made it over to the WAS Webserver!
3. Start a browser and point it to your GWAPI Webserver (the one on which you verified the basic function of WCSuite, which is the one listening on Port 80). Issue the following URL: http:///redbook/verify/redbook.html
If things work properly, the Proxy /redbook/verify/* statement in the httpd.conf file should route this over to the WAS Webserver listening on Port 8080. You should see the “You made it over to the WAS Webserver!” message. Let’s review where we are. Figure 39 illustrates the configuration at this point in time.
WCSuite V4.1 Net.Data
DB2 V6
WAS Webserver
GWAPI Webserver WCSuite GWAPI Plugin
Note that WAS not yet installed or configured here.
SSL Port 80
Proxy
Port 8080
Static HTML File
Figure 39. Checkpoint picture of configuration after verifying proxy configuration
And this is what you’ve verified: • The GWAPI Webserver accepts inbound requests and knows about the updates to its httpd.conf made by the CMNCONF utility (display of demomall/basemall.htm file proved that).
Chapter 2. Prerequisites, installation and configuration
63
• The SSL function on the GWAPI Webserver works properly (changing the http to https verified that). • The WCSuite started task comes up properly, and the connection between the GWAPI plugin and the WCSuite server instance operates properly (tests from 2.4.20, “Checklist to validate basic WCSuite functionality” on page 58 proved this). • The second Webserver (the “WAS Webserver”) works properly for serving static HTML pages (pointing browser to Port 8080 showed that). • The proxy configuration of the GWAPI Webserver correctly routed the request over the WAS Webserver (the simple redbook.html file proved that). Here is what you have left to do in this phase of the installation/verification process: • Install the WebSphere Application Server (WAS) and configure its use as a plugin to the WAS Webserver. • Verify the WAS configuration by exercising the sample servlets provided with WAS.
2.5.4 Install and configure WAS plugin in the WAS Webserver Back in 2.5.2, “Create second Webserver to run WAS plugin” on page 62 you established the second Webserver that will act as the Webserver on which the WAS plugin will run. It is now time to install and configure WAS on that Webserver. To give you a picture of how some of these configuration files relate to one another, consider the picture provided in Figure 40 on page 65.
64
IBM WebSphere Commerce Suite V4.1 for OS/390
The WAS plugin has its own configuration file, which by default resides in the /properties directory as shown.
IBM HTTP Server
IBM Websphere Application Server (WAS) plugin
/usr/lpp/WebSphere /AppServer
httpd. envvars
httpd.conf
/properties
was.conf
/bin (Typically found in /etc)
: ServerInit :
Plugin Code
/usr/lpp/WebSphere/AppServer/bin/was302plugin.so:init_exit
The WAS plugin is loaded by the ServerInit statement found in the httpd.conf file.
Figure 40. Relationship of WAS to the HTTP Server and their configuration files
The installation of WAS will place the code into the /usr/lpp/WebSphere/AppServer directory (or wherever you choose to install it). The configuration process involves updating several different files shown in the picture. We wanted to give you this picture so you could visually see the relationship of the Webserver’s configuration files and the WAS configuration files. In addition, we show you what tells the Webserver to load the WAS plugin into its address space. We’ll introduce even more configuration files as you work through this document. To configure the WAS plugin, do the following: 1. Using the WebSphere Application Server Standard Edition Planning, Installing, and Using Manual (GC34-4806), install the WAS code onto your system. Typically this is installed into /usr/lpp/WebSphere. 2. Manually create the following subdirectories under the /usr/lpp/WebSphere/AppServer directory: • logs • work 3. Add the program control bit by issuing the following command on all the files in the /usr/lpp/Websphere/AppServer/bin directory: extrattr +p *.so
You can verify that the program control bit is set by issuing the command: ls -E *.so
Chapter 2. Prerequisites, installation and configuration
65
from the /usr/lpp/WebSphere/AppServer/bin directory. You should see output that looks something like this: -rwxr-xr-x -rwxr-xr-x -rwxr-xr-x -rwxr-xr-x -rwxr-xr-x
-ps -ps -ps -ps -ps
2 2 3 3 2
OMVSKERN OMVSKERN OMVSKERN OMVSKERN OMVSKERN
SYS1 SYS1 SYS1 SYS1 SYS1
655360 1097728 589824 589824 745472
Jun Jun Jun Jun Jun
26 26 26 26 26
12:44 12:44 12:46 12:46 12:45
libascommon.so libasin.so libstubj.so libstubj_g.so was302plugin.so
It’s the “p” in the “ -ps” string that indicates the program control bit is on. 4. Update the was.conf file that is located in the /usr/lpp/WebSphere/AppServer/properties directory. There are five “properties” that you need to update:
• appserver.logdirectory= Set this to: /usr/lpp/WebSphere/AppServer/logs
• appserver.workingdirectory= Set this to: /usr/lpp/WebSphere/AppServer/work
• appserver.jvmpropertiesfile= Set this to: /usr/lpp/WebSphere/AppServer/properties/default_global.properties
• appserver.classpath= This property is used by WAS to know what classes to load at initialization time. To validate the basic operation of the WAS servlet support, you may leave this blank. The WCSuite Configuration Guide suggests: /usr/lpp/WebSphere/AppServer/properties/default_mimetype.properties
For now it doesn’t seem to matter, so provide what the Configuration Guide suggests. Later, when we configure this WAS plugin to run the WCSuite servlets, we will add quite a bit more to this classpath.
• appserver.loglevel= Set this to Warning. This will log activity to the directory specified on the appserver.logdirectory property. 5. Now go to the http.conf file in use by the WAS Webserver ( not the GWAPI Webserver), edit and add the following directives. Again, add these before the Pass /* directive found lower in the file: ServerInit Service Service Service Service Service Service ServerTerm
/usr/lpp/WebSphere/AppServer/bin/was302plugin.so:init_exit , /*.jhtml /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:service_exit /*.shtml /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:service_exit /*.jsp /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:service_exit /servlet/* /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:service_exit /webapp/* /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:service_exit /commerce/* /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:service_exit /usr/lpp/WebSphere/AppServer/bin/was302plugin.so:term_exit
Where: is the directory in which you installed the WAS code. Typically this is /usr/lpp/WebSphere. is the directory and name of the file that will serve as the configuration file for the WAS plugin. By default this file is /usr/lpp/WebSphere/AppServer/properties/was.conf. You could place this
66
IBM WebSphere Commerce Suite V4.1 for OS/390
file somewhere else. If you’re running multiple copies of WAS on your system, then you probably will locate this file in its own directory. For example, on the system upon which we tested WCSuite to write this redbook, our file was located at /web/comm2/was.conf. This block of directives serves two purposes: • The ServerInit statement is read by the Webserver and used to start the WAS plugin at the time the Webserver is initialized. The ServerTerm does the opposite: it stops the WAS plugin when the Webserver is being brought down. • The Service directives are used to map inbound URL strings to the WAS plugin. Take for example a URL format of a WCSuite command that exercises the new Java-based function: http:///webapp/commerce/servlet/ProductDisplay?prrfnbr=12345 ...
The Webserver would see this, parse through its directives, and find a match with the Service /webapp/* directive. This in turn would invoke the WAS plugin and execute the command, which is implemented as a Java servlet run under WAS. 6. Determine the home directory locations of the following components. We have included here the typical locations, but your system may be different. Table 5. Home directory locations of key system components
Home
Your Location
Typical
Java
/usr/lpp/java/J1.1
HTTP Server
/usr/lpp/internet
JDBC
/usr/lpp/db2/db2610
WCSuite
/usr/lpp/CommerceSuite
In the next step we’ll refer to these as , , and . You will substitute your actual values. 7. Turn your attention to the httpd. envvars file (not the “conf” file, but the “envvars” file). This is the environment variables file for the WAS plugin Webserver, and it needs to be updated to reflect the system environment in which it will run. Do the following: Note
The information on any single environment variable must be typed out on one line, even if that means scrolling to the right. Do not break a line in the envvars file. Many envvar files have lines that string out several hundred characters to the right of the screen margin. • To the PATH variable, add: /bin:/bin
• To the LIBPATH variable, add: /lib/mvs/native_threads:/lib
• Set the JAVA_HOME variable to your directory
Chapter 2. Prerequisites, installation and configuration
67
• To the CLASSPATH variable, add (again, on one line— it is broken here just to so it would fit on the page): /lib/classes.zip: /server_root/CAServlet: /classes/db2jdbcclasses.zip: /www/Servlets/Public
2.5.5 Validate the WAS plugin The picture of your environment should now be what we show in Figure 41.
WCSuite V4.1 Net.Data
DB2 V6
WAS Webserver
GWAPI Webserver
was.conf Websphere Application Server Plugin
WCSuite GWAPI Plugin
httpd.conf
SSL Port 80
Proxy
Port 8080
httpd. envvars
Figure 41. Environment after WAS plugin configured into WAS Webserver
To verify that the WAS plugin is working properly, do the following: 1. Stop and restart the WAS Webserver so the changes you have made to the httpd.conf, httpd.envvars and was.conf file can be picked up. 2. Make sure the GWAPI Webserver is also up and running. This will provide the proxy routing of the request over to the WAS Webserver listening on port 8080. 3. From a browser, issue the following URL: http:///webapp/examples/index.html
This will go to the GWAPI Webserver first, but the Proxy statements you placed in the httpd.conf of this server will route the request over to the WAS Webserver. The WAS Webserver’s Service /webapp/examples/* directive will map this request to the WAS plugin. The WAS examples page should display the screen shown in Figure 42 on page 69.
68
IBM WebSphere Commerce Suite V4.1 for OS/390
The first two links run JSP pages The last link runs a servlet that queries for and displays the WAS configuration.
Figure 42. The WAS examples HTML page
This is a static HTML page, so do not think that your WAS configuration has been fully tested yet. All this tested was the Service directive in httpd.conf. 4. Click on the link that says “Show server configuration.” This will run a servlet called showCfg. If that runs properly, then it validates the ability of the WAS plugin to locate its supplied sample servlet and run it. The result should look like that shown in Figure 43 on page 70.
Chapter 2. Prerequisites, installation and configuration
69
Figure 43. WAS “showCfg” servlet output
2.5.6 End of phase 2 review In Phase 1 you configured and validated the basic function of the WCSuite product. That validated the GWAPI Webserver’s configuration, and the ability of the WCSuite GWAPI plugin to communicate with the WCSuite server. The WCSuite server was able to communicate with the DB2 subsystem, and the basic functions of the WCSuite product were validated. In Phase 2 you enabled the GWAPI Webserver to be a proxy server and route certain requests over to a second HTTP Server, which we are calling the WAS Webserver. The proxy configuration was validated by accessing a static HTML page known to exist only on the WAS Webserver, but not on the GWAPI Webserver you pointed your browser at. Also in Phase 2 you installed and configured the WAS plugin to the HTTP Server, and by running the sample servlet showCfg, you validated the WAS plugin’s operation. Here is what you must now do: 1. Configure a JDBC Type 2 connection for DB2. 2. Modify the WAS Webserver’s configuration to recognize WCSuite components. 3. Validate the ability to run the supplied sample JSPs that come with the WCSuite Demomall. Doing so will validate the servlet functionality of WCSuite, and position you to move to Phase 4.
70
IBM WebSphere Commerce Suite V4.1 for OS/390
2.6 Phase 3: JDBC configuration and WCSuite servlet validation 2.6.1 Update the environment variable and configuration files There are several files on your system that need to be updated. Figure 44 shows those files.
1
db2sqljjdbc.properties
DB2
WAS Webserver
WAS Plugin
2
http.envvars
3
was.conf
OMVS Shell 4
/u/userid/.profile
Figure 44. Environment variable, configuration and properties files updated for JDBC configuratio
The updates to these files are described next. 1. db2sqljjdbc.properties This file is typically located in the /usr/lpp/db2/db2610/classes directory. Whether you wish to change the default file or copy the file to a user directory (such as /u/cmnsrv/configs in our example here in this redbook) is up to you. For the WCSuite environment, two processes make use of this file: • Your OMVS shell environment will need to know where this file is when you run the db2genJDBC utility (that process will be explained later, in 2.6.2, “Bind the DBRM plans” on page 73). The db2sqljjdbc.properties file has a pointer to the PDS data set that will house the output from db2genJDBC. • The WAS plugin has a pointer in its configuration file (was.conf) to the db2sqljjdbc.properties file so WAS can understand the JDBC properties it is to work with. Edit the copy of db2sqljjdbc.properties that you will use (the default copy in the DB2 directory, or one that you have copied to another directory) and make sure it has the following directives: DB2SQJSSID= DB2SQLJDBRMLIB=CMN.DBRMLIB.DATA
Chapter 2. Prerequisites, installation and configuration
71
DB2SQLJATTACHTYPE=RRSAF DB2SQLMULTICONTEXT=YES
A few notes on this: • The DB2SQLJSSID value is pointing to the Subsystem ID of your DB2, not the location name, which may be different. Later, in the was.conf file and the ncommerce.conf file, we’ll make reference to the location name. If the two are the same, then things are easier. If they are different, then you must be careful. • The DB2SQLJDBRMLIB value may point to any MVS PDS. To keep things easy to remember, you should probably have the high level qualifier of the data set the same as the installation HLQ you used when you installed WCSuite. This PDS must be allocated prior to running the db2genJDBC utility. The allocation parameters are provided in 2.6.2, “Bind the DBRM plans” on page 73. 2. httpd.envvars This is the environment variable file for the HTTP Server that is running the WAS plugin, and not the HTTP Server that is acting as the proxy server (see Figure 41 on page 68 for a picture of the relationship of these two Webservers.) To verify exactly which file is being used, check the LEPARM value of the JCL start procedure used to invoke the server. That will point to the file you should modify. Update the LIBPATH, LD_LIBRARY_PATH and PATH variables as follows (while maintaining whatever existing values may already be there):
LIBPATH Provide a pointer to the SQLJ/JDBC library directory, which typically resides in: /usr/lpp/db2/db2610/lib
LD_LIBRARY_PATH Provide a pointer to the SQLJ/JDBC library directory, which typically resides in: /usr/lpp/db2/db2610/lib
PATH Provide a pointer to the SQLJ/JDBC binary directory (careful: not the library directory like LIBPATH and LD_LIBRARY_PATH): /usr/lpp/db2/db2610/bin Provide a DB2SQLJPROPERTIES variable to the file: DB2SQLJPROPERTIES=/u/cmnsrv/configs/db2sqjjdbc.properties
Note: This should point to wherever you copied the db2sqljjdbc.properties file back in the first step of this process. 3. was.conf This is the configuration file for the WAS plugin that is running in the WAS Webserver as shown in Figure 41 on page 68. The directive in this file that will be updated is the appserver.classpath directive. This directive, like all directives in was.conf, may not be split across lines. So be prepared to have your values stretch well beyond the right side of the screen.
72
IBM WebSphere Commerce Suite V4.1 for OS/390
It requires two updates: • A pointer to the db2sqljclasses.zip file, for example: appserver.classpath= ... /usr/lpp/db2/db2610/classes/db2sqljclasses.zip ...
• A pointer to the directory in which the db2sqljjdbc.properties file resides. Back in the first step of this process we suggested you might want to copy that file to the directory in which all of the other configuration files resided (in our example, /u/cmnsrv/configs). Wherever your copy of that file resides, put a reference to it on the appserver.classpath directive: appserver.classpath ... /u/cmnsrv/configs ...
4.
/u/userid/.profile This is the file that establishes the environment when you go into the OMVS shell. The /etc/profile file also provides this function. If your installation maintains a common environment for all users, then place these changes down in /etc/profile. Otherwise, put them in /u/userid/.profile. WCSuite does not use the .profile for your userid, nor do any of the HTTP Servers or the WAS plugin. We are updating this to provide the ability to run the db2genJDBC utility from your OMVS shell. Update the following: CLASSPATH Point to /usr/lpp/db2/db2610/classes/db2sqljclasses.zip PATH Point to /usr/lpp/db2/db2610/bin This provides access to the db2genJDBC utility without having to type out the fully qualified directory path. DB2SQLJPROPERTIES Create this variable and set its value to the directory and file name of where you copied the db2sqljjdbc.properties file back in step 1 of this process. In our example we have that set to: DB2SQLJPROPERTIES=/u/cmnsrv/configs/db2sqljjdbc.properties
You must export this variable to your environment: EXPORT DB2SQLJPROPERTIES
This provides the db2genJDBC utility knowledge of the file’s location, and it is in that file that the pointer to the MVS PDS data set where the output from db2genJDBC utility will be placed is named.
2.6.2 Bind the DBRM plans The binding of the DBRM plans involves a few steps. Back in 2.4.6, “Bind WCSuite DBRM plan” on page 34 you bound one plan — mserver — but that didn’t have any JDBC/SQLJ information in it so it is not enough for WCSuite’s new function that uses Java. So now you must rebind mserver to include the JDBC/SQLJ information, as well as binding a default DB2 plan of DSNJDBC.
2.6.2.1 Running the db2genJDBC utility The first step in the binding process is running a DB2 SQLJ utility called db2genJDBC, which resides in the /usr/lpp/db2/db2610/bin directory. Let’s start to pull some of the pieces together. Figure 45 on page 74 shows the various files
Chapter 2. Prerequisites, installation and configuration
73
that help you run the db2genJDBC utility, and the output from the db2genJDBC utility.
(Your user profile)
DB2SQLJPROPERTIES=//db2sqljjdbc.properties [points to] [provides environment to]
(db2sqljjdbc.properties file)
DB2SQLJDBRMLIB=CMN.DBRMLIB.DATA [points to]
Your userid's OMVS shell
CMN.DBRMLIB.DATA(DSNJDBC1 DSNJDBC2 DSNJDBC3 PDS DSNJDBC4)
db2genJDBC process
/u/userid [point to on command]
HFS file
DSNJDBC_JDBCProfile.ser
db2jdbc.cursors Output from the db2genJDBC process ... and input to BIND process
Figure 45. Environment supporting the running of db2genJDBC utility
You can see why the updates to your user profile and db2sqljjdbc.properties come into play. Now, to run the utility, do the following: 1. Allocate the data set CMN.DBRMLIB.DATA as pointed to in the db2sqljjdbc.properties file. (If the data set already exists, then simply skip this step). The allocation parameters are as follows: Space units . . . . Primary quantity . Secondary quantity Directory blocks . Record format . . . Record length . . . Block size . . . . Data set name type
. BLOCK . 100 20 . 10 . FB . 80 . 6080 : PDS
2. Locate the file db2jdbc.cursors. It’s typically located in the /usr/lpp/db2/db2610/classes directory. Make a note of its location because you’ll have to point to it on the command line when you invoke db2sqljjdbc. 3. Go to the OMVS shell, and change directories to /usr/lpp/db2/db2610 directory (or whatever the classes directory of your DB2 installation happens to be), and issue the command: db2genJDBC -cursors=db2jdbc.cursors
If the cursors file is located any place other than the current directory, then qualify the file name with the directory path.
74
IBM WebSphere Commerce Suite V4.1 for OS/390
If things run properly, the output will look like this: -----------------------------------------------------> DB2 6.1: Begin Generation of JDBC Profile -----------------------------------------------------> JDBC program name is: DSNJDBC -> Number of JDBC Statements is: 150 -> Number of Callable Statements is: 5 -> Cursor Property file is: /usr/lpp/db2/db2610/classes/db2jdbc.cursors -----------------------------------------------------> Creating DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC1)' -> Successfully created DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC1)' -> Creating DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC2)' -> Successfully created DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC2)' -> Creating DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC3)' -> Successfully created DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC3)' -> Creating DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC4)' -> Successfully created DBRM in dataset //'CMN.DBRMLIB.DATA(DSNJDBC4)' db2genJDBC SUMMARY INFORMATION -----------------------------------------------------> JDBC Profile DSNJDBC contains: -> 150 Statement sections. -> 5 Callable Statment sections. -> 100 NON HOLD cursors. -> 100 HOLD cursors. ----------------------------------------------------->INFORMATIVE<->INFORMATIVE<->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<- -> ->INFORMATIVE<->INFORMATIVE<- -> JDBC applications. ->INFORMATIVE<->INFORMATIVE<-
***************** IMPORTANT ***************** The following DBRMs must be bound as specified into the packages with the associated Transaction Isolation: Bind DBRM in //'CMN.DBRMLIB.DATA(DSNJDBC1)' into Package DSNJDBC1 with Transaction Isolation UR Bind DBRM in //'CMN.DBRMLIB.DATA(DSNJDBC2)' into Package DSNJDBC2 with Transaction Isolation CS Bind DBRM in //'CMN.DBRMLIB.DATA(DSNJDBC3)' into Package DSNJDBC3 with Transaction Isolation RS Bind DBRM in //'CMN.DBRMLIB.DATA(DSNJDBC4)' into Package DSNJDBC4 with Transaction Isolation RR These packages must then be bound into the plan to be used for ***************** IMPORTANT *****************
-----------------------------------------------------> DB2 6.1: End Generation of JDBC Profile -----------------------------------------------------
4. If you look in the directory in which you ran the db2genJDBC utility, you’ll find a file named: DSNJDBC_JDBCProfile.ser. Any servlet running under the WAS plugin will need information on the location of this file. The method of telling it where that file exists is with the appserver.classpath directive in the was.conf file. Therefore, this file must reside in a directory named on appserver.classpath.
Note:
This step is critically important, otherwise when you run a servlet that attempts a JDBC connection it’ll fail and indicate it can’t find the serialized profile..
So, copy this file to the separate directory we created for storing the WCSuite configuration files (/u/cmnsrv/configs in our example). 5. Edit the was.conf file and update the appserver.classpath directory with the directory in which you just placed the DSNJDBC_JDBCProfile.ser file. In our example that would be /u/cmnsrv/configs. You will need to stop and restart the WAS Webserver to pick up the changes to the was.conf file.
Chapter 2. Prerequisites, installation and configuration
75
You’re almost there. Now you must bind the plans.
2.6.2.2 Binding the plans The process of binding the DBRM plan involves running two JCL job streams. One JCL job stream is provided by DB2 (this is the DSNTJJCL member in the data set DSN610.SDSNSAMP), and one is provided by the WCSuite product (this is the file /usr/lpp/CommerceSuite/install/cmnbjdbc.jcl). The process you should follow is: 1. Copy the member DSN610.SDSNSAMP(DSNTJJCL) to your own JCL library for modification. 2. Make the appropriate modifications. Figure 46 illustrates what needs updating.
Supply a job card
Point to the DB2 SDSNLOAD module
DSNTJJCL JOB ... //****************************************************** (comments removed to save space)
//****************************************************** //JOBLIB DD DISP=SHR, // DSN=DSN610.SDSNLOAD Point to the data set //BINDJDBC EXEC PGM=IKJEFT01,DYNAMNBR=20 that received the //DBRMLIB DD DISP=SHR, output from the // DSN=CMN.DBRMLIB.DATA db2genJDBC utility //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * Specify the DSN SYSTEM(DBS2)
DB2 subsystem ID
BIND BIND BIND BIND BIND
PACKAGE (DSNJDBC) MEMBER(DSNJDBC1) PACKAGE (DSNJDBC) MEMBER(DSNJDBC2) PACKAGE (DSNJDBC) MEMBER(DSNJDBC3) PACKAGE (DSNJDBC) MEMBER(DSNJDBC4) PLAN(DSNJDBC) PKLIST(DSNJDBC.DSNJDBC1, DSNJDBC.DSNJDBC2, DSNJDBC.DSNJDBC3, DSNJDBC.DSNJDBC4)
ISOLATION(UR) ISOLATION(CS) ISOLATION(RS) ISOLATION(RR)
END /* //
Figure 46. Modifications to supplied DB2 sample BIND job DSNTJJCL
3. Submit the job. This will result in the plan DSNJDBC being bound. 4. Copy the HFS file /usr/lpp/CommerceSuite/install/cmnbjdbc.jcl to your JCL library for modification. Copying from an HFS file to a PDS can be accomplished from the ISHELL, or by using the OGET command. 5. Make the appropriate modifications. Figure 47 on page 77 illustrates what modifications are required.
76
IBM WebSphere Commerce Suite V4.1 for OS/390
Supply a job card CMNBJDBC JOB ... Point to the data set //****************************************************** that received the (comments removed to save space) output from the //****************************************************** db2genJDBC utility //BINDJDBC EXEC PGM=IKJEFT01,DYNAMNBR=20 //DBRMLIB DD DISP=SHR, // DSN=-YYYYYYY-.DBRMLIB.DATA // DD DSN=-YYYYYYY-.SCMNDBRM,DISP=SHR Point to the WCSuite //SYSTSPRT DD SYSOUT=* SCMNDBRM data set //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(-ZZZZ-) Specify the DB2 BIND BIND BIND BIND BIND
PACKAGE (DSNJDBC) MEMBER(DSNJDBC1) ISOLATION(UR) PACKAGE (DSNJDBC) MEMBER(DSNJDBC2) ISOLATION(CS) PACKAGE (DSNJDBC) MEMBER(DSNJDBC3) ISOLATION(RS) PACKAGE (DSNJDBC) MEMBER(DSNJDBC4) ISOLATION(RR) PLAN(MSERVER) PKLIST(DSNJDBC.DSNJDBC1, DSNJDBC.DSNJDBC2, DSNJDBC.DSNJDBC3, DSNJDBC.DSNJDBC4) MEMBER(NETCDB2,DTWGA226) ACTION(REPLACE) + KEEPDYNAMIC(YES) ISOLATION(CS) CURRENTDATA(NO);
subsystem ID
END /* //
Figure 47. Modifications to supplied WCSuite sample BIND job cmnbjdbc
6. Submit the job. A return code of 4 is normal. This will result in the plan MSERVER being bound. Now you are ready to verify your JDBC configuration.
2.6.3 Verify the JDBC connection To verify the JDBC connection, you can compile and run as a servlet some sample Java code we supply in this redbook. This servlet makes a JDBC connection to DB2 and then does a simple query against the MERCHANT database table of the WCSuite Demomall. The results are displayed on your browser. There are several steps you must take: 1. Update your user profile. 2. Modify the sample servlet code to match your environment. 3. Compile the servlet code. 4. Copy the resulting class file to your WAS Webserver’s servlet directory. 5. Update your was.conf file to recognize the new servlet. 6. Restart the WAS Webserver. 7. Test the servlet. These steps are discussed in detail in the following sections.
Chapter 2. Prerequisites, installation and configuration
77
2.6.3.1 Update your user profile Your user profile (the same .profile you updated back in 2.6.1, “Update the environment variable and configuration files” on page 71) needs to be updated to do two things: • Provide access to the javac Java compiler, which resides in the /bin directory of the Java home. • Provide access to the various Java classes that will be used to compile the sample servlet. Update the following environment variables in your .profile: PATH Add /usr/lpp/java/J1.1/bin to the path variable. (If your Java install path is different than this — for example, /usr/lpp/java18/J1.1/bin, which is what it was on the system used to write this redbook — then use what your system has). CLASSPATH There is quite a list of files to add to the CLASSPATH: CLASSPATH=$CLASSPATH:/usr/lpp/WebSphere/AppServer/lib/ibmwebas.jar CLASSPATH=$CLASSPATH:/usr/lpp/WebSphere/AppServer/lib/jsp10.jar CLASSPATH=$CLASSPATH:/usr/lpp/WebSphere/AppServer/lib/lotusxsl.jar CLASSPATH=$CLASSPATH:/usr/lpp/WebSphere/AppServer/lib/servlet.jar CLASSPATH=$CLASSPATH:/usr/lpp/WebSphere/AppServer/lib/xml4j.jar CLASSPATH=$CLASSPATH:/usr/lpp/WebSphere/AppServer/lib/x509v1.jar CLASSPATH=$CLASSPATH:/usr/lpp/java18/J1.1/lib/classes.zip
This example illustrates a handy way to avoid having a long environment variable line that extends beyond the right side of the screen. The $CLASSPATH variable contains all the contents of CLASSPATH issues up to that point in the file. So by using $CLASSPATH at the beginning of each line, you can simply concatenate the new entry to the end of the previous entries. This method also ensures that any CLASSPATH setting established by the /etc/profile file is carried in and placed at the front of your CLASSPATH.
2.6.3.2 Modify the sample servlet code to match your environment The sample servlet code is as follows. If you are reading the PDF version of this redbook, select the text and copy-and-paste the code to a text editor, then FTP it to your user home directory on your OS/390 system for compiling. The file name on the OS/390 system must be TestJdbc.java Here’s what you need to change in the source code: • The value for static String url = needs to be one that can map to a “default_jdbcpool” JDBC connection pool statement in the was.conf file. Specifically, it needs to map to the “databaseurl” connection pool statement: jdbcconnpool.default_jdbcpool.databaseurl=jdbc:db2os390:
where is the name of your DB2 location name (not subsystem ID). // ### import import import
78
Start of sample code ### java.io.*; java.sql.*; javax.servlet.*;
IBM WebSphere Commerce Suite V4.1 for OS/390
import javax.servlet.http.*; public class TestJdbc extends HttpServlet { static String db2Driver = "COM.ibm.db2os390.sqlj.jdbc.DB2SQLJDriver"; static String url = "jdbc:db2os390sqlj:LOC"; static String query = "SELECT MERFNBR,MESTNAME FROM CMNSRV.MERCHANT"; static Connection con = null; public void init(ServletConfig config) throws ServletException { loadDriver(db2Driver); try { con = DriverManager.getConnection(url); } catch (SQLException e) { e.printStackTrace(); } } public void destroy() { try { if (con != null) con.close(); } catch (Exception e) { e.printStackTrace(); } }
/* Close connection with Data Base*/
public void doGet (HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException { res.setContentType("text/html"); PrintWriter out = res.getWriter(); out.println(""); out.println("Stores in Demomall"); out.println(""); out.println("Query of MERCHANT Table
"); out.println(""); executeSQL(out); out.println(""); out.println(""); out.println("
