WSADMIN Scripting Primer
 White paper
 
Abstract
IBM® WebSphere® Application Server V5.0 has a scripting interface called "WSADMIN." That interface is common across all platforms. The Information Center has a wealth of very good examples, but unless you know something about WSADMIN those examples can be difficult to approach. This white paper offers an introduction to WSADMIN, and it does it in the form of a "primer." Simple step-by-step exercises are given that will guide you from the most simple WSADMIN tasks up to some fairly complex things.

Note: this version of the document is a "preliminary release." Future updates may include additional examples of WSADMIN scripts. This is being supplied as a "preliminary release" so important information on using WSADMIN is made available as soon as possible.
 
 
Content

WSADMIN Scripting Primer
Preliminary Release
-- document not yet indexed.
Look for update in future with index.

This document can be found on the webat: http://www.ibm.com/support/techdocs.
Search for document number WP100421 under the category of "White Papers".

The complete document is attached below, but can also be found at:
http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101014

Version Date
: Sat, Aug 27, 2005


Table of Contents

Summary Overview
5
Why this document was written
5
What this document is intended to provide -- and not provide
5
How this document is designed
5
The z/OS® focus of this document
5
Where reference documentation is available
5
Introduction to WSADMIN
6
What WSADMIN is not
6
If you have configured a Application Server for z/OS cell, you have used WSADMIN
7
The wsadmin.sh shell script
7
Two ways to use WSADMIN -- interactive and batch
7
Invoking the wsadmin.sh shell script from OMVS, Telnet, or JCL
8
A fourth way to invoke WSADMIN -- on another platform
9
Important: run wsadmin.sh under authority of Application Server Administrator ID
9
Connecting to server process port, or operating in "local mode"
9
When should one use "local mode" versus "remote mode"?
10
If connecting, which server process should we connect to?
11
If we operate in local mode (no connection), what config HFS do we act against?
12
Important: Do NOT use WSADMIN and Administrative Console at the same time
12
Using a scripting language
13
Learning challenges
13
Lesson 1: Starting Client and Exploring Commands
14
Access command line interface
14
Invoke "Help" facility of WSADMIN
14
Start WSADMIN client interface with -conntype of NONE
15
List the applications installed in this cell
16
Exiting the WSADMIN interactive client
17
Concluding points on this lesson
17
Lesson 2: Invoking WSADMIN in Batch Mode
18
WSADMIN commands that follow the invocation of the shell script
18
WSADMIN commands held in a separate file
19
Important point: WSADMIN by default expects files to be in ASCII
19
Create HFS file and enter commands
19
Intentionally create error where EBCDIC used when WSADMIN expects ASCII
20
Use -javaoption switch to indicate source is in EBCDIC
20
WSADMIN commands inside JCL
20
A look inside the BBODIAPP job
21
Question: why no -javaoption in JCL to say commands are in EBCDIC?
22
Copy BBODIAPP job and modify it to do something simpler at this point
22
Pointing to an external file from a JCL batch job
23
Concluding points on this lesson
24
Lesson 3: Introduction to Jacl scripting
25
Getting ready
25
Simple setting of variable and putting variable back to screen
25
What happened in that last exercise?
26
Setting multiple variables
26
Parsing words out of a string
27
Passing values in as parameters
27
Using If-Else to validate the number of parameters passed in
28
Jacl lists -- an important way of providing options to WSADMIN commands
30
Using Jacl variables to break up long command lines
30
Jacl "list" function to the rescue
31
Variable substitution into "list" function
31
Nested options -- option lists inside and option list
32
Concluding points on this lesson
34
Lesson 4: Installing an Application using $AdminApp Object
35
To connect to a server process or not ... that is the question
35
Which server process to connect to?
35
If -conntype none used, does it matter which copy of wsadmin.sh used?
36
Important note concerning server security if enabled
36
Simple install with minimum options
36
Preliminary activities to ready your environment for exercise
36
Invoke "help" to understand the $AdminApp object better
37
Install MyIVT using a simple script file
40
Uninstall MyIVT
41
Determining what task options are applicable to MyIVT.ear
41
Finding out more about a particular task option
41
Installing MyIVT.ear and mapping to a different Virtual Host
43
Uninstall application in preparation for next exercise
44
Using Jacl variables to construct the long command line
44
Jacl script that installs or uninstalls based on passed in parameter
45
Concluding points on this lesson
47
Lesson 5: The $AdminConfig Object
48
A little background on $AdminConfig
48
What methods are on this object?
48
How many different "configuration types" exist?
48
Does $AdminConfig require a connection to a server process?
49
Caution: z/OS is different type of environment from distributed
49
Synchronizing changes with nodes
49
Node synchronization overview
49
Initiating synchronization using WSADMIN
50
Programmatically synchronizing with every node in the cell
51
Node Agent configuration settings that affect synchronization intervals
51
Exploring the VirtualHost type
52
How can we know that VirtualHost is a type?
52
What is the structure of the VirtualHost type?
53
What is the value in what we just did?
54
What is the minimum required to construct a VirtualHost configuration type?
55
Using WSADMIN to create a simple, no-alias Virtual Host
55
Determining the ID of the cell to provide as the "parent" for the create method
55
Jacl script to get the cell ID, then create no-alias virtual host
56
Listing the existing VirtualHost types (including your new one)
56
Using WSADMIN to determine the values assigned to an existing virtual host
57
Using the getid method to place the config ID of default_host into a Jacl variable
58
Using the show method to display all the attributes held by the configuration object
59
Using the showAttribute method to display a certain kind of attribute
59
Using the show and showAttribute methods to display contents of host alias
60
Creating a new virtual host complete with an HostName/Port alias
61
Understanding all the open and closing braces in create VirtualHost command
62
Jacl script with hard-coded attribute list
62
Jacl script using variables to populate attribute list
63
Question: what if virtual host had multiple hostname/port pairs?
64
Using the modify method of $AdminConfig to add another alias to the virtual host
65
Changing the name of the virtual host
65
Adding additional aliases to the virtual host
66
Deleting the test virtual hosts created in this lesson
67
Jacl script to delete a virtual host
67
Question: is it possible to delete multiple objects with one command invocation
68
Creating a new server by copying from an existing server
68
Simple example without node synchronization
69
More automated example with node synchronization
69
Changing an application server's short name
70
Changing an application server's Cluster Transition Name
72
Concluding points on this lesson
73
Lesson 6: The $AdminControl Object
74
Does requiring a connection to server process limit how I might invoke $AdminControl?
74
Which server process should we connect to?
74
Starting a server in a Network Deployment configuration
75
Stopping a server in a Network Deployment configuration
76
Starting a Network Deployment server using batch JCL
76
Starting a server in a Base Application Server node configuration
77
Stopping a server in a Base Application Server node configuration
77
Checking the status of a server process
77
Starting an Application
78
Stopping an Application
78
Checking the status of an application
79
Concluding points on this lesson
79
Lesson 7: Digging Deeper into the $AdminApp Object
80
Installing a second copy of an application into a cell
80
Setting the JNDI name for an EJB
80
Where are those values to be found in the EAR file itself?
82
Constructing $AdminApp install command with change to JNDI name
83
Mapping an EJB-ref to JNDI name
83
Putting it all together -- install application, set JNDI name, map reference to EJB
84
Updating an existing application with a new copy
86
Simple update
86
Update of application and ignoring bindings in EAR file
87
Mapping an application to a data resource
87
Format of MapResRefToEJB
88
Example Jacl script that installs application and maps resource reference
89
Concluding points on this lesson
89
Lesson 8: WSADMIN and Clusters
90
What clusters are in your environment?
90
What servers are members of that cluster?
90
What nodes are those cluster members configured?
90
Installing an application into a cluster
91
Manually synchronizing with each known node of the cluster
91
Programmatically synchronizing every node
91
Programmatically synchronizing to just the cluster nodes
91
Starting the members of a cluster
92
Stopping the members of a cluster
93
Checking the status of the cluster and cluster members
93
Appendix A: Exercises (available for copy-and-paste)
94
Lesson 2 Exercises
94
Lesson 3 Exercises
95
Lesson 4 Exercises
95
Lesson 5 Exercises
96
Lesson 6 Exercises
100
Lesson 7 Exercises
100
Lesson 8 Exercises
102
More Information
104
Tracing WSADMIN activites
104
Turning tracing on or off
104
Changing location of trace output
104
Dynamically turning tracing on or off
105
Tracing when WSADMIN client running on a distributed platform
105
When Global Security is enabled
105
Authenticating the WSADMIN client to the SOAP port
105
Insuring client's ID has CA Certificate in its keyring
105
Using WSADMIN on distributed box when Global Security and SSL enabled
105
Document Change History
106
Index
107


Summary Overview
WSADMIN is a scripting interface into WebSphere Application Server that permits the automation of many different tasks. Starting with Version 5 of the product, the scripting interface is now common across all platforms: zSeries®, pSeries®, xSeries® and iSeries™.

Generally speaking, WSADMIN is most powerful when used to automate frequently executed tasks, such as installing applications. There the objective is often to remove as much potential for inconsistency from the process as possible. The user-interface for WebSphere Application Server -- the "Administrative Console" -- is a standard point-and-click web interface. It is quite powerful, but the potential is there to do things differently on environment A as compared to B.

Why this document was written
WSADMIN is a fairly complex scripting interface, and can be difficult to approach for someone with little or no knowledge of the topic. The Application Server "Information Center " web site is a rich source of WSADMIN examples, but unless someone has a working knowledge of WSADMIN, those examples can be quite intimidating.

What this document is intended to provide -- and not provide
The objective of this document is to provide a basic working knowledge of WSADMIN so that the Information Center's examples can be used to greater advantage. This document makes no attempt to be a complete reference for WSADMIN command syntax; the Information Center serves that function. Also, this exercises in this document are limited to relatively simple tasks. We believe keeping things simple will allow the primary objective to best be met: a basic working knowledge of WSADMIN.

How this document is designed
This document is designed to be a "primer." Readers are introduced to important concepts in a systematic way, and knowledge is built as the reader progresses through the document. The document provides a series of step-by-step exercises to reinforce the concepts. The document is intended to be worked through from front to back, though readers with some preliminary WSADMIN knowledge may skip ahead as they see appropriate.

Note: The exercises are provided as separate text files or, if you do not have the files, in-line in this document under "Appendix A: Exercises (available for copy-and-paste)" starting on page 94. Use Acrobat's "text selection" function to extract.


The z/OS focus of this document
As mentioned, WSADMIN is common across all platforms on which WebSphere Application Server Version 5 runs. The command syntax is essentially the same across all platforms. But the manner in which the commands are executed may differ slightly. WebSphere Application Server for z/OS also has certain characteristics unique to the platform, such as: "short name" values; server processes comprised of controller and servant; the need to coordinate MVS definitions such as RACF and WLM to the Application Server structure.

This document maintains a focus on the z/OS platform, though much of the knowledge gained on z/OS can be carried to other platforms as well.

Where reference documentation is available
The WebSphere Application Server "Information Center " is located at:
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/
index.jsp?topic=/com.ibm.websphere.zseries.doc/info/welcome_nd.html


You may then search on specific keywords, or search on "WSADMIN examples" and receive a long list of common WSADMIN tasks. Or use the navigation panel to go to:
Reference ð Scripting Interfaces


Introduction to WSADMIN
What is WSADMIN? The most basic answer to that question is this: WSADMIN is a feature of WebSphere Application Server that allows a program to do the things a human operator does when they point-and-click on the Administrative Console. So in that sense, WSADMIN is a feature that provides a way to automate administrative tasks. It does this by providing a scripting interface into the administrative function of Application Server.

Note:
It is important to understand at this point what WSADMIN is not. It is not a way to simply record and playback the mouse movements, mouse clicks and keyboard entry of someone sitting at the Administrative Console of Application Server. What the scripting interface provides is a way for another program to "connect to" WebSphere Application Server and accomplish administrative tasks by issuing commands with keywords, options and parameters. It does this by providing four Java™ "objects" -- AdminApp, AdminConfig, AdminControl and Help. Each object has a number of "methods" that may be invoked by your program (called a "script").

Understanding what all the methods are, how to code the syntax for the methods, and knowing what values to supply for the parameters is the challenge in learning WSADMIN.

The WSADMIN scripting interface is common across all the platforms on which WebSphere Application Server Version 5 runs. This is different than in Version 4, where at one point in time the distributed platforms migrated up to WSADMIN while the z/OS platform continued to use the older interface.

WSADMIN being universal across the platforms is a good thing: it allows the same script to be used in different environments. So, for example, a script written for a test environment running on z/Linux may be reused against a production z/OS server.

Same script used across different environments.

What WSADMIN is not

It is important to understand at this point what WSADMIN is not. It is not a way to simply record and playback the mouse movements, mouse clicks and keyboard entry of someone sitting at the Administrative Console of Application Server. What the scripting interface provides is a way for another program to accomplish administrative tasks by issuing commands with keywords, options and parameters.

It does this by providing four Java "objects" -- AdminApp, AdminConfig, AdminControl and Help. Each object has a number of "methods" that may be invoked by your program (called a "script"):

Four Java "objects" provided with WSADMIN; your script operates against methods on the objects
If you look at the table of contents for this document, you will see that it is organized around the first three of these objects.

If you have configured a Application Server for z/OS cell, you have used WSADMIN
Yes, you have: the BBOWIAPP batch job (for a Base Application Server node) and the BBODIAPP batch job (for a Deployment Manager) both invoked WSADMIN to install the Administrative application into the server. WSADMIN was invoked out of the JCL, and the script used to install the application was included in the JCL. We explore this under "A look inside the BBODIAPP job" on page 21.

The wsadmin.sh shell script

The way in which WSADMIN is invoked is with the wsadmin.sh shell script. In a Network Deployment configuration, you will have several different copies of that shell script in the HFS:

Ÿ in the /bin directory of the Deployment Manager
Ÿ in the /bin directory of each Node Agent
Ÿ in the /bin directory of each application server
??? Why three copies? Each of those server types -- Deployment Manager, Node Agent and application server -- is a "managed process," and WSADMIN may connect to each. By locating a copy of wsadmin.sh in the /bin directory of each server, it allows WSADMIN to have a default managed process to act upon. If you invoke wsadmin.sh in the /bin of the Deployment Manager, for example, and supply no parameters telling it to connect somewhere else, it will default and connect to the Deployment Manager. We will talk about "connecting" a bit later.

Note: WebSphere Application Server for z/OS uses a shell script, as do the UNIX® and Linux products. The xSeries product uses a batch (*.bat) file. They all accomplish the same thing.


Two ways to use WSADMIN -- interactive and batch
The difference between the two lies in how the commands are passed to WSADMIN:
Ÿ In interactive mode you have a command entry prompt. You enter the WSADMIN commands at the prompt. WSADMIN accepts the commands, processes them, then presents the command prompt again:

Entering WSADMIN commands at the wsadmin> command prompt (interactive mode)

Ÿ In batch mode you supply the commands to WSADMIN as a block of commands, either in a separate file or as a block of "inline" commands.

WSADMIN commands supplied in external file, or strung along "inline" with shell script invocation

Note: The "inline" method is what was used in the BBOWIAPP job to install the Admin application.


Interactive mode is nice when the commands being entered are relatively short, and you are not looking to save the commands for re-use later. You will see the use of interactive mode throughout this document when we are querying the "help" method of WSADMIN, and when we are doing simple things like listing out installed applications. Batch mode is nice when the commands being entered are long and complex, and when they will be used later. An example of the use of batch mode would be a set of commands that installs an application.

Invoking the wsadmin.shshell script from OMVS, Telnet, or JCL
Sitting at your computer, you have a few different ways in which you can invoke the wsadmin.sh shell script:

Three different ways to invoke wsadmin.sh

Which you use is really a matter of personal preference. In this document we most often instruct the use of the OMVS shell, but in truth a Telnet terminal would work perfectly well. Using a JCL job to invoke WSADMIN may also be used, and we illustrate that method in several places in the document.

A fourth way to invoke WSADMIN -- on another platform

WSADMIN can be instructed to connect to a running server process, and in fact we will do that quite a bit in this document. You pass in a -host and -port parameter to accomplish this. That means that WSADMIN on any server platform can connect to another server:

Invoking WSADMIN on a PC and connecting across the network to Application Server on z/OS

Note: The key point is that when WSADMIN is told to connect to a server process, that server process may be on any system on the network. But this method can get complicated, particularly when SSL will be used: it requires the coordination of keyrings on both systems. For this document we will avoid this and rely on OMVS, Telnet or JCL batch submission.


Important: run wsadmin.shunder authority of Application Server Administrator ID
The "Application Server Administrator ID" is one of the RACF IDs created when you created your Application Server configuration. It was defined in the "Security Domain" phase of configuration. The default value is WSADMIN, though your value will likely be something different.

When running the wsadmin.sh shell script, it is important to have the script run under the authority of this userid. That will give WSADMIN the proper permissions to read, write and search the configuration HFS directory.
There are two ways to run the shell script under the authority of that ID:OMVS or Telnet

Before invoking wsadmin.sh, "switch users" ( su ) to the Application Server Administrator ID. Provide the password. Then invoke wsadmin.sh JCL batch Make sure that the JOB card has the USER= and PASSWORD= values for the Application Server Administrator ID.

 
Attachment Attachment
 
 


Document Information


Current web document: swg27006561.html
Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server for z/OS > Administrative Scripting Tools (for example: wsadmin or ANT)
Operating system(s): z/OS
Software version: 6.0.2
Software edition:
Reference #: 7006561
IBM Group: Software Group
Modified date: Aug 28, 2005