word pro - wp101142 - feature pack for ejb3 · overview of feature packs and the ejb 3.0 feature...

WebSphere Application Server for z/OS V6.1

Feature Pack for Feature Pack for Feature Pack for Feature Pack for EJBEJBEJBEJB 3 3 3 3.0.0.0.0

This document can be found on the web at:www.ibm.com/support/techdocs

Search for document number WP101142 under the category of "White Papers"

Version Date: June 10, 2008See "Document Change History" on page 37 for a description of the changes in this version of the document

Written by the WebSphere Application Server for z/OS Support Team at the

IBM Washington Systems CenterIBM Washington Systems CenterIBM Washington Systems CenterIBM Washington Systems Center

Part of the IBM Americas Advanced Technical Support (ATS) organization

Many thanks to Harvey McGee, Rohith Ashok, Jeff Mierzejewski and MickeyScott, all of WebSphere z/OS development.

The WebSphere Application Server for z/OS support team at the WashingtonSystems Center consists of: John Hutchinson, Bob Teichman, Mike Kearney, Louis

Wilen, Lee-Win Tai, Steve Matulevich, Mike Loos, Paul Houde and Don Bagwell.Mike Cox, Distinguished Engineer, serves as technical consultant and advisor.

For questions or comments regarding this document, send e-mail to Don Bagwell [email protected]

Table of Contents

19Augmentation of an existing Deployment Manager node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19Adding other feature packs to this Deployment Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19Quick visual verification of the feature pack being included in DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18Uploading and running the jobs to create the stacked DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17Step-by-step illustration of stacked create for the FZCELL DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16A picture illustrating the intermediate symbolic links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16Stacked create of a new Deployment Manager node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16Configuring and Running the Jobs that Add the Feature Pack to a Node . . . . . . . . . . . . . . . . . . . . .

14Acquiring the Feature Pack for Web Services function for Application Server Toolkit . . . . . . . . . . . . .

13Using Rational Product Updater with a local copy of the update files . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12Upgrading to 6.1.1.5 using Rational Product Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11Download the Application Server Toolkit 6.1.1 installation ZIP file and install . . . . . . . . . . . . . . . . . . . . . . . . . .

11Clear the leftover folders and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11Uninstall earlier version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10Installing Application Server Toolkit 6.1.1 before upgrading to 6.1.1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . .

10Seeing evidence of feature packs in the zPMT product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9Verifying the level of Application Server Toolkit you have currently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9State of your Application Server Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9The Application Server Toolkit and zPMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8WebSphere Application Server for z/OS maintenance information URLs . . . . . . . . . . . . . . . . . . . . . . . . .

8Other maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8Installation process at a high level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8Minimum level of WebSphere Application Server required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8WebSphere Application Server "Optional Materials" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8Installating the Feature Pack for EJB 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7Is there a charge for the Application Server Toolkit? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7If I don't have a copy of the Application Server Toolkit, can I get one? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7May I use the ISPF panels for any of this work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7Is there a way to remove a feature pack from a node once it's there? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7Is there a way to "un-augment" the Deployment Manager if I change my mind? . . . . . . . . . . . . . . . . . . . . . . . . .

7Does the Deployment Manager have to be down when this is done? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7How long does the DMGR augmentation update take? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7Does the augmenting of the DMGR change the configuration file structure? . . . . . . . . . . . . . . . . . . . . . . . . . . .

7Does the DMGR need to be augmented before a node with that feature pack can be federated? . . . . . . . . . .

7Must a node be created with the feature pack before it is federated into the DMGR? . . . . . . . . . . . . . . . . . . . .

6How can the Feature Pack for EJB 3.0 be applied to a node? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6Do I need this feature pack code included in all my nodes? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6May I continue to use EJBs written to the 2.1 specification level? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6Is this something I should do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6Is this Feature Pack for EJB 3.0 something I must do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6Some initial questions and answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6What is EJB 3.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5Creating a node with a feature pack included vs. updating an existing node . . . . . . . . . . . . . . . . . . . . . .

5The role of zPMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4Linking a feature pack into a node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4Overview of "Feature Pack" architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4Overview of Feature Packs and the EJB 3.0 Feature Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3Overview of "Stacked Create" and "Augmentation" process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3Summary of options to include feature pack with a node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3Specifics at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3Specifics at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

WP101142 - Feature Pack for EJB 3.0

Section: MainVersion Date: Tuesday, June 10, 2008

- 1 -© 2007, IBM Americas Advanced Technical SupportWashington Systems Center, Gaithersburg, MD

37Document Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

36Granting necessary UNIXPRIV privileges to ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35A note about maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

34A note about intermediate symbolic links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33Downloading update ZIP file and applying locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33Using Rational Product Updater to apply EJB 3.0 update to Toolkit 6.1.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33Apply the update for EJB 3.0 to Application Server Toolkit 6.1.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32Step 1 - Get to Application Server Toolkit 6.1.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32EJB 3.0 update to Application Server Toolkit 6.1.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32Miscellaneous Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31What happens if you deploy an EJB 3.0 application into a node without EJB 3.0 support? . . . . . . . . . . . . . . .

30Invoking the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30Installing the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30Programmatic verification of feature pack inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30Visual verification of feature pack inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30Verifying the Feature Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

28Replace an existing node with a new node created with the feature pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27Create and federate a new node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27Including the feature pack into existing cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27Federation of a Standalone with feature packs into a DMGR that's been augmented . . . . . . . . . . . . .

26Stacked create of a new Standalone with Feature Pack for Web Services with immediateaugmentation of Feature Pack for EJB 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

26Quick visual verification of Feature Pack for EJB 3.0 being included in Standalone Server . . . . . . . . . . . . . . .

26Adding other feature packs to this Standalone Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

26Start the Standalone or not? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25Uploading and running the jobs to create the stacked DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23Step-by-step illustration of stacked create for the FZCELL standalone server . . . . . . . . . . . . . . . . . . . . . . . . .


22Stacked create of a new Standalone Server node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

22Adding other feature packs to this Deployment Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

22Quick visual verification of Feature Pack EJB 3.0 being included in DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . .

22Uploading and running the job to augment the DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

20Step-by-step illustration of the augmentation of the FZCELL DMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


19Important Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .




Specifics at a Glance

Specifics at a glance

BothApplicable to ND configuration or standalone?

YesMay be used with earlier Feature Pack for Web Services?

No. The FP EJB3.0 function is part of theApplication Server Toolkit 6.1.1.5 product. 1

Optional Feature needed to Application Server Toolkit?

AST 6.1.1.5 1Minimum level of Application Server Toolkit (for zPMTfunction)

UK31382 and UK31495PTFs that supply the Feature Pack for EJB 3.0

Version 6.1.0.13 + AK56841, or higherMinimum level of WebSphere Application Server for z/OS

Supports all functions described in the EJB3.0 Core Contracts specification.

What it provides

Summary of options to include feature pack with a node

"Stacked create" = one set of jobs that builds the node and links to the feature pack in one step"Augmentation" = a job that links a node to the feature pack after it has been created

Note:

Note: Standalone server nodes may be augmented with Feature Pack for EJB 3.0 provided the augmentation isdone immediately after Standalone creation and before federation takes place.

NoNoExisting federated Appserver node

No NoteYesStandalone Server node

YesYesDeployment Manager node

AugmentationStacked Create

Overview of "Stacked Create" and "Augmentation" process

For more detailed information, go to "Configuring and Running the Jobs that Add the Feature Packto a Node" starting on page 16.

� Use zPMT to create a single customized job that updates the target node

� Upload the job to z/OS and execute

Applicable to the a Deployment Manager node only, with one exception:augmentation with Feature Pack for EJB 3.0 of a standalone server that's neverbeen started. This would be the case where you're building a new server and youwant both Feature Pack for Web Services and Feature Pack for EJB 3.0. Youstack create with Web Services, then immediately augment with EJB 3.0.

Augmentation

Updates a node withthe feature pack

� Use zPMT to create a customized set of creation jobs designated as doing boththe node creation and the inclusion of the feature pack

� Upload the jobs to z/OS and execute in sequence

The zPMT panels to configure the stacked create are nearly identical to those fora normal node creation process. There is one additional panel for the featurepack information.

The jobs are the same as for a normal node creation. The inclusion of the featurepack is included in the same jobs. It does not imply an additional job.

Stacked Create

Creates the node andincludes the featurepack in one set of jobs

What's involvedProcess




1 Between Nov 30, 2007 and Dec 12, 2007 ... see "EJB 3.0 update to Application Server Toolkit 6.1.1.4" on page 32 for anupdate to 6.1.1.4.

Overview of Feature Packs and the EJB 3.0 Feature Pack

Overview of "Feature Pack" architecture

"Feature Packs" are a way of providing new function on an optional basis. Those who want it getthe feature pack, those who do not want it simply forego the feature pack. The function provided ina feature pack is added to a node's configuration through utility jobs created by the zPMTconfiguration tool. How that is done is the subject of this paper.

The Feature Pack for EJB 3.0 is the second one delivered for WebSphere Application Server.The first was the Feature Pack for Web Services, which came out at the end of June 2007.

Note:

The key to begin understanding the feature pack architecture is to realize that the files thatimplement the function of each feature pack is supplied separately from the normal WebSphereApplication Server for z/OS product HFS. The feature packs are part of the "Optional Materials." Sowhen you think of "WebSphere Application Server for z/OS" there are really two FMIDs in play:

/usr/lpp

/zWebSphere

/V6R1

/zWebSphere_OM

/V6R1

(The WebSphere z/OS product HFS)hlq.SBBOHFS

(WebSphere "Optional Materials" product HFS)hlq.SIWOHFS

/FPWS

/FPEJB3

/HTTP

Feature Pack for Web Services

IBM HTTP Server Powered by Apache

Feature Pack for EJB 3.0

/xxx

/yyyFuture feature packs

FMID = H28W610

FMID = JIWO610

The feature packs are added to the "Optional Materials" product via PTFs. See "Installating theFeature Pack for EJB 3.0" on page 8 for service levels and PTFs needed.

Linking a feature pack into a node

Installing the code is the first step. The second step is to "link" a node's configuration HFS tothe feature pack code so the node can make use of the function. That is done using customizedjobs created using the zPMT tool. Those jobs update the node's configuration HFS withsymlinks that connect the node to the installed feature pack code.

How those jobs are created and run is what this document is all about.

What the various "gotchas" are will be covered in this document.

The key points to understand right now are:

� Feature packs are additional function supplied in the "Optional Materials" (FMID JIWO610)

product




� The "Feature Pack for EJB 3.0" is one feature pack ... it is in fact the second one to be released.The "Feature Pack for Web Services" came out in the middle of 2007. Other feature packs areplanned for the future.

� You decide whether the function provided in a feature pack is something you wish to use. If so,then you need to "link" a node's configuration HFS to the feature pack file structure.

� The zPMT tool (part of the Application Server Toolkit) plays a key role in this. The zPMT is thetool used to create the customized JCL batch jobs that "link" a node to the feature pack.

The role of zPMT

The zPMT configuration tool is a required piece of this puzzle. The zPMT is what builds thecustomized batch jobs that link a node to a feature pack. Here's a snapshot of a zPMT panel thatshows the two feature packs:

The key point we'd like to make at this point in the paper is that the Application Server Toolkit, inwhich the zPMT resides, needs to be at a minimum level (6.1.1.5) to have the Feature Pack for EJB3.0 functionality. Earlier versions won't have it.

So it's a coordination thing: Feature Pack installed on z/OS and Application Server Toolkit (zPMT)at the right level so the customized jobs can be built to link the node into the feature pack.

And if you'd like to use the Feature Pack for Web Services as well, that code is provided as an"Optional Feature" to the AST and needs to be installed separately.

Note:

We discuss how to check for the proper level of Application Server Toolkit and how to update itunder "The Application Server Toolkit and zPMT" starting on page 9.

Creating a node with a feature pack included vs. updating an existing node

There are two ways a node's configuration can be linked to the function provided by a feature pack:

1. By building it that way from the start

This is known as doing a "stacked" create -- "stacked" meaning the zPMT tool combines the basicnode configuration tasks with the feature pack tasks into one set of creation jobs. You run those jobsin sequence and when you're done you have a node that also has the feature pack. Only the zPMTtool can be used to do this; the ISPF configuration panels do not support the feature packs.

2. By updating an existing node configuration

This is known as "augmenting" a node -- "augment" meaning update, or "add to" the node. The jobthat does this is created by the zPMT tool.

The Deployment Manager node is eligible to be augmented with a feature pack, butapplication server nodes (or "managed nodes") are, generally speaking, not eligible.There are exceptions to that as we'll see, but the exceptions all involve augmenting anapplication server node immediately after creating it.

Important:

This has an impact on applying a feature pack to an existing cell. If an existing application servernode can't be augmented with the feature pack, and you want that node to have the new function, itmeans one of two things: either a new node needs to be built, or the existing node torn down andre-built with the feature pack.




Building a brand new cell is less of a concern because you can employ the "stacked" createapproach as needed as you construct your cell.

We'll see how all this fits together as we draw out several scenarios and illustrate the step-by-stepprocess used to introduce the feature pack function into the node.

What is EJB 3.0?

The Sun web site offers the following:

Q: How does EJB 3.0 improve over EJB 2.1?

A: The goal of EJB 3.0 is to target ease of development, the main theme of the Java EE 5 platformrelease. EJB 3.0 is a major simplification over the APIs defined by the EJB 2.1 and earlierspecifications. The simplified EJB 3.0 API allows developers to program EJB components as ordinaryJava objects with ordinary Java business interfaces rather than as heavy weight components. Bothcomponent and client code are simplified, and the same tasks can be accomplished in a simpler way,with fewer lines of code. Because it is much simpler, EJB 3.0 is also much faster to learn to use than

EJB 2.1. 2

The specifics of that get deep into the realm of application development, which is outside the scopeof this white paper.

The key point is this: the Feature Pack for EJB 3.0 provides code support for WebSphereApplication Server for z/OS to run code written to the EJB 3.0 specification. And as mentioned, thefeature pack supports all the functions described in the "EJB 3.0 Core Contracts" specification.

Some initial questions and answers

Is this Feature Pack for EJB 3.0 something I must do?

No. You consider this only if you want to provide to your WebSphere configuration the newfeatures that are provided in the Feature Pack for EJB 3.0.

Is this something I should do?

That depends. If you intend to write applications that employ EJB 3.0 code, then yes. But if youhave no intention of doing that, then perhaps not.

May I continue to use EJBs written to the 2.1 specification level?

Yes. This adds the EJB 3.0 support. It does not remove the EJB 2.1 support.

Do I need this feature pack code included in all my nodes?

Not necessarily. Only those application server nodes where you want to use the newfunctionality, and the Deployment Manager node. Application server nodes that don't need thisnew functionality don't require knowledge of or access to the feature pack.

How can the Feature Pack for EJB 3.0 be applied to a node?

As mentioned, there are two ways:

1. It can be added at the time of node creation. This is known as a "stacked" creation -- the zPMTtool is told to create the customized jobs to include both the creation of the node as well as theinclusion of the feature pack.

2. It can be added after the fact using "augmentation." But as mentioned, that is generally speakingonly applicable to the Deployment Manager node. One exception is an application server nodethat was stack created with the Feature Pack for Web Services (the first one delivered, back inJune of 2007) but not yet started for the first time. That node may then be augmented with thefeature pack.




2http://java.sun.com/javaee/overview/faq/ejb.jsp

Must a node be created with the feature pack before it is federated into the DMGR?

Yes. A node can't be federated without starting it at least once. And if a node has been startedonce, it's no longer eligible for augmentation with the feature pack. So the order of things is: stack create the node with the feature pack, then federate it into the DMGR.

Does the DMGR need to be augmented before a node with that feature pack can befederated?

Yes. Federation won't work otherwise. For a DMGR to accept a node that has the feature pack,the DMGR must also have that same feature pack.

Does the augmenting of the DMGR change the configuration file structure?

Yes it will. Whenever you augment a DMGR node with a feature pack, be sure to back up yourcell's configuration file system.

How long does the DMGR augmentation update take?

It depends, but figure on about 20 minutes.

Does the Deployment Manager have to be down when this is done?

Yes. The Deployment Manager must be stopped when this update is performed.

Is there a way to "un-augment" the Deployment Manager if I change my mind?

There's no un-augment job. You can restore the backup copy of your file system.

Is there a way to remove a feature pack from a node once it's there?

There's no remove job. You would have to rebuild the node.

May I use the ISPF panels for any of this work?

No. The zPMT is what's required. The zPMT is part of the Application Server Toolkit. The ISPFpanels have no knowledge of feature packs.

Consider the ISPF panels more or less "deprecated" at this point in time. The zPMT methodof creating configurations and updating them will be what's used going forward from here.

Note:

Further, the Application Server Toolkit and zPMT need to be brought up to the proper level forthis to work. We show how to do that under "The Application Server Toolkit and zPMT" startingon page 9.

If I don't have a copy of the Application Server Toolkit, can I get one?

Yes. See the instructions for doing that under "The Application Server Toolkit and zPMT"starting on page 9.

Is there a charge for the Application Server Toolkit?

If you have a valid license for WebSphere Application Server -- distributed or z/OS -- you havethe right to use the Application Server Toolkit/zPMT. No charge.




Installating the Feature Pack for EJB 3.0

WebSphere Application Server "Optional Materials"

The FPWS requires that the WebSphere "Optional Materials" be installed. That is FMID JIWO610.

That is typically installed at /usr/lpp/zWebSphere_OM/V6R1.

The FPWS will be installed into that zWebSphere_OM structure.

Minimum level of WebSphere Application Server required

You must be at 6.1.0.13 at a minimum. That became available on November 22, 2007.

Installation process at a high level

� Receive and apply ++APAR AK56841. This is necessary maintenance to the WebSphere

Application Server for z/OS 6.1.0.13 code in preparation for the use of the Feature Pack for EJB3.0 functionality..

� Receive and apply PTF UK31382. This provides some sample jobs that prepare the

environment for the Feature Pack for EJB 3.0 PTF.

� Receive and apply PTF UK31495. This is the Feature Pack for EJB 3.0 function.

Other maintenance

� UK31229 -- brings Feature Pack for Web Servics up to 6.1.0.13 level.

� UK30625 -- brings WebSphere IHS z/OS up to 6.1.0.13 level.

WebSphere Application Server for z/OS maintenance information URLs

"APAR/PTF Tables by version for IBM WebSphere Application Server for z/OS"http://www.ibm.com/support/docview.wss?rs=404&uid=swg27006970

"APAR/PTF table for WebSphere Application Server V6.1 for z/OS"http://www.ibm.com/support/docview.wss?rs=404&uid=swg27007926

"APAR/PTF Table for IBM WebSphere Application Server for z/OS v6.1 optional materials"http://www.ibm.com/support/docview.wss?rs=404&uid=swg27009131




The Application Server Toolkit and zPMT

The Application Server Toolkit is the piece of software in which the zPMT (z/OS Profile ManagementTool) is shipped. The zPMT is what you use to configure the customized jobs that create nodes andcells, and you use to link a node into the feature pack.

In this section we will focus on how to get you to the point where you may be in a position to start theprocess of customizing the jobs to include the Feature Pack for EJB 3.0. The steps to actually do thecustomization will be covered in the next section.

State of your Application Server Toolkit

We'll provide a quick summary chart of the different starting states of your Application Server Toolkitand give you guidance on how to get to the point where you can start configuring the jobs for thefeature pack support.

... you'll need to install the Web Services "Optional Feature" into theApplication Server Toolkit.

See "Acquiring the Feature Pack for Web Services function forApplication Server Toolkit" on page 14.

... you wish to acquire theApplication Server Toolkitsupport for Feature Pack forWeb Services (FPWS).

... you're probably experiencing a problem where the firewall ispreventing the Rational Product Updater function from communicatingwith its update host. There's a way to FTP the update file down to yourPC -- most firewalls will permit FTP -- and point the AST at that updatefile.

See "Using Rational Product Updater with a local copy of the updatefiles" on page 13.

... can't work the RationalProduct Updater because offirewall issues.

... you'll need to use the Rational Product Updater function to take thetoolkit to the 6.1.1.5 level that includes the Feature Pack for EJB 3.0function.

See "Upgrading to 6.1.1.5 using Rational Product Updater" on page 12.

... are at Application ServerToolkit 6.1.1 but not yet6.1.1.5.

... you may apply an update to 6.1.1.4 that will provide the EJB 3function. See "EJB 3.0 update to Application Server Toolkit 6.1.1.4" onpage 32. If AST 6.1.1.5 is availabe (after 12-Dec-2007) then updating to6.1.1.5 is recommended over update to 6.1.1.4. See next table row.

... are at Application ServerToolkit 6.1.1.4

... you'll need to install the 6.1.1 version of the Application Server Toolkitbefore you can use the Rational Product Updater function to take thetoolkit to the 6.1.1.5 level that includes the Feature Pack for EJB 3.0function.

See "Installing Application Server Toolkit 6.1.1 before upgrading to6.1.1.5" on page 10.

... are at a level of theApplication Server Toolkitprior to 6.1.1.

... see "Verifying the level of Application Server Toolkit you havecurrently" on page 9.

... wish to verify the level ofApplication Server Toolkit youcurrently have.

Then ...If you ...

Verifying the level of Application Server Toolkit you have currently

� Start your copy of Application Server Toolkit

� Select Help � About

� The level of the Application Server Toolkit is reported there:




� You have two options to acquire the Feature Pack for EJB 3.0 function in zPMT:1. Update 6.1.1.4 with an update fix that contains the EJB 3.0 function. See "EJB 3.0

update to Application Server Toolkit 6.1.1.4" on page 32 for more on this option.2. Update Application Server Toolkit to 6.1.1.5 -- that level includes the zPMT with the

Feature Pack for EJB 3.0 function included. This is the focus of this section.

� If you're at 6.1.0.x then you can't use the Rational Product Updater feature to get to6.1.1.5. You need to install 6.1.1.0 first, then update to 6.1.1.5. See "InstallingApplication Server Toolkit 6.1.1 before upgrading to 6.1.1.5" on page 10.

Notes:

Seeing evidence of feature packs in the zPMT product

If you're curious to see what feature packs, if any, the zPMT thinks it has available to it, you canfollow this simple procedure:

� Start your copy of Application Server Toolkit

� Select Window � Preferences

� Scroll down and expand "Servers"

� Click on "WebSphere for z/OS Customization"

� Over on the right side click on the "Create" button

� Click "Next" to get past the first information panel

� On the "Environment Selection" panel you'll see what features packs are present:

In this example both the EJB and the Web Services feature packs are present

If nothing appears below the "z/OS federate an application server" line, then no feature packs are present

� If your Application Server Toolkit is at 6.1.1.5 and you don't see "Feature Pack for EJB3.0," then something is wrong. The EJB feature pack should be part of the 6.1.1.5Application Server Toolkit product.

� If you're interested in the Web Services feature pack and you don't see it there, read"Acquiring the Feature Pack for Web Services function for Application Server Toolkit" onpage 14.

Notes:

� Click "Cancel" to back out of the zPMT

� Click "Cancel" again to back out of "Preferences"

� Close the Application Server Toolkit

Installing Application Server Toolkit 6.1.1 before upgrading to 6.1.1.5




It turns out a copy of the Application Server Toolkit at a level below 6.1.1 -- for example, 6.1.0.4 orwhatever -- can not be updated to 6.1.1.x using the Rational Product Updater. It just can't.

What is required is that you uninstall the pre-6.1.1 version and install Application Server Toolkit6.1.1. Then you can use the Rational Product Updater feature to get to 6.1.1.5.

Uninstall earlier version

� Uninstall the copy of Application Server Toolkit by going into Control Panel � Add orRemove Programs. It should show up as "IBM WebSphere Application Server Toolkit."

Clear the leftover folders and files

The uninstall process will not remove all the folders and files from where the product wasinstalled before. You may see that the installation of the new Application Server Toolkit 6.1.1code fails because of these files still being present. You have a choice: delete the remnantfolder structure or install Application Server Toolkit 6.1.1 at a different location.

We'll assume you'll delete the folder structure. If you wish to install the new Application ServerToolkit as a different location, skip to the next step.

We have a quirky issue to overcome ... the folder structure is so deep, and some of thefolders have such long names, that the total length of some of the files exceeds whatWindows can delete. What we'll do next is a workaround to overcome this.

Note:

� Open up Windows Explorer

� Go to C:\Program Files\IBM\WebSphere\AST

� Using Windows Explorer, try to delete the folders under \AST. Some will succeed, others

will fail. The ones that fail will be the ones where the length of the folder structure is toolong.

� For those that failed to delete, do the following:

� Using Windows Explorer, rename the first folder that failed to delete to somesingle-character name, such as A or X or whatever.

� Expand that folder and rename the next folder down a single character name.

� Repeat this for about five or six levels deep.

� Then try to delete the higher folder.

� If it succesfully deletes, then move on to the next folder that wouldn't delete

� But if it still won't delete, then keep renaming folders until you get to a point wherethe length of the total path is reduced enough to allow the folder tree to be deleted.

� When everything under \AST is gone, then delete \AST and move on to the next step.

Download the Application Server Toolkit 6.1.1 installation ZIP file and install

The Application Server Toolkit 6.1.1 product can be downloaded from the Internet at thefollowing location:

http://www.ibm.com/support/docview.wss?uid=swg24014241

That's the Windows version. The Linux version can be found at:


We'll focus on the Windows installation here.

Note:




� Go to that URL and scroll down to find this:

� Use either the FTP link or the DD link. The file that is downloaded will be called:

esd.image.ast.win32.zip

� The ZIP file has two "disk" folders inside of it. Extract those out to a location somewhere onyour hard drive.

� In the \disk1 folder locate install.exe and double click on it.

� Follow the prompts and install the Application Server Toolkit.

Upgrading to 6.1.1.5 using Rational Product Updater

This assumes you're at the 6.1.1 level at a minimum. If you're not, go to "Installing ApplicationServer Toolkit 6.1.1 before upgrading to 6.1.1.5" starting on page 10.

� Select Start � All Programs � IBM WebSphere �

Application Server Toolkit V6.1.1 � Rational Product Updater

� Click on the "Installed Products" tab. This will display what you have installed right now. It'lllook something like this:

� Click on the "Find Updates" button. The Application Server Toolkit will make contact with thewebsite and search for updates eligible for your copy of the toolkit. When it is finished it'll reportback what updates are available. You should see the "Fixpack 5" update available andchecked:

� Click "Install Updates"

� Accept the terms of the license and click on "OK"




� The updater will show a progress bar. This process takes some time (10 minutes or more) sobe patient:

� When it is done the Rational Product Updater will show no other updates, and you'll see the"Updates successfully installed" messsage:

� Click on the "Installed Products" tab to verify that 6.1.1.5 is installed:

� Close the Rational Product Updater.

Using Rational Product Updater with a local copy of the update files

Some people have reported trouble using the Rational Product Updater function because of firewallrules that block certain kinds of protocols and ports. To get around that, there is a way to FTP theupdate file as a big ZIP file, then point the Rational Product Updater at the extracted contents of thatlocal ZIP to do the updates.

� Point your browser at the following URL (all on one line ... it's split here):

ftp://ftp.software.ibm.com/software/websphere/appserv

/support/tools/AST/local/fixpacks/ast61/fp6115/

� Save the ast611fixpack5.zip file to your workstation's hard drive. The file is very large, so

it may take some time to download it.

� Unzip that file into some temporary folder, such as C:\temp\fixpack5 or whatever.

� Now go to Start � All Programs � IBM WebSphere �


� When Rational Product Updater opens, select Preferences � Update Sites.

� Use the "Browse" button drill down into where you unzipped the downloaded ZIP file ...C:\temp\fixpack5 or whatever you called it.

� Drill down into the \update folder




� Select the policy_6115_fixpack5.xml file then click the "Open" button

� Click on "OK". You just told Rational Product Updater where to look for updates. It'll "go" to thatlocal folder structure rather than out to the web.

When you're done, don't forget to clear this setting ... otherwise it'll keep going there for allfuture updates.

Note:

� Click on the "Find Updates" button. Rational Product Updater will very quickly search throughyour "local site" and determine the one update available is FixPack 5 -- 6.1.1.5

� Once it's done that, click on "Install Updates". It'll then start updating AST to 6.1.1.5. Thisprocess will take 10 minutes or more.

� When it has completed, close Rational Product Updater. Your Application Server Toolkit is nowat 6.1.1.5.

Acquiring the Feature Pack for Web Services function for Application Server Toolkit

� You need to be at 6.1.1.3 to install this Feature Pack for Web Services optional feature.

� To use Rational Product Updater to update the Application Server Toolkit to 6.1.1.3, youmust be at 6.1.1 at a minimum. If you're not, go to "Installing Application Server Toolkit 6.1.1before upgrading to 6.1.1.5" starting on page 10.

Notes:



� Click on the "Find Optional Features" button

� You'll see a progress bar as Rational Product Updater goes out and searches for what optionalfeatures are available for the level of Application Server Toolkit you have. This may take a fewminutes.

� When the search completes, you should see something like this:

Notice that there are two optional features there: the "Feature Pack for Web Services" (whatwe're looking for here), and the "Extended Deployment Profile Management Tooling." Thatsecond one is for configuring the jobs that augment nodes for WebSphere XD. It's a veryinteresting product, but not directly related to what we're covering in this document.

� Uncheck the Extended Deployment checkbox and make sure the Feature Pack for WebServices box is checked.

� Click on "Install Features"

� Accept the license

� A progress bar will appear as Rational Product Updater locates, downloads and installs thefeature. This will take a few minutes.

� When the installation is complete, click on the "Installed Products" tab and you should seesomething like this:




The Feature Pack for Web Services function appears, which means it is now available to thezPMT. If you want to verify that, see "Seeing evidence of feature packs in the zPMT product" onpage 10.

For more on the Feature Pack for Web Services, see:

http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101084

Note:




Configuring and Running the Jobs that Add the Feature Pack to a Node

In this section we'll look at five different creation scenarios:

Page 27"Federation of a Standalone with feature packs into a DMGR that's been augmented"5

Page 26"Stacked create of a new Standalone with Feature Pack for Web Services with immediateaugmentation of Feature Pack for EJB 3.0"

4

Page 22"Stacked create of a new Standalone Server node"3

Page 19"Augmentation of an existing Deployment Manager node"2

Page 16"Stacked create of a new Deployment Manager node"1

Some may wonder how to incorporate the feature packs into an existing cell. That's a bit morechallenging. We cover that under "Including the feature pack into existing cells" starting on page 27.

Stacked create of a new Deployment Manager node

Here we'll illustrate the use of the zPMT to create a single set of customized batch JCL jobs that willcreate a Deployment Manager and link it to the Feature Pack for EJB 3.0 code. This is called a"stacked create" -- the creation jobs are "stacked" with the Feature Pack inclusion work.

A picture illustrating the intermediate symbolic links

As we mentioned in "A note about intermediate symbolic links" on page 34, intermediatesymbolic links are a way of providing greater isolation between nodes in a configuration. Thisbecomes important if rolling maintenance in a non-disruptive way is an objective.

Using intermediate symbolic links is not a technical requirement. It is optional. It makesgood sense to use them, but you may point your configuration directly at the actual mountpoint of the SMP/E HFS file systems.

Note:

The following picture illustrates the intermediate symbolic link structure we used for theFZCELL:

/usr/lpp/zWebSphere/V6R1

/usr/lpp/zWebSphere_OM/V6R1

/FPEJB3

/FPWS

/wasv61config/fzcell

/fzdmnode_wassmpe

/fzdmnode_fpws

/fzdmnode_fpejb3

D/fzdmnode

A

B

C

E

F

GIntermediate symbolic links created in advance for the

FZCELL DMGR node

If this is your first exposure to intermediate symbolic links, please take a moment and studythe picture and see that they're really nothing more than directories that point to a differentplace. Please see WP100396 on ibm.com/support/techdocs for a complete

explanation of the value of using these things. Trust us ... you want to know aboutintermediate symlinks.

Note:

Notes:

A. The actual mount point for the WebSphere Application Server for z/OS SMP/E HFS(hlq.SBBOHFS).

B. The actual mount point for the WebSphere Application Server for z/OS "Optional Materials"feature (FMID=JIWO610 ... this was the hlq.SIWOHFS data set).




C. When we installed the the Feature Pack for Web Services and the Feature Pack for EJB 3.0PTFs, these directories were created to hold those files and folders.

D. The directory /wasv61config/fzcell/fzdmnode was where we planned on mounting the

configuration HFS for the DMGR node we were building.

E. This is the first of three intermediate symbolic links. This one pointed to the actual mount point ofthe WebSphere Appserver (FMID=H28W610) SMP/E HFS -- or block A in the picture. In the

zPMT we pointed to this intermediate symbolic link whenever it asked for the location of theWebSphere product code.

F. The second of three intermediate symbolic links. This one pointed to where the Feature Pack forEJB 3.0 code was installed. This was the directory /FPEJB3 under block B in the picture. In the

zPMT we pointed to this intermediate symbolic link whenever it asked for the location of theFeature Pack for EJB 3.0 code

G. The third of three intermediate symbolic links. This one pointed to where the Feature Pack forWeb Services code was installed. This was the directory /FPWS under block B in the picture. In

the zPMT we pointed to this intermediate symbolic link whenever it asked for the location of theFPWS code.

Step-by-step illustration of stacked create for the FZCELL DMGR

Follow along and see how you can do it using your copy of the Application Server Toolkit.

� Started the Application Server Toolkit

� Selected Window � Preferences

� Scrolled down and expand "Servers"

� Clicked on "WebSphere for z/OS Customization"

� Over on the right side clicked on the "Create" button

� Clicked "Next" to get past the initial information screen

� Selected the "Feature Pack for EJB 3.0" option and clicked "Next."

Next

This is the key to creating a "Stacked Create" -- select the feature pack first, then (asyou'll see) you select the configuration type next.

Note:

� The next panel presented the only two options for a "Stacked Create" that exist: DMGR orApplication Server. We picked Deployment Manager and clicked "Next."

Next




From that point the process was nearly identical to how a non-stacked DMGR would bedone (with one exception, which we'll show). For the sake of illustrating the intermediatesymbolic links we'll show a few of the panels related to that as well.

Note:

� On the panel where the configuration HFS information is specified there is also a placewhere it asks for the "Product File System." That mean the location of the WebSphere z/OSSMP/E product HFS. Back on page 16 we provided a picture of the intermediate symlinkswe created for this node. We entered the intermediate symlink for the product HFS here:

� After the familiar panel asking about the security options, a new panel was presented, thisone asking for information about where the Feature Pack for EJB 3.0 code was located:

Intermediate symbolic link for the FPEJB3 code

See "A picture illustrating the intermediate symbolic links" on page 16 for an illustrationof the intermediate symbolic links we used.

Note:

� From there on it was the exact same set of panels to finish up the definition and completethe generation of the jobs.

Uploading and running the jobs to create the stacked DMGR

The process of uploading the jobs for the "Stacked Create" definition is exactly the same as itwould be for any other configuration definition created by zPMT.




It turns out the jobs to be run are the same as you would run for any Deployment Manager node.There is no new or additional job in a "Stacked Create" that does the Feature Pack stuff. Thatprocess is buried in one of the existing jobs.

Starting the DMGR is done exactly the same as would be the case for a DMGR that was createdwithout the FPEJB.

Once you've created the "Stacked Create" definition, the rest of the process -- uploadthe jobs, run them and then start the DMGR -- is the same.

Key Point:

Quick visual verification of the feature pack being included in DMGR

� In the Administrative Console go to System Administration � Nodes

� Take a look at the "Version" information for the node:

EJB 3.0 Version information is seen ... means FP is part of the node

Adding other feature packs to this Deployment Manager

That would involve performing an "augmentation." A Deployment Manager node is eligible foraugmentation, application server nodes are not (with one exception, which we cover under"Stacked create of a new Standalone with Feature Pack for Web Services with immediateaugmentation of Feature Pack for EJB 3.0" starting on page 26).

Continue to the next section to read about augmenting a DMGR node.

Augmentation of an existing Deployment Manager node

Deployment Managers are eligible for augmentation (or "update"). This involves the configuration ofa single job that runs against the configuration of the DMGR and links it to the feature pack.

For a DMGR to support a node with a feature pack, that feature pack must also beinstalled in the DMGR.

Key Point:

For the Feature Pack for EJB 3.0 the DMGR must be at a level of 6.1.0.13 or higher.

Important Note

The DMGR to be augmented must be built using the "z/OS Deployment Manager" option of thezPMT and not the "z/OS cell (deployment manager and application server)" option.Augmentation fails if the DMGR was built using the "cell" option.


This is the exact same picture we showed back on page 16. We are illustrating theaugmentation of the FZCELL DMGR assuming it had been built without the feature pack.






/FPEJB3

/FPWS


/fzdmnode_wassmpe

/fzdmnode_fpws

/fzdmnode_fpejb3

D/fzdmnode

A

B

C

E

F


FZCELL DMGR node

As you'll see, in the zPMT configuration panels for the augmentation job, it's going to ask for thelocation of both the product HFS and the feature pack HFS. We'll supply the intermediatesymbolic links for both: /fzdmnode_wassmpe for the product HFS (block E), and

/fzdmnode_fpejb3 for the Feature Pack for EJB 3.0 (block F).

Step-by-step illustration of the augmentation of the FZCELL DMGR

� Started Application Server Toolkit




� Over on the right side clicked on the "Augment" button


� For the "Environment Selection" panel highlight the type of node to be augmented --Deployment Manager in this example -- and clicked "Next."

Next

� For the "Augment Selection" panel highlight the type of feature pack to be augmented -- theFeature Pack for EJB 3.0 in this example -- and clicked "Next."

Next

� For the "Customization Name and Location" panel provide a name for the augmentationdefinition. This is no different from what you'd do for any zPMT customization ... it's just aname that will be displayed in the zPMT so you can identify the definition more easily. Click"Next" when ready.

� For the "Target Data Sets" panel provide the high-level qualifier for the data set on the z/OSsystem that will be used when the augmentation job is uploaded.




� The zPMT panel used to specify the location of the node and the product files is next:

Next

1

2

3

Notes:

1. This is the location of the node to be augmented. What's shown above is the root directory ofthe FZCELL Deployment Manager.

2. This field is asking for where the feature pack -- EJB 3.0 in this example -- is installed. Youcould point directly at the actual mount point, or you could employ intermediate symbolic links.The example above illustrates the intermediate symbolic links. Back on page 19 weillustrated the intermediate symbolic links we used for our environment. For this field we usedthe intermediate symbolic link for the Feature Pack for EJB 3.0, which was block F in thepicture on page 19.

3. This field is asking for the location of the WebSphere z/OS product code. Again, you couldpoint directly at the actual mount point. Here we show the use of intermediate symbolic links.

The link shown here is block E from the picture on page 19.

� The next panel asks for the JOB card information. The authority of the ID under which thisjob runs is important. The instructions for the IWOFAUGD job calls for the following:

A. An ID with either UID=0 authority or one that has been granted the appropriate UNIXPRIV

access. See "Granting necessary UNIXPRIV privileges to ID" on page 36 for how to grant anID access to the UNIXPRIV classes so it can run the job without needing full UID=0.

B. The ID should be connected to the cell's "Configuration Group ID" if the cell is using aLocalOS (SAF) user registry.

C. The instructions also say:

"If SSL certificates are stored in the SAF keyrings, then the user ID used to run this job musthave a SAF keyring whose name matches the value of com.ibm.ssl.keyStore in the

/<mount>/DeploymentManager/profiles/default/properties/ssl.client.props

file, and this keyring must contain the deployment manager's CA certificate."

The WebSphere Admin ID -- if one was created at the time of cell creation -- will haveitems B and C by default. You can grant that ID UNIXPRIV and be set. But use propercaution with that ID if augmented with UNIVPRIV, particularly if that ID is shared amongmultiple users.

Note:




� On the "Customization Summary" panel we clicked "Augment." That told the zPMT togenerate the augmentation job.

� Finally, on the "Definition Summary" panel we clicked "Finish."

Uploading and running the job to augment the DMGR

� The customized job for augmentation is uploaded using the exact same process as used forany zPMT definition -- with the "Upload" button.

� On the z/OS side we saw that the hlq.CNTL data set had only one job -- IWOFAUGD.

� We stopped the Deployment Manager server.

The servers in the node must be stopped when running the augmentation job. Fora Deployment Manager node that implies one server -- the DMGR itself.

Important:

� We submitted the IWOFAUGD job. It has three steps. All three came back with RC=0. The

node was augmented with the Feature Pack for EJB 3.0.

� The DMGR was restarted.

Quick visual verification of Feature Pack EJB 3.0 being included in DMGR

� In the Administrative Console go to System Administration � Nodes

� Take a look at the "Version" information for the node:


Adding other feature packs to this Deployment Manager

We just illustrated the augmentation of a DMGR with the Feature Pack for EJB 3.0. Let's sayyou wanted to add Feature Pack for Web Servics as well. The process would be exactly thesame, except you'd pick the Web Services feature pack on the "Augment Selection" panel.

Because Deployment Managers are eligible for augmentation, you can add featurepack after feature pack to them. You do this through augmentation, like we justillustrated.

Application server nodes are different. They are generally not eligible foraugmentation by feature packs. There is an exception, and that is what we'll beginillustrating next.

Key Point:

Stacked create of a new Standalone Server node

This is very similar to the sacked create of the DMGR (page 16). The difference is we're creating aStandalone Server rather than a DMGR.

The reason why you'd do this is because existing federated nodes can't be augmented with afeature pack. This means if you have a existing cell and you want to incorporate the featurepack functionality, it's likely going to mean doing a "Stacked Create" of a Standalone, thenfederating that into the DMGR cell.

See "Including the feature pack into existing cells" on page 27 for more on this.

Note:





The symlinks for this node are different from the symlinks we used before for the DeploymentManager. We have found that having separate symbolic links for each node is what providesthe maximum flexibility.

But the concept is the same, and the actual SMP/E mount points are the same. Theintermediate symbolic links themseves are what's different:



/FPEJB3

/FPWS


/fznodec_wassmpe

/fznodec_fpws

/fznodec_fpejb3

D/fznodec

A

B

C

E

F


FZCELL node on SYSC

Notes:

A. The actual mount point for the WebSphere Application Server for z/OS SMP/E HFS(hlq.SBBOHFS).

B. The actual mount point for the WebSphere Application Server for z/OS "Optional Materials"feature (FMID=JIWO610 ... this was the hlq.SIWOHFS data set).

C. When we installed the the Feature Pack for Web Services and the Feature Pack for EJB 3.0PTFs, these directories were created to hold those files and folders.

D. The directory /wasv61config/fzcell/fznodec was where we planned on mounting the

configuration HFS for the Standalone we were building.

E. This is the first of three intermediate symbolic links. This one pointed to the actual mount point of

the WebSphere Appserver (FMID=H28W610) SMP/E HFS -- or block A in the picture. In the

zPMT we pointed to this intermediate symbolic link whenever it asked for the location of theWebSphere product code.

F. The second of three intermediate symbolic links. This one pointed to where the Feature Pack for

EJB 3.0 code was installed. This was the directory /FPEJB3 under block B in the picture. In the

zPMT we pointed to this intermediate symbolic link whenever it asked for the location of theFeature Pack for EJB 3.0 code

G. The third of three intermediate symbolic links. This one pointed to where the Feature Pack for

Web Services code was installed. This was the directory /FPWS under block B in the picture. In

the zPMT we pointed to this intermediate symbolic link whenever it asked for the location of theFPWS code.

Step-by-step illustration of stacked create for the FZCELL standalone server

Follow along and see how you can do it using your copy of the Application Server Toolkit.

� Started Application Server Toolkit




� Over on the right side clicked on the "Create" button


� Selected the "Feature Pack for EJB 3.0" option and clicked "Next."




Next

This is the key to creating a "Stacked Create" -- select the feature pack first, then (asyou'll see) you select the configuration type next.

Note:

� The next panel presented the only two options for a "Stacked Create" that exist: DMGR orApplication Server. We picked Application Server and clicked "Next."

Next

From that point the process was nearly identical to how a non-stacked Standalone wouldbe done (with one exception, which we'll show). For the sake of illustrating theintermediate symbolic links we'll show a few of the panels related to that as well.

Note:

� On the panel where the configuration HFS information is specified there is also a placewhere it asks for the "Product File System." That mean the location of the WebSphere z/OSSMP/E product HFS. Back on page 23 we provided a picture of the intermediate symlinkswe created for this node. We entered the intermediate symlink for the product HFS here:

� After the "Web Server Definition" panel a new panel was presented, this one asking forinformation about where the Feature Pack for EJB 3.0 code was located:




Intermediate symbolic link for the FPEJB3 code

See "A picture illustrating the intermediate symbolic links" on page 23 for an illustrationof the intermediate symbolic links we used.

Note:

� From there on it was the exact same set of panels to finish up the definition and completethe generation of the jobs.

Uploading and running the jobs to create the stacked DMGR

The process of uploading the jobs for the "Stacked Create" definition is exactly the same as itwould be for any other configuration definition created by zPMT.

It turns out the jobs to be run are the same as you would run for any Standalone Server node.There is no new or additional job in a "Stacked Create" that does the Feature Pack stuff. Thatprocess is buried in one of the existing jobs.

Once you've created the "Stacked Create" definition, the rest of the process -- uploadthe jobs and run them -- is the same.

Key Point:




Start the Standalone or not?

It depends on what you're looking to do with the Standalone Server:

� Go ahead and start the Standalone as you would normally.... you intend to leave the server as aStandalone, with no immediate plansto federate

� Do not start the server� See "Stacked create of a new Standalone with Feature

Pack for Web Services with immediate augmentation ofFeature Pack for EJB 3.0" starting on page 26

... you've stack created theStandalone with the FPWS and nowyou wish to augment with FPEJB

� Start the Standalone once. Federation requires that aStandalone be started at least once before federation canoccur.

� Make sure the DMGR node has been augmented with thesame feature pack.

� Federate the Standalone into the DMGR. See"Federation of a Standalone with feature packs into aDMGR that's been augmented" on page 27.

... the next step is to federate thenode into a DMGR cell

Then ...If ...

Adding other feature packs to this Standalone Server

May be possible, depending on the state of the Standalone:

No further augmentation permitted.Standalone federated into DMGR cell

Augment with Feature Pack for EJB 3.0 providedthe server has never been started

Plain Standalone without any feature packs

No further augmentation. Feature Pack for WebServices can't be augmented to an applicationserver node.

Stack created with Feature Pack for EJB 3.0

Augment with Feature Pack EJB 3.0 provided theserver has never been started

Stack created with Feature Pack Web Services

OptionsState

Quick visual verification of Feature Pack for EJB 3.0 being included in Standalone Server

� In the Administrative Console go to Servers � Application Servers

� Take a look at the "Version" information for the server:


Stacked create of a new Standalone with Feature Pack for Web Services with immediateaugmentation of Feature Pack for EJB 3.0

This is really a two-step process:

1. Use the zPMT to create the jobs to perform a "Stacked Create" of a Standalone Server with theFeature Pack for Web Services. The process would be nearly identical to what we illustrated under




"Stacked create of a new Standalone Server node" starting on page 22. The difference being thatyou'd select the Feature Pack for Web Services option rather than Feature Pack for EJB 3.0. Andyou'd point to the web services code rather than the EJB 3.0 code. Everything else would be thesame.

2. Use the zPMT to create an augmentation job to augment the newly created Standalone Server withthe Feature Pack for EJB 3.0. The process would be nearly identical to what we illustrated under"Augmentation of an existing Deployment Manager node" starting on page 19. The difference beingthat you'd point to the Standalone Server directory rather than the DMGR directory.

That's it ... create a stacked Standalone with Feature Pack for Web Services, then immediatelyaugment with Feature Pack for EJB 3.0. When that's done the Standalone Server will have bothfeature packs included. You may then federate the Standalone into the DMGR. Be sure the DMGRhas been augmented with both feature packs as well, otherwise the federation will fail.

Federation of a Standalone with feature packs into a DMGR that's been augmented

The federation of a Standalone Server into a Deployment Manager is really the same with thefeature packs as it is without the feature packs. Federation is not itself affected by the presence ofthe feature packs ... provided you live by this one basic rule:

For a Deployment Manager to accept a node in federation it must have all the featurespacks the node being federated has.

Basic Rule:

For example:

� Imagine a Standalone Server that was built to include the Feature Pack for EJB 3.0 code. Youwish to now federate that into a Deployment Manager cell. That DMGR must also have theFeature Pack for EJB 3.0 code included in its configuration.

� Imagine two different Standalone Servers -- one with Feature Pack for Web Services and theother with Feature Pack for EJB 3.0. Both will be federated into a DMGR. That DMGR musthave both feature packs included in its configuration.

There's a possible concern about different levels of the feature pack code in the DMGR versusthe node being federated. If both are linked to the same set of shared SMP/E install code (asmight be the case for a cell on an LPAR or in a Sysplex), then the concern is minimal. But if thecell spans different platforms or Sysplexes, then it's possible the levels might be different.

Rules of thumb: � Try to keep the levels the same. � If that's not possible, try to make sure the DMGR is at a higher level than any federated node� If having different levels can't be avoided, try to keep the difference between the levels to be

as close as possible.

Note:

If the DMGR doesn't contain all the same feature packs that the node being federated has, then thefederation itself will fail.

Including the feature pack into existing cells

If you have an existing cell that's hosting applications and you want to incorporate feature packs intoit, there are some things you must keep in mind. First and foremost is this: augmenting an existingapplication server node is not permitted. Augmenting a Deployment Manager node is permitted, butaugmenting a federated application server node is not.

If you have an existing cell that you wish to incorporate feature pack functionality, you have twoapproaches you can take. Those two approaches are covered next.

Create and federate a new node

This approach involves the creation of a new node that will run in parallel with the other nodes ofyour cell. The following picture illustrates this:




CR

Daemon

CR SR

DMGR

Node

CR

Node Agnt

Node A

CR SR

AppSvr

CR SR

AppSvr

MVS System Image A

CR

Daemon

CR

Node Agnt

Node B

CR SR

AppSvr

MVS System Image B

Cell

CR

Node Agnt

Node AA

CR SR

AppSvr

zPMT

"Stacked create" with the Feature Pack functionality

Node AA

Build and federate

Several notes about this approach:

� The Deployment Manager will need to be augmented with the feature pack prior to the federationof the node with the feature pack. That's true in all cases, not just this scenario.

� Two nodes in a cell on the same LPAR is something our standard naming convention doesn'treally account for. It's technically possible to do this, but the naming convention doesn't take intoaccount the possibility of two or more application server nodes on a given MVS image. It wouldbe necessary to tweak the standard naming convention to accomodate this.

� You'd have to be sure not to overlap ports or names with any nodes or servers that already exist.

Replace an existing node with a new node created with the feature pack

This approach seeks to avoid the issue of two nodes on an MVS image by replacing a node withone built with the feature pack. This is a somewhat "brute force" approach since it involves theunfederation and disposal of a node and the recreation and refederation of it:




CR

Daemon

CR SR

DMGR

Node

CR

Node Agnt

Node A

CR SR

AppSvr

CR SR

AppSvr

MVS System Image A

CR

Daemon

MVS System Image B

Cell

CR

Node Agnt

Node B

CR SR

AppSvrzPMT

Built with Feature Pack for Web Services function included

Build and federate

CR

Node Agnt

Node B

CR SR

AppSvr

Unfederate and discard

1

2

You should not attempt to unfederate and then augment that node.Note:

Notes about this approach:

� Anything that's in that node would lost, of course. This includes any applications that weredeployed there, as well as any servers beyond the initial one, and any customization that hadbeen done to the settings of that node.

� You would not need to re-run the SAF jobs (the BRAJ and BRAK jobs) from when you originallycreated the node. Unfederating and deleting the node does not delete the SAF profiles. Providedthe new node uses the same naming convention and same JCL start procedures, you can re-usethe SAF profiles.

� This approach is easier to accomplish if you had maintained the customization variables frombefore -- either the SAVECFG from the ISPF panels or the configuration definition within thezPMT. You could re-use the same definitions to rebuild the node, but this time "stacking" it withthe feature pack.




Verifying the Feature Pack

There are two basic ways you can verify the inclusion of the Feature Pack to a node:

1. Visual -- see what the Administrative Console indicates for the node

2. Programmatic -- deploy an application that makes use of EJB 3.0 and insure that it works

Visual verification of feature pack inclusion

� In the Administrative Console go to:

System Administration � Nodes

� The level and features for each node will be displayed:

Reports the level of each node as well as the feature

packs that are present. In this example, the EJB 3.0 feature pack is present but the Web Services feature pack is not.

Programmatic verification of feature pack inclusion

The Feature Pack for EJB 3.0 comes with a very simple sample application that includes a statelessEJB 3.0 counter bean. Deploying that application and verifying its operation verifies the EJB 3.0support available to the server (and thus the node).

The application is called EJBCounterSample and is located in the /installableApps directory of theSMP/E HFS for the feature pack:

/usr/lpp/zWebSphere_OM/V6R1/FPEJB3/installableApps/EJB3CounterSample.ear

Installing the sample application

� In the Administrative Console, go to Applications � Install New Application

� Select the radio button for "Remote file system" and supply in the input field the location andear file name for the sample application. Example:

/usr/lpp/zWebSphere_OM/V6R1/FPEJB3/installableApps/EJB3CounterSample.ear

� Install as you would any application. Install into an application server that is part of a nodethat has the EJB 3.0 feature pack. You may take all the other defaults

� Save and synchronize.

� Start the application.

Invoking the sample application

� From a browser, issue the URL that invokes this application:

http://host:port/ejb3sample/counter

where host:port refers to the server in which the application has been deployed.




� You should get a response that looks like this:

This button invokes the EJB 3.0 counter bean

This field reports the number of times bean

has been invoked

� Click the "Increment" button and observe the count value go up each time.

� Go to the SYSPRINT of the application server servant region and observe the followingmessage:

JPACounterEntity:getValue = xx

where "xx" is the counter value.

What happens if you deploy an EJB 3.0 application into a node without EJB 3.0 support?

It won't deploy. A validation routine of WebSphere will check the application specificationsagainst the support offered by the target server. If the application has EJB 3.0 components andthe application server does not have the EJB 3.0 feature pack, you will see this at deploymenttime:

ADMA5055E: Errors in validating application target association for EJB3CounterSample

ADMA0110E: This type of J2EE application is not supported on nodes <node> of version 6




Miscellaneous Information

EJB 3.0 update to Application Server Toolkit 6.1.1.4

There will be a short window of time between the release of the EJB 3.0 Feature Pack and therelease of the Application Server Toolkit 6.1.1.5 product. During that time there will be available anupdate to Application Server Toolkit 6.1.1.4 that will enable the tool to support the EJB 3.0 FeaturePack. The following picture illustrates the issue:

Release of Feature Pack for EJB 3.0

Nov 30, 2007

Release of Application Server Toolkit 6.1.1.5

Dec 12, 2007

Pre-release beta and internal-IBM only

Toolkit 6.1.1.4 + Update for EJB 3.0

Toolkit 6.1.1.5

Our focus in this section is that gray portion -- Application Server Toolkit 6.1.1.4 + Update for EJB3.0. That update is officially called "IBM WebSphere Application Server Toolkit v6.1.1.4 -- zPMTUpdate for Feature Pack for EJB 3.0".

If you're reading this document at some point after December 12, 2007 (the release date ofApplication Server Toolkit 6.1.1.5), you might consider going with that level of the toolkit, which hasthe Feature Pack for EJB 3.0 function included.

The EJB 3.0 update to 6.1.1.4 will likely be available even after the release of Application ServerToolkit 6.1.1.5.

Note:

If you're in that gray area, or you have 6.1.1.4 and wish to update rather than go to 6.1.1.5, thenthere are two ways to apply the update:

1. Using Rational Product Updater to locate and apply the "remote" update2. Downloading the update ZIP file from a website and using Rational Product Updater to apply the

update "locally"

You should try the first method initially. If that works, then you're finished. But if you find thatRational Product Updater has trouble getting past firewalls, then use the second method.

Step 1 - Get to Application Server Toolkit 6.1.1.4

You must be at level 6.1.1.0 before you can upgrade to 6.1.1.4. You can't go from alevel such as 6.1.0.x and update to 6.1.1.x. You must uninstall the 6.1.0.x product andinstall new the 6.1.1.0 product. Then update.

See "Installing Application Server Toolkit 6.1.1 before upgrading to 6.1.1.5" on page 10for instructions on how to get to 6.1.1.x.

Important!

Once you're at a level of at least 6.1.1.x, then you can update to 6.1.1.4 in one of two ways:

1. Using Rational Product Updater

See "Upgrading to 6.1.1.5 using Rational Product Updater" on page 12 for instructions on how thisis done. Substitute 6.1.1.4 for 6.1.1.5 in the instructions.

If when using Rational Product Updater you see the 6.1.1.5 product as available forupdate, go to that rather than going to 6.1.1.4 and then applying the EJB 3.0 update.The Application Server Toolkit 6.1.1.5 product has the EJB 3.0 function included. So ifyou see 6.1.1.5, go with that.

Note:




2. Downloading the update ZIP file and updating locally

See "Using Rational Product Updater with a local copy of the update files" on page 13 forinstruction on how this is done. Substitute "6114" for "6115" in the instructions to get the 6.1.1.4level of update.

Try 6115 first and see if it's there. If so, then go straight to 6.1.1.5 and bypass the6.1.1.4+update solution.

Note:

Once you're at 6.1.1.4, then proceed. If you saw 6.1.1.5 and updated to that, then skip the restof this section because with 6.1.1.5 you have the EJB 3.0 function in the zPMT and you're readyto go.

Apply the update for EJB 3.0 to Application Server Toolkit 6.1.1.4

As we said, there are two ways you can go about this. Choose one of the two. We recommendyou try the Rational Product Updater method first. If firewalls block your access, try thedownload method.

Using Rational Product Updater to apply EJB 3.0 update to Toolkit 6.1.1.4



� Click on the "Installed Products" tab. This will display what you have installed right now.It should look something like this:

� Click on the "Find Updates" button. The Application Server Toolkit will make contactwith the website and search for updates eligible for your copy of the toolkit. When it isfinished it'll report back what updates are available. You should see "IBM WebSphereApplication Server Toolkit v6.1.1.4 -- zPMT Update for Feature Pack for EJB 3.0" in thelist of available updates,

� Make sure that update is checked.

� Click "Install Updates"

� Accept the terms of the license and click on "OK"

� The updater will show a progress bar. This process takes some time so be patient:

� When it is done the Rational Product Updater will show no other updates, and you'll seethe "Updates successfully installed" messsage.

� Click on the "Installed Products" tab to verify that the EJB 3.0 update to 6.1.1.4 isinstalled.

� Close the Rational Product Updater.

Downloading update ZIP file and applying locally

� Go to this website:





� Download the fix pack from the Download package section of this document.

� Extract the fix pack to a temporary directory. For example: c:\temp

� Now go to Start � All Programs � IBM WebSphere �


� When Rational Product Updater opens, select Preferences � Update Sites.

� Use the "Browse" button drill down into where you unzipped the downloaded ZIP file

� Locate the policy.xml file and select that, then click the "Open" button

� Click on "OK". You just told Rational Product Updater where to look for updates. It'll"go" to that local folder structure rather than out to the web.

When you're done, don't forget to clear this setting ... otherwise it'll keep going therefor all future updates.

Note:

� Click on the "Find Updates" button. Rational Product Updater will very quickly searchthrough your "local site" and see only one update, which is the update for EJB 3.0 on topof 6.1.1.4

� Once it's done that, click on "Install Updates". It'll then start updating Application ServerToolkit 6.1.1.4 to include the EJB 3.0 code.

� When it has completed, close Rational Product Updater.

A note about intermediate symbolic links

A WebSphere Application Server for z/OS node has a configuration file structure (or "HFS" as manypeople say, but it could also be a ZFS) that contains hundreds of folders and files. It also hasthousands of symbolic links that point to the actual product code maintained by SMP/E. Theproduct is designed this way so each node doesn't have to have a full copy of every product file ...rather, a symbolic link is created in the node's configuration to simply point to the actual file.

Several years ago we discovered that the use of "intermediate symbolic links" was helpful tomaintain the most flexibility and isolation between nodes. As a quick reminder, an intermediatesymbolic link is nothing more than symbolic link that sits between the node's configuration and theactual SMP/E file:

Node Configuration

HFS

/bin/file.sh

(Really a symlink)

/intermediate/symlink

Product SMP/E HFS

/bin/file.sh

(The actual file)

The full value of this is spelled out in the WP100396 white paper on the IBM Techdocs website:

http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP100396

If you're responsible for designing and maintaining a WebSphere z/OS cell and you're notfamilar with the concept of "intermediate symbolic links," then you should invest some time andread WP100396. The concept explained there is fundamentally important to aneasy-to-maintain cell.

Note:

We bring this up because the linkage between the node's configuration and the Feature Pack filesalso involves symbolic links. And the same concepts apply -- intermediate symbolic links provide apoint where a node can be moved to new maintenance independent of other nodes.




When planning the inclusion of Feature Pack code into a node, give serious considerationto the use of "intermediate symbolic links" between the node and the feature pack code inthe SMP/E HFS for JIWO610.

Key Point:

The illustrations we provided under "Configuring and Running the Jobs that Add the Feature Pack toa Node" starting on page 16 showed the use of intermediate symbolic links.

A note about maintenance

To introduce this topic, let's again look at a picture that illustrates the relationship of the differentFMIDs and the features packs:

/usr/lpp

/zWebSphere

/V6R1

/zWebSphere_OM

/V6R1

/FPWS

/FPEJB3

/HTTP

Feature Pack for Web Services

IBM HTTP Server Powered by Apache

Feature Pack for EJB 3.0

/xxx

/yyyFuture feature packs

FMID = H28W610This is the WebSphere Application Server for z/OS product.

FMID = JIWO610This is the WebSphere Application Server for z/OS "Optional Materials" product.

Features packs are included in the "Optional

Materials" product.

We have different maintenance streams at work here:

� One for the H28W610 product

� One for each of the features packs in the JIWO610 product

The feature packs maintenance stream will consist of an initial install support PTF and thensubsequent maintenance PTFs as needed. This is done to give people the flexibility toinstall the features they need and not install those they don't need.

Note:

There a relationship between the level of WebSphere Application Server (H28W610) and the levelof the feature packs included in the node. The basic issues are these: the service level of a featurepack can't be higher than the level of WebSphere Application Server in the node supporting it, andthe level of the WebSphere Application Server can't get too far out front of the level of the featurepacks.

So the plan is this:

� Each feature pack service level will contain SMP/E logic to require that WebSphere ApplicationServer (FMID H28W610) be upgraded to the new feature pack level if its not already there.




� Each WebSphere Application Server service level will have an action hold telling the customerto upgrade any feature packs in the same zone to the new WAS service level.

There's a couple of conditions to be aware of:

� If a Deployment Manager node is at a level of WebSphere that's more than one maintenancelevel higher than the feature pack being augmented, the augmentation job will fail. There'll be arather clear message in the failed job telling you exactly that.

� The applyPTF.sh postinstaller process will not allow a server to start if it sees the level of

WebSphere and the level of any referenced feature packs as being more than one leveldifference. By "referenced" we mean the node has that feature pack included.

You can see what feature packs are included in a node and what level they're at by going toSystem Administration � Nodes in the Administrative Console.

As a general rule, maintain the same maintenance level for H28W610 (WebSphere

Application Server) and any feature packs that are part of JIWO610 (the Optional

Materials). There's some flexibilty that allows the feature packs to be one level behindWAS. But in general, keeping WAS and the feature packs aligned in their maintenance isa good practice.

Key Point:

Granting necessary UNIXPRIV privileges to ID

WebSphere Application Server for z/OS documents a way to have an ID other than a UID=0 ID runthe customization jobs. In the past a UID=0 ID was suggested because it was guaranteed to havethe needed authority to create directories, and issue the chown and chmod commands. But many

people, very reasonably, requested information on how to give an ID just enough authority withouthaving it be a full UID=0 ID. What follows are the commands that are needed to grant theUNIXPRIV authorities that would give it just enough:

PERMIT SUPERUSER.FILESYS CLASS(UNIXPRIV) ID(adminid) ACC(CONTROL)PERMIT SUPERUSER.FILESYS.MOUNT CLASS(UNIXPRIV) ID(adminid) ACC(UPDATE)PERMIT SUPERUSER.FILESYS.CHOWN CLASS(UNIXPRIV) ID(adminid) ACC(READ)PERMIT SUPERUSER.FILESYS.CHANGEPERMS CLASS(UNIXPRIV) ID(adminid) ACC(READ)PERMIT SUPERUSER.FILESYS.PFSCTL CLASS(UNIXPRIV) ID(adminid) ACC(READ)SETROPTS RACLIST(UNIXPRIV) REFRESH

If you wish, you may continue to use a UID=0 ID.




Document Change History

Check the date in the footer of the document for the version of the document.

Note added regarding which option of zPMT used to create DMGR. Augmentationwon't work if DMGR created with the zPMT "cell" options (DMGR + federatedapplication server node in one set of jobs). The DMGR must be built using only the"Deployment Manager" option. See "Important Note" on page 19.

June 10, 2008

Minor update providing the new official name of the update to Application Server Toolkit6.1.1.4 to provide the Feature Pack for EJB 3.0 function.

December 04, 2007

Updated the document with minor corrections for spelling, grammar and improperacronym usage.

November 29, 2007

Original document.November 26, 2007

End of WP101142




word pro - wp101142 - feature pack for ejb3 · overview of feature packs and the ejb 3.0 feature...

Documents