Application Server Administration
Application Server Administration
Application Server Administration
Administration
©
2005 Progress Software Corporation. All rights reserved.
Progress® software products are copyrighted and all rights are reserved by Progress Software Corporation. This manual is also copyrighted and all rights are
reserved. This manual may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine-readable form without
prior consent, in writing, from Progress Software Corporation. The information in this manual is subject to change without notice, and Progress Software
Corporation assumes no responsibility for any errors that may appear in this document. The references in this manual to specific platforms supported are subject
to change.
A (and design), Allegrix, Allegrix (and design), Business Empowerment, DataDirect (and design) DataDrirect Connect, DataDirect OLE DB, DirectALert,
EdgeXtend, Empowerment Center, eXcelon, IntelliStream, O (and design), ObjectStore, OpenEdge, PeerDirect, P.I.P., POSSENET, Powered by Progress,
Progress, Progress Dynamics, Progress Empowerment Center, Progress Empowerment Program, Progress Fast Track, Progress OpenEdge, Partners in Progress,
Partners en Progress, Persistence, Persistence (and design), ProCare, Progress en Partners, Progress in Progress, Progress Profiles, Progress Results, Progress
Software Developers Network, ProtoSpeed, ProVision, SequeLink, SmartBeans, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed and Your
Software, Our Technology–Experience the Connection are registered trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the
U.S. and/or other countries. AccelEvent, A Data Center of Your Very Own, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Cache-Forward,
DataDirect, DataDirect Connect64, DataDirect Technologies, Data Direct XQuery, DataXtend, Fathom, Future Proof, ObjectCache, ObjectStore Event Engine,
ObjectStore Inspector, ObjectStore Performance Expert, ObjectStore Trading Accelerator, POSSE, ProDataSet, Progress Business Empowerment, Progress
DataXtend, Progress for Partners, Progress ObjectStore, PSE Pro, PS Select, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser,
SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, WebClient,
and Who Makes Progress are trademarks or service marks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries.
SonicMQ is a registered trademark of Sonic Software Corporation in the U.S. and other countries. Vermont Views is a registered trademark of Vermont Creative
Software in the U.S. and other countries. IBM is a registered trademark of IBM Corporation. JMX and JMX-based marks and Java and all Java-based marks are
trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other trademarks or service marks contained herein are the
property of their respective owners.
OpenEdge includes Imaging Technology copyrighted by Snowbound Software 1993-2003. www.snowbound.com.
OpenEdge includes software developed by the Apache Software Foundation (http://www.apache.org/). Copyright © 1999 The Apache Software Foundation. All
rights reserved (Xerces C++ Parser (XML) and Xerces2 Java Parser (XML)); Copyright © 1999-2002 The Apache Software Foundation. All rights reserved
(Xerces Parser (XML)); and Copyright © 2000-2003. The Apache Software Foundation. All rights reserved (Ant). The names “Apache,” “Xerces,” “ANT,” and
“Apache Software Foundation” must not be used to endorse or promote products derived from this software without prior written permission. Products derived
from this software may not be called “Apache”, nor may “Apache” appear in their name, without prior written permission of the Apache Software Foundation. For
written permission, please contact apache@apache.org. Software distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or
implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product.
OpenEdge includes software developed by Vermont Creative Software. Copyright © 1988-1991 by Vermont Creative Software.
OpenEdge includes software developed by IBM and others. Copyright © 1999, International Business Machines Corporation and others. All rights reserved.
OpenEdge includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/.
OpenEdge includes the UnixWare platform of Perl Runtime authored by Kiem-Phong Vo and David Korn. Copyright © 1991, 1996 by AT&T Labs. Permission
to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any
software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. THIS SOFTWARE IS
BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T LABS
MAKE ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS
FOR ANY PARTICULAR PURPOSE.
OpenEdge includes the RSA Data Security, Inc. MD5 Message-Digest Algorithm. Copyright ©1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.
OpenEdge includes software developed by the World Wide Web Consortium. Copyright © 1994-2002 World Wide Web Consortium, (Massachusetts Institute of
Technology, European Research Consortium for Informatics and Mathematics, Keio University). All rights reserved. This work is distributed under the W3C®
Software License [http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231] in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
OpenEdge includes code licensed from Mort Bay Consulting Pty. Ltd. The Jetty Package is Copyright © 1998 Mort Bay Consulting Pty. Ltd. (Australia) and
others.
OpenEdge includes the JMX Technology from Sun Microsystems, Inc.
OpenEdge includes software developed by the ModelObjects Group (http://www.modelobjects.com). Copyright © 2000-2001 ModelObjects Group. All rights
reserved. The name "ModelObjects" must not be used to endorse or promote products derived from this software without prior written permission. Products
derived from this software may not be called "ModelObjects", nor may "ModelObjects" appear in their name, without prior written permission. For written
permission, please contact djacobs@modelobjects.com.
OpenEdge includes files that are subject to the Netscape Public License Version 1.1 (the "License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at http://www.mozilla.org/NPL/. Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is Mozilla Communicator client code, released March 31, 1998. The Initial Developer of the Original Code is Netscape Communications
Corporation. Portions created by Netscape are Copyright © 1998-1999 Netscape Communications Corporation. All Rights Reserved.
December 2005
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preface–1
Part I Introduction
iv
Contents
v
Contents
vi
Contents
vii
Contents
viii
Contents
ix
Contents
x
Contents
16. Configuring and Managing the OpenEdge Adapter for Sonic ESB. . . . . . . . . 16–1
Introducing the OpenEdge Adapter for Sonic ESB . . . . . . . . . . . . . . . . . . . . . . . . 16–2
Installation of the OpenEdge Adapter for Sonic ESB . . . . . . . . . . . . . . . . . . . . . . 16–2
Configuring the Sonic Management Console (SMC) for OpenEdge
services manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–3
Enabling the OpenEdge service resource editor. . . . . . . . . . . . . . . . . . . 16–4
Confirming the SMC is configured properly (Optional) . . . . . . . . . . . . . . 16–5
Importing the OpenEdge service type definition (Optional). . . . . . . . . . . 16–6
Using the OpenEdge Adapter for Sonic ESB . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–8
Editing OpenEdge service properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–8
Creating an OpenEdge service instance. . . . . . . . . . . . . . . . . . . . . . . . . 16–14
Editing OpenEdge service properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–23
Exposing a service as a standard Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–23
Deploying services in the Sonic ESB environment . . . . . . . . . . . . . . . . . . . . . . . . 16–26
Deploying a service in a new Sonic ESB container . . . . . . . . . . . . . . . . 16–27
Deploying the ESB container in a new SonicMQ container . . . . . . . . . . 16–28
Security considerations for OpenEdge Adapter for Sonic ESB . . . . . . . . . . . . . . . 16–31
Part VI Appendix
xi
Contents
requestWaitTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–11
serviceFaultLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–12
serviceLoggingLevel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–12
staleO4GLObjectTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–13
waitIfBusy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–13
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index–1
xii
Contents
Figures
Figure 2–1: AppServer run-time components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–3
Figure 2–2: AppServer administration framework . . . . . . . . . . . . . . . . . . . . . . . . . . 2–12
Figure 3–1: AIA client connection information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–18
Figure 3–2: AIA configuration information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–19
Figure 5–1: WSA administration architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–3
Figure 5–2: Directory structure of the WSA as a JSE Web application . . . . . . . . . 5–7
Figure 12–1: The local DataServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–6
Figure 12–2: Remote DataServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12–7
Figure 12–3: WebSpeed configuration that supports an international Web site . . . . 12–10
Figure 14–1: The WebSpeed ASP Web Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–3
xiii
Contents
Tables
Table 2–1: AppServer run-time components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–4
Table 2–2: AppServer configuration entity names . . . . . . . . . . . . . . . . . . . . . . . . . 2–27
Table 2–3: AppServer agent status indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–36
Table 2–4: AppServer utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–40
Table 2–5: Management tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–41
Table 3–1: Qualified Web Servers and Java Servlet Engines . . . . . . . . . . . . . . . . 3–6
Table 3–2: AIA configuration entity names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–15
Table 4–1: Moving the installed sample Web application . . . . . . . . . . . . . . . . . . . . 4–2
Table 5–1: URL components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–5
Table 5–2: Sample aliases for URL components . . . . . . . . . . . . . . . . . . . . . . . . . . 5–6
Table 5–3: web.xml file items to check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–12
Table 5–4: ubroker.properties properties of a WSA instance . . . . . . . . . . . . . . . . . 5–16
Table 5–5: Statistics of a WSA instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–19
Table 6–1: Setting the WSA instance’s default Web service properties . . . . . . . . . 6–2
Table 6–2: Deployment Information That Can Be Changed . . . . . . . . . . . . . . . . . . 6–7
Table 6–3: Web service order info version 1: Example . . . . . . . . . . . . . . . . . . . . . . 6–8
Table 6–4: Web service order info version 2: Example . . . . . . . . . . . . . . . . . . . . . . 6–8
Table 6–5: File created when a Web service is deployed . . . . . . . . . . . . . . . . . . . . 6–9
Table 6–6: Statistics for a Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6–15
Table 7–1: Initial settings for JSE security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
Table 7–2: Initial settings for WSA security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–5
Table 7–3: Controlling Web service, WSDL, and administration access using
JSE security constraints 7–8
Table 7–4: Controlling Web service, WSDL, and administration access using
role names 7–9
Table 7–5: Requiring Web service user authorization for Web service, WSDL,
and administration access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–12
Table 7–6: Disabling access to Web services, WSDL, and administration . . . . . . . 7–17
Table 7–7: Setting the appAuth property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–22
Table 7–8: Setting the wsdlAuth property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–24
Table 7–9: Enabling multiple user roles for Web services, WSDL, and
administration 7–25
Table 7–10: Setting security constraints for multiple user roles on Web services,
WSDL, and administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–26
Table 7–11: Enabling Web services per user and per application . . . . . . . . . . . . . . 7–27
Table 7–12: Sample Web service security constraints by application and
role name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–27
Table 7–13: Sample Web service user roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–28
Table 7–14: Possible web.xml file for enabling Web services per user
per application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7–29
Table 8–1: WSA management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–3
Table 8–2: Web service management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 8–4
Table 9–1: Windows NT WebSpeed Messengers . . . . . . . . . . . . . . . . . . . . . . . . . 9–13
xiv
Contents
xv
Contents
Procedures
Using SMQConnect on a client example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15–5
xvi
Preface
This Preface contains the following sections:
• Purpose
• Audience
• Organization
• Typographical conventions
• OpenEdge messages
Preface
Purpose
This manual provides a central point of reference for configuring and managing the following
OpenEdge® Application Server products and OpenEdge adapters:
• OpenEdge AppServer™
• WebSpeed Messenger
All of these products and adapters share one or more of the following common features:
• Play a unique role within OpenEdge application and integration services to help you
develop and deploy applications as part of a Service Oriented Architecture (SOA).
Audience
This manual is for you if you need to configure and manage any of the OpenEdge Application
Server products and OpenEdge adapters that it features. This manual is also for you if you need
to deploy AppServer applications, WebSpeed applications, Progress 4GL applications that
include JMS messaging using SonicMQ, or if you need to deploy Progress 4GL Web services
within the OpenEdge or Sonic ESB environment. For more information on these products and
adapters, see OpenEdge Getting Started: Application and Integration Services. For most of
these products and components it is helpful to be familiar with the Progress Explorer
framework. For more information on this framework, see OpenEdge Getting Started:
Installation and Configuration.
Preface–2
Preface
Organization
Part I, Introduction
Introduces the OpenEdge server and adapter products who’s management is described in
this manual, and provides references for more information on product architecture and
usage.
Describes the components, tools, and procedures for managing an AppServer installation.
Describes the components, tools, and procedures for managing an AppServer Internet
Adapter installation.
Describes the basic features of Web Services Adapter (WSA) management and some post
installation configuration tasks.
Describes how to create and manage a WSA Web application in the context of a Java
servlet engine (JSE), how to create and manage WSA servlets in the context of a WSA
Web application, and how to create and manage corresponding WSA instances in the
context of the OpenEdge environment using the Progress Explorer framework.
Describes how to deploy and manage Progress 4GL Web services in the context of a single
WSA instance, and how to export and import Web services between WSA instances.
Describes the components of WSA security and how to create and manage common WSA
security configurations, listed for reference by alphabetical order.
Preface–3
Preface
Introduces the WSAMAN command-line utility to perform many of the WSA and Web
service management tasks that are otherwise performed using the Progress Explorer GUI.
Describes the basic requirements and procedures for configuring a WebSpeed installation
in the Windows environment.
Describes the basic requirements and procedures for configuring a WebSpeed installation
in the UNIX environment.
Describes the components of WebSpeed security and how to use them to manage secure
WebSpeed installations and applications.
Preface–4
Preface
Describes the components, tools, and procedures for managing a SonicMQ Adapter
installation to provide Java Message Service (JMS) messaging for a Progress 4GL client
of a SonicMQ JMS.
Chapter 16, “Configuring and Managing the OpenEdge Adapter for Sonic ESB”
Describes the components, tools, and procedures for managing Progress 4GL Web
services as OpenEdge services installed and enabled through the Sonic ESB Adapter on
the Sonic Enterprise Service Bus (Sonic ESB).
Describes the syntax for commands and utilities documented in this manual. If this manual
provides the primary documentation for a command or utility, the syntax for that
command or utility appears in this appendix
Preface–5
Preface
Typographical conventions
This manual uses the following typographical conventions:
Convention Description
SMALL, BOLD Small, bold capital letters indicate OpenEdge® key functions and
CAPITAL LETTERS generic keyboard keys; for example, GET and CTRL.
KEY1 KEY2 A space between key names indicates a sequential key sequence:
you press and release the first key, then press another key. For
example, ESCAPE H.
Syntax:
Period (.) All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEAT
or end with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT
colon (:) statements can end with either a period or a colon.
Preface–6
Preface
Convention Description
{} Large braces indicate the items within them are required. They are
used to simplify complex syntax diagrams.
{} Small braces are part of the Progress 4GL language. For example,
a called external procedure must use braces when referencing
arguments passed by a calling procedure.
... Ellipses indicate repetition: you can choose one or more of the
preceding items.
Syntax
FOR is one of the statements that can end with either a period or a colon, as in this example:
Syntax
Preface–7
Preface
In this example, the outer (small) brackets are part of the language, and the inner (large) brackets
denote an optional item:
Syntax
A called external procedure must use braces when referencing compile-time arguments passed
by a calling procedure, as shown in this example:
Syntax
{ &argument-name }
In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them:
Syntax
In this example, you must include two expressions, and optionally you can include more.
Multiple expressions are separated by commas:
Syntax
In this example, you must specify MESSAGE and at least one expression or SKIP [ (n) ], and
any number of additional expression or SKIP [ ( n ) ] is allowed:
Syntax
Preface–8
Preface
In this example, you must specify {include-file, then optionally any number of argument or
&argument-name = "argument-value", and then terminate with }:
Syntax
{ include-file
[ argument | &argument-name = "argument-value" ] ... }
Syntax
In this example, ASSIGN requires either one or more field entries or one record. Options
available with field or record are grouped with braces and brackets:
Syntax
Preface–9
Preface
OpenEdge messages
OpenEdge displays several types of messages to inform you of routine and unusual occurrences:
• Compile messages inform you of errors found while OpenEdge is reading and analyzing
a procedure before running it; for example, if a procedure references a table name that is
not defined in the database.
• Startup messages inform you of unusual conditions detected while OpenEdge is getting
ready to execute; for example, if you entered an invalid startup parameter.
• Continues execution, subject to the error-processing actions that you specify or that are
assumed as part of the procedure. This is the most common action taken after execution
messages.
• Returns to the Progress Procedure Editor, so you can correct an error in a procedure. This
is the usual action taken after compiler messages.
• Halts processing of a procedure and returns immediately to the Progress Procedure Editor.
This does not happen often.
OpenEdge messages end with a message number in parentheses. In this example, the message
number is 200:
If you encounter an error that terminates OpenEdge, note the message number before restarting.
Preface–10
Preface
• Choose Help→Messages and then enter the message number to display a description of
a specific OpenEdge message.
On UNIX platforms, use the Progress pro command to start a single-user mode character
OpenEdge client session and view a brief description of a message by providing its number.
install-dir/dlc/bin/pro
3. Type the message number and press ENTER. Details about that message number appear.
4. Press F4 to close the message, press F3 to access the Progress Procedure Editor menu, and
choose File→ Exit.
Preface–11
Preface
Preface–12
Part I
Introduction
Many of the server products that support application and integration services share common
requirements and similar tools for server configuration and administration. This chapter
describes all of these server products and where to find more information on using as well as
managing them, as described in the following sections:
For a complete overview of application and integration services in OpenEdge®, introducing and
describing how these server products work together, see OpenEdge Getting Started:
Application and Integration Services. For information on installing these products, see
OpenEdge Getting Started: Installation and Configuration.
Overview of Server and Services Administration
The AppServer is often used together with the OpenEdge NameServer to provide connection
and server-level fault tolerance and facilitate application service availability. With the help of
additional server products and adapters whose management is also described in this manual, the
AppServer can make its application services available to all types of OpenEdge clients in many
different configurations.
For more information on managing the AppServer, see Chapter 2, “Configuring and Managing
the AppServer.”
The AIA is installed and runs as a Java servlet in most any Java Servlet Engine (JSE) or in the
integrated JSE of a Web server, which provides the Internet access to the AppServer. As the
interface between Internet clients and the AppServer, the AIA provides connection options that
allow it to access an AppServer on behalf of the client directly or by accessing a NameServer
configured to provide location-independent access to the AppServer.
1–2
OpenEdge Web Services Adapter (WSA)
For information on connecting to the AppServer of the Internet using the AIA or AIA/S, see
OpenEdge Application Server: Developing AppServer Applications for 4GL clients and
OpenEdge Development: Open Client Introduction and Programming for Open Clients.
For more information on managing the AIA or AIA/S, see Chapter 3, “Configuring and
Managing the AppServer Internet Adapter.”
Also like the AIA, the WSA runs as a Java servlet in most any Java Servlet Engine (JSE) or in
the integrated JSE of a Web server, which provides the Internet access that Web service clients
require. However, in addition to the HTTP and HTTPS communications provided by the
JSE/Web server, the WSA understands the Simple Object Access Protocol (SOAP) used to
exchange service messages between Web service clients and the Web services that it manages.
Thus, the WSA translates between service requests from Web service clients and application
service responses from the AppServer, which it then returns as Web service responses to the
clients.
Progress 4GL Web services rely on Open Client technology to develop the client interface
required by Web service clients. For information on how to build Progress 4GL Web services
and access them from Web service clients, see OpenEdge Development: Web Services and
OpenEdge Development: Open Client Introduction and Programming.
For more information on managing the WSA, including information on how to deploy and
manage Progress 4GL Web services, see Part III, “Web Services Adapter Administration.”
Those chapters cover all aspects of Web service deployment, run-time management, and
security, as well as the management of the WSA itself.
1–3
Overview of Server and Services Administration
The Messenger runs on a Web server as a CGI or equivalent process (depending on the Web
server type) and acts as the gateway and translator between Web requests and responses on the
Web server side and the corresponding WebSpeed requests and responses on the Transaction
Server side. Like the AppServer, the WebSpeed Transaction Server can have a controlling
NameServer configured to provide server-level fault tolerance with multiple Transaction
Servers supporting the same application service. The WebSpeed Transaction Server and
Messenger each rely on the Progress Explorer framework for configuration and administration.
For information on managing the WebSpeed Transaction Server and WebSpeed Messenger, see
Part IV, “WebSpeed Administration.” Those chapters cover all aspects of WebSpeed
deployment, run-time management, and security, as well as the management of the WebSpeed
Transaction Server and Messenger themselves.
1–4
OpenEdge Adapter for Sonic ESB
For more information on the OpenEdge Adapter for SonicMQ architecture, see OpenEdge
Getting Started: Application and Integration Services.
For information on developing applications that incorporate messaging via SonicMQ, see
OpenEdge Development: Messaging and ESB.
For more information on managing the OpenEdge Adapter for SonicMQ, see Chapter 15,
“OpenEdge Adapter for SonicMQ Administration.” For more information on SonicMQ and its
installation, configuration, and management, see the SonicMQ product documentation.
Thus, once installed as an OpenEdge service, a Progress 4GL Web service becomes available
to take part with the ESB workflow process, as well as a Web service. As a Web service, the
Sonic ESB uses Web Service Description Language (WSDL) to make the OpenEdge service
available to Web service clients, much as does the WSA in the OpenEdge environment (see the
“OpenEdge Web Services Adapter (WSA)” section on page 1–3).
For more information on the OpenEdge Adapter for Sonic ESB and working with OpenEdge
services in Sonic ESB-integrated applications, see OpenEdge Development: Messaging and
ESB.
Once installed in the Sonic ESB environment, the OpenEdge Adapter for Sonic ESB has no
management interface of its own. Rather, you manage its deployed (installed) OpenEdge
services on the Sonic ESB using the Sonic ESB Explorer and related tools. For more
information, see Chapter 16, “Configuring and Managing the OpenEdge Adapter for Sonic
ESB.”
1–5
Overview of Server and Services Administration
1–6
Part II
AppServer and Internet Adapter
Administration
This chapter describes the tasks required to configure, start up, shut down, and maintain the
AppServer. The AppServer operates on the UNIX and Windows platforms, and you can
perform the required tasks from either the UNIX or Windows command lines or from the
Progress Explorer running on a Windows workstation.
AppServer administration includes common tasks for configuring all OpenEdge server products
that use the NameServer (OpenEdge Unified Broker products). For an overview of these
common tasks, including detailed information on NameServer configuration, see OpenEdge
Getting Started: Installation and Configuration. The sections of this chapter describe:
• AppServer clients
2–2
Run-time components and operation
NameServer
The dotted arrows indicate optional communications to establish a connection between client
applications and the AppServer.
2–3
Configuring and Managing the AppServer
Table 2–1 identifies and describes the components shown in Figure 2–1.
Component Description
Client A process that requests the execution of remote Progress 4GL procedures
application in the context of an AppServer session.
A client application can be:
• A Progress 4GL client session, including the WebClient.
• A WebSpeed 4GL (SpeedScript) session (WebSpeed agent), which
runs 4GL procedures on behalf of Web browser clients. (For more
information, see OpenEdge Application Server: Developing
WebSpeed Applications.)
• Another AppServer session (AppServer agent). (For more
information, see OpenEdge Application Server: Developing
AppServer Applications.)
• A .NET Open Client application. (For more information, see
OpenEdge Development: .NET Open Clients.)
• A Java Open Client application. (For more information, see
OpenEdge Development: Java Open Clients.)
• A client of Progress 4GL Web services (including Sonic ESB
services).
The Progress interface in Figure 2–1 is the code that allows a client
application to access an AppServer. For 4GL clients, this interface is
accessed through built-in 4GL statements and functions dedicated to
AppServer access. For .NET, Java, and Web service Open Clients, this
interface is accessed through a client interface that is custom-built with the
OpenEdge Open Client Toolkit to access AppServer procedures.
2–4
Run-time components and operation
Component Description
AppServer A process that creates, manages, and allocates AppServer agents for access
broker by client applications. The AppServer broker manages client connection
requests and dispatches requests to AppServer agents. Exactly how it does
this depends on the AppServer operating mode. (For more information, see
OpenEdge Application Server: Developing AppServer Applications.) A
single AppServer broker supports one AppServer instance.
1. The same NameServer process can also coordinate Web browser access to WebSpeed Transaction Servers and 4GL
client access to OpenEdge DataServers or OpenEdge Adapter for SonicMQ. For more information on all
NameServer features, see OpenEdge Getting Started: Installation and Configuration.
2–5
Configuring and Managing the AppServer
Distribution of components
The AppServer broker for an AppServer instance and its associated AppServer agents must all
execute on the same computer. Client applications, however, can run on any computer in the
network that can access the computer where the AppServer agent is running. Any required
NameServer can execute on the same computer as a client application, the same computer as an
AppServer instance, or on any other computer in the network to which both AppServer agents
and client applications have access. With these conditions satisfied, OpenEdge can establish a
connection between any client and any AppServer. For more information on how you can
distribute AppServer components on a network, see the information on machine distribution in
OpenEdge Getting Started: Installation and Configuration.
Fault-tolerant NameServers
You can configure NameServer such that a group of NameServers work together to resolve a
client connection request. Having a group of NameServers working together to resolve the
request provides fault-tolerant access to the NameServer function.
OpenEdge provides two mechanisms that you can use to implement fault-tolerant NameServers,
and you can use them independently or together:
For more information on setting up fault-tolerant NameServers, see OpenEdge Getting Started:
Installation and Configuration.
2–6
Run-time components and operation
Note: If you have not installed the NameServer Load Balancer and an AppServer tries to
register the same application service on the same controlling NameServer of an
already-registered AppServer, the AppServer attempting to register receives an error.
The NameServer Load Balancer also allows you to have the NameServer distribute client
connections across a set of fault-tolerant AppServers proportionately, according to a weight
factor that you specify when you configure each AppServer instance. When each AppServer
registers with the controlling NameServer, in addition to its location and supported application
service list, the AppServer registers any weight factor you specify. The NameServer uses the
weight factors configured for all instances in a set of fault-tolerant AppServers to determine
how to distribute client connections among them.
The values of these weight factors are arbitrary. It is the relative differences between these
values that determine how the NameServer balances load. To achieve effective load balancing,
you must coordinate weight factor assignments according to individual AppServer
performance. Thus, the most correct weight factor for each AppServer instance depends on the
relative performance (for your application) of the particular AppServer platform and its
configuration compared to other AppServers that register support for the same application
service.
2–7
Configuring and Managing the AppServer
Note that the NameServer is flexible enough that you can dynamically start an AppServer
instance to register at any time among a set of running fault-tolerant AppServers. As an
AppServer instance starts up and registers, the NameServer adds it to the list of available
AppServers that support the same application services. The NameServer then apportions client
connection requests according to the latest set of weight factors.
For more information on setting weight factors and the effects of these settings, see OpenEdge
Getting Started: Installation and Configuration.
Operating modes
When you configure an AppServer instance, you must specify an operating mode for it. The
operating mode determines how client requests are dispatched to individual AppServer agents
running on the AppServer instance. Each operating mode features different performance and
design trade-offs.
The AppServer supports the following four operating modes, in increasing order of complexity:
1. State-reset — All requests sent by a client connected to this AppServer go to the same
AppServer agent. This AppServer agent remains dedicated to the same client for the life
of the connection. When the client disconnects, the AppServer agent resets its context to
what it was at startup, removing all context created during the terminated client
connection.
Note: This operating mode is conceptually similar to the operation of AppServers prior
to Progress Version 9, which run in only one operating mode.
2. State-aware — All requests sent by a client connected to this AppServer go to the same
AppServer agent. This AppServer agent remains dedicated to the same client for the life
of the connection. When the client disconnects, the AppServer agent deletes any remote
persistent procedures that are still active in its context. However, it maintains all other
context created during the terminated client connection for access during future client
connections. This context remains available until it is removed during a future client
connection or the AppServer agent terminates.
2–8
Run-time components and operation
3. Stateless — An AppServer agent is not dedicated to a specific client. The AppServer agent
can execute a request from any client that has an outstanding request to the AppServer.
Because a client request can execute in an AppServer agent that is different from any that
executed previous requests for the same client, session context established for this client
during a previous request might not be available. Because OpenEdge does not
automatically clean up any session context between requests, the session context in which
a client request runs might have been established by a request from a different client.
4. State-free — The AppServer is not dedicated to a specific client, but executes requests
from all clients that connect to an application service that the AppServer supports. Its
AppServer agents can execute a requests from any client that is logically connected to and
sends request to the application service that the AppServer supports. Because a client
request can execute a request on any AppServer and agent that supports the application
service, session context is usually not available from one request to the next for the same
client.
For more information on the functional, performance, and design trade-offs among these
operating modes, see OpenEdge Application Server: Developing AppServer Applications.
Security derives from the client authentication of the server’s identity via a Public Key
Infrastructure (PKI) and a symmetric data encryption system. To configure an AppServer
instance for SSL operation, you must:
• Obtain and install a server private key and a public key certificate. OpenEdge provides
built-in keys and certificates that are suitable for use on development or demonstration
servers; for production machines, you should obtain server certificates from an internal or
public Certificate Authority (CA).
• Specify an alias and password for access to the private key/digital certificate.
2–9
Configuring and Managing the AppServer
• To perform these configuration tasks, you can use the Progress Explorer (in Windows
only) or manually edit the ubroker.properties file.
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
For more information on SSL support in OpenEdge, see OpenEdge Getting Started: Core
Business Services.
• Session-free — For the session-free modes (stateless and state-free), the client makes an
SSL connection to the AppServer broker, which is the single primary server connection.
SSL tunneling is not necessary for the transmission of data between the broker and the
AppServer agent, because this connection is local to a single system and therefore is not
exposed to the network.
2–10
Run-time components and operation
An SSL-enabled AppServer instance cannot start if the correct key password is not provided,
the server key store entry cannot be found, or the server digital certificate is out of date. See the
“SSL-enabled AppServer operation” section on page 2–9 for more information.
You can also configure the AppServer agent to pass a set of OpenEdge startup parameters to
any AppServer agents that it starts. These startup parameters have the same effect on each
AppServer agent as the startup parameters used to start a Progress 4GL client. For example, one
of the startup parameters you specify might be the Database (-db) parameter to indicate that all
AppServer agents in the pool are to connect to a specific database when they start up.
AppServer registration
When you start an AppServer instance configured to use a NameServer, the first thing the
AppServer agent does is to register with the controlling NameServer that you specified during
AppServer configuration. When you shut down an AppServer instance, the AppServer agent
immediately unregisters the AppServer with the controlling NameServer, ensuring that the
NameServer no longer makes this AppServer available for client connection requests.
2–11
Configuring and Managing the AppServer
AppServer
AppServer NameServer
broker
client
Progress
Explorer
AppServer
AdminServer
Management agent
utilities
Text
editor
AppServer Configuration
properties utilities
(ubroker.properties)
AppServer host
Figure 2–2 shows the NameServer and AppServer components running on the same machine.
You can also install the NameServer and AppServer on separate machines connected to the
same network. In that case, a separate AdminServer and ubroker.properties file exist on each
machine for access by the Progress Explorer.
2–12
AppServer administration framework
For more information on distributed AppServer configurations, see OpenEdge Getting Started:
Installation and Configuration.
The core of the Progress Explorer administration framework is the AdminServer process, which
resides on each machine where an OpenEdge server product is installed. (In Windows, this is
the installed service, AdminService for OpenEdge.) The AdminServer performs the actual
configuration and management of these products within the Progress Explorer framework.
• AppServer clients.
• NameServer.
• AppServer agent.
• AppServer agents.
For more information on how AppServer clients, NameServers, AppServer agents, and
AppServer agents work together, see the sections on the AppServer in OpenEdge Getting
Started: Application and Integration Services. Administration of these components follows the
general procedures outlined in this section using the Progress Explorer, the
ubroker.properties file, and the supporting utilities. For an overview of this configuration
procedure and detailed information on configuring NameServers, see OpenEdge Getting
Started: Installation and Configuration.
2–13
Configuring and Managing the AppServer
AppServer clients
This chapter describes configuration and startup of the AppServer itself. For information on
configuring and starting up the various AppServer clients, see the documentation for your client
product.
For Progress 4GL clients, see OpenEdge Getting Started: Installation and Configuration, and
the following manuals:
For information on configuring and deploying .NET, Java, and Web services Open Clients, see
OpenEdge Development: Open Client Introduction and Programming and OpenEdge
Development: Web Services.
Progress Explorer is a graphical user interface that provides an easy way for you to create and
manage AppServers. The Progress Explorer tool runs as a Windows client and works with the
AdminServer (AdminService in Windows) in a client/server framework to manage AppServers
and their controlling NameServers.
For an introduction to using the Progress Explorer tool and information on creating and
managing NameServers, see OpenEdge Getting Started: Installation and Configuration. For
information on configuring an AppServer using the Progress Explorer tool, see the
“Configuring an AppServer with the Progress Explorer” section on page 2–21. For information
on starting and managing an AppServer, see the “Starting and managing an AppServer with the
Progress Explorer” section on page 2–32.
2–14
AppServer clients
The command-line management utilities run on both Windows and UNIX platforms and allow
you to manage existing AppServer configurations. The management utilities for the AppServer
include the:
Like the Progress Explorer tool, the command-line management utilities work with the
AdminServer in a client/server framework to manage AppServers and their controlling
NameServers. Unlike the Progress Explorer tool, these utilities do not create a new AppServer
configuration. Without the Progress Explorer, you must use a text editor and the configuration
utilities. For more information, see the “Text editor and configuration utilities” section on
page 2–18.
This chapter describes how to manage an AppServer using the Progress Explorer and the
ASBMAN utility. For information on managing a NameServer using the NSMAN utility, see
OpenEdge Getting Started: Installation and Configuration.
For information on starting and managing an AppServer using the management utilities, see the
“Starting and managing an AppServer with the management utilities” section on page 2–34.
2–15
Configuring and Managing the AppServer
NameServers
The NameServer is an optional, but powerful, part of any AppServer configuration and
management. Its features support the following AppServer capabilities:
For an overview of these features, see OpenEdge Getting Started: Application and Integration
Services. For detailed information on configuring and managing NameServers to support all of
these features, see OpenEdge Getting Started: Installation and Configuration. This chapter
describes when and where to use NameServer instances as part of AppServer configuration and
management.
AppServer broker
The AppServer broker:
• Registers the application services the AppServer provides with the controlling
NameServer. For more information on application services, see OpenEdge Getting
Started: Application and Integration Services.
• Manages connections between clients and a pool of AppServer agents that it starts.
• Maintains the status of each AppServer agent in its pool and scales the number of
processes according to changing demand.
• When configured for stateless or state-free operating mode, dispatches remote requests to
AppServer agents.
One AppServer agent provides connection management for a single AppServer instance.
However, you can configure multiple AppServer instances, possibly using different operating
modes and accessing different resources, for a single AppServer installation. For information
on broker configuration options, see the “Configuring AppServer components” section on
page 2–19.
2–16
AppServer clients
AppServer agents
An AppServer agent is an OpenEdge session within the AppServer that executes 4GL
procedures on behalf of AppServer clients. The AppServer broker manages a pool of AppServer
agents for an AppServer instance. Each AppServer agent in the pool runs an identical set of 4GL
procedures that share the same OpenEdge resources. The application services that an AppServer
supports are really aliases for the same set of remote procedures supported by all AppServer
agents in the pool.
When you configure AppServer agents, you specify a single set of properties that apply in
common to all processes in the pool. For more information on configuring AppServer agents,
see the “Configuring AppServer components” section on page 2–19.
For general information on the ubroker.properties file and more specific information on
AppServer properties, see the “Editing the properties file” section on page 2–25. For
information on NameServer properties, see the sections on configuring the NameServer using
the properties file in OpenEdge Getting Started: Installation and Configuration.
2–17
Configuring and Managing the AppServer
• Use the mergeprop utility installed with OpenEdge. For information on using mergeprop,
see OpenEdge Getting Started: Installation and Configuration.
To update NameServer and AppServer configurations from a UNIX platform, you must use one
of the preceding methods. In general, you should update all UNIX configurations remotely from
a Windows platform, using the Progress Explorer GUI. If you must update a UNIX AppServer
configuration locally, make a copy of the file, update the copy, and then verify the result.
OpenEdge provides a set of configuration validation utilities that you can use to verify the
correctness of any changes that you make to this file.
• Install the necessary product components. Typically, this involves installing OpenEdge
and the AppServer on one or more network machines. If you plan to configure
fault-tolerant servers or use load balancing, you must install the NameServer Load
Balancer.
• Configure and set up the machines involved in the OpenEdge installation. Typically, you
have completed any required network configuration for all machines before installing
OpenEdge. After installation, you must also set up each machine environment to run
OpenEdge and the AppServer.
2–18
Configuring AppServer components
• If you plan to use secure (SSL-enabled) AppServers, obtain and install a server private key
and a public key certificate on each host machine. See the “SSL-enabled AppServer
operation” section on page 2–9 for more information.
For more information on OpenEdge installation and setup, see OpenEdge Getting Started:
Installation and Configuration. For more information on the distribution of resources in the
AppServer environment, see the information on machine distribution for Unified Broker
products in these same manuals. For more information on security-related concepts and
configuring SSL-enabled OpenEdge servers, see OpenEdge Getting Started: Core Business
Services.
1. Make sure that the AdminServer process is running on each of the following machines:
2–19
Configuring and Managing the AppServer
On UNIX, use the proadsv command to start the AdminServer. To check whether the
AdminServer is running, run the ps command to show the full command line for each
process on the system and locate any jre commands in the list. The AdminServer process
is running if you see a jre command with the arguments that correspond to those specified
for jvmstart in the OpenEdge proadsv shell script located in
OpenEdge-Install-Directory/bin.
For more information on using the PROADSV utility, see the “PROADSV” section on
page B–17.
For more information on starting the AdminServer, see OpenEdge Getting Started:
Installation and Configuration.
2. In the Progress Explorer, connect to the running AdminServer processes that you verified
in Step 1. After you connect to a machine running an AdminServer process, its host name
or IP address appears as a folder in the tree view.
3. Expand each machine folder to see a list of folders showing all OpenEdge server products
installed on the machine.
4. If you are using the NameServer, select the NameServer product folders where you want
to configure NameServers and configure one or more such instances to support all
AppServer instances you want to configure. Note that for every AppServer instance that
you plan to run on a separate machine from its controlling NameServer, you must
configure a remote NameServer instance on the same machine as the AppServer. This
remote NameServer instance must reference the host and port of the controlling
NameServer for the AppServer. For more information, see the chapter on configuring
OpenEdge Unified Broker products in OpenEdge Getting Started: Installation and
Configuration.
5. Select the AppServer product folders where you want the AppServer instances to reside.
If you are using the NameServer, configure the instances to register with the controlling
NameServer (with or without load balancing). Specify any application service names
required for clients to access the AppServer and any other required configuration
information. For more information, see the “Configuring an AppServer with the Progress
Explorer” section on page 2–21.
The sections that follow describe the basic steps for configuring each AppServer instance. For
more information, see the Progress Explorer online help.
2–20
Configuring AppServer components
1. Make sure the AdminServer is running on the host where you want to configure the
AppServer (see the “General steps for using the Progress Explorer to configure an
AppServer instance” section on page 2–19).
3. Connect to the AdminServer on your AppServer host (see OpenEdge Getting Started:
Installation and Configuration).
• To define a new AppServer, select the AppServer folder in the Progress Explorer’s
tree view, right-click, and choose New. Enter a unique name for the AppServer and
click OK. Then open the property editor for the new instance by selecting the
instance, right-clicking, and choosing Properties.
The AppServer instance property editor shows a tree view of property categories on the
left and the properties for the selected category on the right.
5. Select a property category and set the properties as required. You can accept the default
values, if they are appropriate for your application. You probably want to specify the
properties under each category. See the Progress Explorer online help for detailed
information about each property.
2–21
Configuring and Managing the AppServer
The Broker category specifies properties of the AppServer broker. Expanding this
category shows the following property subcategories:
• General — You must specify an Operating mode, and you probably want to specify
a non default value for the TCP/IP port number where the AppServer agent listens
for requests.
If you want the AppServer to start whenever you start the AdminServer, select the
Auto start check box, and if you want to use a different working directory from the
one specified during AppServer product installation, you can also change it here.
• AppService Name List — You can either enter any names for the application
services supported by this AppServer or select the Supports default service check
box if you want this AppServer to support the default service for all client
connections that do not specify an application service name. If you choose to use
application service names, the default application service name is the name of the
AppServer instance.
• Logging Setting — You can set the following logging options: specify a different
pathname from the default for the broker log file; specify the level of logging detail;
control whether the logging for a session appends to or overwrites the previous
broker log file; specify a comma-separated list of logging entry types to be included
in the broker log file, choosing from the valid values listed in the Progress Explorer
online help; set a file-size threshold that determines the point at which a new log file
is created (0 = unlimited log file size); and specify the maximum number of broker
log files to be kept (0 = unlimited number of log files retained). See OpenEdge
Development: Debugging and Troubleshooting for detailed information on logging
options.
2–22
Configuring AppServer components
• Advanced Features — You can specify the maximum number of client connections
(Maximum client instances) that the AppServer can support at one time, the
AppServer weight factor (Priority weight) for load balancing, the time between
retries to register the AppServer with the controlling NameServer, the timeout period
for starting the AppServer, the timeout period for an AppServer to accept a client
request, and the timeout period for the AppServer agent to trim its quota of
AppServer agents between the maximum and minimum setting (see the Agent
category). For more information on these options, see the Progress Explorer online
help.
The Agent category specifies properties of the AppServer agents. Expanding this category
shows the following property subcategories:
• General — You can specify a pathname of the AppServer agent executable (Server
executable file). You generally only need to specify a different value than the default
if you build a new AppServer agent executable using the OEBuild utility. For more
information, see the “Customizing the AppServer agent executable” section on
page 2–30.
Specify the OpenEdge startup parameters for the AppServer agent (Server startup
parameters). These are the standard OpenEdge client startup parameters, and can
include any parameters that you require for each AppServer session, including (but
not limited to) all of the standard database, code-page, and process management
parameters. For more information, see OpenEdge Deployment: Startup Command
and Parameter Reference.
The AppServer can run with a different code page than the client application. For
more information, see the “Managing code pages” section on page 2–38.
For PROPATH, specify the semicolon-separated list of directories where the AppServer
can locate 4GL procedures to execute. This setting overrides any PROPATH
environment variable settings on the AppServer host when it starts up. Make sure
that all of the 4GL procedures (r-code or source) that you want the AppServer to
execute are located in one of these PROPATH directories. Otherwise, the procedure
must be executed using its fully qualified pathname.
Specify the minimum and maximum TCP/IP port numbers that the AppServer agent
can assign to AppServer agents that it starts up. (Check with your system
administrator for appropriate ranges.)
2–23
Configuring and Managing the AppServer
• Logging Setting — You can set the following logging options: specify a different
pathname from the default for the server log file; specify the level of logging detail;
control whether the logging for a session appends to or overwrites the previous server
log file; specify a comma-separated list of logging entry types to be included in the
server log file, choosing from the valid values listed in the Progress Explorer online
help; set a file-size threshold that determines the point at which a new log file is
created (0 = unlimited log file size); and specify the maximum number of server log
files to be kept (0 = unlimited number of log files retained). See OpenEdge
Development: Debugging and Troubleshooting for detailed information on logging
options.
• Pool Range — These settings determine the number of AppServer agents that the
AppServer agent can start up and maintain for the AppServer. For more information
on setting these values, see the “Specifying the server pool parameters” section on
page 2–37.
• Advanced Features — To allow the 4GL debugger to run in the AppServer session,
select the 4GL debugger enabled check box. Specify the names of any AppServer
configuration procedures that you want the AppServer to execute, and any
parameters for the Startup procedure. For more information on debugging
AppServer applications and on AppServer configuration procedures, see OpenEdge
Application Server: Developing AppServer Applications.
The options in the SSL category options define the security settings for an SSL-enabled
AppServer instance. Note that an AppServer enabled for SSL operation does not accept
non-SSL client connections. For more information on SSL operations, see OpenEdge
Getting Started: Core Business Services. Expanding this category shows the following
property subcategories:
• General — If you check the Enable SSL Client Connections box, select the alias
for the private key/digital certificate entry (in the OpenEdge keystore) that you want
to secure connections for this AppServer instance. Also, enter and confirm the
password for this private key and digital certificate. You need not enter a password
if you choose to use the default_server certificate and its default password.
• Advanced Features — By default, caching is enabled for the SSL client session, and
you can enter a time-out value that specifies the length of time (in seconds) that a
disconnected session is held in the cache. During this specified interval, a connected
client can resume its session. To disable session caching, check the box.
2–24
Configuring AppServer components
The Messaging category specifies properties for an OpenEdge Adapter for SonicMQ
ServerConnect (ServerConnect) process started by the application service running on this
AppServer. It allows you to start a ServerConnect process at startup. You can also set
logging options for the ServerConnect: specify a different pathname from the default for
the broker log file; specify the level of logging detail; control whether the logging for a
session appends to or overwrites the previous broker log file, specify a different pathname
from the default for the server log file; specify the level of logging detail; control whether
the logging for a session appends to or overwrites the previous server log file. See
OpenEdge Development: Debugging and Troubleshooting for detailed information on
logging options.
If you want to specify environment variables for AppServer execution, select the
Environment Variables category. It allows you to enter name-value pairs for
environment variable settings. Any values you set here override prior values set for the
same environment variables in the operating system. For more information, see the
“Environment variable settings” section on page 2–29.
Note: Do not set the PROPATH variable in the Environment Variables category. Use the
Server General category instead.
The properties file stores all the configuration definitions for all instances of the NameServer,
and all instances of any AppServer, AppServer Internet Adapter, WebSpeed Server, Web
Services Adapter, OpenEdge Adapter for SonicMQ, and DataServer product that run on the
same machine. Each configuration definition contains environment variables, registry entries (if
Windows), and property settings for each product instance.
There is one copy of this file for each OpenEdge installation. Thus, if you install the
NameServer on a separate machine from the AppServer product that it manages, the
NameServer and AppServer product each have their own copy of the ubroker.properties file.
2–25
Configuring and Managing the AppServer
The AdminServer reads and updates this file according to your instructions using the Progress
Explorer and management utilities. The ubroker.properties file is installed in the properties
subdirectory of the OpenEdge installation directory (for example,
OpenEdge-Install-Directory/properties/ubroker.properties on UNIX, or
OpenEdge-Install-Directory\properties\ubroker.properties in Windows). For the
AdminServer to access the properties file, the file must reside in this directory.
When editing the ubroker.properties file without the Progress Explorer, note that:
• You should not directly change the values in the ubroker.properties file unless you have
a complete understanding of how the changes affect components. When possible, always
use the Progress Explorer to make all changes to this file.
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
• Always make a copy of this file, edit the copy, and verify the result before replacing the
original with your edited copy.
• For complete definitions of all the properties and detailed information on how to set them,
see the ubroker.properties.README file, as well as the comments included in the
properties file itself. Both files reside in the properties directory.
The file consists of a hierarchical structure of configuration entities, where parent entities
provide configuration information that you can override or extend in each child entity. Each
configuration entity has a name that begins the entity definition, and the definition contains
configuration settings for one or more products or product instances.
2–26
Configuring AppServer components
The AppServer configurations in ubroker.properties can include the entities listed in Table
2–2.
Thus, parent entities provide default values for all of their child entities. For example, the parent
[UBroker] contains a set of definitions that can be inherited by its child AppServer product
[UBroker.AS] and any other product entities, and then again by its child
[UBroker.AS.product-instance-name] and any other product instance entities. However, at
any child level, a redefinition of any value supersedes the default value of its parent. All children
from the redefinition level down inherit this new value.
To edit the properties file directly, use a text editor such as vi or Notepad. Once you edit the
properties file, use the following utilities to validate the AppServer configuration information
in the file:
2–27
Configuring and Managing the AppServer
If the file contains any other OpenEdge server configurations (such as for WebSpeed or the
OpenEdge Adapter for SonicMQ), run the configuration validation utilities for those Unified
Broker products to ensure that these configurations are still valid. For more information, see
OpenEdge Getting Started: Installation and Configuration.
Note: If you always use the Progress Explorer, you never have to use these utilities.
The ASCONFIG utility displays the property settings associated with an AppServer configuration,
and checks that the syntax and values are valid. You must run the ASCONFIG utility locally on
the machine on which the AppServer is running. The utility does not run across the network.
Syntax
asconfig[
[ [ -name AppServer-name ]
[ -propfile path-to-properties-file ]
[ -validate ]
] | -help ]
For more information on the ASCONFIG utility, see the “ASCONFIG” section on page B–10 and
the “Summary of management tasks” section on page 2–40.
The following command validates the syntax and views the configurations of all AppServer
instances defined within the test.properties file located in the current working directory:
2–28
Setting up the environment for AppServer execution
• Set any standard environment variables (for example, DLC) on the AppServer and
NameServer machines.
• Copy r-code files to support any OpenEdge SmartDataObjects you want to run on the
AppServer.
For more information on setting the standard OpenEdge environment variables, see the chapters
on setting up the environment and configuring OpenEdge Unified Broker products in OpenEdge
Getting Started: Installation and Configuration.
The working directory settings for AppServer and NameServer each specify the directory in
which the specified product starts up and, by default, where its log files and any other files
output by AppServer applications are written. As with other settings, you can change or override
the default settings for the working directory. You can also individually specify the locations of
AppServer and NameServer log files. For more information, see the “Configuring AppServer
components” section on page 2–19.
2–29
Configuring and Managing the AppServer
The AppServer agent executable is essentially a version of the Progress 4GL client. Like the
4GL client, you can rebuild the AppServer agent executable using the OEBuild utility.
To build a new AppServer agent executable and make it available to your AppServer
installation:
1. Build the executable using the OEBuild utility according to the instructions provided in
OpenEdge Deployment: Managing 4GL Applications.
2. Specify the pathname for your new AppServer agent executable using the Progress
Explorer or by setting the srvrExecFile property in the AppServer properties file
(ubroker.properties). For more information on specifying the pathname for the
AppServer agent executable, see the “Configuring AppServer components” section on
page 2–19.
2–30
Starting and managing an AppServer instance
You can also shut down a NameServer and the AppServer instances that it controls in any order.
However, when you shut down the NameServer, any client applications that are not already
connected cannot connect to the AppServer instances that this NameServer controls. Connected
clients can still continue to operate with any running AppServers. If you restart the NameServer,
any running AppServers that it controls automatically register with it and again become
available for client connections.
Before you begin to develop or deploy applications in Windows or UNIX, note the requirements
for each platform.
• Where any OpenEdge databases or other DataServers reside that your AppServer instance
needs to access.
For more information, see the “General steps for using the Progress Explorer to configure an
AppServer instance” section on page 2–19.
2–31
Configuring and Managing the AppServer
To access the Progress Explorer tool, you can open it from the OpenEdge program group or in
the Microsoft Management Console (MMC) on your Windows system. For more information,
see OpenEdge Getting Started: Installation and Configuration. Once you have opened the
Progress Explorer in the MMC, you can start an AppServer instance.
1. In the Progress Explorer, connect to each of the running AdminServer processes required
by your AppServer configuration. The name or IP address of the machine running each of
these processes appears as a folder in the tree view.
2. Expand each machine folder to see a list of folders showing the name of each NameServer
and AppServer product installed on the machine.
3. Expand the NameServer folder under each machine to see a list of configured
NameServers.
4. Start each NameServer that you need to support your AppServer instance and that is not
already auto-started. For more information, see OpenEdge Getting Started: Installation
and Configuration.
5. Start each OpenEdge database or DataServer that your application requires and that is not
already auto-started. For more information on starting databases and DataServers, see
OpenEdge Getting Started: Installation and Configuration.
6. Under the machine folder where it resides, expand the AppServer folder for the instance
you want to start.
2–32
Starting and managing an AppServer instance
• Choose Action→Start.
Using the Progress Explorer, you can also invoke the following management functions for the
running AppServer instance:
Note: You cannot stop the AppServer if it is actively handling any client requests.
• Check and manage the operational status of the AppServer. Using the status dialog box,
you can also reduce (Trim servers button) and increase (Add servers button) the number
of running AppServer agents for this AppServer. For more information on the effects of
these functions, see the “Specifying the server pool parameters” section on page 2–37. For
more information on AppServer status indicators, see the “Checking AppServer status”
section on page 2–36.
• View the log files for the AppServer. To view a log file, expand the AppServer instance
folder in the tree view and select the log file you want to view. The contents of the log file
appear in the right pane.
Note: Before you can delete an AppServer instance, you must stop the AppServer.
For more information on using the Progress Explorer to start and manage an AppServer
instance, see the Progress Explorer online help.
2–33
Configuring and Managing the AppServer
1. If your AppServer requires NameServer support, use the NSMAN utility to start each
NameServer that you need to support your AppServer instance. For more information, see
OpenEdge Getting Started: Installation and Configuration.
2. Start each OpenEdge database or DataServer that your application requires. For more
information on starting databases and DataServers, see OpenEdge Getting Started:
Installation and Configuration.
The ASBMAN utility runs on both Windows and UNIX platforms. It allows you to invoke the
following management functions on a local or remote AppServer instance:
• Start an AppServer.
• Check and manage the operational status of the AppServer. Management options allow
you to reduce (trim) and increase (add) the number of running AppServer agents for this
AppServer. For more information on the effects of these options, see the “Specifying the
server pool parameters” section on page 2–37. For more information on AppServer status
indicators, see the “Checking AppServer status” section on page 2–36.
2–34
Starting and managing an AppServer instance
Unlike the Progress Explorer, the ASBMAN utility has no mechanism for viewing log files or
deleting configured AppServer instances. If you want to set the AppServer log file or delete the
AppServer instance, you must do it manually using operating system commands. To delete the
AppServer, you must remove the entry for this AppServer instance in the AppServer properties
file or use the Progress Explorer. For more information on managing log files, see OpenEdge
Getting Started: Installation and Configuration. For more information on accessing the
AppServer properties file, see the “Editing the properties file” section on page 2–25.
Note: Before you can delete an AppServer instance, you must stop the AppServer.
Syntax
asbman {
{ -name AppServer-name
{ -kill | -start | -stop | -query |
-addservers number-to-start |
-trimservers number-to-trim }
[ -host host-name -user user-name | -user user-name ]
[ -port port-number ]
} | -help }
For more information on the ASBMAN utility, see the “ASBMAN” section on page B–7.
2–35
Configuring and Managing the AppServer
Status Description
BUSY The process is actively executing application logic for an AppServer client.
For a state-aware or state-reset AppServer, this status persists until the client
disconnects from the AppServer.
LIMBO The process is in a transitional state. If this status persists, it indicates an error
condition.
STARTING The AppServer has started the process, but it has not yet completed
initialization.
2–36
Specifying the server pool parameters
• Initial number of servers to start — The number of processes started when the
AppServer first starts up.
• Minimum servers — The minimum number of processes that the AppServer keeps
running to meet client demand.
• Maximum servers — The maximum number of processes that the AppServer keeps
running to meet client demand.
For a stateless and state-free AppServer, you must tune these parameters to handle changing
client load based on how many clients that you can expect a single AppServer agent to handle
in a given time period. Thus, you are looking for the optimum settings for the number of
concurrent requests.
One way to assess this capacity for all operating modes is to set a high value for the Maximum
Server Instances parameter and a low value for the Minimum Server Instances parameter. Then,
run live for a period of time and see how many AppServer agents the AppServer tends to start.
You might want to set the Initial Server Instances to Start parameter to that value.
2–37
Configuring and Managing the AppServer
• You can trim any number of running AppServer agents below your Minimum Server
Instances parameter value to zero.
• You cannot add any more AppServer agents than your Maximum Server Instances
parameter setting. However, once you have found the maximum number of AppServer
agents that you can run productively for the AppServer, you might even want to set that
value lower if the setting negatively impacts other tasks on the system.
Code-page settings
You can set code pages for 4GL clients and AppServers using several code page startup
parameters. Each parameter allows you to specify any one of a wide variety of supported code
pages for a specified data domain in the OpenEdge environment (for example, memory code
page or input/output stream code page). For the AppServer, you specify code page startup
parameters in the Progress Explorer as part of the srvrStartupParam property setting in the
ubroker.properties file. For more information on these parameters, see the chapter on code
pages in OpenEdge Development: Internationalizing Applications. Whatever the settings, the
AppServer performs the necessary conversions to and from the client application.
Note: Note that the Terminal Code Page (-cpterm) startup parameter has no meaning for the
AppServer.
2–38
Managing code pages
Both .NET and Java Open Clients send requests (input) to the AppServer and receive responses
(output) from the AppServer using Unicode UTF-8. The AppServer automatically converts
between these open client Unicode UTF-8 requests and the particular code page that the
AppServer is using.
Note: If your AppServer application provides database services to a multi-lingual open client
application, using UTF-8 for both the AppServer and the database provides the most
effective data interchange across application components.
Caution: Unicode supports text with embedded nulls. OpenEdge does not support this feature,
no matter what character set it uses. Make sure that any open client applications filter
character strings input to the AppServer for embedded nulls. Unfiltered input can
result in unpredictable errors returned by the AppServer.
Run-time conversions
The AppServer converts the following types of character data passed between a client and the
AppServer agent:
• Connection parameters.
• Error messages.
2–39
Configuring and Managing the AppServer
Table 2–4 describes the utilities (in addition to the Progress Explorer tool) that OpenEdge
provides to help configure and manage an AppServer installation, listed generally in order by
task.
Execution
Utility location Description
ASBMAN Local or remote to the Starts, stops, adds AppServer agents, trims AppServer
AppServer agents, and queries status for an AppServer instance
installation. and its AppServer agent.
NSMAN Local or remote to the Starts, stops, and queries status for a NameServer.
NameServer
machine.
PROADSV Local to the Starts, stops, and queries status for the AdminServer
AppServer on UNIX. In Windows, you start the AdminService as
installation. a Windows service using the Services applet in the
Control Panel.
For more information on the NameServer and NSMAN utility, and the AdminServer and PROADSV
utility, see the “NSMAN” section on page B–14, the “PROADSV” section on page B–17,
OpenEdge Getting Started: Installation and Configuration.
2–40
Summary of management tasks
• Verify the configuration of, start, query, and stop a NameServer instance.
• Verify the configuration of, start, query, add AppServer agents to, trim AppServer agents
from, and stop an AppServer instance.
Start or stop the From the Windows Control Panel, choose Administrative
AdminService in Tools, then choose Services. Choose the AdminService for
Windows. OpenEdge, and click either Start, Restart, or Stop.
2–41
Configuring and Managing the AppServer
2–42
Summary of management tasks
2–43
Configuring and Managing the AppServer
2–44
3
Configuring and Managing the AppServer
Internet Adapter
The AppServer Internet Adapter (AIA) Web-enables the AppServer and the OpenEdge Adapter
for SonicMQ BrokerConnect (BrokerConnect) by supporting HTTP and HTTPS protocols for
sending information across the Internet. In addition, the HTTP and HTTPS protocols provide a
way for clients to access an AppServer or a BrokerConnect connection when the client and
server are separated by firewalls that limit connections to HTTP and HTTPS. These topics are
explained in the following sections:
For more information on the architecture of the AIA and how it supports OpenEdge application
services, see OpenEdge Getting Started: Application and Integration Services. For more
information on OpenEdge Adapter for SonicMQ architecture, see OpenEdge Getting Started:
Application and Integration Services. For information on how to build OpenEdge application
services for the Internet and connect to them from 4GL clients, see OpenEdge Application
Server: Developing AppServer Applications. For information on how to connect Open Client
applications to OpenEdge application services over the Internet, see OpenEdge Development:
Open Client Introduction and Programming. You can also use the Progress Knowledge Base
on the Web (http://www.progress.com/support) for information about Web-enabling 4GL
application clients of OpenEdge application services.
3–2
Installing the AppServer Internet Adapter
• A Java Servlet Engine (JSE), with HTTPS enabled if you are using Secure Sockets Layer
(SSL) connections.
• A Web server with an integrated JSE, with HTTPS enabled if you are using SSL
connections.
For more information on AIA installation, see OpenEdge Getting Started: Installation and
Configuration.
3–3
Configuring and Managing the AppServer Internet Adapter
The first connection is Internet-based between the AIA and the client. For this connection to be
secure, the following conditions must be met:
• The AIA must be HTTPS-enabled; that is, it must be configured to accept HTTPS
requests from clients (via the JSE or Web server). To configure the AIA to accept HTTPS
connection requests, you set the property httpsEnabled=1. You set this property by
checking the HTTPS enabled box in the General properties category in the Progress
Explorer, or by manually editing the ubroker.properties file.
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
• The JSE or Web server must support server authentication. Supporting server
authentication requires that X.509 digital certificates be installed on both the Web server
(or JSE) and the client machine. At each Web server to be accessed, a server certificate
that uniquely identifies this Web server must be installed. As part of the SSL protocol, this
server certificate is sent from the Web server to the client. See the “Enabling the Web
server or JSE for SSL operation” section on page 3–10 for more information.
3–4
Installing the AppServer Internet Adapter
The second connection is via AppServer protocol between the AIA and the AppServer or
BrokerConnect. For this connection to be secure, the following conditions must be met:
• The AIA must be SSL-enabled, meaning that it sends SSL data to the AppServer or
BrokerConnect that is to process the client requests. To configure the AIA to send SSL
requests, you set the property sslEnable=1. You set this property by checking the Enable
SSL AppServer connections box in the SSL properties category in the Progress Explorer,
or by manually editing the ubroker.properties file. In addition, you must obtain and
install public key certificates for the AIA host machine.
A given AIA instance handles only one type of client request, either HTTP or HTTPS. The
following results occur if the AIA receives a request via the incorrect protocol:
3–5
Configuring and Managing the AppServer Internet Adapter
To obtain additional information about SSL operations, refer to the following sources:
• For more information on SSL support in OpenEdge, see OpenEdge Getting Started: Core
Business Services.
• For more information on setting properties for the AIA and other Unified Broker products,
see the Progress Explorer help or the
OpenEdge-Install-Directory\properties\ubroker.properties.README file.
• For more information on managing digital certificates for 4GL clients, see OpenEdge
Deployment: Managing 4GL Applications.
• For more information on managing digital certificates for Open Clients, see OpenEdge
Development: Open Client Introduction and Programming.
3–6
Installing and configuring Web servers and Java servlet engines
A JSE must be installed for each Web server that you are using. How the JSE is installed and
configured to run AIA depends on the JSE and the Web server. The information you provide
during the installation and configuration varies depending on the Web server and JSE. However,
the following reflects some of the tasks you must perform and the information you must provide
when you install and configure a JSE for the AIA:
• Create a servlet instance for each AIA entry in the ubroker.properties file, and use
com.progress.aia.Aia for the ClassName property. Then use the following values for the
Init Arguments for each instance of the servlet:
– instanceName = Name that you specified for the AIA instance in the
ubroker.properties file.
– Optionally set up a virtual path extension to point to AIA. For example, you could
use a virtual path of /aia/Aia. Progress Software Corporation strongly recommends
that you define a virtual path.
Note: The values you enter are case sensitive, so you must enter the values to meet the
requirements of the platform you use.
3–7
Configuring and Managing the AppServer Internet Adapter
On UNIX only, you must add the following environment variables to the script that starts the
JSE:
– Add:
– Add:
Note: This is the path to the work directory you specified when you installed
OpenEdge.
– Add:
LD_LIBRARY_PATH = OpenEdge-Install-Directory/lib:$LD_LIBRARY_PATH;
export LD_LIBRARY_PATH
Note: Depending on your operating system, the library path variable might differ
(for example, LIBPATH, SHLIB_PATH, and so on).
3–8
Installing and configuring Web servers and Java servlet engines
You must restart your JSE and Web server for these changes to take effect. After you have
completed these steps, test the AIA configuration using a Web browser with the following URL:
Syntax
http://Host:Port/Path
Host
Port
Path
Identifies the virtual path and servlet name used to invoke the JSE and the AIA and must
include the following information:
– A virtual path that the JSE has configured within the Web server to recognize and
pass directly to the JSE instead of looking for that directory on the Web server.
The specification of the Path depends on your Web server and JSE. For more information, see
the “Configuring AIA components” section on page 3–10 and the documentation for your Web
server and servlet engine.
http://Host:Port/aia/Aia
For instructions on installing and configuring a specific JSE, see the documentation for that JSE.
For more specific information about configuring the AIA with JSEs, see the Release Notes and
the Progress Knowledge Base on the Web (http://www.progress.com/support). For
information about the configuration tasks you must complete to use the AIA with WebClient,
see the Progress Knowledge Base on the Web (http://www.progress.com/support).
3–9
Configuring and Managing the AppServer Internet Adapter
At the client machine, the Root Certification Authority (CA) certificate for all server certificates
must be installed before HTTPS can be used. For WebClients and 4GL clients, the Root CA
certificates must be installed in the OpenEdge-Install-Directory/certs directory, where
OpenEdge-Install-Directory identifies the directory where OpenEdge is installed. Root CA
certificates for publicly available and well-known CAs, such as Verisign©, are automatically
installed into the OpenEdge-Install-Directory/certs directory during the OpenEdge
installation.
For more information about OpenEdge SSL support, see OpenEdge Getting Started: Core
Business Services. Also see the “Security considerations for AIA administration” section on
page 3–4.
Note: The configuration information is loaded the first time that instance of an AIA is started,
and the AIA continues to use that configuration information until it is stopped and
restarted by the JSE.
This section describes how to configure an AIA instance by using the Progress Explorer and by
editing the ubroker.properties file.
3–10
Configuring AIA components
1. Make sure that the AdminServer process is running on each of the following machines:
On UNIX, use the proadsv command to start the AdminServer. To check whether the
AdminServer is running, run the ps command to show the full command line for each
process on the system and locate any jre commands in the list. The AdminServer process
is running if you see a jre command with the arguments that correspond to those specified
for jvmstart in the OpenEdge proadsv shell script located in
OpenEdge-Install-Directory/bin.
For more information on using the PROADSV utility, see the “PROADSV” section on
page B–17.
For more information on starting the AdminServer, see OpenEdge Getting Started:
Installation and Configuration.
2. In the Progress Explorer, connect to the running AdminServer processes that you verified
in Step 1. After you connect to a machine running an AdminServer process, its host name
or IP address appears as a folder in the tree view.
3. Expand each machine folder to see a list of folders showing all OpenEdge server products
installed on the machine.
3–11
Configuring and Managing the AppServer Internet Adapter
4. If you are using the NameServer, select the NameServer product folders where you want
to configure NameServers and configure one or more such instances to support all AIA
instances you want to configure. Note that for every AIA instance that you plan to run on
a separate machine from its controlling NameServer, you must configure a remote
NameServer instance on the same machine as the AIA. This remote NameServer instance
must reference the host and port of the controlling NameServer for the AIA. For more
information, see the chapter on configuring OpenEdge Unified Broker products in
OpenEdge Getting Started: Installation and Configuration.
5. Select the AIA product folders where you want the AppServer instances to reside. If you
are using the NameServer, configure the instances to register with the controlling
NameServer (with or without load balancing). Specify any application service names
required for clients to access the AIA and any other required configuration information.
For more information, see the “Configuring an AIA with the Progress Explorer” section
on page 3–12.
The sections that follow describe the basic steps for configuring each AIA instance. For more
information, see the Progress Explorer online help.
1. Make sure the AdminServer is running on the host where you want to configure the AIA
(see the “General steps for using the Progress Explorer to configure an AIA instance”
section on page 3–11).
3. Connect to the AdminServer on your AIA host (see OpenEdge Getting Started:
Installation and Configuration).
3–12
Configuring AIA components
• To define a new AIA, select the AIA folder in the Progress Explorer’s tree view,
right-click, and choose New. Enter a unique name for the AIA and click OK. Then
open the property editor for the new instance by selecting the instance, right-clicking,
and choosing Properties.
• To modify an existing AIA configuration, expand the AIA folder in the tree view,
select the AIA instance you want to modify, and open the AIA property editor.
The AIA instance property editor shows a tree view of property categories on the left and
the properties for the selected category on the right.
5. Select a property category and set the properties as required. You can accept the default
values, if they are appropriate for your application. You probably want to specify the
properties under each category. See the Progress Explorer online help for detailed
information about the following categories:
3–13
Configuring and Managing the AppServer Internet Adapter
• Logging Setting — You can set the following logging options: specify a different
pathname from the default for the broker log file; specify the level of logging detail;
control whether the logging for a session appends to or overwrites the previous
broker log file; specify a comma-separated list of logging entry types to be included
in the broker log file, choosing from the valid values listed in the Progress Explorer
online help; set a file-size threshold that determines the point at which a new log file
is created (0 = unlimited log file size); and specify the maximum number of broker
log files to be kept (0 = unlimited number of log files retained). See OpenEdge
Development: Debugging and Troubleshooting for detailed information on logging
options.
• SSL — Check the Enable SSL AppServer Connections box if you want the AIA
to be SSL-enabled; that is, to use SSL tunneling when connecting to the AppServer
or BrokerConnect. If the AIA is SSL-enabled, you can optionally check the
remaining boxes to disable host name verification and to prevent clients from
requesting reuse of the session ID for successive connections to the same AppServer
or BrokerConnect. (Leaving the Disable SSL Session Reuse box unchecked does
not guarantee that session IDs can be reused, because the server might disallow
session reuse.)
3–14
Configuring AIA components
The AIA configurations in ubroker.properties can include the entities listed in Table 3–2.
For complete definitions of all the properties and detailed information on how to set them, see
the ubroker.properties.README file, as well as the comments included in the properties file
itself. Both files reside in the properties directory.
If you use a tool other than Progress Explorer to edit the values in the ubroker.properties file,
you can use the AIACONFIG command to validate the changes made to the ubroker.properties
file for an AIA instance.
3–15
Configuring and Managing the AppServer Internet Adapter
Syntax
aiaconfig[
[ [ -name AIA-instance-name ]
[ -propfile path-to-properties-file ]
[ -validate ]
] | -help ]
Note: If you upgrade to a new version of OpenEdge, you might want to retain changes made
to the previous version’s ubroker.properties file. If that is the case, place the old
properties file in the installed properties directory to replace the default. When
starting the AdminServer for the first time, a properties file conversion utility
automatically runs.
For more information on the AIACONFIG command, see the “AIACONFIG” section on
page B–6.
3–16
Viewing AppServer Internet Adapter connection and configuration information
Syntax
http://Host:Port/Path
For more information on this URL, see the “Installing and configuring Web servers and Java
servlet engines” section on page 3–6.
Note: By default, the allowAiaCmds property in the ubroker.properties file is turned off
(set to 0) for security reasons. If you want to test the AIA using a browser, you must
change the allowAiaCmds value to 1, and then stop and restart the JSE.
The Path used to view connection and configuration information depends on how you configure
your Web server and Java servlet engine. In these examples, the Path was configured based on
the default configuration used by OpenEdge. The first line verifies that AIA is configured
correctly and is being successfully executed by the JSE. If you cannot run this example, there is
a problem with the configuration. The second line provides status information about AIA, as
shown:
http://Host:Port/aia/Aia
http://Host:Port/aia/Aia?GetServletStatus
Connection status
The connection status provides dynamic information about each client connection. This sample
shows status information using the following URL:
http:/starbuck:84/aia/Aia
3–17
Configuring and Managing the AppServer Internet Adapter
Connection information provides you with information about that AIA configuration. If the
AIA is configured correctly, the following information is displayed:
• The first line shows that the AIA servlet was accessed successfully.
• The second line, Connection Pool, shows the current and total connections to the AIA
servlet since startup.
• The third line shows the current connection information including the thread number, the
AppServer and IP address, total number of connections, and the date and time the servlet
was last accessed.
Configuration information
Configuration information comes from the ubroker.properties file. This sample shows
configuration information using the following URL:
http://starbuck:84/aia/Aia?GetServletStatus
3–18
Viewing AppServer Internet Adapter connection and configuration information
Figure 3–2 shows AIA configuration information for the previous sample URL.
3–19
Configuring and Managing the AppServer Internet Adapter
• User Info — Identifies the user. This information displays either just the user name, the
user name and password, or the value None.
• Host:Port — Host and port of the client process using the connection.
3–20
Part III
Web Services Adapter Administration
After OpenEdge is installed, you might have to perform one or more post-installation
configuration tasks for the Web Services Adapter (WSA) in order to deploy Progress 4GL Web
services. You can configure the WSA at three different levels:
1. The Web application level of the Java servlet engine (JSE) where the WSA is installed.
You can define multiple Web applications, each of which can run multiple instances of the
WSA.
2. The WSA instance level of a single JSE Web application. Here, you can specify
parameters that affect the JSE environment and execution of a single WSA instance.
3. The WSA instance within the OpenEdge environment. Here you can manage the
OpenEdge side of WSA creation and execution, using the Progress Explorer framework.
Use the command for your operating system, as shown in Table 4–1.
3. Update your JSE configuration files to refer to the new WSA sample Web application
directory. For more information, see the “Configuring the JSE to recognize the WSA”
section on page 4–3. In general, you need to restart the JSE (or Web server) for the new
configuration settings to take effect.
4–2
Configuring the JSE to recognize the WSA
4. If you plan to deploy Web services to WSA instances created in the new sample Web
application directory, destination-directory/wsa, you can proceed with deployment
immediately after completing Step 3. In this case all Web services are deployed to a WSA
instance directory within destination-directory/wsa. However, if you want to specify
a separate Web service deployment directory for any WSA instance created for the Web
application, you must update the Web application descriptor file to specify a new
deployment directory for that instance. For more information, see the sections on changing
the Web service deployment directory in Chapter 6, “Deploying and Managing Progress
4GL Web Services.”
To increase this allocation pool, set the -Xmxsize JVM startup option to a higher value. For
example, you might set the value to 512 MB by specifying this option as -Xmx512m.
For more information on this option and JVM memory management, see the documentation on
tuning garbage collection with the JVM available at the Java Web site (http://Java.sun.com).
4–3
Configuring a Web Services Adapter Installation
• WSA administrators.
• Client developers.
For more information on these security settings, including instructions for modifying them, see
Chapter 7, “Web Services Adapter Security Configurations.”
The WSA supports SSL communications with the AppServer with the use of a secure protocol.
You control the default protocol for services deployed to a WSA instance by setting the value
of the appServiceProtocol property in the default.props file. To enable SSL tunneling, you
specify either AppServerS (if the service is registered with a NameServer) or AppServerDCS (for
direct connection to the AppServer) as the protocol. For more information, see the “Security
considerations for Web service administration” section on page 6–3.
Note: The procedure that follows pertains to the security of communication between the
client application and the WSA. To enable SSL communication between the WSA and
the AppServer, you must obtain and install public key certificates for the WSA host
machine and complete separate configuration procedures for each deployed service
and for the AppServer. See the “Security considerations for Web service
administration” section on page 6–3 for more information.
4–4
Enabling the WSA for HTTPS client connections
This includes installing the Web server digital certificate in the Web server. For more
information, see the Web server documentation.
3. Using a text editor, modify the web.xml file for the WSA as follows:
4. Using a text editor, edit the ubroker.properties file to set the WSA URL (value of the
wsaUrl property) to use the HTTPS protocol (instead of HTTP).
4–5
Configuring a Web Services Adapter Installation
4–6
5
Managing the Web Services Adapter
The Web Services Adapter (WSA) is a Java servlet running within a Java servlet engine (JSE).
You can manage the WSA using the Progress Explorer framework, including the Progress
Explorer, WSAMAN utility, and the WSACONFIG utility. The WSA serves as the gateway and
management engine for your Web service. It provides user access to the Web Services
Description Language (WSDL) file, supports all required Web service administration, and
manages the exchange of Web service Simple Object Access Protocol (SOAP) requests and
responses between the Web service and Web service clients at run time.
You must configure the WSA and create and configure WSA instances before you can deploy
Web services to them. This chapter contains the following sections:
The WSA includes extensive security features, which this chapter introduces, but for more
detailed information on WSA security, see Chapter 7, “Web Services Adapter Security
Configurations.”
Managing the Web Services Adapter
• Constructing URLs
Note: For a complete overview of Progress 4GL Web services architecture and how the WSA
supports Web services, see OpenEdge Getting Started: Application and Integration
Services.
• On the system where the JSE is running, install the WSA component of OpenEdge.
• On the system where the AdminServer to administer the WSA is running, install the Web
Services Admin Enabler component. The AdminServer can reside on the same machine as
the WSA (local) or on a separate machine (remote).
For more information on installing these components and related products, see OpenEdge
Getting Started: Installation and Configuration.
5–2
WSA administration architecture
Figure 5-1 shows the components used to configure and manage a WSA in its environment.
Web server
Progress (optional)
AdminServer Internet or
Explorer or
Intranet
WSAMAN JSE
WSA context
WSA
ubroker.properties
wsa1 wsa1
default .props
wsa2 wsa2
default .props
When the WSA runs within the context of a JSE or Web server, several WSA instances can run
within the context of the WSA Web application (such as wsa1 and wsa2 shown in Figure 5-1).
In addition to the WSA Web application other Web applications can run within the JSE,
including additional WSA instances.
5–3
Managing the Web Services Adapter
2. The Web server comprises one or more JSEs (web-server-context) and one or more
non-JSE Web resources, such as static HTML pages.
3. Each JSE comprises one or more WSA Web applications (wsa-webapp-context) and one
or more non-WSA Web applications.
4. Each WSA Web application comprises one or more WSA instances (wsa-instance).
If the JSE runs stand-alone (that is, with an integrated Web server), the JSE-based WSA
configuration is:
5–4
WSA administration architecture
Constructing URLs
In this manual, the URL path to a specific WSA instance is referred to as wsa-root-url. When
you install the WSA, the installation procedure prompts you for a wsa-root-url value for the
sample WSA instance (wsa1). Thereafter, every time you create a new WSA instance you must
provide a new wsa-root-url value for that instance. The value is stored in the wsaUrl property
in ubroker.properties.
Syntax
http[s]://host:port[/web-server-context]/wsa-webapp-context/wsa-instance
Note: If the WSA URL host is named localhost, it must be changed to the name of the host
machine when Web services are deployed for network access.
In the above syntax, use the optional element, /web-server-context, if the WSA runs in a JSE
that runs in a separate Web server. Omit the optional element if the WSA runs in a JSE that runs
stand-alone.
In order to create a WSA instance, you need to construct the URL for the wsa-root-url. The
URL components in the syntaxes each describe a specific part of the WSA instance
configuration, as shown in Table 5–1.
5–5
Managing the Web Services Adapter
For example, consider the sample Web service system elements and aliases in Table 5–2.
web-server-context bedrock
wsa-webapp-context quarry
wsa-instance fred
• The WSA running in the context of the JSE running in the context of a separate Web server
has the following URL:
http://servicehost:80/bedrock/quarry/fred
• The WSA running in the context of the JSE running stand-alone has the following URL:
http://servicehost:8080/quarry/fred
Any URL subpaths specified by the client that lie beyond wsa-root-url are delivered to the
WSA instance for it to interpret and use. For example, to access the WSDL documents
associated with a particular WSA instance, append the /wsdl subpath to wsa-root-url, as
shown in bold:
http://servicehost:80/bedrock/quarry/fred/wsdl
Given this URL, an HTTP message travels through the Web server, through the JSE, then to the
WSA instance, fred. Then, the WSA instance is passed the relative path, /wsdl, which tells it
to perform a WSDL-related operation.
5–6
WSA administration architecture
. . . /WSA-web-application-directory
[ optional static html pages ]
.
.
.
WEB-INF/
web.xml ( WSA Web application descriptor file )
lib/
wsa.jar
soap.jar
[ any additional WSA Web application jar files ]
.
.
.
classes/
[ optional Java .class files ]
.
.
.
The WSA Web application consists of a subdirectory named WEB-INF (the name is case
sensitive) that contains the Web application descriptor file (web.xml) and two subdirectories for
holding Java class files and Java jar files. The WSA Web application does not contain any class
files, but does include several jar files. These form a single Web application that can contain one
or more WSA instances. A JSE can contain multiple WSA Web applications, and each Web
application can contains multiple WSA instances.
5–7
Managing the Web Services Adapter
Configuring a WSA Web application involves editing its web.xml file, an XML-based file that
must conform to the JSE version’s document type definition (DTD) published by Sun
Microsystems, Inc. You might have to manually edit web.xml to set WSA instance security or
to add a WSA instance to the WSA Web application. For a full description of the web.xml file,
see Sun’s JSE specifications.
Note: These steps assume that the sample WSA Web application provided with OpenEdge is
installed in the OpenEdge-Install-Directory/servlets/wsa directory.
1. If you are running a production server, or if you do not want to lose your deployed Web
services when installing another version of OpenEdge, copy the entire sample WSA Web
application directory tree to another disk location, outside the OpenEdge installation
directory. For an example of how this might be done see the information on copying the
WSA sample Web application in Chapter 4, “Configuring a Web Services Adapter
Installation.”
2. Configure the JSE to recognize the WSA Web application. Depending upon the JSE, you
might have to edit one of its configuration files or install the WSA Web application by
using a browser-based administration interface. In addition, each JSE typically has a
directory where a Web application resides. See your JSE vendor’s documentation for the
specific directory name and a discussion of Web applications.
Note: If a Web application installation procedure requests the path to the Web application
deployment file, enter the path to the WSA Web application. For example, the Web
application deployment path created during OpenEdge installation is
OpenEdge-Install-Directory/servlets/wsa.
5–8
Creating one or more WSA instances
3. If you chose to enable security when you installed the WSA Web application sample, you
must now define the WSA administration user names and roles in the JSE. For more
information, see your JSE vendor’s documentation. The WSA comes preconfigured to use
the role definitions PSCAdmin and PSCOper (case-sensitive). With security enabled, the
WSA requires the JSE to authenticate and authorize a user before passing the HTTP
request to the JSE for handling. For more information on WSA security, see Chapter 7,
“Web Services Adapter Security Configurations.”
1. In the Progress Explorer’s left pane, right-click on the Web Services Adapter, and click
New as shown:
5–9
Managing the Web Services Adapter
b. Select Local or Remote, depending on whether the WSA is local or remote to the
AdminServer.
c. Choose OK.
When the Progress Explorer’s left pane appears, it now contains the new WSA instance:
5–10
Creating one or more WSA instances
3. In the Progress Explorer’s left pane, highlight the new WSA instance, right-click, and
select Properties. A properties dialog box for the new appears WSA instance, like the
following:
In the left pane, the property categories that you can select (those not grayed out) depend
on whether the WSA instance is local or remote, as shown in the following table:
If the WSA instance is... The categories you can select are...
Local • Location
• Proxy Server Setting
• WSDL
• Logging Setting
• Security
• Advanced Features
Remote • Location
• Proxy Server Setting
• Advanced Features
5–11
Managing the Web Services Adapter
4. If the WSA instance is remote, perform the following additional steps on the system where
the WSA is installed:
a. In the ubroker.properties file, copy and rename the section corresponding to the
sample WSA instance provided (wsa1) to a new section—in essence, cloning wsa1’s
section to a new section.
b. Then, edit the properties in the new WSA instance’s section as desired.
5. In the web.xml file, use a text editor (or whatever tool your JSE provides), to copy and
rename the section corresponding to the sample WSA instance provided (wsa1) to a new
section—in essence, cloning wsa1’s section to a new section.
Then, check and perhaps modify the web.xml items listed in Table 5–3.
Check this attribute ... Which indicates ... And whose default is ...
5–12
Creating one or more WSA instances
Check this attribute ... Which indicates ... And whose default is ...
Progress Software Corporation recommends that you use names consistently when you name a
remote WSA instance and when you edit entries corresponding to the remote WSA instance in
the ubroker.properties and web.xml files.
5–13
Managing the Web Services Adapter
2. Following the instructions for your specific JSE, start the WSA as a Web application. See
your JSE vendor’s documentation for information about starting and running a Web
application.
Note: Depending on the behavior of a specific JSE, starting the JSE might automatically
start the WSA.
5–14
Starting and testing a WSA instance
1. Confirm that the WSA instance started correctly by checking for the presence of the files
and directories in the following table:
2. Confirm that the WSA is responding by pointing a Web browser at the WSA instance’s
URL (wsa-root-url).
http://servicehost:8080/wsa/wsa1
The test is successful if you receive a WSA Web Services OK HTML page.
5–15
Managing the Web Services Adapter
Table 5–4 lists, by category, the properties of a WSA instance that reside in the
ubroker.properties file. For more information on these properties, see the Progress Explorer
online help.
Category Property
5–16
Configuring and managing a WSA instance
Category Property
5–17
Managing the Web Services Adapter
• debugClients
• enableWsdl
• enableWsdlListings
• loggingLevel
• logMsgThreshold
• webAppEnabled
Any modifications to these properties take affect immediately, but do not remain once the WSA
is restarted. Changing these properties at run time does not save the new properties values. To
make the run-time properties changes persistent you must also change the values of the startup
properties.
To modify the run-time properties of a WSA instance, you can use Progress Explorer or the
WSAMAN utility. To modify the startup properties of a WSA instance, use Progress Explorer. For
more information on the Progress Explorer, see For more information on the WSAMAN utility, see
Chapter 8, “Using the WSA Management Utility (WSAMAN)” and Appendix B, “Command
and Utility Reference.”
At times, you might find that in order to update a WSA configuration, you must edit the
ubroker.properties file by hand using a text editor, especially when you need to update the
WSA security configuration. When you complete a manual update of the ubroker.properties
file, use the WSACONFIG utility to verify the integrity of the WSA configurations in the file.
Note: You can also use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
The WSACONFIG utility displays the property settings associated with WSA configuration, and
checks that the syntax and values are valid. You must run the WSACONFIG utility locally on the
machine on which the WSA is running. The utility does not run across the network.
5–18
Configuring and managing a WSA instance
Syntax
wsaconfig[
[ [ -name WSA-instance-name ]
[ -propfile path-to-properties-file ]
[ -validate ]
] | -help ]
For more information on the WSACONFIG utility, see “WSACONFIG” section on page B–19.
For example, the following command validates the syntax and views the configurations of all
WSA instances defined within the test.properties file located in the current working
directory:
Statistic Description
Number of HTTP requests Total requests received from the HTTP listener, including
administrative, WSDL, and Web service requests.
5–19
Managing the Web Services Adapter
Statistic Description
Number of services disabled Web services deployed to this WSA that are disabled from
client access.
Number of errors Total errors returned by the WSA, with error counts broken
out at the bottom of the list for each of several error
categories when total errors are greater than 0.
When you first run a WSA instance, it creates a default.props file that contains a collection
of properties assigned to each Web service deployed to the WSA instance. For additional
information about the default values for Web services properties and how to change them, see
Chapter 6, “Deploying and Managing Progress 4GL Web Services.”
5–20
6
Deploying and Managing Progress 4GL
Web Services
After the developer uses ProxyGen to define a Web service and create a Web Service Mapping
(WSM) file, and after you create a Web Services Adapter (WSA) instance, you initialize the
WSA instance’s default Web service properties, deploy the Web service to the WSA instance,
enable the Web service, and finally configure the Web service.
This chapter describes how to deploy Web service using the WSA in the following sections:
For information on using ProxyGen to generate a WSM file for Web service deployment, see
OpenEdge Development: Open Client Introduction and Programming.
Deploying and Managing Progress 4GL Web Services
Table 6–1: Setting the WSA instance’s default Web service properties
6–2
Initializing a WSA instance’s default Web service properties
For more information on modifying the default Web service properties of a WSA instance,
including a full list of default properties, see the Progress Explorer online help, or see Chapter
8, “Using the WSA Management Utility (WSAMAN)” and Appendix B, “Command and Utility
Reference.”
The first connection is Internet-based between the WSA and the client. See the “Enabling the
WSA for HTTPS client connections” section on page 4–4 for information about making this
connection secure. In brief, the following conditions must be met:
• The WSA must be HTTPS-enabled; that is, it must be configured to accept HTTPS
requests from clients (via the JSE or Web server).
• A private key and a Web server digital certificate must be installed on the Web server, and
the Web server must be configured for SSL support.
The second connection is via AppServer protocol between the deployed service and the
AppServer. For this connection to be secure, the following conditions must be met:
• You must obtain and install public key certificates for the WSA host machine.
• The service must send SSL requests to the AppServer that is to process the client requests.
To configure the service to send SSL requests, you set the value of the
appServiceProtocol property to AppServerS or AppServerDCS. You set this property,
either for a specific service or as the default for services deployed to a given WSA
instance, by using the Progress Explorer or by manually editing the
WebServiceFriendlyName.props file or the default.props file. (Note that this property
applies to deployed services, not to the WSA itself; for more information on configuring
WSA security, see Chapter 7, “Web Services Adapter Security Configurations.”)
6–3
Deploying and Managing Progress 4GL Web Services
• The AppServer must be SSL-enabled, meaning that it accepts SSL requests from the WSA
(or other clients). You set the property sslEnable=1 by checking the Enable SSL Client
Connections box in the SSL General properties category in the Progress Explorer, or by
manually editing the ubroker.properties file. You must also obtain and install a server
private key and public key certificate and set additional SSL server properties. See the
“SSL-enabled AppServer operation” section on page 2–9 for more information.
For more information on SSL support in OpenEdge, including configuring and operating a Web
service as a client of an SSL-enabled AppServer, see OpenEdge Getting Started: Core Business
Services.
You can set the following properties, either as defaults for services deployed to a given WSA
instance or as properties of a specific service:
• noHostVerify — Controls whether the WSA compares the host name of the connecting
AppServer with the Common Name specified in the server digital certificate.
• noSessionReuse — Controls whether the service requests reuse of the session ID for
successive connections to the same AppServer.
For more information about these and other service properties, see Appendix A, “Reference to
Progress 4GL Web Service Properties.”
6–4
Deploying a Web service
1. In the Web Services Adapter (WSA) folder, expand the WSA instance where you want to
deploy the Web service. The Web Services folder appears under the expanded WSA
instance. Right-click the Web Services folder. A shortcut menu appears. Choose Deploy
A New Web Service, as shown:
You can also Select the Web Services folder; click the Deploy a New Web Service button
or choose Action→Deploy A New Web Service.
6–5
Deploying and Managing Progress 4GL Web Services
Enter the path name of the WSM file for the Web service that you want to deploy. You can
also use the Browse button to select and enter the filename from the appropriate directory.
Choose the Continue button to continue the deployment. This displays the Deploy:
Deployment Information dialog box, as shown:
The initial values in the dialog box are set from existing information in the WSM file, and
you can change them as necessary.
6–6
Deploying a Web service
2. Make any necessary changes to the values in the Deploy: Deployment Information
dialog box. The fields you can change are listed in Table 6–2.
Field Description
Web Service A namespace used to uniquely identify the Web service to the WSA
Namespace instance where the Web service is deployed.
SOAP Action A string that the client application is required to place in the
SOAPAction HTTP header when accessing a Web service at the
WSA instance. The SOAPAction HTTP header is required for all
HTTP messages that carry SOAP messages and is used by
intervening security servers (such as firewalls) to determine if each
HTTP message is allowed to pass through to its destination. The
default is a blank string, but can be any string required by the
intervening security servers on the network.
Append to Indicates whether to append the object name to the SOAP Action
SOAP Action value.
WSDL Specifies the SOAP format to use when sending or receiving SOAP
Style/Use messages for this Web service. The value that you choose depends
entirely on what your anticipated Web service clients can support.
To deploy the Web service with these settings, choose OK. An information box appears
verifying that the deployment has completed.
6–7
Deploying and Managing Progress 4GL Web Services
For example, Table 6–3 shows how you might represent the first version of the Web service.
Deployment
information Value
Name OrderInfo-RpcEncoded-0001
Table 6–4 shows how you might represent the second version of the Web service.
Deployment
information Value
Name OrderInfo-RpcEncoded-0002
6–8
Deploying a Web service
File Description
friendlyname.props An XML file containing the current Web service property settings
(initially set from default.props).
friendlyname.wsad The Web Service Application Descriptor (WSAD) XML file that
defines the Web service to the WSA instance.
friendlyname.wsdl The WSDL XML file that defines the Web service to potential Web
service clients.
During development, you can change the definition and deployment information of a deployed
Web service using a Web service update. You can use Progress Explorer or WSAMAN to do this.
However, once deployed and enabled for client access under production conditions, avoid
making any changes to this information, as client implementations depend on its stability.
To make the same Web service available using different information after production
deployment (for example, to add a new operation or use a different SOAP Message Style),
deploy a new Web service with the new information by using a different Web service name and
target namespace at the same WSA instance (similar to versioning a Web service), or by
deploying the Web service to a different WSA instance.
However, you can always change the run-time properties of a deployed Web service at any time,
but most properties require that you first disable the Web service. For more information, see the
Progress Explorer online help, Chapter 8, “Using the WSA Management Utility (WSAMAN),”
Appendix B, “Command and Utility Reference,” and Appendix A, “Reference to Progress 4GL
Web Service Properties.”
6–9
Deploying and Managing Progress 4GL Web Services
You can change the deployment directory for all Web services deployed to a given WSA
instance by modifying the Web application descriptor file (web.xml). For a description of this
file, see the information on the WSA as a Web application in Chapter 5, “Managing the Web
Services Adapter.” This file is initially installed at the following OpenEdge installation location
for the WSA sample Web application:
OpenEdge-Install-Directory/servlets/wsa/WEB-INF/web.xml
Note: These instructions assume that you have not changed the sample WSA Web
application directory from its installed location.
6–10
Changing the Web service deployment directory
To specify a new deployment location for the Web services of a WSA instance:
1. Open the web.xml that defines the WSA servlet instance for editing in a text editor.
2. Locate the following XML in the file by searching for "deploymentDir" within the servlet
definition for your WSA instance:
<servlet>
<servlet-name>wsa1_servlet</servlet-name>
<display-name>Web Services Adapter servlet 1</display-name>
<!-- Enter an optional description of the Web Services Adapater
servlet and uncomment this element if supported by the JSE
3. Remove the XML comment tags around the <init-param> element and specify the new
deployment directory as the <param-value> element value (C:/work/deployment/).
5. If you have any existing deployed Web services for this WSA instance, move the existing
WSA instance directory to the new deployment directory. For example, if the WSA
instance directory is wsa1, move the entire directory subtree to the new deployment
directory as follows, using the appropriate operating system commands:
OpenEdge-Install-Directory/servlets/wsa/wsa1/*→
C:/work/deployment/wsa1/*
You can now deploy and otherwise manage Web services for the WSA instance, wsa1.
6–11
Deploying and Managing Progress 4GL Web Services
1. In the WSA folder, select the Web service instance (wsa1), expand it.
2. Select a Web service, such as OrderInfo under the Web services folder, and right-click it.
When a shortcut menu appears, choose Enable, as shown:
You can also choose the Enable button, or choose Action→Enable from the menu.
An information box appears confirming that you have enabled the Web service for client
access. If the Web service was previously disabled, this also decrements the number of
Web services disabled statistic for the parent WSA instance.
6–12
Administering a deployed Web service
Note: The WSA must have the Enable Web Services box checked before it accepts client
requests for the enabled Web service. To check the Enable Web Service box for a
local WSA instance, use Progress Explorer. For a remote WSA instance, set the
underlying webAppEnabled property by hand editing the ubroker.properties file.
For more information, see Chapter 5, “Working With the Web Services Adapter.”
Action Description
Disable and enable it. Makes the Web service unavailable to Web service clients;
makes it available again.
Export and import it. Creates a backup file of the deployed Web service; uses the
information in the backup file to deploy a Web service.
Note: Export creates a Web Service Definition (WSD) file;
import requires an existing WSD file.
Get and set its properties. Provides the value of its properties; resets one of its
properties.
Get and reset its statistics. Displays the value of each Web service statistic; reinitializes
the statistics.
Query its deployment Provides the Web service’s status (enabled or disabled),
information and display its friendly name, namespace, SOAP action, and SOAP
status (enabled or disabled). message style.
Update it. Lets you change the Web service’s WSM file without
undeploying and redeploying it.
Undeploy it. Removes the files created when the Web service was
deployed.
To perform these functions, you can use the Progress Explorer or the WSAMAN utility. For more
information, see the Progress Explorer’s online help, Chapter 8, “Using the WSA Management
Utility (WSAMAN),” and Appendix B, “Command and Utility Reference.”
6–13
Deploying and Managing Progress 4GL Web Services
Notes: The WSD file contains a complete copy of the Web service properties of the original
Web service. When an import is performed, the imported Web service has the same
properties as the original.
An import requires the WSD file be accessible to the local machine. An export
produces the WSD file accessible to the local machine—that is, the machine where the
Progress Explorer or the WSAMAN utility run.
For more information exporting and importing Web services using the Progress Explorer, see
the Progress Explorer online help.
For more information on exporting and importing Web services using the WSAMAN utility, see
Chapter 8, “Using the WSA Management Utility (WSAMAN)” and Appendix B, “Command
and Utility Reference.”
6–14
Monitoring and tuning Web services
Statistic Description
Number of Errors Total errors returned for requests to the Web service,
with errors broken down for each of several error
categories after the first error is reported.
Number of Proxy AppObjects Total AppObjects registered for all clients of this Web
service.
Number of Proxy ProcObjects Total ProcObjects registered for all clients of this Web
service.
For more information on the statistics of a Web service, see Progress Explorer’s online help.
If the Web service uses a NameServer and is session free, the Web service has a connection
pool, with properties you can adjust. If the Web service is session managed, it can be set to store
multiple requests to the service or repeat them. In either case, for more information, see
Appendix A, “Reference to Progress 4GL Web Service Properties” and the Progress Explorer
online help.
6–15
Deploying and Managing Progress 4GL Web Services
Production environment
1. Deploy the new version of the Web service with a new friendly name, and new target
namespace.
3. Notify clients that the new version of the Web service is available, and instruct them to
update their clients based on the new WSDL.
4. Once there are no clients using the old version of the Web service, disable it.
5. Export the Web service, to create a backup. This provides a WSD file of the original
version.
6–16
Typical Web service administration scenarios
Development environment
2. Export the Web service. This provides a WSD file of the original version, to create a
backup.
Caution: Progress Software Corporation recommends you never use the Update function in a
production environment.
1. Notify all clients that the Web service is going to be disabled at a certain time.
4. Modify the Web service’s properties, as desired, using the Progress Explorer or the WSAMAN
utility’s setprops function.
You do not have to disable and enable a Web service to modify its serviceLoggingLevel
property, which changes the level of information provided in log messages, or its
serviceFaultLevel property, which changes the level of information provided in SOAP Fault
response messages. For more information, see the information on debugging Progress 4GL Web
services in OpenEdge Development: Web Services.
6–17
Deploying and Managing Progress 4GL Web Services
6–18
7
Web Services Adapter Security
Configurations
This chapter provides an overview of the security provided by the Web Services Adapter
(WSA), describes its initial settings, and provides an alphabetical list of configuration
instructions for a variety of situations, as described in the following sections:
• Overview
• Initial settings
Overview
When WSA security is enabled, the JSE and WSA work in tandem to authenticate the Web
service client and to check that the client has the privileges to execute the requested operation.
To continue the example, when the JSE intercepts an HTTP request destined for the WSA
instance’s Web service application URL:
1. The JSE performs HTTP Basic authentication using the user’s ID and password.
2. If the user ID and password are valid, the JSE checks that the user ID has been granted
access to the Role WsaWebServicesUser.
3. If the user ID has been granted access, the JSE passes the HTTP request and the
authenticated user ID to the WSA.
7–2
Overview
To continue the example, when the WSA gets an HTTP request from the JSE:
1. The WSA first checks its ubroker.properties values to determine whether the URL
requires the JSE to perform user authentication.
2. If it does, the WSA verifies that the JSE has passed it a valid user ID—just in case the JSE
configuration becomes corrupted.
3. When it verifies that it has a valid user ID, the WSA checks whether the URL is for a WSA
administrative function.
a. The WSA determines which Role the user is in and gives the user the security
privileges associated with that Role.
b. The WSA determines whether the user’s privileges allow it to execute the
administrative function. If yes, the administrative function is executed.
If the URL is not for a WSA administrative function, the WSA processes the HTTP/SOAP
request as a web service operation.
When the WSTK installation runs, it tailors the web.xml and ubroker.properties files,
initializing JSE and WSA security as specified during installation. You can use these initial
settings or modify them as desired.
7–3
Web Services Adapter Security Configurations
• Requiring the JSE to perform user authentication and role authorization for any
combination of:
• Disabling the WSA from responding to all user requests from any combination of:
7–4
Initial settings
Initial settings
JSE security is initially set in OpenEdge-Install-Directory/servlets/wsa/web.xml as
shown in Table 7–1.
7–5
Web Services Adapter Security Configurations
Note: A developer might develop and test a Web service using a nonsecure WSA, then (if
necessary) deploy it to a secure WSA or secure the test WSA.
In XML, comments start with the start-comment (<!--) and end with the end-comment (-->)
tag.
To comment out an XML security-constraint, place an XML start-comment before the XML
element tag that begins the entry and place an XML end-comment after the XML tag that
terminates the <security-constraint> element, as in the following example:
<!--
<security-constraint>
...
</security-constraint>
-->
The web.xml file included with the sample Web service application includes embedded
comments with additional information on changes you might need to make.
7–6
Alphabetical list of configuration instructions
• Controlling access to Web services, WSDL, and WSA administration using one JSE
security-constraint
• Disabling access to all Web services, to all WSDL, or to all WSA administration
• Enabling multiple user roles to access Web services, WSDL, or WSA administration
7–7
Web Services Adapter Security Configurations
• WSDL
• WSA administration
Table 7–3: Controlling Web service, WSDL, and administration access using
JSE security constraints
For accessing ... The security-constraint might look like this ...
WSDL <security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/wsdl/*</url-pattern>
</web-resource-collection>
</security-constraint>
7–8
Alphabetical list of configuration instructions
1. Choose user-authorization role-names to identify users who can access your desired
combination of functions.
Syntax
<auth-constraint>
<role-name>name</role-name>
</auth-constraint>
For example, if you want to grant access to all of a WSA’s Web services, WSDL, and
WSA administration and grant access to the user-authorization role-names PSCAdmin and
GuestAdmin, you might modify the security-constraints as shown in Table 7–4.
For
accessing ... The modified security-constraint might look like this ...
7–9
Web Services Adapter Security Configurations
For
accessing ... The modified security-constraint might look like this ...
WSDL <security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/wsdl/*</url-pattern>
<auth-constraint>
<role-name>PSCADmin</role-name>
<role-name>GuestAdmin</role-name>
</auth-constraint>
</web-resource-collection>
</security-constraint>
WSA <security-constraint>
administration <web-resource-collection>
<url-pattern>/wsa1/admin/*</url-pattern/*>
<auth-constraint>
<role-name>PSCAdmin</role-name>
<role-name>GuestAdmin</role-name>
</auth-constraint>
</web-resource-collection>
</security-constraint>
7–10
Alphabetical list of configuration instructions
3. Modify the properties of the WSA instance to require JSE authentication of all users of
your desired combination of functions. The technique for doing so depends on whether the
WSA instance is local (residing on the AdminServer machine) or remote (not residing on
the AdminServer machine):
If the WSA instance is local, using Progress Explorer, select the WSA instance,
right-click, and select Security in the property sheet:
Then, enable the checkboxes on the Security panel to require JSE user authentication of
all users in your desired combination of functions as follows:
7–11
Web Services Adapter Security Configurations
If the WSA instance is remote, edit the ubroker.properties file for the WSA. In the
section for the WSA instance, for each function in your desired combination, set the
property that enables JSE authentication of all users of that function, as shown in Table
7–5.
Table 7–5: Requiring Web service user authorization for Web service,
WSDL, and administration access
WSDL wsdlAuth 1
For more information on the properties of a WSA instance, see the comments in the
ubroker.properties file.
7–12
Alphabetical list of configuration instructions
To change the permissions and action settings for the default administrator:
3. Change the individual permission properties to have the read, write, and delete actions you
choose.
[AdminRole]
apps_defaults=
apps_enable=
apps_props=
apps_stats=
servlet_props=
servlet_services=read
servlet_stats=
7–13
Web Services Adapter Security Configurations
3. Change the individual permission properties to have the read, write, and delete actions you
choose. For example:
[AdminRole.PSCOper]
apps_defaults=read
apps_enable=read
apps_props=read
apps_stats=read
servlet_props=read
servlet_services=read
servlet_stats=read
1. Enable the JSE to authenticate users and grant them access if they hold a membership in
one of your customized administrator roles. To do so, in the WSA’s web.xml file, in the
security-constraint for WSA administration, add a role-name element for each of your
customized administrator roles.
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/admin/*</url-pattern/*>
</web-resource-collection>
</security-constraint>
Syntax
<auth-constraint>
<role-name>name</role-name>
</auth-constraint>
7–14
Alphabetical list of configuration instructions
For example, if you created the new administrator roles tempadmin1 and tempadmin2, you
might modify the security-constraint for WSA administration to appear as follows:
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/admin/*</url-pattern/*>
<auth-constraint>
<role-name>tempadmin1</role-name>
<role-name>tempadmin2</role-name>
</auth-constraint>
</web-resource-collection>
</security-constraint>
2. Add an administrator role to the WSA security. Using a text editor, edit the
ubroker.properties file from which the WSA is initialized:
Each administrator role definition resides in groups that begin with “[AdminRole.”,
followed by the role-name, and ending with “]”.
b. Copy the group once for each new administrator role you want to create.
c. Choose a new role-name. Change the group’s role-name to reflect the new role name.
[AdminRole.PSCAdmin]
apps_defaults=read,write
apps_enable=read,write
apps_props=read,write
apps_stats=read,write
servlet_props=read,write
servlet_services=read,write,delete
servlet_stats=read,write
3. Modify the adminRole property of the WSA to add the new role-names to the list of
role-names. The technique for doing so depends on whether the WSA instance is local
(residing on the AdminServer machine) or remote (not residing on the AdminServer
machine).
If the WSA is local, using Progress Explorer, select the WSA instance. Then, in the WSA’s
Security panel, in the list of Admin roles, add the new role-names.
7–15
Web Services Adapter Security Configurations
If the WSA instance is remote, using a text editor, edit the ubroker.properties file. In
the adminRoles property, add the new role-names to the comma-separated list of existing
role names:
[WSA]
.
.
.
adminRoles=PSCAdmin,PSCOper
If the WSA instance resides locally, using Progress Explorer, highlight the WSA instance,
right-click, and choose Properties. Select Security to bring up the Security panel. Then, select
the fields on the Security panel to disable access to all Web services, all WSDL, or all WSA
administration, as desired. For more information on accessing the Security panel, see the
“Controlling access to Web services, WSDL, and WSA administration using user-authorization
role-names” section on page 7–9.
7–16
Alphabetical list of configuration instructions
If the WSA instance is remote, using a text editor, edit the ubroker.properties file. In the
section for the WSA instance, for each function that you want to disable, set the corresponding
property, shown in Table 7–6.
WSDL enableWsdl 0
For more information on the properties of a WSA instance, see the comments in the
ubroker.properties file.
Note: If you disable all WSA administration access while the WSA instance is running, you
must stop and restart the JSE to re-enable WSA administration access.
7–17
Web Services Adapter Security Configurations
1. Using a text editor, edit the WSA instance’s web.xml file, commenting out the
security-constraint holding the URL path of the WSA administrator, as shown:
<!--
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/admin/*</url-pattern>
</web-resource-collection>
</security-constraint>
-->
Note: In the actual web.xml file, the URL path of the WSA administrator is in bold.
2. Using Progress Explorer (or the WSAMAN utility), disable (or set to 0) the WSA
instance’s adminAuth property:
• If the WSA instance is local (the WSA resides on the AdminServer machine), using
Progress Explorer, select the WSA instance, right-click, and choose Properties.
Select Security to display the Security panel. In the Security panel, disable
authentication for WSA administration.
• If the WSA instance is remote (the WSA instance does not reside on the
AdminServer machine), using a text editor, edit the ubroker.properties file. In the
properties for the WSA instance, set adminAuth to 0 (zero), as shown:
[WSA]
.
.
.
adminAuth=1
7–18
Alphabetical list of configuration instructions
1. If the WSA is local, configure the WSA to not use the “all administrators have all
privileges” rule. To do so, follow these steps:
a. Using Progress Explorer, select the WSA instance, right-click, and choose
Properties. Select Security.
b. Change the WSA instance's list of administrator roles by selecting at least one of the
listed administrator roles.
When no administrator roles are selected, the WSA invokes the “all administrators
have all privileges” rule. When at least one role is selected, the WSA enforces
per-administrator-role Permissions.
2. If the WSA instance is remote, using a text editor, edit the ubroker.properties file. In
either or both of the [AdminRole.PSCAdmin] and [AdminRole.PSCOper] groups, as
desired, edit the servlet_services property from read, write, delete to read.
7–19
Web Services Adapter Security Configurations
When you install the WSA, you can choose to enable security. In this case, security is preset to
enable access to WSDL listings. But you can disable this access. The technique for doing so
depends on whether the WSA instance resides locally (on the AdminServer machine) or
remotely (not on the AdminServer machine).
Note: Neither technique disables access to the WSA instance’s WSDL files individually.
If the WSA instance resides locally, using Progress Explorer, select the WSA instance,
right-click, and choose Properties. Select Security to bring up the Security panel. In the
Security panel, disable WSDL listings for the WSA instance.
If the WSA instance resides remotely, in the ubroker.properties file from which the WSA
instance’s properties are initialized, in the section for the WSA instance, set the
enableWsdlListing property to 0, as shown:
[WSA]
.
.
.
enableWsdlListings=1
7–20
Alphabetical list of configuration instructions
1. Choose an authorization role name to identify users who get access to all of a WSA
instance’s Web service applications.
2. Using a text editor, edit the WSA instance’s web.xml file as follows:
a. Uncomment or add a <security-constraint> element for the URL path for Web
service applications. The security-constraint might appear as follows:
<!--
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/</url-pattern>
</web-resource-collection>
</security-constraint>
-->
Syntax
<auth-constraint>
<role-name>name</role-name>
</auth-constraint>
7–21
Web Services Adapter Security Configurations
For example, after you add the role names webservicesrole1 and
webservicesrole2, the <security-constraint> element might appear as follows:
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/</url-pattern>
<auth-constraint>
<role-name>webservicesrole1</role-name>
<role-name>webservicesrole2</role-name>
</auth-constraint>
</web-resource-collection>
</security-constraint>
3. Modify the JSE to add your user’s accounts and grant them membership to the chosen role.
4. Modify the WSA instance’s properties to enable authorization for Web services. Use one
of the following techniques:
• If the WSA instance is local (the WSA resides on the AdminServer machine), using
Progress Explorer, select the WSA instance, right-click, and choose Properties.
Select Security to bring up the Security panel. In the WSA instance’s Security panel,
enable authentication for Web services.
• If the WSA instance is remote (the WSA instance does not reside on the
AdminServer machine), use a text editor.
• In the ubroker.properties file, in the properties for the WSA instance, set appAuth
to 1 (one). The possible values for appAuth are listed in Table 7–7.
7–22
Alphabetical list of configuration instructions
For example:
[WSA]
.
.
.
appAuth=0
1. Choose an authorization role name to identify users who get access to all of a WSA
instance’s WSDL.
2. Using a text editor, edit the WSA instance’s web.xml file as follows:
a. Uncomment or add a <security-constraint> element for the URL path for WSDL.
The <security-constraint> element might appear as follows:
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/wsdl/*</url-pattern>
</web-resource-collection>
</security-constraint>
Syntax
<auth-constraint>
<role-name>name</role-name>
</auth-constraint>
7–23
Web Services Adapter Security Configurations
For example, after you add the role-names wsdlrole1 and wsdlrole2, the
<security-constraint> element might appear as follows:
<security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/</url-pattern>
<auth-constraint>
<role-name>wsdlrole1</role-name>
<role-name>wsdlrole2</role-name>
</auth-constraint>
</web-resource-collection>
</security-constraint>
3. Modify the JSE to add your user’s accounts and grant them membership to the chosen role.
4. Modify the WSA instance’s properties to enable authorization for WSDL. Use one of the
following techniques:
• If the WSA instance is local (the WSA resides on the AdminServer machine), using
Progress Explorer, select the WSA instance, right-click, and choose Properties.
Select Security to display the Security panel. In the Security panel, enable
authentication for WSDL.
• If the WSA instance is remote (the WSA instance does not reside on the
AdminServer machine), using a text editor, in the ubroker.properties file from
which the WSA instance is initialized, in the properties for the WSA instance, set
wsdlAuth to 1 (one). The possible values for wsdlAuth are listed in Table 7–8.
For example:
[WSA]
.
.
.
wsdlAuth=0
7–24
Alphabetical list of configuration instructions
To enable multiple roles, use a text editor to edit the WSA instance’s web.xml file.
1. Find the <security-constraint> element for accessing Web services, WSDL, or WSA
administration, as shown in Table 7–9.
Table 7–9: Enabling multiple user roles for Web services, WSDL, and
administration
For accessing ... The security-constraint might look like this ...
WSDL <security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/wsdl/*</url-pattern>
</web-resource-collection>
</security-constraint>
7–25
Web Services Adapter Security Configurations
Syntax
<auth-constraint>
<role-name>name</role-name>
</auth-constraint>
For example, you can set up the role names WSUser1 and WSUser2 for accessing Web
services, WSDUser1 and WSDUser2 for accessing WSDL, and WSAdminUser1 and
WSAdminUser2 for accessing WSA administration, as shown in Table 7–10.
Table 7–10: Setting security constraints for multiple user roles on Web
services, WSDL, and administration
WSDL <security-constraint>
<web-resource-collection>
<url-pattern>/wsa1/wsdl/*</url-pattern>
<auth-constraint>
<role-name>WSDLUser1</role-name>
<role-name>WSDLUser2</role-name>
</auth-constraint>
</web-resource-collection>
</security-constraint>
7–26
Alphabetical list of configuration instructions
For example, suppose the Acme Company wants to deploy as Web services the applications
described in Table 7–11.
Table 7–11: Enabling Web services per user and per application
Accounting (Update) Members of the Accounting Read, modify, and create records
department only. in the Accounting system.
Human Resources Members of the Human Read, modify, and create records
Resources department only. in the Human Resources system.
1. Set up the WSA instances, security-constraint URL-patterns, and role names shown in
Table 7–12.
7–27
Web Services Adapter Security Configurations
2. In the properties of each WSA instance, require user authorization to Web service
applications:
• If the WSA is local, using Progress Explorer, select the WSA instance, right-click,
and select Properties. Select Security to display the Security panel. In the Security
panel, add user authorization to Web services.
• If the WSA instance is remote, using a text editor, edit the ubroker.properties file.
Add user authorization to Web services.
3. In the JSE’s user database, assign each employee the appropriate role, as shown in Table
7–13.
7–28
Alphabetical list of configuration instructions
Table 7–14: Possible web.xml file for enabling Web services per user
per application (1 of 4)
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<display-name>Web Services Adapter</display-name>
<servlet>
<servlet-name>worktracking_servlet</servlet-name>
<display-name>Web Services Adapter worktracking servlet
</display-name>
<servlet-class>com.progress.wsa.WsaServlet</servlet-class>
<init-param>
<param-name>InstallDir</param-name>
<param-value>/progress/openedge</param-value>
</init-param>
<init-param>
<param-name>instanceName</param-name>
<param-value>worktracking</param-value>
</init-param>
<init-param>
<param-name>propertyFileName</param-name>
<param-value>/progress/openedge/properties/ubroker.properties
</param-value>
</init-param>
</servlet>
7–29
Web Services Adapter Security Configurations
Table 7–14: Possible web.xml file for enabling Web services per user
per application (2 of 4)
<servlet>
<servlet-name>accntgquery_servlet</servlet-name>
<display-name>Web Services Adapter accounting-query servlet
</display-name>
<servlet-class>com.progress.wsa.WsaServlet</servlet-class>
<init-param>
<param-name>InstallDir</param-name>
<param-value>/progress/openedge</param-value>
</init-param>
<init-param>
<param-name>instanceName</param-name>
<param-value>accntgquery</param-value>
</init-param>
<init-param>
<param-name>propertyFileName</param-name>
<param-value>/progress/openedge/properties/ubroker.properties
</param-value>
</init-param>
</servlet>
<servlet>
<servlet-name>accntg_servlet</servlet-name>
<display-name>Web Services Adapter full accountingservlet
</display-name>
<servlet-class>com.progress.wsa.WsaServlet</servlet-class>
<init-param>
<param-name>InstallDir</param-name>
<param-value>/progress/openedge</param-value>
</init-param>
<init-param>
<param-name>instanceName</param-name>
<param-value>accntg</param-value>
</init-param>
<init-param>
<param-name>propertyFileName</param-name>
<param-value>/progress/openedge/properties/ubroker.properties
</param-value>
</init-param>
</servlet>
7–30
Alphabetical list of configuration instructions
Table 7–14: Possible web.xml file for enabling Web services per user
per application (3 of 4)
<!-- List all of the servlet mappings here -->
<servlet-mapping>
<servlet-name>hr_servlet</servlet-name>
<url-pattern>/hr/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>worktracking_servlet</servlet-name>
<url-pattern>/worktracking/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>accntgquery_servlet</servlet-name>
<url-pattern>/accntgquery/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>accntg_servlet</servlet-name>
<url-pattern>/accntg/*</url-pattern>
</servlet-mapping>
<security-constraint>
<web-resource-collection>
<web-resource-name>Work-Tracking Web Services</web-resource-name>
<url-pattern>/worktracking/</url-pattern>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>Users</role-name>
</auth-constraint>
</security-constraint>
7–31
Web Services Adapter Security Configurations
Table 7–14: Possible web.xml file for enabling Web services per user
per application (4 of 4)
<security-constraint>
<web-resource-collection>
<web-resource-name>Accounting-query Web Services
</web-resource-name>
<url-pattern>/accntgquery/</url-pattern>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>DeptMgr</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Accounting Web Services</web-resource-name>
<url-pattern>/accntg/</url-pattern>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>Acctdept</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Acme Company Web Services</realm-name>
</login-config>
</web-app>
7–32
8
Using the WSA Management Utility
(WSAMAN)
This chapter provides an overview of the functions of the WSAMAN utility in the following section:
• Overview
Using the WSA Management Utility (WSAMAN)
Overview
The WSAMAN utility is a command-line utility for administering Web Services Adapter (WSA)
instances and Web services.
The functions provided by the WSAMAN utility duplicate their Progress Explorer equivalents. For
more information on the Progress Explorer equivalents, see the Progress Explorer online help.
Syntax
Each function of the WSAMAN utility has syntax similar to the following:
Syntax
[ -option ]...
One or more options, where each option consists of a name (for example, -appname) and
a value (for example, wsainstance-name).
function
For more information on the functions of the WSAMAN utility, see Appendix B, “Command
and Utility Reference.”
8–2
Overview
Function Description
WSAMAN getprops (WSA) Displays the current value of the properties that can be
changed while the WSA is running.
WSAMAN list Displays the list of Web service applications that have been
deployed to the WSA instance.
WSAMAN setdefault Sets one of the default Web service properties associated
with a WSA instance.
WSAMAN setprops (WSA) Temporarily changes the value of one of the properties of
a WSA instance. Changes last until the JSE is stopped and
restarted.
8–3
Using the WSA Management Utility (WSAMAN)
For more information on the functions of the WSAMAN utility, see Appendix B, “Command
and Utility Reference.”
Function Description
WSAMAN export Creates a Web Service Definition (WSD) file on the local
system from an existing Web service on an existing WSA
instance.
8–4
Overview
Function Description
WSAMAN query (Service) Displays the following information about a Web service:
• Target NameSpace.
• Status.
• AppServer URL.
• Session model.
• WSDL Style/Use.
• Relevant Web service properties (regardless of
whether the Web service is enabled or disabled).
For more information on the functions of the WSAMAN utility, see Appendix B, “Command
and Utility Reference.”
8–5
Using the WSA Management Utility (WSAMAN)
8–6
Part IV
WebSpeed Administration
• WebSpeed administration
9–2
WebSpeed configuration overview
• Install the necessary WebSpeed components. You can distribute WebSpeed components
over a number of machines, but the WebSpeed Messenger must be installed in the scripts
directory of your Web server.
• Configure the machines involved in the WebSpeed installation. This includes setting the
appropriate environment variables and setting up your Web server.
For more information about these preliminary tasks, see OpenEdge Getting Started: Installation
and Configuration.
Once you complete these preliminary tasks, you can begin to configure the WebSpeed
components.
1. Start the AdminService process on each machine. (See the “Starting the AdminService”
section on page 9–18.)
2. Once the AdminService is running, you can use the Progress Explorer to create and modify
NameServer and WebSpeed Transaction Server configurations. These configurations are
in the properties file (ubroker.properties) on the machine where you installed the
WebSpeed Transaction Server. (See the “Progress Explorer” section on page 9–5.)
You can also edit the ubroker.properties file manually by using a text editor. If you
choose to use a text editor, you must have file system access to the file. (See the “Overview
of the ubroker.properties file” section on page 9–18.)
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
You can validate NameServer and WebSpeed configurations with the NSCONFIG and
WSCONFIG validation utilities. These utilities must have access to the properties file. (See
the “NSCONFIG” section on page B–12 and the “WSCONFIG” section on page B–47.)
3. Determine if you must set (or change any preset) WebSpeed environment variables. (See
the “Setting up the WebSpeed environment” section on page 9–19.)
9–3
Configuring WebSpeed in Windows
4. Use the Progress Explorer (or the NSMAN utility) to start up a NameServer instance that you
configured to coordinate client access to one or more WebSpeed Transaction Server
instances on your network. After the NameServer has started, use the Progress Explorer
(or the WTBMAN utility) to start up each WebSpeed Transaction Server instance controlled
by that NameServer. (See the “Starting the WebSpeed Transaction Server and
NameServer” section on page 9–25.)
After a WebSpeed Transaction Server starts up, it registers its location and the Application
Services it supports with its controlling NameServer.
5. Set up the WebSpeed Messenger on your Web server. (See the “Setting up WebSpeed on
the Web server machine” section on page 9–13.)
6. At any time after Step 5, you can verify that the AdminService, the NameServer, and the
WebSpeed Transaction Server are running and test the configuration to confirm that you
have set up WebSpeed correctly. You perform this verification with the Progress Explorer,
the WebSpeed command-line utilities, or the WebSpeed Messenger Administration
(WSMAdmin) page in a browser. (See the “Testing your configuration” section on
page 9–29 for more information.)
7. You can shut down the AdminService process at any time on a WebSpeed or NameServer
machine. If you shut down the AdminService while there are NameServer and WebSpeed
Transaction Server instances still running, those instances are shut down as well.
WebSpeed administration
The WebSpeed administration framework consists of the following system administration
components:
• The Progress Explorer tool, which allows local and remote administration and
configuration of WebSpeed and other OpenEdge components.
• The management utilities, which allow administration from the command line of
WebSpeed and other OpenEdge components.
This framework provides a consistent structure for all the OpenEdge server products installed
on your network.
9–4
WebSpeed administration
The AdminService
The AdminService, the core of the common administration framework, supports the managing
of WebSpeed and other OpenEdge products (for example, NameServer, database, DataServer).
The AdminService runs as a service in Windows and on UNIX platforms. By default, it starts
automatically.
Alternately, you can run a command from a command prompt or a batch file similar to the
following:
where version is the version number of OpenEdge. You can find the version number for your
installation by going to the OpenEdge folder in your Windows Start menu and choosing
Version Info.
Progress Explorer
The Progress Explorer is a graphical administration utility that operates as a plug-in to the
Microsoft Management Console (MMC). The Progress Explorer combines the functionality of
all the command-line utilities with the ability to create, save modifications to, and delete
individual WebSpeed Transaction Servers, NameServers, DataServers, AppServers,
BrokerConnect, Web Services, and databases. You can also use the Progress Explorer to
configure WebSpeed Messengers, start additional WebSpeed agents, or trim back running
WebSpeed agents.
9–5
Configuring WebSpeed in Windows
When you start the Progress Explorer, the following window appears:
The interface includes a menu bar and two distinct frames. The left frame presents a tree view
that might include WebSpeed Transaction Servers, WebSpeed Messengers, NameServers,
AppServers, DataServers, and OpenEdge databases. Expanding any of the folders under an
AdminService shows a list of all configured instances of that component. With a component
selected, you can create new instances (except WebSpeed Messengers) by choosing Action→
New. With a component instance selected, you can start, stop, configure, get status views, and
read the log files for that instance.
When you install WebSpeed, a sample WebSpeed Transaction Server (wsbroker1) and a
sample NameServer (NS1) are installed automatically. You administer each product instance
through a tabbed property sheet, which appears in the right frame. You use the tabs to configure
or modify all the properties for a specific instance. A toolbar is also available, enabling you to
start, save, delete, check the status of, or stop a WebSpeed broker or NameServer instance.
9–6
WebSpeed administration
1. Make sure the AdminServer is running on the host where you want to configure
WebSpeed.
3. Connect to the AdminServer on your WebSpeed host (see OpenEdge Getting Started:
Installation and Configuration).
• To define a new WebSpeed instance, select the WebSpeed folder in the Progress
Explorer’s tree view, right-click, and choose New. Enter a unique name for the
WebSpeed instance and click OK. Then open the property editor for the new
instance by selecting the instance, right-clicking, and choosing Properties.
The WebSpeed instance property editor shows a tree view of property categories on the
left and the properties for the selected category on the right.
5. Select a property category and set the properties as required. You can accept the default
values, if they are appropriate for your application. You probably want to specify the
properties under each category. See the Progress Explorer online help for detailed
information about each property.
The Broker category specifies properties of the WebSpeed broker. Expanding this
category shows the following property subcategories:
• General — The Operating mode is fixed stateless, and you probably want to
specify a nondefault value for the TCP/IP port number where the WebSpeed broker
listens for requests.
If you want WebSpeed to start whenever you start the AdminServer, select the Auto
start check box, and if you want to use a different working directory from the one
specified during the WebSpeed product installation, you can also change it here.
9–7
Configuring WebSpeed in Windows
• AppService Name List — You can either enter any names for the application
services supported by WebSpeed or select the Supports default service check box
if you want WebSpeed to support the default service for all client connections that
do not specify an application service name. If you choose to use application service
names, the default application service name is the name of the WebSpeed instance.
• Logging Setting — You can set the following WebSpeed broker logging options:
specify a different pathname from the default for the broker log file; specify the level
of logging detail; control whether the logging for a session appends to or overwrites
the previous broker log file; specify a comma-separated list of logging entry types to
be included in the broker log file, choosing from the valid values listed in the
Progress Explorer online help; set a file-size threshold that determines the point at
which a new log file is created (0 = unlimited log file size); and specify the maximum
number of broker log files to be kept (0 = unlimited number of log files retained). See
OpenEdge Development: Debugging and Troubleshooting for detailed information
on logging options.
• Advanced Features — You can specify the maximum number of client connections
(Maximum client instances) that the WebSpeed broker can support at one time, the
WebSpeed weight factor (Priority weight) for load balancing, the time between
retries to register WebSpeed with the controlling NameServer, the time-out period
for starting WebSpeed, the time-out period for WebSpeed to accept a client request,
and the timeout period for the WebSpeed agent to trim its quota of WebSpeed agents
between the maximum and minimum setting (see the Agent category). For more
information on these options, see the Progress Explorer online help.
9–8
WebSpeed administration
The Agent category specifies properties of the WebSpeed agents. Expanding this category
shows the following property subcategories:
• General — You can specify a pathname of the WebSpeed agent executable, startup
parameters for the WebSpeed agent. For more information, see OpenEdge
Deployment: Startup Command and Parameter Reference.
Specify the minimum and maximum TCP/IP port numbers that the WebSpeed agent
can assign to WebSpeed agents that it starts up. (Check with your system
administrator for appropriate ranges.)
Specify the mode for running applications during the current WebSpeed session
using the Agent Application Mode. The default mode is Development.
• Logging Setting — You can set the following WebSpeed agent logging options:
specify a different pathname from the default for the server log file; specify the level
of logging detail; control whether the logging for a session appends to or overwrites
the previous server log file; specify a comma-separated list of logging entry types to
be included in the server log file, choosing from the valid values listed in the Progress
Explorer online help; set a file-size threshold that determines the point at which a
new log file is created (0 = unlimited log file size); and specify the maximum number
of server log files to be kept (0 = unlimited number of log files retained). See
OpenEdge Development: Debugging and Troubleshooting for detailed information
on logging options.
• Pool Range — These settings determine the number of WebSpeed agents that the
WebSpeed agent can start up and maintain for WebSpeed.
9–9
Configuring WebSpeed in Windows
To specify the directory that WebSpeed agents use to upload text files, use File
Upload Directory.
To allow the 4GL debugger to run in the WebSpeed session, select the 4GL
debugger-enabled check box. Specify the names of any WebSpeed configuration
procedures that you want WebSpeed to execute, and any parameters for the Startup
procedure. For more information on debugging WebSpeed applications and on
AppServer configuration procedures, see OpenEdge Application Server: Developing
AppServer Applications.
The options in the SSL category options define the security settings for an SSL-enabled
WebSpeed instance. Note that a WebSpeed-enabled instance for SSL operation does not
accept non-SSL client connections. For more information on SSL operations, see
OpenEdge Getting Started: Core Business Services. Expanding this category shows the
following property subcategories:
• General — If you check the Enable SSL Client Connections check box, select the
alias for the private key/digital certificate entry (in the OpenEdge keystore) that you
want to secure connections for this WebSpeed instance. Also enter and confirm the
password for this private key and digital certificate. You need not enter a password
if you choose to use the default_server certificate and its default password.
• Advanced Features — By default, caching is enabled for the SSL client session, and
you can enter a time-out value that specifies the length of time (in seconds) that a
disconnected session is held in the cache. During this specified interval, a connected
client can resume its session. To disable session caching, check the box.
The Messaging category specifies properties for a ServerConnect process started by the
application service running on this WebSpeed Transaction Server. It allows you to start a
SonicMQ ServerConnect background process at startup. You can also set logging options
for the SonicMQ ServerConnect process: specify a different pathname from the default for
the broker log file; specify the level of logging detail; control whether the logging for a
session appends to or overwrites the previous broker log file; specify a different pathname
from the default for the server log file; specify the level of logging detail; control whether
the logging for a session appends to or overwrites the previous server log file. See
OpenEdge Development: Debugging and Troubleshooting for detailed information on
logging options.
9–10
WebSpeed administration
If you want to specify environment variables for WebSpeed execution, select the
Environment Variables category. It allows you to enter name-value pairs for
environment variable settings. Any values you set here override prior values set for the
same environment variables in the operating system.
Note: Do not set the PROPATH variable in this category. Use the Server General category
instead.
For information about how to use the Progress Explorer to configure WebSpeed, see the
Progress Explorer online help.
WTBMAN utility
You can use the WTBMAN utility to control the operation of a WebSpeed Transaction Server. The
utility allows you to start a Transaction Server, query its status, start and stop additional
WebSpeed agents, trim by a certain number of agents, and shut down the Transaction Server.
For more information about the WTBMAN utility, see the “WTBMAN” section on page B–49.
WSCONFIG utility
You can use the WSCONFIG utility to validate existing WebSpeed Transaction Server or
WebSpeed Messenger configurations. The WSCONFIG utility reads the ubroker.properties file
for validation.
The WSCONFIG configuration command runs locally only, on the machine where the WebSpeed
components that you want to check are installed.
Note: Because the WSCONFIG utility does not run across the network and no AdminService is
installed during a Messenger-only installation, you cannot use the WSCONFIG utility to
check a Messenger-only installation.
For more information about the WSCONFIG utility, see the “WSCONFIG” section on page B–47.
9–11
Configuring WebSpeed in Windows
Note: The NameServer can simultaneously support the WebSpeed Transaction Server,
AppServers, and DataServers.
NSMAN utility
You can use the NSMAN utility to control the operation of a configured NameServer. The utility
provides the ability to start a NameServer, query a NameServer status, and shut down a
NameServer.
For more information about the NSMAN utility, see the “NSMAN” section on page B–14.
NSCONFIG utility
You can use the NSCONFIG utility to query the current configuration of an existing NameServer
and to view all the option values for a specific NameServer. This utility is a diagnostic tool and
can be helpful when you are attempting to validate and resolve configuration settings.
The NSCONFIG configuration command runs locally only, on the machine where the NameServer
is installed. The utility does not run across the network.
For more information about the NSCONFIG utility, see the “NSCONFIG” section on page B–12.
9–12
Setting up WebSpeed on the Web server machine
Note: Since WebSpeed can run on a wide range of Web servers, it is not possible to provide
specific instructions here for configuring your Web server. For specific information
about your Web server, see your Web server documentation.
1. The WSASP Messenger calls WebSpeed applications from an Active Server Page. It cannot coexist with the ISAPI
Messenger.
9–13
Configuring WebSpeed in Windows
The NSAPI executables reside and run from the install-path\bin directory. The CGI
Messenger and ISAPI executables reside and run from the \scripts directory on the Web
server.
You can use the sample file cgiip.wsc to set up a file association for running the CGIIP
Messenger under Microsoft’s IIS Server. For details, see the cgiip.wsc file, which is located in
the install-path\bin directory.
Note: You must restart an ISAPI or Netscape NSAPI Web server after installing and
configuring the Messenger.
The Messenger executable comes with the WebSpeed Transaction Server. The Messenger is
installed in the scripts directory of the Web server, which you specify during an OpenEdge
installation.
If you install the WebSpeed Transaction Server on an operating system that is different from the
operating system that runs your Web server, go to the Download area on the PSDN Web site at
http://psdn.progress.com/downloads/ and download a compatible Messenger. This is
necessary because you must install a Messenger that is compatible with the Web server’s
operating system. For example, if you are distributing WebSpeed components across networked
machines and your Web server is running on UNIX, be sure to install a WebSpeed Messenger
executable that is suitable for running on UNIX. Make sure that you download a Messenger for
the appropriate UNIX platform and for the appropriate Web server type.
A Netscape Web server uses information in its configuration file to recognize the WebSpeed
NSAPI Messenger. The configuration file for the Netscape Enterprise Server is named
install-dir\https-host-name\config\obj.conf. (If you are using the Fast Track Server,
see your Web server documentation for the name of the server’s configuration file.)
9–14
Setting up WebSpeed on the Web server machine
Make a copy of the file before you modify it so that you can restore the original configuration.
Table 9–2 describes the changes you must make to obj.conf.
Init fn=WSNSAinit This Init line must appear as the last Init
command. It informs the Web server that the
named function is an external entry point
within the DLL.
9–15
Configuring WebSpeed in Windows
Each line you add to obj.conf must be on a single line. Do not add line breaks within a
command line. Use forward slashes (/) in pathnames. Here is an excerpt from a sample
obj.conf file (the additions that you must make for the WebSpeed Messenger are bold):
Init ...
Init ...
# The following directive is a single line; it contains no line breaks
Init fn=load-modules shlib="c:/Program Files/OpenEdge/bin/wsnsa.dll"
funcs=WSNSAinit,WSNSAdefault,WSNSAshutdown,WSNSAWebSpeedCheck
Init fn=WSNSAinit
<Object name=default>
AuthTrans ...
AuthTrans ...
NameTrans fn=WSNSAwebspeedCheck
NameTrans ...
NameTrans ...
PathCheck ...
PathCheck ...
ObjectType ...
ObjectType ...
Service method=(GET|POST|HEAD) fn=WSNSAdefault
Service ...
Service ...
AddLog ...
AddLog ...
Error ...
</Object>...
...
...
...
Access the Netscape Server’s browser-based Admin panel and apply the configuration changes
before restarting the Web server.
9–16
Placing static files on the Web server
Before running any WebSpeed application, make sure that your Web server is up and running.
Consult your Web server documentation for more information about getting the Web server
fully up and running.
Typically, a Messenger script file, such as cgiip.exe, resides in the \scripts or equivalent
directory that contains your Web server’s scripts. When you configure your Web server, you
can decide which directories can hold executable files.
Most Web servers map URLs leading with /scripts to a /scripts subdirectory. This
subdirectory is located either under or parallel to the document root directory. The /scripts
directory typically contains only executable files. This is an appropriate location to place your
Messenger script file.
If your WebSpeed application uses static HTML files, you should place them on the Web server
machine in a subdirectory of the Web server’s document root directory (or consult your Web
server documentation for information about other options, such as creating an additional
document root directory). You must place image files (.gif or .jpeg), audio files (.au), and
video files (.mpeg, .mpg) on the Web server machine. These files cannot be served directly by
WebSpeed. You must place these files on the Web server machine.
WebSpeed objects or compiled code must be accessible and visible to the WebSpeed agents.
Make the files accessible by placing them on the machine where your Transaction Server runs.
You can make a file visible to the WebSpeed agents by adding its directory name to the
Transaction Server’s PROPATH.
9–17
Configuring WebSpeed in Windows
From a Windows machine, you use the Progress Explorer to create and configure instances of
the WebSpeed Transaction Server or the NameServer on the Windows platform or remote
UNIX platforms. It is possible to do this by editing the ubroker.properties file manually. See
the “Overview of the ubroker.properties file” section on page 10–15 for more information on
the ubroker.properties file.
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
9–18
Setting up the WebSpeed environment
Alternately, you can run a command from a command prompt or a batch file similar to the
following:
where version is the version number of OpenEdge. You can find the version number for your
installation by going to the OpenEdge folder in your Windows Start menu and choosing
Version Info.
Note: In distributed configurations, you must edit the appropriate environment variables on
each machine where you have WebSpeed components installed.
You can change most of these settings using the Progress Explorer or by editing the WebSpeed
property file, ubroker.properties. Note that it is not necessary to modify the Windows
registry or the system environment variables (through the Windows Control Panel).
9–19
Configuring WebSpeed in Windows
When you install the WebSpeed Transaction Server, the installation process sets the PROPATH
for you in the ubroker.properties file. PROPATH initially includes a number of subdirectories
in your installation directory. In addition, the PROPATH includes a dot ( . ) directory reference.
When the agent sees the dot, the process substitutes the name of its current working directory.
For example, the agents resolve the dot to their broker’s default directory, which is the working
directory.
You can override installed PROPATH settings using the PROPATH property in the properties file
(ubroker.properties).
The properties file relies on a default setting for the working directory that you specify during
installation. You can remove or modify the references in the properties file to establish your
own working directory settings for both the WebSpeed Transaction Server and the NameServer.
For more information on OpenEdge environment settings, see OpenEdge Getting Started:
Installation and Configuration.
For disk management reasons, you might want to specify a nondefault location for the log files
used by WebSpeed. A WebSpeed installation uses a number of different log files, which are
stored in the default working directory. For example:
After you decide where you want log files to reside, you can specify the location for each in the
Progress Explorer or by directly editing the ubroker.properties file. For more information,
see the “Configuring WebSpeed components” section on page 9–21.
9–20
Configuring WebSpeed components
Because log files receive the WebSpeed and NameServer startup and shutdown messages,
OpenEdge system messages, and trace messages, the file can grow quickly. If you have the
Append option set in the Transaction Server’s configuration, these log files do not truncate
automatically. In this case, you should periodically trim the file with a text editor. You might
want to archive the file contents as you do it. For more information on maintaining log files, see
the “Maintaining the WebSpeed Transaction Server and NameServer log files” section on
page 9–27.
For more information about creating, configuring, and managing with the Progress Explorer,
see the Explorer online help.
For information about managing with the command-line utilities, see the “WebSpeed
command-line utilities” section on page 9–11.
• The NameServer allows for location transparency and load balancing. Simple or static
configurations might not require those features.
If you choose not to use the NameServer, configure your Transaction Server to indicate that it
should not register with a NameServer. Then, configure your Messenger to connect directly to
the Transaction Server.
9–21
Configuring WebSpeed in Windows
You can also eliminate the NameServer by directly editing the ubroker.properties file,
although using Progress Explorer is less error prone.
2. Find the broker definition for your Transaction Server. For example:
[UBroker.WS.wsbroker1]
registerNameServer=0
9–22
Configuring WebSpeed components
4. Find the definition for your Messenger. For example, if you use CGIIP:
[WebSpeed.Messengers.CGIIP]
registerNameServer=0
6. Add and set the port number for your broker. For example, if you are using the default
wsbroker1:
Port=3055
Note: When you eliminate the NameServer, the Messenger can only access one WebSpeed
Transaction Server (broker). One of the advantages of using the NameServer is that
you can run multiple brokers.
If the weight factor that you specify for each Unified broker instance is appropriate in relation
to the others, the effect is to assign more connections to broker instances with greater resources,
and thus to balance connection load among all the instances. You can set the load-balancing
weight factor for each Unified broker instance in the Progress Explorer or by editing the
priorityWeight property in the ubroker.properties file.
9–23
Configuring WebSpeed in Windows
Properly specified, these weight factors give some sense of the amount of work that an
individual WebSpeed Transaction Server instance can handle. For example, Table 9–3 shows
the effect of weight factors specified for three WebSpeed Transaction Server instances
registered for the same application service.
WebSpeed Transaction
Server name Weight factor % of time selected
WS1 20 20
WS2 20 20
WS3 60 60
The selection algorithm used by the NameServer guarantees that WS1 and WS2 are each
selected 20% of the time and WS3 is selected 60% of the time. Thus, if the sum of weight factors
for all WebSpeed Transaction Server instances that support the same application adds up to 100,
each weight factor specifies the exact percentage of time that the NameServer selects the given
WebSpeed Transaction Server instance over time.
You can specify any sum of values (not necessarily 100), but the weight of each is always
proportional to the sum, as shown in Table 9–4.
WebSpeed Transaction
Server name Weight factor % of time selected
WS1 2 2/7
WS2 2 2/7
WS3 3 3/7
9–24
Starting the WebSpeed Transaction Server and NameServer
For more information on load balancing and fault tolerance, see OpenEdge Getting Started:
Installation and Configuration.
1. The AdminService must be running. If the AdminService is not running, you must start it.
(See the “Starting the AdminService” section on page 9–18.)
2. Start an existing NameServer or create a new NameServer instance. You can create and
start a NameServer by using the Progress Explorer, or you can edit the
ubroker.properties file to create an instance and then use the NSMAN utility to start the
instance. When you configure a NameServer instance, you can set it to start up by default
whenever the AdminService starts.
Note: The NameServer can be on any machine in your network, even a UNIX machine.
If you are using the Progress Explorer, see the online help for information about creating
and starting an instance. If you are editing the ubroker.properties file, see the “Editing
the ubroker.properties file” section on page 10–16.
9–25
Configuring WebSpeed in Windows
To start a local instance of the NameServer (NS1) from the command line, use the
following command:
To start a remote instance of the NameServer from the command line, use the following
command:
nsman -name NS1 -host host-name -port port -user user-name -start
Where host-name is the name of the host machine on which you want the instance to run;
port is the port number on the AdminService; and user-name is the user ID of the system
account under which the NameServer will run.
See the Progress Explorer online help for information about creating and starting an
instance.
To start a local instance of the WebSpeed Transaction Server from the command line, use
the following command:
Note: The WebSpeed Transaction Server consists of a broker and agents. When you start
the broker, the agents are also started.
9–26
Maintaining the WebSpeed Transaction Server and NameServer log files
To start a remote instance of the WebSpeed Transaction Server from the command line,
use the following command:
wtbman -name broker -host host -port port -user user -start
where broker is the name of the WebSpeed broker, host is the name of the host machine
on which you want the instance to run; port is the port number on the AdminService; and
user is the user ID of the system account under which the Transaction Server will run. If
you specify a host name, the Explorer prompts you for a user name (if you do not supply
it) and password.
By using either the Progress Explorer or the command-line utilities, you can also stop a
NameServer or WebSpeed Transaction Server instance, check its status, and increase or reduce
the number of running WebSpeed agents. For more information, see the Progress Explorer
online help and the “Using the Progress Explorer to check status” section on page 9–29, and the
“Managing the WebSpeed Transaction Server” section on page 9–31.
If you have the Append option set in the Transaction Server’s configuration, these log files do
not truncate automatically. In this case, you should periodically trim the file with a text editor.
You might want to archive the file contents as you do it.
For more information on how to configure the log files for your environment, see the
“Configuring WebSpeed and NameServer log files” section on page 9–20.
9–27
Configuring WebSpeed in Windows
The WebSpeed Messenger must reside on the same machine as the Web server. The Web server
and the WebSpeed Messengers need not be on the same machine as the rest of the WebSpeed
components. Instead, you can install the Web server and the WebSpeed Messengers together on
a different machine if you want.
In this configuration, the Messenger must be able to connect remotely to the machines where
the NameServers and AdminServices are installed. To do this, you must configure a remote
NameServer. For more information on this, see OpenEdge Getting Started: Installation and
Configuration.
For more information, see the “Starting the WebSpeed Transaction Server and NameServer”
section on page 9–25.
9–28
Testing your configuration
• Use the -query option of the NSMAN and WTBMAN utilities to check the status of components.
To query a local NameServer, use the NSMAN utility, which is installed in install-path\bin:
Where NameServer is the name of the NameServer that you want to query.
nsman -name NameServer -host host -port port -user user -query
9–29
Configuring WebSpeed in Windows
To query a local WebSpeed broker, use the WTBMAN utility, which is installed in
install-path\bin:
Where broker is the name of the WebSpeed broker that you want to query. You can have more
than one broker running on a single machine.
wtbman -name broker -host host-name -port port -user user-name -query
The query reports on the broker’s pool of WebSpeed agents. For each agent, it lists a process
ID, its port number, its status, how many requests it has serviced, when it started, and when its
status changed.
• BUSY — The agent is actively executing application logic (Web object) for a Web user.
• LIMBO — The agent is in a transitional state. If the status persists, it indicates an error
condition.
• LOCKED — The agent is dedicated to a particular Web browser and is only available to
the browser whose application locks it.
• STARTING — The broker has launched the agent, but the agent has not yet initialized.
See the “Managing the WebSpeed Messenger” section on page 9–33 for the URL for the
WSMAdmin page.
9–30
Managing the WebSpeed Transaction Server
To run the status.p procedure from a Web browser, enter a URL using the following format:
http://hostname/script-dir/Messenger/WService=broker/src/web/
examples/status.p
In addition to allowing you to start, query, or stop the Transaction Server, the WTBMAN utility lets
you do the following:
9–31
Configuring WebSpeed in Windows
Where broker is the name of the WebSpeed broker specified in the ubroker.properties file
and number-to-start is the number of additional agents you want to start. The number you
specify must not exceed the maxSrvInstance value in the ubroker.properties file or your
license limit.
Where broker is the name of the Transaction Server and number-to-trim is the number of
agents you want to stop.
To force an immediate shutdown of the Transaction Server and all its agents, enter the following
command:
9–32
Managing the WebSpeed Messenger
wtbman -help
If you are running an NSAPI Web server, use the following URL:
http://host-name[:port]/wsnsa.dll[/WService=appservicename]?WSMAdmin
Where host-name is the name of the host on which the Messenger is running, port is the port
that your Web server uses (if different from the default port 80), and appservice-name is the
name of the application service.
For example, the following URL requests the Administration page for the NSAPI Messenger on
a host named mars:
http://mars/wsnsa.dll/WService=wsbroker1?WSMAdmin
If you are running an ISAPI Web server, use the following URL:
http://host-name[:port]/scripts/wsisa.dll/[/WService=appservice-name]
?WSMAdmin
9–33
Configuring WebSpeed in Windows
If you are running a CGI Web server, use the following URL:
http://host-name/scripts/cgiip.exe[/WService=appservice-name]?WSMAdmin
Where host-name is the name of your Web server machine, port is the port that your Web
server uses (if different from the default port 80), scripts is your Web server’s scripts
directory, and appservice-name is the name of the application service.
9–34
10
Configuring WebSpeed on UNIX
This chapter explains how to configure WebSpeed to run on UNIX-based systems, as described
in the following sections:
• WebSpeed administration
10–2
WebSpeed configuration overview
• Install the necessary WebSpeed components. You can distribute WebSpeed components
over a number of machines, but the WebSpeed Messenger must be installed in the scripts
directory of your Web server.
• Configure the machines involved in the WebSpeed installation. This includes setting the
appropriate environment variables and setting up your Web server.
For more information about these preliminary tasks, see OpenEdge Getting Started: Installation
and Configuration.
Once you complete these preliminary tasks, you can begin to configure the WebSpeed
components.
1. Start the AdminServer process on each machine by using the PROADSV utility. (See the
“Starting the AdminServer” section on page 10–18.)
2. Once the AdminServer is running, you can then use the Progress Explorer or a text editor
to create and modify NameServer and WebSpeed Transaction Server configurations.
These configurations are in the properties file (ubroker.properties) on the machine
where you installed the WebSpeed Transaction Server. You can use the Progress Explorer
remotely from a Windows machine to access configurations installed on a UNIX machine.
You can also edit the ubroker.properties file manually using a text editor. If you choose
to use a text editor, you must have file system access to the file. (See the “Overview of the
ubroker.properties file” section on page 10–15.)
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
You can validate NameServer and WebSpeed configurations using the validation utilities,
NSCONFIG and WSCONFIG. These utilities must have access to the properties file. (See the
“NSCONFIG” section on page B–12 and the “WSCONFIG” section on page B–47.)
10–3
Configuring WebSpeed on UNIX
3. Determine if you need to set (or change any preset) WebSpeed environment variables.
(See the “Setting up the WebSpeed environment” section on page 10–18.)
4. Use the NSMAN utility (or the Progress Explorer remotely) to start up a NameServer instance
that you configured to coordinate client access to one or more WebSpeed Transaction
Server instances on your network. After the NameServer has started, use the WTBMAN utility
(or the Progress Explorer remotely) to start up each WebSpeed Transaction Server
instance controlled by that NameServer. (See the “Starting the WebSpeed Transaction
Server and NameServer” section on page 10–22.)
After a WebSpeed Transaction Server starts up, it registers its location and the Application
Services it supports with its controlling NameServer.
5. Set up the WebSpeed Messenger on your Web server. (See the “Setting up WebSpeed on
the Web server machine” section on page 10–7.)
6. At any time after Step 5, you can validate that the AdminServer, the NameServer, and the
WebSpeed Transaction Server are running and test the configuration to confirm that you
have set up WebSpeed correctly. You perform this validation by using the WebSpeed
command-line utilities, the Progress Explorer (remotely from a Windows machine), or the
WebSpeed Messenger Administration (WSMAdmin) page in a browser. (See the “Testing
your configuration” section on page 10–26 for more information.)
7. You can shut down the AdminServer process at any time on the WebSpeed machine. If
you shut down the AdminServer while there are NameServer and WebSpeed Transaction
Server instances still running, those instances are shut down as well.
WebSpeed administration
The WebSpeed administration framework consists of the following system administration
components:
• The Progress Explorer tool, which allows local and remote administration and
configuration of WebSpeed and other OpenEdge components.
• The management utilities, which allow administration from the command line of
WebSpeed and other OpenEdge components.
This framework provides a consistent structure for all the OpenEdge server products installed
on your network.
10–4
WebSpeed administration
The AdminServer
The AdminServer, the core of the common administration framework, supports the managing
of WebSpeed and other OpenEdge products (for example, NameServer, database, DataServer)
and is also used by other OpenEdge processes.
By using the PROADSV utility, you can start up and shut down the AdminServer. Remember that
the AdminServer serves as a connection point for both local and remote services for
configuration and administration.
Progress Explorer
The Progress Explorer is a graphical administration utility that operates as a plug-in to the
Microsoft Management Console (MMC) in Windows machines. The Progress Explorer
combines the functionality of all the command-line utilities with the ability to create, save
modifications to, and delete individual WebSpeed Transaction Servers, NameServers,
DataServers, AppServers, and databases. You can also use the Progress Explorer to configure
WebSpeed Messengers, start additional WebSpeed agents, or trim back running WebSpeed
agents.
You can use the Progress Explorer from a remote machine to create, configure, and administer
the WebSpeed components on a UNIX machine. For more information on the Progress
Explorer, see the Progress Explorer online help.
WTBMAN utility
You can use the WTBMAN utility to control the operation of a WebSpeed Transaction Server.
The utility allows you to start a Transaction Server, query its status, start and stop additional
WebSpeed agents, trim by a certain number of agents, and shut down the Transaction Server.
For more information about the WTBMAN utility, see the “WTBMAN” section on page B–49.
10–5
Configuring WebSpeed on UNIX
WSCONFIG utility
You can use the WSCONFIG utility to validate existing WebSpeed Transaction Server or
WebSpeed Messenger configurations. The WSCONFIG utility reads the ubroker.properties file
for validation.
The WSCONFIG configuration command runs locally only, on the machine where the WebSpeed
components that you want to check are installed.
Note: Because the WSCONFIG utility does not run across the network and no AdminServer is
installed during a Messenger-only installation, you cannot use the WSCONFIG utility to
check a Messenger-only installation.
For more information about the WSCONFIG utility, see the “WSCONFIG” section on page B–47.
Note: The NameServer can simultaneously support the WebSpeed Transaction Server,
AppServers, and DataServers.
NSMAN utility
You can use the NSMAN utility to control the operation of a configured NameServer. The utility
provides the ability to start a NameServer, query a NameServer status, and shut down a
NameServer.
For more information about the NSMAN utility, see the “NSMAN” section on page B–14.
10–6
Setting up WebSpeed on the Web server machine
NSCONFIG utility
You can use the NSCONFIG utility to query the current configuration of an existing NameServer
and can be used to view all the option values for a specific NameServer. This utility is a
diagnostic tool and can be helpful when you are attempting to validate and resolve configuration
settings.
The NSCONFIG configuration command only runs locally, on the machine where the NameServer
is installed. The utility does not run across the network.
For more information about the NSCONFIG utility, see the “NSCONFIG” section on page B–12.
Note: Since WebSpeed can run on a wide range of Web servers, it is not possible to provide
specific instructions here for configuring your Web server. For specific information
about your Web server, see your Web server documentation.
CGI-compatible cgiip
10–7
Configuring WebSpeed on UNIX
When you installed WebSpeed, you provided information about your Web server. If you
selected CGI, the installation utility installed the CGI Messenger script, wspd_cgi.sh, into the
directory you specified as your Web server scripts directory. The NSAPI executable resides and
runs from the OpenEdge install-path/bin directory.
Note: You must restart the Netscape NSAPI Web server after installing and configuring the
Messenger.
The Messenger executable comes with the WebSpeed Transaction Server. The Messenger is
installed in the scripts directory of the Web server, which you specify during an OpenEdge
installation.
If you install the WebSpeed Transaction Server on an operating system that is different from the
operating system that runs your Web server, go to the Download area on the PSDN Web site at
http://psdn.progress.com/downloads/ and download a compatible Messenger. This is
necessary because you must install a Messenger that is compatible with the Web server’s
operating system. For example, if your Web server is CGI-compatible and runs in Windows,
you must install a CGI Messenger that can run in Windows.
A Web server uses information in its configuration file to recognize the WebSpeed NSAPI
Messenger. The configuration file for the Netscape Enterprise Server is named
install-dir/https-host-name/config/obj.conf. (If you are using the Fast Track Server,
refer to your Web server documentation for the name of the server’s configuration file.)
10–8
Setting up WebSpeed on the Web server machine
Make a copy of the file before you modify it so that you can restore the original configuration.
Table 10–2 describes the changes you must make to obj.conf.
Init fn=WSNSAinit This Init line must appear as the last Init
command. It informs the Web server that the
named function is an external entry point
within the shared object.
10–9
Configuring WebSpeed on UNIX
Each line you add to obj.conf must be on a single line. Do not add line breaks within a
command line. Use forward slashes (/) in pathnames. Here is an excerpt from a sample
obj.conf file (the additions that you must make for the WebSpeed Messenger are bold):
Init ...
Init ...
# The following directive is a single line; it contains no line breaks
Init fn=load-modules shlib="/usr/dlc/bin/wsnsa.dll"
funcs=WSNSAinit,WSNSAdefault,WSNSAshutdown,WSNSAwebspeedCheck
Init fn=WSNSAinit
<Object name=default>
AuthTrans ...
AuthTrans ...
NameTrans fn=WSNSAwebspeedCheck
NameTrans ...
NameTrans ...
PathCheck ...
PathCheck ...
ObjectType ...
ObjectType ...
Service method=(GET|POST|HEAD) fn=WSNSAdefault
Service ...
Service ...
AddLog ...
AddLog ...
Error ...
</Object>...
The Netscape Web server must be able to locate the WebSpeed Messenger and the resources
that the Messenger requires for configuration information and messages. Edit the Netscape Web
server’s start file (for Netscape Web servers, this file is install-dir/https-hostname/start)
to set the environment variables described in Table 10–3.
10–10
Setting up WebSpeed on the Web server machine
1. On AIX only, you need to add /usr/lib to the shared library search path environment variable.
Here is a sample start file for AIX that includes the necessary WebSpeed information:
#! /bin/sh
...
LIBPATH=/usr/lib:$LIBPATH export LIBPATH
...
DLC=/usr/dlc; export DLC
PROMSGS=/$DLC/promsgs; export PROMSGS
PROCFG=$DLC/progress.cfg: export PROCFG
WRKDIR=/usr/workdir export WRKDIR
Access the Netscape Server’s browser-based Admin panel and apply the configuration changes
before restarting the Web server.
Before running any WebSpeed application, make sure that your Web server is running. Consult
your Web server documentation for more information about running the Web server.
10–11
Configuring WebSpeed on UNIX
Configuring a Messenger to access a CGI-compatible Web server requires only that you create
a script file that the Web server uses to invoke the Messenger executable, cgiip. You do not
have to change the configuration of your Web server. The script file sets WebSpeed
environment variables and invokes the Messenger executable, cgiip.
You can find a sample file that you can use as the basis for a shell script to configure the script
file at install-path/bin/wspd_cgi.sh.
10–12
Setting up WebSpeed on the Web server machine
The wspd_cgi.sh script provides and documents additional options for invoking the Messenger
executable. You can, for example, specify the default WebSpeed service or use the -f option to
specify a named configuration file. Table 10–4 describes the various options.
Option Description
Note: Specifying a WebSpeed service name in a URL overrides any settings in your
Messenger script file.
You can edit the script if you would like to see what information cgiip is sending to the browser
for debugging purposes (including HTTP headers). Here is a sample script that shows how you
might do this:
After a request from a Web browser initiates this script, the script saves all of the CGI
environment information in a file named webapp.env. The script sends its output not only to the
browser but also to a file named /tmp/webapp.out. You can look at /tmp/webapp.out to see
what was sent to the browser. The technique is useful for pinpointing problems that might be
related more to the server than to your application. A clue that this might be the case is if your
browser receives no output from your application and displays server errors.
10–13
Configuring WebSpeed on UNIX
Remember that this script executes every time a browser makes a request. Thus, if multiple
browsers make multiple simultaneous requests, the agents servicing the requests can overwrite
each other’s output to the file. For this reason, you should use this technique only when you are
debugging your application (typically with a controlled number of agents and browsers).
Typically, a Messenger script file, such as wspd_cgi.sh, resides in the cgi-bin or equivalent
directory that contains your Web server’s scripts. When you configure your Web server, you
can decide which directories can hold executable files. You can also designate whether the
executable files require a specific extension (such as .cgi) or can use any extension. See your
Web server documentation for details on how to configure a scripts directory and CGI
programs.
Most UNIX Web servers map URLs leading with /cgi-bin to a cgi-bin subdirectory. This
subdirectory is located either under or parallel to the document root directory. The cgi-bin
directory typically contains only executable files. This is an appropriate location to place your
Messenger script file.
Many UNIX Web servers allow CGI programs to reside in directories other than cgi-bin.
However, some Web servers might require a specific extension. See your Web server
documentation for more information.
If your WebSpeed application uses static HTML files, you should place them on the Web server
machine in a subdirectory of the Web server’s document root directory (or consult your Web
server documentation for information about other options, such as creating an additional
document root directory). You must place image files (.gif), audio files (.au), and video files
(.mpeg, .mpg) on the Web server machine. These files cannot be served directly by WebSpeed.
You must place these files on the Web server machine.
10–14
Overview of the ubroker.properties file
WebSpeed objects or compiled code must be accessible and visible to the WebSpeed agents.
Make the files accessible by placing them on the machine where your Transaction Server runs.
You can make a file visible to the WebSpeed agents by adding its directory name to the
Transaction Server’s PROPATH.
Note: The AppServer and the DataServers also use the ubroker.properties file to store
configuration data. For the purposes of this guide, the ubroker.properties file focus
is on the WebSpeed Transaction Server and the NameServer. See the appropriate
manual for details about viewing and editing configurations applicable to the other
products.
For more information on the structure of the ubroker.properties file, see OpenEdge Getting
Started: Installation and Configuration.
10–15
Configuring WebSpeed on UNIX
From a Windows machine, you can also use the Progress Explorer remotely to create and
configure instances of the WebSpeed Transaction Server or the NameServer on the UNIX
platform.
If you edit the configuration by hand, without the Progress Explorer, note that:
• You should not directly change the values in the ubroker.properties file unless you have
a complete understanding of how the changes affect WebSpeed components. If you have
the Progress Explorer available from a remote Windows machine, use it to make all
changes to this file on your UNIX machines.
• For complete definitions of all the properties and detailed information on how to set them,
see the comments included in the installed file.
• If you create additional instances of the WebSpeed Transaction Server and the
NameServer, you must be sure that each of the following parameters has a value unique to
the entire ubroker.properties file:
10–16
Overview of the ubroker.properties file
– uuid — A universally unique identifier for a Transaction Server. If you use the
Progress Explorer to create the new Transaction Server, this property is
automatically set. If you manually add Transaction Server definitions, generate a
unique uuid for each Transaction Server definition by using the following command:
install-path\bin\genuuid
You can then cut and paste the value after “uuid=”.
• If you create additional instances of the WebSpeed Transaction Server and the
NameServer by copying an existing instance, be sure that each of the following parameters
has the correct values for the new instance:
– srvrStartupParam — Identify the startup parameters for your agents. Copy the
value from the ubroker.properties file’s [UBroker.WS] section to your new
Transaction Server definition, and modify.
– userName and groupName — You can optionally specify a username and a group
name that the Transaction Server runs under; if you do not specify these names, the
Transaction Server runs under the username and group name of the user who starts
the AdminServer.
Note: If you install the NameServer on a separate host from the WebSpeed Transaction
Server, the NameServer installation includes its own copy of the properties file.
You must ensure that all related properties and sections of the file are properly specified for each
Transaction Server or NameServer instance. If you do edit the file directly, use the appropriate
configuration utility (NSCONFIG or WSCONFIG) to validate the product configuration that you
have edited.
10–17
Configuring WebSpeed on UNIX
For a complete overview of all the sections in the ubroker.properties file and more
information on how to edit the file, see the comments in the file, or see OpenEdge Getting
Started: Installation and Configuration. You can use the mergeprop utility installed with
OpenEdge to manually edit the ubroker.properties file. For information on using mergeprop,
see OpenEdge Getting Started: Installation and Configuration. For more information on the
configuration utilities, see Appendix B, “Command and Utility Reference.”
The PROADSV utility provides you with the ability to start up and shut down the AdminServer on
UNIX. This command runs locally on the AdminServer machine.
proadsv -start
For more information on using the PROADSV utility, see “PROADSV” section on page B–17.
Alternately, if you are configuring WebSpeed remotely from a Windows machine, you can use
the Progress Explorer graphical user interface configuration tool.
10–18
Setting up the WebSpeed environment
Note: In distributed configurations, you must edit the appropriate environment variables on
each machine where you have WebSpeed components installed.
You can change most of these settings using the Progress Explorer (remotely, from a Windows
machine) or by editing the WebSpeed property file, ubroker.properties.
When you install the WebSpeed Transaction Server, the installation process sets PROPATH for
you in the ubroker.properties file. PROPATH initially includes a number of subdirectories in
your installation directory. In addition, the PROPATH includes a dot ( . ) directory reference.
When the agent sees the dot, the process substitutes the name of its current working directory.
For example, the agents resolve the dot to their broker’s default directory, which is the working
directory.
You can modify this and other environment variable settings in the OpenEdge shell scripts
installed on UNIX. You can override installed PROPATH settings using the PROPATH property in
the properties file (ubroker.properties).
The properties file relies on a default environment variable setting, stored in the WRKDIR
environment variable, for the working directory that you specify during installation. You can
remove or modify the references in the properties file to establish your own working directory
settings for both the WebSpeed Transaction Server and the NameServer.
10–19
Configuring WebSpeed on UNIX
For disk management reasons, you might want to specify a nondefault location for the log files
used by WebSpeed. A WebSpeed installation uses a number of different log files, which are
stored in the default working directory. For example:
After you decide where you want log files to reside, you can specify the location for each in the
Progress Explorer or by directly editing the ubroker.properties file. For more information,
see the “Configuring WebSpeed components” section on page 10–20.
Log files can grow quickly. If you have the Append option set in the Transaction Server’s
configuration, these log files do not truncate automatically. In this case, you should periodically
trim the file with a text editor. You might want to archive the file contents as you do it. For more
information on maintaining log files, see the “Maintaining the WebSpeed Transaction Server
and NameServer log files” section on page 10–24.
For more information about creating, configuring, and managing with the Progress Explorer,
see the Explorer online help.
For information about managing with the command-line utilities, see the “WebSpeed
command-line utilities” section on page 10–5.
10–20
Configuring WebSpeed components
If the weight factor that you specify for each Unified broker instance is appropriate in relation
to the others, the effect is to assign more connections to broker instances with greater resources,
and thus to balance connection load among all the instances. You can set the load-balancing
weight factor for each Unified broker instance in the Progress Explorer (from a remote
Windows machine) or by editing the priorityWeight property in the ubroker.properties
file.
For more information on load balancing and fault tolerance, see the “Understanding the
NameServer’s load-balancing option” section on page 9–23. Also see the OpenEdge Getting
Started: Installation and Configuration.
Note: The NameServer can be on any machine in your network, even a Windows machine.
In addition, you can configure your Transaction Server to run without a NameServer.
For more information, see the “Eliminating the NameServer” section on page 9–21.
10–21
Configuring WebSpeed on UNIX
1. The AdminServer must be running. If the AdminServer is not running, use the PROADSV
command to start it. (See the “Starting the AdminServer” section on page 10–18.)
2. Start an existing NameServer or create a new NameServer instance. You can create and
start a NameServer by using the Progress Explorer, or you can edit the
ubroker.properties file to create an instance and then use the NSMAN utility to start the
instance. When you configure a NameServer instance, you can set it to start up by default
whenever the AdminServer starts.
If you are using the Progress Explorer, see the online help for information about creating
and starting an instance. If you are editing the ubroker.properties file, see the “Editing
the ubroker.properties file” section on page 10–16.
To start a local instance of the NameServer from the command line, use the following
command:
To start a remote instance of the NameServer from the command line, use the following
command:
Where host-name is the name of the host machine on which you want the instance to run;
port is the port number on the AdminServer. The user-name and password in the
properties file are used when starting a NameServer in this manner from a UNIX system.
10–22
Starting the WebSpeed Transaction Server and NameServer
If you are using the Progress Explorer, see the online help for information about creating
and starting an instance. If you are editing the ubroker.properties file, see the “Editing
the ubroker.properties file” section on page 10–16.
To start a local instance of the WebSpeed Transaction Server from the command line, use
the following command:
To start a remote instance of the WebSpeed Transaction Server from the command line,
use the following command:
Where host-name is the name of the host machine where you want the instance to run;
port is the port number on the AdminServer. The user-name and password in the
properties file are used when starting a NameServer in this manner from a UNIX system.
By using either the Progress Explorer or the command-line utilities, you can also stop a
NameServer or WebSpeed Transaction Server instance, check its status, and increase or reduce
the number of running WebSpeed agents. For more information, see the Progress Explorer
online help. Also see the “Using the Progress Explorer to check status” section on page 10–26
and the “Managing the WebSpeed Transaction Server” section on page 10–28.
10–23
Configuring WebSpeed on UNIX
If you have the Append option set in the Transaction Server’s configuration, these log files do
not truncate automatically. In this case, you should periodically trim the file with a text editor.
You might want to archive the file contents as you do it.
For more information how to configure the log files for your environment, see the “Configuring
WebSpeed and NameServer log files” section on page 10–20.
The WebSpeed Messenger must reside on the same machine as the Web server. The Web server
and the WebSpeed Messengers need not be on the same machine as the rest of the WebSpeed
components. Instead, you can install the Web server and the WebSpeed Messengers together on
a different machine if you want.
In this configuration, the Messenger must be able to connect remotely to the machines where
the NameServers and AdminServers are installed. To do this, you must configure a remote
NameServer. For more information on this, see OpenEdge Getting Started: Installation and
Configuration.
10–24
Starting WebSpeed to test the configuration
1. Make sure the AdminServer is running. If the AdminServer is not running, use the
PROADSV utility, which is installed in install-path/bin, as shown:
proadsv -start
2. Make sure the NameServer is running. If the NameServer is not running, use the NSMAN
utility to start it.
Typically, the sample NameServer (NS1) starts automatically with the AdminServer. You
can use this sample NameServer, or you can create a new NameServer by editing the
ubroker.properties file. Start the new NameServer with the NSMAN utility.
3. Start an existing WebSpeed Transaction Server. You can use the sample WebSpeed
Transaction Server (wsbroker1), or you can create a new Transaction Server by editing the
ubroker.properties file; then start the new Transaction Server with the WTBMAN
command.
You can also use the Progress Explorer remotely from a Windows machine to start the
NameServer or the WebSpeed Transaction Server. See the Progress Explorer online help for
information.
10–25
Configuring WebSpeed on UNIX
• Use the -query option of the NSMAN, PROADSV, and WTBMAN utilities to check the status of
components.
To query the AdminServer, use the PROADSV utility, which is installed in install-path/bin, as
shown:
proadsv -query
To query a local NameServer, use the NSMAN utility, which is installed in install-path/bin, as
shown:
To query a remote NameServer, add the following parameters to the command, as shown:
nsman -name NameServer-name -host host-name -port port -user user-name -query
10–26
Testing your configuration
To query a local WebSpeed Transaction Server, use the WTBMAN utility, which is installed in
install-path/bin, as shown:
Where ts-name is the name of the Transaction Server that you want to query. You can have
more than one Transaction Server running on a single machine.
To query a remote WebSpeed Transaction Server, add the following parameters to the
command:
wtbman -name ts-name -host host-name -port port -user user-name -query
The query reports on the Transaction Server’s pool of WebSpeed agents. For each agent, it lists
a process ID, its port number, its status, how many requests it has serviced, when it started, and
when its status changed. These are the agent status types:
• BUSY — The agent is actively executing application logic (Web object) for a Web user.
• LIMBO — The agent is in a transitional state. If the status persists, it indicates an error
condition.
• LOCKED — The agent is dedicated to a particular Web browser and is only available to
the browser whose application locks it.
• STARTING — The broker has launched the agent, but the agent has not yet initialized.
See the “Managing the WebSpeed Messenger” section on page 10–30 for the URL for the
WSMAdmin page.
10–27
Configuring WebSpeed on UNIX
To run the status.p procedure from a Web browser, enter a URL using the following format:
http://hostname/script-dir/Messenger/WService=brokername/src/web/
examples/status.p
You can also use the Progress Explorer remotely from a Windows machine to manage and
validate the Transaction Server. (With the Progress Explorer, you can also configure the
Transaction Server.) See the Progress Explorer online help for more information.
In addition to allowing you to start, query, or stop the Transaction Server, the WTBMAN utility lets
you do the following:
10–28
Managing the WebSpeed Transaction Server
Where broker is the name of the Transaction Server specified in the ubroker.properties file
and number-to-start is the number of additional agents you want to start. The number you
specify must not exceed the maxSrvInstance value in the ubroker.properties file or your
license limit.
Trimming agents
To trim agents, enter the following command:
Where broker is the name of the Transaction Server and number-to-trim is the number of
agents you want to stop.
To force an immediate shutdown of the Transaction Server and all its agents, enter the following
command:
10–29
Configuring WebSpeed on UNIX
wtbman -help
http://host-name[:port]/wsnsa.dll[/WService=appservice-name]?WSMAdmin
Where host-name is the name of the host where the Messenger is running, port is the port that
your Web server uses (if different from the default port 80), and appservice-name is the name
of the Transaction Server or NameServer.
For example, the following URL requests the Administration page for the NSAPI Messenger on
a host named mars:
http://mars/wsnsa.dll/WService=wsbroker1?WSMAdmin
http://host-name/scripts/cgiip.exe[/WService=appservice-name]?WSMAdmin
Where host-name is the name of your Web server machine, port is the port that your Web
server uses (if different from the default port 80), scripts is your Web server’s scripts
directory, and appservice-name is the name of the application service.
10–30
11
WebSpeed Dynamic Code-page Support
This chapter explains how WebSpeed dynamic code-page support works and how to configure
it.
To understand this chapter, you should be an experienced WebSpeed developer familiar with
internationalization, code pages, and Unicode. For information on developing WebSpeed
applications, see the OpenEdge Application Server: Developing WebSpeed Applications. For
information on internationalization, code page, and Unicode, see the OpenEdge Development:
Internationalizing Applications.
• Introduction
Introduction
WebSpeed dynamic code-page support lets a WebSpeed agent running one code page and a
Web browser running a different, but compatible, code page exchange data without corrupting
it.
With dynamic code-page support, a single agent with the CPINTERNAL code page set to UTF-8
(an encoding of Unicode) can handle requests from multiple browsers each running a different
code page.
11–2
How dynamic code-page support works
When a Web request reflecting a response to a language-selection page is received by the agent,
the application:
3. Determines the MIME version (as opposed to the OpenEdge version) of the code-page
name.
4. Converts the MIME version of the code-page name to the OpenEdge version.
5. Sets a cookie called wscharset to the MIME version of the code-page name.
Or:
Sets a query field or a hidden-form field called wscharset to the MIME version of the
code-page name.
When a Web request reflecting a response to a Web page other than a language-selection page
is received by the agent, WebSpeed’s web-disp.p procedure:
1. Searches for the code-page name in a query field called wscharset or a hidden-form field
called wscharset. If the code-page name was not found, it searches in a cookie called
wscharset.
2. Converts the code-page name from MIME format to OpenEdge format and stores the
result in the WEB-CONTEXT handle’s HTML-CHARSET attribute.
11–3
WebSpeed Dynamic Code-page Support
Then, the application ensures that the MIME version of the code-page name will appear in the
Web page the application will create. The technique used depends on whether the Web page is
created using static HTML or dynamic HTML. For example:
• If the Web page is created using static HTML, the application should contain a META tag
with the MIME version of the code-page name, as in the following:
• If the Web page is created using dynamic HTML, the application uses the
OUTPUT-CONTENT-TYPE() WebSpeed API function to insert the MIME version of the
code-page name into the HTML document.
Once WebSpeed’s web-disp.p procedure stores the OpenEdge version of the code-page name
in HTML-CHARSET, the agent uses HTML-CHARSET to perform the following code-page
conversions:
1. Just after an incoming Web request is received, the agent converts it from the
HTML-CHARSET code page to the agent’s CPINTERNAL code page.
2. Just before an outgoing Web page is sent, the agent converts it from the agent’s
CPINTERNAL code page to the HTML-CHARSET code page.
11–4
Summary of code-page conversions
• Just before the agent sends a Web page, if the WEB-CONTEXT handle’s HTML-CHARSET
attribute is set, the agent converts the Web page from the agent’s CPINTERNAL code page
to the HTML-CHARSET code page.
• Just before the agent sends a Web page, the agent converts it from the agent’s CPINTERNAL
code page to the SESSION:CPSTREAM code page.
For more information, see Chapter 12, “Connecting WebSpeed to a Data Source.”
11–5
WebSpeed Dynamic Code-page Support
1. The WebSpeed application should include a page that lets the user select a language or
nationality from a list of preselected languages or nationalities. For each language or
nationality in the list, the developer determines an appropriate code page, which must be
compatible with the WebSpeed agent’s CPINTERNAL code page. To simplify meeting this
requirement, make the agent’s CPINTERNAL code page UTF-8, which is highly compatible
with OpenEdge code pages. (For more information, see install-path/prolang/readme.)
3. The application notes the language or nationality selected, determines the corresponding
code page, and stores the MIME version of the code-page name within the Web request in
a query field, a hidden-form field, or a cookie.
Note: Any static HTML the application uses should be in the same code page selected by
the user. and should refer to the same code page in the <META> tag’s HTTP-EQUIV
attribute. See the first code example in the “Storing the MIME code-page name”
section on page 11–8.
Each time the agent receives information from a Web browser, it automatically converts
the information from the browser’s code page to the agent’s CPINTERNAL code page.
Similarly, just before the agent sends a Web page back to the browser, it automatically
converts it from the agent’s CPINTERNAL code page to the browser’s code page.
11–6
Tasks for the WebSpeed developer
iso-8859-2 iso8859-2
Shift_JIS SHIFT-JIS
TIS-620 620-2533
windows-1250 1250
Note: Table 11–1 does not list all code pages that can be used with dynamic code-page
support. For a complete list of these code pages, see the source code for
adecomm/convcp.p.
For more information on converting between MIME and OpenEdge code-page names, see the
“Converting code-page names between MIME and OpenEdge formats” section on page 11–9.
11–7
WebSpeed Dynamic Code-page Support
• Using HTML, store the MIME code-page name in a hidden-form field or a query field
called wscharset.
In the following fragment, the MIME code-page name is stored in a hidden-form field
called wscharset:
<HEAD>
<META HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=windows-1252">
</HEAD>
<BODY>
<FORM METHOD="POST" ACTION="test.w">
Name: <INPUT TYPE="text" ID="name"><BR>
Address: <INPUT TYPE="text" ID="address"><BR>
City: <INPUT TYPE="text" ID="city"><BR><BR>
<INPUT TYPE="hidden" NAME="wscharset" VALUE="windows-1252">
<INPUT TYPE="submit" VALUE="Submit">
</FORM>
</BODY>
In the following fragment, the MIME code page is stored in a query field called wscharset:
<A HREF="tstiso2.w?wscharset=iso-8859-2”></A>
• Use the SET-COOKIE WebSpeed API function to create a cookie called wscharset
containing the MIME code-page name, as shown in the following fragment:
• Dynamic code-page support does not work if the code-page name is stored using the
CHARSET attribute of the META tag exclusively or the WebSpeed API
outputContentType() function exclusively. You must also store the code-page name in
wscharset. Also, the stored code-page names must match.
11–8
Storing the MIME code-page name
Syntax
input-name
direction
output-name
A CHARACTER expression indicating the name of a CHARACTER variable to contain the result.
11–9
WebSpeed Dynamic Code-page Support
The following example converts the value of cMimeCharset to OpenEdge format and stores the
result in cProCharset:
The following example converts the value of cProCharset to MIME format and stores the result
in cMimeCharset:
Additional notes
Here are additional notes on developing applications with dynamic code-page support:
• The page for selecting a language or nationality not use fill-in fields. If fill-in fields are
used, the application might not be able to determine which code page the fill-in fields are
encoded in.
• If your Web server can perform code-page conversion, turn this feature off if you want to
use the dynamic code-page support supplied by WebSpeed.
• See the “Creating an international Web site” section on page 12–9 for information on how
to configure WebSpeed to support internationalization.
11–10
12
Connecting WebSpeed to a Data Source
This chapter describes how to connect WebSpeed agents to a data source for application
development or deployment, as outlined in the following sections:
In a local configuration, the OpenEdge database resides on the same machine as the WebSpeed
Transaction Server. The structure of a remote configuration can vary. OpenEdge Getting
Started: WebSpeed Essentials shows some of the configuration possibilities. When you are
developing in a client/server environment, you can connect to the database in single-user mode.
When you develop WebSpeed applications on a Windows system with the WebSpeed
Workshop, you must run the OpenEdge database in a multi-user mode. In the WebSpeed
Workshop development environment, several agents must connect to the database
simultaneously: one for the Progress Explorer, another for the WebSpeed WebTools, and one
for the AppBuilder.
See the chapter on startup in the OpenEdge Data Management: Database Administration for
more information on running the OpenEdge database server and the parameters that you can
specify.
You provide the information that an agent needs to connect to a database when you configure a
WebSpeed Transaction Server and specify the agent options for its pool of agents. The
WebSpeed agent is a 4GL client running in batch mode and can accept nearly all the startup
parameters a standard client can.
WebSpeed provides many parameters that allow you to control connections to the database and
make adjustments to increase performance. These include parameters for controlling
record-buffer size, cursor size, and read-only access. In addition to database connection
parameters, WebSpeed provides session parameters that allow you to control the conditions
under which it compiles your r-code and Web objects and how to handle code page issues. See
the OpenEdge Deployment: Startup Command and Parameter Reference for details on session
parameters.
12–2
Connecting to an OpenEdge RDBMS
Connecting programmatically
You can also provide connection information programmatically with the SpeedScript CONNECT
statement. You can specify a parameter file that includes connection information with the
CONNECT statement. However, you cannot connect to a database in the same procedure that
accesses that database. You cannot connect to a database within an embedded SpeedScript
program that then accesses the database tables and fields. Instead, you should include the
CONNECT statement in a separate procedure (.p) that the embedded SpeedScript calls. This
ensures that all agents receive the information they need to connect to the database.
By default, this connection uses shared memory. If you want to use a network connection
instead, specify the Host Name (-H) and Service Name (-S) parameters (described in Table
12–1) when you connect to the database. The network type defaults to TCP.
12–3
Connecting WebSpeed to a Data Source
Parameter Description
Host Name (-H) Indicates the name of the machine where the database
server resides.
Service Name (-S) Indicates the name of the available service you are
calling. This is the service that the database server uses,
not a WebSpeed service. See your \etc\services file
for a list of available services. Note that the database
server does not have to use a named service.
The remote database is on the pluto host and the database server uses the service, mysv12.
12–4
Connecting to a Non-OpenEdge data source through a DataServer
The following sections supplement the information provided by the applicable OpenEdge
DataServer guide. The sections describe the general tasks that you must perform to install and
configure your DataServers in a WebSpeed environment. The sections also provide specific
instructions for connecting WebSpeed agents to the various data sources.
Before developing a WebSpeed application that accesses a non-OpenEdge data source, read
your DataServer Guide for information on writing SpeedScript code that gives you the results
and behavior you expect for your data source. Some elements of SpeedScript do not behave as
documented in the standard WebSpeed documentation when accessing non-OpenEdge data
sources. There is also additional syntax that allows you to optimize queries by leveraging the
strengths of individual database managers that the standard documentation does not describe in
detail.
Typically, integrating a non-OpenEdge data source into your WebSpeed environment involves
the following basic steps:
• Building a schema holder that contains the data definitions in a format required by
WebSpeed applications.
• Configuring WebSpeed agents to connect to the schema holder and data source.
Planning where to locate a DataServer is a similar process regardless of which DataServer you
use. The other steps, however, vary across DataServers. See the appropriate OpenEdge
DataServer guide for instructions.
12–5
Connecting WebSpeed to a Data Source
Figure 12–1 shows a DataServer that is local to the WebSpeed Transaction Server. The database
also resides on this machine. (However, the database does not have to be local.)
WebSpeed
Transaction
Server
DataServer
Schema
Database
holder
12–6
Connecting to a Non-OpenEdge data source through a DataServer
Figure 12–2 shows one possible configuration for the remote DataServer where a WebSpeed
agent accesses a remote DataServer. Here, the database and the DataServer are running on the
same machine. The schema holder is local to the WebSpeed Transaction Server to increase
performance.
WebSpeed
DataServer
Transaction
Server
Schema
Database
holder
The figures show a schema holder on the same machine where your agents run. A local
read-only schema holder gives you better performance. However, you might decide that you
want your schema holder on a separate machine to make better use of processing resources.
Note that none of the configuration diagrams include a Web server. The Web server plays no
role after passing the initial Web request for data to the WebSpeed Messenger. Much like a
typical OpenEdge client, the WebSpeed agent interacts with the DataServer, which in turn
passes queries and data requests to the database management system.
You can integrate DataServers for ODBC and ORACLE into the Progress Explorer
administrative framework, which allows you to have a single administrative system and take
advantage of the NameServer’s load balancing. Alternately, the WebSpeed agents can access
DataServers that cannot be managed by the AdminServer.
There are variations on these configurations that allow you to combine Windows and UNIX
platforms or to distribute the components using vendor networking (for example, ORACLE’s
SQL*Net). See your OpenEdge DataServer guide for more information. The DataServer guides
present configuration information in traditional client/server terms; when reading this material
for implementing WebSpeed, substitute WebSpeed agent for Client.
12–7
Connecting WebSpeed to a Data Source
1. Start the DataServer processes and create the schema holder. The WebSpeed Transaction
Server does not have to be running at this time.
3. Configure the WebSpeed agent to use the parameter file that you created by specifying the
Parameter File (-pf) parameter. For example, if you created a parameter file named
db2dbcon.pf, your entry in the Startup Parameters field on the Server Parameters tab in
the Progress Explorer might be:
When the WebSpeed broker whose agents you configured with DataServer connection
information receives a Web request, it selects an agent from its pool to service the request
by connecting to the non-OpenEdge database and, through the DataServer, retrieving or
updating data.
12–8
Creating an international Web site
Also, consider using UTF-8 (an encoding of Unicode) for the encoding of the database and for
the CPINTERNAL code page of the WebSpeed agents. This approach is strongly recommend
by Progress Software Corporation. For more information on Unicode, see OpenEdge
Development: Internationalizing Applications.
Also, consider using WebSpeed dynamic code-page support. For more information, see Chapter
11, “WebSpeed Dynamic Code-page Support.”
12–9
Connecting WebSpeed to a Data Source
Figure 12–3 shows a WebSpeed configuration that supports an international Web site.
Web
Server Web
Browsers
NameServer
Messenger
wsSpain
Unicode
12–10
Creating an international Web site
This configuration creates a Web site that handles requests from users in Spain, Japan, and the
United States. In this example, all countries share a single Unicode (UTF-8) database. This
particular Web site expects the highest rate of access from its Spanish users, so it has multiple
Transaction Servers and agent pools configured to handle the Web requests. These Transaction
Servers are, in turn, registered with a NameServer. The NameServer can manage the Spanish
Transaction Servers as they have access to equivalent resources, that is, their agents are all
configured identically: they use the same internal code page and they connect to the same
database in the same manner. Web requests coming from Japanese and U.S. users are each
serviced by a single Transaction Server and its agent pool.
When setting up a Transaction Server’s environment, you must ensure that when a message is
issued by a WebSpeed agent, the Transaction Server displays it in the appropriate language. To
accomplish this, set the PROMSGS variable in the ubroker.properties file’s Environment
section for each Transaction Server definition. You cannot set PROMSGS at a system level,
because multiple Transaction Servers requiring different translations of messages will run
simultaneously. The international PROMSGS files have a three-letter extension that indicates the
language. The following example sets PROMSGS to the Japanese version of the messages file:
Define and configure your Transaction Servers as you would for a standard WebSpeed
installation.
If it is important that you have messages displaying in the user’s language at all levels of the
application, you can use the CGI-compatible Messenger. The NSAPI-compatible Messenger
can use only one PROMSGS file, which you configure in its startup script. For the CGI Messenger,
you can create a script file (based on wspd_cgi.sh) for each language and specify the
appropriate PROMSGS file to use.
12–11
Connecting WebSpeed to a Data Source
Configuring agents
To configure agents to run in an international environment, you must address code-page issues
and session options when you specify agent parameters. OpenEdge automatically installs the
language you select as the default and configures your machine for this default language;
however, you must configure each agent to use the appropriate parameters for the country it
accepts requests from. Using a parameter (.pf) file helps you manage agent startup and
connection information.
In Windows, use the Progress Explorer to configure the agents. You add the Parameter File (-pf)
startup parameter and name of your parameter file to the Startup Parameters field for the agent
Executable File.
On UNIX, use the Progress Explorer from a remote Windows machine or manually update the
ubroker.properties file to configure the agents. You add the Parameter File (-pf) startup
parameter and name of your parameter file to the srvrStartupParam option in the section of the
ubroker.properties file where you define the Transaction Server.
For each supported international language, OpenEdge provides an example parameter file that
you can use as the base for creating your own.
The following examples show the contents of parameter files for the Spanish, Japanese, and
U.S. agents, respectively. They are based on the parameter files provided by OpenEdge in the
prolang/lang directory, as shown:
These files provide the information that agents need to connect to a local database and to run
with session options appropriate to their cultural context. For example, each agent displays
dates in a distinct format; in addition, the Spanish agents use the comma as a radix for decimal
data. You can add other parameters to the parameter file to further manage how agents connect
to the databases.
12–12
Creating an international Web site
Here is a sample setting for the srvrStartupParam option in the section of the
ubroker.properties file where you define the wsJapan Transaction Server:
Alternatively, the WebSpeed application can let the language or nationality be selected by the
user. From the user’s selection, the application can set the CPINTERNAL, CPSTREAM, and
DATE-FORMAT attributes of the SESSION handle to the appropriate values.
Code pages
The agent’s CPINTERNAL code page (that is, the code page used by the agent for its internal
processing) must be compatible with the code page of the database it connects to. This is easy
to accomplish if the databases’s code page is UTF-8.
The agent’s CPSTEAM code page (which the -cpstream parameter specifies) must be the same
as the agent’s CPSTREAM code page (assuming dynamic code-page support is not used).
Session options
Supporting an international Web site means more than just supporting several languages. You
must also support the cultural difference in date formats and numeric notations. WebSpeed
allows you to control how agents display and process date information and numeric
conventions. The Date (-d) parameter lets you specify the format that an agent uses to process
dates. By default, an agent processes dates as month, day, year. To display a date as day, month,
year, specify -d dmy in the agent’s parameter (.pf) file. The European Numeric Format (-E)
parameter specifies that a comma (,) represents the decimal point instead of a period (.).
In Windows, another aspect of an agent’s session environment that you control through startup
parameters is which initialization (.ini) file an agent uses. If you want an agent to display error
messages in a language other than the default language you chose for your WebSpeed
installation, you must use an initialization file to set the PROMSGS option to the appropriate
version of the PROMSGS file. The WebSpeed agent can use the [WinChar Startup] section of the
initialization file, so you must set PROMSGS there. Specify the Initialization File (-ininame)
parameter to specify the name of the initialization file you customized for the agent.
12–13
Connecting WebSpeed to a Data Source
Assuming that the sample configuration shown in Figure 12–3 is running with an
NSAPI-compatible Web server, the URLs for the links that Japanese, Spanish, and U.S. users
would select are as follows:
http://mars/wsnsa.dll/WService=wsJapan/iwebapp
http://mars/wsnsa.dll/WService=wsUSA/iwebapp
http://mars/wsnsa.dll/WService=wsSpain/iwebapp
The URLs for Japan, Spain, and the U.S. name WebSpeed Transaction Servers to service the
Web request.
12–14
13
WebSpeed Security
This chapter highlights some security issues related to WebSpeed, as described in the following
sections:
You can access these properties from either the Progress Explorer, or the ubroker.properties
file that resides in the install-path\properties directory. You can use the mergeprop utility
installed with OpenEdge to manually edit the ubroker.properties file. For information on
using mergeprop, see OpenEdge Getting Started: Installation and Configuration.
13–2
Changing WebSpeed applications from development mode to production mode
Table 13–1 details the functionality differences between the production and development
modes.
Production • Prohibits Web objects specified in the URL with the path
install-path\src\web\ from being run.
You can use the Progress Explorer Tool to change the value of the Agent application mode from
development to production.
13–3
WebSpeed Security
1. Double click the WebSpeed folder on the left-hand side of the main Progress Explorer
window.
3. Choose Properties on the shortcut menu. The broker Properties dialog box displays.
Another method of changing the application mode from development to production is to edit the
ubroker.properties file.
13–4
Changing WebSpeed applications from development mode to production mode
1. Determine if you need to set all brokers or just individual brokers to a Production mode.
The property values established in the various sections of the ubroker.properties file are
governed by a parent-to-child inheritance relationship. For example, values set in the
parent, the [UBroker] section, are inherited at the [UBroker.WS] level. Similarly, values
defined at the [UBroker.WS] level are inherited as default values by each individual broker
instance in the [UBroker.WS.brokername] sections.
Alternatively, you can retain the property values established at the parent level and
override only those individual values at the lower, child level that you need to change.
2. Search the ubroker.properties file for the srvrAppMode property in the section, or
sections, that you need to change.
– To affect all brokers, search for srvrAppMode property in the [UBroker.WS] section.
– To affect one or more individual brokers, search for or add the srvrAppMode property
in the individual [UBroker.WS.brokername] section.
When enabled in the Development mode, this utility can help you debug problems in a
WebSpeed configuration. However, if you leave this utility enabled when you move your
system from Development mode to Production mode, you expose your system information to
unauthorized access.
Ensure that you disable the WebSpeed Messenger Administration utility before you deploy your
WebSpeed applications.
13–5
WebSpeed Security
There is one exception to this guideline. If you are using WSMAdmin with the WebSpeed
Messenger Administration Internet Protocol List option, you can leave the WebSpeed
Messenger Administration utility enabled in Production mode. See the “Establish the
WebSpeed Messenger Administration Internet Protocol List (Optional)” section on page 13–7
for more information.
Disabling WSMAdmin
You can use the Progress Explorer Tool to disable the WSMAdmin utility.
1. Double click the Messengers folder on the left side of the main Progress Explorer
window.
2. Right click the specific messenger whose internal commands you want to disable.
3. Choose Properties from the shortcut menu. The Properties dialog box for the selected
messenger appears:
4. Deselect the check box next to the Internal Administration Command - WSMAdmin
field.
13–6
Changing WebSpeed applications from development mode to production mode
5. If you are changing this value for either a WSISA or WSNSA Messenger, re-start your
web server.
Verify that the Messenger Internal Commands are disabled. You should not be able to
access the WSMAdmin utility and its features from a Web browser.
You can also disable the internal commands for a WebSpeed messenger by editing the
ubroker.properties file.
1. Search the file for the AllowsMsngrCmds property. It is located in the properties section that
is associated with the specific messenger type that your configuration is using.
For example, if you are using a CGIIP Messenger, the AllowsMsngrCmds property you
must set is in the [WebSpeed.Messengers.CGIIP] section.
2. Set the property value to 0 to disable the WebSpeed Messenger Administration utility
commands.
Verify that the Messenger Internal Commands are disabled. You should not be able to
access the WSMAdmin utility and its features from a web browser.
You can use the Internet Protocol List option only if you enable the WebSpeed Messenger
Administration utility. This utility maintains control over your list of IP addresses. Using the
Internet Protocol List allows you the opportunity to debug specific applications remotely
without exposing Web applications to unwanted access.
13–7
WebSpeed Security
1. Double click the Messengers folder on the left-hand side of the main Progress Explorer
window.
2. Right click the specific messenger whose internal commands you want to enable.
3. Choose Properties from the shortcut menu. The Properties dialog box for the messenger
you selected displays.
6. Press the Add button. The IP address you added now displays in the large text box above
the IP address field.
7. For each additional IP address that you add, repeat steps 5 and 6. Additional addresses
appear in the list, as shown:
8. Click the OK button when you have added all address entries.
13–8
Changing WebSpeed applications from development mode to production mode
1. Search the file for the AllowsMsngrCmds property. It is located in the messenger
properties section that is associated with the specific messenger type that your
configuration is using.
For example, if you are using a CGIIP Messenger, you must set or add the
AllowsMsngrCmds property in the [WebSpeed.Messengers.CGIIP] section.
2. If the AllowsMsngrCmds property is disabled, set the property value to 1 to enable it.
3. Add the wsmAdmIPList property and type each unique IP address that you want to identify,
separating each address with a comma.
Caution: Do not leave the IP address field blank (default value) because it will enable any IP
address to access the WebSpeed Messenger’s internal commands.
When your application is in Production mode, the Debug mode is always off, regardless of the
value on the Debug setting. When you are in Development mode, you can set values for the
Debug mode to enable or disable debugging.
13–9
WebSpeed Security
To check the status of the Debug mode using the Progress Explorer Tool:
1. Double click the WebSpeed folder on the left-hand side of the main Progress Explorer
window.
5. The Agent application mode value governs which Debug mode values are available:
– If the value set for the Agent application mode is Production, the Debug mode is
always off, regardless of the value that displayed on the Debug setting.
– If the value set for the Agent application mode is Development, you can set values
for the Debug mode that allow you to enable or disable debugging.
To check the status of Debug mode from the ubroker.properties file, perform:
1. Review the srvrAppMode setting for the broker property sections that you want to affect.
It will be either Production or Development.
2. Add the srvrDebug property to the broker property sections that you need to change.
13–10
Changing additional settings to minimize security risks
• Change all default port numbers to random, available port values between the range of
1025 and 65536 before you deploy WebSpeed. Table 13–2 lists some key default port
numbers to consider changing.
20931 AdminService
5162 NameServer
• Change all default WebSpeed broker names, AdminService names, and NameServer
names from their system-supplied default names to proprietary names to protect their
identities.
13–11
WebSpeed Security
• FTP directories.
The following list identifies key files and suggests some ways to shield the identify of each file:
• Rename the default WebSpeed Messenger filename associated with the messenger type
that you are using: cgiip.exe, wsisa.dll, or wsnsa.dll.
• Use a file association technique to shield the identity of the default WebSpeed Messenger
and broker filenames when they are run. This activity is only supported if you are using a
Microsoft Internet Information Web Server (IIS Web Server) on a Windows platform, and
your WebSpeed Messenger type is cgiip.exe. This technique allows you to define a file
extension that can run an executable. The file extension, which includes the default
filenames of the WebSpeed Messenger and broker, obscures the identity of these files as
it passes the broker name to the executable that runs them.
For detailed instructions on how to perform this file association technique, refer to the
cgiip.wsc file that is shipped with the WebSpeed product.
• If you are using a UNIX platform, consider changing the default script name,
wspd_cgi.sh, to a less immediately identifiable name to hide the WebSpeed messenger
and WebSpeed broker names that the wspd_cgi.sh file contains.
13–12
Authenticating a password using SpeedScript
Note: As previously mentioned earlier in this section, do not include references to the file
upload directory in your PROPATH.
Note: For a more information about security issues as they pertain to WebSpeed
configurations and their integration with firewalls, see the “Maximizing WebSpeed
compatibility with your firewall” section on page 13–19.
• Ensure that a user is, in fact, a valid user who is recognized by the system.
• Grant this authenticated user access only to the system resources to which this individual
is assigned, or authorized to use.
13–13
WebSpeed Security
Note: The Get method is not recommended in this type of authentication process because it
automatically displays the value of your password in your browser’s URL field.
To modify this example to query a table that contains user and password information that
must be verified:
<html>
<head>
<title>Password Example</title>
</head>
<body>
<form method="post" action="val.html"
Enter Password:<input type="password" name="pass" value=""><br>
<input type="submit" name="action" value="process">
</form>
</body>
</html>
13–14
Securing data transmissions between WebSpeed client and server components
4. Create another blank HTML file and enter the following code:
<html>
<head>
<title>Password Page 2</title>
</head>
<body>
<script language="SpeedScript">
define variable pass as character.
If get-value("pass") = "mypass" then do:
{&out} "Accepted".
/*Could also run an .html or .r file from here, using the run statement.*/
end.
else do:
{&out} "Denied".
/*Could also redirect the user to an .html or .r file from here, using
the run statement.*/
end.
</script>
</body>
</html>
5. Close and save this second file with the filename val.html.
The word Accepted appears to verify the acceptance and validation of the username and
password values.
If you intend to use secure transmissions, it is important that you read OpenEdge Getting
Started: Core Business Services for a more detailed discussion of these technologies. This
manual explains the relevant concepts and gives instructions for using the keys, certificates, and
management tools that OpenEdge provides.
13–15
WebSpeed Security
HTTPS provides many benefits for WebSpeed users to support their e-commerce efforts;
encryption, authentication, and message integrity are just a few of the benefits of using this
protocol.
WebSpeed Messengers are compatible with HTTPS; however, configuration of your system to
use HTTPS between browser clients and the Web server does not involve any OpenEdge
components. Refer to your Web server documentation to configure the Web server for HTTPS
communications.
The SSL protocol resides above the network protocol, as defined by Transmission Control
Protocol/Internet Protocol (TCP/IP), and directly below the application protocols, such as
HTTP, HTTPS, or IMAP. It uses TCP/IP on behalf of the application protocols and, in the
process, enables the following activities to occur:
OpenEdge supports SSL communications between the WebSpeed Messenger and the
WebSpeed Transaction Server, as described in the next section.
13–16
Securing data transmissions between WebSpeed client and server components
You have the option of configuring any WebSpeed Transaction Server instance to require
Secure Sockets Layer (SSL) client connections. You can maintain both SSL-enabled and
non-SSL Transaction Server instances, but a given instance supports only one type of
connection, either secure or non-secure.
Security derives from the client authentication of the server's identity via a Public Key
Infrastructure (PKI) and a symmetric data encryption system. To configure a Transaction Server
instance for SSL operation, you must:
• Obtain and install a server private key and a public key certificate. OpenEdge provides
built-in keys and certificates that are suitable for use on development or demonstration
servers; for production machines, you should obtain server certificates from an internal or
public Certificate Authority (CA).
• Specify an alias and password for access to the private key/digital certificate.
To perform these configuration tasks, you can use the Progress Explorer (in Windows only) or
manually edit the ubroker.properties file, as explained in the next section.
13–17
WebSpeed Security
To enable SSL communications, you must configure both the WebSpeed Messenger and the
WebSpeed Transaction Server.
• The Messenger must be SSL-enabled, meaning that it sends SSL data to the Transaction
Server that is to process the client requests. To configure the Messenger to send SSL
requests, you set the property sslEnable=1. You set this property by checking the Enable
SSL AppServer connections box in the SSL properties category in the Progress Explorer,
or by manually editing the ubroker.properties file. In addition, you must obtain and
install public key certificates for the Messenger host machine.
• Determine whether you want the Messenger to verify the host name for the WebSpeed
Transaction Server by comparing it with the Common Name specified in the server digital
certificate, and raise an error if they do not match (the default behavior). You can disable
this verification by setting the property noHostVerify=1. To do so, check the Disable
Client Verification of SSL Host Name box in the Progress Explorer, or manually edit the
ubroker.properties file.
• Determine whether you want the Messenger to request reuse of the session ID for
successive connections to the same Transaction Server (the default behavior). If not, set
the property noSessionReuse=1, either by checking the Disable SSL Session Reuse box
in the Progress Explorer or by editing the ubroker.properties file. (The default behavior
does not guarantee that session IDs can be reused, because the server might disallow
session reuse.)
• The Transaction Server must be SSL-enabled, meaning that it accepts SSL requests from
the Messenger. You set the property sslEnable=1 by checking the Enable SSL Client
Connections box in the SSL General properties category in the Progress Explorer, or by
manually editing the ubroker.properties file. You must also obtain and install a server
private key and public key certificate, unless you are using the defaults provided with
OpenEdge.
13–18
Maximizing WebSpeed compatibility with your firewall
• In the SSL General properties category in the Progress Explorer, select the alias for the
private key/digital certificate entry (in the OpenEdge keystore) that you want to secure
connections for this Transaction Server. Also enter and confirm the password for this
private key and digital certificate. You need not enter a password if you choose to use the
default_server certificate and its default password. (Note: The password is encrypted in
the ubroker.properties file; if manually editing the file, you must use the genpassword
utility to encrypt the password. The properties appear in the file as keyAlias= and
keyAliasPasswd=.)
• In the SSL Advanced Features properties category in the Progress Explorer, you can enter
a timeout value that specifies the length of time (in seconds) that a disconnected session is
held in the cache. During this specified interval, a connected client can resume its session.
To disable session caching, check the box, or edit the ubroker.properties file and set the
property noSessionCache=0. The timeout value appears in the file as sessionTimeout=n.
For more information on setting properties for WebSpeed Messengers and Transaction Servers
and other Unified Broker products, see the Progress Explorer help or the
OpenEdge-Install-Directory\properties\ubroker.properties.README file.
The main purpose of a firewall is to restrict access to your Web site to ensure that only
authorized, authentic users are allowed to connect through specific communication access, or
controlled, points. The following topics highlight important security issues related to OpenEdge
and WebSpeed communication ports and traffic that interact with the firewall:
• Using the NameServer client port range value settings with a firewall
13–19
WebSpeed Security
Table 13–3 identifies the network communications requirements for your WebSpeed
configuration.
Web browser to The Web browser must have access to the Web server. Typically,
Web server port 80 is used for this purpose; however, you can set up any port.
13–20
Maximizing WebSpeed compatibility with your firewall
• It is not advisable to set up a firewall between WebSpeed and a remote database. This type
of arrangement can unnecessarily expose your site to security leaks on many levels. It is
preferable that you set up your WebSpeed brokers and agents with your database behind
the same firewall.
The specific value you set up for the Registration mode depends on the connection arrangement
you want. The following procedures identify and describe the Registration mode values.
To make a client connection through a NAT firewall using the Progress Explorer Tool:
1. Double click the WebSpeed folder on the left-hand side of the main Progress Explorer
window.
13–21
WebSpeed Security
5. Select the Registration Mode value you want to set. Table 13–4 defines each value.
Select this
Registration
Mode... To Identify the hostname as...
Use Broker Host IP The IP address of the machine where the WebSpeed broker is
Address (default) located. The WebSpeed broker determines its IP address and
passes this information to the NameServer when the broker
registers.
Clients connect to the host using the broker’s IP address.
Use Broker The hostname of the machine where the WebSpeed broker is
LocalHost located. The WebSpeed broker determines its hostname and
passes this information to the NameServer when the broker
registers.
Clients connect to the host using this hostname.
Use Host Name (as The IP address defined. The WebSpeed broker passes the IP
defined in the address value defined in the property description field to the
unlabeled property NameServer when the broker registers.
description field)
Clients connect to the host using the IP address defined.
To make a client connection through a NAT firewall using the ubroker.properties file:
1. Search the file for the broker property section, or sections, that you want to change.
2. Set the value of the registrationMode property. Table 13–5 defines the values from
which you can choose to enter in the registrationMode property.
13–22
Maximizing WebSpeed compatibility with your firewall
Enter this
Registration
Mode... To Identify the hostname as...
Note: For more information, see the “GENERAL INSTRUCTIONS for configuring the
Unified Broker and NameServer for WebSpeed and AppServers” in the
ubroker.properties file.
13–23
WebSpeed Security
To facilitate communication when a firewall exists between the WebSpeed Messenger and the
NameServer, you could open all UDP ports from the machine that is running the NameServer
to the machine that is running the WebSpeed Messenger.
However, opening all 65,000 UDP ports from inside the firewall to outbound ports is a
time-consuming job. Also, opening every port is not a necessity. You can specify a client port
range minimum with minNSClientPort and a client port range maximum with
maxNSClientPort.
Using these two parameters, a firewall administrator can restrict the UDP response from the
NameServer to the client. The administrator can specify a range of ports in the properties file
and therefore reduce the number of UDP ports that are open in the firewall.
The following rules apply to the values set for these parameters:
• The value for these two parameters must be a number between 1024 and 65535 inclusive
(or 0).
• If both minimum and maximum values are set to zero, then a random port number will be
dynamically assigned. This is the default setting. The assigned port number will be in the
range of 1024 through 65535.
• If both minimum and maximum values are set to the same number, the port number will
be used exclusively for NameServer communication.
13–24
14
Using Active Server Pages with
WebSpeed
This chapter contains information for developers who want to use Microsoft’s Active Server
Page (ASP) technology in conjunction with their WebSpeed applications, as described in the
following sections:
In order to enable the use of Active Server Pages, you must set up the WSASP Messenger on a
machine that has WebSpeed installed and is running a Microsoft Web server.
You can test your configuration (and also customize error messages) from the WebSpeed
Configuration and Verification Page. A link to the WebSpeed Configuration and
Verification Page is on the WebSpeed ASP Web Page.
14–2
Enabling the WebSpeed ASP example
To access the WebSpeed ASP Web page, you must create a virtual directory called wsasp from
the Microsoft Web server console. The virtual directory must point to
install-path/webspeed/wsasp and must have execute permissions.
When you go to http://host-name/wsasp, you should see the page shown in Figure 14–1.
3. Start a WebSpeed broker named wsbroker1 whose agents are connected to the Sports2000
database server.
14–3
Using Active Server Pages with WebSpeed
You can do this in Progress Explorer by selecting AppService Name List from the
wsbroker1 Properties dialog box. Make sure that the Supports default service check box
is checked as shown in the following:
14–4
Part V
Messaging and ESB Administration
Chapter 16, Configuring and Managing the OpenEdge Adapter for Sonic ESB
15
OpenEdge Adapter for SonicMQ
Administration
This chapter provides instructions for administration and configuration tasks associated with the
OpenEdge Adapter for SonicMQ®, as well as instructions for working with the sample
applications installed with OpenEdge, as described in the following sections:
• Maximizing performance
• Internationalization considerations
OpenEdge Adapter for SonicMQ Administration
For more information on OpenEdge Adapter for SonicMQ architecture, see OpenEdge Getting
Started: Application and Integration Services.
The 4GL client application connects to BrokerConnect by specifying, when the JMS session is
created, the connection parameters of either the NameServer (if a controlling NameServer is
specified for the adapter) or the adapter itself.
• Via HTTP or HTTPS over the Internet, with use of the AppServer Internet Adapter. See
Chapter 3, “Configuring and Managing the AppServer Internet Adapter,” for more
information.
• Via AppServer protocol, with or without Secure Sockets Layer (SSL) tunneling. To
support SSL communications with client applications, BrokerConnect must be configured
as an SSL-enabled server. See the “SSL-enabled BrokerConnect operation” section on
page 15–3 for more information.
ClientConnect is for OpenEdge clients and will run as a background process in conjunction with
a Progress 4GL client. There is a single adapter process per client process with the SonicMQ
Broker acting as a service point for all JMS sessions.
15–2
Introducing the OpenEdge Adapter for SonicMQ
The ServerConnect option is for OpenEdge Application Servers (WebSpeed and AppServer).
With this configuration, there is a single adapter process per unified broker process, allowing
multiple Application Server agents to connect to this single adapter process.
For information about programming 4GL client applications in the SonicMQ environment, see
OpenEdge Development: Messaging and ESB. Also see OpenEdge Getting Started: Application
and Integration Services for a discussion of OpenEdge Adapter for SonicMQ architecture.
Security derives from the client authentication of the server's identity via a Public Key
Infrastructure (PKI) and a symmetric data encryption system. To configure an adapter instance
for SSL operation, you must:
• Obtain and install a server private key and a public key certificate. OpenEdge provides
built-in keys and certificates that are suitable for use on development or demonstration
servers; for production machines, you should obtain server certificates from an internal or
public Certificate Authority (CA).
• Specify an alias and password for access to the private key/digital certificate.
To perform these configuration tasks, you can use the Progress Explorer (in Windows only) or
manually edit the ubroker.properties file. You can use the mergeprop utility installed with
OpenEdge to manually edit the ubroker.properties file. For information on using mergeprop,
see OpenEdge Getting Started: Installation and Configuration.
15–3
OpenEdge Adapter for SonicMQ Administration
For more information on SSL support in OpenEdge, see OpenEdge Getting Started: Core
Business Services.
OpenEdge supports data privacy using SSL for the connection between the Progress 4GL client
and BrokerConnect directly over intranet connections and over the Internet through the
AppServer Internet Adapter (AIA) using HTTPS. You can also secure the direct connection
between an AIA and BrokerConnect server session using SSL. BrokerConnect allows you to set
SSL server session properties for BrokerConnect using the Progress Explorer framework. This
is similar to setting SSL server session properties for an AppServer. For more information on
setting SSL for BrokerConnect, see the “Configuring BrokerConnect” section on page 15–7.
For more information on SSL support in OpenEdge, see OpenEdge Getting Started: Core
Business Services. For more information on configuring the AIA for Internet access to
OpenEdge server sessions, see the “Configuring an AIA with the Progress Explorer” section on
page 3–12.
15–4
Configuring and administering the OpenEdge Adapter for SonicMQ
• Configuring ClientConnect
• Configuring ServerConnect
• Configuring BrokerConnect
Configuring ClientConnect
ClientConnect is a process that runs with your 4GL client session. In the following example, the
application creates a session procedure by calling jmssession.p persistently specifying the
-SMQConnect connection parameter:
The only configuration is for logging and debugging, if necessary. By default, logging is
disabled for ClientConnect sessions. Logging is turned on by setting the brkrLoggingLevel and
srvrLoggingLevel properties to a value greater than 0.
Note: Logging level represents the amount of logging information written to the log file.
Valid logging level values are 1 (Errors), 2 (Basic), 3 (Verbose), and 4 (Extended). The
default value is 2. For more information on logging, see OpenEdge Development:
Debugging and Troubleshooting.
The property and logging options for ClientConnect are stored in the Adapter.CC.cc1 section
of the install-dir/properties/JavaTools.properties file. These properties must be
modified manually, and are applicable to all OpenEdge clients using ClientConnect
functionality.
15–5
OpenEdge Adapter for SonicMQ Administration
Configuring ServerConnect
ServerConnect is a process that runs with your AppServer 4GL session or WebSpeed
SpeedScript session. The ServerConnect process that runs inside of the AppServer or
WebSpeed server is multi-threaded and allows for multiple SonicMQ connections within the
same process. Additionally, each connection to a SonicMQ Broker uses multiple threads.
These settings start a SonicMQ ServerConnect process when the AppServer or WebSpeed
server starts with specified logging options. After starting the AppServer or WebSpeed server,
ensure the SonicMQ Broker is running.
15–6
Configuring and administering the OpenEdge Adapter for SonicMQ
The only necessary configuration is for logging and tuning. Logging properties are defined
through the AppServer or WebSpeed broker. These settings can be modified using the Progress
Explorer.
Configuring BrokerConnect
BrokerConnect is a Unified Broker product and part of the Progress Explorer framework. On
the Windows platform, you can use the Progress Explorer to start, stop, get status, add, delete,
and edit properties of BrokerConnect.
1. Make sure that the AdminServer is running on the host where you want to configure the
BrokerConnect instance.
2. Open the Progress Explorer from the OpenEdge program group or in the Microsoft
Management Console (MMC).
• To define a new adapter instance, select the SonicMQ Adapter folder in the
Progress Explorer’s tree view and open the New dialog box. Enter a unique name for
the adapter instance. Choose OK. The Preferences dialog box appears. Set any
global preferences that you require (see the online help), and choose OK. The
BrokerConnect instance property editor appears.
The property editor shows a tree view of property categories on the left and the properties
for the selected category on the right.
15–7
OpenEdge Adapter for SonicMQ Administration
5. Select a property category and set the properties as required. You can accept the default
values, if they are appropriate for your application.
For information on setting the CLASSPATH, see the “Setting the CLASSPATH” section on
page 15–16.
• General — Specify a working directory and the TCP/IP port number where
BrokerConnect listens for requests. Check the Auto start box if you want the adapter
to start whenever you start the AdminServer.
• AppService Name List — Enter the names of the application services that the
BrokerConnect instance is to register with the controlling NameServer, if any.
Clients connecting to the adapter must specify one of these service names.
• Logging Setting — Specify a pathname for the broker log file, the level of logging
detail, and whether the logging for a session appends to or overwrites the previous
broker log file.
15–8
Configuring and administering the OpenEdge Adapter for SonicMQ
• Logging Setting — Specify a pathname for the server log file, the level of logging
detail, and whether the logging for a session appends to or overwrites the previous
broker log file.
• Pool Range — These settings determine the number of threads that the
BrokerConnect agent can start up and maintain. One thread is required for each
active client application.
The options in the SSL category options define the security settings for an SSL-enabled
BrokerConnect instance. Note that a BrokerConnect enabled for SSL operation does not
accept non-SSL client connections. For more information on SSL operations, see
OpenEdge Getting Started: Core Business Services. Expanding this category shows the
following property subcategories:
• General — If you check the Enable SSL Client Connections box, select the alias
for the private key/digital certificate entry (in the OpenEdge keystore) that you want
to secure connections for this adapter instance. Also enter and confirm the password
for this private key and digital certificate. You need not enter a password if you
choose to use the default_server certificate and its default password.
• Advanced Features — By default, caching is enabled for the SSL client session, and
you can enter a time-out value that specifies the length of time (in seconds) that a
disconnected session is held in the cache. During this specified interval, a connected
client can resume its session. To disable session caching, check the box.
Select the Environment Variables if you want to specify environment variables for
BrokerConnect execution. It allows you to enter name-value pairs for environment
variable settings. Any values you set here override prior values set for the same
environment variables in the operating system.
15–9
OpenEdge Adapter for SonicMQ Administration
When editing the ubroker.properties file without the Progress Explorer, note that:
• You should not directly change the values in the ubroker.properties file unless you
have a complete understanding of how the changes affect components. When possible,
always use the Progress Explorer to make all changes to this file.
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
• Always make a copy of this file, edit the copy, and verify the result before replacing the
original with your edited copy.
• For complete definitions of all the properties and detailed information on how to set them,
see the ubroker.properties.README file, as well as the comments included in the
properties file itself. Both files reside in the properties directory.
The file consists of a hierarchical structure of configuration entities, where parent entities
provide configuration information that you can override or extend in each child entity. Each
configuration entity has a name that begins the entity definition, and the definition contains
configuration settings for one or more products or product instances.
15–10
Configuring and administering the OpenEdge Adapter for SonicMQ
You can optionally specify the attributes described in Table 15–2 in the srvrStartupParam
property of BrokerConnect.
15–11
OpenEdge Adapter for SonicMQ Administration
If srvrStartupParam attributes are specified, they serve as default values for all of the clients;
however, the 4GL-JMS API allows clients to overwrite the srvrStartupParam defaults.
Names of attributes are case-sensitive. The attributes must be separated with a semicolon (;).
For example:
Adaptconfig
Use adaptconfig to validate manual changes you made to the ubroker.properties file for
BrokerConnect instances, as shown:
Syntax
adaptconfig [
[ [ -name adapter-broker ] [ -propfile path-to-properties-file ]
[ -validate ] ] | -help ]
For information on using the adaptconfig utility, see the “ADAPTCONFIG” section on
page B–3.
15–12
Maximizing performance
Adaptman
Use adaptman to start, stop, query, and kill an existing instance of a SonicMQ Broker for
BrokerConnect or to manipulate brokers on other machines by specifying the name of the
machine and the port the AdminServer is running on. For example:
Syntax
adaptman {
{ -name adapter-broker { -kill | -start | -stop | -query }
[ -host host-name -user user-name | -user user-name ]
[ -port port-number ] }| -help }
For information on using the adaptconfig utility, see the “ADAPTMAN” section on page B–4.
Maximizing performance
The primary goal of a JMS messaging system is to reliably distribute asynchronous business
events and information between applications. This is achieved by a loosely coupled
communication style of application integration. A more tightly coupled communication
mechanism, such as sockets or direct calls to the AppServer, is useful for passing large amounts
of data or for subsecond response time.
Performance comparison
The following example illustrates the kind of performance you can expect. It compares passing
data between two 4GL clients through a JMS server with passing the same data between two
4GL clients through an AppServer application.
15–13
OpenEdge Adapter for SonicMQ Administration
The first client publishes the customer table of the Sports database as a StreamMessage with
each record written as a bytes item using RAW–TRANSFER. The second client subscribes to the
JMS server, receives the message, and puts the data in a temp-table. It takes, on average, 1.5
seconds to transfer the table.
Passing the customer table from one client to another through the AppServer (by passing it from
the first client as an input temp-table to an AppServer application and then passing it to the
second client, from the AppServer application, as an output temp-table) takes, on average, 1.3
seconds.
15–14
Maximizing performance
Message reuse
The creation of a 4GL message is relatively expensive. The publisher (or sender) of a message
should reuse a Message object whenever possible. The message can be cleared for reuse by
calling clearBody and clearProperties. The message body of some message types is
automatically cleared when new data is set. (For more information, see OpenEdge
Development: Messaging and ESB.
The application that consumes messages can reuse them by calling the setReuseMessage
message consumer method. If setReuseMessage is called, the message consumer reuses the
same Message object for all the messages it receives, provided that the message was not deleted
by the application.
Load balancing
SonicMQ supports client-side load balancing. With this enabled, a connect request can be
redirected to another broker within the SonicMQ cluster, provided broker-side load balancing
has not been disabled.
Client-side load balancing involves the following methods on the session handle:
• setLoadBalancing
• getLoadBalancing
For more information on these methods, see OpenEdge Development: Messaging and ESB.
Discardable messages
When you publish a message to a topic, you can specify the DISCARDABLE delivery mode. If you
do and the destination message queue is full, the message is automatically discarded.
You can specify the DISCARDABLE delivery mode in the following methods:
• setDefaultPersistency
• publish
For more information on discardable messages, see the reference entries for these methods in
OpenEdge Development: Messaging and ESB.
For more information on maximizing performance, see SonicMQ Performance Tuning Guide.
15–15
OpenEdge Adapter for SonicMQ Administration
Internationalization considerations
The 4GL interpreter (for the client, AppServer, and WebSpeed) supports many code-page
encoding standards. The JMS client uses Unicode. The translation of text data between the
4GL’s code page and Unicode is done automatically by the 4GL-JMS implementation. (For
more information, see OpenEdge Development: Messaging and ESB.)
When a 4GL client sends text data to JMS (for example, in a TextMessage or a StreamMessage),
the 4GL client must send the text in a Unicode/UTF-8 format. If the internal code page of the
client is not in Unicode/UTF-8 format (-cpinternal UTF-8), the 4GL-JMS implementation must
convert the text to UTF-8.
When text is converted to UTF-8, each character can require up to three bytes. This causes the
text size limit of each text chunk to be 10K, since the conversion routine must prepare enough
expansion room. Since all the message types support segmentation of text data, the limit can be
worked around by using multiple segments. Whenever possible, the 4GL client’s internal code
page should be set to UTF-8 to avoid performing code-page conversions and to eliminate the
10K size limit.
15–16
16
Configuring and Managing the OpenEdge
Adapter for Sonic ESB
This chapter contains instructions for managing OpenEdge services in the Sonic ESB
environment, as described in the following sections:
• Can be managed with the use of Sonic’s powerful management and customization tools.
This chapter focuses on management of the OpenEdge Adapter for Sonic ESB and the services
that it supports. For a description of basic architecture and how the OpenEdge Adapter for Sonic
ESB operates, see OpenEdge Getting Started: Application and Integration Services. For
additional information, including guidelines for developing 4GL applications for use as Sonic
ESB services, see OpenEdge Development: Messaging and ESB.
If you choose to install OpenEdge on a different host, you must manually complete certain
configuration tasks as explained in the sections that follow.
16–2
Installation of the OpenEdge Adapter for Sonic ESB
3. To make Sonic ESB execute the environment script on startup, copy the environment
scripts from the SonicESB-Install-Directory/config (openedge_env.bat or
openedge_env.sh) to SonicESB-Install-Directory/bin/setenv.
16–3
Configuring and Managing the OpenEdge Adapter for Sonic ESB
2. The file contains a comma-separated list of values for the property resourceEditorNames.
Add ‘, WSMEditor’ to the end of the list of values.
3. Add the following three property-value pairs to the end of the file:
16–4
Installation of the OpenEdge Adapter for Sonic ESB
2. On the SMC menu bar, select Tools and then Sonic ESB Explorer.
3. In the left pane of the Sonic ESB Explorer window, expand the Services folder.
16–5
Configuring and Managing the OpenEdge Adapter for Sonic ESB
You can use either the graphical Sonic ESB Explorer or the command-line ESB Admin Tool to
import the service type definition. Either of the procedures that follow adds the OpenEdge
service type to the Sonic ESB Directory Service, making it possible to install and deploy
AppServer applications as services in the Sonic ESB environment.
To import the OpenEdge service type with the Sonic ESB Explorer:
1. Start the SonicMQ container that is to host OpenEdge services. Typically this is the default
container, SonicMQ Container1.
2. On the Management Console menu bar, select Tools and then Sonic ESB Explorer.
3. In the left pane of the Sonic ESB Explorer window, click the Services folder.
4. In the right pane, click the Import button. The Import Service Type window, a standard
file browser, appears.
5. Browse to the OpenEdgeSrvType.xml file and select it. If you completed the manual setup
procedure as instructed, the path is esbadapter\config\OpenEdgeSrvType.xml below
the top-level Sonic ESB directory.
16–6
Installation of the OpenEdge Adapter for Sonic ESB
6. With the OpenEdgeSrvType.xml file selected, click Open. You return to the Sonic ESB
Explorer window, which now shows OpenEdge Services in the Service Type Name
field, as shown:
7. Click the Apply button to complete the import process. You now see OpenEdge Services
in the list of service types.
To import the OpenEdge service type with the ESB Admin Tool:
1. Start the SonicMQ container that is to host OpenEdge services. Typically this is the default
container, SonicMQ Container1.
2. Launch the ESB Admin Tool (available in the Sonic ESB program group on the Windows
Start menu).
3. At the ESB Admin Tool command prompt, type the following command to connect to the
broker:
16–7
Configuring and Managing the OpenEdge Adapter for Sonic ESB
4. Type the following command at the ESB Admin Tool command prompt:
• WSM file — After developing your 4GL application, you use the Proxy Generator tool to
create a Web Services Mapping (WSM) file. The OpenEdge Adapter for Sonic ESB uses
this WSM file to create the corresponding SOAP calls, enabling the application to function
as a service on the ESB. See OpenEdge Development: Open Client Introduction and
Programming and the Proxy Generator online help for more information.
• WSD file — If you intend to deploy an existing WSA-based Web service in the Sonic ESB
environment, you can export its service definition from the Progress Explorer tool and use
the resulting Web Service Definition (WSD) file instead of a WSM file. By doing so, you
preserve the defined properties of the service and avoid the need to modify them again.
16–8
Using the OpenEdge Adapter for Sonic ESB
If you want to change the defaults, you can do so by using the OpenEdge custom resource editor
to modify the file, as explained in the “Editing the default service properties” section on
page 16–11. The OpenEdge resource editor also provides the option of generating a Web
Services Definition Language (WSDL) file for the service (see the “Generating a WSDL file
from the OpenEdge Resource Editor” section on page 16–20).
For any specific service instance, you can override some of the defaults stored in the file by
editing the desired values in the Sonic ESB Explorer. You can specify these service-specific
values when you create the service instance, and you can edit them after the instance has been
defined (see the “Creating an OpenEdge service instance” section on page 16–14). In cases
where no value is explicitly defined for a service, the default value is in effect.
By overriding the defaults with service-specific values, you can use the same WSM or WSD
resource as the basis for multiple services that differ only with respect to a few details. For
example, you might want to create two or more services that provide the same functionality but
use the facilities of different AppServers.
Note: Editing the service properties in the Sonic ESB Explorer window does not affect any
values stored in the WSM or WSD resource. Conversely, editing the resource does not
affect any overrides that were entered for the service instance.
Adding the WSM or WSD resource to the Sonic ESB Directory Service
To make the WSM or WSD file available, you must load the file as a resource into the Sonic
ESB Directory Service.
Note: You can load the WSM or WSD file before creating a service instance, as explained in
the procedure that follows, or you can do so as part of the process of creating the
instance (see the “Creating an OpenEdge service instance” section on page 16–14).
16–9
Configuring and Managing the OpenEdge Adapter for Sonic ESB
1. Start the SonicMQ container that hosts the Directory Service. Typically this is the
SonicMQ Domain Manager.
2. On the Sonic Management Console menu bar, select Tools and then Sonic ESB Explorer.
3. In the left pane of the Sonic ESB Explorer window, click the Resources node.
Note: If there is no Resources node, since nothing is currently stored in Resources, see
the “Creating an OpenEdge service instance” section on page 16–14.
16–10
Using the OpenEdge Adapter for Sonic ESB
5. Click Load from File. The Load Resource From File window, a standard file browser,
appears. Navigate to the WSM or WSD file, select it, and click Open. The right pane of
the Sonic ESB Explorer window now shows the name and contents of the file, as shown:
6. You can change the name of the resource, if you wish, to any name of your choice that is
not already in use (but keep the .wsm or .wsd extension). Then click Apply to store the
WSM or WSD file in the Directory Service.
Use this procedure to set default properties that will be in effect for services based on a given
WSM or WSD file. The values that you specify will apply unless they are overridden for
specific service instances.
1. Start the SonicMQ Domain Manager and open the Sonic ESB Explorer.
2. In the left pane of the Sonic ESB Explorer window, click the Resources node.
3. In the resource list at the top of the right pane, locate and select the resource that you want
to edit.
16–11
Configuring and Managing the OpenEdge Adapter for Sonic ESB
4. Click the Edit button at the bottom of the right pane. The Edit OpenEdge Service
Definition window appears, as shown:
• Web Service Namespace — The namespace uniquely identifies the service and its
elements within the Sonic ESB. It must meet the requirements of an XML namespace
value. (This default can be overridden by a service-specific value entered in the
Sonic ESB Explorer.)
• SOAP Action URI — This is an optional value; if specified, it can be any string. If
you enter a value, any client accessing the service as a Web service must place that
value in the SOAPAction HTTP header when it invokes operations on the service.
Enter or modify these values as appropriate. Then click the Runtime Properties tab.
16–12
Using the OpenEdge Adapter for Sonic ESB
6. The Runtime Properties tab shows the values of various properties that affect execution
of the service:
If the service was designed to use the session-managed session model, more properties are
listed than are shown in the illustration above. For an explanation of each property, see
Appendix A, “Reference to Progress 4GL Web Service Properties.”
The following properties can be overridden by service-specific values entered in the Sonic
ESB Explorer:
• appServiceProtocol
• appServiceHost
• appServicePort
• appServiceName
• noSessionReuse
• noHostVerify
After setting the properties as appropriate, click the Deployment Information tab if you
want to generate a WSDL file, or click OK to save your changes and return to the Sonic
ESB Explorer.
16–13
Configuring and Managing the OpenEdge Adapter for Sonic ESB
1. If necessary, start the SonicMQ Domain Manager container and then start the SonicMQ
Management Console.
2. On the Management Console menu bar, select Tools and then Sonic ESB Explorer.
3. In the left pane of the Sonic ESB Explorer, click the plus symbol (+) next to Services to
expand the display of the folder contents.
4. In the expanded list of contents of the Services folder, select OpenEdge Services.
16–14
Using the OpenEdge Adapter for Sonic ESB
5. In the right pane, click New. The custom form for specifying OpenEdge service attributes
goes into editable mode, as shown:
16–15
Configuring and Managing the OpenEdge Adapter for Sonic ESB
• The first six fields (those above the horizontal separator line) are for specifying
standard attributes common to all Sonic ESB services (see Step 6 through Step 9
below).
• The remaining fields (those below the horizontal separator line) are for specifying
attributes specific to OpenEdge services (see Step 10 through Step 16 below).
6. Of the properties common to all Sonic ESB services, only the service name (comparable
to the friendly name for a WSA-based Web service) is required. Enter a unique name in
the Service Name field.
7. Optionally, you can specify an entry endpoint, an exit endpoint, a fault endpoint, and a
rejected message endpoint for the service. Service endpoints function as logical
connections between services and are used as routing mechanisms. An endpoint can be a
SonicMQ queue or topic, a service, or a process. See the Sonic ESB Developer’s Guide for
more information about endpoints.
You can specify an existing endpoint or create a new one for use as any of the four
endpoint values. Click the ellipsis (...) button to the right of an endpoint field (for example,
Entry Endpoint) to display the Select Endpoint window, as shown:
16–16
Using the OpenEdge Adapter for Sonic ESB
• Click New; select Endpoint, Service, or Process; then select the desired option from
the submenu to display the Configure Endpoint window. Enter the appropriate values
and click OK to return to the Select Endpoint window.
9. Optionally specify a WSDL file to be associated with the OpenEdge service. This is
typically the WSDL file generated by means of the OpenEdge resource editor. For more
information on generating a WSDL file, see the “Generating a WSDL file from the
OpenEdge Resource Editor” section on page 16–20.
To specify a WSDL file, it must already be stored in the sonicfs directory. Click the
ellipsis (...) button and the Choose WSDL File Resource window appears:
16–17
Configuring and Managing the OpenEdge Adapter for Sonic ESB
10. Of the attributes specific to OpenEdge services, only the OpenEdge Service Definition
File field requires that you supply a value. You must specify a valid WSM or WSD file.
Click the ellipsis (...) button to the right of this field. The OpenEdgeMapping File
window appears:
11. If the WSM or WSD file you want has already been loaded into the Sonic ESB Directory
Service, select it from the list in the OpenEdgeMapping File window and click OK. Then
skip to Step 15.
If the WSM or WSD file has not yet been loaded, click Create New Resource to display
the Create Resource window, as shown:
12. In the Create Resource window, click Load from File to display a file browser. Navigate
to the directory containing the appropriate WSM or WSD file, select the file, and click
Open to return to the Create Resource window.
16–18
Using the OpenEdge Adapter for Sonic ESB
13. Click OK in the Create Resource window to return to the OpenEdgeMapping File
window.
15. The value in the SOAP Fault Processing field determines the action taken when the
AppServer returns a SOAP fault message. SOAP faults result from conditions such as the
server not running or a message being improperly formatted; they are not caused by
application errors.
Choose one of three values from the drop-down menu that appears when you click the
down arrow at the right of the field:
• None — No fault processing occurs. As is always the case with any response from
the AppServer, the SOAP fault message is simply sent to the service’s exit endpoint,
if any, or to the next step specified in the process itinerary.
• Message — The message that was being processed when the SOAP fault was
generated is sent to the service’s fault endpoint or to the fault endpoint specified in
the process definition. The message can be processed after the fault is corrected.
• Fault — The SOAP fault message is sent to the service’s fault endpoint or to the fault
endpoint specified in the process definition (perhaps triggering an alert to a person
who can take the appropriate corrective action). The message that was being
processed when the SOAP fault was generated is lost.
Note: If the SOAP Fault Processing field is set to Message or Fault, the service
definition or the process definition must specify a fault endpoint. Otherwise, a
SOAP fault causes an exception.
16. Enter values in the remaining fields only if you want to override the default values in the
WSM or WSD file specified in the OpenEdge Service Definition File field. If values are
entered for them, these properties override the defaults as follows:
16–19
Configuring and Managing the OpenEdge Adapter for Sonic ESB
For an explanation of these and other service properties, see Appendix A, “Reference to
Progress 4GL Web Service Properties.”
17. Click Apply at the bottom of the right pane of the Sonic ESB Explorer to create the service
instance.
You have the option of associating a WSDL file with your service. By generating the correct
WSDL file and associating it with your service, you can use the Sonic Web Services Call
Composer to generate calls to your service from a workflow.
2. In the left pane of the Sonic ESB Explorer window, click the Resources node.
3. From the Resources node, select the WSM file of your service. The Edit
OpenEdgeService Definition appears, as shown:
16–20
Using the OpenEdge Adapter for Sonic ESB
4. Click the Generate WSDL button to bring up the Generate WSDL dialog, as shown:
5. Specify a Web Service URL that points directly to the service using a sonic: URL address.
A sonic: URL address consists of three slash-delimited parts, as shown in the following
table:
Address
part Example Description
For more information, see Sonic ESB Developer’s Guide provided by Sonic Software
Corporation.
6. In the File Name field, specify a File Name for the WSDL file by either typing the absolute
or relative pathname or click Browse, navigate to the directory where you want to create
the file, enter a filename, and click Open.
16–21
Configuring and Managing the OpenEdge Adapter for Sonic ESB
2. Navigate to the directory where you want to store the WSDL file.
4. Browse to the directory where your WSDL file is saved and select the WSDL file.
Now your service definition can select the imported WSDL file.
16–22
Exposing a service as a standard Web service
• To change properties specific to a given service instance, open the Services folder in the
left pane of the Sonic ESB Explorer and select OpenEdge Services. Then select the
service instance from the list in the right pane, and set the desired values as explained in
the “Creating an OpenEdge service instance” section on page 16–14.
• To change service defaults, edit the associated WSM or WSD file as explained in the
“Editing the default service properties” section on page 16–11.
The procedure that follows presents the basic steps for configuring such an acceptor. Refer to
Sonic ESB Developer’s Guide for more detailed information.
1. Start the SonicMQ management container (by default, Container1) and then start the
SonicMQ Management Console.
2. On the Configure tab, click the plus symbol (+) next to Brokers to expand the display of
the folder contents.
3. Click the plus symbol next to the name of the broker to which you want to add the acceptor
(by default, Broker1), and then select Acceptors in the expanded list.
16–23
Configuring and Managing the OpenEdge Adapter for Sonic ESB
4. Right-click in the right pane to display a pop-up menu. From this menu, select New and
then HTTP(S) Direct. The New HTTP(S) Direct Acceptor window appears:
6. In the first URL field, enter a host name or localhost. In the second (following the colon),
enter the port number.
16–24
Exposing a service as a standard Web service
7. Click the New button to the right of the Protocols list.Then, from the menu that appears,
select HTTP Direct for SOAP. The New HTTP Direct for SOAP Protocol window
appears, as shown:
8. In the Name field, type a name of your choice. You can use the same name that you gave
to the acceptor if you wish.
16–25
Configuring and Managing the OpenEdge Adapter for Sonic ESB
9. Click New and select Content Reply Send from the menu. The New Direct Content
Reply Send URL window appears, as shown:
10. Enter the appropriate values at the New Direct Content Reply Send URL window and
click OK at each of the three windows (New Direct Content Reply Send URL, New
HTTP Direct for SOAP Protocol, New HTTP(S) Direct Acceptor) to create the
acceptor.
You can use existing containers for the deployment of OpenEdge services, or you can create
new ones. The procedures explained below include instructions for creating a new container of
each type; skip those steps if you prefer to use existing containers.
16–26
Deploying services in the Sonic ESB environment
1. In the left pane of the Sonic ESB Explorer, select the ESB Containers folder.
3. In the ESB Container Maintenance area of the right pane, type a descriptive string (for
example, OpenEdge_ESB_Container) in the Name field.
5. In the left pane, if necessary, expand the display of the ESB Containers folder contents.
Then select the container that you want to use.
6. In the right pane, click New to display a list of available services and processes. Scroll
through the list and select the service that you want to deploy.
16–27
Configuring and Managing the OpenEdge Adapter for Sonic ESB
1. At the Sonic Management Console, select the connection (normally Connection1) from
the Window menu.
3. Right-click in the window and select New and then Configuration from the pop-up
menus. The Create Configuration window appears, as shown:
16–28
Deploying services in the Sonic ESB environment
In the Name field, type a descriptive string (for example, OpenEdge_Container). Click
OK.
6. The newly created container now appears in the contents of the Containers folder in the
left pane. Select the container that you want to use, right-click, and select Add
Component from the pop-up menu. The New Container Component window appears,
as shown:
16–29
Configuring and Managing the OpenEdge Adapter for Sonic ESB
Enter values in the required fields (shown in red and with asterisks) as follows:
• Name — Type a name of your choice. You can use the same name that you assigned
the ESB container, or a different descriptive name if you prefer.
• Component — Click the ellipsis (...) to the right of the field to display the
Component Chooser browser. Click the plus symbol (+) by the ESB Containers
folder and then select the appropriate container from the list of the folder contents.
Click OK.
The boot file is an .XML file whose name and location you can specify. Navigate to the
desired directory, name the file (for example, OpenEdge_Container.xml). and click Save
to create the file.
8. Finally, you must create a script to start the container. You can use one of the following
files as the basis for this script:
Make a copy of the appropriate file in a directory of your choice and name it appropriately
(for example, OpenEdge_startcontainer.bat).
set CONTAINERFILE=container.xml
Change the value to the full path to the boot file (for example, OpenEdge_Container.xml)
that you created in Step 7, and save the file. You can now start the container at any time
by executing this script.
16–30
Security considerations for OpenEdge Adapter for Sonic ESB
The first connection, that between the OpenEdge Adapter for Sonic ESB and the client, is
secured by the facilities of the Sonic ESB and thus is outside the scope of OpenEdge
administration. See the Sonic ESB documentation for information about making this connection
secure.
The second connection is via AppServer protocol between the deployed service and the
AppServer. For this connection to be secure, the following conditions must be met:
• You must obtain and install public key certificates for the OpenEdge Adapter for Sonic
ESB host machine.
• The service must send SSL requests to the AppServer that is to process the client requests.
To configure the service to send SSL requests, you set the value of the
appServiceProtocol property to AppServerS or AppServerDCS. You set this property,
either for a specific service (see the “Editing OpenEdge service properties” section on
page 16–23) or as the default for services deployed to a given adapter instance (see the
“Editing the default service properties” section on page 16–11). Note that this property
applies to deployed services, not to the WSA itself.
• The AppServer must be SSL-enabled, meaning that it accepts SSL requests from the
OpenEdge Adapter for Sonic ESB (or other clients). You set the property sslEnable=1 by
checking the Enable SSL Client Connections box in the SSL General properties category
in the Progress Explorer, or by manually editing the ubroker.properties file. You must
also obtain and install a server private key and public key certificate and set additional SSL
server properties. See the “SSL-enabled AppServer operation” section on page 2–9 for
more information.
Note: You can use the mergeprop utility installed with OpenEdge to manually edit the
ubroker.properties file. For information on using mergeprop, see OpenEdge
Getting Started: Installation and Configuration.
For more information on SSL support in OpenEdge, including configuring and operating a
Sonic ESB service as a client of an SSL-enabled AppServer, see OpenEdge Getting Started:
Core Business Services.
16–31
Configuring and Managing the OpenEdge Adapter for Sonic ESB
You can set the following properties, either as defaults for services deployed to a given
OpenEdge Adapter for Sonic ESB instance or as properties of a specific service:
• noHostVerify — Controls whether the WSA compares the host name of the connecting
AppServer with the Common Name specified in the server digital certificate.
• noSessionReuse — Controls whether the service requests reuse of the session ID for
successive connections to the same AppServer.
For more information about these and other service properties, see Appendix A, “Reference to
Progress 4GL Web Service Properties.”
16–32
Part VI
Appendix
You can set the properties described in this appendix to affect execution of a deployed Web
service. The properties that are available for you to set depend on the session model of the Web
service (session managed or session free). You can verify the session model of a Web service
by viewing its status.
The properties described in this appendix apply to a Progress 4GL Web service whether you
deploy it as a Web service using an instance of the Web Services Adapter (WSA) in the
OpenEdge environment or you deploy it as an OpenEdge service using the OpenEdge Adapter
for Sonic ESB to install it in the Sonic Enterprise Service Bus (ESB) environment. In the Sonic
ESB environment an OpenEdge service can function either as a Web service (as in the
OpenEdge environment) or in integration with other processes on the Enterprise Service Bus.
In all cases, these properties have the same effect on service functionality.
• Overview
• Alphabetical reference
Reference to Progress 4GL Web Service Properties
Overview
You can set default values for Web service properties on a WSA instance using the Progress
Explorer, which then apply to every Web service that you deploy to that WSA instance. Once
deployed, you can review and change these values for each individual Web service.
You can set the same properties for an OpenEdge service in the Sonic ESB environment, using
the custom resource editor for OpenEdge services accessible from the Sonic ESB Explorer.
In the following sections, service refers to either a Progress 4GL Web service or an OpenEdge
service, and adapter refers to either the WSA Adapter or the OpenEdge Adapter for Sonic ESB.
Summary of properties
Table A–1 lists a summary of all the properties that you can set for a service, depending on its
session model (free, managed, or both).
Note: A connection pool is a cache that the adapter manages for each session-free service that
relies on a controlling NameServer to access the AppServer that provides the
corresponding application service. This cache maintains one or more AppServer
connections for the application service, which are made available by the NameServer
and otherwise managed through these properties. For more information on connection
pools, see Chapter 6, “Deploying and Managing Progress 4GL Web Services.”
Session
Property model Short description
A–2
Overview
Session
Property model Short description
A–3
Reference to Progress 4GL Web Service Properties
Session
Property model Short description
A–4
Alphabetical reference
• serviceFaultLevel
• serviceLoggingLevel
If you set other properties while the service is enabled, the property value changes take effect
only after you disable, then enable the service again.
Alphabetical reference
This section contains an alphabetical reference to the properties that you can set for a service,
including the applicable session model, a complete description of usage, and the default value
for each property.
appServiceHost
Session model: Managed or Free
Host name for the NameServer or AppServer that supports an application service with the name
specified by the appServiceName property.
appServiceName
Session model: Managed or Free
The name of an application service supported by the NameServer or AppServer specified by the
appServiceHost property, and that supports all operations that define the service.
A–5
Reference to Progress 4GL Web Service Properties
appServicePort
Session model: Managed or Free
The UDP (NameServer) or TCP (AppServer) port number to access the application service
supported by the host specified by the appServiceHost property.
appServiceProtocol
Session model: Managed or Free
The protocol that the WSA Adapter or OpenEdge Adapter for Sonic ESB uses to access the host
specified by the appServiceHost property. For a NameServer host, this is “AppServer”; for an
AppServer host, “AppServerDC”.
connectionLifetime
Session model: Free
The maximum lifetime (in seconds) of AppServer connections in the connection pool for this
service. A value of 0 indicates that the lifetime of these connections is unlimited, unless they are
disconnected according to the requirements of other property settings, such as
idleSessionTimeout. A positive value indicates that the WSA Adapter or OpenEdge Adapter for
Sonic ESB maintains any AppServer connections for this service for the specified number of
seconds. Thus, when the idleSessionTimeout interval expires, the adapter does any necessary
trimming of connections in the connection pool beginning with those whose
connectionLifetime interval has expired. However, the adapter maintains the connections for
all services whose connectionLifetime interval has not yet expired regardless of other
property settings.
Installation default: 0
A–6
Alphabetical reference
idleSessionTimeout
Session model: Free only
The duration (in seconds) between attempts by the WSA Adapter or OpenEdge Adapter for
Sonic ESB to shut down extra network connections to the AppServer, based on client demand.
The adapter does this by monitoring the maximum number of sessions needed since the last
time-out, then disconnecting any connections in excess of that number.
A value of 0 indicates that the adapter will never disconnect idle sessions unless the
connectionLifetime interval has expired.
Installation default: 0
initialSessions
Session model: Free only
The number of network sessions to be created (and shared by all clients) when the connection
pool for the service is initialized by the WSA Adapter or OpenEdge Adapter for Sonic ESB.
This value must be between the value of the minSessions property and the maxSessions
property, inclusive, unless maxSessions is set to 0. If maxSessions is set to 0, the
initialSessions value must only be greater than or equal to minSessions.
Installation default: 1
maxSessions
Session model: Free only
The maximum number of connected sessions allowed in the connection pool. Once the number
of sessions in the pool reaches the limit specified by maxSessions, the WSA Adapter or
OpenEdge Adapter for Sonic ESB creates no additional sessions for this service, and handles
all requests for this service according to the requestWaitTimeout property setting.
Installation default: 0
A–7
Reference to Progress 4GL Web Service Properties
minIdleConnections
Session model: Free only
The minimum number of idle, or inactive, AppServer connections to maintain. Given sufficient
AppServer resources, this setting allows the WSA Adapter or OpenEdge Adapter for Sonic ESB
to always have a free connection available when a new request arrives, so the request does not
have to wait for the adapter to locate and establish a new connection to service it. When the
value of this property is greater than zero, the adapter uses its free time to pre-allocate network
connections for the service connection pool.
Installation default: 0
minSessions
Session model: Free only
The minimum number of connected sessions allowed in the connection pool. The WSA Adapter
or OpenEdge Adapter for Sonic ESB attempts to keep at least this many sessions connected to
the application service (AppServer).
Installation default: 1
noHostVerify
Session model: Both
If set to 1, turns off host verification for an SSL Web service connection (specified by the
appServiceProtocol property). If cleared, the WSA compares the host name of the connecting
AppServer with the Common Name specified in the server digital certificate, and raises a Web
service error if they do not match. With this parameter specified, the Web service never raises
the error.
Installation default: 0
A–8
Alphabetical reference
noSessionReuse
Session model: Both
If set to 1, the Web service connection does not reuse the SSL session ID when reconnecting to
the same AppServer for an SSL Web service connection (specified by the appServiceProtocol
property).
Installation default: 0
nsClientMaxPort
Session model: Managed or Free
The maximum value for the UDP port number that the WSA Adapter or OpenEdge Adapter for
Sonic ESB specifies when communicating with the NameServer. This value must be greater
than or equal to the value of the nsClientMinPort property.
This property applies only to services that use a NameServer to access application services (an
AppServer).
Installation default: 0
nsClientMinPort
Session model: Managed or Free
The minimum value for the WSA Adapter or OpenEdge Adapter for Sonic ESB to specify for
the UDP port number when communicating with the NameServer. The value must be less than
or equal to the value of the nsClientMaxPort property.
If this value is 0, the adapter chooses the NameServer client port number randomly.
This property applies only to services that use a NameServer to access application services (an
AppServer).
Installation default: 0
A–9
Reference to Progress 4GL Web Service Properties
nsClientPicklistExpiration
Session model: Free only
The maximum duration (in seconds) that the WSA Adapter or OpenEdge Adapter for Sonic
ESB retains a list of AppServer options (pick list) for an idle application service.
This property applies only to services that use a NameServer to access application services (an
AppServer).
Installation default: 0
nsClientPicklistSize
Session model: Free only
The number of available AppServer options (the broker pick list) that the WSA Adapter or
OpenEdge Adapter for Sonic ESB requests from the NameServer each time it looks up a given
application service name.
This property applies only to services that use a NameServer to access application services (an
AppServer).
Installation default: 1
nsClientPortRetry
Session model: Managed or Free
The maximum number of requests that the WSA Adapter or OpenEdge Adapter for Sonic ESB
makes for a valid local UDP port number when attempting to communicate with the
NameServer on behalf of the service.
This property applies only to services that use a NameServer to access application services (an
AppServer).
Installation default: 3
A–10
Alphabetical reference
nsClientPortRetryInterval
Session model: Managed or Free
The interval (in milliseconds) that the WSA Adapter or OpenEdge Adapter for Sonic ESB waits
between requests to get a valid UDP port number when attempting to communicate with the
NameServer on behalf of the service.
This property applies only to services that use a NameServer to access application services (an
AppServer).
requestWaitTimeout
Session model: Free
Determines how the WSA Adapter or OpenEdge Adapter for Sonic ESB handles requests when
the connection pool becomes full. (The connection pool is full when the number of active
sessions equals the value of maxSessions, and all sessions are currently running requests.)
The adapter handles such requests according to the value of requestWaitTimeout as shown in
Table A–2.
If the value is... The WSA Adapter or OpenEdge Adapter for Sonic ESB...
0 Rejects the request and returns an error message to the client indicating
that there are too many concurrent requests.
>0 Queues the request for the maximum number of seconds specified by
the value until an AppServer session becomes available. If no session
becomes available in that time, the adapter returns an error to the client.
Installation default: 0
A–11
Reference to Progress 4GL Web Service Properties
serviceFaultLevel
Session model: Managed or Free
The amount (level) of information returned to the client for a SOAP Fault as determined by an
integer value. A level of 2 returns basic information in the <FaultCode> and <FaultString>
elements for each SOAP Fault message, which is suitable for normal production environments.
A level of 3 returns more detailed information that is suitable for development environments.
Other values provide varying levels of diagnostic information, and are reserved for use by
Progress Technical Support and Engineering.
Installation default: 2
serviceLoggingLevel
Session model: Managed or Free
The amount and type of information written for each service log entry by the WSA Adapter or
OpenEdge Adapter for Sonic ESB to the adapter log file, cumulatively determined by the
integer values from 1 to 4, as shown in Table A–3.
Installation default: 2
A–12
Alphabetical reference
staleO4GLObjectTimeout
Session model: Managed or Free
The maximum duration (in seconds) that a service object (AppObject, SubAppObject, or
ProcObject) can be idle before it is released.
As part of managing certain service objects with OpenEdge, clients explicitly create them using
factory methods before invoking other methods on them. When the client no longer requires the
object, it has the responsibility to release the object from the service run-time context. However,
if this time-out expires before the client releases the object, the WSA Adapter or OpenEdge
Adapter for Sonic ESB assumes that the client application no longer requires access to the
object, and deletes it from the service run-time context automatically. In effect, the adapter uses
this time-out to provide garbage collection on service objects that client applications stop
referencing and fail to release in the specified period of time. Any subsequent attempt by a client
to access this object returns an error from the adapter.
A value of 0 for this property specifies that the adapter perform no garbage collection on idle
objects, leaving the responsibility for releasing them entirely to client applications.
When all objects that reference the connection pool have been released, the adapter also releases
the now unreferenced connection pool as well.
Installation default: 0
waitIfBusy
Session model: Managed only
An integer value that determines how to handle client requests to a service that is busy
processing a prior request. If the value is 1, the WSA Adapter or OpenEdge Adapter for Sonic
ESB queues multiple requests for this service and executes them one at a time until the queue
is empty. If the value is 0 and the adapter is executing a prior request for the service, each
subsequent request for the same service fails until the adapter completes the request it is
currently executing.
Installation default: 0
A–13
Reference to Progress 4GL Web Service Properties
A–14
B
Command and Utility Reference
This appendix describes the following commands and utilities that you use to configure,
manage, start, and stop AdminServer, Application Internet Adapter (AIA), AppServer,
OpenEdge Adapter for SonicMQ BrokerConnect, Web Services Adapter (WSA), and
WebSpeed:
• ADAPTCONFIG
• ADAPTMAN
• AIACONFIG
• ASBMAN
• ASCONFIG
• NSCONFIG
• NSMAN
• PROADSV
• WSACONFIG
• WSAMAN deploy
• WSAMAN disable
Command and Utility Reference
• WSAMAN enable
• WSAMAN export
• WSAMAN getdefaults
• WSAMAN import
• WSAMAN list
• WSAMAN resetdefaults
• WSAMAN resetprops
• WSAMAN setdefault
• WSAMAN undeploy
• WSAMAN update
• WSCONFIG
• WTBMAN
B–2
ADAPTCONFIG
ADAPTCONFIG
Validates manual changes made to the ubroker.properties file for an OpenEdge Adapter for
SonicMQ BrokerConnect instance.
Syntax
Operating
system Syntax
adaptconfig[
[ [ -name adapter-broker ]
UNIX [ -propfile path-to-properties-file ]
Windows [ -validate ]] | -help ]
-name adapter-broker
-propfile path-to-properties-file
-validate
-help
Note If No options is used, the results lists all defined SonicMQ Brokers for BrokerConnect.
B–3
Command and Utility Reference
ADAPTMAN
Starts, stops, queries, and kills an existing OpenEdge Adapter for SonicMQ BrokerConnect
broker or manipulates brokers on other machines by specifying name of the machine and the
port the AdminServer is running on.
Syntax
Operating
system Syntax
adaptman {
{ -name adapter-broker
{ -kill | -start | -stop | -query }
[ -host host-name -user user-name | -user user-name ]
UNIX [ -port port-number ]
Windows } | -help }
-name adapter-broker
-kill
Causes emergency shutdown of the SonicMQ Broker for BrokerConnect. -k is also valid.
-start
-stop
-query
-host host-name
-user user-name
B–4
ADAPTMAN
-port port-number
-help
Note Enter the -i or the -name parameter followed by the name of the SonicMQ Broker for
BrokerConnect and then the command to start, stop, query, or kill a broker.
Examples Table B–1 shows several examples that use the adaptman command to start an instance called
SonicMQ1.
Task Command
Get status of an instance on the machine adaptman -host xxxxxx -port 12935 -i
whose AdminServer is on port 12935. sonicMQ1 -q
B–5
Command and Utility Reference
AIACONFIG
Validates changes made to the ubroker.properties file for an AIA instance.
Syntax
Operating
system Syntax
aiaconfig [
[ [ -name AIA-instance-name ]
[ -propfile path-to-properties-file ]
UNIX [ -validate ]
Windows ] | -help ]
-name AIA-instance-name
-propfile path-to-properties-file
-validate
-help
Note If you upgrade to a new version of OpenEdge, you might want to retain changes made to the
previous version’s ubroker.properties file. If that is the case, place the old properties file in
the installed properties directory to replace the default. When starting the AdminServer for
the first time, a properties file conversion utility automatically runs.
B–6
ASBMAN
ASBMAN
Starts, stops, adds AppServer agents, trims AppServer agents, and queries the status for an
AppServer instance and its AppServer agent.
Syntax
Operating
system Syntax
asbman {
{ -name AppServer-name
{ -kill | -start | -stop | -query |
-addservers number-to-start |
-trimservers number-to-trim }
[ -host host-name -user user-name | -user user-name ]
UNIX [ -port port-number ]
Windows } | -help }
-name AppServer-name
-kill
Stops and removes the AppServer from memory, no matter what it is doing.
-start
Starts an AppServer.
-stop
Note: The AppServer stops only after completing any active client requests.
-query
-addservers number-to-start
B–7
Command and Utility Reference
-trimservers number-to-trim
-host host-name
Specifies the name of the machine where the AdminServer is running. If a host name is
not specified, it defaults to the local host name.
-user user-name
Specifies a user name and prompts for a password. A user name and password are required
only when you use the -host parameter and specify a remote host name. If you specify a
remote host name with the -host parameter but do not specify a user name with the -user
parameter, you receive a prompt for a user name and password.
• A user name as a simple text string, such as “mary”, implies a local user whose user
account is defined on the local Windows server machine, which is the same machine
that runs the AdminServer.
• A user name as an explicit local user name, in which the user account is defined on
the same machine that runs the AdminServer, except the user name explicitly
references the local machine domain, for example “.\mary”.
• A user name as a user account on a specific Windows domain. The general format is
Domain\User, in which the User is a valid user account defined within the domain
and the Domain is any valid Windows Server, including the one where the
AdminServer is running.
-port port-number
Specifies the port number of the machine on which the AdminServer is running. If a port
number is not specified, it defaults to 20931.
-help
B–8
ASBMAN
Examples Table B–2 shows several examples that use the ASBMAN command. Assume the AppServer
instance is AS1 and the NameServer is NS1.
Task Command
Start a remote AppServer instance after nsman -name NS1 -host nsserve -port
20950 -user daniel -start
starting a remote controlling NameServer.1
asbman -name AS1 -host asserve -port
20950 -user daniel -start
Stop a local AppServer instance (AS1) and its asbman -name AS1 -stop
nsman -name NS1 -stop
controlling NameServer instance (NS1).
1. The AppServer and controlling NameServer are on different hosts and happen to use the same TCP/IP port number
to access the AdminServer on each host. If you specify a host, the Progress Explorer always prompts for a user name
(if necessary) and password. In this example, the commands specify the user name and prompt only for the
password.
B–9
Command and Utility Reference
ASCONFIG
Displays the property settings associated with an AppServer configuration and checks that the
syntax and values in the ubroker.properties file are valid. You must run the ASCONFIG utility
locally on the machine on which the AppServer is running. The utility does not run across the
network. (Progress only)
Syntax
Operating
system Syntax
asconfig [
[ [ -name AppServer-name ]
[ -propfile path-to-properties-file ]
UNIX [ -validate ]
Windows ] | -help ]
-name AppServer-name
Specifies which existing AppServer configuration to examine. The name must match the
name of an existing AppServer configuration in the specified properties file. If you do not
specify an AppServer, the ASCONFIG utility analyzes all AppServer configurations defined
in the properties file specified by the -propfile parameter.
-propfile path-to-properties-file
• %DLC%\properties\ubroker.properties in Windows.
• $DLC/properties/ubroker.properties on UNIX.
-validate
Checks the syntax and values of property settings defined in the specified properties file.
-help
B–10
ASCONFIG
Note Never needed if you always use the Progress Explorer GUI.
Example The following command validates the syntax and views the configurations of all AppServer
instances defined within the test.properties file located in the current working directory:
B–11
Command and Utility Reference
NSCONFIG
Displays the property settings associated with a NameServer configuration and checks that the
syntax and values are valid. The NSCONFIG utility runs locally on the machine where the
AdminService is running. The utility does not run across the network.
Syntax
Operating
system Syntax
nsconfig[
[ [ -name name-server ]
[ -propfile path-to-properties-file ]
[ -validate ]
Windows ] | -help ]
-name name-server
Specifies which existing NameServer configuration to examine. The name must match the
name of an existing NameServer configuration in the specified properties file. If you do
not specify a NameServer, the NSCONFIG utility analyzes all NameServer configurations
defined in the properties file specified by the -propfile parameter.
-propfile path-to-properties-file
• install-path\properties\ubroker.properties in Windows.
• install-path/properties/ubroker.properties on UNIX.
-validate
Checks the syntax and values of property settings defined in the specified properties file.
-help
B–12
NSCONFIG
Notes • Never needed if you always use the Progress Explorer GUI.
• A single NameServer can simultaneously support all of the AppServer, WebSpeed, and
DataServer products using Progress Explorer.
Examples Table B–3 shows several examples that use the NSCONFIG command. Assume the NameServer
is NS1.
Task Command
For information on managing a NameServer using the NSCONFIG utility, see OpenEdge Getting
Started: Installation and Configuration.
B–13
Command and Utility Reference
NSMAN
Controls the operation of a configured NameServer. The utility allows you to start a
NameServer, query its status, and shut down a NameServer.
Syntax
Operating
system Syntax
nsman {
{ -name nameserver
{ -kill | -start | -stop | -query }
[ -host host-name -user user-name | -user user-name ]
[ -port port-number ]
Windows } | -help }
-name name-server
-kill
Stops and removes the NameServer from memory, no matter what it is doing.
-start
-stop
-query
-host host-name
Specifies the name of the machine where the AdminServer is running. If a host name is
not specified, it defaults to the local host name.
B–14
NSMAN
-user user-name
Specifies a user name and prompts for a password. A user name and password are required
only when you use the -host parameter and specify a remote host name. If you specify a
remote host name with the -host parameter but do not specify a user name with the -user
parameter, you receive a prompt for a user name and password.
-port port-number
Specifies the port number of the machine where the AdminServer is running. If a port
number is not specified, it defaults to 20931.
-help
Examples Table B–4 shows several examples that use the NSMAN command. Assume the NameServer is
NS1; the user name is tom; and the AdminServer is on the remote host finance on the port 9999.
Task Command
B–15
Command and Utility Reference
Notes • A single NameServer can simultaneously support all of the AppServer, WebSpeed, and
DataServer products.
• When you specify a user name with the -user parameter, Windows supports three
different formats:
– A user name as a simple text string, such as mary, implies a local user whose user
account is defined on the local server, which is the same machine that runs the
AdminServer.
– A user name as an explicit local user name, in which the user account is defined on
the same machine that runs the AdminServer, except the user name explicitly
references the local machine domain, for example, .\mary.
For information on managing a NameServer using the NSMAN utility, see OpenEdge Getting
Started: Installation and Configuration.
B–16
PROADSV
PROADSV
Starts, stops, and queries the status of the AdminServer on UNIX. In Windows, you start the
AdminService as a Windows service using the Services applet in the Control Panel.
Syntax
Operating
system Syntax
-start
-stop
-query
-port port-number
Specifies the listening port number. If a port number is not specified, the port defaults to
20931.
-adminport port-number
Specifies the port number used by the AdminServer for database broker communication.
If a port number is not specified, the adminport defaults to port 7832.
-help
B–17
Command and Utility Reference
Examples Table B–5 shows several examples that use the NSCONFIG command. Assume the NameServer
is NS1.
Task Command
For more information on the PROADSV utility, see OpenEdge Getting Started: Installation and
Configuration or OpenEdge Data Management: Database Administration.
B–18
WSACONFIG
WSACONFIG
Validates Web Services Adapter configurations. The WSACONFIG utility displays the property
settings associated with WSA configuration and checks that the syntax and values are valid.
You must run the WSACONFIG utility locally on the machine where the WSA is running. The
utility does not run across the network.
Syntax
Operating
system Syntax
wsaconfig [
[ [ -name WSA-instance-name ]
[ -propfile path-to-properties-file ]
UNIX [ -validate ]
Windows ] | -help ]
-name WSA-instance-name
Specifies which existing WSA configuration to examine. The name must match the name
of an existing WSA configuration in the specified properties file. If you do not specify a
WSA, the WSACONFIG utility analyzes all WSA configurations defined in the properties file
specified by the -propfile parameter.
-propfile path-to-properties-file
• OpenEdge-Install-Directory\properties\ubroker.properties in Windows.
• OpenEdge-Install-Directory/properties/ubroker.properties on UNIX.
-validate
Checks the syntax and values of property settings defined in the specified properties file.
-help
B–19
Command and Utility Reference
Example The following command validates the syntax and views the configurations of all WSA instances
defined within the test.properties file located in the current working directory:
B–20
WSAMAN deploy
WSAMAN deploy
Deploys a Web service to a WSA instance.
This transfers the Web service’s WSM file to the WSA instance, which generates the Web
Services Application Descriptor (WSAD), WSDL, and friendlyname.props files. Most of the
properties in the friendlyname.props file are initialized from the values in the default.props
file of the WSA instance you are deploying to.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
-wsm wsm-location-on-wsaman-machine
[ -appname new-appfriendlyname ]
[ -namespace new-targetnamespace ]
UNIX [ -encoding new-encodingstyle ]
Windows -deploy
-name wsainstance-name
The name of the WSA instance where you want to deploy the Web service.
-wsm wsm-location-on-wsaman-machine
-appname new-appfriendlyname
Note: This value replaces the value supplied by the developer to ProxyGen.
-namespace new-targetnamespace
Note: This value replaces the value supplied by the developer to ProxyGen.
B–21
Command and Utility Reference
-encoding new-encodingstyle
Use a value from Table B–6, which lists the WSDL style/use combinations supported.
Table B–6: Setting the SOAP format for deployment using WSAMAN
Use this value ... For this WSDL style/use combination ...
1 RPC/Encoded
2 RPC/Literal
3 Document/Literal
Notes • The WSM file must be locally accessible from the machine running the Progress Explorer
or the WSAMAN utility; that is, located on a local drive or a mapped network drive.
B–22
WSAMAN disable
WSAMAN disable
Makes a deployed Web service temporarily unavailable to incoming client requests.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname | -namespace
UNIX app-targetnamespace }
Windows -disable
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
Note When a Web service is disabled, the WSA begins a shutdown process that involves stopping the
Web service’s existing client requests and terminating any AppServer connections in the Web
service’s connection pool.
B–23
Command and Utility Reference
WSAMAN enable
Makes a deployed Web service available to incoming client requests.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX | -namespace app-targetnamespace }
Windows -enable
-name wsainstance-name
-appname app-friendlyname
-namespace app-targetnamespace
• While a Web service is enabled, you can set only the serviceFaultLevel and
serviceLoggingLevel properties. To set the other properties, the Web service must be
disabled. Any changes to the other properties take effect when the Web service is enabled.
• When a Web service is enabled, the WSA begins a startup process that involves
establishing the Web service’s connection pool. Establishing the Web service’s
connection pool involves pre-establishing any AppServer connections that will be cached
to handle incoming client requests more efficiently.
B–24
WSAMAN export
WSAMAN export
Creates a WSD file on the local system from an existing Web service on an existing WSA
instance. This facilitates updating a production Web service, cloning a Web service, or moving
a Web service from WSA instance to WSA instance.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
| -namespace app-targetnamespace }
UNIX [ -wsd wsd-location-on-wsaman-machine ]
Windows -export
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
-wsd wsd-location-on-wsaman-machine
If this parameter is not supplied, -export creates the file friendlyname.wsd in the current
working directory.
Note When a Web service is exported and imported, the imported Web service is disabled and a
friendlyname.props file identical to the original is created for it.
B–25
Command and Utility Reference
WSAMAN getdefaults
Displays the default Web service properties associated with a WSA instance. These properties
reside in the WSA instance’s default.props file and are used to initialize the
friendlyname.props file of each Web service deployed to this WSA instance.
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -getdefaults
-name wsainstance-name
For more information on these properties, see Appendix A, “Reference to Progress 4GL Web
Service Properties.”
B–26
WSAMAN getprops (Service)
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX |-namespace app-targetnamespace }
Windows -getprops
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
For more information on these properties, see Appendix A, “Reference to Progress 4GL Web
Service Properties.”
Note If the Web service is disabled, all relevant properties are displayed. If the Web service is
enabled, only the serviceFaultLevel and serviceLoggingLevel properties are displayed.
B–27
Command and Utility Reference
• loggingLevel
• enableWsdl
• enableWsdlListings
• webAppEnabled
• debugClients
• logMsgThreshold
These properties reside in the ubroker.properties file. For more information on them, see the
comments in ubroker.properties.
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -getprops
-name wsainstance-name
Note The values of these properties can be temporarily overridden through WSAMAN setprops
(WSA). Such changes are not written to ubroker.properties. If there are such changes in
effect, the values displayed by the WSAMAN getprops (WSA) might not match the values in
ubroker.properties.
B–28
WSAMAN getstats (Service)
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX | -namespace app-targetnamespace }
Windows -getstats
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
For more information on these statistics, see the Progress Explorer online help for Web services.
B–29
Command and Utility Reference
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -getstats
-name wsainstance-name
For more information on these statistics, see the Progress Explorer online help.
B–30
WSAMAN import
WSAMAN import
Deploys a previously exported Web service. This facilitates updating a production Web service,
cloning a Web service, or moving a Web service from WSA instance to WSA instance.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
-wsd wsd-location-on-wsaman-machine
[ -appname new-appfriendlyname ]
[ -namespace new-targetnamespace ]
UNIX [ -encoding new-encoding-style ]
Windows -import
-name wsainstance-name
The name of the WSA instance where you want to deploy the Web service.
-wsd wsd-location-on-wsaman-machine
-appname new-appfriendlyname
Note: This value replaces the value supplied by the developer to ProxyGen.
-namespace new-targetnamespace
Note: This value replaces the value supplied by the developer to ProxyGen.
B–31
Command and Utility Reference
-encoding new-encoding-style
Use a value from Table B–7, which lists the WSDL style/use combinations supported.
Table B–7: Setting the SOAP format for import using WSAMAN
Use this value ... For this WSDL style/use combination ...
1 RPC/Encoded
2 RPC/Literal
3 Document/Literal
Notes • The WSD file must be locally accessible from the machine running the Progress Explorer
and the WSAMAN utility, that is, located on a local drive or a mapped network drive.
B–32
WSAMAN list
WSAMAN list
Displays the list of Web service applications that have been deployed to the WSA instance.
• Friendly name
• Namespace URI
• Status
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -list
-name wsainstance-name
B–33
Command and Utility Reference
• Target NameSpace.
• AppServer URL.
• Session model.
• WSDL style/use.
Note: All properties are displayed, regardless of whether the Web service is enabled or
disabled.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX |-namespace app-targetnamespace }
Windows -query
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
B–34
WSAMAN query (WSA)
The properties are stored in the WSA instance’s ubroker.properties file. For more
information on them, see the comments in ubroker.properties.
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -query
-name wsainstance-name
B–35
Command and Utility Reference
WSAMAN resetdefaults
Resets, to its original values, a WSA instance’s default.props file (which contains the default
Web service properties associated with the WSA instance).
The default.props file is used to initialize the friendlyname.props file of each Web service
deployed to the WSA instance.
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -resetdefaults
-name wsainstance-name
For more information on these properties, see Appendix A, “Reference to Progress 4GL Web
Service Properties.”
B–36
WSAMAN resetprops
WSAMAN resetprops
Reinitializes a Web service’s friendlyname.props file to the current value of the WSA
instance’s default.props file (which contains the default Web service properties associated
with the WSA instance).
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX |-namespace app-targetnamespace }
Windows -resetprops
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
Note If the Web service is enabled, the resetprops function resets only serviceFaultLevel and
serviceLoggingLevel, which are the only properties of an enabled Web service that can be set.
For more information on these properties, see Appendix A, “Reference to Progress 4GL Web
Service Properties.”
B–37
Command and Utility Reference
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX | -namespace app-targetnamespace }
Windows -resetstats
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
For more information on these statistics, see the Progress Explorer online help for Web services.
B–38
WSAMAN resetstats (WSA)
Syntax
Operating
system Syntax
wsaman
UNIX -name wsainstance-name
Windows -resetstats
-name wsainstance-name
For more information on these statistics, see the Progress Explorer online help for Web services.
B–39
Command and Utility Reference
WSAMAN setdefault
Sets one of the default Web service properties associated with a WSA instance.
These properties reside in the default.props file associated with this WSA instance and are
used to initialize the friendlyname.props file of each Web service deployed to it.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
-prop property-name
UNIX -value property-value
Windows -setdefaults
-name wsainstance-name
-prop property-name
-value property-value
For more information on these properties, see Appendix A, “Reference to Progress 4GL Web
Service Properties.”
B–40
WSAMAN setprops (Service)
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname | -namespace
app-targetnamespace }
-prop property-name
UNIX -value property-value
Windows -setprops
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
-prop property-name
-value property-value
Note To set any Web service property except for serviceFaultLevel and serviceLoggingLevel,
the Web service must be disabled. Otherwise, the request fails.
For more information on these properties, see Appendix A, “Reference to Progress 4GL Web
Service Properties.”
B–41
Command and Utility Reference
• loggingLevel
• enableWsdl
• enableWsdlListings
• webAppEnabled
• debugClients
• logMsgThreshold
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
-prop property-name
UNIX -value property-value
Windows -setprops
-name wsainstance-name
-prop property-name
-value property-value
B–42
WSAMAN setprops (WSA)
• Once a setprops change takes effect, it lasts until the JSE is restarted.
These properties reside in the ubroker.properties file. For more information on them, see the
comments in ubroker.properties.
B–43
Command and Utility Reference
WSAMAN undeploy
Undeploys a Web service from a WSA instance. This removes the Web service’s WSDL,
WSAD, and friendlyname.props files.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
{ -appname app-friendlyname
UNIX |-namespace app-targetnamespace }
Windows -undeploy
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-appname app-friendlyname
-namespace app-targetnamespace
Note When you undeploy a Web service, whether you use the WSAMAN utility or the Progress Explorer,
no WSD file is created and no information on the undeployed Web service is saved. To create
a WSD file, export the Web service before undeploying it.
B–44
WSAMAN update
WSAMAN update
Lets you change a Web service’s deployment information (stored in the WSM file) without
undeploying and deploying. Updating does not affect the Web service’s friendlyname.props
file. It is useful during development, but not during production.
Syntax
Operating
system Syntax
wsaman
-name wsainstance-name
-wsm wsm-location-on-wsaman-machine
{ -appname app-friendlyname
| -namespace app-targetnamespace }
UNIX [ -encoding encodingstyle ]
Windows -update
-name wsainstance-name
The name of the WSA instance the Web service is deployed to.
-wsm wsm-location-on-wsaman-machine
-appname app-friendlyname
-namespace app-targetnamespace
B–45
Command and Utility Reference
-encoding encodingstyle
Use a value from Table B–8, which lists the WSDL style/use combinations supported.
Table B–8: Setting the SOAP format for update using WSAMAN
Use this value ... For this WSDL style/use combination ...
1 RPC/Encoded
2 RPC/Literal
3 Document/Literal
Notes • If the friendly name is different from the AppObject name, you must use the -appname
option and not the -namespace option.
• Progress Software Corporation recommends that you never use the WSAMAN update
function on a production system.
B–46
WSCONFIG
WSCONFIG
Displays the property settings associated with a WebSpeed Transaction Server or Messenger
configuration and checks that the syntax and values are valid. The WSCONFIG utility runs locally,
on the machine where the WebSpeed components that you want to check are running. Because
the utility does not run across the network and no AdminServer is installed during a
Messenger-only install, you cannot use the WSCONFIG utility to check a Messenger-only install.
(WebSpeed only).
Syntax
Operating
system Syntax
wsconfig[
[ [ -name component-name ]
[ -propfile path-to-properties-file ]
[ -messenger ]
UNIX [ -validate ]
Windows ] | -help ]
-name component-name
-propfile path-to-properties-file
B–47
Command and Utility Reference
-messenger
Displays one or all of the Messengers for you to view. If -name refers to a Messenger and
the -messenger parameter is used, then information appears for that one Messenger. If
-name does not refer to a Messenger and the -messenger parameter is used, then
information appears for all the Messengers.
The Messenger names in Windows are CGIIP, WSISA, WSNSA, and WSASP. The Messenger
names on UNIX are CGIIP and WSNSA.
-validate
Checks the syntax and values of property settings defined in the specified properties file.
-help
Examples Table B–9 shows several examples that use the WSCONFIG command. Assume the Transaction
Server name is wsbroker1.
Task Command
B–48
WTBMAN
WTBMAN
Controls the operation of a configured WebSpeed Transaction Server. The utility allows you to
start a Transaction Server, query its status, start and stop additional WebSpeed Agents, trim by
a certain number of agents, and shut down the Transaction Server. (WebSpeed only).
Syntax
Operating
system Syntax
wtbman {
{ -name transaction-server-name
{ -kill | -start | -stop | -query
| -addagents number-to-start
| -trimagents number-to-trim }
[ -host host-name -user user-name | -user user-name ]
UNIX [ -port port-number ]
Windows } | -help }
-name transaction-server-name
-kill
Stops and removes the Transaction Server from memory, no matter what it is doing.
-start
-stop
-query
-addagents number-to-start
B–49
Command and Utility Reference
-trimagents number-to-trim
-host host-name
Specifies the name of the machine where the AdminServer is running. If a host name is
not specified, it defaults to the local host name.
-user user-name
Specifies a user name and prompts for a password when logging in to a remote machine.
A user name and password are required only when you use the -host parameter and
specify a remote host name. If you specify a remote host name with the -host parameter
but do not specify a user name with the -user parameter, you receive a prompt for a user
name and password.
-port port-number
Specifies the port number of the machine on which the AdminServer controlling the
WebSpeed Transaction Server is running. If a port number is not specified, it defaults to
20931.
-help
Examples Table B–10 shows several examples that use the wtbman command. Assume that the Transaction
Server name is wsbroker1, the user name is tom, and the AdminServer is on the remote host
finance at port 9999.
Task Command
B–50
WTBMAN
Task Command
Add agents (for example, 2) to a remote wtbman -name wsbroker1 -host finance
-port 9999 -user tom -addagents 2
Transaction Server.1
Trim agents (for example, 3) from a local wtbman -name wsbroker1 -trimagents 3
Transaction Server.
Trim agents (for example, 3) from a remote wtbman -name wsbroker1 -host finance
-port 9999 -user tom -trimagents 3
Transaction Server.1
Notes When you specify a user name with the -user parameter, Windows supports three different
formats:
• A user name as a simple text string, such as mary, implies a local user whose user account
is defined on the local server, which is the same machine that runs the AdminServer.
• A user name as an explicit local user name, in which the user account is defined on the
same machine that runs the AdminServer, except the user name explicitly references the
local machine domain, for example, .\mary.
• A user name as a user account on a specific domain. The general format is Domain\User,
in which the User is a valid user account defined within the domain, and the Domain is any
valid server, including the one where the AdminServer is running.
B–51
Command and Utility Reference
B–52
Index
Index–2
Index
Index–3
Index
Index–4
Index
Default service E
AppServer setting 2–22
WebSpeed setting 9–8 enable function
deploy function WSAMAN utility B–24
WSAMAN utility B–21 Enabling
Progress 4GL Web services 6–12
Deploying Web services 6–4
Endpoints
Deployment directory
SonicMQ 16–16
changing for Web services 6–10
Environment variables
Deployment files
BrokerConnect setting 15–9
Progress 4GL Web service 6–9
for JSE 3–8
Web service management 6–14
NameServer setting 2–25, 9–11
Deployment information PROMSGS 12–11
for Progress 4GL Web services 6–7 PROPATH
for Sonic ESB services 16–8, 16–12 Windows 9–19
where to set 2–29
Development mode WRKDIR
WebSpeed security 13–2 UNIX 10–19
Windows 9–20
Digital certificates
and Web servers 3–10 ESB Admin Tool
installing for WSA 4–4 importing service definition 16–7
Index–5
Index
Index–6
Index
J Load balancing
NameServer
Java UNIX 10–21
class files location Windows 9–23
UNIX 10–14 overview 2–7
Windows 9–17
LOCKED status 2–36
Java Message Service (JMS)
Log files 2–30
MapMessage 15–14
configuring
performance considerations 15–13 to
UNIX 10–20
15–15
Windows 9–20
reusing messages 15–15
maintaining
StreamMessage 15–14
UNIX 10–24
TextMessage 15–14
Windows 9–27
Java servlet engine (JSE)
Logging properties
configurations with WSA 5–3
AIA broker setting 3–14
configuring to recognize the WSA 4–3
AppServer agent process setting 2–24
Installing and configuring 3–9
AppServer broker setting 2–22
large Web service messages 4–3
WebSpeed agent process setting 9–9
role in WSA security 7–2
WebSpeed broker setting 9–8
security files 7–3
using with uri 3–17
virtual paths 3–7, 3–9 M
Java servlet engine (JSE)s
and Web servers 3–6 Maximum servers kept running 2–37
Index–7
Index
Index–8
Index
Index–9
Index
Index–10
Index
Property file S
overview
UNIX 10–15 Sample WSA Web application
Windows 9–18 moving 4–2
ptpsession.p 15–5 Schema holder 12–7
Script file
Q wspd_cgi.sh shell 10–12
Index–11
Index
Index–12
Index
Starting an AppServer T
NSMAN command-line utility 2–34
Progress Explorer 2–32 TCP ports 13–20
Starting configurations Testing configuration
WSA for AIA 3–9, 3–17
Starting a WSA instance 5–14
Testing utilities
STARTING status 2–36 for AIA 3–17
State-aware operating mode Tuning
overview 2–8 Progress 4GL Web services 6–15
State-free operating mode
overview 2–9 U
Stateless operating mode
ubroker.properties file 2–17
overview 2–9
See Properties file
State-reset operating mode BrokerConnect properties 15–10
overview 2–8 editing
UNIX 10–16
Static files hierarchy
HTML AppServer 2–27
UNIX 10–14 UNIX 10–15
Windows 9–17 location
Java class files UNIX 10–16
UNIX 10–14 modifying for BrokerConnect 15–10
Windows 9–17 overview
UNIX 10–15
Status, AppServer run-time 2–36 Windows 9–18
structure 10–15
Status.p procedure
unique values needed 10–16
validating configurations updating for a secure WSA 4–5
UNIX 10–28 validating edits 10–17
Windows 9–31
undeploy function
Stream Code Page (-cpstream) startup
WSAMAN utility B–44
parameter 12–13
UNIX requirements 2–20, 3–11
Syntax
ASBMAN utility 2–35 update function
ASCONFIG utility 2–28, 5–19 WSAMAN utility B–45
System requirements URL
NT and Windows 2–19 international Web site 12–14
UNIX 2–20, 3–11
Index–13
Index
Index–14
Index
Index–15
Index
Index–16
Index
Index–17
Index
Index–18