OpenEdge Development:

TM

Web Services
 2004 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.
Allegrix, A [Stylized], ObjectStore, Progress, Powered by Progress, Progress Fast Track, Progress Profiles, Partners in Progress, Partners en Progress, Progress en
Partners, Progress in Progress, P.I.P., Progress Results, ProVision, ProCare, ProtoSpeed, SmartBeans, SpeedScript, and WebSpeed 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, Allegrix
& Design, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Business Empowerment, Empowerment Center, eXcelon, Fathom, Future Proof,
IntelliStream, ObjectCache, OpenEdge, PeerDirect, POSSE, POSSENET, ProDataSet, Progress Business Empowerment, Progress Dynamics, Progress
Empowerment Center, Progress Empowerment Program, Progress for Partners, Progress OpenEdge, Progress Software Developers Network, PSE Pro, PS Select,
Real Time Event Engine, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder,
SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Technical Empowerment, Trading Accelerator, 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.
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 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 [email protected]. 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 are copyrighted by DataDirect Technologies, 1991-2002.
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.

August 2004

Product Code: 4639

Item Number: 101198; R10.0B
Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preface1

Part I Introduction

1. Web Services in OpenEdge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

OpenEdge support for building and accessing Web services . . . . . . . . . . . . . . . . 12
Tools for developing Progress 4GL Web services . . . . . . . . . . . . . . . . . 12
Elements of 4GL client access to Web services . . . . . . . . . . . . . . . . . . . 13
Industry standards for Web services supported by OpenEdge . . . . . . . . 14
Turning 4GL application services into Web services . . . . . . . . . . . . . . . . . . . . . . . 15
AppServer for running business logic . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Open Client Toolkit and WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Web Services Adapter for administration and run-time support . . . . . . . 18
Progress Explorer framework for configuration and deployment. . . . . . . 19
Web service and server security options. . . . . . . . . . . . . . . . . . . . . . . . . 110
Documenting client programming requirements . . . . . . . . . . . . . . . . . . . 111
Building and deploying Progress 4GL Web services. . . . . . . . . . . . . . . . 112
Programming 4GL clients to access industry Web services . . . . . . . . . . . . . . . . . 116
SOAPthe message medium. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
WSDL and the Web service interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Interacting with a Web service and its operations . . . . . . . . . . . . . . . . . . 124
Handling Web service operation outputs and inputs . . . . . . . . . . . . . . . . 129
Handling Web service errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Managing asynchronous requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Contents

Part II Clients Accessing Progress 4GL Web Services

2. WSDL and Web Service Objects in Progress 4GL Web Services. . . . . . . . . . . 21

Requirements for accessing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Getting a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
WSDL file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Object representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Object binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Deployment information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
SOAP message formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Style and use attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
SOAP formats supported by Progress 4GL Web services. . . . . . . . . . . . 29
WSDL element overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3. Session Models and Object IDs in Progress 4GL Web Services . . . . . . . . . . . 31

Session models for Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Session models for AppServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
How object IDs support session models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
How session models affect Web service objects . . . . . . . . . . . . . . . . . . . . . . . . . . 34

4. General Client Programming Model for Progress 4GL Web Services . . . . . . . 41

Creating client interfaces from WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Understanding how client interfaces differ using different SOAP formats . . . . . . . 43
Method signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Method return values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
TABLE (static temp-table) parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
TABLE-HANDLE (dynamic temp-table) parameters . . . . . . . . . . . . . . . . 45
Programming for different session models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Programming for session-managed Web services. . . . . . . . . . . . . . . . . . 46
Programming for session-free Web services . . . . . . . . . . . . . . . . . . . . . . 47
Overview of calling methods on Web service objects . . . . . . . . . . . . . . . . . . . . . . 48
Client interface methods for session-managed AppObjects . . . . . . . . . . 49
Client interface methods for session-free AppObjects . . . . . . . . . . . . . . . 410
Client interface methods for SubAppObjects and ProcObjects (session-managed
and session-free) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Handling communications with Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Retrieving and sending object IDshandling SOAP headers . . . . . . . . . . . . . . . . 415
Defining object IDs in WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Using object IDs in a SOAP message . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Object IDs in examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

iv
 Contents

Defining and passing Web service method parameters . . . . . . . . . . . . . . . . . . . . 418

Client data type mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Relational data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Array parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Array mapping in WSDL documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Date and time data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Dedicated Progress 4GL data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Mapping relational data (Progress 4GL temp-tables) . . . . . . . . . . . . . . . . . . . . . . 428
Defining TABLE (static temp-table) parameters . . . . . . . . . . . . . . . . . . . 428
Defining TABLE-HANDLE (dynamic temp-table) parameters. . . . . . . . . 432
Mapping Progress procedures to SOAP messages . . . . . . . . . . . . . . . . . . . . . . . 433
4GL procedure prototype to WSDL operation (Web service
development) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
WSDL operation to client method prototype (client development) . . . . . 438
Client method call to SOAP request/response message pair
(run time). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Handling Web service errors and SOAP faults . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Client programming for SOAP faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

5. Sample Code with SOAP Messages for Progress 4GL Web Services . . . . . . 51
Sample Web service specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Accessing a session-managed Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Accessing a session-free Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Running a Progress non-persistent procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Creating and using a ProcObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
ProcObject session context. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
ProcObject IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
ProcObject class factory methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Running an internal procedure or user-defined function . . . . . . . . . . . . . . . . . . . . 514
Creating and using a SubAppObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
SubAppObject/Client associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
SubAppObject IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
SubAppObject class factory methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Releasing an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
Passing static and dynamic temp-table parameters . . . . . . . . . . . . . . . . . . . . . . . 519
Invoking a method with a TABLE parameter (RPC/Encoded) . . . . . . . . 519
Invoking a method with a TABLE-HANDLE parameter
(RPC/Encoded). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Receiving a SOAP fault message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Learning more about SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

v
Contents

6. Sample Progress 4GL Web Services and Client Applications . . . . . . . . . . . . . 61

Sample application directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Using the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

7. Testing and Debugging Progress 4GL Web Services . . . . . . . . . . . . . . . . . . . . 71

Testing the AppServer application as a Web service . . . . . . . . . . . . . . . . . . . . . . . 72
Unit testing from the Progress 4GL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Testing from a Web services client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Setting error information levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
WSA and Web service logging level properties . . . . . . . . . . . . . . . . . . . . 74
Logging information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Hints for setting the WSA loggingLevel property . . . . . . . . . . . . . . . . . . . 75
Hints for setting the Web service serviceLoggingLevel property . . . . . . . 76
Setting the logging level properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Identifying relevant log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Working with SOAP faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Setting the serviceFaultLevel property . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Typical SOAP fault response message . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Handling SOAP faults programmatically . . . . . . . . . . . . . . . . . . . . . . . . . 79
Using a SOAP message viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Identifying errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
How the WSA logs Web service information . . . . . . . . . . . . . . . . . . . . . . 712
Errors occurring in WSA administration requests. . . . . . . . . . . . . . . . . . . 713
Errors occurring in Web service application requests . . . . . . . . . . . . . . . 713
Sample error scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
Scenario 1: Web service deployed but not enabled . . . . . . . . . . . . . . . . . 715
Scenario 2: 4GL updated, but Web service not redeployed. . . . . . . . . . . 717
Scenario 3: Web service deployed but AppServer not running . . . . . . . . 719

Part III Progress 4GL Clients Accessing Industry Web Services

8. Analyzing WSDL for Progress 4GL Access to Web Services . . . . . . . . . . . . . . 81

Using the WSDL Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Index document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Operation index document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Service document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Port type document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
Data types document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821

vi
 Contents

Mapping XML Schema data types to Progress 4GL data types . . . . . . . . . . . . . . 824
Simple data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
Complex data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837

9. Connecting to Web Services from the Progress 4GL. . . . . . . . . . . . . . . . . . . . 91

What is a Web service connection? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Binding to a Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Creating a server object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Binding to a server object handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Managing Web service bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
Accessing a port type for a Web service. . . . . . . . . . . . . . . . . . . . . . . . . 910
Accessing a different port type in the same Web service . . . . . . . . . . . 912
Accessing multiple port types simultaneously. . . . . . . . . . . . . . . . . . . . . 912

10. Invoking Web Service Operations from the Progress 4GL . . . . . . . . . . . . . . . 101
Preparing to invoke operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Creating a Web service procedure object . . . . . . . . . . . . . . . . . . . . . . . . 102
Specifying SOAP header callback procedures at run time . . . . . . . . . . 103
Using the SET-CALLBACK-PROCEDURE( ) method . . . . . . . . . . . . . . 104
Defining SOAP header callback procedures. . . . . . . . . . . . . . . . . . . . . . 104
Invoking operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using the RUN Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Using a User-defined Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Managing operation parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Managing complex data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Types of complex data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Complex data example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

11. Handling SOAP Message Headers in the Progress 4GL . . . . . . . . . . . . . . . . . 111

SOAP message headersan overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
SOAP header structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
SOAP header object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Invoking a header handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Defining header handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
Defining a response header handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
Defining a request header handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
Creating and managing SOAP message headers . . . . . . . . . . . . . . . . . . . . . . . . 1113
Reusing an unchanged SOAP response header . . . . . . . . . . . . . . . . . . 1115
Modifying a reused SOAP response header. . . . . . . . . . . . . . . . . . . . . . 1120
Using a client-created SOAP request header . . . . . . . . . . . . . . . . . . . . . 1126

vii
Contents

Managing memory for SOAP headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131

SOAP header object model and DOM relationships . . . . . . . . . . . . . . . . 1131
Memory for the SOAP header object model and DOM . . . . . . . . . . . . . . 1132
Attributes and methods for handling SOAP headers . . . . . . . . . . . . . . . . . . . . . . . 1133
SOAP header object attributes and methods . . . . . . . . . . . . . . . . . . . . . . 1133
SOAP header-entryref object attributes and methods . . . . . . . . . . . . . . . 1134

12. Handling Errors in Progress 4GL Requests to Web Services . . . . . . . . . . . . . 121

Handling SOAP faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Detecting a SOAP fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Managing a SOAP fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Example 4GL accessing a SOAP fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Debugging 4GL applications that call Web services . . . . . . . . . . . . . . . . . . . . . . . 128
SOAP Viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Using WSAViewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Using ProSOAPView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211

13. Sample Progress 4GL Applications Accessing Web Services . . . . . . . . . . . . . 131

Samples overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Temperature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
StockQuotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
DatatypeFormats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Using the Temperature sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Web service description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Temperature sample walk-through . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Using the StockQuotes sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Web service description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1310
StockQuotes sample walk-through . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311
Using the DatatypeFormats sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318
Web service description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318
DatatypeFormats sample walk-through . . . . . . . . . . . . . . . . . . . . . . . . . . 1320
Common procedure for SOAP fault handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1327

Part IV Appendices

A. Developing a .NET Client to Access Progress 4GL Web Services . . . . . . . . . . A1

What is Microsoft .NET? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A2
Using .NET as your Web services client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A3
VB.NET sample Web service specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A3

viii
 Contents

Creating the VB.NET client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A4

Adding a Web reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A5
Reference.vbWeb service client interface . . . . . . . . . . . . . . . . . . . . . . A5
Reference.vbOpen Client objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . A6
.NET data type mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A7
Accessing parameter data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A7
TABLE (static temp-table) parameters . . . . . . . . . . . . . . . . . . . . . . . . . . A8
TABLE-HANDLE (dynamic temp-table) parameters . . . . . . . . . . . . . . . A9
Sample interface object prototypes in Reference.vb . . . . . . . . . . . . . . . A10
Sample common interface method prototypes in Reference.vb . . . . . . . A11
Sample Progress 4GL and VB.NET interface method prototypes . . . . . A12
Developing the VB.NET client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A15
Creating the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A16
Running a non-persistent (external) procedure. . . . . . . . . . . . . . . . . . . . A16
Creating server-side context for a ProcObject (running a
persistent procedure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A17
Running an internal procedure or user-defined function . . . . . . . . . . . . . A18
Creating a SubAppObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A18
Releasing an object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A19
Running a procedure that passes a TABLE parameter . . . . . . . . . . . . . A19
Processing the data from a TABLE parameter . . . . . . . . . . . . . . . . . . . . A20
Running a procedure that passes a TABLE-HANDLE parameter. . . . . . A20
Preparing the schema and data for an input TABLE-HANDLE
parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A21
Processing the schema and data for an output TABLE-HANDLE
parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A22
Extra processing required for RPC/Encoded TABLE-HANDLE
parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A23
Handling errors on the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A24
Compiling and running the .NET client application . . . . . . . . . . . . . . . . . . . . . . . . A24
Learning more about writing .NET clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A25

B. Developing a Java Client to Access Progress 4GL Web Services . . . . . . . . . B1

Using Java client toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B2
Java sample Web service specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B3
Creating Java Axis client interface objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B4
Generating client interface objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B5
Proxy directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B5
Proxy classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B6
Java data type mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B7
Output parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B7
Progress 4GL unknown values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B8

ix
Contents

TABLE (static temp-table) parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . B8

TABLE-HANDLE (dynamic temp-table) parameters . . . . . . . . . . . . . . . . B10
Sample Java prototypes for common object methods . . . . . . . . . . . . . . . B11
Sample Progress 4GL and Java interface method prototypes . . . . . . . . B12
Developing the Axis client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B15
Setting up the Web service objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B16
Using the sample PscObjectIDHandler and HandlerControlBlock
classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B17
Setting up the PscObjectIDHandler objects . . . . . . . . . . . . . . . . . . . . . . . B18
Connecting to a Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B20
Running a non-persistent (external) procedure . . . . . . . . . . . . . . . . . . . . B20
Creating server-side context for a ProcObject (running a
persistent procedure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B21
Running an internal procedure or user-defined function . . . . . . . . . . . . . B22
Running an internal procedure that passes a TABLE parameter. . . . . . . B23
Processing the data from a TABLE parameter. . . . . . . . . . . . . . . . . . . . . B23
Running a procedure that passes a TABLE-HANDLE parameter . . . . . . B24
Using sample helper classes to manage TABLE-HANDLE parameters . B25
Preparing the schema and data for input TABLE-HANDLE parameters . B26
Processing the schema and data for output TABLE-HANDLE
parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B27
Releasing an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B28
Handling errors on the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B29
Compiling and running the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B31
Learning more about writing Java clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B31

C. Progress 4GL Elements for Accessing Web Services. . . . . . . . . . . . . . . . . . . . C1

Handles for accessing a Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C2
Statements for accessing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C4
Attributes, methods, and events for accessing Web services . . . . . . . . . . . . . . . . C7

D. Data Type Casting Rules for Progress 4GL Calls to Web Services . . . . . . . . . D1
CHARACTER or LONGCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D3
DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D4
DATETIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D5
DATETIME-TZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D6
DECIMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D7
INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D9
LOGICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D12
MEMPTR or RAW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D13

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index1

x
 Contents

Figures
Figure 11: Progress 4GL Web services architecture . . . . . . . . . . . . . . . . . . . . . . 15
Figure 12: Progress 4GL clients accessing Web services . . . . . . . . . . . . . . . . . . 116
Figure 41: OpenEdge Web services architecture . . . . . . . . . . . . . . . . . . . . . . . . . 414
Figure 61: Progress 4GL Web services sample applications . . . . . . . . . . . . . . . . 62
Figure 71: WSAViewer main window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Figure 81: WSDL Analyzer index document for multiple services . . . . . . . . . . . . 85
Figure 82: WSDL Analyzer operation index document . . . . . . . . . . . . . . . . . . . . . 87
Figure 83: WSDL Analyzer service document for one of multiple services . . . . . . 88
Figure 84: WSDL Analyzer service document for a single service only . . . . . . . . 810
Figure 85: WSDL Analyzer port type document (up to the Summary) . . . . . . . . . 812
Figure 86: WSDL Analyzer port type document (connection parameters) . . . . . . 814
Figure 87: WSDL Analyzer port type document (services and ports) . . . . . . . . . . 815
Figure 88: WSDL Analyzer port type document (example connection code) . . . . 816
Figure 89: WSDL Analyzer port type document (operation detail start) . . . . . . . . 818
Figure 810: WSDL Analyzer port type document (operation detail finish) . . . . . . . 819
Figure 811: WSDL Analyzer data types document (summary list) . . . . . . . . . . . . . 821
Figure 812: WSDL Analyzer data types document (data type detail) . . . . . . . . . . . 822
Figure 111: Referencing a header entry in the SOAP header object model . . . . . . 115
Figure 112: Accessing entry elements in the SOAP header object model . . . . . . . 116
Figure 121: SOAPSpy window opened by ProSOAPView . . . . . . . . . . . . . . . . . . . 1211
Figure 122: ProSOAPView Spy menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
Figure 123: ProSOAPView status bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
Figure 124: ProSOAPView Call types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
Figure 125: ProSOAPView Request tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
Figure 126: ProSOAPView Call menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214

xi
Contents

Tables
Table 11: WSDL sections overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Table 12: AppServer and Web service access compared . . . . . . . . . . . . . . . . . . 125
Table 13: Attributes on Web service asynchronous request object handle . . . . . 135
Table 14: Results for asynchronous Web service requests . . . . . . . . . . . . . . . . . 136
Table 21: WSDL style and use attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 22: Supported SOAP message formats . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 23: WSDL element overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Table 41: Supported XML data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Table 42: Valid date input formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Table 43: XML data types for TABLE (static temp-table) parameter columns . . . 431
Table 44: XML data types for TABLE-HANDLE (dynamic temp-table)
parameter columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Table 51: Sample Web service specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Table 71: Setting error levels for WSA and Web services . . . . . . . . . . . . . . . . . . 74
Table 72: OpenEdge log files providing Web service-related messages . . . . . . . 77
Table 73: Some SOAP message viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Table 74: WSA administration error logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Table 75: Sample Web service specification for error scenarios . . . . . . . . . . . . . 715
Table 81: WSDL Analyzer docIndex document for multiple services . . . . . . . . 86
Table 82: WSDL Analyzer docOperation index document list . . . . . . . . . . . . . . 87
Table 83: WSDL Analyzer docService document (from multiple services) . . . . 89
Table 84: WSDL Analyzer docService document (from one service) . . . . . . . . 811
Table 85: WSDL Analyzer docPort type document beginning sections . . . . . . 813
Table 86: WSDL Analyzer docPort type document connection details . . . . . . . 817
Table 87: WSDL Analyzer docPort type document operation detail . . . . . . . . . 820
Table 88: WSDL Analyzer docData types document . . . . . . . . . . . . . . . . . . . . 823
Table 89: Suggested XML Schema mappings to Progress 4GL data types . . . . . 825
Table 810: Supported casts between XML Schema and Progress 4GL
data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Table 91: Web service connection parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Table 111: 4GL to manage object memory for SOAP headers . . . . . . . . . . . . . . . . 1132
Table 112: SOAP header object attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133
Table 113: SOAP header object methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
Table 114: SOAP header-entryref object attributes . . . . . . . . . . . . . . . . . . . . . . . . 1134
Table 115: SOAP header-entryref object methods . . . . . . . . . . . . . . . . . . . . . . . . . 1135
Table 121: ERROR-STATUS handle attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Table 122: SOAP fault object attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Table 123: SOAP fault-detail object attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Table 124: SOAP fault-detail object methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Table 125: Web service message viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Table 131: DatatypeFormats sample applicationexample formats . . . . . . . . . . . 1318
Table 132: DatatypeFormats sample applicationinput parameters . . . . . . . . . . . 1319
Table 133: DatatypeFormats sample applicationoutput parameters . . . . . . . . . . 1319

xii
 Contents

Table A1: VB.NET sample Web service specifications . . . . . . . . . . . . . . . . . . . . A3

Table A2: Supported .NET data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A7
Table A3: .NET data types for TABLE (static temp-table) parameter columns . . A8
Table A4: .NET data types for TABLE-HANDLE (dynamic temp-table)
parameter columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A9
Table B1: Java sample Web service specifications . . . . . . . . . . . . . . . . . . . . . . . B3
Table B2: Proxy classes for a sample Java Axis client (RPC/Encoded) . . . . . . . B6
Table B3: Supported Java data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B7
Table B4: Java data types for TABLE (static temp-table) parameter columns . . . B9
Table B5: Java data types for TABLE-HANDLE (dynamic temp-table)
parameter columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B10
Table C1: Handles to access Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C2
Table C2: Statements to access Web services . . . . . . . . . . . . . . . . . . . . . . . . . . C4
Table C3: Attributes, methods, and events to access Web services . . . . . . . . . . C7
Table D1: 4GL data type castCHARACTER or LONGCHAR . . . . . . . . . . . . . . D3
Table D2: 4GL data type castDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D4
Table D3: 4GL data type castDATETIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D5
Table D4: 4GL data type castDATETIME-TZ . . . . . . . . . . . . . . . . . . . . . . . . . . D6
Table D5: 4GL data type castDECIMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D7
Table D6: 4GL data type castINTEGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D9
Table D7: 4GL data type castLOGICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D12
Table D8: 4GL data type castRAW or MEMPTR . . . . . . . . . . . . . . . . . . . . . . . D13

xiii
Contents

Procedures
WSDL Containing an object ID definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
SOAP header containing an object ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
arraySample procedure signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Array parameter definition for RPC/Encoded WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
RPC/Encoded WSDL schema example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Array parameter definition for RPC/Literal WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
RPC/Literal WSDL schema example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Array parameter definition for Document/Literal WSDL . . . . . . . . . . . . . . . . . . . . . . . . . 425
Document/Literal WSDL schema example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
TABLE parameter row schema for all SOAP formats . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
TABLE parameter for RPC/Encoded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
TABLE parameter for RPC/Literal and Document/Literal . . . . . . . . . . . . . . . . . . . . . . . . 429
TABLE parametersgeneral RPC/Encoded format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
TABLE parametersgeneral Document (or RPC)/Literal format . . . . . . . . . . . . . . . . . . 430
TABLE-HANDLE definition for all dynamic temp-table parameters . . . . . . . . . . . . . . . . 432
TABLE-HANDLE parametersgeneral format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Progress 4GL procedure prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
WSDL message section defining request and response messages . . . . . . . . . . . . . . . . 435
WSDL portType section defining an operation signature on an object . . . . . . . . . . . . . . 436
WSDL Bindings section defining an operation and object binding . . . . . . . . . . . . . . . . . 437
WSDL service section defining the Web service location . . . . . . . . . . . . . . . . . . . . . . . . 438
Interface method prototype (VB.NET) generated from a WSDL operation definition . . . 438
Interface method call (VB.NET) generating SOAP messages . . . . . . . . . . . . . . . . . . . . 439
SOAP request message for method input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 439
SOAP response message for method output parameters . . . . . . . . . . . . . . . . . . . . . . . 440
SOAP faultsgeneral format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
VB.NET method declarations on AppObject, OrderInfo . . . . . . . . . . . . . . . . . . . . . . . . . 52
VB.NET method declarations on ProcObject, CustomerOrder . . . . . . . . . . . . . . . . . . . . 53
VB.NET method declarations on SubAppObject, Payroll . . . . . . . . . . . . . . . . . . . . . . . . 53
VB.NET prototype for an AppObject Connect_Object method . . . . . . . . . . . . . . . . . . . . 54
VB.NET client code for the connect method on AppObject, OrderInfo . . . . . . . . . . . . . . 55
SOAP connect request for AppObject, OrderInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
SOAP response to OrderInfo AppObject connect request . . . . . . . . . . . . . . . . . . . . . . . 56
VB.NET client code to instantiate session-free AppObject, OrderInfo . . . . . . . . . . . . . . 57
Progress 4GL prototype for a non-persistent external procedure . . . . . . . . . . . . . . . . . . 58
VB.NET prototype for a method that runs a Progress non-persistent procedure . . . . . . 58
VB.NET client code calling an external procedure method . . . . . . . . . . . . . . . . . . . . . . . 58
SOAP request from calling the FindCustomerByNum procedure method . . . . . . . . . . . 59
SOAP response from calling the FindCustomerByNum method . . . . . . . . . . . . . . . . . . . 59
Progress 4GL prototype for a persistent procedure to implement a ProcObject . . . . . . . 511
VB.NET prototype for the ProcObject CreatePO_CustomerOrder method . . . . . . . . . . 511
VB.NET client code to create the ProcObject, CustomerOrder . . . . . . . . . . . . . . . . . . . 512
SOAP request to create ProcObject, CustomerOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . 512

xiv
 Contents

SOAP response from creating ProcObject, CustomerOrder . . . . . . . . . . . . . . . . . . . . . 513

Progress 4GL prototype for a user-defined function . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
VB.NET prototype for a Progress user-defined function method . . . . . . . . . . . . . . . . . . 514
VB.NET client code of method to run a Progress user-defined function . . . . . . . . . . . . 514
SOAP request for user-defined function method, GetTotalOrdersByNumber . . . . . . . . 515
SOAP response from calling the GetTotalOrdersByNumber method . . . . . . . . . . . . . . 515
VB.NET prototype for an SubAppObject CreateAO_Payroll method . . . . . . . . . . . . . . . 517
VB.NET declaration of method to create a SubAppObject . . . . . . . . . . . . . . . . . . . . . . 518
VB.NET prototype for a Release_Object method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
VB.NET client code calling methods to release objects . . . . . . . . . . . . . . . . . . . . . . . . . 519
Progress 4GL prototype that passes a TABLE parameter . . . . . . . . . . . . . . . . . . . . . . . 519
RPC/Encoded WSDL definition for TABLE parameter, ttEmp . . . . . . . . . . . . . . . . . . . . 520
TABLE row schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
TABLE parameter for RPC/Encoded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
TABLE parameter for RPC/Literal and Document/Literal . . . . . . . . . . . . . . . . . . . . . . . 520
VB.NET declaration of interface method passing static TEMP-TABLE, ttEmp . . . . . . . 521
VB.NET client code passing TABLE, ttEmp, to an interface method . . . . . . . . . . . . . . . 521
RPC/Encoded SOAP request to pass a TABLE parameter . . . . . . . . . . . . . . . . . . . . . . 522
Document/Literal SOAP request to pass a TABLE parameter . . . . . . . . . . . . . . . . . . . 523
Progress 4GL prototype that passes a TABLE-HANDLE parameter . . . . . . . . . . . . . . . 524
RPC/Encoded WSDL definition for TABLE-HANDLE parameter, ttHandle . . . . . . . . . . 524
TABLE-HANDLE definition for all TABLE-HANDLE parameters . . . . . . . . . . . . . . . . . . 525
VB.NET declaration of interface method passing TABLE-HANDLE, ttHandle . . . . . . . . 525
VB.NET client code passing TABLE-HANDLE, ttHandle, to interface method . . . . . . . 525
SOAP request (RPC/Encoded) for TABLE-HANDLE, ttHandle . . . . . . . . . . . . . . . . . . . 526
TABLE-HANDLE <schema> element for an RPC/Encoded SOAP request . . . . . . . . . 527
TABLE-HANDLE <Data> element for an RPC/Encoded SOAP request . . . . . . . . . . . . 527
Sample SOAP fault for disabled Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Binding a Web service in the 4GL using service and port . . . . . . . . . . . . . . . . . . . . . . . 98
Binding a Web service in the 4GL using binding and SOAP endpoint . . . . . . . . . . . . . . 98
Accessing a port type for a Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
Accessing multiple port types simultaneously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
4GL prototype for operation with complex type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Complex type in the WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
Complex type managed in the 4GL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
SOAP message with header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Invocation of a header handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Definition of a header handler procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
SOAP response header to be reused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
Invoking a request that reuses an unchanged SOAP response header . . . . . . . . . . . . 1116
Response header handler saving a SOAP response header for reuse . . . . . . . . . . . . . 1118
Request header handler reusing a saved SOAP response header . . . . . . . . . . . . . . . . 1119
SOAP request header built from a modified SOAP response header . . . . . . . . . . . . . . 1120
Invoking a request that modifies a reused SOAP response header (start) . . . . . . . . . . 1121
Invoking a request that modifies a reused SOAP response header (end) . . . . . . . . . . . 1122

xv
Contents

Request header handler modifying a saved SOAP response header (start) . . . . . . . . . 1123
Request header handler modifying a saved SOAP response header (end) . . . . . . . . . . 1124
SOAP request header created entirely by the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
Invoking a request that creates a SOAP request header on the client . . . . . . . . . . . . . . 1127
Procedure to create a SOAP request header (start) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
Procedure to create a SOAP request header (continuation) . . . . . . . . . . . . . . . . . . . . . 1129
Procedure to create a SOAP request header (end) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
Request header handler passing a client-created SOAP request header . . . . . . . . . . . 1130
Sample SOAP fault message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Sample SOAP fault procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

xvi
Preface
This Preface contains the following sections:

Purpose

Audience

Organization

Typographical conventions

Examples of syntax descriptions

OpenEdge messages
OpenEdge Development: Web Services

Purpose
This manual describes how OpenEdge supports Web services. It describes the technology for
exposing AppServer application services as Web services (Progress 4GL Web services),
and how to access industry Web services from the Progress 4GL as a Web service client. It also
describes the requirements for programming industry Web service clients to access Progress
4GL Web services. And it defines the Web services industry standards that OpenEdge supports.

This manual provides a brief overview of Web services architecture in OpenEdge. However, for
a complete description of the Web services architecture in OpenEdge, including all components
and how they work together, see OpenEdge Getting Started: Application and Integration
Services.

This manual describes the general procedures and facilities for building Progress 4GL Web
services, as well as specific client requirements. However, for specific information on Web
service development, deployment, and administration, see the following documentation:

Web service development:

OpenEdge Application Server: Developing AppServer Applications

OpenEdge Development: Open Client Introduction and Programming

Web service deployment and administration:

OpenEdge Application Server: Administration

Progress Explorer online help for the Web Services Adapter

OpenEdge Development: Messaging and ESB (for deploying and managing Progress
4GL Web services for the Sonic ESB using the Sonic ESB Adapter)

Audience
The most appropriate reader for this manual is one or both of the following:

An experienced developer or provider of Progress 4GL application services who wants to

make an application service available as a Web service over the Internet or an intranet.

An experienced Progress 4GL (or SpeedScript) developer who wants to access industry
Web services from their 4GL (or SpeedScript) application.

Preface2
 Preface

Organization
Part I, Introduction

Chapter 1, Web Services in OpenEdge

Provides a general overview of Web services in OpenEdge, describing how to develop,

deploy, and manage Progress 4GL Web services, and how you can access industry Web
services from a Progress 4GL application. This includes a brief overview of the Web
Service Description Language (WSDL) and Simple Object Access Protocol (SOAP) that
provides part of the foundation for Web services in OpenEdge. This chapter also describes
the industry Web service standards that OpenEdge supports.

Part II, Clients Accessing Progress 4GL Web Services

Chapter 2, WSDL and Web Service Objects in Progress 4GL Web Services

Describes how the interface to Progress 4GL Web services is based on the Open Client
object model and defined in a Web Service Description (WSDL) file.

Chapter 3, Session Models and Object IDs in Progress 4GL Web Services

Describes how Progress 4GL Web services support AppServer session models.

Chapter 4, General Client Programming Model for Progress 4GL Web Services

Describes how to program client access to Progress 4GL Web services using the Open
Client object model, including a description of session model programming, data type
mapping, handling SOAP headers, and SOAP faults.

Chapter 5, Sample Code with SOAP Messages for Progress 4GL Web Services

Describes, in detail, the techniques for coding Progress 4GL Web service operations using
VB.NET as the sample client platform, showing the types of SOAP messages that are
generated for various types of SOAP requests supported by the Open Client object model.

Chapter 6, Sample Progress 4GL Web Services and Client Applications

Describes the sample Progress 4GL Web services that are installed with OpenEdge and
the sample client applications to access them (also installed).

Preface3
OpenEdge Development: Web Services

Chapter 7, Testing and Debugging Progress 4GL Web Services

Describes how to test and debug Progress 4GL Web services using log files, SOAP
viewers, and basic SOAP fault handling techniques.

Part III, Progress 4GL Clients Accessing Industry Web Services

Chapter 8, Analyzing WSDL for Progress 4GL Access to Web Services

Describes how to run the WSDL Analyzer to generate documentation on a Web service.
This documentation describes how to connect to a Web service defined in the WSDL and
how to call its operations from the 4GL. The chapter also describes how OpenEdge maps
Progress 4GL data types to the XML Schema data types interpreted by Web services.

Chapter 9, Connecting to Web Services from the Progress 4GL

Describes how to connect to and manage connections to a Web service from the 4GL once
you have generated the WSDL documentation for it.

Chapter 10, Invoking Web Service Operations from the Progress 4GL

Describes how to invoke and manage Web service operations from the 4GL once you have
generated the WSDL documentation for it. This includes information on how to configure
Web service operations for managing SOAP message headers in the 4GL.

Chapter 11, Handling SOAP Message Headers in the Progress 4GL

Describes how to manage SOAP message headers in the 4GL for Web service operations
that are configured for SOAP header management. This includes a detailed description of
the 4GL techniques for accessing, manipulating, creating, and managing all elements of a
SOAP message header.

Chapter 12, Handling Errors in Progress 4GL Requests to Web Services

Describes how to manage errors from 4GL requests to Web services in general and for
SOAP faults in particular. This includes a detailed description of the 4GL techniques for
accessing all elements of a SOAP fault message.

Chapter 13, Sample Progress 4GL Applications Accessing Web Services

Describes some of the sample 4GL applications installed with OpenEdge that access Web
services, both public Web services and sample Web services provided with OpenEdge for
deployment.

Preface4
 Preface

Part IV, Appendices

Appendix A, Developing a .NET Client to Access Progress 4GL Web Services

Describes a sample scenario in which a .NET client application is developed to access a

Progress 4GL Web service.

Appendix B, Developing a Java Client to Access Progress 4GL Web Services

Describes a sample scenario in which a Java client application is developed to access a

Progress 4GL Web service.

Appendix C, Progress 4GL Elements for Accessing Web Services

Provides a quick reference to the basic Progress 4GL elements provided by OpenEdge to
access Web services.

Appendix D, Data Type Casting Rules for Progress 4GL Calls to Web Services

Describes in finer detail the key rules used to transform data for Web service operation
parameters between alternative mappings of Progress 4GL data types and XML Schema
data types.

Typographical conventions
This manual uses the following typographical conventions:

Convention Description

Bold Bold typeface indicates commands or characters the user types, or

the names of user interface elements.

Italic Italic typeface indicates the title of a document, provides

emphasis, or signifies new terms.

SMALL, BOLD Small, bold capital letters indicate OpenEdge key functions and
CAPITAL LETTERS generic keyboard keys; for example, GET and CTRL.

KEY1-KEY2 A hyphen between key names indicates a simultaneous key

sequence: you press and hold down the first key while pressing the
second key. For example, CTRL-X.

Preface5
OpenEdge Development: Web Services

Convention Description

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:

Fixed width A fixed-width font is used in syntax statements, code examples,

and for system output and filenames.

Fixed-width italics Fixed-width italics indicate variables in syntax statements.

Fixed-width bold Fixed-width bold indicates variables with special emphasis.

UPPERCASE Uppercase words are Progress 4GL language keywords.

fixed width Although these always are shown in uppercase, you can type them
in either uppercase or lowercase in a procedure.

This icon (three arrows) introduces a multi-step procedure.

This icon (one arrow) introduces a single-step procedure.

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.

[] Large brackets indicate the items within them are optional.

[] Small brackets are part of the Progress 4GL language.

{} 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.

| A vertical bar indicates a choice.

... Ellipses indicate repetition: you can choose one or more of the
preceding items.

Preface6
 Preface

Examples of syntax descriptions

In this example, ACCUM is a keyword, and aggregate and expression are variables:

Syntax

ACCUM aggregate expression

FOR is one of the statements that can end with either a period or a colon, as in this example:

FOR EACH Customer:

DISPLAY Name.
END.

In this example, STREAM stream, UNLESS-HIDDEN, and NO-ERROR are optional:

Syntax

DISPLAY [ STREAM stream ] [ UNLESS-HIDDEN ] [ NO-ERROR ]

In this example, the outer (small) brackets are part of the language, and the inner (large) brackets
denote an optional item:

Syntax

INITIAL [ constant [ , constant ] ]

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

PRESELECT [ EACH | FIRST | LAST ] record-phrase

Preface7
OpenEdge Development: Web Services

In this example, you must include two expressions, and optionally you can include more.
Multiple expressions are separated by commas:

Syntax

MAXIMUM ( expression , expression [ , expression ] ... )

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

MESSAGE { expression | SKIP [ ( n ) ] } ...

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" ] ... }

Long syntax descriptions split across lines

Some syntax descriptions are too long to fit on one line. When syntax descriptions are split
across multiple lines, groups of optional and groups of required items are kept together in the
required order.

In this example, WITH is followed by six optional items:

Syntax

WITH [ ACCUM max-length ][ expression DOWN ]

[ CENTERED ] [ n COLUMNS ][ SIDE-LABELS ]
[ STREAM-IO ]

Preface8
 Preface

Complex syntax descriptions with both required and

optional elements
Some syntax descriptions are too complex to distinguish required and optional elements by
bracketing only the optional elements. For such syntax, the descriptions include both braces (for
required elements) and brackets (for optional elements).

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

ASSIGN { [ FRAME frame ] { field [ = expression ] }

[ WHEN expression ] } ...
| { record [ EXCEPT field ... ] }

OpenEdge messages
OpenEdge displays several types of messages to inform you of routine and unusual occurrences:

Execution messages inform you of errors encountered while OpenEdge is running a

procedure; for example, if OpenEdge cannot find a record with a specified index field
value.

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.

Preface9
OpenEdge Development: Web Services

After displaying a message, OpenEdge proceeds in one of several ways:

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.

Terminates the current session.

OpenEdge messages end with a message number in parentheses. In this example, the message
number is 200:

** Unknown table name table. (200)

If you encounter an error that terminates OpenEdge, note the message number before restarting.

Obtaining more information about OpenEdge messages

On Windows platforms, use OpenEdge online help to obtain more information about OpenEdge
messages. Many OpenEdge tools include the following Help menu options to provide
information about messages:

Choose HelpRecent Messages to display detailed descriptions of the most recent

OpenEdge message and all other messages returned in the current session.

Choose HelpMessages and then enter the message number to display a description of
a specific OpenEdge message.

In the Progress Procedure Editor, press the HELP key or F1.

Preface10
 Preface

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.

To use the pro command to obtain a message description by message number:

1. Start the Progress Procedure Editor:

install-dir/dlc/bin/pro

2. Press F3 to access the menu bar, then choose Help Messages.

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.

Preface11
OpenEdge Development: Web Services

Preface12
 Part I
Introduction

Chapter 1, Web Services in OpenEdge

 1
Web Services in OpenEdge

In OpenEdge, you can:

Deploy Web services that you build from Progress 4GL application services running on
the AppServer. These Progress 4GL Web services are accessible from any application
that can access industry Web services as a client.
Access industry Web services and invoke Web service operations from any 4GL
application, and otherwise manage interactions with Web services from the 4GL in a
manner consistent with industry Web service clients.

This chapter describes the general support for Web services in OpenEdge and contains the
following sections:

OpenEdge support for building and accessing Web services

Turning 4GL application services into Web services

Programming 4GL clients to access industry Web services

For a general introduction to Web services and a detailed architectural overview of Web
services in OpenEdge, see OpenEdge Getting Started: Application and Integration Services.
OpenEdge Development: Web Services

OpenEdge support for building and accessing Web services

OpenEdge provides a set software tools and 4GL language elements specifically designed to
build Progress 4GL Web services on the one and, and access industry Web services from the
4GL on the other. This section describes:

Tools for developing Progress 4GL Web services

Elements of 4GL client access to Web services

Industry standards for Web services supported by OpenEdge

Tools for developing Progress 4GL Web services

In OpenEdge, you can build and deploy Web services using the AppServer, OpenEdge Web
service tools, including the OpenEdge Web Services Adapter (WSA). The Web service tools
allow you to develop a Web-service-enabled AppServer application service using the
OpenEdge Open Client Toolkit, then to deploy this application as a Web service using the
Progress Explorer framework.

Open Client Toolkit and 4GL Web services

You can define Web services using the Open Client Toolkit much as you define traditional Open
Client proxies. However, instead of generating Open Client proxies for immediate access by
Open Client applications, you generate a client interface definition, Web Service Mapping file
(.wsm), and deploy this definition generating a Web Service Description Language (WSDL) file
and property files that you then manage, along with the operational Web service, within the
context of the WSA.

Web Services Adapter

The WSA is a Java servlet running on a Web server or stand-alone JSE. Situated between the
client and AppServer, this Java servlet understands how to communicate at run time:

With a Web service client using Simple Object Access Protocol (SOAP).

With an AppServer using the Progress 4GL interface to the application service.

The WSA also generates the WSDL file required by Web service clients during Web service
deployment, and it maintains the status of all 4GL Web services that have been deployed to its
Web application context. It serves as the SOAP-to-business interface gateway and Web service
management engine for your 4GL Web service. The WSA provides client access to the Web

12
 Web Services in OpenEdge

service WSDL file and supports Web service administration; it also manages the exchange of
Web service SOAP requests and generates SOAP responses between Web service clients and
AppServers at run time.

For an overview of the components and procedures for building Progress 4GL Web services,
see the Turning 4GL application services into Web services section on page 15.

Elements of 4GL client access to Web services

Like most Web service client platforms, the 4GL relies on a WSDL file to define the interface
for a Web service that it accesses. OpenEdge provides a utility, the WSDL Analyzer, that reads
the WSDL file for a Web service and generates documentation describing requirements for
invoking and managing Web service operations in the 4GL. OpenEdge also requires access to
the WSDL file at run time to interpret 4GL calls to Web service operations and to manage the
exchange of data between the 4GL client and the Web service.

Access to Web services and AppServerssimilarities and differences

The 4GL views a Web service very much like an application service provided directly through
the AppServer. To access a Web service, OpenEdge provides many of the same 4GL elements
that you use to access a session-free AppServer, and it provides additional elements specifically
designed to manage calls to a Web service that are not required to access an AppServer directly.

Requirements for accessing Web services in the 4GL

In general, all 4GL network deployment models support inherent access to Web services,
including:

A small or large networked client application.

A WebClient application.

Business logic running on an AppServer.

SpeedScript running on a WebSpeed Transaction Server.

All you need is the WSDL file, any additional documentation provided for using the Web
service, and a networked 4GL session and development environment to develop and deploy
4GL applications that access Web services.

For an overview of the tools and procedures for accessing industry Web services in the 4GL,
see the Programming 4GL clients to access industry Web services section on page 116.

13
OpenEdge Development: Web Services

4GL applications accessing Progress 4GL Web services

It is possible for a 4GL application to access Progress 4GL Web services. However, the greater
efficiency achieved by accessing an AppServer directly over the Internet using the AppServer
Internet Adapter (AIA), and certainly the ability to access an AppServer directly within an
intranet, makes the choice to use a Progress 4GL Web service interface for the same purpose
somewhat less useful.

However, if you happen to use a Web service written in the Progress 4GL, you can follow the
same procedures required of any Web service client to access a Progress 4GL Web service. For
more information, see Part II, Clients Accessing Progress 4GL Web Services.

Industry standards for Web services supported by

OpenEdge
OpenEdge supports the following industry standards for both Progress 4GL Web services
development and 4GL applications accessing industry Web services:

WSDL WSDL 1.1 (W3C Notethe de facto standard). For more information on
WSDL, visit the following Web address:

http://www.w3.org/TR/wsdl

SOAP SOAP 1.1 HTTP Binding. For more information on SOAP, visit the following
Web address:

http://www.w3.org/TR/SOAP

XML Schema W3C 2001 XML Schema. For more information on XML Schema, visit
the following Web address:

http://www.w3.org/TR/xmlschema-0/

14
 Web Services in OpenEdge

Turning 4GL application services into Web services

Figure 11 shows the basic Progress 4GL Web services architecture, indicating how the WSA
provides the SOAP-to-business interface gateway for an application service provided by the
AppServer.

Web service
Web server/JSE AppServer

Web services
client
Post (SOAP)

Web Services
Java

HTTP listener
VB.NET Progress

Adapter
HTTP/S

(WSA)
Progress 4GL
... business
Response (SOAP) logic

WSDL

Figure 11: Progress 4GL Web services architecture

In this figure, the standard set of components required for Web services in general appear with
gray shading, and those required for Progress 4GL Web services appear with darker gray
shading. Otherwise, the Progress 4GL Web services architecture provides features that are
virtually identical to any other Web services architecture in the industry.

15
OpenEdge Development: Web Services

OpenEdge supports these features with the components of the Web service tools for all phases
of Web service development, deployment, and management:

AppServer for running business logic

Open Client Toolkit and WSDL

Web Services Adapter for administration and run-time support

Progress Explorer framework for configuration and deployment

Web service and server security options

Documenting client programming requirements

Building and deploying Progress 4GL Web services

AppServer for running business logic

The business end of a Web service created with OpenEdge is the set of Progress 4GL procedures
running on an AppServer that execute Web service requests. With OpenEdge, you can develop
new AppServer applications for use as Web services, or you can define new Web services based
on existing AppServer applications. When you Web service-enable an existing AppServer
application, you do not have to make any code changes in order to make them accessible as Web
services.

The AppServer supports four operating modes for Web service applications:

The stateless, state-aware, and state-reset operating modes (supported for all OpenEdge
clients). As with other OpenEdge clients, these operating modes maintain a private and
persistent connection for each client of the Web service. So, the AppServer accepts all
requests from each client over this private connection.

The state-free operating mode (not supported for Java and .NET Open Clients). With this
operating mode, the AppServer accepts requests from any and all Web service clients
without the use of connections.

These operating modes thus support two distinct session models for Web services:

The connection-oriented operating modes support a session-managed model.

The connectionless, state-free, operating mode supports a session-free model.

16
 Web Services in OpenEdge

The session-managed model provides varying types of support for maintaining and managing
session context across client requests, throughout the life of the client connection. With this
model, the type of context management supported depends on the actual operating mode of the
AppServer, and the AppServer application must be written to maintain session context
accordingly. With this model, the AppServer handles all requests from a single client
sequentially, completing each request before accepting another, which allows an orderly
maintenance of context from one request to the next.

The session-free model supports a completely connectionless and context-free interaction

between the client and Web service application. This session-free model is far more scalable
than the session-managed model because the AppServer accepts client requests from all clients
as fast as it can execute them, and in no special order. The AppServer also runs as many requests
at a time in parallel as the number of Application Server processes it has available to handle
them. Thus, no AppServer resource (memory or process) is reserved for indefinite use by a
single client, as is the case with the session-managed model. With this model, the AppServer
application must be written to be context free, and all mechanisms otherwise available for
context management on the AppServer are not supported.

For more information on setting up and programming the AppServer for Web services using
both session models, see OpenEdge Application Server: Developing AppServer Applications

Open Client Toolkit and WSDL

To make an AppServer application accessible as a Web service, you use the OpenEdge Open
Client Proxy Generator (ProxyGen), provided by the Open Client Toolkit to define the Web
service interface for the application. To define the Web service, you follow the Open Client
object model, much as you define proxies for other Open Clients (see OpenEdge Development:
Open Client Introduction and Programming). However, instead of generating an Open Client
proxy for the Web service, you generate the Web service (client interface) definition in a WSM
file used to deploy the Web service and an optional WSDL file for Web service client
development (see the Web services development components architecture in OpenEdge Getting
Started: Application and Integration Services).

Thus, the Open Client interface definition that you specify and that ProxyGen generates
includes at least one AppObject, zero or more SubAppObjects, and zero or more ProcObjects.
These Web service object definitions, when processed using a Web service client platform,
become the client interface objects that a client application accesses to interact with the Web
service.

17
OpenEdge Development: Web Services

In addition to other Web service deployment information, ProxyGen allows you to specify the
following basic features of a Web service interface:

SOAP format OpenEdge supports the deployment of a Web service definition using
any one of three SOAP formats. To support multiple client platforms, you might generate
and deploy a Web service with multiple SOAP formats by generating a separate Web
service definition for each format. Each separate WSDL definition identifies a unique Web
service, even though the underlying AppServer application is the same. When you deploy
the same Web service definition for multiple SOAP formats, you also must specify a
unique target namespace for each one in order to deploy it to the same WSA instance.
Otherwise, you must deploy the same Web service definition with different SOAP formats
to different WSA instances.

Session model This setting must match the session model supported by the AppServer
application. The session model also determines the standard object management methods
required for the Web service, and ProxyGen defines these methods according to the
session model that you choose.

For more information on how the Open Client object model supports Web service development
and on using ProxyGen to define a Web service definition, see OpenEdge Development: Open
Client Introduction and Programming. For more information on how the ProxyGen-generated
or deployed WSDL reflects the Open Client object model for Web services, see Chapter 2,
WSDL and Web Service Objects in Progress 4GL Web Services.

Web Services Adapter for administration and run-time

support
The WSA is the heart of OpenEdge support for Web services built in Progress 4GL. The WSA
is a Java Servlet provided by Progress that runs as a Web application in the context of a Java
Servlet Engine (JSE). To support Web service tools architecture for OpenEdge, the WSA serves
the following three functions:

1. Supports the deployment environment for Web service-enabled AppServer applications

and manages the deployed Web services.

2. Generates and manages WSDL files for Web services as they are deployed and makes
these WSDL files available for download by potential Web service clients.

18
 Web Services in OpenEdge

3. Directs incoming SOAP messages for client requests to specified Web services and
converts the SOAP requests to AppServer requests as defined by the Web service WSAD
file. It then converts AppServer responses to SOAP messages and returns these outgoing
response messages from the specified Web services to the Web service clients that are
waiting for them.

You can define multiple WSA server instances (Java servlets), each with different properties,
and you can deploy multiple Web services to each WSA instance. Each WSA instance then
supports the three WSA functions for its own set of Web services (see the information on WSA
configuration, Web service deployment components, and client development components in
OpenEdge Getting Started: Application and Integration Services). For example, you might
create separate WSA instances to deploy Web services that share the same SOAP format. This
can be useful when you want to deploy the same Web service application to support multiple
SOAP formats (see the information on SOAP in the Web services section of OpenEdge Getting
Started: Application and Integration Services).

For more information on WSA configuration and administration and on WSA deployment and
Web service run-time support, see OpenEdge Application Server: Administration.

Progress Explorer framework for configuration and

deployment
Within OpenEdge, the WSA is encapsulated as a server that you manage using the Progress
Explorer or the wsaman command-line utility (see the information on WSA configuration and
Web service deployment components in OpenEdge Getting Started: Application and
Integration Services). While these utilities support most WSA configuration options, you must
edit the local ubroker.properties file for your WSA installation by hand to set some WSA
configuration properties, particularly those that define WSA administration roles and their
associated access permissions. Similar to other OpenEdge servers, OpenEdge provides the
wsaconfig command-line utility to validate manual changes to the ubroker.properties file
for WSA configuration.

You can also use the Progress Explorer or wsaman to temporarily change a selected set of WSA
instance properties at run time (WSA Run-time Properties). This can be helpful for debugging
or testing certain settings before making them permanent in your WSA configuration.

19
OpenEdge Development: Web Services

You must also use Progress Explorer or wsaman to deploy Web services to a particular WSA
instance and to manage deployed Web services at run time. Each deployed Web service behaves
according to the settings of a predefined set of run-time properties. While these properties have
maintainable default values initially set for all Web services deployed to a WSA instance, you
can set and reset their values, under prescribed run-time conditions, for each Web service
individually.

For more information on WSA configuration and administration and on deploying and
configuring Web services, see OpenEdge Application Server: Administration.

Web service and server security options

OpenEdge supports a variety of security options for the WSA that can be used to control access
to its various administrative and run-time functions. Generally, these security options include:

Requiring authorization to access WSA administration functions.

Restricting WSA instance administration to a selection of authorized functions.

Requiring authorization to retrieve WSDL files.

Requiring authorization for clients to access Web services.

Enabling or disabling access to WSA administration.

Enabling or disabling client access to Web services.

Securing the data connection between a Web service and the AppServer using SSL
tunneling.

For more information on security options for managing WSA configuration and administration
and on managing access control for Web services, see OpenEdge Application Server:
Administration. For more information on how OpenEdge supports security for Progress 4GL
Web services, see OpenEdge Getting Started: Security.

110
 Web Services in OpenEdge

Documenting client programming requirements

Most Web services built with OpenEdge require client programmer documentation along with
the WSDL file in order to use the Web service interface. This information describes any special
requirements for Web service operation parameters and other requirements for Web service
binding and programming. The requirements for most input and output parameters and their
data types are based on standards supported in the WSDL file and that most Web service client
toolkits support without additional programming. However, there are some unique features of
OpenEdge support for building Web services that might be helpful or necessary for client
programmers to know in order to be successful:

Open Client object model The Open Client object model supports certain built-in
object management methods whose availability and use depends on the session model of
the Web service application and the particular type of Open Client object in use. For
example, in a session-managed application, the instantiation of each object returns a
unique ID that identifies that object and must be maintained and supplied in all method
calls on that object. In general, the client programmer needs to understand when they can
and should use these built-in methods on an object and how to use them.

SOAP format All Web service client platforms support a limited choice of SOAP
formats, often fewer than the three supported by OpenEdge. The client programmer needs
to know the SOAP format that a particular Web service uses in order to know whether their
client platform supports it. This information is certainly available in the WSDL, but it
might be helpful to know before downloading the WSDL. Also, you might provide
versions of the Web service for each supported SOAP format and identify them
accordingly.

Relational data OpenEdge allows you to build Web services that pass arrays of
complex data types as input and output parameters, thus supporting the exchange of
relational data (sometimes known as data sets, result sets, data objects, or as in Progress
temp-tables). For many 4GL-built Web services, the WSDL supplies all the schema
information required to access these relational data, particularly for static temp-tables.
However, for Web services that pass dynamic temp-tables, where the schema is not
defined at compile-time, the client programmer needs additional documentation on the
schema required to pass dynamic temp-tables as input parameters.

SOAP faults The client programmer needs to understand the format of error messages
that are returned from 4GL-built Web services.

For more information on all these requirements (and more) for programming client applications
to access Progress 4GL Web services, see Part II, Clients Accessing Progress 4GL Web
Services.

111
OpenEdge Development: Web Services

Building and deploying Progress 4GL Web services

A typical order of tasks to bring a Progress 4GL Web service from conception to
implementation include:

1. Defining client requirements

2. Preparing the AppServer application

3. Defining the Web service

4. Configuring a WSA instance

5. Deploying the Web service

6. Writing a client and testing the Web service

7. Providing the Web service to users

8. Tuning the Web service and its WSA instance

The following sections provide more information on these tasks.

Defining client requirements

The first step in building any new Web service application is to understand the requirements of
its intended clients. This can help with deciding certain details of a Web service design and
implementation, including (but not limited to):

The session model to support with a new Web service application. For more information,
see OpenEdge Application Server: Developing AppServer Applications

The types of Open Client objects to use in designing the Web service (also closely
associated with the session model of the Web service). For more information, see
OpenEdge Development: Open Client Introduction and Programming.

The SOAP formats (style and use) to support for Web service deployment. For more
information, see Chapter 2, WSDL and Web Service Objects in Progress 4GL Web
Services and Chapter 4, General Client Programming Model for Progress 4GL Web
Services.

Note: For an existing AppServer application, the requirements of intended Web service clients
are already likely to be known and reflected in the existing AppServer application.

112
 Web Services in OpenEdge

Preparing the AppServer application

Once the client requirements are known, you can design and write a new AppServer application
for a Web service, or decide whether to enable an existing AppServer application as a Web
service. You can enable the complete interface to a smaller application, or selected interface
components of a larger application, as client requirements dictate. The session model that the
AppServer must support for a new application also determines the complexity of its
programming. For information on configuring and programming AppServers, see OpenEdge
Application Server: Administration and OpenEdge Application Server: Developing AppServer
Applications.

Defining the Web service

After you have built and compiled the Progress r-code for the AppServer application, you can
use ProxyGen to prepare the application for deployment as a Web service. As you define the
Web service, your knowledge of the application and client requirements helps to decide how
best to organize and include the procedures of your application as Open Client objects and
methods. For information on how to use ProxyGen to define the Web service, see OpenEdge
Development: Open Client Introduction and Programming. ProxyGen saves the Web service
definition as a WSM file.

Configuring a WSA instance

At any time in the cycle of Web service design and development, you can create and configure
a WSA instance to host your Web service when you are ready to deploy it. Many considerations
might determine when and how you do this, such as the available server and network resources,
as well as any other requirements that you determine for deploying the Web service (for
example, support for different client SOAP formats). You also need to think carefully about
security requirements for the WSA instance and the Web services you plan to deploy to it.

Note: Creating and configuring a WSA instance is a two-step process in which you (1) use the
Progress Explorer to define and Progress Explorer or the wsaman utility to configure the
instance on the OpenEdge side, and (2) use whatever tools are available to define the
WSA instance as a Java servlet to your JSE. After completing the creation and
configuration of a WSA instance, you might have to restart the JSE to start up the Java
servlet for that instance to deploy Web services to the context of the WSA instance. See
your JSE documentation for information on the requirements for running and accessing
instances of the JSE context.

For information on how to create and configure WSA instances, see OpenEdge Application
Server: Administration.

113
OpenEdge Development: Web Services

Deploying the Web service

After you have defined the Web service and configured a WSA instance for it, you can deploy
the Web service definition to that WSA instance using Progress Explorer or the wsaman utility.

Caution: You can update a deployed Web service to change its deployment information and
object definitions. However, never update a deployed Web service that you have
enabled for live access by production clients. Instead, create a new version of the
Web service with the intended updates and deprecate the old version of the Web
service once all clients have moved to the new version.

You can also adjust the values for a variety of properties of a deployed Web service or change
the default values that are automatically assigned when you first deploy a Web service.

For more information on deploying and managing a deployed Web service, see OpenEdge
Application Server: Administration.

Writing a client and testing the Web service

Typically, the earliest that you can begin writing the code to access a Web service in a client
application is after you have obtained the WSDL file for a Web service (and any required
documentation). You can obtain this WSDL file before deployment by selecting the option to
generate it directly from ProxyGen when you first define the Web service.

However, the order in which you actually develop the client and Web service side of a complete
application solution depends on your application and the environment in which it runs. For
example, if you are writing both the client and Web service as a single application solution for
an intranet environment, you might begin developing the client side as a way of determining the
exact requirements for the Web services you need to develop.

There are also additional techniques for testing and debugging a Web service with or without
writing a client for it.

Caution: Before you begin testing a Web service, deploy it to a WSA instance that is dedicated
for Web service testing and otherwise isolated from the intended client domain. This
allows you to enable the Web service for access by clients doing preproduction
testing without making it visible and live to post-production clients. Once testing
is complete, you can redeploy or import the Web service to the context of the
production WSA instance.

114
 Web Services in OpenEdge

For more information on writing client applications for a 4GL Web service, see Part II, Clients
Accessing Progress 4GL Web Services. For more information on testing and debugging Web
services, see Chapter 7, Testing and Debugging Progress 4GL Web Services.

Providing the Web service to users

When you initially deploy a Web service, it is disabled from access by clients over the network.
This allows you to adjust Web service property values and perform other administrative tasks,
such as setting up the WSA instance to distribute the WSDL file to users, before making it
visible and accessible to the intended network clients. When the Web service is ready for
production, you can enable it for client access using an option in Progress Explorer or the
wsaman utility.

Caution: Do not make a newly deployed Web service available to production clients until you
ensure that all Web service testing, updating, and administration is complete to
support that Web service in the production client domain. (See the Writing a client
and testing the Web service section on page 114.)

For more information on when and how to enable and disable Web services for client access,
see OpenEdge Application Server: Administration.

Tuning the Web service and its WSA instance

Both during preproduction testing and full production access by real clients, you can monitor
various run-time statistics accumulated for both the WSA instance and the Web services that are
deployed to it. Over time, this will allow you to adjust WSA instance and Web service property
values to yield the best performance metrics.

Note: Remember also to monitor and tune the AppServer configurations that support your Web
services along with monitoring and tuning the Web services themselves.

For information on monitoring and tuning AppServer configurations, WSA instances, the Web
services that are deployed to WSA instances, see OpenEdge Application Server:
Administration.

115
OpenEdge Development: Web Services

Programming 4GL clients to access industry Web services

Figure 12 shows the basic industry Web services architecture, showing how a Progress 4GL
client application communicates with a Web service.

Web service
Progress 4GL
client Web service Application
provider server
SOAP processor

HTTP/S listener
4GL client logic

Client interface

Post (SOAP)

HTTP/S

Businessi Interface
Business

SOAP processor
HTTP/S listener
logic:
Response (SOAP)
Java
C#.NET
Progress

WSDL

Figure 12: Progress 4GL clients accessing Web services

As you can see, the client architecture for a Progress 4GL application accessing a Web service
mirrors the Web service provider and application server architecture. The additional
components on the 4GL client specifically for accessing Web services are indicated in a darker
gray. The WSDL file, obtained from the Web service provider describes both the logical and
physical interface required by the client to access the Web service. At the logical level,
OpenEdge uses the WSDL file to define the client interface (API) required to program calls to
Web service operations and to provide support for interpreting those operations at run time.

116
 Web Services in OpenEdge

At the physical level, OpenEdge contains its own SOAP processor to convert between calls to
4GL-defined procedures and SOAP messages understood by the Web service, and it supports
both nonsecure HTTP and SSL using its HTTP/S listener to manage the transport of these SOAP
messages across the wire.

Once the logical and physical interface to a Web service is known, you can interact with that
Web service in the 4GL in a manner very similar to interacting with a session-free AppServer.
Many of the same 4GL elements are used to support the same logical functionality. In addition,
the OpenEdge and the Progress 4GL provides functionality that allows you to handle the unique
requirements of managing a Web service request:

SOAPthe message medium

WSDL and the Web service interface

Interacting with a Web service and its operations

Handling Web service operation outputs and inputs

Handling Web service errors

Managing asynchronous requests

SOAPthe message medium

As described in OpenEdge Getting Started: Application and Integration Services, SOAP is the
protocol used to format message exchanges between Web service clients and Web services. The
industry currently considers many scenarios for Web services communications (described at
http://www.w3.org/TR/ws-arch-scenarios/). OpenEdge supports variations of the
request-response scenario.

In the request-response scenario, a client (Web service client) sends a SOAP request message
to invoke a Web service operation and the operation sends a response back to the client in the
form of a SOAP response message (for a successful invocation) or in the form of a SOAP fault
message (for an invocation that results in an error).

117
OpenEdge Development: Web Services

SOAP message document structure

SOAP messages have a common XML document structure that consists of the following
ordered elements:

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope . . . >
<soap:Header>
.
.
.
</soap:Header>
<soap:Body
.
.
.
</soap:Body>
</soap:Envelope>

These SOAP elements have the following functions:

1. Envelope (mandatory) Defines all the namespaces used in the document. Namespaces
are identifiers that provide a way to define XML elements without name conflicts. This is
important for a Web service because it must be able to define its elements uniquely across
the Internet, as well as to identify elements from other namespaces commonly used by all
Web services on the Internet, such as the namespace for the SOAP specification itself. A
namespace is typically defined by a Universal Resource Identifier (URI), usually in the
form of a Universal Resource Locator (URL) or a Universal Resource Name (URN). The
WSDL files that define Web service interfaces use namespaces in the same way (see the
WSDLan overview section on page 121).

2. Header (optional) Used to send application-specific information, such as context and

firewall information, including a standard set of attributes that describe the operation, and
one or more entry elements that contain the specific information about the application. A
good example of information passed in such a header entry is the object ID passed in the
SOAP header for Progress 4GL Web services that maintain context for a session-managed
AppServer (see Chapter 3, Session Models and Object IDs in Progress 4GL Web
Services).

118
 Web Services in OpenEdge

3. Body (mandatory) Contains data and SOAP formatting information according to the
type of message it is. So, for a:

SOAP request message The body contains the operation name and its input
parameter values.

SOAP response message The body contains any operation output parameters and
any return value for a successful request.

SOAP fault message The body contains error information for a failed request,
including a set of standard attributes sufficient to identify the error and zero or more
detail elements unique to the application that provide more complete information
about what caused the error.

With some Web services, you do not have to have any direct knowledge of SOAP message
structure to use them. These are Web services for which all the operation parameters map
directly to 4GL data type parameters. For such Web services, especially where even SOAP
faults can be ignored, you can interact with them in the 4GL without regard to SOAP message
structure. The WSDL Analyzer also reduces your need to know SOAP in depth because it
provides documentation on exactly what you need to do in the 4GL to use Web service
operations. For an example of 4GL interaction with such a service, see the Interacting with a
Web service and its operations section on page 124.

Many of the more complex Web services require direct 4GL interaction with the underlying
XML in each SOAP message, in addition to any mapping of Web service parameters directly to
4GL data types. The Progress 4GL supports access to XML with an implementation of the
Document Object Model (DOM) and Simple API for XML (SAX). For more information this
XML support, see OpenEdge Development: Programming Interfaces. For more information on
when and what you need to do to access the XML for SOAP request and response messages,
see the Handling Web service operation outputs and inputs section on page 129.

Also, if you must handle the SOAP faults returned from a Web service request, you might need
to access the underlying XML for the SOAP fault. For more information on when and what you
need to do to access the underlying XML for a SOAP fault, see the Handling Web service
errors section on page 132.

119
OpenEdge Development: Web Services

SOAP message formats

SOAP messages can be generated using several different formats, depending on the
communications scenario. OpenEdge supports request-response scenarios that use the
following SOAP formats:

RPC/Encoded

RPC/Literal

Document/Literal

To hide the details of these SOAP formats, OpenEdge provides the WSDL Analyzer. This
utility reads a WSDL file and translates the Web service interface definition into a 4GL interface
that you can use to access the Web service. Generally, when writing a Web service client in the
4GL, especially if you use the WSDL Analyzer (see the OpenEdge WSDL Analyzer section
on page 124), you have no need to know the SOAP message format of the Web service you
are using. However, if the Web service that you choose supports a different SOAP format than
those supported by OpenEdge, the analyzer indicates that OpenEdge cannot support the Web
service.

WSDL and the Web service interface

Most Web service providers publicize and describe the public interface to their Web services
using WSDL. OpenEdge requires that you have access to a valid WSDL file that describes the
Web service you need to access. The WSDL file that you obtain from the Web service provider
provides accurate information on the Web service interface, including the interface definition
of Web service operations and the precise binding requirements to physically access the Web
service on the network from your 4GL application. For more information on WSDL and Web
services architecture, see the sections on OpenEdge support for Web services in OpenEdge
Getting Started: Application and Integration Services. The following sections provide an
overview of WSDL and how OpenEdge makes use of WSDL to make accessing Web services
easier from the 4GL.

Note: Web services do not generally require that you have a WSDL file to access them.
However, the Progress 4GL does require this file for both development and run-time
access to the Web service.

120
 Web Services in OpenEdge

WSDLan overview

If you have built Web services in the 4GL, you might already be familiar with the basic structure
of a WSDL file and how OpenEdge uses it to define 4GL Web services (see Chapter 2, WSDL
and Web Service Objects in Progress 4GL Web Services). This section describes a WSDL file
more generically, as it might define any Web service you might want to access from the 4GL.

Note: Accessing some Web services requires little, if any, knowledge of WSDL. However, for
complex Web services, you must have a basic understanding of WSDL to make full use
of the Web service and to access its data appropriately.

A single WSDL file describes a single Web service and contains a series of major sections that
define features of the Web service interface, from data and operations to the binding information
needed to access the Web service on the network. Each section is defined by a corresponding
WSDL element.

Table 11 lists and describes these major WSDL sections in the order that they appear in a
WSDL file.

Note: This information is similar to the description of WSDL file sections provided for
Progress 4GL Web services (see Chapter 2, WSDL and Web Service Objects in
Progress 4GL Web Services). However, Table 11 describes the WSDL sections from
a more general perspective. The WSDL files that you see in the industry do not
necessarily define Web services in the same way that OpenEdge uses them to define
4GL Web services.

121
OpenEdge Development: Web Services

Table 11: WSDL sections overview (1 of 2)

Section Description

Definitions Defined by one occurrence of the <definitions> element. This section

identifies the Web service, defines all valid namespaces for the WSDL file,
and encapsulates all other WSDL sections. Each Web service has a unique
namespace (target namespace) defined by the targetNamespace attribute of
the <definitions> element.

Types Defined by one occurrence of the <types> element. This section provides
data type definitions used to describe the messages exchanged between a
Web service and the Web service client. These data type definitions
typically use the XML Schema specification.

Messages Defined by one or more <message> elements. Each <message> element

consists of multiple logical parts, consisting of the message name and the
message parts. The message name is a unique name that identifies the
message. The message parts specify the part names and data types.

Port types Defined by one or more <portType> elements. Each <portType> element
defines a set of abstract operations (one <operation> element for each
operation) and the abstract messages (operation parameters) involved. Each
port type is uniquely named among all port types defined within the WSDL
file.

122
 Web Services in OpenEdge

Table 11: WSDL sections overview (2 of 2)

Section Description

Bindings Defined by one or more <binding> elements. This section specifies how the
client and Web service exchange messages for each operation (<operation>
element).
Each binding element contains information that specifies the protocol by
which the client accesses the Web service. OpenEdge supports the SOAP
protocol, which specifies a message protocol that includes an envelope,
header, and body.
For SOAP, the binding information includes a transport attribute that
identifies the transport protocol used by the binding. OpenEdge supports the
transport protocols, HTTP and HTTPS (HTTP/S).
A SOAP binding also identifies a format used for each operation to
exchange messages, indicated by the style and use attributes. OpenEdge
supports the message formats named style/use respectively as:
RPC/Encoded
RPC/Literal
Document/Literal
Each <binding> element corresponds to a previously-defined <portType>
element, specifying appropriate information about the same set of
operations. As described for port types, a <portType> element defines the
abstract elements of each operation, the parameters and their data types that
the client must interact with at the logical level. The corresponding
<binding> element defines the physical details of how messages for these
same operations are exchanged over the network.
Note: The message style also has an effect on how the Messages and Types
sections relate to each other to define messages for operation
parameters.

Services Defined by zero or more occurrences of the <service> element. This is an

optional section that defines a collection of related endpoints (ports). Each
<service> element is uniquely identified within this section of the WSDL
file by a name and can contain several <port> elements. Each <port>
element specifies a binding and a location at which that binding's operations
can be accessed by the Web service client.
Note that a Web service is identified by a combination of a single binding
and endpoint. If no <service> elements exist in the WSDL file, the Web
service client must obtain a valid endpoint, typically in the form of a URL,
where the operations for each binding can be accessed on the Internet.

123
OpenEdge Development: Web Services

For more information on how to use the WSDL file to help program the 4GL interface to a Web
service, see Chapter 8, Analyzing WSDL for Progress 4GL Access to Web Services. For
complete information on WSDL and its meaning, see the official WSDL specification at the
following URL:

http://www.w3.org/TR/wsdl

OpenEdge WSDL Analyzer

OpenEdge makes accessing Web services from the 4GL much easier by providing a utility (the
WSDL Analyzer) that can read the WSDL file and produce a reference guide that documents
exactly how to use the 4GL to access the Web service. This guide is a series of HTML
documents with hyperlinks that clearly define all Web service operations and their 4GL
interfaces, including how complex Web service data types are represented in the WSDL. It also
provides the binding information necessary to access the Web service on the Internet. Finally,
it includes any internal WSDL file comments as documentation from the Web service provider.

To make use of the OpenEdge features that allow you to access a Web service at run time, the
client application must have access to a current WSDL file for the Web service you want to use.
Using the reference output is optional, but highly recommended to most effectively structure
your code to access the Web service. The way OpenEdge interprets the run-time invocation of
Web service operations is consistent with the WSDL Analyzer processing to produce its
reference documentation. For an example of how the WSDL Analyzer can help you to program
your 4GL interaction with a Web service, see the Interacting with a Web service and its
operations section on page 124. For more information on WSDL, how the 4GL maps Web
services based on WSDL, and how you can use the WSDL Analyzer to help you write the
necessary 4GL, see Chapter 8, Analyzing WSDL for Progress 4GL Access to Web Services.

Interacting with a Web service and its operations

The general procedure for accessing a Web service to invoke its operations is similar to
accessing a session-free AppServer and invoking its remote procedures and user-defined
functions, with some variation. For information on accessing a session-free AppServer, see
OpenEdge Application Server: Developing AppServer Applications.

124
 Web Services in OpenEdge

AppServer and Web service access compared

Table 12 lists and compares the 4GL elements used for session-free AppServer access and
Web service access, listed in rough order of use.

Table 12: AppServer and Web service access compared

Session-free AppServer clients Web service clients

use the... use the...

Server object handle to access the Server object handle to access the Web
AppServer application service. service.

CONNECT( ) method on the server handle to CONNECT( ) method on the server handle to
logically connect (bind) the server object to logically connect (bind) the server object to
the application service. the Web service.

RUN statement to instantiate a remote RUN statement to access a port type in the
persistent procedure on an AppServer and Web service and map it to a Web service
map it to a proxy persistent procedure proxy procedure handle.
handle.

RUN statement and the proxy persistent RUN statement and the Web service proxy
procedure handle to execute an internal procedure handle (Web service procedure
procedure of the remote persistent object) to invoke an operation of the port
procedure. type as a remote internal procedure.
Note: All Web service operations can be
invoked as remote internal
procedures, allowing them to be
invoked asynchronously. However,
some Web service operations can
also be invoked as remote
user-defined functions.

FUNCTION prototype statement with the FUNCTION prototype statement with the Web
proxy procedure handle and function service proxy procedure handle, and
invocation to return the value of a remote function invocation to return the value of a
user-defined function. Web service operation that the WSDL
Analyzer indicates can be invoked as a
function.

NO-ERROR option and the ERROR-STATUS NO-ERROR option and the ERROR-STATUS
system handle to trap 4GL statement errors. system handle to trap 4GL statement errors
and Web service SOAP faults.

125
OpenEdge Development: Web Services

Table 12: AppServer and Web service access compared

Session-free AppServer clients Web service clients

use the... use the...

Asynchronous request object handle to Asynchronous request object handle to

manage asynchronous execution of remote manage asynchronous invocation of Web
4GL procedures. service operations.

DISCONNECT( ) method on the server handle DISCONNECT( ) method on the server handle
to logically disconnect (unbind) the server to logically disconnect (unbind) the server
object from the application service. object from the Web service.

DELETE object statement to delete object DELETE object statement to delete object
handles that are no longer needed. handles that are no longer needed.

Basic Web service access cycle

As you can see from Table 12, you can access a Web service using the same basic 4GL element
framework used to access a session-free AppServer. The following sample code shows a
working 4GL program that accesses the TemperatureService Web service. This is an actual
public Web service whose WSDL file is available at the following location on the Internet:

http://www.xmethods.net/sd/2001/TemperatureService.wsdl

Note: While this is the URL to an actual Web service at this time of writing, the URL or
availability of any public Web service can change at any time.

126
 Web Services in OpenEdge

Sample Web service access

This is a simple Web service that allows you to get the current temperature for a United States
zip code (hard-coded in the example). Here is the 4GL program that accesses it, with numbered
comments (such as, /*2*/ or /*7*/) corresponding to the ordered description that follows:

DEFINE VARIABLE hWeatherWS AS HANDLE. /*1*/

DEFINE VARIABLE hPortType AS HANDLE.
DEFINE VARIABLE cTemp as CHARACTER.

CREATE SERVER hWeatherWS. /*2*/

hWeatherWS:CONNECT /*3*/
("-WSDL 'http://www.xmethods.net/sd/2001/TemperatureService.wsdl'").

RUN TemperaturePortType SET hPortType ON SERVER hWeatherWS NO-ERROR. /*4*/

RUN getTemp IN hPortType (INPUT "01730", OUTPUT cTemp). /*5*/

MESSAGE "The temperature is: " cTemp VIEW-AS ALERT-BOX.

DELETE PROCEDURE hPortType. /*6*/

hWeatherWS:DISCONNECT(). /*7*/
DELETE OBJECT hWeatherWS. /*8*/

This code:

1. Creates two handles and a variable to receive Web service output:

hWeatherWS To be used as the server object handle for the Web service.

hPortType To be used as the Web service proxy procedure handle to map the port
type that contains the requested Web service operation.

cTemp To receive the current temperature value for the given zip code.

2. Creates the server object on hWeatherWS to use for binding the Web service.

3. Logically binds the Web service to the server object using the CONNECT( ) method, which
specifies:

The location of the Web service WSDL file for run-time access.

The physical service and port (endpoint) through which all communications pass
between the 4GL client and the Web service.

127
OpenEdge Development: Web Services

In this example, no service and port are is explicitly specified because there is only one
valid service and port in the WSDL file. For information on the full range of binding
options for Web services, see the Chapter 9, Connecting to Web Services from the
Progress 4GL.

4. Using the RUN statement syntax, creates the Web service proxy procedure object and maps
it to the port type (TemperaturePortType) that defines the getTemp operation for the Web
service.

5. Invokes the getTemp operation as a procedure for the ZIP code location input as "01730"
and the temperature at that location output as cTemp and displayed in a message. For more
information on mapping Web service port types and invoking operations on them, see the
Chapter 10, Invoking Web Service Operations from the Progress 4GL.

6. Deletes (cleans up) the hPortType procedure object, using the DELETE PROCEDURE
statement, after it is no longer needed.

7. Unbinds the Web service from the hWeatherWS server object using the DISCONNECT( )
method on the hWeatherWS server handle.

8. Deletes (cleans up) the hWeatherWS server object, using the DELETE OBJECT statement,
after it is no longer needed.

Note: At this point, the program can use the same hWeatherWS server object to bind to
another Web service or another binding for the same Web service, perhaps to return
humidity or wind speed at a zip code location using a different port type. If it is
completely finished accessing Web services and AppServers, but has more work to
do, it might clean up by deleting the hWeatherWS server object using the DELETE
object statement.

For more information on managing Web service bindings, see the Chapter 9, Connecting
to Web Services from the Progress 4GL.

This sample shows the similarity between basic AppServer and Web service access using
synchronous interaction with the client. Another common feature between client interaction
with an AppServer and client interaction with a Web service is the ability to invoke procedures
asynchronously. For information on when and what you need to do to invoke Web service
requests asynchronously, see the Managing asynchronous requests section on page 133.

128
 Web Services in OpenEdge

WSDL Analyzer as the client interface source

All of the information for writing the code in the previous example is likely to be found in the
WSDL file used to bind the Web service at run time (often accessed directly from the WSDL
URL location). If you run the WSDL Analyzer on the WSDL file to generate the interface
documentation, it generates a hyperlinked document contain information on how to connect to
and invoke operations in the Web service, such as the:

Connection parameters for the CONNECT( ) method.

Name of a Web service port type.

Prototypes for 4GL procedures and user-defined functions used to invoke Web service
operations for a given port type.

Any complex types defined for use in Web service operation parameters.

Other information required to use the Web service, such as the way Web service errors
(SOAP faults) are returned to the client.

For more information on running the WSDL Analyzer and the documentation that it generates,
see Chapter 8, Analyzing WSDL for Progress 4GL Access to Web Services.

Handling Web service operation outputs and inputs

A Web service provides two basic means of exchanging information between a client and the
Web service:

Passing strongly typed data through the parameters of its operations.

Passing information in the header of each SOAP request and response message with
varying degrees of structure and typing.

For both types of information exchange, it may be necessary to access the XML of the
underlying SOAP message in order to complete the necessary exchange of information. The
following sections describe when you might need to do this and the 4GL facilities that you can
use.

129
OpenEdge Development: Web Services

Handling complex operation parameters

As shown in the previous sample (see the Basic Web service access cycle section on page
126), the WSDL Analyzer provides sufficient documentation to code a 4GL application as a
Web service client. Often, the input, output, and return parameters of Web service operations
can be mapped from their XML Schema types directly to 4GL data types. When this is the case,
handling the data for Web service requests is no more challenging than for an AppServer remote
procedure call. The 4GL provides recommended and alternative mappings between all basic
XML Schema data types and the data types of the 4GL. If for any reason OpenEdge is unable
to map the Web service parameter and corresponding 4GL parameter, it generates a run-time
error. For information on the 4GL data type mappings to XML Schema and how they are
supported in this release of OpenEdge, see Chapter 8, Analyzing WSDL for Progress 4GL
Access to Web Services.

For more complex data interactions, where a Web service parameter is itself an aggregate of
more than one XML Schema data type (known as a complex type), you must directly access and
interpret the XML for the parameter yourself. You can do this by converting between the string
representation of the serialized XML parameter and a parsed representation, such as provided
using the Document Object Model (DOM) or Simple API for XML (SAX) parser, both
supported in the 4GL (see OpenEdge Development: Programming Interfaces). For more
information on XML complex types and how OpenEdge maps them to the 4GL, see Chapter 8,
Analyzing WSDL for Progress 4GL Access to Web Services. For more information on how
to work with complex types for Web service input and output parameters, see Chapter 10,
Invoking Web Service Operations from the Progress 4GL.

Handling the information in SOAP headers

Some Web services require that you pay attention to the content of the SOAP header in the
SOAP request message, the SOAP response message, or both messages for an operation. This
can be a simple task or a complex one, depending on the Web service and its application
requirements. OpenEdge supports either situation by giving you access to the content of the
SOAP header of any SOAP request or response message.

For a SOAP request message, you can access the SOAP header at a point just after invoking the
Web service operation and just prior to when OpenEdge sends the message to the Web service.
For a SOAP response message, you can access the SOAP header after the message arrives at
your Web service client and just prior to when OpenEdge returns the results of any operation
output and return parameters to your 4GL program.

130
 Web Services in OpenEdge

Progress callbacks and callback procedures

The 4GL allows you to set a Progress callback for either or both of the SOAP request and
response messages exchanged as part of a Web service operation. A Progress callback specifies
an internal procedure that you make available for the calling context to execute as part of a core
Progress action, in this case, sending or receiving a SOAP message. The specified internal
procedure (callback procedure) provides access to the SOAP header at an appropriate point for
a request or response message, depending on the type of callback. From within callback
procedure you can access the SOAP header using the required procedure parameter and alter the
content as allowed by the type of callback.

For more information on setting up SOAP header callback procedures, see Chapter 10,
Invoking Web Service Operations from the Progress 4GL.

SOAP header and SOAP header-entryref objects

A SOAP header is a container for other elements known as SOAP header entries. To access a
SOAP header and its SOAP header entries, the 4GL provides two objects: a SOAP header
object, which provides access to the header and its header entries, and a SOAP header-entryref
object that references a given SOAP header entry and its attributes. To inspect or modify the
actual content of a SOAP header entry, you must access its underlying XML. The 4GL allows
you to access the header entry XML either as a serialized XML string or as a DOM tree, much
like you access a complex type parameter (see the Handling complex operation parameters
section on page 130). Using 4GL elements that manipulate DOM trees, you can create a SOAP
header to use for an outgoing SOAP request message, inspect a SOAP header for an incoming
SOAP response message to save header entry values, or modify the SOAP response header for
use as a SOAP request header during invocation of a following Web service operation.

For information on using callbacks to work with these headers for each type of SOAP message,
see Chapter 11, Handling SOAP Message Headers in the Progress 4GL.

131
OpenEdge Development: Web Services

Handling Web service errors

As with invocation of any 4GL statement, invoking a Web service operation can raise an ERROR
condition that you can handle in exactly the same way as an other 4GL statement error. The
ERROR condition from a Web service request can result from one of three basic causes:

1. A SOAP fault returned by the Web service.

2. A 4GL internal error raised by OpenEdge.

3. An error intentionally raised by the 4GL application (using the RETURN ERROR statement)
in one of the following procedures:

SOAP request header callback procedure.

SOAP response header callback procedure.

The features of SOAP header callback procedures can add complexity to the error handling for
Web service requests. For more information on managing errors for Web service requests, see
Chapter 12, Handling Errors in Progress 4GL Requests to Web Services.

SOAP fault errors

For a SOAP fault, you start out by handling the ERROR condition as usual in the 4GL, whether it
is:

Following the invocation of a synchronous Web service request.

In the event procedure of an asynchronous Web service request.

If the Web service returns a SOAP fault from an error detected while processing a Web service
request, OpenEdge receives the SOAP fault and turns it into a Progress error message. If the
statement that invoked the request includes the NO-ERROR option, OpenEdge also attaches the
error message to the ERROR-STATUS system handle.

You can identify this error as a SOAP fault by the content of this message (using the
GET-MESSAGE( ) method) and also by examining the object referenced by the
ERROR-OBJECT-DETAIL attribute on the ERROR-STATUS handle. If the error resulted from a SOAP
fault, this attribute references a SOAP fault object, which in turn references an optional SOAP
fault-detail object, depending on the Web service application.

If there is no SOAP fault-detail object, you can get all the information available on the SOAP
fault from the remaining attributes of the SOAP fault object and the methods of the
ERROR-STATUS system handle.

132
 Web Services in OpenEdge

If there is a SOAP fault-detail object, it likely stores more information about the SOAP fault in
XML defined by the Web service. You can access this XML in much the same way you access
the XML for a SOAP header entry (see the Handling the information in SOAP headers section
on page 130). That is, you can obtain this SOAP fault information as a serialized XML string
or as a DOM tree that you interpret as required, much like accessing a complex Web service
parameter (see the Handling complex operation parameters section on page 130).

For more information on using the ERROR-STATUS system handle, the SOAP fault object handle,
and SOAP fault-detail object handle to manage SOAP faults, see Chapter 12, Handling Errors
in Progress 4GL Requests to Web Services.

4GL internal errors

You can handle an internal ERROR condition raised for invocation of a 4GL statement as usual
by trapping it with the ON ERROR option or inspecting the ERROR-STATUS system handle directly
after invoking the request with the NO-ERROR option.

Errors raised by the application

Within a SOAP header callback procedure you can invoke the RETURN ERROR statement as
though it were part of the 4GL statement that generated the request so it can be trapped using
standard 4GL error handling. However, for an asynchronous Web service request, an unhandled
internal error or RETURN ERROR statement invoked in the SOAP response header callback
procedure is propagated from the callback to the event procedure, rather than the point
following invocation of the asynchronous request (see the Managing asynchronous requests
section on page 133).

One reason to invoke RETURN ERROR in a SOAP header response callback procedure is to
respond to a SOAP header fault. You must determine that there is an error in the header of a
SOAP response message by inspecting the header XML. OpenEdge does not otherwise detect
a SOAP header fault returned from a Web service.

Managing asynchronous requests

As indicated previously, you can invoke Web service requests asynchronously from the 4GL.
This means that you can invoke a Web service request in such a way that the result is handled
independently of the mainline flow of execution. That is, 4GL statements following the
asynchronous request execute immediately and in order without waiting for the result of the
asynchronous request to be available. Instead, the asynchronous request specifies an internal
event procedure to handle the result when the result for that asynchronous request becomes
available, which is signalled by the activation of a PROCEDURE-COMPLETE event.

133
OpenEdge Development: Web Services

When it is time to handle the PROCEDURE-COMPLETE event, the specified event procedure
executes and manages any OUTPUT or INPUT-OUTPUT parameters that were passed to the
asynchronous request when it was invoked. These parameters are returned as INPUT parameters
to the event procedure, which can store the parameter values or otherwise process the result for
use by the mainline program. The mainline program can periodically inspect an asynchronous
request object handle (also available to the event procedure), which it sets during invocation of
the request, in order to determine if the specified asynchronous request has completed. If the
request has completed, the program can then make use of the results as provided by the internal
event procedure that handled them.

The model for asynchronous Web service request invocation is very similar to the model for
asynchronous remote procedure invocation on a session-free AppServer. However, the two
models are not exactly the same and have some differences. This section describes how the two
models differ as well as their basic similarities. For information on the model for invoking
asynchronous requests on a session-free AppServer, see OpenEdge Application Server:
Developing AppServer Applications.

Note: For certain features that support Web service requests in the 4GL (for example, error
handling), the feature behavior might differ depending on whether the request is
synchronous or asynchronous. The documentation describes these differences in the
chapters where the features are described.

Supported asynchronous Web service requests

You can only invoke an asynchronous Web service request as a procedure using the RUN
statement. This means that if a Web service operation is invoked as a user-defined function, you
can only invoke it synchronously, because all operations that have a return value can only be
invoked as user-defined functions, where the value must be made available at the point of
invocation. This is consistent with how OpenEdge supports the invocation of asynchronous
requests on the AppServer (remote procedures only).

Order of completion

Similar to a session-free AppServer request, the order of completion for an asynchronous Web
service request is determined solely by the Web service. The manner in which the 4GL client
send and response queues for an asynchronous request handle messages is identical for both
session-free asynchronous AppServer requests and asynchronous Web service requests. That is,
if the 4GL invokes multiple asynchronous Web service requests, the order of their completion
cannot be determined on the Web service or session-free AppServer client. So, you must write
your mainline program, and indeed your asynchronous event procedures, to make no
assumptions about the order in which multiple asynchronous Web service requests complete.

134
 Web Services in OpenEdge

A subtle distinction between a session-free asynchronous AppServer request and an

asynchronous Web service request is the SOAP response callback procedure available for the
Web service request (see the Handling the information in SOAP headers section on page
130). If a SOAP response callback procedure is set for an asynchronous Web service request,
it executes after the SOAP response message arrives at the client but before the asynchronous
event procedure executes to handle the PROCEDURE-COMPLETE event for the request.

Asynchronous request object handle

OpenEdge maintains an asynchronous request object for each asynchronous request, which
maintains the status of the request, including whether and how it has completed (successfully or
unsuccessfully). The handle to this asynchronous request object is available to the mainline
program and to the event procedure for an asynchronous Web service request in the same way
as for an asynchronous AppServer request. The Web service server object handle maintains its
own chain of pending asynchronous request object handles (FIRST-ASYNC-REQUEST and
LAST-ASYNC-REQUEST attributes), and the PROCEDURE-NAME attribute on each asynchronous
request object handle returns the name of its Web service operation as it returns the name of the
remote procedure executed for an asynchronous AppServer request.

Table 13 shows attributes on the asynchronous object handle with special meaning for Web
services.

Table 13: Attributes on Web service asynchronous request object handle

(1 of 2)

Attribute Meaning for Web service requests

ERROR Returns TRUE within the context of the event procedure when:
You invoke the RETURN ERROR statement within the
context of an associated SOAP response header callback
procedure.
A SOAP fault is returned for the asynchronous Web
service request.

NEXT-SIBLING and Maintains a chain of asynchronous request object handles for

PREV-SIBLING all pending asynchronous requests invoked in the same Web
service.

PERSISTENT-PROCEDURE Returns a handle to the procedure object bound to the Web

service port type.

PROCEDURE-NAME Returns the name of the Web service operation invoked

asynchronously.

135
OpenEdge Development: Web Services

Table 13: Attributes on Web service asynchronous request object handle

(2 of 2)

Attribute Meaning for Web service requests

QUIT Always returns FALSE for an asynchronous Web service

request.

SERVER Returns a handle to the server object for the Web service where
the asynchronous request is executed.

Results handling

A few differences exist in the results returned for an asynchronous Web service request
compared to an asynchronous AppServer request, as shown in Table 14.

Table 14: Results for asynchronous Web service requests

4GL result elements Web service request result

ERROR-STATUS system handle If the ERROR attribute of the asynchronous request object
handle is set to TRUE because of a SOAP fault, the
ERROR-STATUS:ERROR-OBJECT-DETAIL attribute
references a SOAP fault object with information on the
SOAP fault (see the Handling Web service errors
section on page 132).

RETURN-VALUE function The value for 4GL RETURN-VALUE function is never

altered directly by the response from a Web service
asynchronous request.

STOP condition The client can raise the STOP condition by executing the
CANCEL-REQUESTS( ) method on the Web service server
object handle. All outstanding Web service requests are
handled in a similar manner to those on an AppServer,
except that for any currently executing Web service
requests, the result is undefined. OpenEdge disconnects
from all ports to currently executing Web service
requests, and the exact response depends on how the
Web service responds to the lost connection.

136
 Part II
Clients Accessing Progress 4GL Web
Services

Chapter 2, WSDL and Web Service Objects in Progress 4GL Web Services

Chapter 3, Session Models and Object IDs in Progress 4GL Web Services

Chapter 4, General Client Programming Model for Progress 4GL Web Services

Chapter 5, Sample Code with SOAP Messages for Progress 4GL Web Services

Chapter 6, Sample Progress 4GL Web Services and Client Applications

Chapter 7, Testing and Debugging Progress 4GL Web Services

 2
WSDL and Web Service Objects in
Progress 4GL Web Services

This chapter describes how Open Client objects are represented as Web service objects in the
WSDL for 4GL Web services and some of the requirements for access 4GL Web services using
WSDL as outlines in the following sections:

Requirements for accessing Web services

Getting a WSDL file

WSDL file overview

SOAP message formats

WSDL element overview

OpenEdge Development: Web Services

Requirements for accessing Web services

For a client application to access a Web service, it must be able to read and write SOAP
messages that are transported over HTTP. To accomplish this, you (as the client developer)
must first obtain a WSDL file that describes the Web service, then use one of the following
techniques to create client code that can access the Web service over the network:

Read the WSDL file to identify the specified Web service operations, then code the client
application to directly create, send, and receive the SOAP messages over HTTP required
to invoke and handle the responses from these operations. Even with the help of SOAP and
HTTP libraries, this requires complex coding for simple operations.

Provide the WSDL file as input to a client development tool that generates a client
interface, which shields you from many of the complexities of HTTP and SOAP. A client
interface provides the native language API required by the client application to access the
Web service. It contains callable units of code written in the client development language
that ultimately invoke the operations specified in the WSDL. The code in this interface
knows how to create, send, and receive the SOAP over HTTP required to invoke and
handle the responses from these operations. Using the client interface, you only need to
code the client application to invoke these operations in the development language, with
minimal regard for the underlying SOAP management that the interface provides.

In either case, you will also need to consult any user documentation provided by the Web
service application developer that explains the programming model for the Web service and
how to access its operations.

22
 WSDL and Web Service Objects in Progress 4GL Web Services

Getting a WSDL file

The Web service deployer can make the WSDL for a Web service available in many possible
ways, including (but not limited to):

Hosting it with a WSA to which it is deployed using the Web services tools.

Using e-mail to distribute it.

Posting it on a Web server.

Hosting it in a UDDI directory.

While the Web service developer can use any available technique to provide a
Web-services-tools-defined WSDL file, they can host the file on a network using a WSA by
deploying the Web service using the Web services tools. This deployed WSDL file resides at a
URL determined by the WSA installation and other information specified for the Web service
at deployment. Once the Web service is deployed, the WSA administrator can make the WSDL
available by enabling access to WSDL listings on the network. For more information on Web
service deployment, see the Web service chapters of OpenEdge Application Server:
Administration.

To obtain a WSDL file deployed to a WSA instance, you can download it over the network
through its URL, specified using the following syntax:

Syntax

http[s]://host:port[/web-server-context]/wsa-webapp-context/wsa-instance/
wsdl?targetURI=web-service-name

Note: The syntax is case sensitive.

For example, here is a WSDL retrieval URL for a Web service with the friendly name,
OrderInfo, that is deployed to a WSA instance (wsa1) running in the WSA Web application
context (wsa):

http://servicehost:80/wsa/wsa1/wsdl?targetURI=OrderInfo

23
OpenEdge Development: Web Services

For more information on the syntax of the WSDL retrieval URL, see the chapters on the WSA
in OpenEdge Application Server: Administration.

Note: As an aid for developing client code to test Web services under development, the Web
service developer can optionally generate a WSDL file from ProxyGen when generating
versions of the Web service definition prior to deployment. This file is written to the
generation output directory specified in ProxyGen and can be used to create client
interface prototypes for reference during test development. For more information, see
OpenEdge Development: Open Client Introduction and Programming.

WSDL file overview

During Web service deployment, the WSA generates one WSDL file that defines one or more
Web service objects. These Web service objects conform to the Open Client object model, and
include a single AppObject, zero or more SubAppObjects, and zero or more ProcObjects to
describe the Web service. They include all operationsprocedures, user-defined functions, and
built-in operations for object managementthat define the Web service interface, depending on
the Web service object and session model. The WSDL file might also define an object identifier
(object ID) for each Open Client object. The WSDL defines this object ID for most Open Client
object types, depending on the session model.

For more information on the Open Client object model and its architecture, see OpenEdge
Development: Open Client Introduction and Programming. For more information on how
object IDs are used in different session models, see Chapter 3, Session Models and Object IDs
in Progress 4GL Web Services. For more information on how the Open Client object model
supports Web services built using OpenEdge, see Chapter 4, General Client Programming
Model for Progress 4GL Web Services.

Object representation
WSDL does not have an inherent concept of objects for encapsulating operations. However,
Progress 4GL Web services follow common usage in representing each Web service object
within a unique namespace of the WSDL file. Typically, interface generators code each such
object defined in the WSDL file as a corresponding object in the client interface. However, the
interface generator on a particular client platform ultimately determines how each WSDL object
is represented in the client development language.

24
 WSDL and Web Service Objects in Progress 4GL Web Services

Object binding
In addition to defining the Web service interface, the WSDL file also specifies how this
interface is bound to the application server that executes the operations of the Web service. For
Progress 4GL Web services, this binding information specifies how to generate and handle
SOAP messages exchanged over HTTP between the client and WSA instance that manages the
Web service. This includes information to identify the Web service and its WSA instance, as
well as to format and send the SOAP messages. The Web service deployer specifies this binding
and implementation information (deployment information) during Web service deployment.

Deployment information
This deployment information consists of the data stored in WSDL elements as follows:

Web service namespace A namespace used to uniquely identify the Web service to the
WSA instance where the Web service is deployed. In the WSDL, this value is specified by
the targetNamespace attribute of the <definitions> element. It is typically specified as
a Universal Resource Identifier (URI), usually in the form of a Universal Resource
Locator (URL) or Universal Resource Name (URN). The value can be specified in
ProxyGen, during Web service definition, or in Progress Explorer, during Web service
deployment.

WSA URL The URL for the WSA instance where the Web service is deployed, and
that forms the root for all URLs that access the Web services it manages. In the WSDL,
this is specified by the location attribute of the <soap:address> element within the
<services> element.

SOAP action A string (if specified) that the client application must place in the
SOAPAction HTTP header when it invokes operations on the Web service. In the WSDL,
this value is specified using the soapAction attribute of the <soap:operation> element,
and the value is included in the SOAPAction header of all HTTP messages that transport
SOAP messages for the Web service.

The SOAPAction HTTP header is normally 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 specified at deployment that is required by the
intervening security servers on the network.

25
OpenEdge Development: Web Services

SOAP format Two string values that specify the format of SOAP messages exchanged
between the client and the Web service. In the WSDL, these are specified by the style
attribute in the <soap:binding> and <soap:operation> elements, and by the use attribute
in the <soap:header>, <soap:body>, and <soap:fault> elements. While these values are
specified in many places within the WSDL, the same style and use values are used
everywhere in the file, ensuring that all SOAP messages generated for the Web service use
the same SOAP format. For more information on SOAP formats, see the SOAP message
formats section on page 26.

For more information on specifying this deployment information in a WSDL, see OpenEdge
Development: Open Client Introduction and Programming for the optional WSDL typically
used for development testing, and see the Web service deployment chapters in OpenEdge
Application Server: Administration for the WSDL deployed to a WSA instance. For more
information on how the WSDL file specifies this information, see the WSDL element
overview section on page 29.

SOAP message formats

The OpenEdge implementation of Web services uses the request/response model for invoking
and handling the results from operations on the Web service. The client sends a request message
to the Web service, and the Web service returns a response message back to the same client.

Usually, client interfaces expose this request/response pair as a single object method. When the
client executes the method, the underlying interface sends a SOAP request message containing
any method input parameters and receives a SOAP response message containing any method
output parameters and any return value.

26
 WSDL and Web Service Objects in Progress 4GL Web Services

Style and use attributes

The WSDL file can represent SOAP requests and responses in several different ways.
Specifically, the style attribute can have the value "rpc" or "document" and the use attribute
can have the value "encoded" or "literal".

Table 21 summarizes how each value affects SOAP message format.

Table 21: WSDL style and use attributes (1 of 2)

WSDL/SOAP
attribute Value Description

style "rpc" RPC A communications style that sends request

messages and response messages using a remote procedure
call (RPC) model. The input message contains the name of
the WSDL operation and the input parameters. The output
message contains any return value and any output
parameters.

"document" Document A communications style that sends and

manages messages using an arbitrary XML document
model that does not impose any particular communications
model on the messages. Thus, there is no standard
convention for whether and how messages are sent or
received. The communications model (request and
response, or one-way) is specified in XML Schema
definitions contained within the WSDL or in a separate
schema.
Note: The Progress 4GL Web services Document style
always specifies a request/response schema in the
WSDL.

27
OpenEdge Development: Web Services

Table 21: WSDL style and use attributes (2 of 2)

WSDL/SOAP
attribute Value Description

use "encoded" Encoded A message formatting scheme that uses a set

of rules to encode the data in the body of the message. The
message itself does not conform to a particular schema, but
the rules are indicated by an encoding namespace specified
in the WSDL.
Note: The encoding scheme used by the Progress 4GL
Web services (and most client platforms) is SOAP
encoding, a message encoding scheme defined by
the SOAP standard.

"literal" Literal A message formatting scheme in which the

body of the message conforms to a specific XML Schema
that is specified in the WSDL.

In practical terms, there is little difference between using RPC or Document style when
exchanging request/response messages, as is typical with Web services. The most significant
difference in message structure is in the choice of use, Encoded (SOAP encoding) or Literal.
SOAP encoding allows for a simpler representation of complex, object-oriented data structures
than is possible with Literal encoding. However, Document/Literal messages have the
advantage that they can be validated by XML Schema.

28
 WSDL and Web Service Objects in Progress 4GL Web Services

SOAP formats supported by Progress 4GL Web services

Most Web service message formats pair Document style with Literal use and pair RPC style
with Encoded use. However, Progress 4GL Web services support three SOAP message formats,
with the features shown in Table 22.

Table 22: Supported SOAP message formats

SOAP format Progress 4GL Web services features

RPC/Encoded The client interface object method normally has the same function
signature as the 4GL procedure/function. This is possible because the
WSDL for RPC/encoded includes a parameterOrder attribute on
each request/response pair (operation). A return value (result) is
always present in the response message for a user-defined function. A
return value (result) is present in the response message for a procedure
only if specified in ProxyGen (mapped to the 4GL RETURN-VALUE).

RPC/Literal The features are identical to RPC/Encoded.

Document/Literal The client interface object method might not have the same function
signature as the 4GL procedure/function. This is because the WSDL
for Document/Literal does not support the parameterOrder attribute.
The client toolkits generally create a method signature with the
parameters of the request message followed by the parameters of the
response message. A return value (result) is always present in the
response message for both procedures (mapped to the 4GL
RETURN-VALUE) and user-defined functions. The client interface can
represent this return value as a return value on the method or as an
output parameter named "result", depending on the client platform.

WSDL element overview

A WSDL file is an XML document consisting of a series of ordered sections. These sections
contain all the elements used to specify the definitions and bindings for Web service objects. In
general, each succeeding section element references elements defined by preceding sections, to
ensure each object definition and its operations are associated with the required bindings for
these objects.

29
OpenEdge Development: Web Services

Thus, all Web-services-tools-generated WSDL files follow the W3C WSDL 1.1 specification
and include the element sections listed in Table 23.

Table 23: WSDL element overview (1 of 3)

Section Description

definitions Defined by one occurrence of the <definitions> element. This section

identifies the Web service, defines all valid namespaces for the WSDL file,
and contains all other WSDL sections.

types Defined by one occurrence of the <types> element. Each Web service
object has its own schema (<schema> element) in the types section that
specifies all the <complexType> element definitions that the object requires,
including any object ID, and any Progress temp-tables. There is a separate
schema in the types section that specifies the <complexType> definition for
the SOAP fault <detail> element. Note that definitions for built-in XML
Schema data types are not listed in the types section. The elements in the
message section use these types section elements, as required, to define the
input (request) and output (response) parameters with these data types.
The types section also defines the object schema differently, depending on
the SOAP format of the Web service:
RPC/Encoded Temp-tables are represented as SOAP arrays. There
is no indication if a scalar parameter can be null (the 4GL Unknown
value, as specified in ProxyGen), though it can be supported by the
Web service application.
RPC/Literal Temp-tables are represented as <complexType>
element definitions. There is no indication if a scalar parameter can be
null (the 4GL Unknown value, as specified in ProxyGen), though it
can be supported by the Web service application.
Document/Literal Temp-tables are represented as <complexType>
element definitions. Operation request and response messages are also
defined as <complexType> element definitions, because there is no
inherent communications model supported by the Document style
(unlike RPC style, which inherently supports request/response
messaging). The schema indicates if a scalar parameter can be null (the
4GL Unknown value, as specified in ProxyGen) using the nillable
attribute.

210
 WSDL and Web Service Objects in Progress 4GL Web Services

Table 23: WSDL element overview (2 of 3)

Section Description

message Defined by one or more <message> elements. This section defines the
request/response message pair for all operations (Progress procedures or
user-defined functions), as well as the built-in object management
operations supported by each Web service object. The parameters for each
operation are grouped in separate message definitions for input and output.
For Document/Literal format, the parameters are also defined with
reference to <schema> element definitions in the types section. In addition,
the message section defines the SOAP fault message returned by every
operation on occurrence of a Web service error.
For every operation, there is an input (or request) message, which is sent
from the client (through the WSA) to the AppServer, and there is an output
(or response) message, which is sent from the AppServer (through the
WSA) to the client. For RPC formats, the input parameters for each
operation appear in a single named message definition, and the output
parameters for each operation appear in a single, correspondingly named,
"Response" message definition. The WSDL defines input/output
parameters by defining the same parameter in both the input and
"Response" messages. Any return parameter, if present, always appears as
the first parameter in the "Response" message definition. For a
Document/Literal WSDL, the message definitions point to a
<complexType> element defined in the types section for each message.

portTypes Defined by one or more <portType> elements. This section defines the
signatures of all operations using the message definitions from the message
section. There is a separate <portType> element defined for each Web
service object.
Each <portType> element defines the operations for the specified object,
using a separate <operation> element to define each operation. Each such
<operation> element names the operation and references its input, output,
and fault message definitions from the message section.

211
OpenEdge Development: Web Services

Table 23: WSDL element overview (3 of 3)

Section Description

bindings Defined by one or more <binding> elements. This section defines the
SOAP bindings for all Web service operations. SOAP bindings specify
information that indicates how calls to Web service operations are
converted to SOAP request/response messages. The information for SOAP
bindings is specified during Web service deployment (see the Object
binding section on page 25) and determines the format and content of the
envelope, header, and body of all SOAP messages generated for the Web
service. There is a separate <binding> element defined for each Web
service object. Each <binding> element contains <operation> elements
that map directly to the <operation> elements used to define the operation
signatures in a corresponding <portType> element. The Bindings section
<operation> elements thus specify the SOAP binding for each element of
the corresponding operation signature defined by the portTypes section
<operation> elements. Note that while some binding information, such as
soapAction attribute and SOAP format (style and use attributes), is
specified individually for the elements of each operation, the same values
are used to bind all operations of the Web service.

service Defined by one occurrence of the <service> element. This section defines
the deployed location of all Web service objects based on the root URL for
the WSA instance that hosts the Web service. The <service> element
includes one <port> element for each Web service object whose bindings
are defined in the Bindings section. The same WSA root URL is defined for
each object, as specified by the location attribute of the <soap:address>
element.

For more information on WSDL and its meaning, see the WSDL specification at the following
URL:

http://www.w3.org/TR/wsdl

For information on the XML Schema definitions supported by the OpenEdge for 4GL Web
services, see Chapter 4, General Client Programming Model for Progress 4GL Web Services.
This book also provides additional WSDL examples.

212
 3
Session Models and Object IDs in
Progress 4GL Web Services

When a Web service is defined in ProxyGen, the Web service developer must select a session
model for the Web service, and the selected model must match the session model used to
implement the Web service application on the AppServer. The choice of session model affects
how the AppObject for a Web service is defined in the WSDL, how the WSA manages the Web
service at run time, and how the client must access the Web service objects.

This chapter contains the following sections:

Session models for Web services

Session models for AppServers

How object IDs support session models

How session models affect Web service objects

OpenEdge Development: Web Services

Session models for Web services

The Web service session model affects client access to Web services as follows:

Session managed The Web service client maintains a persistent connection to the
AppServer, maintaining session context between requests for a single client application.
This allows a client to carry out complex transactions that span multiple requests, but often
requires extra code management, on the part of the client, for each request.

Session free The Web service client sends requests without any connection to an
AppServer. This allows more clients to simultaneously access the Web service with
minimal code management, but each request returns a complete result that has no certain
dependency on the results of any previous requests.

Note: Session-free Web services using ProcObjects can maintain limited session context
across multiple requests, but ProcObjects are not recommended for use by
session-free Web services. For more information, see the How session models
affect Web service objects section on page 34.

Session models for AppServers

On an AppServer, the session model is determined by its operating mode. The supported session
models include:

Session managed Implemented using the stateless, state-aware, or state-reset operating

modes.

Session free Implemented using the state-free operating mode.

For more information on how the AppServer supports session models, see OpenEdge
Application Server: Developing AppServer Applications. This section, and other sections in this
chapter, describe the requirements for programming clients to access Web services running in
these session models.

32
 Session Models and Object IDs in Progress 4GL Web Services

How object IDs support session models

Progress 4GL Web services use object IDs to maintain context for clients across multiple
operations of a Web service. All session-managed objects and session-free objects, except for
session-free AppObjects, require client applications to obtain the object ID from the WSA for
each such object when they create it and to send the object ID for the object to the WSA along
with each request on that object.

Note: SubAppObjects and ProcObjects have limited utility in the session-free model and
generally should not be defined for session-free Web services. See the How session
models affect Web service objects section on page 34, for more information.

The WSA creates a unique object ID when ever it instantiates one of these objects at the request
of a client when it connects an AppObject to a session-managed Web service or when it creates
a SubAppObject or ProcObject for any Web service. The WSA sends this object ID back to the
client in a SOAP response header. Once received, the client application must send the same
object ID to the WSA in the SOAP request header for every operation that it invokes on the
specified object. The value of this object ID must be identical to the original value returned
when the WSA instantiated the object.

The mechanism used by the client application to retrieve object IDs from the SOAP response
and to send object IDs in the SOAP request depends on the client platform. Some platforms
handle SOAP header information automatically and transparently to the application program.
Others require you to explicitly obtain the object ID from the SOAP response message and send
it in the next appropriate SOAP request message in a manner determined by the client platform.

For session-managed Web services, these object IDs allow each client to maintain
communications with its own set of Web service objects, and thus interact with the context
maintained by the AppServer for these objects. For session-free Web services, these object IDs
allow the use of SubAppObjects and ProcObjects, when it is necessary to do so.

33
OpenEdge Development: Web Services

How session models affect Web service objects

A session-managed AppObject establishes a connection with a single AppServer dedicated to a
single client application. This AppServer services all requests for operations invoked on that
AppObject until the AppObject is released. This same connection is shared by SubAppObjects
and ProcObjects of that Web service, and the connection is not freed until all objects of the Web
service have been released. In effect, the WSA creates copies (server instances) of these objects
for each client application that accesses the same session-managed Web service, and maintains
a unique object ID for each instance.

A session-free AppObject establishes no connection to an AppServer. Instead, the WSA

maintains a pool of AppServer TCP/IP connections (connection pool) that it uses to send
requests from all clients to any available AppServer. So, requests from operations of all client
applications invoked on a session-free AppObject are executed as the WSA receives them and
resources are available to handle them. In effect, all clients of a session-free Web service share
the same server instance of the AppObject. Requests sent to session-free SubAppObjects use
any available AppServer connection in the Web service connection pool, but the WSA
maintains a separate server instance of the SubAppObject for each client that accesses it using
its own unique object ID until the client releases it. The WSA also maintains a separate server
instance of any ProcObject accessed by a client for a session-free Web service, and each such
ProcObject reserves a single AppServer connection from the connection pool dedicated for the
sole use of its client until the client releases the ProcObject.

Thus, for session-managed Web service objects, the AppServer can maintain session context
between requests, enabling the possibility of fine-grained, multi-request transactions on a
server-side database. For session-free Web service AppObjects and SubAppObjects, there is no
single AppServer to maintain session context, and any transactions on a server-side database
must be course-grained so that they begin and end for each request before the AppServer returns
the response to the client.

Note: SubAppObjects provide no additional functionality for a session-free Web service that
is not already provided by the AppObject, except to organize Web service operations
into developer-defined categories, much like using folders to organize files. However,
using session-free SubAppObjects adds complexity to the client application required to
manage the object IDs.

34
 Session Models and Object IDs in Progress 4GL Web Services

Any ProcObject of a session-free Web service does maintain context on a single AppServer that
can be used to manage finer-grained, multiple-request database transactions. But because a
ProcObject reserves its AppServer connection until the object is released, that resource is not
available for other requests on objects of the session-free Web service.

Note: Progress Software Corporation recommends that Web service developers avoid defining
any ProcObjects for session-free Web services. Each instantiated ProcObject degrades
the performance of a session-free Web Service by taking AppServer connections out of
the connection pool that might otherwise be used by all other requests to the Web
service.

35
OpenEdge Development: Web Services

36
 4
General Client Programming Model for
Progress 4GL Web Services

The starting point for developing a Web service client application is the WSDL for the Web
service. A typical client application development process consists of the following tasks, each
described in a section of this chapter:

Creating client interfaces from WSDL

Understanding how client interfaces differ using different SOAP formats

Programming for different session models

Overview of calling methods on Web service objects

Handling communications with Web services

Retrieving and sending object IDshandling SOAP headers

Defining and passing Web service method parameters

Mapping relational data (Progress 4GL temp-tables)

Mapping Progress procedures to SOAP messages

Handling Web service errors and SOAP faults

OpenEdge Development: Web Services

Creating client interfaces from WSDL

You have two basic options for handling Web service SOAP messages from your client
application:

Write your own code to send and receive the SOAP messages as specified in the WSDL.

Generate client interfaces directly from the WSDL using a Web service client toolkit.
Some of the client toolkits available today include:

Microsoft .NET

Apache Axis

Iona XMLBus

Progress 4GL

Most of this chapter assumes you are using a similar client toolkit to generate client interfaces.
These proxies provide an API that generally appears as an interface to application functions, but
that actually provides an interface to messaging operations that hide the complexity of
exchanging SOAP messages over HTTP. (For information on SOAP over HTTP, see the
Handling communications with Web services section on page 414.)

Each client toolkit generates these proxies in a unique manner, but most create objects with
methods. Usually, they create one object for each <portType> and one object for each
<complexType> specified in the WSDL.

These toolkits might generate methods to handle SOAP messages in any of the following ways
for each Web service operation:

Handling the request and response messages in a single method.

Note: All examples in this chapter follow this technique.

Providing separate methods to handle the request and response messages.

Providing a request method with the response message as an output parameter or return
value.

Whatever differences exist in how client platforms generate and interpret SOAP messages, the
Web services tools generate WSDL that allows all clients to generate and interpret all SOAP
messages required to access Web-services-tools-defined Web services.

42
 General Client Programming Model for Progress 4GL Web Services

Understanding how client interfaces differ using different

SOAP formats
Client toolkits define the objects and methods of a Web service a little differently depending on
the Web service SOAP format. The following sections compare how client interfaces represent
components of Web-services-tools-defined Web services for the SOAP formats supported by
Progress 4GL Web services:

Method signatures

Method return values

TABLE (static temp-table) parameters

TABLE-HANDLE (dynamic temp-table) parameters

For information on how some of these components appear in WSDL and SOAP, see Chapter 5,
Sample Code with SOAP Messages for Progress 4GL Web Services.

Method signatures
Client interface method signatures typically map to Progress 4GL prototypes as follows:

RPC/Encoded Method signatures normally match the prototypes in the Progress 4GL.

RPC/Literal Same as RPC/Encoded.

Document/Literal Method signatures do not necessarily match the prototypes in the

Progress 4GL.

43
OpenEdge Development: Web Services

Method return values

Client interface methods typically provide return values for Progress 4GL procedures and
user-defined functions as follows:

RPC/Encoded Methods provide return values:

Always for user-defined functions.

For procedures only when returning the 4GL RETURN-VALUE is specified in

ProxyGen.

RPC/Literal Same as RPC/Encoded.

Document/Literal Methods provide return values:

Always for user-defined functions. The result will be either the method return value
or the first output parameter.

Always for procedures. The result will either be the method return value or the first
output parameter. If specified in ProxyGen, the result will be the 4GL RETURN-VALUE.
If the 4GL RETURN-VALUE is not specified in ProxyGen the result is a null string.

TABLE (static temp-table) parameters

For all SOAP formats, client interfaces typically represent temp-table parameters as follows:

For every temp-table, a row is represented by an object.

Every temp-table parameter is represented as an array of that temp-tables row objects.

44
 General Client Programming Model for Progress 4GL Web Services

TABLE-HANDLE (dynamic temp-table) parameters

For all SOAP formats, client interfaces typically represent TABLE-HANDLE parameters as
follows:

For every TABLE-HANDLE parameter within a Web service object, there is a single object
representing all TABLE-HANDLEs.

In both request messages (input) and response messages (output), the schema of the
TABLE-HANDLE must accompany the data.

For every input TABLE-HANDLE, you must include the schema of the TABLE-HANDLE in the
form of an XML Schema followed by the data in the form of an XML document fragment.

For every output TABLE-HANDLE, you must parse the XML Schema and data in the SOAP
response message.

Programming for different session models

You must program Web service clients differently, depending on the Web service session
model. The following sections summarize these differences.

Caution: For any session model, failing to call the release method on any Open Client object
that a Web service client uses (except a session-free AppObject) leaves any resources
reserved for that object unavailable for other uses. In effect, this creates a memory
leak in the WSA. The Web service deployer can manage these orphaned resources
by property settings on the Web service. For more information, see the Web service
properties reference sections of OpenEdge Application Server: Administration.

45
OpenEdge Development: Web Services

Programming for session-managed Web services

The programming model for session-managed Web services is similar to programming all other
Open Clients, except for the use of object IDs:

Before invoking any other method on a session-managed AppObject, you must instantiate
(create) and call a connect method on the object to establish a connection to the AppServer
context. The client must obtain the object ID for the AppObject after it is created. After
that, you can invoke any method on the AppObject. Calls to all AppObject methods are
sequential (calls follow one another) using the established connection. You must call the
release method on an AppObject when you no longer need the object (Web service).

You can create ProcObjects and SubAppObjects using class factory methods on the
AppObject or create ProcObjects on another SubAppObject. Once created, all objects
share the same connection. This connection terminates only after you have called the
release method on all Web service objects that you create. You must call each object's
release method when you no longer need the object.

You can call methods on a ProcObject as soon as you create it and after the client obtains
the object ID for it. Calls to all ProcObject methods (internal procedures and user-defined
functions) are sequential using the connection established by the AppObject. You must
call the release method on a ProcObject when you no longer need the object.

You can call methods on a SubAppObject as soon as you create it and after the client
obtains the object ID for it. Calls to all SubAppObject methods are sequential using the
connection established for the AppObject. You must call the release method on a
SubAppObject when you no longer need the object.

Once connected to a session-managed Web service, you must always send object IDs with
each method call.

46
 General Client Programming Model for Progress 4GL Web Services

Programming for session-free Web services

The programming model for session-free Web Services differs significantly from the
session-managed model:

After you instantiate (create) a session-free AppObject, you can call any method on the
object and you never connect to an AppServer. Calls to all AppObject methods are
executed in parallel (calls execute simultaneously) using the available AppServer
connections in the Web service connection pool (a pool of AppServer connections
maintained for each session-free Web service). Each call to the AppObject is independent
of every other call and can come from any client, in any order.

You can create SubAppObjects and ProcObjects using class factory methods. Although no
connection is established for the AppObject, SubAppObjects and ProcObjects are
maintained uniquely for each client, and ProcObjects reserve their own AppServer
connections from the Web service connection pool. You must call each object's release
method when you no longer need the object and to return each objects AppServer
connections to the connection pool.

You can call methods on a ProcObject as soon as you create it and after the client obtains
the object ID for it. Calls to all ProcObject methods (internal procedures and user-defined
functions) are sequential using the connection established for the ProcObject. You must
call the release method on a ProcObject when you no longer need the object and to return
the objects AppServer connection to the connection pool.

You can call methods on a SubAppObject as soon as you create it and after the client
obtains the object ID for it. Calls to all SubAppObject methods are executed in parallel.
You must call the release method on a SubAppObject when you no longer need the object,
to remove it from the list of client SubAppObjects maintained by the WSA and to return
its AppServer connection to the connection pool.

Once an object is created, you must always send object IDs with each method call on a
session-free SubAppObject or ProcObject, but you never send object IDs on method calls
to a session-free AppObject.

47
OpenEdge Development: Web Services

Overview of calling methods on Web service objects

The following sections provide an overview of the methods supported on Web service objects,
and how to use them based on the session model of the Web service. The bold-italicized
variable names are replaced by real object and method names during WSDL file generation:

AppObject The name of the AppObject for which the named item is defined or
associated.

SubAppObject The name of the SubAppObject for which the named item is defined or
associated.

ProcObject The name of the ProcObject for which the named item is defined or
associated.

ProcName The name of a method that executes a Progress 4GL non-persistent procedure
or internal procedure on the AppServer.

FuncName The name of a method that executes a Progress 4GL user-defined function
on the AppServer.

Many of the methods referenced in this section are standard methods from the Open Client
programming model. The precise syntax for invoking these methods differs depending on the
client development language used to access Web services; however, the basic signatures for
these methods are the same in all languages. For more information on how these methods are
used in Web service clients, see Chapter 5, Sample Code with SOAP Messages for Progress
4GL Web Services.

The following sections describe usage for:

Client interface methods for session-managed AppObjects

Client interface methods for session-free AppObjects

Client interface methods for SubAppObjects and ProcObjects (session-managed and

session-free)

48
 General Client Programming Model for Progress 4GL Web Services

Client interface methods for session-managed

AppObjects
A session-managed AppObject provides the following methods.

Use this method to connect to an AppServer:

Connect_AppObject (...)

This method must be executed before any other method can be called. The SOAP response
header returned by this method contains an AppObjectID element whose value must be sent in
the SOAP request header for all other methods invoked on this AppObject.

Use this method to release the AppObject connection:

Release_AppObject ( )

Once this method is executed, no other methods on the AppObject can be called. The SOAP
request header must contain the value of the AppObjectID element. If other objects
(SubAppObjects or ProcObjects) are using the same connection, the connection is not
terminated until the corresponding release method is called on every object.

Use this method to create a SubAppObject:

CreateAO_SubAppObject ( )

This method must be executed before calling any other methods on the SubAppObject. The
SOAP request header must contain the value of the AppObjectID element. The SOAP response
header returned by this method contains a SubAppObjectID element whose value must be sent
in the SOAP request header for all methods invoked on this SubAppObject.

Use this method to create a ProcObject and execute the corresponding persistent procedure:

CreatePO_ProcObject (...)

49
OpenEdge Development: Web Services

This method must be executed before calling any other methods on the ProcObject. The SOAP
request header must contain the value of the AppObjectID. The SOAP response header returned
by this method contains a ProcObjectID whose value must be sent in the SOAP request header
for all methods invoked on this ProcObject.

Call a ProcName method on the AppObject to execute a corresponding non-persistent external

procedure typically identified by ProcName:

ProcName (...)

The SOAP request header must contain the value of the AppObjectID element.

Client interface methods for session-free AppObjects

A session-free AppObject provides the following methods.

Call a ProcName method on the AppObject to execute a corresponding non-persistent external

procedure typically identified by ProcName:

ProcName (...)

Because no context is maintained for a session-free AppObject, calls to these methods require
no object IDs to be sent in the SOAP request header.

Use this method to create a SubAppObject:

CreateAO_SubAppObject ( )

Note: SubAppObjects are not recommended for use in session-free Web services.

410
 General Client Programming Model for Progress 4GL Web Services

This method must be executed before calling any other methods on the SubAppObject. The
SOAP response header returned by this method contains a SubAppObjectID element whose
value must be sent in the SOAP request header for all methods invoked on this SubAppObject.
Because no context is maintained for a session-free AppObject, calls to this method require no
object ID to be sent in the SOAP request header.

Use this method to create a ProcObject and execute the corresponding persistent procedure:

CreatePO_ProcObject (...)

Note: ProcObjects are not recommended for use in session-free Web services.

This method must be executed before calling any other methods on the ProcObject. The SOAP
response header returned by this method contains a ProcObjectID element whose value must
be sent in the SOAP request header for all methods invoked on this ProcObject. Because no
context is maintained for a session-free AppObject, calls to this method requires no object ID
to be sent in the SOAP request header.

Client interface methods for SubAppObjects and

ProcObjects (session-managed and session-free)
You use the methods for ProcObjects and SubAppObjects in the same way regardless of the
session model. The value for the ProcObjectID element or SubAppObjectID element that you
send in the SOAP request header for methods invoked on each object is initially returned in the
SOAP response header of the CreatePO_ProcObject method or CreateAO_SubAppObject
method that you called to instantiate the object.

ProcObject methods

A ProcObject provides the following methods.

Use this method to terminate and remove the context of the persistent procedure that is managed
by the ProcObject:

Release_ProcObject ( )

411
OpenEdge Development: Web Services

Once this method is executed, no other methods on the ProcObject can be called. The SOAP
request header must contain the value of the ProcObjectID element. If other objects (AppObject
or SubAppObjects) are sharing the same connection, the connection does not terminate until
you call the release method for all the objects sharing the connection.

Call a ProcName method on the ProcObject to execute a corresponding internal procedure in the
persistent procedure that is managed by the ProcObject:

ProcName (...)

The SOAP request header must contain the value of the ProcObjectID element.

Call a FuncName method on the ProcObject to execute a corresponding user-defined function in

the persistent procedure that is managed by the ProcObject:

FuncName (...)

The SOAP request header must contain the value of the ProcObjectID element.

SubAppObject methods

A SubAppObject provides the following methods.

Use this method to release a SubAppObject:

Release_SubAppObject ( )

Once this method is executed, no other methods on the SubAppObject can be called. The SOAP
request header must contain the value of the SubAppObjectID element. If other objects
(AppObject or ProcObjects) are sharing the same connection, the connection does not terminate
until you call the release method for all the objects sharing the connection.

Use this method to create a ProcObject and call the corresponding persistent procedure:

CreatePO_ProcObject (...)

412
 General Client Programming Model for Progress 4GL Web Services

This method must be executed before calling any other methods on the ProcObject. The SOAP
request header must contain the value of the SubAppObjectID element. The SOAP response
header returned by this method contains a ProcObjectID element whose value must be sent in
the SOAP request header for all methods invoked on this ProcObject.

Call a ProcName method on the SubAppObject to execute a corresponding non-persistent

external procedure typically identified by ProcName:

ProcName (...)

The SOAP request header must contain the value of the SubAppObjectID element.

413
OpenEdge Development: Web Services

Handling communications with Web services

Figure 41 shows the HTTP communications model used to exchange SOAP messages between
Web service clients and Web services defined with the Web services tools. The HTTP Post
method carries a SOAP request message and the HTTP Response carries a SOAP response
message. Progress 4GL Web services support this message exchange in accordance with the
SOAP 1.1 over HTTP standard.

Web services

Web server/JSE

Web service
clients
Post (SOAP)

Object manager
Java
Java

Web services
Java
VB.NET
VB.NET

adapter
VB.NET

listener
C#.NET

HTTP
C#.NET
Progress
Response (SOAP)

WSDL
WSDL
WSDL WSDL
WSAD
WSDL
files files

Figure 41: OpenEdge Web services architecture

Note: The WSDL file defines the available Web service methods at development time, while
the WSAD file defines the mapping between a Web service method and AppServer
procedure at run time. For more information on how these files function in the 4GL Web
services development environment, see Chapter 1, Web Services in OpenEdge.

414
 General Client Programming Model for Progress 4GL Web Services

Each SOAP message is an XML document that consists of the following ordered elements:

1. SOAP Envelope (mandatory) Used to define the namespaces used in the document.

2. SOAP Header (optional) Used to send the object ID, when required for the object.

3. SOAP Body (mandatory) Contains the data and SOAP formatting information. For a
SOAP request message, the body contains the method name and its input parameter
values. For a SOAP response message, the body contains one of the following sets of
components:

Any method output parameters and any return value for a successful request.

A SOAP fault for a failed request.

The remainder of this chapter contains many examples of SOAP messages, with all of these
elements.

Retrieving and sending object IDshandling SOAP headers

A previous chapter (see Chapter 3, Session Models and Object IDs in Progress 4GL Web
Services) explains that object IDs must be retrieved from and sent in SOAP headers for
methods on the following Open Client objects:

Session-managed AppObjects

ProcObjects

SubAppObjects

Each client toolkit provides different means to access SOAP headers. In some environments,
such as Microsoft .NET, the interface automatically moves information from the response
header to subsequent request headers within the same object. You do have to do a little work to
move the information between objects (for example, copying a ProcObject ID from the
AppObject that creates a ProcObject to the ProcObject itself). In other environments, you are
responsible for extracting the information from the response header and sending it in the SOAP
headers for subsequent requests.

415
OpenEdge Development: Web Services

The WSDL defines the SOAP elements that hold the object ID using a <complexType>
declaration in the types section for each Web service object schema that requires it. The headers
in the SOAP messages that are sent and received for a given object then contain the required
object ID values.

Defining object IDs in WSDL

This is a sample of the types section that might appear in the WSDL for many of the sample
Web services in this chapter. (This example is for RPC/Encoded, but similar for all SOAP
formats):

WSDL Containing an object ID definition

<types>
<schema elementFormDefault="unqualified"
targetNamespace="urn:OrderSvc:OrderInfo"
xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<complexType name="OrderInfoID">
<sequence>
<element name="UUID" type="xsd:string"/>
</sequence>
</complexType>

<!-- Temp Table declarations here (if any) -->

</schema>

<!-- Additional Object Schema Declarations (if any) -->

</types>

The WSDL schema definition for each Web service object (except a session-free AppObject)
defines the SOAP header element that contains the value of its object ID as a <complexType>.
As shown in the example, the name for the SOAP header element is the name of the
<complexType>, in this example, "OrderInfoID". The name of the element that contains the
value of the object ID is "UUID", defined as an element of type "xsd:string". This definition
is the same for the object IDs of all Web service objects, differing only in the name of the object
ID element.

416
 General Client Programming Model for Progress 4GL Web Services

Using object IDs in a SOAP message

This is a sample header of a SOAP message containing an object ID for the object specified in
the sample WSDL, using the WSDL-defined <OrderInfoID> SOAP element:

SOAP header containing an object ID

<soap:Header>
<t:OrderInfoID xmlns:t="urn:OrderSvc:OrderInfo"
soap:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/>
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000001|AO>;M/IryPm3piDcF/W5DsH4GA==</UUID>
</t:OrderInfoID>
</soap:Header>

The value of the object ID appears in bold, contained by the <UUID> element.

The same basic <OrderInfoID> element contains the object ID in the SOAP response header
that initially returns the OrderInfoID object ID, when the object is created, and is required in
any subsequent SOAP request header sent by methods invoked on the OrderInfo object.

Thus, for all Web service objects that require object IDs, your client application must parse out
the object ID value in the <UUID> element contained by the object ID element (<OrderInfoID>
in the example) and returned in the SOAP response header at object creation, whether it happens
automatically or you must program it explicitly. Similarly, for every SOAP request sent by a
method invoked on this same object, your client application must create an object ID element
containing a <UUID> element that holds this identical object ID value in the SOAP header of the
request message.

417
OpenEdge Development: Web Services

Object IDs in examples

For some examples of SOAP headers that contain object IDs and sample code that handles
object IDs, see the following chapters:

Chapter 5, Sample Code with SOAP Messages for Progress 4GL Web Services

Appendix A, Developing a .NET Client to Access Progress 4GL Web Services

Appendix B, Developing a Java Client to Access Progress 4GL Web Services

For examples of client applications that handle object IDs, see the sample 4GL Web service
applications installed with OpenEdge. For information on how to access these applications, see
Chapter 6, Sample Progress 4GL Web Services and Client Applications.

Defining and passing Web service method parameters

Most parameters are defined and passed in SOAP messages as XML Schema data types.
Progress 4GL Web services expose Progress 4GL parameter data types as XML data types in
the WSDL based on the 2001 XML Schema: Data types (referred to as xsd in Table 41).

Table 41 lists the data type mappings for parameters between Progress 4GL and XML data
types. Most of these parameters can also be passed as arrays.

418
 General Client Programming Model for Progress 4GL Web Services

Table 41: Supported XML data types

Progress 4GL data type XML Schema data type

CHARACTER xsd:string

COM-HANDLE xsd:long

DATE xsd:date

DATETIME xsd:dateTime

DATETIME-TZ xsd:dateTime

DECIMAL xsd:decimal

INTEGER (32 bit) xsd:int

LOGICAL xsd:boolean

LONGCHAR1 xsd:string

MEMPTR1 xsd:base64Binary

RAW xsd:base64Binary

RECID (32 or 64 bit) xsd:long

ROWID xsd:base64Binary

WIDGET-HANDLE xsd:long

complexType
TABLE (static temp-table)2

complexType (<any>)
TABLE-HANDLE (dynamic temp-table)2
1 LONGCHAR and MEMPTR data types are designed to support very large strings of data. Use of these data types
as parameters in Web services can result in a serious performance impact.
2
TABLE and TABLE-HANDLE data types cannot be passed as arrays. For more information on passing arrays,
see the Array parameters section on page 420.

Note: The Progress 4GL parameter type BUFFER, DATASET, or DATASET-HANDLE is not
supported.

419
OpenEdge Development: Web Services

Client data type mapping

Each client environment provides its own mapping from XML Schema data types to client
language data types. For example, a 4GL CHARACTER parameter is mapped to a
java.lang.String class in Java and a System.String type in .NET.

Relational data types

The Progress WSDL represents TABLE and TABLE-HANDLE parameters as <complexType>
element definitions. The Mapping relational data (Progress 4GL temp-tables) section on
page 428 describes these <complexType> elements.

Array parameters
The WSA supports arrays (extents) as parameters for the data types listed in Table 41. These
data types are mapped to XML Schema data types as indicated in this. In the WSDL document,
the XML Schema data types are housed in a complex structure whose type definition depends
on the encoding style. For details and examples of array representation for each WSDL style/use
format, see the Array mapping in WSDL documents section on page 421.

Note: TABLE (temp-table) and TABLE-HANDLE (temp-table handle) parameters cannot be array
parameters.

Fixed arrays

In cases where the Progress 4GL refers to fixed-array parameters, only the Document/Literal
WSDL style/use format represents the fixed size of the array; the RPC/Encoded and
RPC/Literal formats represent all arrays as unbounded. Therefore, when using either of the RPC
WSDL style formats, the developer must know the size of each array parameter that is expected.
The WSA returns a SOAP fault if the array sizes do not match.

The Document/Literal schema represents each parameter individually, and thus specifies the
size for each fixed array parameter. See the examples in the Array mapping in WSDL
documents section on page 421.

420
 General Client Programming Model for Progress 4GL Web Services

Array mapping in WSDL documents

This section provides detailed information about how array parameters are represented in each
of the three WSDL style/use formats:

RPC/Encoded

RPC/Literal

Document/Literal

The description of each WSDL format includes an example. The example shows the schema
information in the types section, plus the message sections for request and response, for a
4GLprocedure with the following signature in the CustomerAO AppObject:

arraySample procedure signature

/* arraySample*/
DEFINE INPUT PARAMETER names AS CHARACTER EXTENT.
DEFINE INPUT PARAMETER hireDates AS DATETIME EXTENT.
DEFINE OUTPUT PARAMETER quotas AS INTEGER EXTENT 12.

RPC/Encoded

For the RPC/Encoded format, an array parameter is represented as a SOAP array complexType
in an XML Schema type definition.

Array parameter definition for RPC/Encoded WSDL

<complexType name="ArrayOfXMLType">
<complexContent>
<restriction base="soapenc:Array">
<attribute ref=soapenc:arrayType" wsdl:arrayType="XMLType[]"/>
</restriction>
<complexContent>
</complexType>

The WSDL file contains a separate schema for each object defined in ProxyGen. Each such
schema includes one SOAP array complexType definition for each data type used as an array
parameter for any procedure or function in that object. For example, if the 4GL defines one or
more parameters in the object with the data type CHARACTER EXTENT, the schema includes a
complexType named ArrayOfString.

421
OpenEdge Development: Web Services

The RPC/Encoded WSDL document for the arraySample procedure shown at the beginning of
this section includes the following types and message sections:

RPC/Encoded WSDL schema example

<wsdl:types>
<schema targetNamespace="urn:tempuri-org:CustomerAO"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="unqualified">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<complexType name="ArrayOfInt">
<complexContent>
<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType"
wsdl:arrayType="xsd:int[]"/>
</restriction>
</complexContent>
</complexType>
<complexType name="ArrayOfDateTime">
<complexContent>
<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType"
wsdl:arrayType="xsd:dateTime[]"/>
</restriction>
</complexContent>
</complexType>
<complexType name="ArrayOfString">
<complexContent>
<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType"
wsdl:arrayType="xsd:string[]"/>
</restriction>
</complexContent>
</complexType>
</schema>
</wsdl:types>
.
.
.
<wsdl:message name="CustomerAO_arraySample">
<part name="names" type="S1:ArrayOfString"/>
<part name="hireDates type="S1:ArrayOfDateTime"/>
</wsdl:message>
<wsdl:message name="CustomerAO_arraySampleResponse">
<part name="quotas" type="S1:ArrayOfInt"/>
</wsdl:message>

422
 General Client Programming Model for Progress 4GL Web Services

RPC/Literal

For the RPC/Literal format, an array parameter is represented as an unbounded sequence of its
data type in an XML Schema type definition, where XMLType is the XML Schema type:

Array parameter definition for RPC/Literal WSDL

<complexType name="ArrayOfXMLType">
<sequence>
<element name="item" type="XMLType"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>

The WSDL file contains a separate schema for each object defined in ProxyGen. Each such
schema includes one complexType definition for each data type used as an array parameter for
any procedure or function in that object. For example, if the 4GL defines one or more
parameters in the object with the data type CHARACTER EXTENT, the schema includes a
complexType named ArrayOfString.

423
OpenEdge Development: Web Services

The RPC/Literal WSDL document for the arraySample procedure shown at the beginning of
this section includes the following types and message sections:

RPC/Literal WSDL schema example

<wsdl:types>
<schema targetNamespace="urn:tempuri-org:CustomerAO"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="unqualified"
<complexType name="ArrayOfInt">
<sequence>
<element name="item" type="xsd:int"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="ArrayOfDateTime">
<sequence>
<element name="item" type="xsd:dateTime"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="ArrayOfString">
<sequence>
<element name="item" type="xsd:string"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
</schema>
</wsdl:types>

<wsdl:message name="CustomerAO_arraySample">
<part name="names" type="S1:ArrayOfString"/>
<part name="hireDates" type="S1:ArrayOfDateTime"/>
</wsdl:message>
<wsdl:message name="CustomerAO_arraySampleResponse">
<part name="quotas" type="S1:ArrayOfInt"/>
</wsdl:message>

424
 General Client Programming Model for Progress 4GL Web Services

Document/Literal

For the Document/Literal format, an array parameter is represented as a sequence of its data
type in an XML Schema type definition:

Array parameter definition for Document/Literal WSDL

<complexType
<sequence>
<element name="paramName" type="XMLType"
minOccurs="zero_or_extentval"
maxOccurs="extentval_or_unbounded"/>
</sequence>
</complexType>

The bolded elements refer to:

paramName The name of the parameter.

XMLType The XML Schema type of the parameter.

zero_or_extentval 0 or an integer for the minimum array size.

extentval_or_unbounded An integer for the maximum array size or unbounded.

425
OpenEdge Development: Web Services

The Document/Literal WSDL document for the arraySample procedure shown at the beginning
of this section includes the following types and message sections:

Document/Literal WSDL schema example

<wsdl:types>
<schema targetNamespace="urn:tempuri-org:CustomerAO"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<element name="arraySample">
<complexType>
<sequence>
<element name="names" type="xsd:string"
minOccurs="0" maxOccurs="unbounded"
nillable=true>
<element name="hireDates" type="xsd:dateTime"
minOccurs="0" maxOccurs="unbounded"
nillable=true>
</sequence>
</complexType>
</element>
<element name="arraySampleResponse">
<complexType>
<sequence>
<element name="quotas" type="xsd:int"
minOccurs="12" maxOccurs="12"
nillable=true>
</sequence>
</complexType>
</element>
</schema>
</wsdl:types>

<wsdl:message name="CustomerAO_procName">
<part name="parameters" element="S1:procName"/>
</wsdl:message>
<wsdl:message name="CustomerAO_procNameResponse">
<part name="parameters" element="S1:procNameResponse"/>
</wsdl:message>

426
 General Client Programming Model for Progress 4GL Web Services

Date and time data

The Progress 4GL DATE, DATETIME, and DATETIME-TZ data types are explicit with respect to the
inclusion or exclusion of time and time zone values. When sending date/time values to a 4GL
Web service, the client application must precisely match the expected format. The WSA returns
a SOAP fault if the client request fails to include a time or time zone when that information is
expected, or if the client includes unexpected time or time zone information.

In the case of a DATE field, the WSDL document maps the item unambiguously to the XML
Schema data type xsd:date. Both DATETIME and DATETIME-TZ, however, map to the
xsd:dateTime data type; therefore, the WSDL does not tell the client developer whether a time
zone value is required. The developer must obtain this information by another means and must
ensure that the client application sends the expected value.

Table 42 lists the XML date data formats that are valid as input for each of the 4GL data types;
use of any other input format results in a SOAP fault.

Table 42: Valid date input formats

Progress 4GL data type Valid input formats

DATE CCYY-MM-DD

DATETIME1 CCYY-MM-DDThh:mm:ss
CCYY-MM-DDThh:mm:ssZ
CCYY-MM-DDThh:mm:ss+hh:mm
CCYY-MM-DDThh:mm:ss-hh:mm

DATETIME-TZ CCYY-MM-DDThh:mm:ssZ
CCYY-MM-DDThh:mm:ss+hh:mm
CCYY-MM-DDThh:mm:ss-hh:mm

1
Any time zone information input to DATETIME is lost.

Dedicated Progress 4GL data types

The COM-HANDLE, RECID, ROWID, and WIDGET-HANDLE 4GL data types are not meaningful outside
the Progress 4GL environment. You can obtain their values from a Progress procedure (through
one Web service method) and pass them back to another Progress procedure (through another
Web service method), but there is no other practical use for them on the client side.

427
OpenEdge Development: Web Services

Mapping relational data (Progress 4GL temp-tables)

Progress 4GL Web services support the passing of Progress 4GL static and dynamic temp-tables
as parameters; however, the client application must do more work to handle dynamic
temp-tables.

For examples of client applications that use static and dynamic temp-tables, see Chapter 6,
Sample Progress 4GL Web Services and Client Applications. The following sections provide
more information on client temp-table management, with examples:

Defining TABLE (static temp-table) parameters

Defining TABLE-HANDLE (dynamic temp-table) parameters

Defining TABLE (static temp-table) parameters

TABLE parameters pass data only, because the static temp-table schema is known at WSDL
generation. Progress 4GL Web services map a TABLE definition to a <complexType> consisting
of a <sequence> of elements that represent a row (Progress record). Each <element> in this
sequence represents a column (Progress field) of the row. For all SOAP formats, a TABLE
parameter is defined as a <complexType> that references the corresponding row element
<complexType>.

Client-development toolkits typically define an object for every <complexType> representing a

temp-table row. The client application then creates the TABLE parameter by creating an array
of temp-table row object instances.

The following examples show some <complexType> definitions for TABLE rows and parameters.

The following WSDL sample defines a TABLE row named, staticTT_ttEmpRow, with two
columns, Name and Number:

TABLE parameter row schema for all SOAP formats

<complexType name="staticTT_ttEmpRow">
<sequence>
<element name="Name" nillable="true" type="xsd:string"/>
<element name="Number" nillable="true" type="xsd:int"/>
</sequence>
</complexType>

428
 General Client Programming Model for Progress 4GL Web Services

The following WSDL sample defines a temp-table parameter for the ttEmp row using the
RPC/Encoded SOAP format. Note that the parameter is a SOAP array of rows:

TABLE parameter for RPC/Encoded

<complexType name="ArrayOfstaticTT_ttEmpRow">
<complexContent>
<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType"
wsdl:arrayType="S2:staticTT_ttEmpRow[]"/>
</restriction>
</complexContent>
</complexType>

The following WSDL sample defines a TABLE parameter using the RPC/Literal or
Document/Literal SOAP formats. Note that the parameter is a sequence of multiple rows:

TABLE parameter for RPC/Literal and Document/Literal

<complexType name="staticTT_ttEmpParam">
<sequence>
<element maxOccurs="unbounded"
minOccurs="0" name="ttEmpRow" type="S2:staticTT_ttEmpRow" />
</sequence>
</complexType>

For these SOAP formats, the row element name (ttEmpRow) is used to identify each element that
holds a data row sent in SOAP messages that pass a TABLE parameter.

Following are general formats for TABLE parameters in SOAP messages. For an RPC/Encoded
Web service, the TABLE parameter is represented as a SOAP array of TABLE rows, where each
row is encapsulated by an <Item> element:

TABLE parametersgeneral RPC/Encoded format

<Item> <!--- row instance 1 --> </Item>

<Item> <!--- row instance 2 --> </Item>
<Item> <!--- row instance 3 --> </Item>
...

429
OpenEdge Development: Web Services

In RPC/Encoded SOAP messages passing TABLE parameters, you might notice XML like this:

<Item href="#id2"/>
...
<...id="id2">
<!--- row instance 1 -->
<!--- row instance 2 -->
<!--- row instance 3 -->
...
</...>

Some client toolkits use the SOAP encoding href attribute to reference the data in a SOAP array
for a given row instance at a different location in the message (indicated by the id attribute with
the corresponding value). The WSA, however, does not use this indirect form of data reference
for TABLE parameters in RPC/Encoded SOAP messages.

For an RPC/Literal or Document/Literal Web service, the TABLE parameter is represented as a

<sequence> of TABLE row elements. Each element is named after the row <element> in the
<complexType> used to define the TABLE row for the parameter. This WSDL-named row
<element> corresponds to the <Item> element used to represent SOAP array rows in
RPC/Encoded Web services.

Thus, using the sample row element named ttEmpRow, a SOAP message contains a TABLE
parameter for this row definition in the following form:

TABLE parametersgeneral Document (or RPC)/Literal format

<ttEmpRow> <!-- row instance 1 --> </ttEmpRow>

<ttEmpRow> <!-- row instance 2 --> </ttEmpRow>
<ttEmpRow> <!-- row instance 3 --> </ttEmpRow>
...

430
 General Client Programming Model for Progress 4GL Web Services

Each column of a TABLE row can hold any data type shown in Table 43.

Table 43: XML data types for TABLE (static temp-table) parameter
columns

Progress 4GL data type XML Schema data type

BLOB1 xsd:base64Binary

CHARACTER xsd:string

CLOB1 xsd:string

COM-HANDLE xsd:long

DATE xsd:date

DATETIME xsd:dateTime

DATETIME-TZ xsd:dateTime

DECIMAL xsd:decimal

INTEGER (32 bit) xsd:int

LOGICAL xsd:boolean

RAW xsd:base64Binary

RECID (32 or 64 bit) xsd:long

ROWID xsd:base64Binary

WIDGET-HANDLE xsd:long

1
BLOB and CLOB data types are designed to support very large objects. Use of these data types for table fields in
Web services can result in a serious performance impact.

431
OpenEdge Development: Web Services

Defining TABLE-HANDLE (dynamic temp-table)

parameters
TABLE-HANDLE parameters pass both the schema and data, because the dynamic temp-table
schema is not known at compile time. Thus, for TABLE-HANDLE parameters, Progress 4GL Web
services map a Progress TABLE-HANDLE to a <complexType> containing a sequence of xsd:any.
There is a single definition used for all TABLE-HANDLE parameters in all supported SOAP
formats. The following WSDL sample shows this common TABLE-HANDLE parameter definition:

TABLE-HANDLE definition for all dynamic temp-table parameters

<complexType name="TableHandleParam">
<sequence>
<any namespace="##local"/>
</sequence>
</complexType>

The client application must create (for input) and parse (for output) the XML Schema along with
the data for the parameter. How the client inserts the input schema and data in request messages
and how it parses the output schema and data from response messages is entirely dependent on
the client toolkit.

This is the general format in Progress 4GL Web services for representing a TABLE-HANDLE in a
SOAP message, where the schema is defined in a <schema> element and each row is
encapsulated by an <Item> element within a <Data> element:

TABLE-HANDLE parametersgeneral format

<DataSet>
<schema>

<!-- TEMP-TABLE row definition in XML Schema -->

</schema>
<Data>

<Item> <!--- row instance 1 --> </Item>

<Item> <!--- row instance 2 --> </Item>
<Item> <!--- row instance 3 --> </Item>
...

</Data>
</DataSet>

432
 General Client Programming Model for Progress 4GL Web Services

Each column of a TABLE-HANDLE row can hold any data type shown in Table 44.

Table 44: XML data types for TABLE-HANDLE (dynamic temp-table)

parameter columns

Progress 4GL data type XML Schema data type

CHARACTER xsd:string

DATE xsd:date

DATETIME-TZ xsd:dateTime

DECIMAL xsd:decimal

INTEGER (32 bit) xsd:int

LOGICAL xsd:boolean

RAW xsd:base64Binary

Mapping Progress procedures to SOAP messages

The mapping of a Progress procedure (or, similarly, a user-defined function) to its final
representation as a pair of SOAP request/response messages follows a well-defined series of
steps:

1. ProxyGen generates a Web service definition that includes the selected Progress
procedure during Web service development (see OpenEdge Development: Open Client
Introduction and Programming).

2. The WSA generates the WSDL file for the Web service during Web service deployment
(see OpenEdge Application Server: Administration). This WSDL file includes a series of
elements that define a Web service operation that is mapped to the selected Progress
procedure in the context of some Open Client object as specified in ProxyGen.

433
OpenEdge Development: Web Services

3. A client developer obtains the WSDL file and typically generates the source code for the
client interface by running a client interface generator. This interface generator, which
often comes as part of a Web services client development platform, reads the WSDL file
and typically writes out the source code for the client interface as a series of objects and
methods, each of which represents a Web service operation. One of these methods maps
to the Web service operation defined in the WSDL file from Step 2.

Note: In OpenEdge, the WSDL Analyzer generates documentation on how to represent

Web service operations in the 4GL. For more information, see Chapter 8,
Analyzing WSDL for Progress 4GL Access to Web Services.

4. The client developer writes the client application that uses the client interface generated in
Step 3. The application invokes the method mapped to the Web service operation defined
in Step 2, which sends a SOAP request message to the WSA where the Web service is
deployed.

5. The WSA receives the SOAP request and packages the input parameters in an AppServer
message which results in executing the corresponding Progress procedure on an
AppServer.

6. The Progress procedure then returns any output parameters and any return value to the
WSA.

7. The WSA packages these procedure results in a SOAP response message, which it returns
to the client that originally sent the request.

In short, this process transforms:

1. 4GL procedure prototype to WSDL operation (Web service development).

2. WSDL operation to client method prototype (client development).

3. Client method call to SOAP request/response message pair (run time).

The following examples show how these three transformations proceed.

434
 General Client Programming Model for Progress 4GL Web Services

4GL procedure prototype to WSDL operation (Web

service development)
This is the Progress procedure prototype for the sample FindCustomerByNum.p external
procedure:

Progress 4GL procedure prototype

/* FindCustomerByNum.p */

DEFINE INPUT PARAMETER CustomerNumber AS INTEGER.

DEFINE OUTPUT PARAMETER CustomerName AS CHARACTER.

For ProxyGen, the main information mapped from this prototype into the corresponding Web
service operation definition is in bold, including the procedure name (filename for an external
procedure) and for any parameters, the parameter mode (input or output), names, and data types.

Note: Some information can only be specified in ProxyGen, such as whether the 4GL
RETURN-VALUE is used and (for external procedures) what Open Client object this
operation belongs to.

These are the message section definitions in the RPC/Encoded and RPC/Literal WSDL file for
the FindCustomerByNum operation request and response messages:

WSDL message section defining request and response messages

<message name="OrderInfo_FindCustomerByNum">
<part name="CustomerNumber" type="xsd:int"/>
</message>
<message name="OrderInfo_FindCustomerByNumResponse">
<part name="CustomerName" type="xsd:string"/>
</message>

Note that the request message contains the input parameter, CustomerNumber, and the response
message contains the output parameter, CustomerName, both defined by appropriate XML data
types.

435
OpenEdge Development: Web Services

This is the definition for the FindCustomerByNum operation in the portType section of the
WSDL:

WSDL portType section defining an operation signature on an object

<portType name="OrderInfoObj">
<operation name="FindCustomerByNum"
parameterOrder="CustomerNumber CustomerName">
<input message="tns:OrderInfo_FindCustomerByNum"/>
<output message="tns:OrderInfo_FindCustomerByNumResponse"/>
<fault name="OrderInfoFault" message="tns:FaultDetailMessage"/>
</operation>
...
</portType>

The portType section defines the object in which the operation is defined, in this case, the
AppObject, OrderInfo (as specified in ProxyGen). Note that this definition groups together the
request (input) and response (output) messages, along with a generic fault message as part of
the operation definition.

436
 General Client Programming Model for Progress 4GL Web Services

This is the definition for the FindCustomerByNum operation in the Bindings section for the
AppObject, OrderInfo:

WSDL Bindings section defining an operation and object binding

<binding name="OrderInfoObj" type="tns:OrderInfoObj">

<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>

<operation name="FindCustomerByNum">
<soap:operation soapAction="" style="rpc"/>
<input>
<soap:header message="tns:OrderInfoID" part="OrderInfoID"
use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:OrderSvc:OrderInfo" wsdl:required="true">
</soap:header>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:OrderSvc:OrderInfo"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:OrderSvc:OrderInfo"/>
</output>
<fault name="OrderInfoFault">
<soap:fault name="OrderInfoFault" use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://servicehost:80/wsa/wsa1"/>
</fault>
</operation>
...
</binding>

Note that this definition specifies that the transport protocol as SOAP over HTTP, and goes on
to define the content for SOAP messages request (input) and response (output) messages for the
operation. This is where the object ID definitions are referenced for operations that require
them.

437
OpenEdge Development: Web Services

This is the port definition in the service section for the object (OrderInfo AppObject)
containing the FindCustomerByNum operation:

WSDL service section defining the Web service location

<service name="OrderInfoService">
<port name="OrderInfoObj" binding="tns:OrderInfoObj">
<documentation/>
<soap:address location="http://servicehost:80/wsa/wsa1"/>
</port>
...
</service>

Note that the URL for the WSA instance is specified here for the location of the Web service.

WSDL operation to client method prototype (client

development)
This is a VB.NET method prototype for the FindCustomerByNum operation defined in the
WSDL file:

Interface method prototype (VB.NET) generated from a WSDL operation

definition

Public Sub FindCustomerByNum(

ByVal CustomerNumber As Integer,
ByRef CustomerName As String)

This prototype has basically the same information as the original Progress 4GL procedure
prototype (see the 4GL procedure prototype to WSDL operation (Web service development)
section on page 435). In this case, ByVal specifies a value for the CustomerNumber parameter
used for input, and ByRef specifies a reference to a variable for the CustomerName parameter
used for output. Also, when VB.NET generates the client interface object that contains this
method, the information provided in the WSDL portType, bindings, and service sections
specify the object on which this method is defined (<portType>), the format of SOAP messages
for this method (<binding>), and the location of the WSA instance to which the Web service is
deployed (<port> within <service>).

438
 General Client Programming Model for Progress 4GL Web Services

Client method call to SOAP request/response message

pair (run time)
This is a sample VB.NET method call to the FindCustomerByNum( ) method defined in the
client interface, where the OrderInfo AppObject instance on which the method is called is
named webService:

Interface method call (VB.NET) generating SOAP messages

Dim CustomerName As String

webService.FindCustomerByNum(3, CustomerName)

Thus, the call passes a value of 3 for the CustomerNumber parameter as input and receives the
value returned by the CustomerName output parameter in a variable that happens also to be
named CustomerName.

This is the SOAP request message sent out by the client after invoking the
FindCustomerByNum( ) method. You can see that the value (3) for the input parameter,
CustomerNumber, is passed in the SOAP message body.

Note that the AppObject ID for OrderInfo is sent along in the SOAP header (<UUID> element).
.NET sends the AppObject ID automatically. For other client platforms, you have might have
to code this information into the SOAP message before it is sent:

SOAP request message for method input parameters

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<q1:OrderInfoID id="h_id1"
xmlns:q1="urn:OrderSvc:OrderInfo">
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000001|AO>;M/IryPm3piDcF/W5DsH4GA==</UUID>
</q1:OrderInfoID>
<soap:Header>
<soap:Body
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:FindCustomerByNum xmlns:q1="urn:OrderSvc:OrderInfo">
<CustomerNumber xsi:type="xsd:int">3</CustomerNumber>
</q1:FindCustomerByNum>
</soap:Body>
</soap:Envelope>

For more information on how object IDs are defined, obtained, and sent in SOAP messages, see
the Retrieving and sending object IDshandling SOAP headers section on page 415.

439
OpenEdge Development: Web Services

This is the SOAP response message returned by the WSA with the value ("Hoops") for the
output parameter, CustomerName:

SOAP response message for method output parameters

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Body>
<ns1:FindCustomerByNumResponse xmlns:ns1="urn:OrderSvc:OrderInfo"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<CustomerName xsi:type="xsd:string">Hoops</CustomerName>
</ns1:FindCustomerByNumResponse>
</soap:Body>
</soap:Envelope>

If an error occurred at any point after the SOAP request message was received by the WSA, a
SOAP fault message would be returned instead of the SOAP response message shown in the
example. For information on SOAP fault messages returned for a method, see the Handling
Web service errors and SOAP faults section on page 440.

Handling Web service errors and SOAP faults

Clients receive Web service errors in the form of a SOAP fault. A SOAP fault specifies a
particular format for the body of SOAP response messages that return errors instead of
successful responses to SOAP requests. Errors are also reflected in log files for various
components of the OpenEdge Web services tools and the Web server or JSE. Run-time errors,
which are normally returned to the client application, can occur at one of the following points
in a message exchange:

Client errors occur:

Before a request is sent to the Web service. The nature of these errors and how they
are propagated depends on the client platform.

While the request is being sent to the Web service. These errors can be written to a
log and might result in a SOAP fault.

Server errors occur after the Web service begins processing the request, preparing and
sending the request to the AppServer. These errors can be written to a log and result in a
SOAP fault.

440
 General Client Programming Model for Progress 4GL Web Services

Client programming for SOAP faults

Client interfaces typically convert SOAP faults to client exceptions. Client code should handle
SOAP faults and alert the user. Client languages catch errors in different ways. One of the more
common techniques is to use try...catch blocks such as those used in Java and VB.NET.

Note: For the Progress 4GL, OpenEdge translates SOAP faults into Progress 4GL errors and
provides access to the SOAP fault information. For more information, see Chapter 12,
Handling Errors in Progress 4GL Requests to Web Services.

Caution: In any catch block or other error routine where you exit the program, you must
release all Web service objects that you have created in the program.

This is the general format for a SOAP fault, with content indicated by the XML comments:

SOAP faultsgeneral format

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here>
<soap:Body>
<soap:Fault>
<faultcode> <!-- Client or Server Environment --> </faultcode>
<faultstring> <!-- Basic Error Message (12345) -->
</faultstring>
<detail>
<ns1:FaultDetail
soap:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:ns1="http://... WSA root URL ...">
<errorMessage xsi:type="xsd:string"><!-- Initial error
message (99999) --></errorMessage>
<requestID xsi:type="xsd:string"> <!-- Unique request ID -->
</requestID>
</ns1:FaultDetail>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

For more information on catching and viewing SOAP faults and working with log files to debug
4GL Web services, see Chapter 7, Testing and Debugging Progress 4GL Web Services.

441
OpenEdge Development: Web Services

442
 5
Sample Code with SOAP Messages for
Progress 4GL Web Services

The following samples provide individual examples of how SOAP messages are sent between
the client and Web service, and code that produces some of these messages. The language used
for both the client and interface code samples described in the following sections is VB.NET:

Sample Web service specifications

Accessing a session-managed Web service

Accessing a session-free Web service

Running a Progress non-persistent procedure

Creating and using a ProcObject

Running an internal procedure or user-defined function

Creating and using a SubAppObject

Releasing an object

Passing static and dynamic temp-table parameters

Receiving a SOAP fault message

Learning more about SOAP

OpenEdge Development: Web Services

Sample Web service specifications

These examples rely on sample Web service specifications shown in Table 51.

Table 51: Sample Web service specifications

Property or component Configuration, value, or name

Session model Managed

Note: Some information and examples are also provided to
show session-free interactions.

TargetNamespace "urn:OrderSvc"

AppObject OrderInfo

ProcObject CustomerOrder

SubAppObject Payroll

Some of the information presented in these examples provides a review of concepts introduced
and described in previous chapters of this manual. Note that some SOAP messages and code
samples are edited for brevity.

Client references to the sample VB.NET interface include the following method declarations for
these interface objects:

Interface AppObject, OrderInfo:

VB.NET method declarations on AppObject, OrderInfo

Public Sub Connect_OrderInfo(

ByVal userId As String,
ByVal password As String,
ByVal appServerInfo As String)
Public Sub FindCustomerByNum(
ByVal CustomerNumber As Integer,
ByRef CustomerName As String)
Public Function CreatePO_CustomerOrder
(ByVal custNum As Integer) As String
Public Sub CreateAO_Payroll( )
Public Sub Release_OrderInfo( )

52
 Sample Code with SOAP Messages for Progress 4GL Web Services

The CreatePO_Object method can be represented as a VB.NET Sub or Function. If the

persistent procedure defined in ProxyGen is specified to return the Progress 4GL
RETURN-VALUE, it is represented, like the example, as a Function. For more information, see
OpenEdge Development: Open Client Introduction and Programming.

Interface ProcObject, CustomerOrder:

VB.NET method declarations on ProcObject, CustomerOrder

Public Sub GetOrderDetails(

ByRef OrderDetails( ) As OrderDetailsRow)
Public Function GetTotalOrdersByNumber
(ByVal Threshold As Decimal) As Integer
Public Sub Release_CustomerOrder( )

Interface SubAppObject, Payroll:

VB.NET method declarations on SubAppObject, Payroll

Public Sub IncreaseSalary(

ByVal EmployeeNumber As Integer,
ByVal Increase As Decimal)
Public Sub Release_Payroll( )

53
OpenEdge Development: Web Services

Accessing a session-managed Web service

To access a session-managed Web service, you must help to maintain connection context by
passing object IDs associated with each request.

To begin using a session-managed Web service:

1. Instantiate (create) the AppObject as appropriate for the client platform.

2. Connect to an AppServer by calling the connect method on the AppObject before calling
any other Web Service (AppObject) method.

3. Obtain the AppObject ID value from the SOAP response header for the connect method
and use it for all subsequent calls to methods on the session-managed AppObject.

4. Invoke any available methods on the AppObject, as required.

5. Ensure that the last method you invoke on the AppObject is the objects release method.
For more information, see the Releasing an object section on page 518.

As with other Open Clients, there is no Progress 4GL involved in implementing the connect
method on an AppObject. For Web services, however, the operation is an object method that is
required by the WSA.

This is a VB.NET declaration for an AppObject connect method, Connect_OrderInfo( ):

VB.NET prototype for an AppObject Connect_Object method

Public Sub Connect_OrderInfo(

ByVal userId As String,
ByVal password As String,
ByVal appServerInfo As String)

Note: For more information on the parameters to this method, see the sections on connecting
to an AppServer in OpenEdge Development: Open Client Introduction and
Programming. Note that there is no AppServer URL parameter. For a Web service
(unlike other Open Client applications), the deployer manages the AppServer
connection information for each Web service through the WSA instance where the Web
service is deployed. Each deployed Web service has writable properties to specify this
information. For more information, see the sections on Web service deployment in
OpenEdge Application Server: Administration.

54
 Sample Code with SOAP Messages for Progress 4GL Web Services

When the client executes the connect method, the SOAP response message contains a SOAP
header with the AppObject ID. You must send this AppObject ID in the SOAP header of the
request message for every subsequent method call on the AppObject.

This is a sample instantiation and invocation of the connect method on the OrderInfo
AppObject:

VB.NET client code for the connect method on AppObject, OrderInfo

webService = New OrderSvc.OrderInfoObj( )

webService.Connect_OrderInfo( "", "", "" )

This is a sample RPC/Encoded SOAP request message that might be generated from invoking
the Connect_OrderInfo( ) method, as in the example:

SOAP connect request for AppObject, OrderInfo

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Body
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:Connect_OrderInfo xmlns:q1="urn:OrderSvc:OrderInfo">
<userId xsi:type="xsd:string" />
<password xsi:type="xsd:string" />
<appServerInfo xsi:type="xsd:string" />
</q1:Connect_OrderInfo>
</soap:Body>
</soap:Envelope>

Note the data for the request highlighted in the example for parameters passed as empty strings.

55
OpenEdge Development: Web Services

This is a sample RPC/Encoded SOAP response that might be generated by the WSA as a
response to the Connect_OrderInfo( ) method:

SOAP response to OrderInfo AppObject connect request

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<t:OrderInfoID xmlns:t="urn:OrderSvc:OrderInfo"
soap:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/>
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000001|AO>;M/IryPm3piDcF/W5DsH4GA==</UUID>
</t:OrderInfoID>
</soap:Header>
<soap:Body>
<ns1:Connect_OrderInfoResponse xmlns:ns1="urn:OrderSvc:OrderInfo"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</soap:Body>
</soap:Envelope>

Note the value for the returned AppObject ID, OrderInfo, highlighted in the example. Thus, the
SOAP response header returns the following AppObject ID contained in the OrderInfoID
element:

2e62cab6b81150d5:167f64e:f295e997b0:-8000;<OrderInfo|PX-000001|AO>;M/IryPm3p
iDcF/W5DsH4GA==

56
 Sample Code with SOAP Messages for Progress 4GL Web Services

Accessing a session-free Web service

Because the AppObject for a session-free Web service maintains no connection to the Web
service, you can call the methods of a session-free AppObject with no preparation. When the
WSA instance receives such a method request, it simply locates an available AppServer
connection in the connection pool for that Web service and invokes the corresponding
procedure or function on the corresponding AppServer.

Note: All AppServers that participate in the connection pool for a session-free Web service are
assumed to share the same version and capabilities and have access to the same set of
databases and other shareable resources on a network. For more information, see
OpenEdge Application Server: Developing AppServer Applications.

To use a session-free Web service:

1. Instantiate (create) the AppObject as appropriate for the client platform:

VB.NET client code to instantiate session-free AppObject, OrderInfo

webService = New OrderSvc.OrderInfoObj( )

2. Invoke any available methods on the AppObject, as required.

Running a Progress non-persistent procedure

Methods that run a non-persistent procedure:

Can appear on any AppObject or SubAppObject.

Require an object ID in the SOAP request header for each method invocation unless the
object is a session-free AppObject.

57
OpenEdge Development: Web Services

This is the Progress 4GL prototype for the sample FindCustomerByNum( ) method:

Progress 4GL prototype for a non-persistent external procedure

/* FindCustomerByNum.p */

DEFINE INPUT PARAMETER CustomerNumber AS INTEGER.

DEFINE OUTPUT PARAMETER CustomerName AS STRING.

This is a sample VB.NET declaration for the Progress non-persistent procedure method,
FindCustomerByNum( ):

VB.NET prototype for a method that runs a Progress non-persistent procedure

Public Sub FindCustomerByNum(

ByVal CustomerNumber As Integer,
ByRef CustomerName As String)

Note: Methods that run a Progress 4GL procedure always return a String for
Document/Literal, and return a String for RPC/Encoded and RPC/Literal only if
specified in ProxyGen.

This is a sample call to this method:

VB.NET client code calling an external procedure method

Dim CustomerName As String

webService.FindCustomerByNum(3, CustomerName)

58
 Sample Code with SOAP Messages for Progress 4GL Web Services

This is a sample RPC/Encoded SOAP request that might be generated from this
FindCustomerByNum( ) method invocation:

SOAP request from calling the FindCustomerByNum procedure method

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<q1:OrderInfoID id="h_id1"
xmlns:q1="urn:OrderSvc:OrderInfo">
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000001|AO>;M/IryPm3piDcF/W5DsH4GA==</UUID>
</q1:OrderInfoID>
<soap:Header>
<soap:Body
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:FindCustomerByNum xmlns:q1="urn:OrderSvc:OrderInfo">
<CustomerNumber xsi:type="xsd:int">3</CustomerNumber>
</q1:FindCustomerByNum>
</soap:Body>
</soap:Envelope>

Note the following:

AppObject ID (OrderInfoID) sent using the <UUID> element of the SOAP header.

Data for the request highlighted in the example, including the request for a
CustomerNumber value of 3.

This is a sample RPC/Encoded SOAP response that is generated by the WSA from this
invocation of the FindCustomerByNum( ) method:

SOAP response from calling the FindCustomerByNum method

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Body>
<ns1:FindCustomerByNumResponse xmlns:ns1="urn:OrderSvc:OrderInfo"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<CustomerName xsi:type="xsd:string">Hoops</CustomerName>
</ns1:FindCustomerByNumResponse>
</soap:Body>
</soap:Envelope>

Note: The CustomerName value, "Hoops", returned and highlighted in the example.

59
OpenEdge Development: Web Services

Creating and using a ProcObject

Each AppObject and SubAppObject that defines ProcObjects also defines a built-in class
factory method specifically for each ProcObject. This method runs a persistent procedure on the
AppServer that thereby establishes a persistent AppServer session context that is encapsulated
by the ProcObject for access by the client.

To create and use a ProcObject:

1. Instantiate (create) the ProcObject as appropriate for the client platform.

2. Call the class factory method for this ProcObject on the parent AppObject or
SubAppObject to run the persistent procedure on the AppServer.

3. Obtain the ProcObject ID value from the response header of the class factory method. Use
this ProcObject ID for all subsequent calls to methods on the ProcObject.

4. Invoke any available methods on the ProcObject.

5. Ensure that the last method you invoke on the ProcObject is the objects release method.
For more information, see the Releasing an object section on page 518.

Note: You can instantiate a ProcObject either before or after calling the class factory method
and getting the ProcObject ID, but you must complete all of these steps before you
invoke methods on the ProcObject.

ProcObject session context

For a session-managed ProcObject, the method establishes the persistent session context using
the same AppServer connection as the parent AppObject. For a session-free ProcObject, the
method establishes the persistent session context on any AppServer that the WSA makes
available through the Web service connection pool, and the client connection to that context
persists until the ProcObject is released. Note that for multiple ProcObjects defined for the same
session-free Web service, no two objects ever share the same session context. While for a
session-managed Web service, all defined ProcObjects always share the same session context.

510
 Sample Code with SOAP Messages for Progress 4GL Web Services

ProcObject IDs
You use the same type of class factory method to create ProcObjects for both session-managed
and session-free Web Services. For a ProcObject whose defining parent is a SubAppObject or
a session-managed AppObject, you must send the object ID of the parent in the SOAP request
message header. However, for a ProcObject whose defining parent is a session-free AppObject,
you do not have an AppObject ID to send in the SOAP request header when you invoke the class
factory method to create the ProcObject.

For every ProcObject, regardless of its parent, the SOAP response header for the class factory
method returns a ProcObject ID that associates the ProcObject session context with the client.
You must send this ProcObject ID in the SOAP request header for all other method calls on the
ProcObject.

ProcObject class factory methods

This the Progress 4GL prototype for the persistent procedure that runs for the sample
ProcObject class factory method, CreatePO_CustomerOrder( ):

Progress 4GL prototype for a persistent procedure to implement a ProcObject

/* CustomerOrder.p */

DEFINE INPUT PARAMETER custNum AS INTEGER.

Note: The parameter list for the persistent procedure that runs for the ProcObject class factory
method is AppServer application dependent, and is the basis for creating the parameter
list of the ProcObject class factory method. A persistent procedure can also be specified
in ProxyGen to return a string value using the 4GL RETURN statement.

This is a VB.NET declaration for the ProcObject class factory method,

CreatePO_CustomerOrder( ):

VB.NET prototype for the ProcObject CreatePO_CustomerOrder method

Public Function CreatePO_CustomerOrder

(ByVal custNum As Integer) As String

511
OpenEdge Development: Web Services

Note: This method maps to a persistent procedure that has been specified to return the string
from the 4GL RETURN-VALUE function.

The following lines of code:

1. Instantiate the ProcObject on the client, enabling access to its methods.

2. Call the CreatePO_CustomerOrder( ) method on the AppObject, webService, to create

the ProcObject, CustomerOrder, on the WSA and run CustomerOrder.p persistently.

3. Copy the ProcObject ID to the ProcObject from the AppObject (webService) that creates
the ProcObject.

VB.NET client code to create the ProcObject, CustomerOrder

custOrder = New OrderSvc.CustomerOrderObj( )

custName = webService.CreatePO_CustomerOrder(3)
custOrder.CustomerOrderIDValue = webService.CustomerOrderIDValue

This is a sample RPC/Encoded SOAP request that might be generated from invoking the
CreatePO_CustomerOrder( ) method to create the ProcObject, passing in a custNum value of 3:

SOAP request to create ProcObject, CustomerOrder

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<q1:OrderInfoID id="h_id1"
xmlns:q1="urn:OrderSvc:OrderInfo">
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000001|AO>;M/IryPm3piDcF/W5DsH4GA==</UUID>
</q1:OrderInfoID>
</soap:Header>
<soap:Body
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:CreatePO_CustomerOrder xmlns:q1="urn:OrderSvc:OrderInfo">
<custNum xsi:type="xsd:int">3</custNum>
</q1:CreatePO_CustomerOrder>
</soap:Body>
</soap:Envelope>

Note the value for the request highlighted in the example, especially the AppObject ID sent for
the AppObject, OrderInfo, which is the parent of the ProcObject being created for customer
number 3.

512
 Sample Code with SOAP Messages for Progress 4GL Web Services

This is a sample RPC/Encoded SOAP response that is generated by the WSA from this
invocation of the CreatePO_CustomerOrder( ) method:

SOAP response from creating ProcObject, CustomerOrder

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<t:CustomerOrderID xmlns:t="urn:OrderSvc:CustomerOrder"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000002|PO>;G1Vc/vmohvLnwxQQXwA6Cg==</UUID>
</t:CustomerOrderID>
</soap:Header>
<soap:Body>
<ns1:CreatePO_CustomerOrderResponse xmlns:ns1="urn:OrderSvc:OrderInfo"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<result xsi:type="xsd:string">Hoops</result>
</ns1:CreatePO_CustomerOrderResponse>
</soap:Body>
</soap:Envelope>

Note the value returned for the CustomerOrder ProcObject ID highlighted in the example. The
Web service returns this ProcObject ID even if it is session free, to allow the ProcObject to
access its own AppServer session context.

Thus, the SOAP response header returns the following ProcObject ID contained in the
CustomerOrderID element:

2e62cab6b81150d5:167f64e:f295e997b0:-8000;<OrderInfo|PX-000002|PO>;G1Vc/vmoh
vLnwxQQXwA6Cg==

Finally, note the 4GL RETURN-VALUE, result, returned from running the persistent procedure,
which returns the customer name, "Hoops".

513
OpenEdge Development: Web Services

Running an internal procedure or user-defined function

Methods to run a Progress internal procedure and user-defined function of a persistent
procedure (ProcObject) are indistinguishable in client code. These methods:

Run only in the context of a defining ProcObject.

Require a ProcObject ID in the SOAP request header, which is the object ID of the
defining ProcObject.

This is the Progress 4GL prototype for the sample user-defined function,
GetTotalOrdersByNumber( ):

Progress 4GL prototype for a user-defined function

/* CustomerOrder.p */

FUNCTION GetTotalOrdersByNumber RETURNS INTEGER

(Threshold AS DECIMAL):

This is a VB.NET declaration for the Progress user-defined function method,

GetTotalOrdersByNumber( ):

VB.NET prototype for a Progress user-defined function method

Public Function GetTotalOrdersByNumber

(ByVal Threshold As Decimal) As Integer

The following is a sample method call for the user-defined function method,
GetTotalOrdersByNumber, which is an interface method on the sample ProcObject,
CustomerOrder:

VB.NET client code of method to run a Progress user-defined function

totNumber = custOrder.GetTotalOrdersByNumber(2150.99)

Note that user-defined function methods return a value whose data type maps to the Progress
data type of the user-defined functions return value.

514
 Sample Code with SOAP Messages for Progress 4GL Web Services

This is a sample RPC/Encoded SOAP request that might be generated from invoking the
GetTotalOrdersByNumber( ) method to execute the Progress user-defined function, passing in
a Threshold order value of 2150.99:

SOAP request for user-defined function method, GetTotalOrdersByNumber

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<q1:CustomerOrderID id="h_id1" xmlns:q1="urn:OrderSvc:CustomerOrder">
<UUID xsi:type="xsd:string">2e62cab6b81150d5:167f64e:f295e997b0:
-8000;<OrderInfo|PX-000002|PO>;G1Vc/vmohvLnwxQQXwA6Cg==</UUID>
</q1:CustomerOrderID>
</soap:Header>
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:GetTotalOrdersByNumber xmlns:q1="OrderSvc:CustomerOrder">
<Threshold xsi:type="xsd:decimal">2150.99</Threshold>
</q1:GetTotalOrdersByNumber>
</soap:Body>
</soap:Envelope>

Note the object ID for the ProcObject, CustomerOrder, sent to make the request on a method of
the ProcObject.

This is the SOAP response returning a function value of 5, which is the total number of orders
that satisfy the specified order Threshold value:

SOAP response from calling the GetTotalOrdersByNumber method

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Body>
<ns1:GetTotalOrdersByNumberResponse
xmlns:ns1="urn:OrderSvc:CustomerOrder"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<result xsi:type="xsd:int">5</result>
</ns1:GetTotalOrdersByNumberResponse>
</soap:Body>
</soap:Envelope>

515
OpenEdge Development: Web Services

Creating and using a SubAppObject

Any AppObject that defines SubAppObjects also defines a built-in class factory method
specifically for each SubAppObject. This method establishes an association between the client
and the SubAppObject managed on the WSA for use by the client.

To create and use a SubAppObject:

1. Call the class factory method for this SubAppObject on the parent AppObject.

2. Instantiate (create) the SubAppObject as appropriate for the client platform.

3. Obtain the SubAppObject ID value from the response header. You use the SubAppObject
ID for all subsequent calls to methods on the SubAppObject.

4. Invoke any available methods on the SubAppObject.

5. Ensure the last method you invoke on the SubAppObject is the objects release method.
For more information, see the Releasing an object section on page 518.

Note: You can instantiate a SubAppObject either before or after calling the class factory
method, but you must do both to invoke methods on the SubAppObject.

SubAppObject/Client associations
For a session-managed SubAppObject, the class factory method associates the object with the
same AppServer session context established by the parent AppObject, sharing the same client
connection to the AppServer. For a session-free SubAppObject, this method establishes an
association between the client and the object managed for the Web service by the WSA.
However, there is no connection or session context established for the client of a session-free
SubAppObject.

516
 Sample Code with SOAP Messages for Progress 4GL Web Services

SubAppObject IDs
You use the same type of class factory method to create SubAppObjects for both
session-managed and session-free Web Services. For a SubAppObject whose defining parent is
a session-managed AppObject, you must send the AppObject ID of the parent in the SOAP
request message header. However, for a SubAppObject whose defining parent is a session-free
AppObject, you do not have an AppObject ID to send in the SOAP request header when you
invoke the class factory method to create the SubAppObject.

For every SubAppObject, regardless of the session model, the SOAP response header for the
class factory method returns a SubAppObject ID that uniquely associates the SubAppObject
session with the client. You must send this SubAppObject ID in the SOAP request header for
all other method calls on the SubAppObject. You must also ensure that the last method you call
on the SubAppObject is the objects release method. For more information, see the Releasing
an object section on page 518.

SubAppObject class factory methods

As with other Open Clients, there is no Progress 4GL involved in implementing the class factory
method on a SubAppObject. However, for Web services, the operation is an object method is
required by the WSA.

This is a VB.NET declaration for the SubAppObject class factory method,

CreateAO_Payroll( ):

VB.NET prototype for an SubAppObject CreateAO_Payroll method

Public Sub CreateAO_Payroll( )

The following lines of code:

1. Call the CreateAO_Payroll( ) method on the AppObject, webService, to create the

SubAppObject, Payroll, on the WSA.

2. Instantiate the SubAppObject on the client, enabling access to its methods.

3. Copy the SubAppObject ID from the AppObject (webService) to the SubAppObject.

4. Invoke the IncreaseSalary( ) method on the Payroll SubAppObject.

517
OpenEdge Development: Web Services

VB.NET declaration of method to create a SubAppObject

webService.CreateAO_Payroll( )
Payroll = New OrderSvc.PayrollObj( )
Payroll.PayrollIDValue = webService.PayrollIDValue
Payroll.IncreaseSalary(54, 4500.00)

Note: The SOAP request/response messages for creating SubAppObjects are very similar to
those for creating ProcObjects. For more information, see the Creating and using a
ProcObject section on page 510.

Releasing an object
When you are finished using any Web service object, except a session-free AppObject, you
must invoke the built-in release method to release that object and return its resources for use by
other clients:

As with other Open Clients, there is no Progress 4GL involved in implementing the release
method on an Open Client object. However, for Web services, the operation is an object method
is required by the WSA.

This is a VB.NET declaration for the AppObject release method, Release_OrderInfo( ):

VB.NET prototype for a Release_Object method

Public Sub Release_OrderInfo( )

Public Sub Release_Payroll( )
Public Sub Release_CustomerOrder( )

Although this method takes no parameters, you must remember to send the object ID for the
object you are releasing in the SOAP header of the release request message.

518
 Sample Code with SOAP Messages for Progress 4GL Web Services

These are sample calls to the release methods declared for the sample Web service:

VB.NET client code calling methods to release objects

custOrder.Release_CustomerOrder( )
Payroll.Release_Payroll( )
webService.Release_OrderInfo( )

Note: AppServer connections used by session-free methods are usually returned to the Web
service connection pool after the SOAP response message for the release method is
returned.

Passing static and dynamic temp-table parameters

The following examples show how parameters are passed for static and dynamic temp-tables
using various code and SOAP message scenarios, including:

Invoking a method with a TABLE parameter (RPC/Encoded).

Invoking a method with a TABLE-HANDLE parameter (RPC/Encoded).

Invoking a method with a TABLE parameter

(RPC/Encoded)
To invoke a method that passes a TABLE parameter, the client application typically must:

Create rows using the interface object that represents the TABLE row.

Insert the rows in an array that represents the TABLE parameter.

This the Progress 4GL prototype for a sample method, staticTT( ), that passes a TABLE
parameter:

Progress 4GL prototype that passes a TABLE parameter

/* staticTT.p */

DEFINE INPUT-OUTPUT PARAMETER TABLE FOR ttEmp.

519
OpenEdge Development: Web Services

This is the RPC/Encoded WSDL request message for the staticTT( ) method, which has a
TABLE parameter, ttEmp. The parameter, ttEmp, is a SOAP array of rows (ttEmpRow) defined in
the Types section of the WSDL:

RPC/Encoded WSDL definition for TABLE parameter, ttEmp

<message name="Employee_staticTT">
<part name="ttEmp" type="S2:ArrayOfstaticTT_ttEmpRow"/>
</message>

The following are the WSDL row and SOAP array definitions for the TABLE:

TABLE row schema

<complexType name="staticTT_ttEmpRow">
<sequence>
<element name="Name" nillable="true" type="xsd:string"/>
<element name="Number" nillable="true" type="xsd:int"/>
</sequence>
</complexType>

TABLE parameter for RPC/Encoded

<complexType name="ArrayOfstaticTT_ttEmpRow">
<complexContent>
<restriction base="soapenc:Array">
<attribute ref="soapenc:arrayType"
wsdl:arrayType="S2:staticTT_ttEmpRow[]"/>
</restriction>
</complexContent>
</complexType>

As a point of comparison here is the RPC/Literal and Document/Literal representation of this

same TABLE parameter definition in WSDL:

TABLE parameter for RPC/Literal and Document/Literal

<complexType name="staticTT_ttEmpParam">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="ttEmpRow"
type="S2:staticTT_ttEmpRow" />
</sequence>
</complexType>

520
 Sample Code with SOAP Messages for Progress 4GL Web Services

This is the declaration for a VB.NET client interface method, staticTT( ), which has a TABLE
parameter, ttEmp, passed as the class, staticTT_ttEmpRow:

VB.NET declaration of interface method passing static TEMP-TABLE, ttEmp

Public Class staticTT_ttEmpRow

Public Name As String
Public Number As Integer
End Class

Public Sub staticTT(ByRef ttEmp( ) As staticTT_ttEmpRow)

The following client code defines a two row array (myTempTable) according to a defined schema
(staticTT_ttEmpRow), then defines and creates two rows assigned with values. It then
initializes the array (as TABLE, ttEmp) with the two rows and passes it to the staticTT( )
interface method, which passes the TABLE to the Web service:

VB.NET client code passing TABLE, ttEmp, to an interface method

Dim myTempTable(1) as webService.staticTT_ttEmpRow

Dim myRow1 as webService.staticTT_ttEmpRow =
New webService.staticTT_ttEmpRow( )
Dim myRow2 as webService.staticTT_ttEmpRow =
New webService.staticTT_ttEmpRow( )

myRow1.Name = "Fred"
myRow1.Number = 1
myRow2.Name = "Barney"
myRow2.Number = 2

myTempTable(0) = myRow1
myTempTable(1) = myRow2

webService.staticTT(myTempTable)

521
OpenEdge Development: Web Services

The following is an RPC/Encoded SOAP message that this call to staticTT( ) might send:

RPC/Encoded SOAP request to pass a TABLE parameter

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<q1:EmployeeID id="h_id1" xmlns:q1="urn:EmployeeSrvc:Employee">
<UUID xsi:type="xsd:string">2e62cab6b81150d5:-1380e8e:f27fb934f4:
-8000;<Employee|PX-000004|AO>;5REiR9inxXQi4s6ghRWkfg==</UUID>
</q1:EmployeeID>
</soap:Header>
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:staticTT xmlns:q1="urn:EmployeeSrvc:Employee">
<ttEmp href="#id1" />
</q1:staticTT>
<soapenc:Array id="id1" xmlns:q2="urn:EmployeeSrvc:Employee"
soapenc:arrayType="q2:staticTT_ttEmpRow[2]">
<Item href="#id2" />
<Item href="#id3" />
</soapenc:Array>
<q3:staticTT_ttEmpRow id="id2" xsi:type="q3:staticTT_ttEmpRow"
xmlns:q3="urn:EmployeeSrvc:Employee">
<Name xsi:type="xsd:string">Fred</Name>
<Number xsi:type="xsd:int">1</Number>
</q3:staticTT_ttEmpRow>
<q4:staticTT_ttEmpRow id="id3" xsi:type="q4:staticTT_ttEmpRow"
xmlns:q4="urn:EmployeeSrvc:Employee">
<Name xsi:type="xsd:string">Barney</Name>
<Number xsi:type="xsd:int">2</Number>
</q4:staticTT_ttEmpRow>
</soap:Body>
</soap:Envelope>

Note: The staticTT( ) method must send the object ID for the Employee AppObject in the
SOAP request header because staticTT( ) is a method on the session-managed
AppObject.

522
 Sample Code with SOAP Messages for Progress 4GL Web Services

As a point of comparison, the following is a Document/Literal SOAP message that this call to
staticTT( ) might send:

Document/Literal SOAP request to pass a TABLE parameter

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header>
<EmployeeID xmlns="urn:EmployeeSrvc:Employee">
<UUID>2e62cab6b81150d5:-1380e8e:f27fb934f4:
-8000;<Employee|PX-000004|AO>;5REiR9inxXQi4s6ghRWkfg==</UUID>
</EmployeeID>
</soap:Header>
<soap:Body>
<staticTT xmlns="urn:EmployeeSrvc:Employee">
<ttEmp>
<ttEmpRow>
<Name>Fred</Name>
<Number>1</Number>
</ttEmpRow>
<ttEmpRow>
<Name>Barney</Name>
<Number>2</Number>
</ttEmpRow>
</ttEmp>
</staticTT>
</soap:Body>
</soap:Envelope>

Note: The staticTT( ) method must send the object ID for the Employee AppObject in the
SOAP request header because staticTT( ) is a method on the session-managed
AppObject.

523
OpenEdge Development: Web Services

Invoking a method with a TABLE-HANDLE parameter

(RPC/Encoded)
To invoke a method that passes a TABLE-HANDLE parameter:

The client application must create and send an XML Schema along with the data to fully
describe the dynamic temp-table in the SOAP request message. The TABLE-HANDLE
parameter in a SOAP request or response consists of an XML <DataSet> element
containing two child elements:

An XML Schema element, <schema>, representing the schema for the

TABLE-HANDLE.

An XML representation of data using an element, <Data>, with each row represented
as a sub-element, <Item>.

The client application must parse the XML Schema and data from the SOAP response
message to make the TABLE-HANDLE accessible as native data within the application.

This is the Progress 4GL prototype for a sample method, dynttIO( ), that passes a
TABLE-HANDLE parameter:

Progress 4GL prototype that passes a TABLE-HANDLE parameter

/* dynttIO.p */

DEFINE INPUT-OUTPUT PARAMETER TABLE-HANDLE ttHandle.

This is the RPC/Encoded WSDL sample definition for the dynttIO( ) method request
message, which also defines a TABLE-HANDLE parameter (ttHandle). The parameters type is the
standard TABLE-HANDLE parameter definition (TableHandleParam) specified in the Types
section of the WSDL:

RPC/Encoded WSDL definition for TABLE-HANDLE parameter, ttHandle

<message name="DynTT_dynttIO">
<part name="ttHandle" type="S2:TableHandleParam"/>
</message>

524
 Sample Code with SOAP Messages for Progress 4GL Web Services

The following WSDL sample shows the definition for TableHandleParam, used for all dynamic
TABLE-HANDLE parameters:

TABLE-HANDLE definition for all TABLE-HANDLE parameters

<complexType name="TableHandleParam">
<sequence>
<any namespace="##local"/>
</sequence>
</complexType>

This is the declaration for a VB.NET client interface method (dynTTIO( )) which has a
TABLE-HANDLE parameter, ttHandle, as a VB.NET object:

VB.NET declaration of interface method passing TABLE-HANDLE, ttHandle

Public Sub dynttIO(ByRef ttHandle As Object)

The following VB.NET client code passes the dyntt object representing a TABLE-HANDLE to the
dynttIO( ) method:

VB.NET client code passing TABLE-HANDLE, ttHandle, to interface method

Dim dyntt as Object

... Code to build up the dyntt Object (XML Schema and data)

webService.dynttIO(dyntt)

For more information on how you might manage TABLE-HANDLE parameters in VB.NET, see the
subsections on handling TABLE-HANDLE parameters in Chapter A, Developing a .NET Client to
Access Progress 4GL Web Services, and in Java see the subsections on handling
TABLE-HANDLE parameters in Chapter B, Developing a Java Client to Access Progress 4GL
Web Services.

525
OpenEdge Development: Web Services

This is the structure of the RPC/Encoded SOAP request message that the sample dynttIO
method sends to pass a dynamic temp-table that you create for the ttHandle TABLE-HANDLE
parameter (see the Invoking a method with a TABLE-HANDLE parameter (RPC/Encoded)
section on page 524):

SOAP request (RPC/Encoded) for TABLE-HANDLE, ttHandle

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope namespaces defined here...>
<soap:Header .../>
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:dynttIO xmlns:q1="urn:DynTTSrvc:DynTT">
<ttHandle>
<DataSet xmlns="">
<schema>
<!-- Schema definition goes here -->
</schema>
<Data>
<!-- Data goes here -->
</Data>
</DataSet>
</ttHandle>
</q1:dynttIO>
</soap:Body>
</soap:Envelope>

The ttHandle TABLE-HANDLE parameter becomes an XML <ttHandle> element containing the
<DataSet> element that contains the schema and the data.

Note: Not shown is any required object ID that must be sent in the SOAP header for the object
on which dynttIO( ) is invoked.

526
 Sample Code with SOAP Messages for Progress 4GL Web Services

This is a sample XML Schema created by VB.NET for the TABLE-HANDLE contained by the
sample <DataSet> element in the sample RPC/Encoded SOAP request:

TABLE-HANDLE <schema> element for an RPC/Encoded SOAP request

<xs:schema id="Data" xmlns=""

xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name="Data" msdata:IsDataSet="true">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<xs:element name="Item">
<xs:complexType>
<xs:sequence>
<xs:element name="Name" type="xs:string"
minOccurs="0"/>
<xs:element name="Number" type="xs:int"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>

Note the definition of the <Data> element containing the data for the table, and how the column
type information is specified within the <Item> element.

This is a sample <Data> element you would create to accompany the specified schema in the
sample RPC/Encoded SOAP request, including the column values for the two rows initialized
in the sample VB.NET code:

TABLE-HANDLE <Data> element for an RPC/Encoded SOAP request

<Data>
<Item>
<Name>Fred</Name>
<Number>1</Number>
</Item>
<Item>
<Name>Barney</Name>
<Number>2</Number>
</Item>
</Data>

527
OpenEdge Development: Web Services

Receiving a SOAP fault message

The following sample SOAP fault shows the response to a request sent for an object
(OrderInfo) of a disabled Web service:

Caution: When exiting the program in response to a SOAP fault, you must release all Web
service objects you created in the program.

Sample SOAP fault for disabled Web service

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here>
<soap:Body>
<soap:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>An error was detected ... request. (10893)
</faultstring>
<detail>
<ns1:FaultDetail ... >
<errorMessage xsi:type="xsd:string">The urn:OrderSvc:OrderInfo
service is unavailable (10921)</errorMessage>
<requestID xsi:type="xsd:string"> 2e62cab6b81150d5:-17c6a3c:
f1dffbd11b:-8000#1f</requestID>
</ns1:FaultDetail>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

Note: SOAP fault messages conform to SOAP 1.1.

The contents of the highlighted SOAP elements include some of the key components of the fault
message, containing such error information as a general error code (<faultcode>) and message
(<faultstring>). These elements are followed by more detailed information, including the
message indicating a more precise cause for the error (<errorMessage>), and a unique identifier
for the request that returned the error (<requestID>). The contents of the <detail> element is
defined in the WSDL Types section. For more information on handling errors, including SOAP
fault messages generated for WSA-managed Web services, see Chapter 7, Testing and
Debugging Progress 4GL Web Services.

528
 Sample Code with SOAP Messages for Progress 4GL Web Services

Learning more about SOAP

While simple in concept, SOAP can be complex to interpret. For more information on working
with SOAP, see Simple Object Access Protocol (SOAP) 1.1 described at this URL:

http://www.w3.org/TR/SOAP

529
OpenEdge Development: Web Services

530
 6
Sample Progress 4GL Web Services and
Client Applications

This chapter describes how to access the sample applications installed with OpenEdge sample
4GL Web services and client applications for accessing them, as outlines in the following
sections:

Sample application directory structure

Using the sample applications

OpenEdge Development: Web Services

Sample application directory structure

OpenEdge includes three sample Progress 4GL Web services and several related sample client
applications written using the Microsoft .NET and Java Axis client platforms. Figure 61 shows
the directory structure under the OpenEdge installation directory where you can locate these
samples.

Figure 61: Progress 4GL Web services sample applications

62
 Sample Progress 4GL Web Services and Client Applications

The installation directory in this figure is C:\Progress\dlc. Thus, the folders under
C:\Progress\dlc\src\samples\webservices provide the following samples:

AppService The three Web services, including the ProxyGen project files to generate
the Web service definitions. These samples include one Web service that passes a dynamic
temp-table.

Java-Axis Java Axis client samples, including applications for sample session-free and
session-managed Web services, and in several choices of SOAP format. Also included
with these samples are sample Java helper classes for managing object IDs and dynamic
temp-table schemas and data.

Microsoft .NET client samples, including a C#.NET application for a session-free Web
service and VB.NET application for session-free and session-managed Web services.
These samples include the Web-services-tools-supported SOAP format choices that are
also supported by .NET.

Using the sample applications

For information on how to access and use these samples, see the README files provided in the
Java-Axis and Microsoft folders for the respective client platforms. For an introduction to the
available Java helper classes, see the Developing the Axis client application section on page
B15.

63
OpenEdge Development: Web Services

64
 7
Testing and Debugging Progress 4GL
Web Services

This chapter explains how to test and debug Progress 4GL Web services. It assumes you are
familiar with Web services and with the Web Services tools in OpenEdge, as described in the
preceding chapters of this manual. Information in this chapter is useful for both Web service and
client developers to troubleshoot 4GL Web services and client applications that access them.

This chapter contains the following sections:

Testing the AppServer application as a Web service

Setting error information levels

Identifying relevant log files

Working with SOAP faults

Using a SOAP message viewer

Identifying errors

Sample error scenarios

OpenEdge Development: Web Services

Testing the AppServer application as a Web service

You can generally use two different approaches for testing an AppServer application you have
written to support a Progress 4GL Web service:

Unit testing from the Progress 4GL From the 4GL, you can access AppServer
functionality directly or as a Progress 4GL Web service.

Testing from a Web service client From a Web service client using any platform,
including the 4GL, you can thoroughly test the Web service as it might behave in the
environment you plan to deploy it.

The approach that you take depends on your preferences, needs, and experience.

Unit testing from the Progress 4GL

Accessing the AppServer directly is useful for doing unit testing without having to bother with
the overhead and inconvenience of managing the Web service deployment environment. This
form of testing also eliminates some of the 4GL logic required to access a Web service.
However, it can provide a good measure of confidence in the basic integrity of the application
service itself.

Testing from a Web services client

This method allows you to create a client application environment and functionality exactly as
you expect real Web service clients to be created, and you can test the application end-to-end
using a complete Web service testing infrastructure.

The rapid prototyping capability of the Progress 4GL can also make it a convenient platform to
test the application service as a Web service, depending on the requirements of the Web service.
Some client platforms might handle certain types of Web service interaction more easily than
others. However, especially where the 4GL most easily handles a particular Web service
application feature, modifying an existing 4GL unit test bed to access the AppServer as a Web
service is a natural next step in testing Web service functionality.

Otherwise, especially if you expect your primary client base to use another platform, you might
want to test on that platform to fully understand what users of that platform need to do in order
to use the Web service that you plan to deploy.

72
 Testing and Debugging Progress 4GL Web Services

To test from a Web services client:

1. Configure the AppServer to support the required application session model:

For information on configuring the session-managed operating modes, see

OpenEdge Application Server: Developing AppServer Applications and the Progress
Explorer online help.

For information on configuring the state-free operating mode (session-free model)

see the Progress Explorer online help.

2. Define the Web service and generate the Web service mapping (WSM) file using
ProxyGen. For more information, see OpenEdge Development: Open Client Introduction
and Programming.

3. Generate a test WSDL file from ProxyGen when you generate the WSM file, or deploy the
WSM file to a WSA instance to obtain a deployed WSDL file. For more information on
deploying a Web service, see the sections on deploying and managing Web services in
OpenEdge Application Server: Administration.

4. Write the test client application, using the WSDL file to help generate client interfaces or
to manually write the code to invoke Web service requests. For more information, see Part
II, Clients Accessing Progress 4GL Web Services. For information on building a
Progress 4GL client to access your Web service, see Part III, Progress 4GL Clients
Accessing Industry Web Services.

5. Once you have an executable test client, ensure that the AppServer and WSA are running,
and the WSA instance where you deployed the Web service is enabled to allow client
access to the Web service. For more information on running and enabling the WSA for
Web service client access, see the sections on working with the WSA and deploying Web
services in OpenEdge Application Server: Administration.

6. Begin testing the client. For information on debugging Web services during testing, see
the Testing the AppServer application as a Web service section on page 72.

73
OpenEdge Development: Web Services

Setting error information levels

To make it easier to diagnose errors, you can control the amount of information provided for the
following sources of Web service error information:

WSA log file.

Web service SOAP (Simple Object Access Protocol) fault response messages.

AdminService log file.

AppServer log file.

NameServer log file.

For information on managing logging for the AdminService, NameServer, and in general for all
OpenEdge servers managed by the Progress Explorer Framework, see OpenEdge Getting
Started: Installation and Configuration for Windows or OpenEdge Getting Started: Installation
and Configuration for UNIX. For more information on managing logging for an AppServer, see
OpenEdge Application Server: Administration. The following sections describe how to control
logging and SOAP fault information output for the WSA and Web services.

WSA and Web service logging level properties

Table 71 shows the property files where these settings occur and the default installation
settings for basic properties that affect output for each of these information sources.

Table 71: Setting error levels for WSA and Web services

Affected error output Property files Default property setting

WSA log file ubroker.properties loggingLevel=2

(WSA properties)

*.props serviceLoggingLevel=2
(Web service properties)

SOAP fault response messages *.props serviceFaultLevel=2

(Web service properties)

74
 Testing and Debugging Progress 4GL Web Services

Note: For complete information on the log file settings for the WSA log file, including more
advanced logging properties, see the Progress Explorer online help and the
unbroker.properties.README file in the properties directory under the OpenEdge
installation directory.

Logging information
The properties in Table 71 have the following functions and value ranges (the greater the
value, the more information is provided):

loggingLevel Affects information logged for a single WSA instance. Set this property
to change the logging detail for WSA administration, WSDL document retrieval, user
authorization, and HTTP request handling. Valid values range between 1 and 4.

serviceLoggingLevel Affects information logged for a single deployed Web service.

Set this property to change the logging detail for the processing of a Web service client
request. Valid values range between 1 and 4.

serviceFaultLevel Affects the information returned in all SOAP faults from a single
deployed Web service. Set this property to change the level of detail returned for client
exceptions. Valid values are 2 or 3.

Hints for setting the WSA loggingLevel property

Set this property to the following value:

3 To get information about user authorization errors or to log the start of a new client
request for any Web service deployed to this WSA instance.

4 To get detailed information about WSA startup parameters.

75
OpenEdge Development: Web Services

Hints for setting the Web service serviceLoggingLevel

property
Set this property to the following value:

4 To record Web service request parameter values.

3 To track Web service request execution. Use this value during Web service
development to provide more information for each Web service request error.

2 To reduce logging overhead when the Web service is running in production. This
value only allows severe errors to be recorded that affect the Web service as a whole, and
no errors to be recorded for single Web service requests.

During production run time, you might temporarily set the value to 3 or 4 when working with a
specific client to resolve an error, then return the logging level to 2 for general client access
when the problem has been resolved.

Setting the logging level properties

Settings to the serviceLoggingLevel and serviceFaultLevel take effect immediately at run
time. You can also set an immediate run-time value for the WSA loggingLevel property, as
well as a persistent value that takes affect the next time the WSA is started.

To change these settings, use the Progress Explorer or the wsaman utility. If you are working
with a WSA installation on a system that does not have an AdminServer installed, you must edit
the ubroker.properties file to change the persistent value of loggingLevel property.

For more information on setting these logging level properties and their appropriate values
using the Progress Explorer, see the online help. You can also set the loggingLevel property If
you are using the wsaman utility, see the sections on the wsaman utility in OpenEdge Application
Server: Administration. For more information on the serviceLoggingLevel and
serviceFaultLevel properties, see the Web service properties reference sections of OpenEdge
Application Server: Administration.

For complete information on OpenEdge logging capabilities, see OpenEdge Development:

Debugging and Troubleshooting.

For more information on using log files, see the Identifying relevant log files section on page
77. For more information on handling SOAP faults, see the Working with SOAP faults
section on page 77.

76
 Testing and Debugging Progress 4GL Web Services

Identifying relevant log files

A common way to detect software errors of all kinds, not just Web service errors, is to examine
log files for error messages. Table 72 lists OpenEdge log files providing Web-service-related
messages. These files all reside in your OpenEdge work directory.

Table 72: OpenEdge log files providing Web service-related messages

This component... Logs messages here...

WSA instance instance-name.wsa.log

Web service instance-name.wsa.log

AdminServer adminserv.log

AppServer instance-name.broker.log
instance-name.server.log

NameServer instance-name.NS.log

For information on managing logging for the AdminService, NameServer, and in general for all
OpenEdge servers managed by the Progress Explorer Framework, see your OpenEdge
Installation and Configuration Guide. For more information on managing logging for an
AppServer, see OpenEdge Application Server: Developing AppServer Applications.

Working with SOAP faults

When an error occurs while processing a Web service client request, the WSA generates a
SOAP fault message and returns it to the client application. The client application should catch
all SOAP faults and handle them programmatically, perhaps by displaying an error message to
the user or by logging the fault information for review off line. If the client application does not
catch the SOAP fault, the behavior of the client application depends on the default error
handling of the client software development kit.

Setting the serviceFaultLevel property

You can control the amount of information provided with SOAP fault messages by how you set
the serviceFaultLevel property for a Web service. Any change in value takes effect
immediately at run time.

77
OpenEdge Development: Web Services

Set this property to the following value:

2 To log general error information in a production environment.

3 To log error information in a development environment or in a production

environment where more detailed information is required.

Note that all Web service logging and fault levels are controlled individually for each Web
service to further reduce processing overhead. For more information on setting this property,
see the Setting error information levels section on page 74.

Typical SOAP fault response message

The following is the content of a typical SOAP fault response that appears within the body of a
WSA-generated SOAP fault message:

<soap:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>An error was detected request. (10893) </faultstring>
<detail>
<ns1:FaultDetail soap:encodingStyle=http://schemas.xmlsoap.org//
xmlns:ns1="http://servicehost:8080/wsa/wsa1">
<errorMessage xsi:type=xsd:string">
The urn:OrderSvc:OrderInfo service is unavailable (10921)
</errorMessage>
<requestID xsi:type=xsd:string">
2e62cab6b81150d5:-17c6a3c:f1dffbd11b:-8000#1f
</requestID>
</ns1:FaultDetail>
</detail>
</soap:Fault>

Note that SOAP faults can be returned by the clients own SOAP libraries and might have a
different XML definition for the contents encapsulated by the <detail> element, depending on
the Web service client toolkit that is used. However, a SOAP fault generated by the OpenEdge
WSA always includes an <error Message> and <requestID> element within the <detail>
element section.

WSAs <errorMessage> element

The SOAP <faultstring> element provides only a very general description of the error. For
the most effective diagnostic detail, always look at the information provided by the
<errorMessage> element.

78
 Testing and Debugging Progress 4GL Web Services

WSAs <requestID> element

Use the information provided by the <requestID> element when you contact the Web service
deployer for assistance with an error. This information tells the Web service deployer whether
more information can be obtained from the WSA log file. For more information on how the
WSA uses the information in the <requestID> element to log information, see the How the
WSA logs Web service information section on page 712.

Handling SOAP faults programmatically

The client application should handle all SOAP faults. Many SOAP client toolkits convert SOAP
faults to client exceptions that can be handled in a try...catch block. The following code is a
VB.NET fragment from the sample applications installed with OpenEdge:

Try
' Code to access the Web service
...
Catch soapEx As System.Web.Services.Protocols.SoapException
Dim detail As String, reqId As String
detail = parseSoapException(soapEx.Detail, reqId)
MsgBox(detail, MsgBoxStyle.Critical, soapEx.Message)
End Try

In this example, parseSoapException( ) is a client helper function to parse the SOAP fault
detail provided in .NET sample code. You can find more examples like this in both the .NET
and Java sample client applications. For more information on these sample applications, see
Chapter 6, Sample Progress 4GL Web Services and Client Applications.

79
OpenEdge Development: Web Services

Using a SOAP message viewer

To view SOAP messages as they are sent and received, use a SOAP message viewer. Table 73
lists some examples.

Table 73: Some SOAP message viewers

This SOAP message viewer... Is...

WSAViewer Provided with the OpenEdge installation.

ProSOAPView Provided with the OpenEdge installation.

Microsoft SOAP Toolkit Available for free download from Microsofts Web
site.

To use a SOAP message viewer:

1. Change the Web service client to send requests to the port of the SOAP message viewer
by changing the SOAP end points URL host and port fields.

2. Configure the SOAP message viewer to forward requests to the host and port of the WSA,
where the Web service is deployed, and run the viewer.

To configure and run WSAViewer:

1. Enter the wsaviewer command from a Proenv shell using the following syntax:

Syntax

wsaviewer listen-port WSA-host WSA-port

2. Change the Web service URL in the Web service client to access the WSAViewer.
Assume that the original Web service URL in the is as follows:

http://bedrockquarry.com:8080/wsa/wsa1

710
 Testing and Debugging Progress 4GL Web Services

In the client, change this URL to use an agreed-upon viewer listening port:

http://bedrockquarry.com:8081/wsa/wsa1

3. To run the WSAViewer, enter this command in the Proenv shell on the WSA machine:

wsaviewer 8081 localhost 8080

The WSAViewer runs configured to listen for requests from the reconfigured client interface on
port 8081 and forward those requests to port 8080. SOAP responses from the WSA, then, move
in the reverse direction.

Figure 71 shows the main window of the WSAViewer when it first opens.

Figure 71: WSAViewer main window

SOAP requests from the client appear in the left-hand viewer and SOAP responses from the
WSA forwarded back to the client appear in the right-hand viewer. A continuous stream of
requests and responses is recorded that you can review by using the vertical scroll bars.

To configure and run ProSOAPView, see Chapter 12, Handling Errors in Progress 4GL
Requests to Web Services.

ProSOAPView is more general purpose than WSAViewer, and it allows you to trace not only
SOAP messages, but also HTTP messages and other document contents exchanged between a
client and server. ProSOAPView works as both an HTTP proxy server and an HTTP client that
can connect to your choice of another proxy server or the final destination.

711
OpenEdge Development: Web Services

Identifying errors
This section describes how to identify errors and describes some of the more common errors
that occur in WSA administration requests and in Web service application requests.

How the WSA logs Web service information

Each time the WSA starts up, each WSA instance receives a unique, alphanumeric identifier
(WSA ID), which the WSA always places in a log file entry that indicates the WSA is starting
up. This WSA ID appears in the log file similar to this example, always appearing after the "ID":

ID 2bbafbc35852308b:7a8a02:f18e8ee918:-8000

When a WSA instance first receives a request for one of its deployed Web services, the WSA
instance assigns the request an alphanumeric identifier (request ID) that is unique for the current
session of the WSA instance. When the WSA logs information about a Web service request,
whether the information concerns processing steps or errors, the WSA always includes its
unique request ID in the log entry text using the following format, where reqid-value is the
request ID for the Web service request to which the log entry applies:

Syntax

(reqid:reqid-value)

When the WSA returns a SOAP fault to a client, it includes the request ID of the Web service
request that triggered the SOAP fault, as well as the WSA ID of the WSA instance where the
Web service is deployed. The WSA places these two IDs within the <requestID> element of
the SOAP fault message according to the following format, where wsaid-value is the WSA ID
and reqid-value is the request ID:

Syntax

wsaid-value#reqid-value

712
 Testing and Debugging Progress 4GL Web Services

The client can then obtain these two IDs from the <requestID> element of the SOAP fault and
provide it to the WSA host operator to look up more detailed information in the corresponding
entries of the WSA log file. The WSA operator then uses the WSA ID to locate the WSA log
file for the corresponding WSA instance. They can now open the log file and search for log file
entries that contain the "(reqid:reqid-value)" string to find all information related to the
specific request and WSA instance.

Errors occurring in WSA administration requests

An error might occur in a WSA administration request. Such errors occur when you use the
Progress Explorer or the wsaman utility. Both these tools are front ends to the AdminServer,
which creates SOAP requests as a Web service client, then sends them to the WSA. When an
error in a WSA administration request occurs, it is logged. Where it is logged depends on when
it occurred, as shown in Table 74.

Table 74: WSA administration error logging

If the error occurred... The error is logged...

While the request is being prepared in the AdminServer. In the AdminServer log.

While the request is being processed in the WSA. In the WSA instance log.

Errors occurring in Web service application requests

A Web service application request is initiated by a client, which creates a SOAP message and
sends it to the WSA. The WSA processes the SOAP message, creates a response, and sends the
response back to the client. An error can occur on the client side or the server side.

Client-side errors

A client-side error occurs before the request is sent or while it is being processed by the WSA.

An example of an error occurring before the request is sent is a mismatch in interface

parameters. For these types of errors, the type of client response depends on the client platform.

713
OpenEdge Development: Web Services

Examples of errors occurring while the request is being sent (which involve a session-managed
AppServer application) include:

Forgetting to call the connect method first.

Not sending the correct Object ID in the SOAP header.

Web server not running.

Web service URL incorrectly specified (host or port).

Network down.

Using HTTP instead of HTTPS when required.

These types of errors result in a SOAP fault response and log file entries.

Server-side errors

A server-side error occurs while the request is being processed by the WSA and the error is not
related to the contents of the SOAP request. Examples of server-side errors include:

Forgetting to enable a specific deployed Web service.

Forgetting to enable client access to Web services for the WSA instance.

Configuring or starting an AppServer incorrectly. This might involve one or more of the
following issues:

Invalid Propath on the AppServer.

Invalid AppService (Application Service name).

Incompatible AppServer operating mode for the Web service session model.

Missing 4GL, or an incorrect version of the 4GL.

Configuring the Java Servlet Engine (JSE) incorrectly so it does not recognize the WSA).

These types of errors result in a SOAP fault response and log file entries.

714
 Testing and Debugging Progress 4GL Web Services

Sample error scenarios

This section discusses sample error scenarios. These scenarios involve a VB.NET client
accessing a Web service whose specification is listed in Table 75.

Table 75: Sample Web service specification for error scenarios

Web service specification Value

Name OrderInfo

TargetNamespace urn:www-progress-com:samples:Orderinfo

AppObject OrderInfo

ProcObject CustomerOrder

Session Model Managed

Scenario 1: Web service deployed but not enabled

In this scenario, a Web service is deployed but not enabled. At this point:

1. The client sends the following connection request:

Connect_OrderInfo("","","")

2. The WSA gets the request and determines the Web service is disabled. At this point:

a. The WSA sends the client a SOAP response containing a SOAP fault.

b. The log files do not show any error.

715
OpenEdge Development: Web Services

The following is the SOAP response containing the SOAP fault:

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here>
<soap:Body>
<soap:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>An error was detected request. (10893)
</faultstring>
<detail>
<ns1:FaultDetail
soap:encodingStyle="http://schemas.xmlsoap.org//"
xmlns:ns1="http://servicehost:8080/wsa/wsa1">
<errorMessage xsi:type=xsd:string">The urn:www-progress-com
:samples:OrderInfo:OrderInfo service is unavailable (10921)
</errorMessage>
<requestID xsi:type="xsd:string">2e62cab6b81150d5:-
17c6a3c:f1dffbd11b:-8000#1f
</requestID>
</ns1:FaultDetail>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

3. The interface translates the SOAP fault into a SOAP exception.

4. The client code catches the SOAP exception.

5. The client displays the following error message (assuming the client application has a user
interface):

Note: All .NET client applications should always catch SOAP faults and handle them. If not,
the .NET Frameworks default exception handler displays the SOAP fault general error
information. This might well hide and cause the loss of the more useful error detail
information in the SOAP fault. For client applications without a user interface, all error
information must be written to an application log file to ensure it is not lost.

716
 Testing and Debugging Progress 4GL Web Services

Scenario 2: 4GL updated, but Web service not redeployed

In this scenario, the 4GL is updated with a different procedure prototype (signature), but the
Web service is not updated accordingly. At this point:

1. The client sends the following method request:

FindCustomerByNum(3, custNameVar)

2. The WSA gets the request and asks the AppServer to run the procedure
FindCustomerByNum.p.

3. The AppServer:

a. Tries to run FindCustomerByNum.p.

b. Detects a parameter-type mismatch and records the following error message in its
log, *.server.log:

[02/12/11@16:07:01.427-0500] P-000371 T-000370 0 AS --

Mismatched parameter types passed to procedure
OrderInfo/FindCustomerByNum.p. (3230)

c. Returns the error to the WSA.

717
OpenEdge Development: Web Services

4. The WSA:

a. Records the following message in its log:

[02/12/11@16:07:01.802-0500] P-000120 T-Thread-11 2 OrderInfo

4GL-Provider (reqid:6) Error in SOAP request execution: 4GL
ERROR condition: Mismatched parameter types passed to
procedure OrderInfo/FindCustomerByNum.p. (3230) (7211) (10926)

b. Sends the following SOAP containing a SOAP fault back to the client:

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here>
<soap:Body>
<soap:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>An error was detected request. (10893)
</faultstring>
<detail>
<ns1:FaultDetail
soap:encodingStyle=http://schemas.xmlsoap.org//
xmlns:ns1="http://servicehost:8080/wsa/wsa1">
<errorMessage xsi:type=xsd:string">Error in SOAP
request execution: 4GL ERROR condition: Mismatched
parameter types passed to procedure
OrderInfo/FindCustomerByNum.p. (10926)
</errorMessage>
<requestID xsi:type=xsd:string">2e62cab6b81150d5:
-87f76e:f20f57227d:-8000#6
</requestID>
</ns1:FaultDetail>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

Note: This example uses a value of 3 for the serviceFaultLevel property.

Notice the correspondence between the "(reqid:6)" string in the log file entry and the
"<requestID> ...2e62...#6" string in the SOAP fault message, indicating information
for the same request.

5. The interface translates the SOAP fault into a SOAP exception.

6. The client catches the SOAP exception.

718
 Testing and Debugging Progress 4GL Web Services

7. The client displays the following error message (assuming the client application has a user
interface):

Note: All .NET client applications should always catch SOAP faults and handle them. If not,
the .NET Frameworks default exception handler displays the SOAP fault general error
information. This might well hide and cause the loss of the more useful error detail
information in the SOAP fault. For client applications without a user interface, all error
information must be written to an application log file to ensure it is not lost.

Scenario 3: Web service deployed but AppServer not

running
In this scenario, a Web service is deployed, but its AppServer is not running. At this point:

1. The client sends the following connection request:

Connect_Orderinfo("", "", ")

2. The WSA:

a. Gets the request.

b. Determines that the AppServer is not available.

c. Records the following in its log:

[02/12/11@16:17:27.349-0500] P-000120 T-Thread-11 2 OrderInfo

4GL-Provider (reqid:8) Error in SOAP request execution: Connect
Failure: Application Service asbroker1 Unknown at NameServer
at Host servicehost Port 5162. (8234) (10926)

719
OpenEdge Development: Web Services

d. Sends a SOAP message with a SOAP fault back to the client. The message is as
follows:

<?xml version="1.0" encoding="UTF-8" ?>

<soap:Envelope namespaces defined here>
<soap:Body>
<soap:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>An error was detected request. (10893)
</faultstring>
<detail>
<ns1:FaultDetail
soap:encodingStyle=http://schemas.xmlsoap.org//
xmlns:ns1="http://servicehost:8080/wsa/wsa1">
<errorMessage xsi:type=xsd:string">Error in SOAP request
execution: Connect Failure: Application Service
asbroker1 Unknown at NameServer at Host servicehost
Port 5162. (8234) (10926)
</errorMessage>
<requestID xsi:type=xsd:string">2e62cab6b81150d5:
-87f76e:f20f57227d:-8000#8 </requestID>
</ns1:FaultDetail>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

3. The interface translates the SOAP fault into a SOAP exception.

4. The client catches the SOAP exception.

5. The client displays the this error message (assuming the client application has a user
interface):

Note: All .NET client applications should always catch SOAP faults and handle them. If not,
the .NET Frameworks default exception handler displays the SOAP fault general error
information. This might well hide and cause the loss of the more useful error detail
information in the SOAP fault. For client applications without a user interface, all error
information must be written to an application log file to ensure it is not lost.

720
 Part III
Progress 4GL Clients Accessing Industry
Web Services

Chapter 8, Analyzing WSDL for Progress 4GL Access to Web Services

Chapter 9, Connecting to Web Services from the Progress 4GL

Chapter 10, Invoking Web Service Operations from the Progress 4GL

Chapter 11, Handling SOAP Message Headers in the Progress 4GL

Chapter 12, Handling Errors in Progress 4GL Requests to Web Services

Chapter 13, Sample Progress 4GL Applications Accessing Web Services

 8
Analyzing WSDL for Progress 4GL
Access to Web Services

The chapter describes how to understand and work with WSDL files for accessing Web services
in the Progress 4GL. This includes understanding how to generate Progress 4GL interface
documentation from a WSDL file to access the Web service and how OpenEdge maps Web
service parameters defined using the XML Schema types in WSDL to the Progress 4GL data
types in your Progress 4GL Web service client application.

The sections in this chapter include:

Using the WSDL Analyzer

Mapping XML Schema data types to Progress 4GL data types

OpenEdge Development: Web Services

Using the WSDL Analyzer

After you have the location to a WSDL file for a Web service you need to access, you can use
the WSDL Analyzer to provide HTML documentation on the interface that the WSDL
describes. This documentation describes the requirements for accessing the Web service using
the Progress 4GL, and includes binding information and Progress 4GL prototypes that will
allow you to access and invoke operations in the Web services. This documentation also
includes the content of any internal WSDL comments that the Web service developer has
provided to explain elements of the Web service interface.

To use the WSDL Analyzer, enter the bprowsdldoc command on your operating system
command line using this syntax:

Note: Use the command window (shell) opened by the proenv command tool to enter this
command with the correct path settings.

Syntax

bprowsdldoc
[ -h ]
|
{
[ -b | -nohostverify | -nosessionreuse
| -WSDLUserid username | -WSDLPassword password
| -proxyhost host | -proxyport port
| -proxyUserid username | -proxyPassword password
] ...
wsdl-url-or-filename [ target-directory ]
}

-h

Displays a help message on the usage of this command.

82
 Analyzing WSDL for Progress 4GL Access to Web Services

-b

Forces documentation of binding names. A Web service can offer two options for a Web
service client to connect (or bind) to it (see Chapter 9, Connecting to Web Services from
the Progress 4GL):

Using services with ports (most common).

Using binding names (the names of the WSDL <binding> elements) with SOAP
endpoints that you must obtain separately (sometimes used to bind a SOAP viewer).

Normally, if a WSDL defines services, the Analyzer includes only the service and port
names in the generated documentation. If the WSDL does not define any services, the
Analyzer documents the binding names. This option tells the Analyzer to document the
binding names even when services are defined in the WSDL.

-nohostverify

Turns off host verification for a Secure Socket Layer (SSL) connection using HTTPS.

-nosessionreuse

Prevents any reuse of the SSL session ID for an HTTPS Web server connection when
reconnecting the same Web server using HTTPS.

-WSDLUserid username

Specifies a username for accessing the WSDL file.

-WSDLPassword password

Specifies a password for accessing the WSDL file.

-proxyhost host

Specifies the name or IP address of the host where an HTTP-based proxy server required
to access the WSDL file is located.

-proxyport port

Specifies the port on which the HTTP-based proxy server is listening for requests to
download WSDL files.

-proxyUserid username

Specifies a username for accessing an HTTP-based proxy server.

83
OpenEdge Development: Web Services

-proxyPassword password

Specifies a password for accessing an HTTP-based proxy server.

wsdl-url-or-filename

A string specifying the URL or path name to the WSDL file. If the string does not specify
a URL protocol ("file://", "http://", or "https://") it is assumed to be a a local file
path name.

target-directory

A string specifying the target directory (to be created if necessary) where the Analyzer will
write the generated documents. If not specified, the Analyzer assumes the current working
directory. Choose a directory dedicated for the specified WSDL file, as some generated
document filenames are the same for multiple WSDL files.

Given the options, the Analyzer produces five types of hyperlinked HTML documents in your
current working directory as described in the following sections. All of these documents are
hyperlinked from a starting index.html file generated in the target-directory:

84
 Analyzing WSDL for Progress 4GL Access to Web Services

Index document
This document is the starting index.html file that the Analyzer generates to describe the WSDL
file. Figure 81 shows an example of this document.

Figure 81: WSDL Analyzer index document for multiple services

If the WSDL file defines more than one service, as in this example, the index document
becomes a service index document that lists all defined services as hyperlinks, each to its own
service document containing sections that describe the service.

85
OpenEdge Development: Web Services

This list appears after all other sections that describe the WSDL file, as shown in Table 81.

Table 81: WSDL Analyzer docIndex document for multiple services

Section heading Description

WSDL The document heading followed by comments in

any WSDL <documentation> elements that
describe the entire WSDL file.

Location The URL of the WSDL file used to generate this

documentation. This is always a complete path
name (absolute path) to the file.

Target namespace The target namespace of the Web service.

Services A hyperlinked listing of all the services defined for

the Web service, including comments in any
WSDL <documentation> elements about these
services.

This index document also contains a hyperlink to an operation index document that contains an
alphabetical list of all operations from all port types in all services (see the Operation index
document section on page 87).

If the WSDL file defines only one service, the index document redirects the browser to that
single service document, as shown in Table 84.

86
 Analyzing WSDL for Progress 4GL Access to Web Services

Operation index document

The operation index document contains a hyperlinked alphabetical list of all operations from all
port types in all services defined in the WSDL file. Figure 82 shows an example of this
document.

Figure 82: WSDL Analyzer operation index document

The list is in the form of a table with columns describing the port type and service information
for each operation, as shown in Table 82.

Table 82: WSDL Analyzer docOperation index document list

Table column Description

Operation A hyperlinked operation name that links to the

operation detail in the port type document.

Documentation Any comments provided in WSDL

<documentation> elements that describe the
operation.

Port type A hyperlinked port type name that links to the top
of the port type document.

Service A hyperlinked service name that links to the service

document.

87
OpenEdge Development: Web Services

The operation index document also contains a hyperlink to the service index (see the Index
document section on page 85) and data types document (see the Data types document
section on page 821).

Service document
The service document is an HTML document that provides an overview of a Web service
interface. Figure 83 shows an example of a service document for one of the services described
in a WSDL with multiple services.

Figure 83: WSDL Analyzer service document for one of multiple services

88
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 83 lists and describes the sections of a service document if the WSDL contains multiple
services, as in Figure 83.

Table 83: WSDL Analyzer docService document (from multiple services)

Section heading Description

Service-name service The name of the service (Service-name) followed

by any comments included in WSDL
<documentation> elements about there service.

Port types (persistent A hyperlinked listing of all the port types defined in
procedures) the Web service, including comments in any
WSDL <documentation> elements about them.

Data types A hyperlinked alphabetical listing of all the

complex types defined for the Web service,
including comments in any WSDL
<documentation> elements as defined for each data
type.

A service document for one of multiple services also contains a hyperlink to the service index
(see the Index document section on page 85) and data types document (see the Data types
document section on page 821).

89
OpenEdge Development: Web Services

Figure 84 shows an example of a service document for a WSDL containing only one service.

Figure 84: WSDL Analyzer service document for a single service only

810
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 84 lists and describes the sections of the service document if the WSDL contains only a
single service, as in Figure 84.

Table 84: WSDL Analyzer docService document (from one service)

Section heading Description

WSDL The document heading followed by comments in

any WSDL <documentation> elements that
describe the entire WSDL file.

Location The URL of the WSDL file used to generate this

documentation. This is always a complete path
name (absolute path) to the file.

Target namespace The target namespace of the Web service.

Service-name service The name of the service (Service-name) followed

by any comments included in WSDL
<documentation> elements about there service.

Port types (persistent A hyperlinked listing of all the port types defined in
procedures) the Web service, including comments in any
WSDL <documentation> elements about them.

Data types A hyperlinked alphabetical listing of all the

complex types defined for the Web service,
including comments in any WSDL
<documentation> elements as defined for each data
type.

This single service document also contains a hyperlink to an operation index document that
contains an alphabetical list of all operations from all port types in the service (see the
Operation index document section on page 87).

811
OpenEdge Development: Web Services

Port type document

For each port type defined in the WSDL file, the Analyzer generates a separate HTML port type
document that contains detailed information on how to work with that port type. Figure 85
shows an example of the beginning of a port type document.

Figure 85: WSDL Analyzer port type document (up to the Summary)

812
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 85 lists and describes the sections that the beginning of a port type document contains.

Table 85: WSDL Analyzer docPort type document beginning sections

Section heading Description

Port type (persistent procedure) The document heading.

Port-type-name The defined name of the port type followed by

comments in any WSDL <documentation>
elements that describe the entire port type.

Summary Basic connection (binding) information and a list of

the operations defined by the port type, including
comments in any WSDL <documentation>
elements on each operation.

A port type document for a WSDL with a single service also contains a hyperlink to the single
service document (Service document section on page 88), data types document (Data types
document section on page 821), and operation index document (Operation index document
section on page 87). A port type document for a WSDL with multiple services adds a link to
the service index (Index document section on page 85), as shown in Table 85.

813
OpenEdge Development: Web Services

Figure 86 shows an example of the connection parameters from the Connection details
section of a port type document, as described in Table 86.

Figure 86: WSDL Analyzer port type document (connection parameters)

814
 Analyzing WSDL for Progress 4GL Access to Web Services

Figure 87 shows an example of service and port descriptions from the Connection details
section of a port type document.

Figure 87: WSDL Analyzer port type document (services and ports)

The WSDL Analyzer can also list the WSDL bindings that support the port type. For more
information on how the Analyzer describes services, ports, and bindings, see Table 86.

815
OpenEdge Development: Web Services

Figure 88 shows a connection code example from the Connection details section of a port type
document, as described in Table 86.

Figure 88: WSDL Analyzer port type document (example connection code)

816
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 86 lists and describes the Connection details section of a port type document.

Table 86: WSDL Analyzer docPort type document connection details

Section heading Description

Connection details Provides information on how to connect to the Web

service to use this port type, including the following
sections:
Connection parameters Progress 4GL
syntax for all of the Web service-related
parameters that can be included in the
connection parameters string passed to the
Progress 4GL CONNECT( ) method, and a
Progress 4GL example of how they might be
used. Some of the same startup options used
for execution of the WSDL Analyzer also
appear in this section, such as those used to
specify HTTPS and proxy server connections.
-Service and -Port descriptions A table
listing the name of each service and the names
of ports for each service that support this port
type. For each service and port name, the table
also includes comments in any WSDL
<documentation> elements defined for each
service and port. So, for example, if the port
type is supported for different applications
and in different locations, you might well
have a corresponding choice of services and
ports to make the connection.
Example Provides a real code example
that illustrates how you might connect and set
up the Web service to access the operations of
the port type.
Binding descriptions If you specify the -b
command-line option, this section appears in
the document. It shows a table listing the
name of each binding that supports this port
type. For each binding, the table also includes
comments in any WSDL <documentation>
elements defined for each binding.

817
OpenEdge Development: Web Services

Figure 89 shows an example of how the Analyzer starts describing a Web service operation in
the Operation (internal procedure) detail section of a port type document.

Figure 89: WSDL Analyzer port type document (operation detail start)

818
 Analyzing WSDL for Progress 4GL Access to Web Services

Figure 810 shows an example of how the Analyzer finishes describing a Web service operation
in the Operation (internal procedure) detail section of a port type document, describing
parameters, return values, headers, and faults associated with the operation as described in
Table 87.

Figure 810: WSDL Analyzer port type document (operation detail finish)

819
OpenEdge Development: Web Services

Table 87 lists and describes the Operation (internal procedure) detail section of a port type
document.

Table 87: WSDL Analyzer docPort type document operation detail

Section heading Description

Operation (internal procedure) A series of subsections describing each Web

detail service operation defined for the port type mapped
as an internal procedure (and user-defined function,
if supported), including:
The operation name.
Comments in any WSDL <documentation>
elements.
Progress 4GL procedure prototypes (and
function prototypes, if also supported).
Progress 4GL example.
Descriptions of parameters and any return
value (for a user-defined function mapping),
including SOAP examples for complex types
as appropriate for different service and port
combinations.
Any SOAP request/response headers and
SOAP faults as appropriate for different
service and port combinations.

The WSDL Analyzer maps all Web service operations from a port type to a 4GL internal
procedure prototype. This allows all Web service operations to be invoked either synchronously
or asynchronously as you require. For some Web service operations, the Analyzer also indicates
a mapping to a 4GL user-defined function prototype. For these dual-mapping operations:

The Analyzer describes both the internal procedure mapping and the user-defined function
mapping in the port type document.

You can invoke them either as 4GL procedures or user-defined functions, depending on
your requirements at any given point in your application. However, as with user-defined
functions in the native 4GL, you cannot invoke these Web service operations as functions
asynchronously.

Figure 89 and Figure 810 show most of an example description for a dual-mapping Web
service operation in the Operation (internal procedure) detail section of a port type document.

820
 Analyzing WSDL for Progress 4GL Access to Web Services

Data types document

For all the complex types defined in the WSDL file, the Analyzer generates a single HTML data
types document that contains a summary and detailed information on each complex type. Figure
811 shows an example of the data type summary list that begins this document, and Figure
812 shows an example data type detail in this document.

Figure 811: WSDL Analyzer data types document (summary list)

821
OpenEdge Development: Web Services

Figure 812: WSDL Analyzer data types document (data type detail)

Table 88 lists and describes the sections that the data types document contains.

Note: This document does not describe standard XML Schema types. For information on how
the Analyzer maps XML Schema types to Progress 4GL data types, see the Mapping
XML Schema data types to Progress 4GL data types section on page 824.

822
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 88: WSDL Analyzer docData types document

Section heading Description

Data types The document heading followed by comments in

any WSDL <documentation> elements that
describe the entire types section.

Datatype summary A hyperlinked alphabetical listing of all the

complex types defined for the Web service,
including comments in any WSDL
<documentation> elements as defined for each data
type.

Datatype detail A series of subsections, one for each complex type

defined for the Web service, listed in alphabetical
order, and each one including comments in any
WSDL <documentation> elements defined for the
complex type, the XML <schema> element that
defines the type, and an example of a SOAP
instance.

A data types document for a WSDL also contains a hyperlink to the current service document
(see the Service document section on page 88) and to the operation index document (see the
Operation index document section on page 87). It also provides a hyperlink to the beginning
(top) of the document from the detail for any data type entry.

823
OpenEdge Development: Web Services

Mapping XML Schema data types to Progress 4GL data

types
The foundation for data types in WSDL is XML Schema, a standard that defines simple data
types and a means to aggregate them into more complex types. OpenEdge supports a range of
acceptable mappings for all XML Schema types. That is, given a parameter on a Web service
operation, OpenEdge supports a range of Progress 4GL data types that it will automatically
transform between OpenEdge and the XML Schema representation. As part of the acceptable
mappings, OpenEdge suggests (through the WSDL Analyzer) a recommended Progress 4GL
data type to use when mapping a Progress 4GL parameter to a particular Web service parameter.

This section identifies the mapping options and how they work going from one domain (XML
Schema) to the other (Progress 4GL) for the following types of data:

Simple data types

Arrays

Complex data types

For more information on how to manipulate these data types (especially complex data types) in
the Progress 4GL, see Chapter 10, Invoking Web Service Operations from the Progress 4GL.

Simple data types

Simple data types represent the foundation for all types of data. The mappings for simple data
types and how they can be transformed between Web services and the Progress 4GL provide
the basic information for how to work with more complex types of data.

Suggested mappings

OpenEdge suggests recommended mappings between Web service parameters and Progress
4GL parameters in the generated documentation produced by the WSDL Analyzer. These are
the mappings that are most semantically useful. Note also that wherever the WSDL file
indicates that a parameter of any data type is nillable, this means that on the Web service side
the parameter can have the null value and on the Progress 4GL side the parameter can pass the
4GL unknown value (?).

824
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 89 lists all the simple XML Schema data types in alphabetical order, showing for each
one the Progress 4GL data type that OpenEdge suggests for mapping it. The table also provides
notes on these mappings where appropriate.

Table 89: Suggested XML Schema mappings to Progress 4GL

data types (1 of 6)

XML Schema data type 4GL data type Notes

anyURI CHARACTER

base64Binary MEMPTR You can use the 4GL BASE64-ENCODE

and BASE64-DECODE functions to convert
between Base 64 clear text (CHARACTER
or LONGCHAR) and binary data (RAW or
MEMPTR).

boolean LOGICAL

byte INTEGER On INPUT, if the 4GL INTEGER value is

outside the valid range of the XML
Schema byte type, it is a run-time error.

date DATE On OUTPUT, the time zone information is

lost. To retain it, use a 4GL CHARACTER
parameter.

dateTime DATETIME-TZ

decimal DECIMAL The 4GL DECIMAL type may not hold the
entire XML Schema decimal value.
However, it is common in the industry to
do a mapping between XML Schema
decimal and another decimal data type.

On OUTPUT, if the XML Schema decimal

value overflows the 4GL DECIMAL type,
it is a run-time error.

double CHARACTER

duration CHARACTER

ENTITIES CHARACTER

ENTITY CHARACTER

825
OpenEdge Development: Web Services

Table 89: Suggested XML Schema mappings to Progress 4GL

data types (2 of 6)

XML Schema data type 4GL data type Notes

float CHARACTER

gDay CHARACTER

gMonth CHARACTER

gMonthDay CHARACTER

gYear CHARACTER

gYearMonth CHARACTER

hexBinary MEMPTR

ID CHARACTER

IDREF CHARACTER

IDREFS CHARACTER

int INTEGER

integer DECIMAL The 4GL DECIMAL type may not hold the
entire XML Schema integer value, but
it is far more likely to do so than the 4GL
INTEGER type.

On INPUT, if the 4GL DECIMAL value is

outside the valid range of the XML
Schema integer type, it is a run-time
error.
On OUTPUT, if the value of the XML
Schema integer value is outside the
valid range of the 4GL DECIMAL type, it
is a run-time error.

Language CHARACTER

826
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 89: Suggested XML Schema mappings to Progress 4GL

data types (3 of 6)

XML Schema data type 4GL data type Notes

long DECIMAL On INPUT, if the 4GL DECIMAL value is

outside the valid range of the XML
Schema long type, it is a run-time error.
On OUTPUT, if the value of the XML
Schema long value is outside the valid
range of the 4GL DECIMAL type, it is a
run-time error.

Name CHARACTER

NCName CHARACTER

negativeInteger DECIMAL The 4GL DECIMAL type may not hold the
entire XML Schema negativeInteger
value, but it is far more likely to do so
than the 4GL INTEGER type.
On INPUT, if the 4GL DECIMAL value is
outside the valid range of the XML
Schema negativeInteger type, it is a
run-time error.
On OUTPUT, if the value of the XML
Schema negativeInteger value is
outside the valid range of the 4GL
DECIMAL type, it is a run-time error.

NMTOKEN CHARACTER

NMTOKENS CHARACTER

827
OpenEdge Development: Web Services

Table 89: Suggested XML Schema mappings to Progress 4GL

data types (4 of 6)

XML Schema data type 4GL data type Notes

nonNegativeInteger DECIMAL The 4GL DECIMAL type may not hold the
entire XML Schema
nonNegativeInteger value, but it is far
more likely to do so than the 4GL
INTEGER type.

On INPUT, if the 4GL DECIMAL value is

outside the valid range of the XML
Schema nonNegativeInteger type, it is
a run-time error.
On OUTPUT, if the value of the XML
Schema nonNegativeInteger value is
outside the valid range of the 4GL
DECIMAL type, it is a run-time error.

nonPositiveInteger DECIMAL The 4GL DECIMAL type may not hold the
entire XML Schema
nonPositiveInteger value, but it is far
more likely to do so than the 4GL
INTEGER type.

On INPUT, if the 4GL DECIMAL value is

outside the valid range of the XML
Schema nonPositiveInteger type, it is
a run-time error.
On OUTPUT, if the value of the XML
Schema nonPositiveInteger value is
outside the valid range of the 4GL
DECIMAL type, it is a run-time error.

normalizedString CHARACTER

NOTATION CHARACTER

828
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 89: Suggested XML Schema mappings to Progress 4GL

data types (5 of 6)

XML Schema data type 4GL data type Notes

positiveInteger DECIMAL The 4GL DECIMAL type may not hold the
entire XML Schema positiveInteger
value, but it is far more likely to do so
than the 4GL INTEGER type.
On INPUT, if the 4GL DECIMAL value is
outside the valid range of the XML
Schema positiveInteger type, it is a
run-time error.
On OUTPUT, if the value of the XML
Schema positiveInteger value is
outside the valid range of the 4GL
DECIMAL type, it is a run-time error.

qName CHARACTER

short INTEGER On INPUT, if the 4GL INTEGER value is

outside the valid range of the XML
Schema short type, it is a run-time
error.

string CHARACTER

time INTEGER On INPUT, the value is converted with no

time zone information.

token CHARACTER

unsignedByte INTEGER On INPUT, if the 4GL INTEGER value is

outside the valid range of the XML
Schema unsignedByte type, it is a
run-time error.

unsignedInt DECIMAL On INPUT, if the 4GL DECIMAL value is

outside the valid range of the XML
Schema unsignedInt type, it is a
run-time error.
On OUTPUT, if the value of the XML
Schema unsignedInt value is outside
the valid range of the 4GL DECIMAL type,
it is a run-time error.

829
OpenEdge Development: Web Services

Table 89: Suggested XML Schema mappings to Progress 4GL

data types (6 of 6)

XML Schema data type 4GL data type Notes

unsignedLong DECIMAL On INPUT, if the 4GL DECIMAL value is

outside the valid range of the XML
Schema unsignedLong type, it is a
run-time error.
On OUTPUT, if the value of the XML
Schema unsignedLong value is outside
the valid range of the 4GL DECIMAL type,
it is a run-time error.

unsignedShort INTEGER On INPUT, if the 4GL INTEGER value is

outside the valid range of the XML
Schema unsignedShort type, it is a
run-time error.

Interacting with XML Schema data formats

You might need to work directly with an XML Schema value whose format is not represented
among the supported formats for the suggested Progress 4GL data type mapping, for example,
a 51-digit decimal value. To handle this requirement, you can pass an XML Schema-formatted
string version of the value into or out of the Web service invocation. OpenEdge automatically
passes the XML Schema-formatted value when you map either a CHARACTER or LONGCHAR data
type to any XML Schema data type that has a suggested mapping (see Table 89) other than
CHARACTER or LONGCHAR.

When you pass the XML Schema-formatted value as an INPUT parameter, the Web service
invocation incorporates it directly into the generated SOAP message. For an OUTPUT parameter,
the invocation copies the XML Schema-formatted value directly from the SOAP message into
the CHARACTER or LONGCHAR parameter.

When you pass an XML Schema-formatted value to a Web service, the invocation also validates
the format of the value to ensure that it conforms to XML Schema formatting rules for the data
type. Note that the invocation does not validate any facets declared in the <schema> element to
constrain the value. It ensures that the format of the value you provide is valid according to its
base XML Schema data type representation, but not, for example, if the value falls within a
given range.

830
 Analyzing WSDL for Progress 4GL Access to Web Services

Thus, for example, if you pass a Progress 4GL CHARACTER as an INPUT parameter for an XML
Schema int, the invocation checks to ensure that it contains a properly formatted 32-bit integer
value. If you pass a Progress 4GL CHARACTER as an OUTPUT parameter for an XML Schema int,
the invocation copies the Schema-formatted value directly from the SOAP message into the
4GL CHARACTER parameter.

Data type casting

As described previously, OpenEdge supports a set of alternative Progress 4GL data types (in
addition to a suggested data type) to represent the value for an XML Schema data type in the
Progress 4GL. These alternative data types essentially force the Web service invocation to cast
the value between the specified native Progress 4GL representation and the corresponding XML
Schema data type. The result of this casting might not preserve as much accuracy as the
suggested mapping.

Table 810 shows all the supported castings (alternative mappings) between the XML Schema
and Progress 4GL data types. The suggested Progress 4GL data type mapping (see Table 89)
for each XML Schema type appears in bold font. For a detailed description of how OpenEdge
casts each supported mapping, see Appendix D, Data Type Casting Rules for Progress 4GL
Calls to Web Services.

Note: OpenEdge supports no castings for the RECID, ROWID, or HANDLE 4GL data types.

Table 810: Supported casts between XML Schema and Progress 4GL
data types (1 of 6)

XML Schema data type Progress 4GL data type

anyURI CHARACTER
LONGCHAR

base64Binary CHARACTER
LONGCHAR
MEMPTR
RAW

boolean CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

831
OpenEdge Development: Web Services

Table 810: Supported casts between XML Schema and Progress 4GL
data types (2 of 6)

XML Schema data type Progress 4GL data type

byte CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

date CHARACTER
DATE
DATETIME
DATETIME-TZ

dateTime CHARACTER
DATE
DATETIME
DATETIME-TZ

decimal CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

double CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

duration CHARACTER
LONGCHAR

ENTITIES CHARACTER
LONGCHAR

ENTITY CHARACTER
LONGCHAR

float CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

gDay CHARACTER
LONGCHAR

832
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 810: Supported casts between XML Schema and Progress 4GL
data types (3 of 6)

XML Schema data type Progress 4GL data type

gMonth CHARACTER
LONGCHAR

gMonthDay CHARACTER
LONGCHAR

gYear CHARACTER
LONGCHAR

gYearMonth CHARACTER
LONGCHAR

hexBinary CHARACTER
LONGCHAR
MEMPTR
RAW

ID CHARACTER
LONGCHAR

IDREF CHARACTER
LONGCHAR

IDREFS CHARACTER
LONGCHAR

int CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

integer CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

Language CHARACTER
LONGCHAR

long CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

833
OpenEdge Development: Web Services

Table 810: Supported casts between XML Schema and Progress 4GL
data types (4 of 6)

XML Schema data type Progress 4GL data type

Name CHARACTER
LONGCHAR

NCName CHARACTER
LONGCHAR

negativeInteger CHARACTER
DECIMAL
INTEGER
LONGCHAR

NMTOKEN CHARACTER
LONGCHAR

NMTOKENS CHARACTER
LONGCHAR

nonNegativeInteger CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

nonPositiveInteger CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

normalizedString CHARACTER
DATE
DATETIME
DATETIME-TZ
DECIMAL
INTEGER
LOGICAL
LONGCHAR

NOTATION CHARACTER
LONGCHAR

positiveInteger CHARACTER
DECIMAL
INTEGER
LONGCHAR

834
 Analyzing WSDL for Progress 4GL Access to Web Services

Table 810: Supported casts between XML Schema and Progress 4GL
data types (5 of 6)

XML Schema data type Progress 4GL data type

qName CHARACTER
LONGCHAR

short CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

string CHARACTER
DATE
DATETIME
DATETIME-TZ
DECIMAL
INTEGER
LOGICAL
LONGCHAR

time CHARACTER
INTEGER
LONGCHAR

token CHARACTER
LONGCHAR

unsignedByte CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

unsignedInt CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

835
OpenEdge Development: Web Services

Table 810: Supported casts between XML Schema and Progress 4GL
data types (6 of 6)

XML Schema data type Progress 4GL data type

unsignedLong CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

unsignedShort CHARACTER
DECIMAL
INTEGER
LOGICAL
LONGCHAR

Arrays
OpenEdge maps arrays of simple types to Progress 4GL arrays. The WSDL Analyzer
determines that it must map to a Progress 4GL array when it recognizes a SOAP array
declaration or the use of the minOccurs and maxOccurs XML Schema attributes in a parameter
type definition. If a SOAP array is declared as unbounded, the Analyzer maps it to a Progress
4GL array with an indeterminate extent.

When it receives a SOAP response that includes a sparse array parameter, OpenEdge creates a
Progress 4GL array of the appropriate size and fills it. OpenEdge sets each unused entry in the
Progress 4GL array to the unknown value (?).

OpenEdge never passes a sparse array as input to a Web service.

For arrays of complex types, the Progress 4GL represents them as arrays of LONGCHAR
(LONGCHAR[ ]) or CHARACTER (CHARACTER[ ]). Each array element you must then handle as a
complex type (see the Complex data types section on page 837).

836
 Analyzing WSDL for Progress 4GL Access to Web Services

Complex data types

An XML Schema complex type is an aggregate of one or more simple types and complex types
defined by a <complexType> XML Schema element. OpenEdge supports the mapping of
complex type parameters to the Progress 4GL CHARACTER and LONGCHAR data types. In all cases,
OpenEdge passes complex type parameters between SOAP messages and the Progress 4GL as
strings in serialized (well-formed XML) form for both INPUT and OUTPUT.

Once in the Progress 4GL, you can continue to work with data from Web service complex types
by directly manipulating the serialized XML in Progress 4GL CHARACTER or LONGCHAR variables,
or you can convert the serialized XML to a parsed representation using the Progress 4GL SAX
or DOM parser (see OpenEdge Development: Programming Interfaces). Whatever technique
you use to work with complex type data in the Progress 4GL, if you need to pass it back to the
Web service, you must pass it back as serialized XML. So, if you maintain the data for complex
types in a Progress 4GL DOM tree (de-serialized), you must serialize it again to a string before
passing it back to a Web service as a complex type parameter.

For more information on how to manage complex types as input and output parameters of Web
service operations and work with the data in the Progress 4GL, see Chapter 10, Invoking Web
Service Operations from the Progress 4GL.

837
OpenEdge Development: Web Services

838
 9
Connecting to Web Services from the
Progress 4GL

The first step in using a Web service is to connect (or bind) your application to it. Web service
connections (or bindings) represent associations between your 4GL application and the Web
service, making it easier for you to access and manage your interaction with the Web service in
the 4GL. They are not physical connections managed by your host or the network.

The following sections describe the features of Web service connections and how you can create
and manage them in the 4GL:

What is a Web service connection?

Binding to a Web service

Managing Web service bindings

For more information on invoking operations in a Web service that you have connected, see
Chapter 10, Invoking Web Service Operations from the Progress 4GL.
OpenEdge Development: Web Services

What is a Web service connection?

Precisely speaking, there is no such thing as a Web service connection. All communications
between a Web service client and the Web service is, from a network point of view,
connectionless. That is, neither the client host nor the Web service host maintain any knowledge
about each other except the others location, and then only when exchanging messages. Any
context or state must be managed explicitly by the application.

However, from the client application point of view, there is definitely a defined relationship
between itself and the Web service it is communicating with, and this relationship is more
properly defined as a binding. A binding retains a logical connection between the client
application and the Web service by maintaining a continuous association between specified
client resources and specified Web service resources. This is the same type of connection that
a 4GL client application maintains between itself and a session-free AppServer with which it is
communicating (see OpenEdge Application Server: Developing AppServer Applications).

This binding relationship makes it easier for the client to send requests to the Web service and
to manage those requests within its own environment until such time as it has no more need for
the bound Web service and its resources. At such a time, the client application can logically
disconnect (unbind) the Web service from its environment in order to free up resources for other
tasks.

While the Web service is bound, the process of invoking a Web service request includes telling
the client host where to send the application message on the Internet so the Web service can
receive and respond to it. This happens every time that the client invokes a Web service request
because, as noted previously, the client host maintains no knowledge of the Web service host
and its relationship to the client application. This lack of a physical connection provides
performance benefits. Given sufficient AppServer resources, a client never needs to wait for an
AppServer to service its Web service request, and whenever an AppServer completes a request,
it is free to service a request from any other client. This arrangement offers maximum scalability
for a given set of AppServer resources over an increasing client load.

To take further advantage of Web service availability on the network, OpenEdge allows the
4GL client to make both synchronous and asynchronous requests to a Web service, providing
greater flexibility in its own request management. For more information on asynchronous Web
service requests, see Chapter 1, Web Services in OpenEdge.

92
 Connecting to Web Services from the Progress 4GL

Binding to a Web service

Binding to a Web service is a two-step process:

1. Create a server object handle.

2. Execute the CONNECT( ) method on the server object handle.

Creating a server object handle

To create a server handle for a Web service, you use the same procedure as creating one for an
AppServer, as shown in the following example:

DEFINE VARIABLE hWebService AS HANDLE.

CREATE SERVER hWebService.

You can now use hWebService to bind a Web service.

Binding to a server object handle

As for an AppServer, you use the CONNECT( ) method on the server object handle to bind that
server object handle to a Web service. This is the basic syntax:

Syntax

CONNECT (
connection-parameters
[ , userid ][ , password ][ , app-server-info ]
)

A Web service binding requires and uses only the connection-parameters argument, which is
a character string containing embedded parameter values to specify the binding. For a Web
service, the last three parameters are AppServer-specific parameters and are ignored if
specified.

The connection-parameters parameter string can contain connection parameters for either an
AppServer application service, a Web service, or both. If the string contains any Web service
parameters, OpenEdge assumes that the method is binding to a Web service and ignores any
AppServer-specific connection parameters in the string.

93
OpenEdge Development: Web Services

Connection parameters

The primary function of the connection parameters is to specify the location and transport
information for the Web service on the network. Web services provide two separate
mechanisms for doing this. OpenEdge supports both mechanisms through the Web service
connection parameters.

This is the Web service syntax for the connection-parameters string:

Syntax

-WSDL wsdl-document [ -WSDLUserid user-id [ -WSDLPassword password ]]

{
{
[ -Service service-name [ -ServiceNamespace service-namespace ] ]
[ -Port port-name ]
}
|
{
[[ -Binding binding-name [ -BindingNamespace binding-namespace ]]
-SOAPEndpoint URL-endpoint ]
}
}
[ -SOAPEndpointUserid user-id [ -SOAPEndpointPassword password ]]
[ -TargetNamespace targetNamespace ]
[ -maxConnections num-connections ]
[ -nohostverify ]
[ -nosessionreuse ]
[ -pf filename ]

The only fully required element is the -WSDL parameter to identify the WSDL document for the
Web service. Note that the remaining required elements specify service, port, and binding
information, but contain only optional elements. This is to indicate that if the WSDL document
contains enough unambiguous information to specify both a valid transport and location for the
Web service, you do not have to specify any of this information in the connection parameters,
and the Web service will be bound according to the WSDL. This is only possible for a WSDL
with a single service and port specification, because there is no provision for specifying a SOAP
endpoint in WSDL without defining a service.

94
 Connecting to Web Services from the Progress 4GL

Basically a complete binding can be specified by one of these mechanisms:

1. A valid service and port (transport and Web service URL location) specification (the most
common mechanism).

2. A valid binding (transport) and SOAP endpoint (Web service URL location) specification
(sometimes used to bind a SOAP viewer between the client and the Web service, or to
provide a consortia of equivalent Web service locations).

Also, if the WSDL unambiguously specifies only some of the required information, the
connection parameters need only contain the required options to unambiguously complete the
transport and location information in the WSDL document. So, for a service and port
specification, you can specify either a -Service option (to unambiguously identify one or more
services that define a single port in the WSDL) or a -Port option (to specify one of several ports
defined for a single service in the WSDL). For a binding and SOAP endpoint specification, the
minimum required element is the -SOAPEndpoint connection parameter, which can complete the
location specification for a WSDL that defines a single <binding> element. If the WSDL
contains multiple services, ports, or bindings, the connection parameters must specify the
necessary -Service/-Port or -Binding/-SOAPEndpoint options to uniquely and correctly
identify the transport and location.

If the WSDL defines a single service, port, and binding, and you include no service, port, and
binding options in the connection parameters, the WSDL-defined service and port take
precedence. If your connection parameters include both valid -Service/-Port and valid
-Binding/-SOAPEndpoint options, the CONNECT( ) method fails.

In all cases, any specified service, port, or binding options must match the corresponding WSDL
entries exactly with respect to namespace, local name, and letter case; otherwise, the
CONNECT( ) method fails. If the WSDL defines multiple services, ports, or bindings, and the
connection parameters do not specify the necessary service, port, or binding options, the
CONNECT( ) method also fails.

95
OpenEdge Development: Web Services

Table 91 provides a short description for each parameter in the Web service connection
parameter string, in the order they appear in the syntax. For more information on these
parameters, see the CONNECT( ) method entry in the OpenEdge Development: Progress 4GL
Reference.

Table 91: Web service connection parameters (1 of 2)

Connection parameter Description

-WSDL wsdl-document URL or file pathname (possibly relative) to

the WSDL file that describes the Web
service.

-WSDLUserid user-id Username to authenticate access to the

WSDL file (overridden by any username
specified in the WSDL URL).

-WSDLPassword password Password to authenticate access to the

WSDL file (overridden by any password
specified in the WSDL URL).

-Service service-name Name of a <service> element in the WSDL.

-ServiceNamespace service-namespace Namespace to disambiguate

duplicate-named <service> elements.

-Port port-name Name of a <port> element defined in the

specified <service> element.

-Binding binding-name Name of a <binding> element in the WSDL.

-BindingNamespace binding-namespace Namespace to disambiguate

duplicate-named <binding> elements.

-SOAPEndpoint URL-endpoint URL location for the Web service.

-SOAPEndpointUserid user-id Username to authenticate access (by either

-Service or -Binding) to the Web service.

-SOAPEndpointPassword password Password to authenticate access (by either

-Service or -Binding) to the Web service.

-TargetNamespace targetNamespace The target namespace specified in the

WSDL for the Web service must match, as a
verification check.

96
 Connecting to Web Services from the Progress 4GL

Table 91: Web service connection parameters (2 of 2)

Connection parameter Description

-maxConnections num-connections Maximum number of simultaneous

(parallel) connections maintained between
the client and Web service for asynchronous
requests.

-nohostverify If specified, turns off host verification for a

Secure Socket Layer (SSL) connection using
HTTPS. Without this parameter specified,
the client compares the host name specified
in the URL with the Common Name
specified in the server certificate, and raises
an error if they do not match. With this
parameter specified, the client never raises
the error. For more information, see the
sections on managing the OpenEdge
certificate store in OpenEdge Getting
Started: Security.1

-nosessionreuse If specified, the connection does not reuse

the SSL session ID when reconnecting to the
same Web server using HTTPS.1

-pf filename File containing any parameters specified in

the CONNECT( ) method.
1
These connection parameters affect all SSL connections made using the Web service server handle, including
any WSDL file access or Web service access that uses HTTPS.

Using HTTPS

When you use HTTPS to make a secure connection to a Web service, you might have to manage
the OpenEdge certificate store to contain the necessary digital certificates for SSL verification.
For information on managing the OpenEdge certificate store, see OpenEdge Getting Started:
Security.

97
OpenEdge Development: Web Services

Invoking the binding

These examples show use of the two mechanisms for binding an actual Web service:

Binding a Web service in the 4GL using service and port

DEFINE VARIABLE hWebService AS HANDLE.

CREATE SERVER hWebService.
hWebService:CONNECT
("-WSDL http://www.xmethods.net/sd/2001/TemperatureService.wsdl
-Service TemperatureService
-Port TemperaturePort").

Binding a Web service in the 4GL using binding and SOAP endpoint

DEFINE VARIABLE hWebService AS HANDLE.

CREATE SERVER hWebService.
hWebService:CONNECT
("-WSDL http://www.xmethods.net/sd/2001/TemperatureService.wsdl
-Binding TemperatureBinding
-SOAPEndpoint http://www.xmethods.net:80/soap/servlet/rpcrouter").

Note: The public Web service used in these examples might not always be available and its
URL can change at any time.

98
 Connecting to Web Services from the Progress 4GL

Binding results

After a successful attempt to bind a Web service, the server object is initialized for the Web
service. This means that on the server object handle the:

CONNECT( ) method returns the value, TRUE, during invocation.

SUBTYPE attribute returns the value, "WEBSERVICE".

CONNECTED( ) method returns the value, TRUE.

Note: A value of TRUE does not indicate the state of the HTTP/S connection between the
client and Web service. Subsequent requests can fail if there is an HTTP failure at
any point between the client and Web service.

An attempt to bind a Web service can fail for any of the following reasons:

A corrupt WSDL file.

A parameter specification in the connection-parameters string is invalid.

The value specified for the -TargetNamespace parameter does not match the target
namespace specified in the WSDL document. (This is a version check.)

The specified WSDL document is not found.

The value for the -WSDLUserid or the -WSDLPassword parameter is invalid.

99
OpenEdge Development: Web Services

Managing Web service bindings

Once you bind a Web service to a server object handle using the CONNECT( ) method, the Web
service remains bound (server-handle:CONNECTED( ) = TRUE) until you invoke the
DISCONNECT( ) method on that handle to unbind it. Between these two points you can access
the single port type supported by the binding by mapping it to a Web service proxy procedure
object, then invoke and manage Web service operations defined in that port type using the
corresponding Web service proxy procedure handle.

You can also create more than one procedure object for a single port type assigned to different
procedure handles. This allows you greater flexibility in how you handle request and response
messages for the same set of Web service operations. For more information, see Chapter 10,
Invoking Web Service Operations from the Progress 4GL.

To work with additional port types in the same Web service or in different Web services, you
must create a separate Web service binding for each port type you want to access. Depending
on how you choose to manage Web service binding resources, you can do all this using one or
more pairs of server and procedure handles. If your application accesses many port types and
Web services, especially if it disconnects and connects Web service bindings frequently, be sure
to delete the created objects, especially the procedure objects, when you no longer need them in
order to prevent memory leaks in your application.

Accessing a port type for a Web service

While the Web service is bound to a server object, you can create and map a procedure object
to the port type supported by the binding in order to invoke its Web service operations using this
syntax:

Syntax

RUN portTypeName [ SET hPortType ] ON SERVER hWebService .

As a result of executing a RUN statement using this syntax, you can access operations defined by
the specified port type (portTypeName) in the Web service mapped to the server object handle,
hWebService. You can invoke these operations by executing them as procedures or user-defined
functions on the procedure object handle, hPortType, which is now mapped to the port type,
portTypeName.

910
 Connecting to Web Services from the Progress 4GL

The RUN statement accomplishes this mapping by creating a procedure object for the port type
and attaching it to the specified procedure object handle:

Accessing a port type for a Web service

DEFINE VARIABLE hWeatherSrv AS HANDLE.

DEFINE VARIABLE hTempPT AS HANDLE.

CREATE SERVER hWebService.

hWeatherSrv:CONNECT("-WSDL http://.../WorldWeather.wsdl
-Service WeatherService
-Port TemperaturePort").

RUN TemperaturePortType SET hTempPT IN hWeatherSrv.

Note: The abbreviated URL for the Web service in this example is completely fictitious, and
any resemblance to an actual public Web service is coincidental.

You can now invoke and manage all of the operations in the port type, TemperaturePortType,
defined for the Web service, WeatherService. For more information on using procedure
handles to invoke Web service operations, see Chapter 10, Invoking Web Service Operations
from the Progress 4GL.

911
OpenEdge Development: Web Services

Accessing a different port type in the same Web service

You can access a different port type in a Web service using the same server object handle, but
only after disconnecting the server object from its current binding.

To access a different port type in a bound Web service using the same server object
handle:

1. Delete the procedure object mapped to the current port type, using the DELETE PROCEDURE
or DELETE OBJECT statement.

2. Unbind (logically disconnect) the server object handle from its current Web service
binding using the DISCONNECT( ) method.

3. Using the CONNECT( ) method on the same server object handle, bind the server object to
the Web service using a binding that supports the next port type.

4. Create and map a new procedure object to the next port type, using the RUN statement with
the same server object handle, and, if you want, setting the same procedure object handle
used to map the previous port type.

You can repeat this procedure for each port type you need to access in the same Web service,
or you can map all of the Web service port types at one time using multiple server object and
procedure object handles.

Accessing multiple port types simultaneously

If you want to maintain access to two or more port types at the same time (for the same or a
different Web service), you must create and bind the Web service to a separate server object
handle for each port type that you want to access. Then create and map a separate procedure
object handle to each port type.

912
 Connecting to Web Services from the Progress 4GL

This example binds two Web services (WeatherService and SailingService) in order to
access three port types (TemperaturePortType, WindPortType, and RentalPortType) at the
same time:

Accessing multiple port types simultaneously

DEFINE VARIABLE hWebServiceTempPT AS HANDLE.

DEFINE VARIABLE hWebServiceWindPT AS HANDLE.
DEFINE VARIABLE hWebServiceSchedulePT AS HANDLE.

CREATE SERVER hWebServiceTempPT.

CREATE SERVER hWebServiceWindPT.
CREATE SERVER hWebServiceSchedulePT.

hWebServiceTempPT:CONNECT( "-WSDL http://.../WorldWeather.wsdl"

-Service WeatherService
-Port TemperaturePort").
hWebServiceWindPT:CONNECT( "-WSDL http://.../WorldWeather.wsdl"
-Service WeatherService
-Port WindPort").
hWebServiceSchedulePT:CONNECT( "-WSDL http://.../SailingSchedule.wsdl"
-Service SailingService
-Port RentalPort").

DEFINE VARIABLE hTempPT AS HANDLE.

DEFINE VARIABLE hWindPT AS HANDLE.
DEFINE VARIABLE hRentalPT AS HANDLE.

RUN TemperaturePortType SET hTempPT IN hWebServiceTempPT

RUN WindPortType SET hWindPT IN hWebServiceWindPT
RUN RentalPortType SET hRentalPT IN hWebServiceSchedulePT
.
.
.

Note: The abbreviated URLs for the Web services in this example are completely fictitious,
and any resemblance to actual public Web services is coincidental.

913
OpenEdge Development: Web Services

914
 10
Invoking Web Service Operations from
the Progress 4GL

Invoking a Web service operation can be a simple process of returning a value and using it
directly (see Chapter 1, Web Services in OpenEdge), or it can require a more complex
treatment. The more complex treatment can include interacting with the SOAP message
headers, handling SOAP faults, parsing and building complex parameters, or simply managing
the serialized XML of a simple parameter.

The following sections describe how to invoke and manage the data associated with an
operation for all of these requirements:

Preparing to invoke operations

Invoking operations

Managing operation parameters

Managing complex data

OpenEdge Development: Web Services

Preparing to invoke operations

The 4GL interface to Web service operations is a type of proxy procedure object that you map
to a port type supported by a given Web service binding (see Chapter 9, Connecting to Web
Services from the Progress 4GL). This Web service procedure object provides access to
operations defined by a port type in much the same way that a proxy procedure object provides
access to remote internal procedures and user-defined functions defined by a persistent
procedure instantiated on an AppServer (see OpenEdge Application Server: Developing
AppServer Applications).

Creating a Web service procedure object

You map the port type to the procedure object using a syntax similar to how you instantiate a
remote persistent procedure:

Syntax

RUN portTypeName [ SET hPortType ] ON SERVER hWebService [ NO-ERROR ] .

For a 4GL remote persistent procedure, you actually execute the procedure by name
persistently; for a Web service port type, you invoke the operation using the name of the port
type from the WSDL (portTypeName) that defines the operations you want to run. Otherwise,
you can set and access a Web service proxy procedure handle (hPortType) the same way as for
a remote persistent procedure. Like an AppServer, you use the server object handle bound to the
Web service (hWebService) to indicate the remote location to receive Web service requests.

Note the lack of parameters in this statement. Where you might pass parameters when
instantiating a remote persistent procedure, you cannot pass any parameters when creating a
Web service procedure object, and OpenEdge raises an error if you do so.

A Web service procedure object supports one additional method not used on a proxy procedure
object (SET-CALLBACK-PROCEDURE( )). All other attributes and methods on a Web service
procedure object work much like they do for any proxy procedure object, or they return
unknown values (?) and empty strings where they have no meaning for a Web service.

102
 Invoking Web Service Operations from the Progress 4GL

Specifying SOAP header callback procedures at run time

For an AppServer, all information about remote requests is either passed with parameters or
obtained using the attributes and methods of various handles related to the request. For a Web
service, most information about Web service requests is passed with parameters, but some
information is also contained within other elements of the SOAP message. The
SET-CALLBACK-PROCEDURE( ) method allows you to specify internal procedures that can access
the content of the SOAP header element in a SOAP message as part of the invocation of a Web
service operation that generates the message.

The SET-CALLBACK-PROCEDURE( ) method registers an internal procedure with a specified

Progress callback, a designation that causes the internal procedure (callback procedure) to
execute in response to some Progress core action, such as in this case, sending and receiving
SOAP messages. For Web services, this method supports two types of Progress callbacks:

"REQUEST-HEADER" Identifying a SOAP request header callback procedure. This

procedure executes just after you invoke a Web service operation and just before
OpenEdge sends the SOAP request message to the Web service. It allows you to create or
pass an existing SOAP header for use as the SOAP header of an out-going SOAP request
message

"RESPONSE-HEADER" Identifying a SOAP response header callback procedure. This

procedure executes just after OpenEdge receives the message sent by the Web service in
response to processing the Web service operation that you invoked, and just before it
makes any output or return parameters available to the 4GL calling context. It allows you
to examine the SOAP header of an in-coming SOAP message.

Note: The SOAP response header callback procedure executes in response to receiving
either a normal SOAP response message or a SOAP fault message generated for
the Web service request. However, a SOAP header is only available in a SOAP
response that is not a SOAP fault.

A single Web service procedure object can support only one request header callback and one
response header callback at one time. This means that for a single procedure object, you must
use the same callbacks for all operations invoked on that procedure object. However, if you
want greater flexibility to use different callbacks for the same set of operations, you can use the
RUN portTypeName statement to create an additional Web service procedure object for the same
port type. You can then invoke the SET-CALLBACK-PROCEDURE( ) method on the new procedure
object to assign a different set of callback procedures for use by that same port type. By creating
additional Web service procedure objects this way, you can then assign as many callback
procedures for a single port type as you want.

103
OpenEdge Development: Web Services

Using the SET-CALLBACK-PROCEDURE( ) method

This is the syntax for the SET-CALLBACK-PROCEDURE( ) method:

Syntax

SET-CALLBACK-PROCEDURE (callback-name, internal-procedure

[ , procedure-context ])

The parameters include:

callback-name A character string value of "REQUEST-HEADER" or "RESPONSE-HEADER"

to identify the type of callback. If this is the only parameter specified, no internal
procedure will be executed for the specified callback (the default), and effectively clears
any previous callback specification for this type of callback.

internal-procedure A character string value containing the name of the internal

procedure you want executed for the specified callback or an empty string, which deletes
a previous callback definition.

procedure-context (Optional) A procedure object handle that points to an active

procedure context that contains the specified internal procedure. This is typically a
persistent procedure instantiated in the current OpenEdge session or the method calling
context (THIS-PROCEDURE). If not specified, it is the value of THIS-PROCEDURE.

Defining SOAP header callback procedures

In general, you can define the internal procedure for a callback in any procedure context that is
guaranteed to be active at the time you execute the SET-CALLBACK-PROCEDURE( )method, and
that remains active until after the callback procedure is executed by OpenEdge. The time of this
execution depends on the type of request:

Synchronous Web service requests For either a SOAP request header callback or a
SOAP response header callback, the procedure context must remain active until the
operation invocation has completed execution.

Asynchronous Web service requests For a SOAP request header callback, the
procedure context must remain active until the operation invocation has completed
execution. For a SOAP response header callback, the procedure context must remain
active until activation of the PROCEDURE-COMPLETE event for the request and any results
have been returned to the PROCEDURE-COMPLETE event procedure.

104
 Invoking Web Service Operations from the Progress 4GL

For each type of callback procedure that you define, you must provide a specific procedure
signature. For more information on this signature, see Chapter 11, Handling SOAP Message
Headers in the Progress 4GL.

Invoking operations
After you have created a Web service procedure object, you can invoke the operations made
available through that object. OpenEdge identifies Web service operations in the 4GL by the
same names and signatures used to define them in the WSDL file for the Web service, which
you specify when you bind the Web service using the CONNECT( ) method (see Chapter 9,
Connecting to Web Services from the Progress 4GL.).

The WSDL Analyzer determines if you can invoke the operation using only a 4GL RUN
statement or if you can also a user-defined function call:

If the Analyzer determines that the operation does not return a value, it defines the
operation as an internal procedure that you must call using the RUN statement.

If the Analyzer determines that the operation returns a value, it defines the operation in
both of the following ways:

a. As a user-defined function that you forward reference and invoke as a function.

b. As an internal procedure that you can call using the RUN statement.

Note: You cannot invoke native 4GL procedures or user-defined functions

interchangeably as one or the other. This feature only applies to Web service
operations, and only those Web service operations as specified by the WSDL
Analyzer.

Any attempt to invoke a Web service operation using a method not specified by the WSDL
Analyzer returns an error.

105
OpenEdge Development: Web Services

Using the RUN Statement

This is the general syntax for invoking operations using the RUN statement:

Syntax

RUN operationName IN hPortType [ ASYNCHRONOUS ... ]

[ ( parameter [ , parameter ] ... ) ]
[ NO-ERROR ] .

As indicated, this statement invokes a Web service operation with the specified name
(operationName) defined in the port type mapped to the specified procedure object handle
(hPortType), passing any parameters with data types specified in the order they are defined for
the operation by the WSDL Analyzer. Also, you can invoke any operation using the RUN
statement either synchronously or asynchronously. For more information on asynchronous
invocation for Web service operations, see Chapter 1, Web Services in OpenEdge. For
complete information on the RUN statement syntax, see OpenEdge Development: Progress 4GL
Reference.

Using a User-defined Function

The invocation for a user-defined function contains no information about its mapping to a Web
service operation or remote user-defined function. Thus, for a user-defined function invocation,
you must first forward reference a prototype mapped to the appropriate Web service procedure
handle definition, exactly as you do for a remote user-defined function prototype mapped to a
Web service proxy procedure handle.

This is the general syntax for the forward reference to a function prototype:

Syntax

FUNCTION operationName [ RETURNS ] dataType

[ ( parameter [ , parameter ] ... ) ]
IN hPortType .

This statement invokes a Web service operation with the specified name (operationName)
defined in the port type mapped to the specified procedure object handle (hPortType), passing
any parameters with data types specified in the order they are defined for the operation by the
WSDL Analyzer, and passing the operation return parameter with the corresponding data type
(dataType).

106
 Invoking Web Service Operations from the Progress 4GL

This is the syntax for simple invocation of one user-defined function in a single statement, the
same for both Web service operations and user-defined functions:

Syntax

return = operationName [ ( parameter [ , parameter ] ... ) ].

This statement invokes a user-defined function with the specified name (operationName),
passing any parameters with data types specified in the order they are defined for the operation
by the WSDL Analyzer, and passing the operation return parameter as the value of the function,
which is assigned to a variable of compatible data type. As with any function, you can invoke
it in any 4GL statement where you need to use its value. However, you can only invoke a Web
service user-defined function synchronously. For complete information on the FUNCTION
statement prototype syntax, see OpenEdge Development: Progress 4GL Reference.

Managing operation parameters

As previously described (see Chapter 8, Analyzing WSDL for Progress 4GL Access to Web
Services), the data types that you specify for parameters in the 4GL invocations of Web service
operations must conform to a set of OpenEdge-supported castings established for corresponding
XML Schema data types. The OpenEdge WSDL Analyzer provides all of the information you
need to build interfaces between your 4GL application and the Web service by documenting all
of the Web service operations and how they can be mapped to the 4GL, including the suggested
(or recommended) 4GL data types to use for XML Schema simple data type parameters.

Depending on the results you want to achieve, you might use an alternative data type dictated
by the alternative castings supported by OpenEdge between XML Schema simple data types
and 4GL data types. Consistent with compatible data types in the 4GL, OpenEdge implicitly
converts between any XML Schema data type and any 4GL data type included in the supported
casting. If OpenEdge cannot complete the specified conversion, it generates a run-time error.

107
OpenEdge Development: Web Services

You can also map all XML Schema simple data types to the 4GL CHARACTER or LONGCHAR type,
because the SOAP messages used to exchange parameter values are XML character data. For
XML Schema simple data types where CHARACTER is not the suggested 4GL data type, using a
CHARACTER or LONGCHAR causes OpenEdge to assume that you are passing the XML
Schema-formatted string (the actual string value of the XML Schema element) as the value for
the parameter. This allows you to perform your own transformation on the value within your
4GL application and to manage the value as you see fit. In doing this, you must format the
CHARACTER/LONGCHAR values properly for any INPUT parameters to conform with the XML
Schema data type defined for the Web service parameter by the WSDL. The only processing
that OpenEdge does when passing XML Schema-formatted values is to perform any code page
conversion required on the character data (for example, between the CPINTERNAL code page
setting and UTF-8) and to validate that the format of the data is acceptable for the XML Schema
data type. OpenEdge does no range or value checking that might be specified in the WSDL file.

For XML Schema complex types, data types containing multiple XML Schema data elements
(including other complex types), you must map them to either the 4GL CHARACTER or LONGCHAR
type. Complex type values contain multiple values structured in a hierarchical fashion,
according to the arrangement of XML elements that describe them. To manage these values,
you must work with the serialized XML directly, typically using the XML parsers in the 4GL.
For more information, see the Managing complex data section on page 108.

In general, if the invocation of a Web service operation fails for any reason, OpenEdge sets all
OUTPUT and function return values to the unknown value (?).

Managing complex data

Wherever you encounter complex data, for a Web service, you must access and manage that
data as serialized XML. Complex data that you might need to access includes:

Complex type parameters (defined by the XML Schema <complexType> element),

including complex arrays.

SOAP header entries.

SOAP fault detail.

108
 Invoking Web Service Operations from the Progress 4GL

Types of complex data

For an OUTPUT parameter, you can work with serialized XML in the CHARACTER or LONGCHAR
parameter directly, using 4GL string-manipulation statements and functions, or work with it in
its parsed form using the 4GL SAX reader or DOM parser. In any case, OpenEdge provides the
entire <complexType> element for the value, exactly as it appears in the SOAP response
message.

For an INPUT parameter, you can build or maintain the required <complexType> element using
the 4GL DOM parser, and save the result as a LONGCHAR value when you are ready to pass it as
an INPUT parameter to the Web service. (The DOM parser is your only choice, as there is no
4GL SAX writer to serialize the XML.)

Note: When you save the parsed XML as a serialized character string, the DOM parser adds a
prolog element to the XML data intended for input to the Web service. OpenEdge
automatically handles this prolog element when it inserts the intended INPUT parameter
value into the SOAP request message.

You can also use the same techniques to access and manage the data for SOAP header entries
and SOAP fault detail. You can get and set this data either as serialized character strings or as
DOM trees. For more information, see Chapter 11, Handling SOAP Message Headers in the
Progress 4GLand Chapter 12, Handling Errors in Progress 4GL Requests to Web Services.

Complex data example

The following examples show how you might manage a complex parameter, or any complex
data, in this case, an OUTPUT parameter. This is a procedure that maps to a Web service
operation, getAddress. Given a social security number (ssn), the operation returns an address
(Address) as a complex type:

4GL prototype for operation with complex type

PROCEDURE getAddress:
DEFINE INPUT PARAMETER ssn AS CHARACTER.
DEFINE OUTPUT PARAMETER Address AS LONGCHAR.
END PROCEDURE.

109
OpenEdge Development: Web Services

This is the schema for <complexType> element that returns the address information to the caller.
It contains five string data type elements representing the components of the address:

Complex type in the WSDL

<complexType name="Address">
<sequence>
<element name="name" type="xsd:string">
<element name="street" type="xsd:string">
<element name="city" type="xsd:string">
<element name="state" type="xsd:string">
<element name="zip-code" type="xsd:string">
</sequence>
</complexType>

This sample 4GL procedure demonstrates how you can manage this complex type in the 4GL.
The variable to receive the parameter value, cmAddress, is defined as a LONGCHAR, which is
essentially a CHARACTER-compatible MEMPTR. After the Web service operation returns a value for
cmAddress, the LOAD( ) method on the x-document handle, hXDoc, parses and loads the
<complexType> element from cmAddress into the associated x-document object.

Because the schema of the complex type is known, the remaining x-document and x-noderef
handle methods simply retrieve the root node from the Address DOM tree, and pick off the
component value (text element) for each of the five component nodes that comprise the complex
type, in order, assigning them to the corresponding fields of a database record.

Note: The URL for the Web service in the following example is completely fictitious, and any
resemblance to an actual public Web service is coincidental.

1010
 Invoking Web Service Operations from the Progress 4GL

Complex type managed in the 4GL

DEFINE VARIABLE hWS AS HANDLE.

DEFINE VARIABLE hAddrPortType AS HANDLE.
DEFINE VARIABLE cmAddress AS LONGCHAR.

CREATE SERVER hWS.

hWS:CONNECT ("-WSDL http://www.zzzcompany.org/ssn.wsdl

-Service addressSVC
-Port addressPort").

RUN addressPortType SET hAddrPortType ON SERVER hWS.

RUN getAddress IN hAddrPortType (INPUT "555-55-5555", OUTPUT cmAddress).

DEFINE VARIABLE hXDoc as HANDLE.

DEFINE VARIABLE hXRoot as HANDLE.
DEFINE VARIABLE hXNode as HANDLE.
DEFINE VARIABLE hXText as HANDLE.

CREATE X-DOCUMENT hXDoc.

CREATE X-NODEREF hXRoot.
CREATE X-NODEREF hXNode.
CREATE X-NODEREF hXText.

hXDoc:LOAD("LONGCHAR", cmAddress, FALSE).

hXDoc:GET-DOCUMENT-ELEMENT(hXRoot).

/* because we know the content, we are just moving straight ahead

and getting each one of the nodes under the root, then getting its
TEXT node to get the data we're interested in. */
hXRoot:GET-CHILD(hXNode, 1).
hXNode:GET-CHILD(hXText, 1).

/* let's assume we have a DB table with the appropriate fields */

myTable.name = hXText:NODE-VALUE.

/* ... */

hXRoot:GET-CHILD(hXNode, 5).
hXNode:GET-CHILD(hXText, 1).
myTable.zip-code = hXText:NODE-VALUE.

/* clean up */
/* ... */

hWS:DISCONNECT( ).

1011
OpenEdge Development: Web Services

1012
 11
Handling SOAP Message Headers in the
Progress 4GL

SOAP headers are an optional part of a SOAP message and the requirement to use them depends
on the Web service. Many Web services require no client handling of SOAP headers.

If the Web service requires you to handle SOAP headers, especially if you need to modify or
examine the contents of a SOAP header, you need to know XML and understand the Progress
4GL facilities for parsing and managing XML. This includes 4GL support for parsing and
directly manipulating an XML document in a Document Object Model (DOM) tree or parsing
and reading the elements of an XML document using the Simple API for XML (SAX). For more
information on these facilities, see OpenEdge Development: Programming Interfaces.

This chapter describes how to define and use specified callback procedures (header handlers)
that manage the SOAP headers for SOAP request and response messages:

SOAP message headersan overview

Defining header handlers

Creating and managing SOAP message headers

Managing memory for SOAP headers

Attributes and methods for handling SOAP headers

For information on how to declare an internal procedure as a callback procedure for handling
headers, see Chapter 10, Invoking Web Service Operations from the Progress 4GL.
OpenEdge Development: Web Services

SOAP message headersan overview

A SOAP request message or a SOAP response message can contain an optional <Header>
element (header) that passes non-parameter information about the Web service or the operation
that generates it. This header can contain one or more header entries. A header entry contains
certain information defined by the Web service that is necessary to properly invoke some or all
of its operations.

A header returned by the Web service in a SOAP response message is a SOAP response header.
A header sent in a SOAP request message by invoking a Web service operation is a SOAP
request header. Syntactically, there is no difference between these two types of headers.
However, keeping them conceptually separate helps to clarify how you can manage them for a
Web service operation. For a given operation, the content of any SOAP request header can be
different from that of any SOAP response header.

Why are headers necessary if operations already pass data as parameters? Headers can simplify
the management of data for users of certain Web services that require the management of
context (such as user authentication) during the course of Web service interaction. With the use
of headers, the mainline of a client application need have no concern about maintaining these
states. The Web service provider typically provides specific information about the content of
headers and how they must be handled by client applications. The client can then provide
special header handlers, which are callback procedures that manage the content of these
headers for the Web service application.

112
 Handling SOAP Message Headers in the Progress 4GL

SOAP header structure

The following XML contains a SOAP header as it might appear inside a SOAP message:

SOAP message with header

<soap:Envelope>
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
. . .
<soap:Header>
<q1:OrderInfoID
xmlns:q1="http://www.example.com/webservices/OrderInfo"
SOAP-ENV:mustUnderstand="1"
SOAP-ENV:actor="/WSA">
<uuid xsi:type="xsd:string">12345-67890-98765-4321</uuid>
</q1:OrderInfoID>
<t:Transaction
xmlns:t="http://www.example.com/webservices/Transaction"
SOAP-ENV:mustUnderstand="1" t:stepnum="1">
<t:TransID>5</t:TransID>
<t:SubID>871</t:SubID>
</t:Transaction>
</soap:Header>
<soap:Body ...>
<parameter-element> ... </parameter-element>
. . .
</soap:Body>
</soap:Envelope >

As you can see, the <Header> element is, itself, nothing more than a container for other
elements, the application-specific header entry elements. Any parameters generated for an
operation in this SOAP message appear in the <Body> element in much the same way.

In this case, the SOAP header contains two header entries, named q1:OrderInfoID and
t:Transaction (where q1: and t: are namespace prefixes). Each of these elements has a series
of attributes and contains one or more child elements. The <q1:OrderInfoID> element contains
one child element named uuid, and the <t:Transaction> element contains two child elements,
named t:TransID and t:SubID. All of these element names are application-defined.

113
OpenEdge Development: Web Services

Accessing the SOAP header

To access the SOAP header and its elements from your 4GL application, you define callback
procedures using specific signatures to use as header handlers, depending on whether the
procedure is used to access a SOAP response header or a SOAP request header. As a minimum,
you might not have to access message headers at all. If you need to access the headers, you can
define one header handler to manage all of the SOAP request headers and another header
handler to manage all of the SOAP response headers that are generated for operations of a single
Web service procedure object. You can specify the handlers for a Web service procedure object
by invoking the SET-CALLBACK-PROCEDURE( ) method on the corresponding procedure handle.
If you want to add additional handlers for the same port type managed by a Web service
procedure object, you must map the port type using additional procedure objects. For more
information, see the information on specifying header callback procedures in Chapter 10,
Invoking Web Service Operations from the Progress 4GL.

Every time you invoke an operation for a port type where you have specified header handlers,
the handlers execute as part of the operation invocation. They intercept and manage the SOAP
headers as part of sending a SOAP request message, before the message is sent to the Web
service, and as part of receiving a SOAP response message, before any message parameters are
passed to complete invocation of the operation.

Requirements for header handlers

Note that there is no absolute requirement to use header handlers. The need for managing
headers depends entirely on the requirements of the Web service that you are accessing. You
can also set and reset the callbacks for header handlers as often as you need to specify the correct
handlers for different operations and port types, add additional header handlers for a single port
type by mapping the port type to additional Web service procedure objects, and you can remove
any previously specified callbacks entirely when you have no need to handle the SOAP headers
for an operation or port type. The only absolute requirement for a header handler is the signature
that you must use to define it.

For more information on:

How to specify callback procedures as header handlers, see Chapter 10, Invoking Web
Service Operations from the Progress 4GL.

The general cycle of operation for header handlers in the 4GL, see the Invoking a header
handler section on page 118.

Defining the callback procedures for header handlers, see the Defining header handlers
section on page 1110.

114
 Handling SOAP Message Headers in the Progress 4GL

SOAP header object model

The most important part of a header handler signature is a HANDLE parameter that references the
header of a SOAP message. This handle references SOAP header object that maps to the parsed
XML of the actual SOAP message header in the form of a DOM tree. This SOAP header object
implements part of an object model that allows you to directly access the XML content of the
SOAP header without having to parse it out of the SOAP message. Figure 111 shows the
relationship between the SOAP header object model and the parsed XML DOM tree using the
SOAP header described in the previous section.

The complete SOAP header object model includes two types of objects:

SOAP header object References the <Header> element of a SOAP message.

SOAP header-entryref object References one of the header entry elements in a SOAP
header as specified by the GET-HEADER-ENTRY( ) method on the SOAP header object. The
SOAP header entryref object can also reference a header entry element that you add to the
SOAP header using the ADD-HEADER-ENTRY( ) method on the SOAP header object.

SOAP header Parsed XML

object model DOM tree
SOAP SOAP
header object Header

SOAP
header - Transaction
entryref object
GET/ADD-HEADER -ENTRY( )

SubID TransID

SOAP
header - OrderInfoID
entryref object

GET/ADD-HEADER-ENTRY( ) Uuid

Figure 111: Referencing a header entry in the SOAP header object model

115
OpenEdge Development: Web Services

The SOAP header object handle also provides attributes that return information about the name
of the header and the number of header entries that the header contains.

In Figure 111, one SOAP header-entryref object references the Transaction header entry and
another object references the OrderInfoID header entry. When working with a SOAP header,
you can also use a single SOAP header-entryref object to reference all of the header entries in
a SOAP header, one at a time. The SOAP header-entryref object handle provides several 4GL
attributes and methods that allow you to inspect and modify the contents of the header entry that
it references. The attributes return the values of standard SOAP attributes contained in the
header entry element, such as the name and namespace of the header entry.

The SOAP header-entryref object handle provides two methods for accessing the element
subtree of the SOAP header entry that it references, as shown in Figure 112.

SOAP header Parsed XML

object model DOM tree
SOAP SOAP
header object Header

Transaction

SOAP
X-noderef
header -
object SubID TransID
entryref object

GET/SET-NODE( )
OrderInfoID

LONGCHAR
GET/SET-SERIALIZED ( )
Uuid

Figure 112: Accessing entry elements in the SOAP header object model

116
 Handling SOAP Message Headers in the Progress 4GL

The:

GET-NODE( ) method assigns an X-noderef object to reference the root node of the header
entry in the DOM subtree of the header entry. You can then use this X-noderef object to
examine the XML elements by walking and returning values for the nodes of the header
entry DOM subtree.

GET-SERIALIZED( ) method assigns a LONGCHAR value that contains the entire header entry
as a serialized XML string that you can parse yourself using either the 4GL SAX reader
or DOM parser.

The SOAP header-entryref object handle also provides two corresponding methods for
replacing the entire content of the SOAP header entry that it references:

The SET-NODE( ) method replaces the content of the header entry with the DOM subtree
whose root node is currently referenced by a specified X-noderef object.

The SET-SERIALIZED( ) method replaces the content of the header entry with a DOM
subtree that it parses from a specified LONGCHAR value containing the serialized XML
for the header entry.

For more information on these objects and all the attributes and methods that they support, see
the Creating and managing SOAP message headers section on page 1113.

117
OpenEdge Development: Web Services

Invoking a header handler

The following procedure fragment shows how the 4GL might specify and invoke a header
handler for the SOAP message described in the previous sections, in this case returned as a
SOAP response message:

Invocation of a header handler

/*** PROCEDURE: Start transactions on an order. ***/

DEFINE INPUT PARAMETER OrderNum AS INTEGER.
DEFINE OUTPUT PARAMETER hOrderSvc AS HANDLE.
DEFINE OUTPUT PARAMETER gcUUID AS CHARACTER.

/* Create hOrderSvc server handle and connect to order Web service. */

.
.
.
/* Create hPortType procedure handle and map port type to it. */
.
.
.
/* Set up response header handler. */
hPortType:SET-CALLBACK-PROCEDURE( "RESPONSE-HEADER",
"TransactionResponseHandler",
THIS-PROCEDURE ).
/* Start a transaction on an order. */
RUN startTransaction( "ORDER", OrderNum ) IN hPortType NO-ERROR.
.
.
.

This fragment specifies the response header handler for an internal procedure named
TransactionResponseHandler that is defined in the current external procedure context. Then,
it invokes a startTransaction procedure as the first operation. As the name and parameters
imply, this operation begins a transaction on the order (perhaps automatically retrieved or
created, as necessary) with the specified order number.

One can imagine that the SOAP response message returned by this operation has a header
containing database object and transaction state information for the transaction that was started.
Our typical SOAP message contains just such information, including an ID for the order (the
<q1:OrderInfoID> element) and some values identifying the transaction that is managing the
order (the <t:Transaction> element).

118
 Handling SOAP Message Headers in the Progress 4GL

The following internal procedure defines the TransactionResponseHandler callback

procedure for the header handler. In this case, the handler locates the <uuid> element in the
OrderInfoID header entry within the SOAP header referenced by the SOAP header object
handle parameter, hSOAPHeader:

Definition of a header handler procedure

/*
This response handler looks for a header entry named "OrderInfoID" and
assumes that it contains an element named "uuid". The handler saves away
the value of "uuid". This routine assumes that the SOAP header is no longer
needed after the callback completes.
*/
PROCEDURE TransResponseHandler:
DEFINE INPUT PARAMETER hSOAPHeader AS HANDLE.
DEFINE INPUT PARAMETER cOperationNamespace AS CHARACTER.
DEFINE INPUT PARAMETER cOperationLocalname AS CHARACTER.

DEFINE VARIABLE hsheEntry AS HANDLE.

CREATE SOAP-HEADER-ENTRYREF hsheEntry IN WIDGET-POOL "soap".

DEFINE VARIABLE hxnTemp AS HANDLE.

DEFINE VARIABLE hxnWorkRoot AS HANDLE.
DEFINE VARIABLE hxnTemp2 AS HANDLE.

CREATE X-NODEREF hxnTemp IN WIDGET-POOL "soap".

CREATE X-NODEREF hxnTemp2 IN WIDGET-POOL "soap".
CREATE X-NODEREF hxnWorkRoot IN WIDGET-POOL "soap".

/* Walk the SOAP-HEADER's list of header entries, */

/* looking for the "OrderInfoID" header entry */
DEFINE VARIABLE idx AS INTEGER.
REPEAT idx = 1 TO hSOAPHeader:NUM-HEADER-ENTRIES:
hSOAPHeader:GET-HEADER-ENTRY(hsheEntry, idx).
IF hsheEntry:LOCAL-NAME = "OrderInfoID" AND
hsheEntry:NAMESPACE-URI =
"http://www.example.com/webservices/OrderInfo"
THEN DO:
/* Get the X-noderef side of the hsheEntry
so we can navigate its body. */
hsheEntry:GET-NODE(hxnWorkRoot).
hxnWorkRoot:GET-CHILD(hxnTemp, 1). /* hxnTemp is now uuid node */
hxnTemp:GET-CHILD(hxnTemp2,1). /* hxnTemp2 is text node of uuid */
gcUUID = hxnTemp2:NODE-VALUE. /* save the text content */
END.
END.
/* Delete all objects created in this procedure. */
DELETE WIDGET-POOL "soap".
/* Delete the SOAP header freeing all of its memory. */
DELETE OBJECT hSOAPHeader.
END PROCEDURE.

119
OpenEdge Development: Web Services

It then saves the uuid string value to an OUTPUT parameter(gcUUID)defined globally in the
calling procedure context. This is all accomplished using methods and attributes of the SOAP
header object, SOAP header entry object, and x-noderef objects to access the parsed XML
DOM tree of the SOAP header.

Defining header handlers

A 4GL application does most of the work for accessing or creating a SOAP header in the two
header handlers that you can invoke for Web service operations (Chapter 10, Invoking Web
Service Operations from the Progress 4GL). These include a callback procedure for handling
the SOAP response message header and another callback procedure for handling the SOAP
request message header for the operation. This is the syntax for defining the signatures for these
two procedures:

SOAP response header callback procedure:

Syntax

PROCEDURE response-header-procname :
DEFINE INPUT PARAMETER hSOAPHeader AS HANDLE .
DEFINE INPUT PARAMETER cOperationNamespace AS CHARACTER .
DEFINE INPUT PARAMETER cOperationLocalName AS CHARACTER .
END PROCEDURE .

SOAP request header callback procedure:

Syntax

PROCEDURE request-header-procname :
DEFINE OUTPUT PARAMETER hSOAPHeader AS HANDLE .
DEFINE INPUT PARAMETER cOperationNamespace AS CHARACTER .
DEFINE INPUT PARAMETER cOperationLocalName AS CHARACTER .
DEFINE OUTPUT PARAMETER lDeleteOnDone AS LOGICAL .
END PROCEDURE .

1110
 Handling SOAP Message Headers in the Progress 4GL

These are the parameters:

response-header-procname The name of a response header handler procedure.

Specified as a character expression to the SET-CALLBACK-PROCEDURE( ) method along
with the "RESPONSE-CALLBACK" setting.

request-header-procname The name of a request header handler procedure. Specified

as a character expression to the SET-CALLBACK-PROCEDURE( ) method along with the
"REQUEST-CALLBACK" setting.

hSOAPHeader A handle to a SOAP header object that encapsulates the header of the
SOAP message that is about to be sent (request header) or that has just been received
(response header). In a response header handler, the SOAP header object has no content if
the NUM-HEADER-ENTRIES attribute on the object handle returns the value 0; otherwise it
contains one or more SOAP header entries. In a request header handler, this is an OUTPUT
parameter, therefore if the outgoing SOAP message requires a SOAP header, you must
either build a SOAP header for this parameter to reference or provide an existing SOAP
header saved from a previous response callback.

cOperationNamespace Contains the namespace portion of the operations qualified

name. Use this parameter together with the cOperationLocalName parameter if you need
to identify the operation for which the SOAP message is being sent or received.

cOperationLocalName Contains the local-name portion of the operation's qualified

name. Use this parameter together with the cOperationNamespace parameter if you need
to identify the operation for which the SOAP message is being sent or received.

lDeleteOnDone (Request callback only) Tells OpenEdge to delete the SOAP header
object and all of the parsed XML after the SOAP header has been inserted into the
out-bound SOAP message. For more information on the scope of these objects, see the
Managing memory for SOAP headers section on page 1131.

For both types of callback procedure you can use the INPUT parameters, cOperationNamespace
and cOperationLocalName, to determine the Web service operation for which the message is
generated. You might use this information either to determine how to parse the SOAP response
header based on the invoked operation or to build a SOAP request header that is specific to the
invoked operation.

1111
OpenEdge Development: Web Services

If you need to pass context between the code that invokes a Web service operation and a header
callback procedure, you can pass the context information as you might for any internal
procedure:

Use procedure variables global to the calling code, if the callback procedure is defined
within the context of the calling code.

Use the PRIVATE-DATA attribute on the procedure context handle (THIS-PROCEDURE) of the
header handler.

Defining a response header handler

The response header handler receives a SOAP header object as an input parameter. This object
references the SOAP header entries returned by the Web service for an operation. You might
need to save the entire SOAP header for use in a subsequent request, or you might need to save
specific information from one or more individual header entries for validation or some other
application purpose. Such requirements dependent entirely on the Web service. However, when
your application no longer needs the input header itself, you must delete the SOAP header
object explicitly.

Caution: After receiving a response message for which a header handler has been defined,
OpenEdge creates a SOAP header object for input to the header handler even if the
message contains no SOAP header. Your application must manage the lifetime of
this response header object even if it does nothing else except delete the object
(typically done in the response header handler). To avoid having to manage SOAP
header objects for response messages that do not contain headers, do not define a
response header handler for these response messages or unregister any that you have
defined.

1112
 Handling SOAP Message Headers in the Progress 4GL

Defining a request header handler

The main function of a request header handler is to build a SOAP <Header> element appropriate
for the operation. You can do this by creating a SOAP header object and associating with it the
required number of SOAP header entries. The handler has an OUTPUT parameter (hSOAPHeader)
that you can use to pass the SOAP header that you have built to OpenEdge to insert into the
outgoing SOAP message. Any changes you make in the handler to the SOAP header object or
its constituent SOAP header-entryref objects are integrated into the SOAP message when the
handler completes execution. Thus, if the SOAP header that you return in this procedure
contains SOAP header entries, OpenEdge sends out the SOAP message containing a
corresponding header element. If you do not set the SOAP header object OUTPUT parameter
(hSOAPHeader), OpenEdge does not include a header in the outgoing SOAP message.

If you create a SOAP header in the handler, with potentially multiple SOAP header entries, you
are responsible for cleaning up the memory that is used for it. As an aid for deleting this object,
and its memory, you can set the lDeleteOnDone parameter for output. Setting this parameter to
TRUE, directs OpenEdge to delete the SOAP header object after OpenEdge has copied the
object's contents to the outgoing message. Otherwise, your application must manage the lifetime
of this object and determine when the object gets destroyed.

Caution: Do not explicitly delete the header object within the context of the request header
handler (before it completes). If you do this, OpenEdge never gets the header to
include in the SOAP request message.

Creating and managing SOAP message headers

Depending on the requirements of the Web service, you can work with SOAP headers in several
different ways. Three basic use cases that a Web service might require for handling SOAP
headers in a client application include:

1. Re-using a SOAP header that it has created for a response message that you must return
unchanged in a subsequent request message.

2. Re-using a SOAP header that it has created for a response message that you must return in
a subsequent request message, but modified with additional or updated header entries.

3. Building a unique SOAP header from scratch to provide as output from the request header
handler.

1113
OpenEdge Development: Web Services

As described previously (see the SOAP header object model section on page 115), the 4GL
represents a SOAP message header as:

One SOAP header object.

One SOAP header-entryref object to access each SOAP header entry.

One X-noderef object to access a selected SOAP header entry as a DOM subtree, thus
modeling the underlying XML of the header entry for access by the Progress 4GL one
node at a time.

Depending on the situation, you might need to work only at the level of the SOAP header object
with no need to inspect the contents, or you might need to access individual SOAP header
entries and their individual XML elements.

Thus, the following sections describe examples of each of the three basic use cases presented in
this section that you are most likely to encounter when managing SOAP headers as part of Web
service access:

Reusing an unchanged SOAP response header.

Modifying a reused SOAP response header.

Using a client-created SOAP request header.

All of these examples are based on a fictitious Web service (HeaderExample), using code that
has been run against a working version of the Web service. In the code examples, listed steps
refer to the numbers in comments, such as /*2b*/ or /*9*/.

1114
 Handling SOAP Message Headers in the Progress 4GL

Reusing an unchanged SOAP response header

This example shows how you might handle a SOAP header that you first encounter in the
response message returned from the Web service, then use unchanged as the SOAP header for
the next request. This is an example of the header returned from the Web service:

SOAP response header to be reused

<soap:Envelope>
. . .
<soap:Header>
<AuthHeader xmlns="http://ServiceHost/SOAPHeader">
<AccessID>XYZZY</AccessID>
</AuthHeader>
</soap:Header>
. . .
</soap:Envelope >

It contains one header entry, AuthHeader, that contains a value used as an access key
(AccessID). This type of header might be used when the Web service and client maintain a
consistent context for each other between requests.

1115
OpenEdge Development: Web Services

This is the mainline of a procedure that invokes the Web service to reuse the response header:

Invoking a request that reuses an unchanged SOAP response header

/*
* SOAPHeader1.p
*
* Calls a ficticious Web service, first to request access, which
* gets back a SOAP response header containing an AccessID,
* and sends the response header back as part of a new request
* using the required access credential that allows the Web service
* to respond appropriately to the follow-up request.
*
* The Web service has only one service and port available.
*/
/*1*/
/* Define local variables */
DEFINE VARIABLE hWebSrvc AS HANDLE.
DEFINE VARIABLE hPortType AS HANDLE.
DEFINE VARIABLE cResponse AS CHARACTER FORMAT "x(72)".
DEFINE VARIABLE g_header AS HANDLE.

/* Create the Web service server object */

CREATE SERVER hWebSrvc.

/* Connect to the Web service */

hWebSrvc:CONNECT("-WSDL
http://ServiceHost/SOAPHeader/HeaderExample.asmx?wsdl").

/* Get the method, set the port type */

RUN HeadersSoap SET hPortType ON hWebSrvc.
/*2*/
/* Associate the req. & resp. callbacks with the port type */
hPortType:SET-CALLBACK-PROCEDURE("REQUEST-HEADER", "ReqHandler").
hPortType:SET-CALLBACK-PROCEDURE("RESPONSE-HEADER", "RespHandler").
/*3*/
/* Invoke the Web service with no header and display the results */
RUN OpenAccess IN hPortType (OUTPUT cResponse).
DISPLAY cResponse LABEL "WS response" WITH FRAME aaa.
/*4*/
/* Go again with the AccessID set from previous response header */
cResponse = "".
RUN HelloWorld IN hPortType (OUTPUT cResponse).
DISPLAY cResponse LABEL "WS response" WITH FRAME bbb.
/*5*/
DELETE OBJECT g_header.
DELETE OBJECT hPortType.
hWebSrvc:DISCONNECT().
DELETE OBJECT hWebSrvc.

/**************** Internal Procedures ****************/

1116
 Handling SOAP Message Headers in the Progress 4GL

This code:

1. Defines several mainline variables, including a global handle to reference the reused
SOAP header (g_header).

2. Registers the request header (ReqHandler) and response header (RespHandler) handlers
after connecting to the Web service and instantiating the HeaderSoap port type procedure
object.

3. Runs the OpenAccess procedure to invoke the Web service operation that returns the
AccessID value in the SOAP response header (see the Response header handler for
returning a header for reuse section on page 1118).

4. Runs the HelloWorld procedure to invoke the next Web service operation, passing back
the SOAP response header to the Web service unchanged as the SOAP request header (see
the Request header handler for reusing a header section on page 1119).

5. Cleans up the global objects maintained in its context and disconnects from the Web
service. Note that one of the objects it deletes is the original SOAP response header saved
by the response header handler during execution of the OpenAccess procedure.

1117
OpenEdge Development: Web Services

Response header handler for returning a header for reuse

This is the SOAP response header handler (RespHandler) that returns the header that is reused
for passing around the AccessID value:

Response header handler saving a SOAP response header for reuse

PROCEDURE RespHandler: /*1*/

DEFINE INPUT PARAMETER hHeader AS HANDLE.
DEFINE INPUT PARAMETER cNamespace AS CHARACTER.
DEFINE INPUT PARAMETER cLocalNS AS CHARACTER.

/* If the g_header global variable

is valid coming in, it has already been set
in a previous response, therefore, delete
the unnecessary response header object.
Otherwise, set g-header to the response
header object to pass back to the request
header handler on subsequent requests. */
IF NOT VALID-HANDLE(g_header) THEN /*2a*/ /* first response */
g_header = hHeader.
ELSE DO: /*2b*/ /* all subsequent responses */
DELETE OBJECT hHeader.
END.
END PROCEDURE.

This code:

1. Receives the SOAP response header using the hHeader parameter.

2. Tests if the global header handle (g_header) already references a valid object:

a. If it does not reference an object, the handler must be running as part of the initial
call to OpenAccess and thus saves the input SOAP header object (hHeader) to the
global context (g_header) for use by subsequent requests. From this moment
forward, all requests to the Web service discard the header object input to the
response handler as unnecessary.

b. If it does reference an object, the handle must already reference a SOAP response
header returned in a prior request (the call to OpenAccess) and has no need of a
subsequent response header. It therefore deletes the unnecessary SOAP header
object returned to the handler through the hHeader parameter in order to prevent a
memory leak accumulating in subsequent requests.

1118
 Handling SOAP Message Headers in the Progress 4GL

Request header handler for reusing a header

This is the SOAP request header handler (ReqHandler) that reuses the initial SOAP response
header to pass the AccessID value between the client and Web service:

Request header handler reusing a saved SOAP response header

PROCEDURE ReqHandler: /*1*/

DEFINE OUTPUT PARAMETER hHeader AS HANDLE.
DEFINE INPUT PARAMETER cNamespace AS CHARACTER.
DEFINE INPUT PARAMETER cLocalNS AS CHARACTER.
DEFINE OUTPUT PARAMETER lDeleteOnDone AS LOGICAL.

/* The IF test determines if this is the first request.

If it is, then g_header is not set and hHeader is set
to ? to ensure that no header is sent.
g_header gets set when the response header is
returned, so a subsequent pass through this code takes
the previous response header and sends it as the
current request header. */
IF NOT VALID-HANDLE (g_header) THEN DO: /*2a*/ /* first request */
hHeader = ?.
lDeleteOnDone = TRUE.
END.
ELSE DO: /*2b*/ /* all subsequent requests */
hHeader = g_header.
lDeleteOnDone = FALSE.
END.
END PROCEDURE.

This code:

1. Sends the SOAP request header for the HelloWorld request (and any request run after
running OpenAccess).

2. Tests if the global header handle (g_header) references a valid object:

a. If it does not reference an object, the request handler must be running as part of the
initial call to OpenAccess and sets the output parameters to ensure that no initial
SOAP request header is sent.

b. If it does reference an object, the handler passes the global header object as output
using the request header parameter (hHeader) and ensures that the object is not
deleted (saving it for use in any further request).

1119
OpenEdge Development: Web Services

Modifying a reused SOAP response header

This example shows how you might handle a SOAP header that you first encounter in the
response message returned from the Web service, then modify it as the SOAP header for the
next request. The response header and its handler are identical to what is used in the header reuse
example (see the Reusing an unchanged SOAP response header section on page 1115). This
is an example of the header returned from the Web service after a password is added:

SOAP request header built from a modified SOAP response header

<SOAP-ENV:Envelope
. . .
<SOAP-ENV:Header>
<ns0:AuthHeader xmlns:ns0="http://ServiceHost/SOAPHeader">
<ns0:AccessID>XYZZY</ns0:AccessID>
<ns0:Password>Administrator</ns0:Password>
</ns0:AuthHeader>
</SOAP-ENV:Header>
. . .
</SOAP-ENV:Envelope>

Note that the client adds the <Password> element as a sibling to the <AccessID> element in the
existing AuthHeader header entry. Another approach is to create and add a new Password
header entry as a sibling to the AuthHeader header entry itself. Again, the actual approach
depends on the Web service itself, in this case the HeaderExample Web service. This type of
header modification might be used when the Web service and client maintain a consistent
context for each other between requests and the operation involved requires authorization or
authentication or some other additional context information.

Following is the mainline of a procedure that invokes the Web service to reuse the initial SOAP
response header by adding a password node to it before passing it back as a SOAP request
header. This code:

1. Defines several mainline variables, including handles to access the global reused SOAP
header (g_header) and its XML, and a variable to hold the password value (cPassword).

2. Registers the request header (ReqHandler) and response header (RespHandler) handlers
after connecting to the Web service and instantiating the HeaderSoap port type procedure
object.

3. Runs the OpenAccess procedure to invoke the Web service operation that returns the
AccessID value in the SOAP response header (see the Response header handler for
returning a header for reuse section on page 1118).

1120
 Handling SOAP Message Headers in the Progress 4GL

Invoking a request that modifies a reused SOAP response header (start)

/*
* SOAPHeader2.p
*
* An addition to SOAPHeader1.p.
*
* Calls a ficticious Web service.
* The first operation (OpenAccess) sends nothing in the request headers and
* gets back a SOAP response header containing an AccessID.
* The second operation (HelloWorld) sends the AccessID back in its request
* header. (No additional information is received in the response header.)
* The third operation (HelloSecureWorld) adds a Password node to the
* existing AccessID entry in its request header. This Password node is added
* as a sibling of the AccessID element and NOT as a new SOAP header entry.
* (Once again no additional information is received in the response header.)
*
* The Web service has only one service and port available.
*/
/*1*/
/* Define local variables */
DEFINE VARIABLE hWebSrvc AS HANDLE.
DEFINE VARIABLE hPortType AS HANDLE.
DEFINE VARIABLE cResponse AS CHARACTER FORMAT "x(72)".
DEFINE VARIABLE hXdoc AS HANDLE.
DEFINE VARIABLE hXnoderef1 AS HANDLE.
DEFINE VARIABLE hXnoderef2 AS HANDLE.
DEFINE VARIABLE hXtext AS HANDLE.
DEFINE VARIABLE cPassword AS CHARACTER INIT ?.
DEFINE VARIABLE g_header AS HANDLE.

/* Create the Web service server object */

CREATE SERVER hWebSrvc.

/* Connect to the WS */
hWebSrvc:CONNECT("-WSDL
http://ServiceHost/SOAPHeader/HeaderExample.asmx?wsdl").

/* Get the method, set the port type */

RUN HeadersSoap SET hPortType ON hWebSrvc.
/*2*/
/* Associate the req. & resp. callbacks with the port type */
hPortType:SET-CALLBACK-PROCEDURE("REQUEST-HEADER", "ReqHandler").
hPortType:SET-CALLBACK-PROCEDURE("RESPONSE-HEADER", "RespHandler").
/*3*/
/* Invoke the Web service with no header and display the results */
RUN OpenAccess IN hPortType (OUTPUT cResponse).
DISPLAY cResponse LABEL "WS response" WITH FRAME aaa.

1121
OpenEdge Development: Web Services

Invoking a request that modifies a reused SOAP response header (end)

/*4*/
/* Go again with the AccessID set from previous response */
cResponse = "".
RUN HelloWorld IN hPortType (OUTPUT cResponse).
DISPLAY cResponse LABEL "WS response" WITH FRAME bbb.
/*5*/
/* Go again with the AccessID set from previous response */
/* header together with an added Username and Password */
cResponse = "".
cPassword = "Administrator".
RUN HelloSecureWorld IN hPortType (OUTPUT cResponse).
DISPLAY cResponse LABEL "WS response" WITH FRAME ccc.
/*6*/
DELETE OBJECT g_header.
DELETE OBJECT hPortType.
hWebSrvc:DISCONNECT().
DELETE OBJECT hWebSrvc.

/**************** Internal Procedures ****************/

4. Runs the HelloWorld procedure to invoke the next Web service operation, passing back
the SOAP response header to the Web service unchanged as the SOAP request header (see
the Request header handler for reusing and modifying a header section on page 1123).

5. Runs the HelloSecureWorld procedure to invoke the next Web service operation, passing
back the password-modified SOAP response header as the Web service SOAP request
header (see the Request header handler for reusing and modifying a header section on
page 1123).

Note: The header handler processing for Step 4 is different from Step 5, to reflect that the
initial SOAP response header is unchanged for one request and modified for the
next.

6. Cleans up the global objects maintained in its context and disconnects from the Web
service. Note that one of the objects it deletes is the original SOAP response header saved
by the response header handler during execution of the OpenAccess procedure.

1122
 Handling SOAP Message Headers in the Progress 4GL

Request header handler for reusing and modifying a header

This is the SOAP request header handler (ReqHandler) that reuses the initial SOAP response
header and adds a Password value to the existing AuthHead header entry to pass along with the
AccessID value between the client and Web service:

Request header handler modifying a saved SOAP response header (start)

PROCEDURE ReqHandler: /*1*/

DEFINE OUTPUT PARAMETER hHeader AS HANDLE.
DEFINE INPUT PARAMETER cNamespace AS CHARACTER.
DEFINE INPUT PARAMETER cLocalNS AS CHARACTER.
DEFINE OUTPUT PARAMETER lDeleteOnDone AS LOGICAL.

/* The IF test determines if this is the first call

through this code.
If it is, then g_header is not set and hHeader is set
to ? to ensure that no header is sent.
g_header gets set when the response header is
returned, so a subsequent pass through this code takes
the previous response header and sends it as the
current request header, possibly modified to
authenticate a secure request. */
IF NOT VALID-HANDLE (g_header) THEN DO: /*2a*/ /* first request */
hHeader = ?.
lDeleteOnDone = TRUE.
END.
ELSE DO: /*2b*/ /* all subsequent requests */
hHeader = g_header.
lDeleteOnDone = FALSE.

This code:

1. Sends the SOAP request header for the HelloWorld and HelloSecureWorld requests (and
any request run after running OpenAccess).

2. Tests if the global header handle (g_header) references a valid object:

a. If it does not reference an object, the request handler must be running as part of the
initial call to OpenAccess and sets the output parameters to ensure that no initial
SOAP request header is sent.

b. If it does reference an object, the handler passes the global header object as output
using the request header parameter (hHeader) and ensures that the object is not
deleted (saving it for use in any further request).

1123
OpenEdge Development: Web Services

Request header handler modifying a saved SOAP response header (end)

/* Password node data are added to the existing SOAP header

if a secure operation is being executed */
/*3*/ IF cPassword <> ? THEN DO:
/*3a*/ /* Build a new x-doc to contain the Password data */
CREATE X-DOCUMENT hXdoc.
CREATE X-NODEREF hXnoderef1.
CREATE X-NODEREF hXnoderef2.
CREATE X-NODEREF hXtext.

/* Add the Password data as a child of the existing header entry */

/*3b*/ DEFINE VARIABLE hHeaderEntryref AS HANDLE.
DEFINE VARIABLE ClientNS AS CHARACTER
INIT "http://ServiceHost/SOAPHeader".
CREATE SOAP-HEADER-ENTRYREF hHeaderEntryref.

/*3c*/ hHeader:GET-HEADER-ENTRY(hHeaderEntryref, 1).

hHeaderEntryref:GET-NODE(hXnoderef1).

/*3d*/ hXdoc:IMPORT-NODE(hXnoderef2, hXnoderef1, TRUE).

IF hXnoderef2:NUM-CHILDREN > 1 THEN DO: /* Get rid of previous */
hXnoderef2:GET-CHILD(hXnoderef1,2). /* Password data */
hXnoderef1:DELETE-NODE().
END.

/*3e*/ hXdoc:APPEND-CHILD(hXnoderef2).
hXdoc:CREATE-NODE-NAMESPACE(hXnoderef1, ClientNS,
"Password", "ELEMENT").

/*3f*/ hXnoderef2:APPEND-CHILD(hXnoderef1).
hXdoc:CREATE-NODE(hXtext, "", "text").
hXnoderef1:APPEND-CHILD(hXtext).
hXtext:NODE-VALUE = cPassword.

/* Replace the existing header entry using a deep copy of the */

/* new version from the x-doc that has the Password node added */
/*3g*/ hHeaderEntryref:SET-NODE(hXnoderef2).

/* Procedure/header cleanup */
/*3h*/ cPassword = ?. /* Use current password until replaced */
DELETE OBJECT hHeaderEntryref.
DELETE OBJECT hXdoc.
DELETE OBJECT hXnoderef1.
DELETE OBJECT hXnoderef2.
DELETE OBJECT hXtext.
END.
END. /* all subsequent requests */
END PROCEDURE.

1124
 Handling SOAP Message Headers in the Progress 4GL

3. Tests if a password has been specified for the current Web service request, indicated by
any cPassword value that is other than the unknown value (?). If the current Web service
request is nonsecure (as with the HelloWorld operation), all work has been done and the
the request handler can end. If the current Web service request is secure (as with the
HelloSecureWorld operation), the request handler adds the password information to the
SOAP request header, as follows:

Note: After the first secure request, all future requests (secure or nonsecure) send a
request header that includes password information because the password
information is never deleted until replaced by a newly-specified password.

a. Creates the XML x-document and x-noderef objects to manipulate the SOAP header.

b. Creates the SOAP header entryref object (hHeaderEntryref) to access SOAP header
entries and defines the namespace (ClientNS) used for defining the SOAP header
entry for this request.

c. Returns the existing header entry from the saved global SOAP header object using
the GET-HEADER-ENTRY( ) method on the SOAP header object and accesses the
XML root node of the entry using the GET-NODE( ) method on the SOAP header
entryref object.

Note: The handler is adding the password information to an existing SOAP header
entry. If it was adding a new header entry to hold the information, it would
invoke the ADD-HEADER-ENTRY( ) method to add the header entry to contain
the new XML for it.

d. Imports the header entry root node into an x-document object in order to access and
modify the XML for the header entry, and also deletes any password data from a
previous secure request before adding the currently-specified password data.

e. Adds the <Password> element as a sibling of the <AccessID> element.

f. Adds the <Password> element value.

g. Replaces the entire existing header entry in the global SOAP header object with the
header entry updated in the x-document object.

h. Sets the password value (cPassword) to unknown (?), which retains the current
password in the header entry until it is explicitly changed in cPassword. Deletes all
of the helper XML and SOAP header entryref objects created in the header handler.

1125
OpenEdge Development: Web Services

Using a client-created SOAP request header

This example shows how you might create a SOAP header internally to use as an initial SOAP
request header, as opposed to recycling a header previously received in a SOAP response
message (described in previous examples). This is an example of the header created by the client
for the Web service:

SOAP request header created entirely by the client

<SOAP-ENV:Envelope
. . .
<SOAP-ENV:Header>
<ns0:AuthHeader xmlns:ns0="http://ServiceHost/SOAPHeader">
<ns0:UserName>Scott</ns0:UserName>
<ns0:Password>Administrator</ns0:Password>
</ns0:AuthHeader>
</SOAP-ENV:Header>
. . .
</SOAP-ENV:Envelope>

The client creates a header very similar to the headers described in the previous examples. The
<UserName> and <Password> elements, in this case, provide user authentication for each Web
service request. The Web service requires this authentication for every Web service request.

Following is the mainline of a procedure that invokes the Web service to create the initial SOAP
request header containing a username and password node. This code:

1. Defines several mainline variables, including handles to access the global SOAP header
(g_header) created for requests and its XML, and variables to hold the username
(cUsername) and password (cPassword) values.

2. Builds the global request header used for all requests (see the Procedure to create a SOAP
request header section on page 1128).

3. Registers the request header (ReqHandler) handler after connecting to the Web service and
instantiating the HeaderSoap port type procedure object.

4. Runs the HelloMyWorld procedure to invoke a Web service operation, passing back the
global SOAP request header created by the client (see the Request header handler for
passing a globally-created header object section on page 1130).

5. Cleans up the global objects maintained in its context and disconnects from the Web
service. Note that one of the objects it deletes is the global SOAP request header create by
the client.

1126
 Handling SOAP Message Headers in the Progress 4GL

Invoking a request that creates a SOAP request header on the client

/*
* SOAPHeader3.p
*
* Calls a ficticious web service, passes it a username and password through
* a SOAP message request header, and gets back a string.
*
* The Web service has only one service and port available.
*/

/* Define local variables */ /*1*/

DEFINE VARIABLE hWebSrvc AS HANDLE.
DEFINE VARIABLE hPortType AS HANDLE.
DEFINE VARIABLE cUsername AS CHARACTER INIT "Scott".
DEFINE VARIABLE cPassword AS CHARACTER INIT "Administrator" .
DEFINE VARIABLE cResponse AS CHARACTER FORMAT "x(72)".
DEFINE VARIABLE hXdoc AS HANDLE.
DEFINE VARIABLE hXnoderef1 AS HANDLE.
DEFINE VARIABLE hXnoderef2 AS HANDLE.
DEFINE VARIABLE hXAttribute AS HANDLE.
DEFINE VARIABLE hXtext AS HANDLE.
DEFINE VARIABLE g_header AS HANDLE.
/*2*/
/* Build global SOAP request header */
RUN BuildRequestHeader (OUTPUT g_header).

/* Create the Web service server object */

CREATE SERVER hWebSrvc.

/* Connect to the WS */
hWebSrvc:CONNECT("-WSDL
http://ServiceHost/SOAPHeader/HeaderExample.asmx?wsdl").

/* Get the method, set the port type */

RUN HeaderSoap SET hPortType ON hWebSrvc.
/*3*/
/* Associate the request callback with the port type */
hPortType:SET-CALLBACK-PROCEDURE("REQUEST-HEADER", "ReqHandler").
/*4*/
/* Invoke the web service and display the results */
RUN HellowMyWorld IN hPortType (OUTPUT cResponse).
DISPLAY cResponse LABEL "WS Response" WITH FRAME aaa.
/*5*/
DELETE OBJECT g_header.
DELETE OBJECT hPortType.
hWebSrvc:DISCONNECT().
DELETE OBJECT hWebSrvc.

/**************** Internal Procedures ****************/

1127
OpenEdge Development: Web Services

Procedure to create a SOAP request header

This is the procedure (BuildRequestHeader) that creates the global SOAP request header that
the client sends in all requests to the Web service:

Procedure to create a SOAP request header (start)

PROCEDURE BuildRequestHeader: /*1*/

/* Define procedure parameter */
DEFINE OUTPUT PARAMETER hHeader AS HANDLE.
/*2*/
DEFINE VARIABLE hHeaderEntryref AS HANDLE.
DEFINE VARIABLE ClientNS AS CHARACTER
INIT "http://ServiceHost/SOAPHeader".
/*3*/
/* Create SOAP header and server objects */
CREATE SOAP-HEADER hHeader.
CREATE SOAP-HEADER-ENTRYREF hHeaderEntryref.
/*4*/
/* Create x-doc objects to build header */
CREATE X-DOCUMENT hXdoc.
CREATE X-NODEREF hXAttribute.
CREATE X-NODEREF hXnoderef1.
CREATE X-NODEREF hXnoderef2.
CREATE X-NODEREF hXtext.

This code:

1. Defines a single output parameter to return the global SOAP header object that it creates
to the client mainline context.

2. Defines a handle variable (hHeaderEntryref) to reference the SOAP header entryref

object, and a variable (ClientNS) that specifies the namespace for the SOAP header entry
that it creates.

3. Creates the global SOAP header object that references the XML for the header using the
CREATE SOAP-HEADER statement, and creates the SOAP header entryref object that
references the XML for the header entry using the CREATE SOAP-HEADER-ENTRYREF
statement.

4. Creates the x-document and x-noderef objects required to build the XML to be added as
the header entry for the global SOAP header.

5. Adds a header entry to the newly-created SOAP header object, referenced by the
hHeaderEntryref object, using the ADD-HEADER-ENTRY( ) method.

1128
 Handling SOAP Message Headers in the Progress 4GL

6. Creates the root node (<AuthHeader> element) for the header entry in the working
x-document object.

Note: The namespace attribute specifying http://www.w3.org/2000/xmlns/ is a

requirement of the DOM. For more information, see the information on XML
support in OpenEdge Development: Programming Interfaces.

7. Creates the <UserName> element as a child node of the header entry.

8. Creates the <Password> element as a second child node of the header entry.

9. Assigns the header entry in the global SOAP header object to the XML for the
<AuthHeader> element of the x-document object using the SET-NODE( ) method.

Procedure to create a SOAP request header (continuation)

/*5*/
/* Create the header entry */
hHeader:ADD-HEADER-ENTRY(hHeaderEntryref).
/*6*/
/* Create the header namespace data */
hXdoc:CREATE-NODE-NAMESPACE(hXnoderef1, ClientNS,
"AuthHeader", "ELEMENT").
hXdoc:CREATE-NODE-NAMESPACE(hXAttribute,
"http://www.w3.org/2000/xmlns/",
"xmlns", "ATTRIBUTE").
hXAttribute:NODE-VALUE = ClientNS.
hXnoderef1:SET-ATTRIBUTE-NODE(hXAttribute).
hXdoc:INSERT-BEFORE(hXnoderef1, ?).
/*7*/
/* Create the Username/Password data */
hXdoc:CREATE-NODE-NAMESPACE(hXnoderef2, ClientNS,
"UserName", "ELEMENT").
hXnoderef1:APPEND-CHILD(hXnoderef2).
hXdoc:CREATE-NODE(hXtext,"","text").
hXnoderef2:APPEND-CHILD(hXtext).
hXtext:NODE-VALUE = cUsername.
/*8*/
hXdoc:CREATE-NODE-NAMESPACE(hXnoderef2, ClientNS,
"Password", "ELEMENT").
hXnoderef1:APPEND-CHILD(hXnoderef2).
hXdoc:CREATE-NODE(hXtext, "", "text").
hXnoderef2:APPEND-CHILD(hXtext).
hXtext:NODE-VALUE = cPassword.
/*9*/
/* Fill the header entry using a deep copy */
hHeaderEntryref:SET-NODE(hXnoderef1).

1129
OpenEdge Development: Web Services

Procedure to create a SOAP request header (end)

/*9*/
/* Fill the header entry using a deep copy */
hHeaderEntryref:SET-NODE(hXnoderef1).
/*10*/
/* Procedure/header cleanup */
DELETE OBJECT hXdoc.
DELETE OBJECT hXAttribute.
DELETE OBJECT hXnoderef1.
DELETE OBJECT hXnoderef2.
DELETE OBJECT hXtext.
DELETE OBJECT hHeaderEntryref.
END PROCEDURE.

10. Cleans up by deleting all the helper objects created in the procedure before returning to the
client mainline.

Request header handler for passing a globally-created header object

This is the SOAP request header handler (ReqHandler) that passes the global SOAP request
header created by the client and the Web service for each request:

Request header handler passing a client-created SOAP request header

PROCEDURE ReqHandler: /*1*/

/* Define procedure parameters */
DEFINE OUTPUT PARAMETER hHeader AS HANDLE.
DEFINE INPUT PARAMETER cNamespace AS CHARACTER.
DEFINE INPUT PARAMETER cLocalNS AS CHARACTER.
DEFINE OUTPUT PARAMETER lDeleteOnDone AS LOGICAL.
/*2*/
/* Pass in global header reused for every request */
hHeader = g_header.
lDeleteOnDone = FALSE.
END PROCEDURE.

This code:

1. Sends the SOAP request header for the HelloMyWorld request (and any subsequent
request).

2. Passes the global SOAP header the request header output parameter and ensures that it is
not deleted until the client mainline has finished with it.

1130
 Handling SOAP Message Headers in the Progress 4GL

Managing memory for SOAP headers

SOAP headers require two types of memory in the 4GL (see the SOAP header object model
section on page 115):

Memory used for the SOAP header and SOAP header entry data that SOAP header and
SOAP header-entryref objects reference, that is, the underlying XML.

Memory used by the SOAP header object, including the memory for SOAP header entries
referenced by SOAP header-entryref objects, even if this header object memory does not
reference any underlying XML.

SOAP header object model and DOM relationships

The manner in which a SOAP header object encapsulates the XML for a SOAP header is similar
to how the 4GL Document Object Model (DOM) allows an x-document object to encapsulate
the XML of a general XML document. The manner in which a SOAP header-entryref object
references a SOAP header entry is similar to how the 4GL DOM allows an x-noderef object to
reference the individual elements and attributes of a general XML document. Similar
dependencies exist for managing the memory for objects in each reference model.

SOAP header objects can be created in the 4GL application in two ways:

Implicitly by OpenEdge for the header of an incoming SOAP response message.

Explicitly by the application using a variation of the CREATE statement.

No matter how the application creates these objects, the application is responsible for explicitly
deleting these and any other objects that it creates during a session, including the SOAP
header-entryref objects used to reference the header entries in a SOAP header object and any
X-document and X-noderef objects used to parse and build the XML structures that occupy
memory for the underlying XML.

1131
OpenEdge Development: Web Services

Memory for the SOAP header object model and DOM

Table 111 summarizes the available 4GL elements and how they can help you to manage
memory for SOAP headers.

Table 111: 4GL to manage object memory for SOAP headers

Deletes all
Deletes the underlying XML
4GL element Applied to object 4GL object DOM objects

Setting the SOAP header object Yes Yes

lDeleteOnDone OUTPUT
parameter of the request
header handler to TRUE
(see the Defining
header handlers
section on page 1110

DELETE OBJECT statement SOAP header object Yes Yes

X-document object Yes Yes

SOAP header-entryref Yes No

object

X-noderef object Yes No

DELETE-HEADER-ENTRY( ) SOAP header-entryref No Yes1

method object

DELETE-NODE( ) method X-noderef object No Yes1

1
This includes any child sub-trees of the deleted X-noderef object.

Caution: Be sure that you always delete the underlying XML for a SOAP header-entryref
object before you delete the SOAP header-entryref object itself. If you lose all
reference to the underlying XML before deleting it, its memory becomes lost to your
application. If this occurs as part of an iterative process, it represents a memory leak
that could cause your application to crash.

1132
 Handling SOAP Message Headers in the Progress 4GL

Attributes and methods for handling SOAP headers

As described in previous sections, the two Progress 4GL objects provided for managing SOAP
headers include the:

SOAP header object For accessing the name and header entries of a SOAP header.

SOAP header-entryref object For accessing each header entry in a SOAP header.

Each of these objects provide attributes and methods that manage header access according to a
SOAP header object model defined for the Progress 4GL. This object model maps to the SOAP
header XML in a manner analogous to the way x-document and x-noderef objects allow you to
access XML through the Document Object Model (DOM) supported in the Progress 4GL. In
fact, the attributes and methods that implement the SOAP header object model provide access
to the XML of a header by making it available to the standard XML support in the 4GL, such
as the DOM, and by allowing the XML to be exchanged between the two SOAP header
representations (SOAP object model and XML).

For more information on the SOAP header object model, see the SOAP header object model
section on page 115. The following sections describe all of the attributes and methods available
for each object in the SOAP header object model.

SOAP header object attributes and methods

Table 112 briefly describes all of the attributes on the SOAP header object that are unique to
the object or have special application to the SOAP header object.

Table 112: SOAP header object attributes

Attribute Type Description

NAME CHARACTER Returns the qualified name of the SOAP header

("namespacePrefix:HEADER").

NUM-HEADER-ENTRIES INTEGER Returns the number of entries attached to the

SOAP header.

TYPE CHARACTER Returns the handle type, "SOAP-HEADER".

1133
OpenEdge Development: Web Services

Table 113 briefly describes all of the methods on the SOAP header object.

Table 113: SOAP header object methods

Method Type Description

ADD-HEADER-ENTRY LOGICAL Creates a new SOAP header entry and attaches it

(hHeaderEntryRef) to the SOAP header. A specified SOAP
header-entryref object handle
(hHeaderEntryRef) references the new header
entry.

GET-HEADER-ENTRY LOGICAL Associates a specified SOAP header-entryref

(hHeaderEntryRef, object handle (hHeaderEntryRef) with an
index) index-specified entry (index) in the associated
SOAP header.

For more information on these attributes and methods, see OpenEdge Development: Progress
4GL Reference.

SOAP header-entryref object attributes and methods

Table 114 briefly describes all of the attributes on the SOAP header-entryref object that are
unique to the object or have special application to the SOAP header-entryref object.

Table 114: SOAP header-entryref object attributes (1 of 2)

Attribute Type Description

ACTOR CHARACTER Returns the value of the actor attribute specified

in the associated SOAP header entry.

LOCAL-NAME CHARACTER Returns the unqualified part of name specified for

the associated SOAP header entry element.

MUST-UNDERSTAND LOGICAL Returns the value of the mustUnderstand

attribute specified in the associated SOAP header
entry.

NAME CHARACTER Returns the qualified name of the SOAP header

entry ("namespacePrefix:localName").

1134
 Handling SOAP Message Headers in the Progress 4GL

Table 114: SOAP header-entryref object attributes (2 of 2)

Attribute Type Description

NAMESPACE-URI CHARACTER Returns the namespace URI prefixed to the

associated SOAP header entry elements name.

TYPE CHARACTER Returns the handle type,

"SOAP-HEADER-ENTRYREF".

Table 115 briefly describes all of the methods on the SOAP header-entryref object.

Table 115: SOAP header-entryref object methods (1 of 2)

Method Type Description

DELETE-HEADER-ENTRY LOGICAL Deletes the underlying SOAP header entry and

( ) all of its content, but does not delete the SOAP
header-entryref object used to reference the
deleted header entry.

GET-NODE (handle) LOGICAL Returns a handle (handle) to an X-noderef

object that references the root node of a DOM
tree containing the parsed XML for the
underlying SOAP header entry.

GET-SERIALIZED ( ) LONGCHAR Returns the XML for the underlying SOAP

header entry in serialized form.

SET-ACTOR (string) LOGICAL Sets the value (string) of the actor attribute in
the underlying SOAP header entry. This method
returns TRUE only if there is an underlying SOAP
header entry (XML sub-tree) associated with the
object handle.

SET-MUST-UNDERSTAND LOGICAL Sets the value (logical) of the mustUnderstand

(logical) attribute in the underlying SOAP header entry.
This method returns TRUE only if there is an
underlying SOAP header entry (XML sub-tree)
associated with the object handle.

1135
OpenEdge Development: Web Services

Table 115: SOAP header-entryref object methods (2 of 2)

Method Type Description

SET-NODE (hXnoderef) LOGICAL Replaces the header entry referenced by this

SOAP header-entryref object with a specified
DOM sub-tree (parsed XML) that is assumed to
represent a SOAP header entry element. The
method performs a deep copy of the XML
sub-tree specified by the X-noderef object
handle (hXnoderef).

SET-SERIALIZED LOGICAL Replaces the header entry referenced by this

(longchar) SOAP header-entryref object with serialized
XML (longchar) that is then parsed into a DOM
sub-tree that represents a SOAP header entry
element. The XML is assumed to be valid for a
SOAP header entry.

For more information on these attributes and methods, see OpenEdge Development: Progress
4GL Reference.

1136
 12
Handling Errors in Progress 4GL
Requests to Web Services

As described previously, the ERROR condition can result from a Web service request by:

1. A SOAP fault returned by the Web service.

2. A 4GL internal error raised by OpenEdge.

3. An error intentionally raised by the 4GL application (using the RETURN ERROR statement)
in a SOAP request header callback procedure or a SOAP response header callback
procedure.

For a thorough overview of handling all types of errors, see Chapter 1, Web Services in
OpenEdge.

This chapter focuses on how to handle SOAP faults and generally how to debug Web service
requests, including the following sections:

Handling SOAP faults

Detecting a SOAP fault

Managing a SOAP fault

Example 4GL accessing a SOAP fault

Debugging 4GL applications that call Web services

OpenEdge Development: Web Services

Handling SOAP faults

When a Web service operation fails after the request arrives at the Web service, it might
generate a SOAP fault. This is a special SOAP response message that contains a single fault
element in the body, namespace qualified and usually identified by a <SOAP:Fault> or
<SOAP-ENV:Fault> tag. This is a typical SOAP fault message, with the most common SOAP
fault elements.

Sample SOAP fault message

<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>VersionMismatch.Additionalinfo</faultcode>
<faultstring>The message does not conform to
expected version</faultstring>
<faultactor>http://www.stockvendor.com</faultactor>
<detail>
<e:badver xmlns:e=http://www.stockvendor.com/>
<message>Expect version 2 request,
received previous version</message>
<errorcode>523</errorcode>
</e:badver>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>

These three child elements of this SOAP fault are mostly application-defined, but typically
provide the following information:

<faultcode> Coded fault identifier, such as an error number or specially-formatted

string to identify the fault.

<faultstring> Single string value containing a simple description of the fault.

<faultactor> (Optional) Single string value identifying the Universal Resource

Identier (URI) of the Web service that caused the fault. This is less common, as it is usually
apparent what Web service has generated the SOAP fault.

<detail> (Optional) Contains elements completely defined by the Web service, but
which provide much more specific information about the fault.

122
 Handling Errors in Progress 4GL Requests to Web Services

Detecting a SOAP fault

When the Web service returns a SOAP fault, OpenEdge responds depending on how the request
is coded. As with 4GL errors, if you do not specify the NO-ERROR option on a RUN statement that
invokes a Web service operation or if the operation is invoked using a user-defined function,
OpenEdge converts the SOAP fault into a standard Progress error message displayed as follows:

The error box displays the operation that generated the SOAP fault and the contents of the
<faultstring> element in the SOAP fault message.

If the statement that invokes a Web service operation traps an error using the NO-ERROR option,
this message and the information for any SOAP fault detail appears in the ERROR-STATUS system
handle, and as with all 4GL errors remains available until the next statement is invoked using
the NO-ERROR option. Table 121 lists the ERROR-STATUS handle attribute that help you to detect
and return the information for a SOAP fault. All other attributes and methods on this handle
work as they do for any 4GL error condition.

Table 121: ERROR-STATUS handle attributes

Attribute Type Description

ERROR LOGICAL Indicates that an ERROR

condition was returned as a
result of processing a Web
service request.

ERROR-OBJECT-DETAIL HANDLE References the SOAP fault

object for any Web service
request that returns a SOAP
fault trapped using the 4GL
NO-ERROR option.

Once you have detected an error (ERROR-STATUS:ERROR=TRUE), you can determine if it is the
result of a SOAP fault using the ERROR-OBJECT-DETAIL attribute. If a SOAP fault caused the
error, this attribute returns a handle to a SOAP fault object containing the SOAP fault
information. Otherwise, it has the unknown value (?).

123
OpenEdge Development: Web Services

Managing a SOAP fault

On detecting a SOAP fault, OpenEdge automatically creates a SOAP fault object for it. This
object contains information from each child element of the response message <Fault> element.
Like the ERROR-STATUS handle information, OpenEdge makes this object available only until
the next statement executes with the NO-ERROR option.

Table 122 lists the attributes on the SOAP fault object, which contains no methods.

Table 122: SOAP fault object attributes

Attribute Type Description

SOAP-FAULT-CODE CHARACTER Returns the value of the <faultcode> element of

the SOAP fault message, which identifies the
fault.

SOAP-FAULT-STRING CHARACTER Returns the value of the <faultstring> element

of the SOAP fault message, which provides a
human-readable description of the fault.

SOAP-FAULT-ACTOR CHARACTER Returns the value of the <faultactor> element

of the SOAP fault message, which is a URI that
identifies the Web service returning the fault.

SOAP-FAULT-DETAIL HANDLE References the SOAP fault-detail object, which

contains more application-specific error
information.

TYPE CHARACTER Returns the handle type, "SOAP-FAULT".

As you can see, these attributes provide access to all the elements of a SOAP fault you might
encounter.

Because the <detail> element has essentially no standard definition, and can contain any
elements that the Web service chooses to generate, OpenEdge provides another object, the
SOAP fault-detail object to return this information to the 4GL application. If the SOAP fault
message contains a <detail> element, the SOAP-FAULT-DETAIL attribute on the SOAP fault
object handle returns a handle to the SOAP fault-detail object that is generated for it. Otherwise,
this attribute returns the unknown value (?). Like the SOAP fault object, OpenEdge makes the
SOAP fault-detail object available only until the next 4GL statement that executes with the
NO-ERROR option.

124
 Handling Errors in Progress 4GL Requests to Web Services

Table 123 lists the single attribute and Table 124 lists the methods of the SOAP fault-detail
object.

Table 123: SOAP fault-detail object attributes

Attribute Type Description

TYPE CHARACTER Returns the handle type, "SOAP-FAULT-DETAIL".

Table 124: SOAP fault-detail object methods

Method Type Description

GET-NODE( ) LOGICAL Returns a handle to an X-noderef object that

references the root node (SOAP <detail>
element) of a DOM tree containing the parsed
XML for the underlying SOAP detail
information.

GET-SERIALIZED( ) LONGCHAR Returns the XML for the underlying SOAP fault
detail information in serialized form.

The GET-NODE( ) and GET-SERIALIZED( ) methods provide access to the elements of the SOAP
fault detail information in exactly the same way as they provide access to SOAP header entries
for a SOAP header (Chapter 11, Handling SOAP Message Headers in the Progress 4GL).

The general approach to managing SOAP fault detail elements is identical to retrieving and
scanning the header entries of a SOAP response header. The structure of elements that make up
the SOAP fault detail information is completely undefined. For more information, see the
documentation available for the Web service you are accessing.

125
OpenEdge Development: Web Services

Example 4GL accessing a SOAP fault

The following procedure fragment runs an operation on a fictitious Web service that returns a
SOAP fault identical to the one described in the beginning of this section (see theHandling
SOAP faults section on page 122). It accesses and begins to examine the SOAP fault message
as described in the following steps that match the numbered comments (/*1*/ to /*7*/) in the
code.

This code:

1. Uses the 4GL VALID-HANDLE function to determine if a given ERROR condition

(ERROR-STATUS:ERROR = TRUE) is caused by a SOAP fault by testing the validity of the
handle returned by the ERROR-STATUS:ERROR-OBJECT-DETAIL attribute.

2. Assigns a handle variable (hSoapFault) to any valid SOAP fault object returned by the
ERROR-STATUS:ERROR-OBJECT-DETAIL attribute for code readability.

Note: You can also use the ERROR-STATUS:ERROR-OBJECT-DETAIL handle attribute

directly to work with the SOAP fault object.

3. Examines the values of SOAP fault elements, as required, using appropriate attributes
(SOAP-FAULT-CODE) on the SOAP fault object handle.

4. Uses the 4GL VALID-HANDLE function to determine if this SOAP fault has SOAP fault
detail by testing the validity of the handle returned by hSoapFault:SOAP-FAULT-DETAIL.

5. Assigns a handle variable (hSoapFaultDetail) to the SOAP fault-detail object returned

by the hSoapFault:SOAP-FAULT-DETAIL attribute for code readability.

Note: You can also use the ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-DETAIL

handle attribute directly to work with the SOAP fault-detail object.

6. Returns the root node of the underlying SOAP fault <detail> element by using the
hSoapFaultDetail:GET-NODE( ) method to assign the root node to the x-noderef object
referenced by the handle variable hxnoderef.

7. Can now use the methods and attributes of the x-noderef object handle (hxnoderef) and
additional handle variables to walk the XML DOM subtree referenced by hxnoderef to
examine the content of the SOAP fault <detail> element as specified by the WSDL for
the Web service.

126
 Handling Errors in Progress 4GL Requests to Web Services

Sample SOAP fault procedure

DEFINE VARIABLE hWS AS HANDLE.

DEFINE VARIABLE hStockPortType AS HANDLE.
DEFINE VARIABLE price AS DECIMAL.

CREATE SERVER hWS.

/* Create a WebServicePortType object, using server & port information. */

hWS:CONNECT( "-WSDL http: //www.stockvend.com/application/wsdl/stock.wsdl

-Service stockSVC
-Port stockPort" ).
RUN stock SET hStockPortType ON SERVER hWS.

RUN getPrice IN hStockPortType( INPUT "error", OUTPUT price ) NO-ERROR.

IF ERROR-STATUS:ERROR THEN DO:
/*1*/
/* Error occurred on the RUN. Did the Web service generate
the error or was it an internal Progress 4GL error? */
IF VALID-HANDLE( ERROR-STATUS:ERROR-OBJECT-DETAIL ) THEN DO:
DEFINE VARIABLE hSoapFault as HANDLE.
/*2*/
hSoapFault = ERROR-STATUS:ERROR-OBJECT-DETAIL.
/*3*/
IF INDEX( "VersionMismatch", hSoapFault:SOAP-FAULT-CODE ) THEN DO:

/*4*/ IF VALID-HANDLE( hSoapFault:SOAP-FAULT-DETAIL ) THEN DO:

DEFINE VARIABLE hSoapFaultDetail as HANDLE.

/*5*/ hSoapFaultDetail = hSoapFault:SOAP-FAULT-DETAIL.

DEFINE VARIABLE hxnoderef AS HANDLE.

CREATE X-NODEREF hxnoderef.
/*6*/ hSoapFaultDetail:GET-NODE( hxnoderef ).

/*7*/ /* From here the application can walk the detail XML and
retrieve the relevant information. */
.
.
.
END. /* Examine SOAP-FAULT-DETAIL */
END. /* Return SOAP-FAULT-CODE info */
END. /* Examine ERROR-OBJECT-DETAIL */
END.

DELETE PROCEDURE hStockPortType.

hWS:DISCONNECT( ).

127
OpenEdge Development: Web Services

Debugging 4GL applications that call Web services

If a 4GL application error appears (from error messages, for example) to result from attempts
to access a Web service, you generally follow three phases of investigation to isolate the
problem.

To investigate a problem in using a Web service:

1. Determine if the WSDL file is still valid for the Web service you are accessing.

This is particularly necessary if you access the WSDL file at a location other than the URL
specified by the Web service provider, for example using a local file system that stores a
separate copy that you have made from the original. It is also very possible that the Web
service provider has changed the URL or target namespace to reference the WSDL file. If
this is the case, you must run the WSDL Analyzer against the new WSDL file to identify
any changes that might affect your code (see Chapter 8, Analyzing WSDL for Progress
4GL Access to Web Services).

So, this is a good first step to diagnose any Web service access failure.

2. If the WSDL file appears to be valid, use a SOAP message viewer at run time to compare
the content of SOAP request and response messages with what the application expects and
what the WSDL file specifies.

OpenEdge provides a set of SOAP viewers included with the installation, and many other
viewers are available. This chapter describes three of them to varying levels of detail.

3. Debug the 4GL code, possibly using the OpenEdge Debugger. For more information on
the Debugger, see OpenEdge Development: Debugging and Troubleshooting.

128
 Handling Errors in Progress 4GL Requests to Web Services

SOAP Viewers
Table 125 lists some tools that you can use to view Web service messages as they are
exchanged between the client and the Web service.

Table 125: Web service message viewers

This SOAP message viewer... Is...

WSAViewer Provided with the OpenEdge installation.

ProSOAPView Provided with the OpenEdge installation.

Microsoft SOAP Toolkit Available for free download from

Microsofts Web site.

The Microsoft SOAP Toolkit contains a variety of tools for working with SOAP messages on
Windows platforms. One advantage of WSAViewer and ProSOAPView is that they run on all
supported OpenEdge platforms.

Using WSAViewer
WSAViewer is a basic tool for viewing the SOAP messages between a given source and
destination, which you determine at startup. As such, it functions as a man in the middle
between the client and the Web service. It is useful if you are only interested in viewing the
content of the SOAP request and response. The simplicity of this tool makes it handy to use
when debugging 4GL Web services for which viewing the well-defined SOAP formats is the
primary focus. For more information on this tool, see Chapter 7, Testing and Debugging
Progress 4GL Web Services.

129
OpenEdge Development: Web Services

Using WSAViewer with a 4GL client

To use WSAViewer with a 4GL client, you have two options:

Change the connection parameters in your Web service CONNECT( ) method to send all
SOAP messages to WSAViewer. WSAViewer then forwards them to the actual Web
service.

Startup the 4GL client using the -proxyhost and -proxyport startup parameters to
redirect the SOAP messages to WSAViewer. Specify -proxyhost using the host name
where the viewer is running (typically localhost), and specify -proxyport using the port
on which WSAViewer listens for SOAP request messages (the listen-port value
specified for WSAViewer as shown in the following syntax).

The syntax to start the viewer is the same when working with any Web service as it is when
working with the OpenEdge Web Services Adapter (WSA):

Syntax

wsaviewer listen-port webservice-host webservice-port

The listen-port is the port on which WSAViewer listens for SOAP request messages. The
webservice-host is the host name of the Web service and the webservice-port is the host port
on which the Web service listens for SOAP request messages.

Suppose you enter the following command line to start the viewer to listen on localhost at port
8080 and pass SOAP request messages to the Web service, www.stockvend.com, listening on
port 80:

wsaviewer 8080 www.stockvend.com 80

You might code your 4GL Web service CONNECT( ) method like this:

DEFINE VARIABLE hWS AS HANDLE.

CREATE SERVER hWS.
hWS:CONNECT("-WSDL http://www.stockvend.com/application/wsdl/stock.wsdl
-Binding StockQuoteObj
-SOAPEndpoint http://localhost:8080/application/stockquotes").

The CONNECT( ) method still gets the WSDL file directly from www.stockvend.com, but all
SOAP messages go through WSAViewer on their way to the Web service and back to the client.

1210
 Handling Errors in Progress 4GL Requests to Web Services

Using ProSOAPView
ProSOAPView is a more flexible tool than WSAViewer that allows you to view the following
message content exchanged between a client and Web service:

Request for a WSDL file

SOAP request and response content.

HTTP request and response content.

The content of any other document exchanged between the client and Web service.

This flexibility is especially helpful to debug industry Web services accessed from the 4GL
(which can originate anywhere and contain a greater variety of SOAP formats).

Running ProSOAPView opens a SOAPSpy window, as shown in Figure 121.

Figure 121: SOAPSpy window opened by ProSOAPView

SOAPSpy works both an HTTP proxy server and as an HTTP client, meaning that it can serve
as a proxy between a Web service client and the Web service and also connect to its final
destination through another proxy, all without changing any of the Web service client code.

The data stream that SOAPSpy can track includes binary data as well as readable text. However,
binary data is represented schematically and all invalid text characters appear as the '?'
character.

1211
OpenEdge Development: Web Services

Running ProSOAPView (SOAPSpy)

You run ProSOAPView by setting it up as a proxy server for the Progress 4GL client.

To configure the Progress 4GL client and run ProSOAPView:

1. Start ProSOAPView by executing the prosoapview command in the OpenEdge

environment using the following syntax:

Syntax

prosoapview [ port-number ]

By default the SOAPSpy executable listens on TCP/IP port 4444. You can specify the
port-number value to change this port assignment.

2. To begin tracking HTTP and SOAP messages, be sure that the client application has not
yet executed the Web service CONNECT( ) method, then choose SpyStart Spying from
the menu bar, as shown in Figure 122, or click the spy icon in the SOAPSpy window.

Figure 122: ProSOAPView Spy menu

3. Start up the Progress 4GL client adding the following startup parameters to the command
line:

Syntax

-proxyhost localhost -proxyport port-number

Set port-number to the TCP/IP listening port used by SOAPSpy (4444 by default). For
more information on these startup parameters and starting up a Progress 4GL client, see
OpenEdge Deployment: Startup Command and Parameter Reference.

1212
 Handling Errors in Progress 4GL Requests to Web Services

Note: You do not have to change any connection parameters coded for the Web service
CONNECT( ) method in the 4GL client application to use ProSOAPView. Proxy
settings handle all redirection of message traffic that is required to inspect
messages sent between the 4GL client and the Web service.

After have opened the SOAPSpy window and begun tracking messages, the status bar indicates
the proxy host and port as shown in Figure 123, where the proxy host is name beata.

Figure 123: ProSOAPView status bar

Tracking messages in the SOAPSpy window

Once tracking begins, the SOAPSpy window shows a list of calls (Web service operation
invocations) on the left and a tab viewer on the right showing message content (see Figure
121).

Each call in the list is identified by its URI, the time of the call, and an icon that identifies the
type of call, as shown in Figure 124.

Figure 124: ProSOAPView Call types

When you select a call in the list, its message content appears in the tab viewer. You can view
different message content for a call by selecting a tab in the viewer. The HTTP Request and
HTTP Response tabs show the raw content of every call. The SOAP Request and SOAP
Response tabs allow you to manipulate individual SOAP messages, including WSDL requests.

1213
OpenEdge Development: Web Services

For example, Figure 125 shows the content of a SOAP request message in the SOAP Request
tab.

Figure 125: ProSOAPView Request tab

If you want to remove a call from the call list, select the call and choose Remove Call (see
Figure 126), either in the Call menu or in the context menu that pops up on the call.

Figure 126: ProSOAPView Call menu

1214
 13
Sample Progress 4GL Applications
Accessing Web Services

This release includes the following sample 4GL client procedures that invoke and manage Web
service requests:

Samples overview

Using the Temperature sample

Using the StockQuotes sample

Using the DatatypeFormats sample

OpenEdge Development: Web Services

Samples overview
The sample applications for 4GL clients accessing Web services reside in the following
OpenEdge installation path:

OpenEdge-install-dir/src/samples/webservices/4GLClient

This directory includes three samples located in these subdirectories:

Temperature

StockQuotes

DatatypeFormats

The rest of this chapter describes how to use each sample.

Note: The public Web services used by some of the samples are not always available and
Progress Software Corporation (PSC) has no control over the availability of these Web
services.

Temperature
This sample calls a public RPC/Encoded Web service that returns the temperature for a given
US zip code. In the process, it demonstrates the passing of a simple data type parameter to a
Web service.

The parameters include:

Input A US zip code as CHARACTER.

Output A temperature in Fahrenheit as CHARACTER.

For more information, see the Using the Temperature sample section on page 134.

132
 Sample Progress 4GL Applications Accessing Web Services

StockQuotes
This sample calls a public Web service in Document/Literal SOAP format that returns stock
information for any number of US stocks. In the process, it demonstrates how the 4GL handles
parameters for Document/Literal Web services in general and an XML Schema complex type
as a parameter.

The parameters include:

Input A complex type and an XML document that contains a comma or space
delimited list of stock symbols.

Output A complex type and an XML document that contains a .NET structure.

For more information, see the Using the StockQuotes sample section on page 139.

DatatypeFormats
This sample client calls a C#.NET Web service in Document/Literal SOAP format (included
with the client). It provides examples of how to format data for some of the XML Schema
simple data types displayed as a list. In the process, it demonstrates how the 4GL handles XML
Schema complex types as both input and output parameters.

The parameters include:

Input A complex type passed as an XML document.

Output A complex type passed as an XML document.

For more information, see the Using the DatatypeFormats sample section on page 1318.

133
OpenEdge Development: Web Services

Using the Temperature sample

TemperatureSample.p invokes the public Weather - Temperature Web Service example, listed
on this Web site:

http://www.xmethods.net/

The WSDL file is at the following location:

http://www.xmethods.net/sd/2001/TemperatureService.wsdl

Note: A public Web service used by a sample is not always available, and PSC has no control
over availability of a public Web service.

Web service description

The Weather - Temperature is an RPC/Encoded Web service that takes a U.S. zip code as input
and returns the current temperature.

134
 Sample Progress 4GL Applications Accessing Web Services

Temperature sample walk-through

TemperatureSample.p follows these steps to prepare, call, and process the output from a quote
request (source code edited and formatted for clarity):

1. Prompts for the requested zip code using the Enter Zip Code field:

DEFINE VARIABLE fillin-1 AS CHARACTER LABEL "Enter Zip Code".

.
.
.
DEFINE FRAME fTemp
fillin-1 AT ROW 3 COLUMN 5
bgetTemp AT ROW 5 COLUMN 12
fillin-2 AT ROW 7 COLUMN 5
WITH SIDE-LABELS SIZE 45 BY 10 THREE-D..
.
.
.
ENABLE ALL WITH FRAME fTemp.

2. Creates a Web service object in the 4GL:

DEFINE VARIABLE hWebService AS HANDLE.

.
.
.
CREATE SERVER hWebService.

3. Connects to the Web service:

hWebService:CONNECT("-WSDL
'http://www.xmethods.net/sd/2001/TemperatureService.wsdl' ").
IF NOT hWebService:CONNECTED() THEN
MESSAGE "SERVER NOT CONNECTED" VIEW-AS ALERT-BOX.

135
OpenEdge Development: Web Services

4. Sets the handle to the port type in the WSDL where the Web service operation is defined
and waits for the user to invoke the request:

DEFINE VARIABLE hPortType AS HANDLE.

.
.
.
RUN TemperaturePortType SET hPortType ON SERVER hWebService NO-ERROR.
IF ERROR-STATUS:ERROR THEN
MESSAGE "Failed to create hPortType" VIEW-AS ALERT-BOX.

WAIT-FOR CLOSE OF CURRENT-WINDOW.

5. When the user clicks the getTemp button, TemperatureSample.p:

a. Retrieves the zip code entered in the Enter Zip Code field:

DEFINE VARIABLE cZipCode AS CHARACTER.

.
.
.
ON CHOOSE OF bgetTemp
DO:
cZipCode = fillin-1:SCREEN-VALUE.
.
.
.

b. Invokes the Web service getTemp operation by making a procedure call:

DEFINE VARIABLE cTemp AS CHARACTER.

.
.
.
ON CHOOSE OF bgetTemp
DO:
cZipCode = fillin-1:SCREEN-VALUE.
RUN getTemp IN hPortType (INPUT cZipCode, OUTPUT cTemp) NO-ERROR.
.
.
.

136
 Sample Progress 4GL Applications Accessing Web Services

c. If there are no errors, assigns the output value from the getTemp procedure call to the
The Temp is field:

ON CHOOSE OF bgetTemp
DO:
cZipCode = fillin-1:SCREEN-VALUE.
RUN getTemp IN hPortType (INPUT cZipCode, OUTPUT cTemp) NO-ERROR.
IF ERROR-STATUS:ERROR THEN
DO:
DO i = 1 TO ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-MESSAGE(i) VIEW-AS ALERT-BOX.
END.
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL) THEN
DO:
MESSAGE "Fault Code: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-CODE SKIP
"Fault String: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-STRING SKIP
"Fault Actor: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-ACTOR SKIP
"Error Type: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:TYPE
VIEW-AS ALERT-BOX.
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL) THEN
MESSAGE "Error Type: "
ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL:TYPE
"Fault Detail: "
ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL:GET-SERIALIZED()
VIEW-AS ALERT-BOX.
END.
END.
ELSE
fillin-2:SCREEN-VALUE = STRING(cTemp, "99").
END.

137
OpenEdge Development: Web Services

d. If there are errors, displays the error information:

ON CHOOSE OF bgetTemp
DO:
cZipCode = fillin-1:SCREEN-VALUE.
RUN getTemp IN hPortType (INPUT cZipCode, OUTPUT cTemp) NO-ERROR.
IF ERROR-STATUS:ERROR THEN
DO:
DO i = 1 TO ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-MESSAGE(i) VIEW-AS ALERT-BOX.
END.
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL) THEN
DO:
MESSAGE "Fault Code: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-CODE SKIP
"Fault String: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-STRING SKIP
"Fault Actor: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-ACTOR SKIP
"Error Type: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:TYPE
VIEW-AS ALERT-BOX.
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL) THEN
MESSAGE "Error Type: "
ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL:TYPE
"Fault Detail: "
ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL:GET-SERIALIZED()
VIEW-AS ALERT-BOX.
END.
END.
ELSE
fillin-2:SCREEN-VALUE = STRING(cTemp, "99").
END.

Note that after displaying all the available error messages, it verifies that a SOAP
fault caused the error by checking if a SOAP fault object is part of the error status
(ERROR-STATUS:ERROR-OBJECT-DETAIL references it). After displaying the basic
SOAP fault information, it further verifies that there is SOAP fault detail information
by checking if a SOAP fault-detail object is part of the SOAP fault object data
(ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-DETAIL references it) and
displays any SOAP fault detail information that it references.

138
 Sample Progress 4GL Applications Accessing Web Services

6. Cleans up by running this code:

DELETE PROCEDURE hPortType.

hWebService:DISCONNECT().
DELETE OBJECT hWebService.

which:

a. Deletes the procedure object.

b. Disconnects from the Web service.

c. Deletes the Web service object.

Using the StockQuotes sample

StockQuotes.p invokes a Stock Quote Web service, listed on this Web site:

http://www.xmethods.net/

The actual Web service is located on the Web at:

http://www.swanandmokashi.com/HomePage/WebServices/StockQuotes.asmx

Note: A public Web service used by a sample is not always available, and PSC has no control
over availability of a public Web service.

139
OpenEdge Development: Web Services

Web service description

The Stock Quote is a public Document/Literal Web service that retrieves the latest stock quote
for a stock ticker that is available at least 20 minutes before the request.

To get multiple quotes, you can enter ticker symbols separated by:

A comma (,), for example:

MSFT,YHOO,GE,PRGS

Or a space, for example:

MSFT YHOO GE PRGS

For a given ticker symbol, the Web service returns the following information:

Company name

Ticker

Stock quote

Price change

Open price

Day range (high/low)

Volume

Market cap

Year range

1310
 Sample Progress 4GL Applications Accessing Web Services

StockQuotes sample walk-through

StockQuotes.p follows these steps to prepare, call, and process the output from a quote request
(source code edited and formatted for clarity):

1. Prompts for the stock symbol(s) to populate the XML document entered using the Enter
Stock Symbols prompt:

DEFINE VARIABLE fillin-1 AS CHARACTER FORMAT "x(40)".

DEFINE VARIABLE text-1 AS CHARACTER FORMAT "x(50)" VIEW-AS TEXT.
DEFINE VARIABLE fillin-2 AS CHARACTER
VIEW-AS EDITOR LARGE SIZE 63 BY 15 SCROLLBAR-VERTICAL LABEL "".
DEFINE VARIABLE text-2 AS CHARACTER FORMAT "x(80)" VIEW-AS TEXT.
DEFINE BUTTON bgetQuote LABEL "getQuote" SIZE 14 BY 1.

DEFINE FRAME fTemp

text-1 AT ROW 1.5 COLUMN 2
fillin-1 AT ROW 1.25 COLUMN 25
text-2 AT ROW 3 COLUMN 2
bgetQuote AT ROW 4.5 COLUMN 30
fillin-2 AT ROW 6 COLUMN 5
WITH NO-LABELS SIZE 82 BY 22 THREE-D.
.
.
.
FILLIN-1:SCREEN-VALUE = "PRGS".
text-1:SCREEN-VALUE = "Enter Stock Symbols".
text-2:SCREEN-VALUE = "To get multiple quotes enter Ticker symbols
seperated by , (eg. PRGS,GE)".
ENABLE ALL WITH FRAME fTemp.

2. Creates a Web service object in the 4GL:

DEFINE VARIABLE hWS AS HANDLE.

.
.
.
CREATE SERVER hWS.

1311
OpenEdge Development: Web Services

3. Connects to the Web service (which has only one valid service and port):

hWS:CONNECT("-WSDL
http://www.swanandmokashi.com/HomePage/WebServices/StockQ
uotes.asmx?wsdl).
IF NOT hWS:CONNECTED() THEN
MESSAGE "SERVER NOT CONNECTED" VIEW-AS ALERT-BOX.

4. Sets the handle to the port type in the WSDL where the Web service operation is defined
and waits for the user to invoke the request:

DEFINE VARIABLE hPortType AS HANDLE.

.
.
.
RUN StockQuotesSoap SET hPortType ON SERVER hWS.
IF NOT VALID-HANDLE(hPortType) THEN
MESSAGE "hPortType invalid: " VALID-HANDLE(hPortType)
VIEW-AS ALERT-BOX.

WAIT-FOR CLOSE OF CURRENT-WINDOW.

5. When the user clicks the getQuote button, StockQuotes.p:

a. Constructs the XML document that is input to the Web service operation. The
document is created in this form:

<s0:GetStockQuotes xmlns:s0="http://swanandmokashi.com/">
<s0:QuoteTicker>stock-symbol(s)</s0:QuoteTicker>
</s0:GetStockQuotes>

1312
 Sample Progress 4GL Applications Accessing Web Services

This is the code, which also saves the document as a LONGCHAR:

DEFINE VARIABLE lcSymbol AS LONGCHAR

VIEW-AS EDITOR LARGE SIZE 60 BY 20.
DEFINE VARIABLE lcQuote AS LONGCHAR
VIEW-AS EDITOR LARGE SIZE 60 BY 20.
DEFINE VARIABLE hDoc AS HANDLE.
DEFINE VARIABLE hRoot AS HANDLE.
DEFINE VARIABLE hChild AS HANDLE.
DEFINE VARIABLE hNextChild AS HANDLE.
DEFINE VARIABLE hNextNode AS HANDLE.
DEFINE VARIABLE hTextNode AS HANDLE.
.
.
.
ON CHOOSE of bgetQuote
DO:
.
.
.
CREATE X-DOCUMENT hDoc.
CREATE X-NODEREF hRoot.
CREATE X-NODEREF hChild.
CREATE X-NODEREF hNextChild.
CREATE X-NODEREF hNextNode.
CREATE x-noderef hTextNode.

hDoc:CREATE-NODE-NAMESPACE(hRoot, "http://swanandmokashi.com/",
"s0:GetStockQuotes", "element").
hRoot:SET-ATTRIBUTE("xmlns:s0", "http://swanandmokashi.com/").
hDoc:APPEND-CHILD(hRoot).

hDoc:CREATE-NODE-NAMESPACE(hChild, "http://swanandmokashi.com/",
"s0:QuoteTicker", "element").
hRoot:APPEND-CHILD(hChild).

hDoc:CREATE-NODE(hTextNode, ?, "text").
hTextNode:NODE-VALUE = FILLIN-1:SCREEN-VALUE.
hChild:APPEND-CHILD(hTextNode).

hDoc:SAVE("longchar", lcSymbol).
.
.
.

1313
OpenEdge Development: Web Services

b. Invokes the GetStockQuotes operation in the Web service by making a procedure

call:

DEFINE VARIABLE lcQuote AS LONGCHAR

VIEW-AS EDITOR LARGE SIZE 60 BY 20.
.
.
.
ON CHOOSE of bgetQuote
DO:
.
.
.
RUN GetStockQuotes IN hPortType (INPUT lcSymbol, OUTPUT lcQuote)
NO-ERROR.

c. Checks for errors and manages the information for any that occur (see the Common
procedure for SOAP fault handling section on page 1327):

DEFINE VARIABLE err AS LOGICAL.

.
.
.
ON CHOOSE of bgetQuote
DO:
.
.
.
RUN GetStockQuotes IN hPortType (INPUT lcSymbol, OUTPUT lcQuote)
NO-ERROR.
RUN ErrorInfo (OUTPUT err).
.
.
.

1314
 Sample Progress 4GL Applications Accessing Web Services

d. If there are no errors, loads the XML document that was passed back as a LONGCHAR
OUTPUT parameter:

ON CHOOSE of bgetQuote
DO:
.
.
.
IF NOT err THEN
DO:
hDoc:LOAD("longchar", lcQuote, FALSE).
.
.
.

e. The Web service returns the output XML document with the following structure
(shown for a single quote example, PRGS):

<GetStockQuotesResponse xmlns="http://swanandmokashi.com/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetStockQuotesResult>
<Quote>
<CompanyName>PROGRESS SOFT</CompanyName>
<StockTicker>PRGS</StockTicker>
<StockQuote>21.41</StockQuote>
<LastUpdated>4:00pm</LastUpdated>
<Change>+0.86</Change>
<OpenPrice>N/A</OpenPrice>
<DayHighPrice>21.60</DayHighPrice>
<DayLowPrice>20.41</DayLowPrice>
<Volume>160721</Volume>
<MarketCap>740.4M</MarketCap>
<YearRange>11.50 - 24.06</YearRange>
</Quote>
</GetStockQuotesResult>
</GetStockQuotesResponse>

1315
OpenEdge Development: Web Services

The client then parses this document to get the relevant information and put it into a
CHARACTER variable for display:

DEFINE VARIABLE cResult AS CHARACTER INITIAL "". . . .

ON CHOOSE of bgetQuote
DO:
.
.
.
IF NOT err THEN
DO:
hDoc:LOAD("longchar", lcQuote, FALSE).
hDoc:GET-DOCUMENT-ELEMENT(hRoot).
/* hRoot = GetStockQuotesResponse */
IF hRoot:SUBTYPE = "ELEMENT" AND
hRoot:NAME = "GetStockQuotesResponse" THEN
DO:
hRoot:GET-CHILD(hChild, 1).
/* hChild = GetStockQuotesResult */
IF hChild:SUBTYPE = "ELEMENT" AND
hChild:NAME = "GetStockQuotesResult" THEN
DO i = 1 TO hChild:NUM-CHILDREN:
hChild:GET-CHILD(hNextChild, i).
/* hNextChild = Quote */
IF hNextChild:SUBTYPE = "ELEMENT" AND
hNextChild:NAME = "Quote" THEN
DO j = 1 TO hNextChild:NUM-CHILDREN:
hNextChild:GET-CHILD(hNextNode, j).
IF hNextNode:NAME = "CompanyName" THEN
DO:
hNextNode:GET-CHILD(hTextNode, 1).
IF hTextNode:SUBTYPE = "TEXT" THEN
cResult = cResult + hNextNode:NAME + " = " +
hTextNode:NODE-VALUE + "~n".
END.
.
.
.
IF hNextNode:NAME = "YearRange" THEN
DO:
hNextNode:GET-CHILD(hTextNode, 1).
IF hTextNode:SUBTYPE = "TEXT" THEN
cResult = cResult + hNextNode:NAME + " = " +
hTextNode:NODE-VALUE + "~n".
END.
END. /* hNextChild = Quote */
END. /* hChild = GetStockQuotesResult*/
END. /* hRoot = GetStockQuotesResponse */
END. /* IF NOT err */
. . .
END. /* bgetQuote */

1316
 Sample Progress 4GL Applications Accessing Web Services

f. Displays the CHARACTER variable containing the data in an EDITOR widget:

ON CHOOSE of bgetQuote
DO:
.
.
.
fillin-2:SCREEN-VALUE = cResult.
END. /* bgetQuote */

6. Cleans up by running this code:

DELETE PROCEDURE hPortType.

hWS:DISCONNECT().
DELETE OBJECT hWS.

which:

a. Deletes the procedure object.

b. Disconnects from the Web service.

c. Deletes the Web service object.

1317
OpenEdge Development: Web Services

Using the DatatypeFormats sample

DatatypeFormats.p invokes the operation MultiDatatypes( ) in the following C# .NET Web
service installed with OpenEdge:

http://localhost/DatatypeFormats/Service1.asmx

This Web service is available at the following path under the OpenEdge installation directory:

src\samples\webservices\4GLClient\DatatypeFormats\CS.NET\DatatypeFormats

Web service description

MultiDatatypes( ) copies a set of value-format pairs packaged as a complex type to an output
parameter that contains the values formatted using the corresponding formats, also packaged as
a complex type.

Table 131 shows some of the formats that SOAP requires to format the XML Schema data
types handled by this operation.

Table 131: DatatypeFormats sample applicationexample formats

Data type Example formats

boolean true, false, 1, 0

datetime 9999-99-99THH:MM:SS.SSS+HH:MM

duration P99Y99M99DT99H99M99S

gDay ---DD

gMonth --MM--

gMonthDay --MM-DD

gYear YYYY

gYearMonth YYYY-MM

1318
 Sample Progress 4GL Applications Accessing Web Services

The complex type input parameter passed to MultiDatatypes( ) contains the simple type
parameters shown in Table 132.

Table 132: DatatypeFormats sample applicationinput parameters

Parameter
simple type Parameter name

boolean paramIn1

batetime paramIn2

duration paramIn3

gDay paramIn4

gMonth paramIn5

gMonthDay paramIn6

gYear paramIn7

gYearMonth paramIn8

The complex type output parameter passed to MultiDatatypes( ) contains the simple type
parameters shown in Table 133.

Table 133: DatatypeFormats sample applicationoutput parameters

Parameter
simple type Parameter name

boolean paramIn1

batetime paramIn2

duration paramIn3

gDay paramIn4

gMonth paramIn5

gMonthDay paramIn6

gYear paramIn7

gYearMonth paramIn8

1319
OpenEdge Development: Web Services

DatatypeFormats sample walk-through

DatatypeFormats.p follows these steps to prepare, call, and process the output from
MultiDatatypes( ) (source code edited and formatted for clarity):

1. Creates a Web service object in the 4GL:

DEFINE VARIABLE hWS AS HANDLE.

.
.
.
CREATE SERVER hWS.

2. Connects to the Web service (which has only one valid service and port):

hWS:CONNECT("-WSDL
http://localhost/DatatypeFormats/Service1.asmx?WSDL).
IF NOT hws:CONNECTED() THEN
DO:
MESSAGE "SERVER:CONNECTED : " hws:CONNECTED() VIEW-AS ALERT-BOX.
LEAVE.
END.

3. Sets the handle to the port type in the WSDL where the MultiDatatypes( ) operation is
defined:

DEFINE VARIABLE hPortType AS HANDLE.

.
.
.
RUN Service1Soap SET hPortType ON SERVER hWS.
IF NOT VALID-HANDLE(hPortType) THEN
DO:
MESSAGE "hPortType valid: " VALID-HANDLE(hPortType)
VIEW-AS ALERT-BOX.
LEAVE.
END.

1320
 Sample Progress 4GL Applications Accessing Web Services

4. Creates the XML document used to pass the input complex type parameter as a LONGCHAR.
This operation requires that the INPUT and OUTPUT parameters are XML documents
because the Web service SOAP format is Document/Literal. The Web service expects the
XML document input parameter to have this structure:

<ns0:MultiDatatypes xmlns:ns0="http://tempuri.org/">
<ns0:paramIn1>boolean-value</ns0:paramIn1>
<ns0:paramIn2>dateTime-value</ns0:paramIn2>
<ns0:paramIn3>duration-value</ns0:paramIn3>
<ns0:paramIn4>gDay-value</ns0:paramIn4>
<ns0:paramIn5>gMonth-value</ns0:paramIn5>
<ns0:paramIn6>gMonthDay-value</ns0:paramIn6>
<ns0:paramIn7>gYear-value</ns0:paramIn7>
<ns0:paramIn8>gYearMonth-value</ns0:paramIn8>
</ns0:MultiDatatypes>

1321
OpenEdge Development: Web Services

This is a sample of the code showing the boolean value of the first parameter and the
gYearMonth value of the last parameter added to the newly-created XML document:

DEFINE VARIABLE lBoolIn as LOGICAL.

DEFINE VARIABLE sgYearMonthIn AS CHARACTER.

DEFINE VARIABLE hDoc AS HANDLE.

DEFINE VARIABLE hRoot AS HANDLE.
DEFINE VARIABLE hText AS HANDLE.
DEFINE VARIABLE hNode AS HANDLE.
DEFINE VARIABLE hChildNode AS HANDLE.
.
.
.
CREATE X-DOCUMENT hDoc.
CREATE X-NODEREF hRoot.
CREATE X-NODEREF hText.
CREATE X-NODEREF hNode.
CREATE X-NODEREF hChildNode.

hDoc:CREATE-NODE-NAMESPACE(hRoot, "http://tempuri.org/",
"s0:MultiDatatypes", "element").
hRoot:SET-ATTRIBUTE("xmlns:s0", "http://tempuri.org/").
hDoc:APPEND-CHILD(hRoot).

/* paramIn1 boolean */
/* boolean value must one of the following values: true, false, 1, 0 */
lBoolIn = TRUE.
hDoc:CREATE-NODE-NAMESPACE(hNode, "http://tempuri.org/",
"s0:paramIn1", "element").
hRoot:APPEND-CHILD(hNode).
hDoc:CREATE-NODE(hText, ?, "text").
hText:NODE-VALUE = STRING(lBoolIn, "true/false").
hNode:APPEND-CHILD(hText).
.
.
.
/* paramIn8 gYearMonth */
/* dYearMonth must be in the format "YYYY-MM" */
sgYearMonthIn = "199902".
hDoc:CREATE-NODE-NAMESPACE(hNode, "http://tempuri.org/",
"s0:paramIn8", "element").
hRoot:APPEND-CHILD(hNode).
hDoc:CREATE-NODE(hText, ?, "text").
hText:NODE-VALUE = STRING(sgYearMonthIn, "9999-99").
hNode:APPEND-CHILD(hText).

1322
 Sample Progress 4GL Applications Accessing Web Services

5. Saves the XML document INPUT parameter as a LONGCHAR:

DEFINE VARIABLE ret AS LOGICAL.

DEFINE VARIABLE lcInput AS LONGCHAR VIEW-AS EDITOR LARGE SIZE 40 BY 10.
.
.
.
ret = hDoc:SAVE( "longchar" , lcInput).

6. Invokes the MultiDatatypes( ) operation of the Web service by making a procedure call:

DEFINE VARIABLE lcOutput AS LONGCHAR VIEW-AS EDITOR LARGE SIZE 70 BY 10.

.
.
.
IF ret THEN
DO:
RUN MultiDatatypes IN hPortType (INPUT lcInput, OUTPUT lcOutput)
NO-ERROR.
.
.
.
END.

7. Checks for errors and manages the information for any that occur (see the Common
procedure for SOAP fault handling section on page 1327):

DEFINE VARIABLE err AS LOGICAL.

.
.
.
ON CHOOSE of bgetQuote
DO:
.
.
.
RUN MultiDatatypes IN hPortType (INPUT lcInput, OUTPUT lcOutput)
NO-ERROR.
RUN ErrorInfo (OUTPUT err).
.
.
.

1323
OpenEdge Development: Web Services

8. If there are no errors, loads the XML document that was passed back in the OUTPUT
parameter:

DO:
.
.
.
IF NOT err THEN
DO:
ret = hDoc:LOAD("longchar" , lcOutput, FALSE).
.
.
.
END.
END.

The Web service returns the output XML document with the following structure:

<ns0:MultiDatatypesResponse xmlns:ns0="http://tempuri.org/">
<ns0:paramOut1>boolean-value</ns0:paramOut1>
<ns0:paramOut2>dateTime-value</ns0:paramOut2>
<ns0:paramOut3>duration-value</ns0:paramOut3>
<ns0:paramOut4>gDay-value</ns0:paramOut4>
<ns0:paramOut5>gMonth-value</ns0:paramOut5>
<ns0:paramOut6>gMonthDay-value</ns0:paramOut6>
<ns0:paramOut7>gYear-value</ns0:paramOut7>
<ns0:paramOut8>gYearMonth-value</ns0:paramOut8>
</ns0:MultiDatatypesResponse>

1324
 Sample Progress 4GL Applications Accessing Web Services

9. Parses the XML document, with the following code showing how values are retrieved for
the boolean value of the first parameter and the gYearMonth value of the last parameter of
the complex type:

DO:
.
.
.
DO:
.
.
.
hDoc:GET-DOCUMENT-ELEMENT(hRoot).
DO i = 1 TO hRoot:NUM-CHILDREN:
hRoot:GET-CHILD(hNode, i).
IF hNode:SUBTYPE = "ELEMENT" THEN
DO:
IF hNode:NAME = "paramOut1" THEN /* boolean */
DO:
Ret = hNode:GET-CHILD(hChildNode, 1).
IF ret AND hChildNode:subtype = "TEXT" THEN
BoolOut = LOGICAL(hChildNode:NODE-VALUE).
END.
.
.
.
IF hNode:NAME = "paramOut8" THEN /* gYearMonth */
DO:
Ret = hNode:GET-CHILD(hChildNode, 1).
IF ret AND hChildNode:subtype = "TEXT" THEN
sgYearMonthOut = hChildNode:NODE-VALUE.
END.

END.
END.
.
.
.
END.
END.

1325
OpenEdge Development: Web Services

10. Displays the data that was extracted from the XML:

DO:
.
.
.
DO:
.
.
.
MESSAGE "Return Values = " SKIP
lBoolOut SKIP
dtzDateOut SKIP
sdurationOut SKIP
sgDayOut SKIP
sgMonthOut SKIP
sgMonthDayOut SKIP
sgYearOut SKIP
sgYearMonthOut
VIEW-AS ALERT-BOX.
END.
END.

11. Cleans up by running this code:

DELETE PROCEDURE hPortType.

hWS:DISCONNECT().
DELETE OBJECT hWS.

which:

a. Deletes the procedure object.

b. Disconnects from the Web service.

c. Deletes the Web service object.

1326
 Sample Progress 4GL Applications Accessing Web Services

Common procedure for SOAP fault handling

The examples StockQuotes.p and DataFormats.p share a common procedure (using their own
physical code copies) for handling SOAP faults. This works because the possible information
that can be received for a SOAP fault is essentially the same for all Web services. You can, of
course, design such a procedure differently to manage the error information and present it to the
user. However, just about any design that you choose can work with any Web service.

This is the procedure that both procedures call to handle all errors, including SOAP faults
(modified to include numeric step comments that are referenced by the following description):

PROCEDURE ErrorInfo: /*1*/

DEFINE OUTPUT PARAMETER errorfound AS LOGICAL INITIAL FALSE.

IF ERROR-STATUS:NUM-MESSAGES > 0 THEN

DO:
errorfound = TRUE.

DO i = 1 TO ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-MESSAGE(i) VIEW-AS ALERT-BOX.
END.
/*2*/
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL) THEN
DO:
MESSAGE "Fault Code: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-CODE SKIP
"Fault String: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-STRING SKIP
"Fault Actor: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-ACTOR SKIP
"Error Type: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:TYPE
VIEW-AS ALERT-BOX.
/*3*/
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-DETAIL)
THEN
MESSAGE "Error Type: "
ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-DETAIL:TYPE
"Fault Detail: "
ERROR-STATUS:ERROR-OBJECT-DETAIL
:SOAP-FAULT-DETAIL:GET-SERIALIZED()
VIEW-AS ALERT-BOX.
END.
END.
END.

1327
OpenEdge Development: Web Services

This code:

1. Determines whether an error has occurred from the value of the OUTPUT parameter, which
is set to TRUE if error messages exist. Each example procedure calls ErrorInfo after
invoking a Web service operation, for example:

RUN GetStockQuotes IN hPortType (INPUT lcSymbol, OUTPUT lcQuote)

NO-ERROR.
RUN ErrorInfo (OUTPUT err).
IF NOT err THEN
/* Process operation results. */
. . .

If an error occurs, ErrorInfo has already processed the error information in expectation
that no normal results are available from the operation to process.

2. After displaying all the available error messages, ErrorInfo verifies that a SOAP fault
caused the error by checking if a SOAP fault object is part of the error status
(ERROR-STATUS:ERROR-OBJECT-DETAIL references it).

3. After displaying the basic SOAP fault information, ErrorInfo further verifies that there
is SOAP fault detail information by checking if a SOAP fault-detail object is part of the
SOAP fault object data (ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-DETAIL
references it) and displays any SOAP fault detail information that it references.

Note also that the error processing in ErrorInfo is essentially identical to the error processing
in the TemperatureSample.p procedure, which could be easily rewritten to call it.

1328
 Part IV
Appendices

Appendix A, Developing a .NET Client to Access Progress 4GL Web Services

Appendix B, Developing a Java Client to Access Progress 4GL Web Services

Appendix C, Progress 4GL Elements for Accessing Web Services

Appendix D, Data Type Casting Rules for Progress 4GL Calls to Web Services
 A
Developing a .NET Client to Access
Progress 4GL Web Services

This appendix describes the basic tasks to develop a .NET client application to use a Progress
4GL Web service. as described in the following sections:

What is Microsoft .NET?

Using .NET as your Web services client

VB.NET sample Web service specifications

Creating the VB.NET client interface

Developing the VB.NET client application

Compiling and running the .NET client application

Learning more about writing .NET clients

OpenEdge Development: Web Services

What is Microsoft .NET?

Briefly, Microsoft .NET supports the following features:

As described by Microsoft, .NET is a robust platform for developing the next generation
of applications.

It is built using industry standards, such as XML and SOAP.

The .NET platform supports many languages, including:

Visual Basic .NET

Visual C# .NET

The .NET API, including data type support, is the same for all languages.

.NET provides a single development environment, Visual Studio .NET, to work with all
its supported languages.

.NET supports the following SOAP formats that are also supported by Progress 4GL Web
services:

RPC/Encoded

Document/Literal

Note: .NET does not support RPC/Literal.

A2
 Developing a .NET Client to Access Progress 4GL Web Services

Using .NET as your Web services client

To create a .NET Web service client application, you perform a standard set-up procedure at the
start of application development.

To create your Web service client application using Visual Studio.NET:

1. Choose a .NET language and create a new project.

2. Add a Web reference for the Web service by specifying the WSDL file location. This
automatically creates a .NET interface.

3. Add logic to the client to create interface objects and call interface methods.

The language used in the rest of this chapter to demonstrate client development with .NET is
Visual Basic (VB.NET).

VB.NET sample Web service specifications

Table A1 describes the specifications for a sample Web service and interface used to illustrate
client development with VB.NET.

Table A1: VB.NET sample Web service specifications (1 of 2)

Property or
component Value or name Object type

Web reference OrderService

URL http://servicehost:80/wsa/wsa1

Session model Managed

TargetNamespace urn:OrderSvc:OrderInfo

A3
OpenEdge Development: Web Services

Table A1: VB.NET sample Web service specifications (2 of 2)

Property or
component Value or name Object type

WSDL objects OrderInfoObj AppObject

CustomerOrderObj ProcObject

OrderInfoID AppObject ID

CustomerOrderID ProcObject ID

OrderDetailsRow Temp-table OrderDetails

Creating the VB.NET client interface

The following sections describe tasks and features for creating the VB.NET client interface:

Adding a Web reference

Reference.vbWeb service client interface

Reference.vbOpen Client objects

.NET data type mapping

Accessing parameter data

TABLE (static temp-table) parameters

TABLE-HANDLE (dynamic temp-table) parameters

Sample interface object prototypes in Reference.vb

Sample common interface method prototypes in Reference.vb

Sample Progress 4GL and VB.NET interface method prototypes

These sections review information presented in previous sections of the manual, to provide
context for understanding the VB.NET environment.

A4
 Developing a .NET Client to Access Progress 4GL Web Services

Adding a Web reference

Adding a Web reference essentially generates the client interface.

To generate a client interface:

1. Enter the URL for the WSDL file. The TargetURI can be set to either the Web service
friendly name (AppObject name, by default) or the TargetNamespace for the Web service,
as in the following examples:

http://servicehost:80/wsa/wsa1/wsdl?targetURI=OrderInfo
http://servicehost:80/wsa/wsa1/wsdl?targetURI=
urn:OrderSvc:OrderInfo

2. Rename the Web reference you added to the project appropriately (for example, from
servicehost to OrderService). Select the Show All Files toolbar button (or choose
ProjectShow All Files) to locate the Web reference file, Reference.vb under the
renamed Web reference.

Reference.vbWeb service client interface

The client interface generated from the WSDL has objects for:

Every Open Client object, for example, OrderInfo and CustomerOrder.

The object ID for each Open Client object (except a session-free AppObject). For
example, OrderInfoID and CustomerOrderID.

Every temp-table, for example, OrderDetailsRow.

A5
OpenEdge Development: Web Services

Reference.vbOpen Client objects

Each Open Client object class usually contains:

The URL of the WSA.

Methods defined in the WSDL for the object.

A member variable for its own object ID, such as OrderInfoID in the sample.

Member variables for the object IDs of any objects created using CreateXX_* methods
(SubAppObjects and ProcObjects), such as CustomerOrderID in the sample.

Each object is named as follows:

It takes the WSDL service name if the Web service has only one object (AppObject), such
as OrderInfoService.

It takes the WSDL <binding> element names, such as OrderInfoObj and

CustomerOrderObj, if the Web service has more than one object.

A6
 Developing a .NET Client to Access Progress 4GL Web Services

.NET data type mapping

Table A2 lists the data-type mappings for parameters between the Progress 4GL and .NET.

Table A2: Supported .NET data types

Progress 4GL data type .NET data type

CHARACTER String

COM-HANDLE Long

DATE Date

DECIMAL Decimal

INTEGER (32 bit) Integer

LOGICAL Boolean

MEMPTR Byte( )

RAW Byte( )

RECID (32 or 64 bit) Long

ROWID Byte( )

TABLE Object

TABLE-HANDLE Object

WIDGET-HANDLE Long

Accessing parameter data

The interface automatically generates parameter data for VB.NET client variables:

For scalar parameters, the client does not need to do any special additional processing to
use them.

TABLE and TABLE-HANDLE parameters require extra processing for the client to use them.

A7
OpenEdge Development: Web Services

TABLE (static temp-table) parameters

For TABLE parameters:

Client interfaces contain an object for each WSDL <complexType> definition of a TABLE
row. For example, the OrderDetailsRow class is declared as follows:

Public Class OrderDetailsRow...

The client interface represents the TABLE parameters as arrays of these row objects.

Table A3 lists the data type mappings for TABLE columns between the Progress 4GL and .NET.

Table A3: .NET data types for TABLE (static temp-table) parameter
columns

Progress 4GL data type .NET data type

CHARACTER String

COM-HANDLE Long

DATE Date

DECIMAL Decimal

INTEGER (32 bit) Integer

LOGICAL Boolean

RAW Byte( )

RECID (32 or 64 bit) Long

ROWID Byte( )

WIDGET-HANDLE Long

A8
 Developing a .NET Client to Access Progress 4GL Web Services

TABLE-HANDLE (dynamic temp-table) parameters

For TABLE-HANDLE parameters, the client must create (for input) and parse (for output) the XML
Schema and data for theTABLE-HANDLE.

Table A4 lists the typical data type mappings for TABLE-HANDLE columns between the Progress
4GL and .NET.

Table A4: .NET data types for TABLE-HANDLE (dynamic temp-table)

parameter columns

Progress 4GL data type .NET data type

CHARACTER String

DATE Date

DECIMAL Decimal

INTEGER (32 bit) Integer

LOGICAL Boolean

RAW Byte( )

When passing a TABLE-HANDLE parameter, the interface or the client views it with different
object types, depending on the Web service SOAP format:

For RPC/Encoded:

The interface represents the parameter as an Object type.

The client represents the parameter as a System.Array type.

For Document/Literal, both the interface and the client represent the parameter as a
System.Xml.XmlElement type.

A9
OpenEdge Development: Web Services

Sample interface object prototypes in Reference.vb

The Web reference file (Reference.vb) defines the sample interface objects using the following
Class declarations. Note the member variables:

Object ID classes

OrderInfoID:

Public Class OrderInfoID Inherits SoapHeader

Public UUID As String
End Class

CustomerOrderID:

Public Class CustomerOrderID Inherits SoapHeader

Public UUID As String
End Class

AppObject class

OrderInfoObj:

Public Class OrderInfoObj

Public OrderInfoIDValue As OrderInfoID
Public CustomerOrderIDValue As CustomerOrderID
...
End Class

Note: The methods in this class declaration are not shown.

A10
 Developing a .NET Client to Access Progress 4GL Web Services

ProcObject class

CustomerOrderObj:

Public Class CustomerOrderObj

Public CustomerOrderIDValue As CustomerOrderID
...
End Class

Note: The methods in this class declaration are not shown.

Sample common interface method prototypes in

Reference.vb
The Web reference file (Reference.vb) defines the sample common interface methods for
managing Web service objects using the following Sub declarations:

Common OrderInfoObj AppObject methods

Connect_OrderInfo( ):

Public Sub Connect_OrderInfo(

ByVal userId As String,
ByVal password As String,
ByVal appServerInfo As String)

Release_OrderInfo( ):

Public Sub Release_OrderInfo( )

Common CustomerOrderObj ProcObject methods

Release_CustomerOrder( ):

Public Sub Release_CustomerOrder( )

A11
OpenEdge Development: Web Services

Sample Progress 4GL and VB.NET interface method

prototypes
The following examples show Progress 4GL prototypes and how the sample Reference.vb file
maps them to the equivalent VB.NET method prototypes:

Note: The object ID in the SOAP headers are not shown in the VB.NET method prototypes.

Non-persistent procedure

Progress 4GL:

/* FindCustomerByNum.p */

DEFINE INPUT PARAMETER CustomerNumber AS INTEGER.

DEFINE OUTPUT PARAMETER CustomerName AS CHARACTER.

VB.NET OrderInfoObj (AppObject) method:

Public Sub FindCustomerByNum(

ByVal CustomerNumber As Integer,
ByRef CustomerName As String)

Persistent procedure

Progress 4GL:

/* CustomerOrder.p */

DEFINE INPUT PARAMETER custNum AS INTEGER.

Note: This procedure returns a value using the 4GL RETURN statement.

A12
 Developing a .NET Client to Access Progress 4GL Web Services

VB.NET OrderInfoObj (AppObject) method:

Public Function CreatePO_CustomerOrder

(ByVal custNum As Integer) As String

User-defined function

Progress 4GL:

/* CustomerOrder.p */

FUNCTION GetTotalOrdersByNumber RETURNS INTEGER

(Threshold AS DECIMAL) :

VB.NET CustomerOrderObj (ProcObject) method:

Public Function GetTotalOrdersByNumber

(ByVal Threshold As Decimal) As Integer

Internal procedure passing a TABLE parameter

Progress 4GL:

/* CustomerOrder.p */

PROCEDURE GetOrderDetails :
DEFINE OUTPUT PARAMETER TABLE FOR OrderDetails.

VB.NET CustomerOrderObj (ProcObject) method:

Public Sub GetOrderDetails(

ByRef OrderDetails( ) As OrderDetailsRow)

A13
OpenEdge Development: Web Services

TABLE definition

Progress 4GL:

/* CustomerOrder.p */

DEFINE TEMP-TABLE OrderDetails

FIELD OrderNum LIKE Order.OrderNum
FIELD SalesRep LIKE Order.SalesRep
FIELD OrderDate LIKE Order.OrderDate
FIELD ShipDate LIKE Order.ShipDate
FIELD TotalDollars AS DECIMAL
FIELD OrderStatus LIKE Order.OrderStatus.

VB.NET OrderDetailsRow object:

Public Class OrderDetailsRow

Public OrderNum As Integer
Public SalesRep As String
<. . .> Public OrderDate As Date
<. . .> Public ShipDate As Date
Public TotalDollars As Decimal
Public OrderStatus As String

External procedure passing a TABLE-HANDLE parameter

Progress 4GL:

/* DynTT.p */

DEFINE INPUT-OUTPUT PARAMETER TABLE-HANDLE ttHandle.

VB.NET RPC/Encoded method:

Public Sub DynTT(ByRef ttHandle As Object)

VB.NET Document/Literal method:

Public Function DynTT(ByRef ttHandle As System.Xml.XmlElement) As String

A14
 Developing a .NET Client to Access Progress 4GL Web Services

Developing the VB.NET client application

Once you have added the Web reference and generated the client interface for the Web service,
you can develop the client application. The typical tasks for developing a VB.NET client
include:

Creating the Web service

Running a non-persistent (external) procedure

Creating server-side context for a ProcObject (running a persistent procedure)

Running an internal procedure or user-defined function

Creating a SubAppObject

Releasing an object

Running a procedure that passes a TABLE parameter

Processing the data from a TABLE parameter

Running a procedure that passes a TABLE-HANDLE parameter

Preparing the schema and data for an input TABLE-HANDLE parameter

Processing the schema and data for an output TABLE-HANDLE parameter

Extra processing required for RPC/Encoded TABLE-HANDLE parameters

Handling errors on the client

Notes: For more information on the concepts and procedures that underlie these tasks, see
Chapter 4, General Client Programming Model for Progress 4GL Web Services and
Chapter 5, Sample Code with SOAP Messages for Progress 4GL Web Services.

OpenEdge comes installed with complete sample client applications that access 4GL
Web services. For more information, see Chapter 6, Sample Progress 4GL Web
Services and Client Applications.

A15
OpenEdge Development: Web Services

Creating the Web service

Complete the steps that follow to create the Web service.

To create the Web service:

1. Create the AppObject:

' There is no communication with the WSA at this time

Dim WS_OrderService As OrderService.OrderInfoObj
WS_OrderService = New OrderService.OrderInfoObj( )

2. Call the connect method on the AppObject (session managed only):

' Connect to the Progress Session Managed Web Service

WS_OrderService.Connect_OrderInfo("", "", "")

Note: Note that the value of the OrderInfoIDValue is extracted from the SOAP response
header automatically by the interface. This value is then assigned to the
OrderInfoIDValue member variable of the AppObject (WS_OrderService).

Running a non-persistent (external) procedure

The following example shows how you might invoke the sample FindCustomerByNum( )
method:

' Send a request to the AppServer to get the Customer Name

' and display in the UI
WS_OrderService.FindCustomerByNum(custNum, custName)
If custName <> Nothing Then
lblCustName.Text = custName

Note: The OrderInfoIDValue is automatically inserted in the SOAP request header by the
interface.

A16
 Developing a .NET Client to Access Progress 4GL Web Services

Creating server-side context for a ProcObject (running a

persistent procedure)
Complete the steps that follow to create the context and run the persistent procedure.

To create the context for a ProcObject on the AppServer and run the persistent
procedure:

1. Create the ProcObject by invoking the CreatePO_CustomerOrder( ) method on the

AppObject:

' There is no communication with the WSA at this time

Dim WS_custOrder As OrderService.CustomerOrderObj
WS_custOrder = New OrderService.CustomerOrderObj( )

' Run the persistent procedure CustomerOrder.p on the AppServer

WS_OrderService.CreatePO_CustomerOrder(custNum)

Note: OrderInfoIDValue is automatically inserted in the SOAP request header by the

interface, and the AppObject CustomerOrderIDValue member variable is also
filled in automatically by the interface.

2. Copy the ProcObject ID from the AppObject to the ProcObject:

' Save the ProcObjectID in the ProcObject copy from AppObject

WS_custOrder.CustomerOrderIDValue =
WS_OrderService.CustomerOrderIDValue

A17
OpenEdge Development: Web Services

Running an internal procedure or user-defined function

The following shows how you might invoke the GetTotalOrdersByNumber( ) method on the
ProcObject to run a user-defined function:

' Run the user-defined function GetTotalOrdersByNumber in

CustomerOrder.p on the AppServer
intResult = WS_custOrder.GetTotalOrdersByNumber(1000000.0)

Note: The CustomerOrderIDValue is automatically inserted in the SOAP request header by the
interface.

Methods for running an internal procedure are essentially the same as those for running a
user-defined function.

Creating a SubAppObject
Complete the steps that follow to create a SubAppObject.

To create a SubAppObject:

1. Create the SubAppObject and evoke the CreateAO_Payroll( ) method:

' There is no communication with the WSA at this time

Dim WS_Payroll As OrderService.PayrollObj
WS_Payroll = New OrderService.PayrollObj( )

' Create the SubAppObject

WS_OrderService.CreateAO_Payroll( )

Note: The OrderInfoIDValue will automatically be put into the SOAP request header by
the interface, and the PayrollIDValue AppObject member variable is filled in
automatically by the interface.

A18
 Developing a .NET Client to Access Progress 4GL Web Services

2. Copy the SubAppObject ID from the AppObject to the SubAppObject:

' Save the SubAppObjectID in the SubAppObject copy from AppObject

WS_Payroll.PayrollIDValue =
WS_OrderService.PayrollIDValue

Releasing an object
For releasing an object:

Every Open Client object except for a session-free AppObject has a release method.

The syntax is the same for all objects, as in the following example that releases the
CustomerOrder object, which happens to be a ProcObject:

' Tell the AppServer to release the Persistent Proc

If Not (WS_custOrder.CustomerOrderIDValue Is Nothing) Then
WS_custOrder.Release_CustomerOrder( )
WS_custOrder.CustomerOrderIDValue = Nothing
End If

Running a procedure that passes a TABLE parameter

This example shows how you might invoke a method that passes a TABLE parameter, by calling
the sample method, GetOrderDetails( ):

' Run the internal procedure GetOrderDetails in CustomerOrder.p.

OUTPUT parameter is the OrderDetails TEMP-TABLE
Dim WS_OrderDetails(-1) As OrderService.OrderDetailsRow
WS_custOrder.GetOrderDetails(WS_OrderDetails)

Note: The CustomerOrderIDValue is automatically inserted in the SOAP request header by the
interface.

A19
OpenEdge Development: Web Services

Processing the data from a TABLE parameter

This example shows how you might process data from a TABLE parameter:

' Loop through the rows to obtain some of the column values
Dim i As Integer
Dim OrderNum As Integer
Dim OrderStatus As String
Dim TotalDollars As Decimal

For i = 0 To WS_OrderDetails.Length - 1
OrderNum = WS_OrderDetails(i).OrderNum
OrderStatus = WS_OrderDetails(i).OrderStatus
TotalDollars = WS_OrderDetails(i).TotalDollars
Next i

Running a procedure that passes a TABLE-HANDLE

parameter
This example shows how you might invoke a method on a Document/Literal Web service that
takes a TABLE-HANDLE parameter, by calling the sample method, DynTT( ):

Imports System.Xml
. . .

Dim dynTTEl as XmlElement

' Code to create XML document representing dynTTEl goes here

' Run the non-persistent procedure DynTT.p.

INPUT-OUTPUT parameter is a TABLE-HANDLE
wsObj.DynTT(dynTTEl)

' Code to process the output TABLE-HANDLE from DynTT.p goes here

A20
 Developing a .NET Client to Access Progress 4GL Web Services

Preparing the schema and data for an input

TABLE-HANDLE parameter
This example shows how you might prepare the schema and data for an input TABLE-HANDLE
parameter by building up the XML element nodes for the SOAP message from existing XML
Schema and XML data files:

Dim schemaDoc As XmlDocument = New XmlDocument( )

Dim dataDoc As XmlDocument = New XmlDocument( )
Dim dataSetDoc As XmlDocument = New XmlDocument( )
Dim root As XmlElement
Dim schemaNode As XmlNode
Dim dataNode As XmlNode

' Load XML Schema(.xsd) and Data(.xml) files into XmlDocuments

schemaDoc.Load("ttEmp.xsd")
dataDoc.Load("empData.xml")

' Load the outer element into the dataSetDoc XmlDocument

dataSetDoc.LoadXml("<DataSet></DataSet>")
root = dataSetDoc.DocumentElement
root.SetAttribute("xmlns", "")

' Insert schema and data nodes as children of the dataSetDoc root node
schemaNode = dataSetDoc.ImportNode(schemaDoc.DocumentElement, True)
dataNode = dataSetDoc.ImportNode(dataDoc.DocumentElement, True)

root.AppendChild(schemaNode)
root.AppendChild(dataNode)

dynTTEl = dataSetDoc.DocumentElement( )

A21
OpenEdge Development: Web Services

Processing the schema and data for an output

TABLE-HANDLE parameter
This example shows how you might process the data from an output TABLE-HANDLE parameter
by walking the output XML Schema and XML data to create a .NET DataSet and bind the
DataSet to a .NET DataGrid:

Dim schemaEl As XmlElement

Dim dataEl As XmlElement
Dim node As XmlNode
Dim type As XmlNodeType
...

' Extract the schema and data elements from the output
schemaEl = Nothing
dataEl = Nothing

For i = 0 To dynTTEl.ChildNodes.Count - 1
node = dynTTEl.ChildNodes( i )
type = node.NodeType
If type = System.Xml.XmlNodeType.Element Then
If schemaEl Is Nothing Then
schemaEl = node
ElseIf dataEl Is Nothing Then
dataEl = node
Else
Too many elements, something is wrong
End If
End If
Next i

' Load schema and data into a System.Data.DataSet, then bind to a

System.Windows.Forms.DataGrid
mySchemaReader = New System.Xml.XmlNodeReader(schemaEl)
myDataReader = New System.Xml.XmlNodeReader(dataEl)

myDataSet.ReadXmlSchema(mySchemaReader)
myDataSet.ReadXml(myDataReader)

' Load myDataGrid with the output from DynTT

myDataGrid.SetDataBinding(myDataSet, "Item")

A22
 Developing a .NET Client to Access Progress 4GL Web Services

Extra processing required for RPC/Encoded

TABLE-HANDLE parameters
For RPC/Encoded Web services, a TABLE-HANDLE parameter is a System.Array containing the
<DataSet> System.Xml.XmlElement. Process the array as follows for:

Input Create the System.Array with the XmlElement containing schema and data.

Output Extract the last element of the System.Array, which is the XmlElement
containing schema and data.

The following example shows the outlines of both procedures:

This code goes after the code that creates XML document representing dynTTEl
and before calling the method taking the TABLE-HANDLE parameter
. . .
Create a System.Array containing dynTTEl
dynTTArray = System.Array.CreateInstance(dynTTEl.GetType, 1)
dynTTArray(0) = dynTTEl

Run DynTT.p
wsObj.DynTT(dynTTArray)

' Process the output TABLE-HANDLE from DynTT.p

dynTTEl = dynTTArray(dynTTArray.Length - 1)
Continue with the rest of the code for processing the output
. . .

A23
OpenEdge Development: Web Services

Handling errors on the client

To handle a SOAP fault in a VB.NET client, catch the SoapException and parse it, as follows:

Try
' Code to access the Web service
...
Catch soapEx As System.Web.Services.Protocols.SoapException
Dim detail As String, reqId As String
detail = parseSoapException(soapEx.Detail, reqId)
MsgBox(detail, MsgBoxStyle.Critical, soapEx.Message)
End Try

Caution: In any catch block where you exit the program, you must release all Web service
objects you created in the program.

The parseSoapException( ) method in this example is a client function provided in the .NET
samples installed with OpenEdge (see Chapter 6, Sample Progress 4GL Web Services and
Client Applications). It parses the detail error information from the SOAP fault message.

You can also use the Microsoft SOAP Toolkit to assist in debugging SOAP fault messages. For
more information, see Chapter 7, Testing and Debugging Progress 4GL Web Services.

Compiling and running the .NET client application

For .NET this is straightforward: .NET compiles the application automatically when you run it
from Visual Studio .NET.

A24
 Developing a .NET Client to Access Progress 4GL Web Services

Learning more about writing .NET clients

For more information on writing .NET clients, review the .NET samples provided with the
OpenEdge, which highlight 4GL Web service functionality (see Chapter 6, Sample Progress
4GL Web Services and Client Applications) and see the following sources:

General information on Microsoft .NET at the following URL:

http://www.microsoft.com/net/default.asp

Information on Microsoft Visual Studio .NET at the following URL:

http://www.microsoft.com/vstudio/nextgen/default.asp

Information from other .NET developers at the Framework Community Web site:

http://www.gotdotnet.com

A25
OpenEdge Development: Web Services

A26
 B
Developing a Java Client to Access
Progress 4GL Web Services

This appendix describes the basic tasks to develop Java client applications that use a Progress
4GL Web service, as described in the following sections:

Using Java client toolkits

Java sample Web service specifications

Creating Java Axis client interface objects

Developing the Axis client application

Learning more about writing Java clients

OpenEdge Development: Web Services

Using Java client toolkits

Most major Java software vendors are developing Java client toolkits to support Web service
client development. In general, these toolkits include features that help automate the generation
of client interfaces to Web services and offer other development aids, such as SOAP viewers
and other debugging aids. Among the more common Java client toolkits are the following:

Axis from Apache

XMLbus from Iona

JAX-RPC

The client development samples in the remainder of this section are provided using Axis as the
client-side Web services toolkit.

Also, if you are developing a secure Web service that relies on the secure socket layer (SSL)
managed by the Web server, OpenEdge provides a utility (procertm) to manage the digital
certificates for a Java client. This same utility is used to manage digital certificates for Java
Open Clients. For more information on this utility, see OpenEdge Development: Java Open
Clients.

B2
 Developing a Java Client to Access Progress 4GL Web Services

Java sample Web service specifications

Table B1 describes the specifications for a sample Web service and interface used to illustrate
client development with Axis.

Table B1: Java sample Web service specifications

Property or
component Value or name Object type

Web service OrderService

URL http://servicehost:80/wsa/wsa1

Session model Managed

TargetNamespace urn:OrderSvc:OrderInfo

WSDL objects OrderInfoObj AppObject

CustomerOrderObj ProcObject

OrderInfoID AppObject ID

CustomerOrderID ProcObject ID

OrderDetailsRow Temp-table OrderDetails

B3
OpenEdge Development: Web Services

Creating Java Axis client interface objects

Axis provides tools that help to automate the creation of the objects for a client interface. The
following sections describe these tools and the generated interface objects:

Generating client interface objects

Proxy directory structure

Proxy classes

Java data type mapping

Output parameters

Progress 4GL unknown values

TABLE (static temp-table) parameters

TABLE-HANDLE (dynamic temp-table) parameters

Sample Java prototypes for common object methods

Sample Progress 4GL and Java interface method prototypes

To create client interfaces and client applications to access 4GL Web services, you must have
Java SDK 1.3 or later and the Axis Toolkit. For more information, see the README files in the
Java samples described in Chapter 6, Sample Progress 4GL Web Services and Client
Applications.

B4
 Developing a Java Client to Access Progress 4GL Web Services

Generating client interface objects

You can generate client interface objects (classes) for the interface using the following
command, where wsdlFileRef is a pointer to the WSDL file:

java org.apache.axis.wsdl.WSDL2Java wsdlFileRef

Note: Set the Classpath as specified in the Axis Users Guide.

The value of wsdlFileRef can be:

A local reference, for example:

C:\OrderInfo.wsdl

A URL to the WSDL, for example:

http://servicehost:80/wsa/wsa1/wsdl?targetURI=OrderInfo

Each generated interface object is a class for an Open Client object an/ or some other component
of the WSDL that is represented as an object in the Java interface.

Proxy directory structure

The Axis WSDL2Java command creates the client interface objects in Java packages that reflect
the TargetNamespace value specified in the WSDL. Thus, for example, suppose the WSDL
specifies a TargetNamespace as follows:

TargetNamespace="urn:OrderSvc:OrderInfo"

The relative directory structure created from this namespace is the following:

OrderSvc/OrderInfo

B5
OpenEdge Development: Web Services

Proxy classes
The Axis interface generator for this sample provides the classes for the Web service
components shown in Table B2. This represents one class for each specified Web service
(WSDL) object or component.

Note: There are no Java objects created for object IDs.

Table B2: Proxy classes for a sample Java Axis client (RPC/Encoded)

Web service
components Class Path

Each Open OrderInfoObjStub .../OrderInfo/

Client object. OrderInfoObjStub.java

CustomerOrderObjStub .../OrderInfo/CustomerOrder
/CustomerOrderObjStub.java

One service OrderInfoServiceLocator .../OrderInfo/

locator object OrderInfoServiceLocator.java
(Provides the
URL to the
WSA).

Each temp-table OrderDetailsRow .../CustomerOrder/

input parameter. OrderDetailsRow.java

Two holder ArrayofOrderDetailsRowHolder .../CustomerOrder/

classes for each holders/
output ArrayofOrderDetailsRowHolder.
temp-table. java

OrderDetailsRowHolder .../CustomerOrder/
holders/OrderDetailsRowHolder
.java

SOAP fault FaultDetail servicehost/FaultDetail.java

detail object.

B6
 Developing a Java Client to Access Progress 4GL Web Services

Java data type mapping

Table B3 lists the data type mappings for parameters between the Progress 4GL and Java.

Table B3: Supported Java data types

Progress 4GL data type Java data type

CHARACTER String

COM-HANDLE long

DATE java.util.Date

DECIMAL java.math.BigDecimal

INTEGER (32 bit) int

LOGICAL boolean

MEMPTR byte[]

RAW byte[]

RECID (32 or 64 bit) long

ROWID byte[]

TABLE (static temp-table) Object (for every TABLE)

TABLE-HANDLE (dynamic temp-table) TableHandleParam Object

WIDGET-HANDLE long

Output parameters
The Java language does not provide a mechanism to pass output parameters. To work around
this, client interfaces use the Java standard of representing output parameters as holder classes,
which provide the reference space to return output parameter values. Axis provides holder
classes for all standard Java data types. The Axis interface generator (WSDL2Java) creates
holder classes for output TABLE and TABLE-HANDLE parameters. For more information on Axis
support for holder classes, see the Axis Users Guide.

B7
OpenEdge Development: Web Services

Progress 4GL unknown values

The Unknown value (?) appears as a null value in Java. For any Progress user-defined function
that returns the Unknown value as a primitive Java data type, this raises an exception in the
interface method that calls this function. The client must compensate for this by catching the
exception, as follows:

catch (NullPointerException con)

{
System.err.println("The total Orders are: 0 (unknown)");
}

TABLE (static temp-table) parameters

For TABLE parameters, client interfaces:

Contain a row object for any input parameter, for example:

public class OrderDetailsRow

Represent an input TABLE parameter as an array of row objects.

Represent output TABLE parameters using an array holder class and a row holder class for
the row objects, as in the following RPC/Encoded example:

public class ArrayofOrderDetailsRowHolder

public class OrderDetailsRowHolder

B8
 Developing a Java Client to Access Progress 4GL Web Services

Table B4 lists the data type mappings for TABLE columns between the Progress 4GL and Java.

Table B4: Java data types for TABLE (static temp-table) parameter
columns

Progress 4GL data type Java data type

CHARACTER String

COM-HANDLE long

DATE java.util.Date

DECIMAL java.math.BigDecimal

INTEGER (32 bit) int

LOGICAL boolean

RAW byte[]

RECID (32 or 64 bit) long

ROWID byte[]

WIDGET-HANDLE long

B9
OpenEdge Development: Web Services

TABLE-HANDLE (dynamic temp-table) parameters

For TABLE-HANDLE parameters:

For every Web service object containing a method that passes a TABLE-HANDLE parameter,
the WSDL contains a <TableHandleParam> element defined as a <complexType>
definition. Therefore, a TableHandleParam class is created for every client object which
contains a method that passes a TABLE-HANDLE parameter, for example:

public class TableHandleParam {

private org.apache.axis.message.MessageElement [ ] _any;
...}

For input TABLE-HANDLE parameters, the client must create a TableHandleParam object,
consisting of a MessageElement array containing the XML Schema and data for the
TABLE-HANDLE. For output TABLE-HANDLE parameters, the client must parse the XML
Schema and data in the MessageElement array.

Table B5 lists the typical data type mappings for TABLE-HANDLE columns between Progress
4GL and Java.

Table B5: Java data types for TABLE-HANDLE (dynamic temp-table)

parameter columns

Progress 4GL data type Java data type

CHARACTER String

DATE java.util.GregorianCalendar

DECIMAL java.math.BigDecimal

INTEGER (32 bit) int

LOGICAL boolean

RAW byte[]

B10
 Developing a Java Client to Access Progress 4GL Web Services

Sample Java prototypes for common object methods

This is an example of an AppObject connect method for the session-managed OrderInfo
AppObject as defined for the OrderInfoObjStub class. It makes the logical connection to the
AppServer:

public void connect_OrderInfo

(java.lang.String userID,
java.lang.String password,
java.lang.String appServerInfo)

This is an example of an AppObject release method for the OrderInfo AppObject as defined
for the OrderInfoObjStub class:

public void release_OrderInfo( )

Note: All interface object release methods have a similar definition.

B11
OpenEdge Development: Web Services

Sample Progress 4GL and Java interface method

prototypes
The following examples show Progress 4GL prototypes and how they map to equivalent Java
interface method prototypes:

Non-persistent procedure

Progress 4GL:

/* FindCustomerByNum.p */

DEFINE INPUT PARAMETER CustomerNumber AS INTEGER.

DEFINE OUTPUT PARAMETER CustomerName AS CHARACTER.

Java OrderInfoObjStub method:

public void findCustomerByNum

(int customerNumber,
javax.xml.rpc.holder.StringHolder customerName)

Note: The output parameter holder class shown in bold is provided by Axis.

Persistent procedure

Progress 4GL:

/* CustomerOrder.p */

DEFINE INPUT PARAMETER CustNum AS INTEGER.

Note: This procedure returns a value using the 4GL RETURN statement.

B12
 Developing a Java Client to Access Progress 4GL Web Services

Java OrderInfoObjStub method:

public String createPO_CustomerOrder (int custNum)

User-defined function

Progress 4GL:

/* CustomerOrder.p */

FUNCTION GetTotalOrdersByNumber RETURN INTEGER

(Threshold AS DECIMAL):

Java CustomerOrderObjStub method:

public int getTotalOrdersByNumber

(java.math.BigDecimal threshold)

Internal procedure using a temp-table

Progress 4GL:

/* CustomerOrder.p */

PROCEDURE GetOrderDetails :
DEFINE OUTPUT PARAMETER TABLE FOR OrderDetails.

Java CustomerOrderObjStub method:

public void getOrderDetails

(OrderSvc.OrderInfo.CustomerOrder.
holders.ArrayOfOrderDetailsRowHolder orderDetails)

Note: The output parameter holder class shown in bold is generated by the Axis
WSDL2Java command.

B13
OpenEdge Development: Web Services

Temp-table definition

Progress 4GL:

/* CustomerOrder.p */

DEFINE TEMP-TABLE OrderDetails

FIELD OrderNum LIKE Order.OrderNum
FIELD SalesRep LIKE Order.SalesRep
FIELD OrderDate LIKE Order.OrderDate
FIELD ShipDate LIKE Order.ShipDate
FIELD TotalDollars AS DECIMAL
FIELD OrderStatus LIKE Order.OrderStatus.

Java OrderDetailsRow object:

public class OrderDetailsRow {

private java.lang.Integer orderNum;
private java.lang.String salesRep;
private java.util.Date orderDate;
private java.util.Date shipDate;
private java.math.BigDecimal totalDollars;
private java.lang.String orderStatus;
...}

External procedure passing a TABLE-HANDLE

Progress 4GL:

/* DynTT.p */

DEFINE INPUT-OUTPUT PARAMETER TABLE-HANDLE ttHandle.

Java DynTTObjStub method:

public void DynTT

(DynTTSrvc.DynTT.holders.TableHandleParamHolder ttHandle)

B14
 Developing a Java Client to Access Progress 4GL Web Services

Developing the Axis client application

Once you have generated the client interface classes for the Web service, some typical tasks for
developing a Java Axis client include:

Setting up the Web service objects

Using the sample PscObjectIDHandler and HandlerControlBlock classes

Setting up the PscObjectIDHandler objects

Connecting to a Web service

Running a non-persistent (external) procedure

Creating server-side context for a ProcObject (running a persistent procedure)

Running an internal procedure or user-defined function

Running an internal procedure that passes a TABLE parameter

Processing the data from a TABLE parameter

Running a procedure that passes a TABLE-HANDLE parameter

Using sample helper classes to manage TABLE-HANDLE parameters

Preparing the schema and data for input TABLE-HANDLE parameters

Processing the schema and data for output TABLE-HANDLE parameters

Releasing an object

Handling errors on the client

Notes: For more information on the concepts and procedures underlying these tasks, see
Chapter 4, General Client Programming Model for Progress 4GL Web Services and
Chapter 5, Sample Code with SOAP Messages for Progress 4GL Web Services.

OpenEdge comes installed with complete sample client applications that access 4GL
Web services. For more information, see Chapter 6, Sample Progress 4GL Web
Services and Client Applications.

B15
OpenEdge Development: Web Services

Setting up the Web service objects

Complete the steps that follow to set up the objects.

To set up the session-managed Web service objects for your client:

1. Create the Web service locator. For the sample, you generate the OrderInfo client's
service object that manages the connection with the WSA:

OrderInfoService service = new OrderInfoServiceLocator( );

2. Instantiate the client objects that do the marshalling and unmarshalling of SOAP and
HTTP messages for methods on the OrderInfo object. For example, you might execute
the following method for the sample:

OrderInfoObjStub orderInfo =
(OrderInfoObjStub)service.getOrderInfoObj(connectURL);

3. Instantiate the client objects that do the marshalling and unmarshalling of SOAP and
HTTP messages for methods on the CustomerOrder object. For example you might
execute the following method for the sample:

CustomerOrderObjStub custOrder =
(CustomerOrderObjStub)service.getCustomerOrderObj(connectURL);

B16
 Developing a Java Client to Access Progress 4GL Web Services

Using the sample PscObjectIDHandler and

HandlerControlBlock classes
Axis is a JAX-RPC-based Web service toolkit. JAX-RPC-based Web Service toolkits provide
the ability to examine, modify, and insert information into SOAP requests using handler objects
that conform to a defined interface (javax.xml.rpc.handler.GenericHandler). Axis client
interface classes do not give programmatic access to SOAP request and response headers;
therefore a client application must create and use one of these handlers to access these SOAP
message headers.

A client application defines one or more of these handlers and binds them to a <portType>
(Open Client object) defined in the Web service's WSDL document. Each time a SOAP request
or response message is handled by an object, the appropriate handlers bound to the object are
called and allowed access to the request or response message. For more information, see the
source code modules for the Java samples described in Chapter 6, Sample Progress 4GL Web
Services and Client Applications.

OpenEdge provides a sample handler class (PscObjectIDHandler) to manage object IDs. This
PscObjectIDHandler class is one possible implementation of a JAX-RPC handler. It provides
two essential pieces of functionality:

1. It is invoked for each incoming SOAP response for the <portType> element (Open Client
object type) where it is bound. When invoked, it scans the SOAP response header for an
object ID that corresponds to an Open Client object name. If it finds one of these Open
Client object IDs, it extracts the object ID value and stores it along with the object name.
The client application or the handler can then access this stored object ID to insert it into
a subsequent SOAP request header. If a handler does not already have an object ID value
reserved to insert in a given SOAP request header, it automatically uses the first object ID
that it stores.

2. It is invoked for each outgoing SOAP request for the <portType> element (Open Client
object type) where it is bound. It then inserts a SOAP header containing the object ID for
the Open Client object name that corresponds to the <portType> element where it is
bound. If an object ID value does not exist for the Open Client object name, the handler
does not insert a SOAP header into the request.

Along with the PscObjectIDHandler class provided with the Progress 4GL Web services
samples is a companion class, HandlerControlBlock. This class allows the Web service client
application to access object ID values stored in a PscObjectIDHandler object. It also gives the
application the ability to control the Object ID value the PscObjectIDHandler inserts into
SOAP request headers. For each PscObjectIDHandler object instance, there is a companion
HandlerControlBlock created and associated with it.

B17
OpenEdge Development: Web Services

Setting up the PscObjectIDHandler objects

After you have completed the Web service object setup (see the Setting up the Web service
objects section on page B16) that creates the OrderInfoObjStub and CustomerOrderObjStub
objects, you can create and register the PscObjectIDHandler and HandlerControlBlock
objects for both the OrderInfo and CustomerOrder Open Client objects.

The following steps create and register a unique handler for each Open Client object so it can
automatically insert its corresponding object ID into outgoing SOAP requests without
intervention by the client application.

To create and register a unique handler for each Open Client object:

1. Set the <portType> element name specified in the WSDL for the OrderInfoObjStub so a
PscObjectIDHandler can be bound to it:

orderInfo.setPortName("OrderInfoPort");

Note: Apache Axis does not automatically obtain the <portType> element name from the
WSDL document when it generates the client interface classes.

2. Set the <portType> element name specified in the WSDL for the CustomerOrderObjStub
so a PscObjectIDHandler can be bound to it:

custOrder.setPortName("CustomerOrderPort");

Note: Apache Axis does not automatically obtain the <portType> element name from the
WSDL document when it generates the client interface classes.

3. Declare the Open Client object names that the PscObjectIDHandler objects will use to
scan for object IDs in SOAP response headers returned from the WSA:

String[] orderInfoObjectNames =
new String[] { "OrderInfo", "CustomerOrder" };

B18
 Developing a Java Client to Access Progress 4GL Web Services

Note: Both the "OrderInfo" and "CustomerOrder" object names are included because
the object IDs for both are returned from factory methods contained in the
OrderInfo AppObject.

4. Call the PscObjectIDHandler built-in factory method to create and register a

PscObjectIDHandler object for the "OrderInfoPort" <portType> element. The handler
is set to scan for and record the object ID values for the OrderInfo and CustomerOrder
Open Client objects. This automatically creates and binds a HandlerControlBlock object
to the PscObjectIDHandler object, returning a reference for it to the client application:

HandlerControlBlock orderInfoControlBlock = null;

orderInfoControlBlock =
PscObjectIDHandler.registerObjectIDHandler(
service,
orderInfoObjectNames,
"",
"OrderInfoPort",
debugHandler );

5. Call the PscObjectIDHandler built-in factory method to create and register a

PscObjectIDHandler object for the "CustomerOrderPort" <portType> element. The
handler is set to scan for and record the object ID values for the OrderInfo and
CustomerOrder Open Client objects. This automatically creates and binds a
HandlerControlBlock object to the PscObjectIDHandler object, returning a reference for
it to the client application:

HandlerControlBlock custOrderControlBlock = null;

custOrderControlBlock =
PscObjectIDHandler.registerObjectIDHandler(
service,
orderInfoObjectNames,
"",
"CustomerOrderPort",
debugHandler );

B19
OpenEdge Development: Web Services

Connecting to a Web service

For session-managed Web services, make a logical connection to the AppObject and save its
object ID for later use:

orderInfo.connect_OrderInfo("", "", "");

if (null == orderInfoControlBlock.getObjectNameID("OrderInfo"))
{
throw new Exception("No header returned from a connect operation to
OrderInfo.");
}

Note: The PscObjectIDHandler registered for the OrderInfoPort type object

(OrderInfoObjStub) automatically looks for and stores the object ID value returned for
the OrderInfoObjStub object if the connect_OrderInfo( ) method is successful.
Because this is the first object ID that the handler stores, it is automatically set to be
inserted as the object ID value in the SOAP header for each SOAP request sent to the
WSA for the OrderInfoObjStub object.

Caution: Now that the Web service is connected, remember to release the AppObject when it
is no longer needed.

Running a non-persistent (external) procedure

The following example shows how you might invoke the sample FindCustomerByNum( )
method:

// Send a request to the AppServer to get the Customer Name

StringHolder custNameHolder = new StringHolder( );

orderInfo.findCustomerByNum(3, custNameHolder);
System.out.println("Customer #3's name is " + custNameHolder.value);

The object ID handler automatically inserts the orderInfo object ID into the SOAP request
header.

StringHolder is one of several holder classes defined by Axis.

B20
 Developing a Java Client to Access Progress 4GL Web Services

Creating server-side context for a ProcObject (running a

persistent procedure)
Complete the steps that follow to create the server-side context for the ProcObject.

To create the context for a ProcObject on the AppServer:

1. Run the persistent procedure, creating the ProcObject:

orderInfo.createPO_CustomerOrder(3);

Caution: Now that the ProcObject is created, remember to release the object later, when
it is no longer needed.

2. Check to see if an object ID was returned:

if (null == orderInfoControlBlock.getObjectNameID("CustomerOrder"))
{
throw new Exception("No header returned from a create operation for
CustomerOrder.");
}

3. The CustomerOrderObjStub object is created from a factory method included in the

OrderInfoObjStub object. Therefore, the PscObjectIDHandler bound to the
OrderInfoObjStub locates and stores the object ID value for the CustomerOrderObjStub
object in the OrderInfoObjStub object. Thus the client application must obtain (export)
the object ID value for the CustomerOrderObjStub from the OrderInfoObjStub handler
and insert (import) it into the CustomerOrderObjStub handler:

custOrderControlBlock.importObjectID("CustomerOrder",
orderInfoControlBlock.exportObjectID("CustomerOrder"));

This enables the CustomerOrderObjStub handler to automatically insert the

CustomerOrder object ID into the headers for all SOAP requests made on the
CustomerOrderObjStub object.

B21
OpenEdge Development: Web Services

4. The client application must then remove (release) the object ID value for the
CustomerOrderObjStub object from the OrderInfoObjStub handler because it is no
longer needed by that handler:

orderInfoControlBlock.releaseObjectNameID("CustomerOrder");

Running an internal procedure or user-defined function

The following sample shows how you might invoke the GetTotalOrdersByNumber( ) method:

try
{
int orderCount = custOrder.getTotalOrdersByNumber(new BigDecimal(5.0));
System.out.println("The total Customer Orders are: " + orderCount);
}
catch (NullPointer Exception e)
{
...
}

Note: The object ID handler automatically inserts the custOrder object ID into the SOAP
request header.

B22
 Developing a Java Client to Access Progress 4GL Web Services

Running an internal procedure that passes a TABLE

parameter
This example shows how you might invoke a method that takes a TABLE parameter, by calling
the sample method, GetOrderDetails( ):

// Create the holder for the TEMP-TABLE OrderDetails

ArrayOfOrderDetailsRowHolder orderDetailsHolder =
new ArrayOfOrderDetailsRowHolder(null);

// Let's now ask the WebService for the order details of the
// current customer

custOrder.getOrderDetails(orderDetailsHolder);

Note: The object ID handler automatically inserts the custOrder object ID into the SOAP
request header.

Processing the data from a TABLE parameter

This example shows how you might process data from a TABLE parameter:

// Loop through the rows and print some of the column values

OrderDetailsRow[] rows = (OrderDetailsRow[]) orderDetailsHolder.value;

// Print out some labels

System.out.println("Customer's Order Details listed below:");
System.out.println("Order# " + "Order Status " + "Total Dollars");

// Now print out all the rows

for (int j = 0; j < rows.length; j++)
{
OrderDetailsRow thisRow = rows[j];
System.out.println(thisRow.getOrderNum( ) +
thisRow.getOrderStatus( ) +
thisRow.getTotalDollars( ));
}

B23
OpenEdge Development: Web Services

Running a procedure that passes a TABLE-HANDLE

parameter
This example shows how you might invoke a method that takes a TABLE-HANDLE parameter, by
calling the sample method, dynTT( ):

import DynTTSrvc.*;
import DynTTSrvc.DynTT.*;
import DynTTSrvc.DynTT.holders.*;
import org.apache.axis.message.MessageElement;
import org.w3c.dom.Element;
...

// Prepare the Schema and Data for the Input TABLE-HANDLE Parameter
// Create the XML Schema and data for the dynamic TEMP-TABLE.
// Then create the TableHandleParam object, ttHandle
...
// Create the holder for the INPUT-OUTPUT TableHandleParam parameter, ttHandle
TableHandleParamHolder ttHolder = new TableHandleParamHolder( );
ttHolder.value = ttHandle;

// Call DynTT.p, passing the Input-Output TABLE-HANDLE

dynTTObj.dynTT(ttHolder);

// Process the schema and data for the Output TABLE-HANDLE

...

B24
 Developing a Java Client to Access Progress 4GL Web Services

Using sample helper classes to manage TABLE-HANDLE

parameters
Progress 4GL Web services sample applications come installed with a set of helper classes that
you can use to manipulate TABLE-HANDLE parameters:

ColumnMetaData.java Represents the schema of a column:

public class ColumnMetaData {

protected String name;
protected int type;
protected int extent;
...}

RowSet.java Represents the XML Schema and data for a TABLE-HANDLE parameter:

public class RowSet {

private Vector m_rows;
private ColumnMetaData[ ] m_schema;
...}

In the RowSet class, m_rows is a Vector of rows, each of which is a Vector of column data.
Each column datum is a Java object appropriate for the column data type. The m_schema
variable is the ColumnMetaData array representing the schema for the temp-table.

SchemaParser.java Parses the <schema> element from a SOAP response message and
creates a ColumnMetaData array for the RowSet class:

public class SchemaParser

{
protected ColumnMetaData[ ] m_schema;
...}

B25
OpenEdge Development: Web Services

Preparing the schema and data for input TABLE-HANDLE

parameters
This example shows how you might prepare the schema and data for an input TABLE-HANDLE
parameter using the helper classes described in the previous section:

// Build up a simple RowSet object representing the input dynamic TEMP-TABLE.

RowSet rsIn = new RowSet( );

// Create the MetaData, consisting of String and Integer columns

ColumnMetaData[] schema = new ColumnMetaData[2];
ColumnMetaData firstCol = new ColumnMetaData("Name",
ColumnMetaData.CHAR_TYPE, 0);
ColumnMetaData secondCol = new ColumnMetaData("Number",
ColumnMetaData.INT_TYPE, 0);
schema[0] = firstCol;
schema[1] = secondCol;

rsIn.setSchema(schema);

// Create a data row and add to the RowSet

Vector row;
row = new Vector( );
row.addElement(new String("Sally Jones"));
row.addElement(new Integer(1));
rsIn.addRow(row);

// Convert the RowSet into a TableHandleParam Object,

// the input parameter for DynTT.p

// Get the RowSet as a DOM Element. This element has two

// children, a <schema> element and a <Data> element
Element dataSetIn = rsIn.getDataSetAsDom( );

// Create a MessageElement containing the DataSet

MessageElement dataSetMsgEl = new MessageElement(dataSetIn);

// Place the DataSet MessageElement into the message element array

// and create the TableHandleParam object
MessageElement msgArrayIn[] = new MessageElement[1];
msgArrayIn[0] = dataSetMsgEl;

// Create the TableHandleParam object, ttHandle, representing the

// dynamic TABLE-HANDLE parameter
TableHandleParam ttHandle = new TableHandleParam( );
ttHandle .set_any(msgArrayIn);

...

B26
 Developing a Java Client to Access Progress 4GL Web Services

Processing the schema and data for output

TABLE-HANDLE parameters
This example shows how you might process the data from an output TABLE-HANDLE parameter
by using the sample TABLE-HANDLE helper classes:

// Process the Output TABLE-HANDLE parameter

ttHandle = ttHolder.value;

MessageElement [] msgArrayOut = ttHandle.get_any( );

// msgArrayOut has one entry, the DataSet

// Get the DOM representation of the MessageElement
Element dataSetOut = msgArrayOut[0].getAsDOM( );

// Create a new RowSet Object based on the DataSet

RowSet rsOut = new RowSet( );

/*
Call the buildRowSet method on the RowSet object.
buildRowSet creates a SchemaParser object to parse the <schema> element of the
dataSetOut and creates the m_schema ColumnMetaData[ ] array representing the
schema. buildRowSet then parses the <Data> element and creates the m_rows
Vector
representing the data.
*/
rsOut.buildRowSet(dataSetOut);

// print out the data for the dynamic temp-table to the console
rsOut.printData( );

B27
OpenEdge Development: Web Services

Releasing an object
The following steps use the object ID handler (PscObjectIDHandler) to manage the object IDs
of the two objects about to be released.

To release the CustomerOrder ProcObject:

1. Release the logical connection. For example, to release the CustomerOrder ProcObject,
call this method:

custOrder.release_CustomerOrder( );

2. Remove (release) the ProcObject ID from the object ID handler, so this ProcObject ID
cannot be used again:

custOrderControlBlock.releaseObjectNameID("CustomerOrder");

To release the OrderInfo AppObject:

1. Release the logical connection for the OrderInfo AppObject:

orderInfo.release_OrderInfo( );

2. Remove (release) the AppObject ID from the object ID handler, so this AppObject ID
cannot be used again:

orderInfoControlBlock.releaseObjectNameID("OrderInfo");

B28
 Developing a Java Client to Access Progress 4GL Web Services

Handling errors on the client

To understand how to handle SOAP fault messages returned by the WSA, first note that the
<FaultDetail> element is described in the interface Java class,
servicehost/FaultDetail.java:

public class FaultDetail {

java.lang.String errorMessage;
java.lang.String requestID;
...
}

Place a try...catch block around any code that accesses the Web server and catch the
AxisFault exception.

B29
OpenEdge Development: Web Services

This is an example of Axis client code to catch a SOAP fault (an AxisFault exception):

try
{
// code to Access the Web Service
}
catch (AxisFault e)
{
// Get the (single) child element of the SOAP Fault <detail> element,
// the <FaultDetail> element.

Element[] faultDetails = e.getFaultDetails( );

if (faultDetails.length > 0)
{
// Now get the contents of the <FaultDetail> element,
// <errorMessage> and <requestID>.

Node faultDetailElem = faultDetails[0].getFirstChild( );

String detailErrorMsg =
faultDetailElem.getFirstChild( ).getNodeValue( );
System.err.println("Exception errorMessage: " + detailErrorMsg);

Node requestIDElem = faultDetailElem.getNextSibling( );

String requestID = requestIDElem.getFirstChild( ).getNodeValue( );

System.err.println("Exception requestID : " + requestID);

}
}

Caution: In any catch block where you exit the program, you must release all Web service
objects you created in the program.

B30
 Developing a Java Client to Access Progress 4GL Web Services

Compiling and running the client application

Compile and run the client application as described below.

To compile and run the application:

1. Set up your Classpath as specified in the Axis Users Guide. Make sure you put the path
to your client interface on the Classpath.

2. Compile both the interface and your client application classes using the Java compiler.

3. Run the application, as usual, in the JVM.

Learning more about writing Java clients

For more information on writing Java clients, see:

The sample Progress 4GL Web services and client code provided with OpenEdge.

The following URL:

http://java.sun.com

B31
OpenEdge Development: Web Services

B32
 C
Progress 4GL Elements for Accessing
Web Services

Many elements of the Progress 4GL support access to Web services, including some that are
extensions to other functionality and some that are unique for interacting with Web services.
The following sections describe all of these elements, including:

Handles for accessing a Web service

Statements for accessing Web services

Attributes, methods, and events for accessing Web services

OpenEdge Development: Web Services

Handles for accessing a Web service

Table C1 lists the 4GL handles that are either valid only for accessing a Web service or have
special application in Web service client programming. The remaining chapters explain how to
use these 4GL elements.

Table C1: Handles to access Web services (1 of 2)

4GL handle Description

Asynchronous request object handle A type of handle that maintains the status of an
asynchronous request in a 4GL client application.
This handle provides methods and attributes that
allow you to check the status of an asynchronous
Web service operation.

ERROR-STATUS system handle Provides access to the error information returned

from processing a Web service request. If the error
resulted from a SOAP fault, the SOAP fault is
returned as a SOAP fault object.

Procedure object handle A handle to a type of procedure object (Web

service procedure object) that provides the
interface to a port type of a Web service. port type
operations are represented as 4GL internal
procedures and user-defined functions within the
procedure object that represents the specified port
type. A single Web service binding supports one
associated port type.

SELF system handle In the context of an asynchronous event procedure,

returns the asynchronous request object handle of
the completed request for which the event
procedure is executing.

Server object handle A handle to a server object that can provide a

logical connection (or binding) to a Web service
from a 4GL client application. The handle
provides methods and attributes that allow you to
logically connect (or bind) the server object to a
Web service and manage the Web service binding.

SESSION system handle Maintains Progress session status, including a list

of all server objects created by the session to bind
Web services.

C2
 Progress 4GL Elements for Accessing Web Services

Table C1: Handles to access Web services (2 of 2)

4GL handle Description

SOAP fault object handle A handle to an object that contains SOAP fault
information for a Web service request. This
system handle provides the SOAP fault object
handle as the value of its ERROR-OBJECT-DETAIL
attribute.

SOAP fault-detail object handle A handle to an object that references any <detail>
element returned in a SOAP fault message
generated for a Web service request. The SOAP
fault object handle provides any SOAP fault-detail
object handle as the value of its
SOAP-FAULT-DETAIL attribute.

SOAP header object handle A handle to an object that contains the SOAP
header for a SOAP request or response message
generated for a Web service operation. This can be
either an existing header from a SOAP response
message, or a newly-created header for a pending
SOAP request message.

SOAP header-entryref object handle A handle to an object that references an entry of a

SOAP header, either an existing entry from the
header of a SOAP response message, or a
newly-created entry for a pending SOAP request
message.

X-document object handle A handle to an XML document object created for

any SOAP message content that you must access
as XML.

X-noderef object handle A handle to any XML element (node object)

within an XML document object that contains
SOAP message content. This allows you to access
the actual text of elements in the XML document
retrieved as X-noderef objects.

C3
OpenEdge Development: Web Services

Statements for accessing Web services

Table C2 lists the 4GL statements that are either valid only for accessing a Web service or have
special application in Web service client programming. The remaining chapters explain how to
use these 4GL elements.

Table C2: Statements to access Web services (1 of 3)

4GL statement Description

CREATE SERVER server-handle Creates a server object and stores a reference to it

in the specified HANDLE variable. You can then
bind (logically connect) the server object to a Web
service using the server handle CONNECT( )
method.

CREATE SOAP-HEADER Creates a SOAP header object used to add a SOAP

header-obj-handle header to a pending SOAP request message
generated by a 4GL Web service invocation.

CREATE SOAP-HEADER-ENTRYREF Creates a SOAP header-entryref object used to add

soap-obj-handle SOAP header entries to an existing SOAP header.

DELETE OBJECT handle Deletes certain objects, including server objects,

procedure objects, SOAP header objects, SOAP
header-entryref objects, and asynchronous request
objects.

DELETE PROCEDURE Deletes the procedure object associated with a

procedure-handle Web service.

FUNCTION operationName Defines a user-defined function prototype to map

[ RETURNS ] dataType a Web service operation as specified by the WSDL
[ ( parameter Analyzer, which determines the need for a
function to return a value.
[
, parameter ] ... ) ]
IN hPortType .

C4
 Progress 4GL Elements for Accessing Web Services

Table C2: Statements to access Web services (2 of 3)

4GL statement Description

return = operationName Invokes a Web service operation defined as a

[ ( parameter user-defined function, where return is a variable
[ , parameter ] ... ) ]. to receive the value of the operation <return>
parameter element, operationName is the name of
the operation as specified in the WSDL file and
whose 4GL prototype is defined using the
FUNCTION statement, and parameter is a 4GL
function parameter as required by the WSDL file
for the operation. The operation can also be
invoked as part of any other 4GL statement that
can invoke a user-defined function.

PROCESS EVENTS Handles any pending PROCEDURE-COMPLETE events

for asynchronous requests by triggering execution
of the event procedures for all completed
asynchronous requests. You can also use any
blocking I/O statement, such as the WAIT-FOR
statement, to handle these events.

RUN portTypeName Creates and associates a procedure object with a

[ SET hPortType ] ON SERVER Web service, where portTypeName is the name of
server-handle [ NO-ERROR ]. a Web service port type as specified in the WSDL
file and whose operations this procedure object
encapsulates, hPortType is a HANDLE variable that
is set to the handle of the created procedure object,
and server-handle is a handle to the server object
that binds the Web service.

C5
OpenEdge Development: Web Services

Table C2: Statements to access Web services (3 of 3)

4GL statement Description

RUN operationName IN hPortType Invokes a Web service operation that does not
[ ASYNCHRONOUS contain a <return> parameter element, where
[ SET asyncRequestHandle ] operationName is the name of a Web service
operation specified in the WSDL file, hPortType
[ EVENT-PROCEDURE
is a handle to the procedure object that
eventInternalProcedure
encapsulates the operation, and parameter is a
[ IN procedureContext ]] 4GL procedure parameter as required by the
[ ( parameter WSDL for the operation. If the operation is
[ , parameter ] ... ) ] invoked asynchronously, asyncRequestHandle is
a handle that is set to the asynchronous request
[ NO-ERROR ] .
object created for the asynchronous request,
eventInternalProcedure is the name of a 4GL
internal procedure defined to handle the results of
the asynchronous request, and procedureContext
is a handle to an active 4GL procedure object that
encapsulates the event internal procedure.

WAIT-FOR ... Handles any pending PROCEDURE-COMPLETE events

for asynchronous requests by forcing the event
procedures for all completed asynchronous
requests to execute. You can also use PROCESS
EVENTS or any other blocking I/O statement, such
as the PROMPT-FOR statement, to handle these
events.

C6
 Progress 4GL Elements for Accessing Web Services

Attributes, methods, and events for accessing Web services

Table C3 lists the 4GL handle attributes and methods that are either valid only for accessing a
Web service or have special application in Web service client programming. The remaining
chapters explain how to use these 4GL elements.

Table C3: Attributes, methods, and events to access Web services (1 of 10)

4GL attribute, method, or event Description

ACTOR A CHARACTER attribute on a SOAP header-entryref

object handle that returns the value of the actor
attribute specified in the associated SOAP header
entry.

ADD-HEADER-ENTRY( ) A LOGICAL method on the SOAP header object

handle that creates a new SOAP header entry and
attaches it to the SOAP header. A specified SOAP
header-entryref object handle references the new
header entry.

ASYNC-REQUEST-COUNT An INTEGER attribute that:

On a server object handle, returns the number
of active asynchronous requests submitted to
this Web service.
On a procedure handle, returns the number of
currently outstanding asynchronous requests
for this procedure object. Can be nonzero
only if the PROXY and PERSISTENT attributes
are both set to TRUE.

CANCELLED A LOGICAL attribute on the asynchronous request

object handle that indicates if the asynchronous
request was cancelled using either the
CANCEL-REQUESTS( ) method or the
DISCONNECT( ) method on the associated server
handle.

C7
OpenEdge Development: Web Services

Table C3: Attributes, methods, and events to access Web services (2 of 10)

4GL attribute, method, or event Description

CANCEL-REQUESTS( ) A LOGICAL method on the server object handle

that:
Terminates the socket connection to all
currently running asynchronous requests for
this Web service and raises the STOP
condition in the event procedure context for
each such request.
Purges the send queue of any asynchronous
requests that have not yet been executed for
this Web service.

CLIENT-CONNECTION-ID A CHARACTER attribute on the server object handle

that returns the connection ID for the connection
associated with this server handle. For Web
services, this is the empty string.

COMPLETE A LOGICAL attribute on the asynchronous request

object handle that indicates if the asynchronous
request is completed and its result is processed on
the client.

CONNECT( A LOGICAL method on the server object handle that

[ connection-parameters ] logically connects (binds) and associates a Web
[ , userid ] service to the server handle. All method
parameters except the connection-parameters
[ , password ] parameter are ignored for a Web service.
[ , appserver-info ] )

CONNECTED( ) A LOGICAL method on the server object handle that

returns TRUE if the handle is currently bound to a
Web service.

DELETE-HEADER-ENTRY( ) A LOGICAL method on the SOAP header-entryref

object handle that deletes the underlying SOAP
header entry and all of its content, but does not
delete the SOAP header-entryref object used to
reference the deleted header entry.

C8
 Progress 4GL Elements for Accessing Web Services

Table C3: Attributes, methods, and events to access Web services (3 of 10)

4GL attribute, method, or event Description

DISCONNECT( ) A LOGICAL method on the server object handle that

disconnects from and removes all reference to the
Web service currently associated with the server
handle. Any running or pending asynchronous
requests to the Web service submitted by this
client are also cancelled.

ERROR A LOGICAL attribute on the asynchronous request

object handle that indicates that an ERROR
condition was returned as a result of processing a
Web service request.

ERROR-OBJECT-DETAIL A HANDLE attribute an the ERROR-STATUS system

handle that references the SOAP fault object for
any Web service request that returns a SOAP fault
that is trapped using the 4GL NO-ERROR option.

EVENT-PROCEDURE A CHARACTER attribute on the asynchronous

request object handle that contains the name of the
internal procedure to be run as the event procedure
for this asynchronous request.

EVENT-PROCEDURE-CONTEXT A HANDLE attribute on the asynchronous request

object handle that contains the procedure handle of
the active procedure context where the event
procedure for this asynchronous request is defined.

FIRST-ASYNC-REQUEST( ) A HANDLE method on the server object handle that

returns the first entry in the list of all current
asynchronous request handles for the specified
Web service.

FIRST-PROCEDURE A HANDLE attribute on the server object handle that

references the first procedure object associated
with the Web service port type bound to this server
object.

FIRST-SERVER A HANDLE attribute on the SESSION system handle

that returns the handle to the first entry in the chain
of server handles for the session, including server
handles for Web services.

C9
OpenEdge Development: Web Services

Table C3: Attributes, methods, and events to access Web services (4 of 10)

4GL attribute, method, or event Description

GET-HEADER-ENTRY( ) A LOGICAL method on the SOAP header object

handle that associates a specified SOAP
header-entryref object handle with a specified
entry in the associated SOAP header.

GET-NODE( ) A LOGICAL method that:

On the SOAP header-entryref object handle,
returns a handle to an X-noderef object that is
the root node of a DOM tree containing the
parsed XML for the underlying SOAP
header entry.
On the SOAP fault-detail object handle,
returns a handle to an X-noderef object that is
the root node of a DOM tree containing the
parsed XML for the underlying SOAP detail
information.

GET-SERIALIZED( ) A LONGCHAR method that:

On the SOAP header-entryref object handle,
returns the XML for the underlying SOAP
header entry in serialized form.
On the SOAP fault-detail object handle,
returns the XML for the underlying SOAP
fault detail information in serialized form.

LAST-ASYNC-REQUEST( ) A HANDLE method on the server object handle that

returns the last entry in the list of all current
asynchronous request handles for the specified
Web service.

LAST-PROCEDURE A HANDLE attribute on the server object handle that

references the last procedure object associated
with the Web service port type bound to this server
object.

LAST-SERVER A HANDLE attribute on the SESSION system handle

that returns the handle to the last entry in the chain
of server handles for the session, including server
handles for Web services.

C10
 Progress 4GL Elements for Accessing Web Services

Table C3: Attributes, methods, and events to access Web services (5 of 10)

4GL attribute, method, or event Description

LOCAL-NAME A CHARACTER attribute on the SOAP

header-entryref object handle that returns the
unqualified part of name specified for the
associated SOAP header entry element.

MUST-UNDERSTAND A LOGICAL attribute on the SOAP header-entryref

object handle that returns the value of the
mustUnderstand attribute specified in the
associated SOAP header.

NAME A CHARACTER attribute that:

On a Web service server object handle,
returns the name of the Web service for use
in the OpenEdge Application Debugger. By
default, this name is set to the URL of the
Web service.
On a Web service procedure object handle,
returns the name of the port type in the
WSDL file that specifies the Web service
operations encapsulated by this procedure
object. This is also the value of
portTypeName in the RUN portTypeName
statement used to instantiate this procedure
object.
On a SOAP header object handle, returns the
qualified name of the SOAP header
("namespacePrefix:HEADER", where
namespacePrefix is usually "SOAP" or
"SOAP-ENV").

On a SOAP header-entryref object handle,

returns the qualified name of the SOAP
header entry
("namespacePrefix:localName").

NAMESPACE-URI A CHARACTER attribute on the SOAP

header-entryref object handle that returns the
namespace URI prefixed to the associated SOAP
header entry elements name.

C11
OpenEdge Development: Web Services

Table C3: Attributes, methods, and events to access Web services (6 of 10)

4GL attribute, method, or event Description

NEXT-SIBLING A HANDLE attribute that:

On an asynchronous request object handle,
returns the next entry in the list of
asynchronous request handles for
asynchronous operation requests submitted
for the same Web service.
On a Web service procedure handle, returns
the next entry in the list of all procedure
objects bound to the same Web service port
type.
On a server object handle, returns the next
entry in the list of all server handles created
for the current Progress session, regardless of
subtype (see the SUBTYPE attribute).

NUM-HEADER-ENTRIES An INTEGER attribute on the SOAP header object

handle that returns the number of entries attached
to the SOAP header.

PERSISTENT A LOGICAL attribute on procedure handles that

returns TRUE for a procedure object associated with
a Web service.

PERSISTENT-PROCEDURE A HANDLE attribute on the asynchronous request

object handle that returns the handle to the
procedure object for the specified asynchronous
Web service request.

C12
 Progress 4GL Elements for Accessing Web Services

Table C3: Attributes, methods, and events to access Web services (7 of 10)

4GL attribute, method, or event Description

PREV-SIBLING A HANDLE attribute that:

On an asynchronous request object handle,
returns the previous entry in the list of
asynchronous request handles for
asynchronous operation requests submitted
for the same Web service.
On a Web service procedure handle, returns
the previous entry in the list of all procedure
objects bound to the same Web service port
type.
On a server object handle, returns the
previous entry in the list of all server handles
created for the current Progress session,
regardless of subtype (see the SUBTYPE
attribute).

PROCEDURE-COMPLETE The event returned for an asynchronous request

object handle that indicates the associated Web
service request has completed execution and, as a
result, causes execution of the event procedure as
specified by the EVENT-PROCEDURE and
EVENT-PROCEDURE-CONTEXT attributes.

PROCEDURE-NAME A CHARACTER attribute on the asynchronous

request object handle that provides the name of the
Web service operation executed to instantiate this
asynchronous request handle.

PROXY A LOGICAL attribute on procedure object handles

that is TRUE if the procedure handle references a
procedure object associated with a Web service.

C13
OpenEdge Development: Web Services

Table C3: Attributes, methods, and events to access Web services (8 of 10)

4GL attribute, method, or event Description

SERVER A HANDLE attribute that:

On a procedure object handle, returns the
handle to the Web service server object with
which the procedure object is associated.
Valid only if the PROXY and PERSISTENT
attributes are both TRUE.
On an asynchronous request object handle,
returns the server handle of the Web service
where this asynchronous request was
invoked.

SET-ACTOR( ) A LOGICAL method on the SOAP header-entryref

object handle that sets the value of the actor
attribute in the underlying SOAP header entry.
This method completes and returns TRUE only if
there is an underlying SOAP header entry (XML)
associated with the object handle.

SET-CALLBACK-PROCEDURE( ) A LOGICAL method on the procedure object handle

that associates a specified internal procedure with
a Progress callback. For Web services, the two
supported types of Progress callbacks, include:
"REQUEST-HEADER" SOAP request header
callback
"RESPONSE-HEADER" SOAP Response
header callback
The internal procedures associated with these
callbacks provide access to the SOAP headers of
the request and response messages sent for all the
Web service operations encapsulated by the
procedure object.

SET-MUST-UNDERSTAND( ) A LOGICAL method on the SOAP header-entryref

object handle that sets the value of the
mustUnderstand attribute in the underlying SOAP
header entry. This method completes and returns
TRUE only if there is an underlying SOAP header
entry (XML) associated with the object handle.

C14
 Progress 4GL Elements for Accessing Web Services

Table C3: Attributes, methods, and events to access Web services (9 of 10)

4GL attribute, method, or event Description

SET-NODE( ) A LOGICAL method on the SOAP header-entryref

object handle that replaces the header entry
referenced by this SOAP header-entryref object
with a specified DOM sub-tree (parsed XML) that
is assumed to represent a SOAP header entry
element.

SET-SERIALIZED( ) A LOGICAL method on the SOAP header-entryref

object handle that replaces the header entry
referenced by this SOAP header-entryref object
with serialized XML that is assumed to parse into
a DOM sub-tree that represents a SOAP header
entry element.

SOAP-FAULT-CODE A CHARACTER attribute on the SOAP fault object

handle that contains the value of the faultcode
attribute for the SOAP fault, which identifies the
fault.

SOAP-FAULT-STRING A CHARACTER attribute on the SOAP fault object

handle that contains the value of the faultstring
attribute for the SOAP fault, which provides a
human-readable description of the fault.

SOAP-FAULT-ACTOR A CHARACTER attribute on the SOAP fault object

handle that contains the value of the faultactor
attribute for the SOAP fault, which is a URI that
identifies the Web service returning the fault.

SOAP-FAULT-DETAIL A HANDLE attribute on the SOAP fault object

handle that references the SOAP fault-detail
object, which contains application-specific error
information.

STOP A LOGICAL attribute on the asynchronous request

object handle that is set to TRUE, if the
asynchronous request was executing when the
client invoked a CANCEL-REQUESTS( ) method.

C15
OpenEdge Development: Web Services

Table C3: Attributes, methods, and events to access Web services(10 of 10)

4GL attribute, method, or event Description

SUBTYPE A CHARACTER attribute that returns the subtype of a

handle. For a server object handle, this is:
WEBSERVICE For a server object
bound to a Web service.
APPSERVER For a server object
bound to an AppServer.
The default value for an unbound server object
handle is the unknown value (?).

TYPE A CHARACTER attribute that returns the handle type,

which:
On a server object handle is "SERVER".
On a procedure object handle is
"PROCEDURE".

On a SOAP header object handle is

"SOAP-HEADER".

On a SOAP header-entryref object handle is

"SOAP-HEADER-ENTRYREF".

On a SOAP fault object handle is

"SOAP-FAULT".

On a SOAP fault-detail object handle is

"SOAP-FAULT-DETAIL".

On an X-document object handle is

"X-DOCUMENT".

On an X-noderef object handle is

"X-NODEREF".

On an asynchronous request object handle is

"ASYNC-REQUEST".

C16
 D
Data Type Casting Rules for Progress
4GL Calls to Web Services

This appendix describes how OpenEdge casts between the following 4GL data types and XML
Schema data types in parameters passed to Web services called from the 4GL. Any casting
between a 4GL type and an unsupported XML Schema type or an invalid match between a 4GL
type and a supported XML Schema type raises a 4GL run-time error, as described in the
following sections:

CHARACTER or LONGCHAR

DATE

DATETIME

DATETIME-TZ

DECIMAL

INTEGER

LOGICAL
OpenEdge Development: Web Services

MEMPTR or RAW

Note: The following tables describe data transformations for the 4GL INPUT and OUTPUT
parameter modes. The INPUT-OUTPUT parameter mode behaves in the same manner.

D2
 Data Type Casting Rules for Progress 4GL Calls to Web Services

CHARACTER or LONGCHAR
Table D1 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL CHARACTER or LONGCHAR type and XML Schema.

Table D1: 4GL data type castCHARACTER or LONGCHAR

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

All XML Schema INPUT1 Attempts to format the 4GL string value to match
types where the specified XML Schema type for inclusion in
CHARACTER is the the SOAP request message.2
suggested 4GL
mapping (see Chapter OUTPUT1 Converts the value from the formatting of the
8, Analyzing WSDL specified XML Schema type before copying it into
for Progress 4GL
the 4GL parameter as a string value.2
Access to Web
Services)

All XML Schema INPUT1 Copies the string value directly, with no attempt to
types where format it, for inclusion in the SOAP request
CHARACTER or message. OpenEdge performs minimal validation
LONGCHAR is not the to ensure that the string contains data formatted
suggested 4GL according to the rules of the XML Schema type.
mapping (see Chapter
8, Analyzing WSDL OUTPUT1 Copies the XML Schema value directly from the
for Progress 4GL SOAP response message to the 4GL parameter
Access to Web unchanged from its XML Schema format.
Services)
1
On both INPUT and OUTPUT parameters, OpenEdge translates the value between the cpinternal code page and
Unicode.
2
The process of serializing and de-serializing CHARACTER data inserts and removes XML character references,
for example, replacing "<" with "&lt;".

D3
OpenEdge Development: Web Services

DATE
Table D2 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL DATE type and XML Schema.

Table D2: 4GL data type castDATE

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

string INPUT Serializes the 4GL parameter into the SOAP

normalizedString request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the string value from the SOAP

response message into the 4GL parameter as if the
4GL DATE( ) function was called on the string in
an OpenEdge session started with the d ymd
startup parameter.

dateTime INPUT Serializes the 4GL parameter according to the

XML Schema serialization rules, with the time
assumed to be 12:00 midnight local time.

OUTPUT De-serializes the XML Schema value into the 4GL

parameter according to the XML Schema
serialization rules with the value set to the local
time adjusted from any time and time zone
information (which is stripped away). If there is no
time and time zone information the value is stored
as is. If you need to maintain the time information,
use the 4GL DATETIME data type. If you need to
maintain the time zone information, use the 4GL
DATETIME-TZ data type.

date INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules with no time zone.

OUTPUT De-serializes the XML Schema value into the 4GL

parameter with the date adjusted for any time zone
information and the time zone information
stripped away. If you need to maintain the time
zone information, use the 4GL DATETIME-TZ data
type.

D4
 Data Type Casting Rules for Progress 4GL Calls to Web Services

DATETIME
Table D3 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL DATETIME type and XML Schema.

Table D3: 4GL data type castDATETIME

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

string INPUT Serializes the 4GL parameter into the SOAP

normalizedString request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the string value from the SOAP

response message into the 4GL parameter as if the
4GL DATETIME( ) function was called on the
string.

dateTime INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules without a time zone.

OUTPUT De-serializes the XML Schema value from the

SOAP response message into the 4GL parameter
according to the XML Schema serialization rules
with the value set to the local time adjusted from
any time zone information (which is stripped
away). If there is no time zone information the
value is stored as is.

date INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules. The time part of the DATETIME
value is lost.

OUTPUT De-serializes the XML Schema value from the

SOAP response message into the 4GL parameter
according to the XML Schema serialization rules
with the date adjusted for any time zone
information (which is stripped away). The 4GL
DATETIME value has the time set to 12:00 midnight.

D5
OpenEdge Development: Web Services

DATETIME-TZ
Table D4 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL DATETIME-TZ type and XML Schema.

Table D4: 4GL data type castDATETIME-TZ

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

string INPUT Serializes the 4GL parameter into the SOAP

normalizedString request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the string value from the SOAP

response message into the 4GL parameter
according to the XML Schema serialization rules
as if the 4GL DATETIME-TZ( ) function was called
on the string.

dateTime INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules including the time zone.

OUTPUT De-serializes the XML Schema value from the

SOAP response message into the 4GL parameter
according to the XML Schema serialization rules.

date INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules. The time part of the
DATETIME-TZ value is lost, but the time zone part
of the DATETIME-TZ value is retained.

OUTPUT De-serializes the XML Schema value from the

SOAP response message into the 4GL parameter
according to the XML Schema serialization rules.
The 4GL DATETIME-TZ value has the time set to
12:00 midnight.

D6
 Data Type Casting Rules for Progress 4GL Calls to Web Services

DECIMAL
Table D5 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL DECIMAL type and XML Schema.

Table D5: 4GL data type castDECIMAL (1 of 2)

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

string INPUT Serializes the 4GL parameter into the SOAP

normalizedString request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the string value from the SOAP

response message into the 4GL parameter as if the
4GL DECIMAL( ) function was called on the string.

boolean INPUT Serializes a 4GL DECIMAL value of 0 to false and

all other values for the 4GL parameter to true.

OUTPUT De-serializes a value of false to a 4GL DECIMAL

value of 0, and de-serializes a value of true to a
DECIMAL value of 1.

decimal INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the XML Schema value into the 4GL

parameter according to the XML Schema
serialization rules. If the XML Schema decimal
value overflows the 4GL DECIMAL, OpenEdge
raises a run-time error.

float INPUT Serializes the 4GL DECIMAL value according to

double XML Schema serialization rules. Some of the least
significant digits might be lost.

OUTPUT De-serializes the XML Schema value to the

equivalent 4GL DECIMAL value. If the value is
outside the range of the 4GL DECIMAL, OpenEdge
raises a run-time error.

D7
OpenEdge Development: Web Services

Table D5: 4GL data type castDECIMAL (2 of 2)

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

integer INPUT Rounds the 4GL DECIMAL value to an integer and

nonPositiveInteger serializes the result based on the serialization rules
negativeInteger for the XML Schema type. Data might be lost. If
long
the DECIMAL value is outside the valid range of the
int
short
XML Schema type, OpenEdge raises a run-time
byte error.
nonNegativeInteger
unsignedLong OUTPUT De-serializes the XML Schema value into the 4GL
unsignedInt parameter as if the 4GL DECIMAL( ) function was
unsignedShort called on the value. If the value in the SOAP
unsignedByte response message is outside the range of the
positiveInteger DECIMAL type, OpenEdge raises a run-time error.

D8
 Data Type Casting Rules for Progress 4GL Calls to Web Services

INTEGER
Table D6 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL INTEGER type and XML Schema.

Table D6: 4GL data type castINTEGER (1 of 3)

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

string INPUT Serializes the 4GL parameter into the XML

normalizedString Schema value as if the 4GL STRING( ) function
was called on the INTEGER value.

OUTPUT De-serializes the XML Schema value as if the

INTEGER( ) function was called on string value.

boolean INPUT Serializes an INTEGER value of 0 to false and all

other values to true.

OUTPUT De-serializes a value of false to a 4GL INTEGER

value of 0, and de-serializes a value of true to an
INTEGER value of 1.

decimal INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the XML Schema value as if the

INTEGER( ) function was called on the serialized
4GL DECIMAL value. This rounds any positions
after the decimal point. If the XML Schema
decimal value is outside the range of a 4GL
INTEGER, OpenEdge raises a run-time error.

float INPUT Serializes the 4GL INTEGER value to a float

according to the XML Schema rules. Some of the
least significant digits of the INTEGER value are lost
if the number of digits in the value is large.

OUTPUT De-serializes the XML Schema value into a 4GL

INTEGER. If the XML Schema value overflows or
underflows a 4GL INTEGER, OpenEdge raises a
run-time error.

D9
OpenEdge Development: Web Services

Table D6: 4GL data type castINTEGER (2 of 3)

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

double INPUT Serializes the 4GL INTEGER value to a double

according to the XML Schema rules.

OUTPUT De-serializes the XML Schema value into a 4GL

INTEGER. If the XML Schema value overflows or
underflows a 4GL INTEGER, OpenEdge raises a
run-time error.

integer INPUT Serializes the 4GL parameter into the SOAP

nonPositiveInteger request message according to the serialization
negativeInteger rules for the XML Schema data type.
long
nonNegativeInteger OUTPUT
unsignedLong
De-serializes the XML Schema value as if the 4GL
unsignedInt INTEGER( ) function was called on the value. If
positiveInteger the XML Schema value is outside the valid range
of a 4GL INTEGER, OpenEdge raises a run-time
error.

int INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the XML Schema value as if the 4GL

INTEGER( ) function was called on the value.

short INPUT Serializes the 4GL parameter into the SOAP

byte request message according to the serialization
unsignedShort rules for the XML Schema data type. If the 4GL
unsignedByte
INTEGER value is outside the valid range of the
XML Schema type, OpenEdge raises a run-time
error.

OUTPUT De-serializes the XML Schema value as if the 4GL

INTEGER( ) function was called on the value.

D10
 Data Type Casting Rules for Progress 4GL Calls to Web Services

Table D6: 4GL data type castINTEGER (3 of 3)

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

time INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules without a time zone. The 4GL
INTEGER value is treated as the number of seconds
since midnight.

OUTPUT De-serializes the XML Schema value to the

number of seconds since midnight. The conversion
loses fractions of seconds. If a time zone is
specified in the value, the time is adjusted to the
same instant in the local time zone.

D11
OpenEdge Development: Web Services

LOGICAL
Table D7 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL LOGICAL type and XML Schema.

Table D7: 4GL data type castLOGICAL

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

string INPUT Serializes the 4GL parameter into the SOAP

normalizedString request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the XML Schema string type as if it

was a serialized boolean value.

boolean INPUT Serializes the 4GL parameter into the SOAP

request message according to the XML Schema
serialization rules.

OUTPUT De-serializes the XML Schema value into the 4GL

parameter according to the XML Schema
serialization rules.

decimal INPUT Serializes a 4GL LOGICAL value of true to an

float XML Schema type value of 1, and serializes a
double LOGICAL value of false to an XML Schema type
value of 0.

OUTPUT De-serializes an XML Schema value of 0 to a 4GL

LOGICAL value of false, and all other XML
Schema values to a LOGICAL value of true.

integer INPUT Serializes a 4GL LOGICAL value of true to an

nonPositiveInteger XML Schema type value of 1 (or -1 for a
long nonPositiveInteger), and serializes a LOGICAL
int
value of false to an XML Schema type value of 0.
short
byte
OUTPUT De-serializes an XML Schema value of 0 to a 4GL
nonNegativeInteger
unsignedLong LOGICAL value of false, and all other XML
unsignedIn Schema values to a LOGICAL value of true.
unsignedShort
unsignedByte

D12
 Data Type Casting Rules for Progress 4GL Calls to Web Services

MEMPTR or RAW
Table D8 describes the supported castings in each 4GL parameter mode (INPUT and OUTPUT)
between the 4GL MEMPTR or RAW type and XML Schema.

Table D8: 4GL data type castRAW or MEMPTR

In this 4GL
For this XML parameter
Schema type... mode... OpenEdge...

base64Binary INPUT Serializes the value of each byte in the 4GL value
hexBinary according to the XML Schema serialization rules
for the data type. If the mapping is to a
base64Binary value with the encoding attribute
set, the value is base-64 encoded and copied
directly from the 4GL parameter without
serialization.

OUTPUT De-serializes the value of each byte in the 4GL

value according to the XML Schema serialization
rules for the data type. If the mapping is from a
base64Binary value, it is always de-serialized into
the 4GL parameter.

D13
OpenEdge Development: Web Services

D14
Index

A 4GL to Web service

managing (multiple) 910
AppObjects in 4GL Web services Bindings section
session-free 410 WSDL
session-managed 49 4GL Web services 212
AppServer generic 123
4GL Web services 16
preparing for 4GL Web services 113
C
AppServer session models 32
Callback procedures 103
AppServers
testing for 4GL Web services 72 Casting XML Schema and 4GL types
4GL client listings 831
Architecture detailed 4GL client rules D1
4GL client of a Web service 116
Progress 4GL Web services 15 CHARACTER 4GL client casting rules D3

Arrays Client for 4GL Web services

4GL client and XML Schema 836 writing 114

Asynchronous requests Client interface methods

4GL clients of Web services 133 session-free AppObjects 410
session-managed AppObjects 49
SubAppObjects and ProcObjects 411
B
Client interfaces
Binding to a Web service 4GL Web services
4GL clients 93 affects from SOAP formats 43
documentation for 4GL clients 85
Bindings
OpenEdge Development: Web Services

Client programming parameter mapping

4GL Web services 4GL clients calling Web services 824
session-free 47 4GL Web services 418
session-managed 46 relational data
Web service objects 48 4GL Web services 428

Client programming for 4GL Web services DATE 4GL client casting rules D4
41
DATETIME 4GL client casting rules D5
Client programming for SOAP faults 441
DATETIME-TZ 4GL client casting rules
Client requirements D6
4GL Web services 111
DECIMAL 4GL client casting rules D7
Complex data management
4GL clients of Web services 108 Defining client requirements 112
4GL examples 109
Defining the Web service 113
4GL types 109
Definitions section
Complex types
WSDL
4GL client and XML Schema 837
4GL Web services 210
Configuring the WSA 113 generic 122

CONNECT( ) method parameters 93 Deploying a 4GL Web service 114

Connecting to a Web service Developing 4GL Web services 112

4GL clients 93 Document format 27
Connection parameters
Document/Literal format
4GL client to Web service 94
4GL Web services 29
Connections
Dynamic temp-table parameters
4GL client to Web service 91
4GL Web services 432
managing (multiple) 910
client to 4GL Web service
session-free 410 E
session-managed 49
Encoded format 28
D ERROR-STATUS system handle
SOAP fault detection 123
Data types
4GL client to XML Schema
arrays 836
complex types 837
simple types 824

Index2
 Index

F L
4GL attributes and methods for accessing Literal format 28
Web services C7
Log files
4GL clients, See Progress 4GL applications 4GL Web service testing 77
13
LOGICAL 4GL client casting rules D12
4GL object handles for accessing Web
LONGCHAR 4GL client casting rules D3
services C2

4GL statements for accessing Web services

C4 M
4GL Web services, See Progress 4GL Web Memory management
services 12 SOAP headers in 4GL clients 1131

FUNCTION statement MEMPTR 4GL client casting rules D13

Web service operations 106
Messages section
WSDL
G 4GL Web services 211
generic 122
Getting a WSDL file 23
N
H Namespaces
Header handlers 112 Web service 25
defining in the 4GL 1110
request messages 1113 O
response messages 1112
invoking in the 4GL 118
Object IDs 24
requirements for in the 4GL 114
client examples
HTTPS in 4GL applications 97 4GL Web services 418
defining in WSDL 416
passing in SOAP headers 415
I session models and 33
Open Client
Industry standards 14
object model for 4GL Web services 24
INTEGER 4GL client casting rules D9
Open Client Toolkit 12
Interacting with a Web service from the WSDL and 17
4GL 124

Index3
OpenEdge Development: Web Services

P Web service connection parameters 94

Web service procedure object 102
Port type procedure object 102 Web service request errors 132

Port types section Progress 4GL Web services

WSDL architectural overview 15
4GL Web services 211 client programming
generic 122 session-free 47
session-managed 46
Preparing the AppServer 113 Web service objects 48
client programming model 41
ProcObjects in 4GL Web services 411 client programming requirements 111
deployment information 25
Progress 4GL applications handling communications with 414
accessing handling errors and SOAP faults 440
4GL Web services 14 handling SOAP headers 415
Web services 13 mapping 4GL procedures to SOAP 433
accessing Web service port types method parameters 418
Port types Open Client object model 24
4GL client access 910 sample applications
accessing Web services directory structure 62
basic sample 127 using 63
alternate mappings to XML Schema 831 sample client development
analyzing WSDL for 82 .NET A1
AppServer compared to Web service Java B1
access 124 SOAP formats supported 29
asynchronous Web service requests 133 SOAP message samples
attributes and methods for Web service Web service example 52
access C7 SOAP sample
binding to Web services 93 creating and using ProcObjects 510
connecting to Web services 93 creating and using SubAppObjects
debugging Web service access 128 516
handling SOAP faults 122 internal procedures/user-defined
handling SOAP headers 103 functions 514
handling Web service errors 121 non-persistent procedures 57
handling Web service inputs and outputs receiving SOAP faults 528
overview 129 releasing objects 518
HTTPS 97 session-free access 57
invoking Web service operations 101 session-managed access 54
managing SOAP headers 111 temp-table parameters 519
managing Web service bindings 910 steps for building and deploying 112
object handles for Web service access temp-table parameters 428
C2 testing and debugging 71
SOAP header object model 115 tools overview 12
statements for Web service access C4 WSDL file overview 24
suggested mappings to XML Schema
824 Progress callbacks 103
Web service client architecture 116

Index4
 Index

Progress Explorer framework Session-free programming

WSA and 19 clients of 4GL Web services 47
ProSOAPView Session-managed programming
using 1211 clients of 4GL Web services 46
Providing a 4GL Web service 115 SET-CALLBACK-PROCEDURE( )
method 103

R Simple Object Access Protocol, See SOAP.

117
RAW 4GL client casting rules D13
SOAP
RPC format 27 4GL header objects 115
4GL header-entryref objects 115
RPC/Encoded format action 25
4GL Web services 29 client messages
4GL Web services 439
RPC/Literal format
format 26
4GL Web services 29 formats
RUN statement 4GL client support 120
formats supported by 4GL Web services
Web service operations 106
29
Web service procedure object 102
learning more 529
message formats
S 4GL Web services 26
message structure overview
Sample 4GL access to a Web service 4GL client perspective 117
messages for 4GL Web services 433
basic overview 127
sample 4GL Web service messages
Sample applications creating and using ProcObjects 510
4Gl Web services creating and using SubAppObjects
directory structure 62 516
using 63 internal procedures/user-defined
functions 514
Security options non-persistent procedures 57
4GL Web services 110 receiving SOAP faults 528
releasing objects 518
Services section session-free access 57
WSDL session-managed access 54
4GL Web services 212 temp-table parameters 519
generic 123 standards supported 14
Session models 16 SOAP fault object
4GL Web services 32 attributes 124
AppServers 32
Object IDs and 33 SOAP fault-detail object
selecting for 4GL Web services 31 attributes and methods 124

Index5
OpenEdge Development: Web Services

SOAP faults T
4GL clients handling 122
4GL Web services Temp-tables
clients handling 440 4GL Web services 428
detecting 123
example 4GL handling 126 Testing
4GL Web services
SOAP formats error identification 712
4GL Web services log files 77
client interface affects 43 sample error scenarios 715
SOAP header object model 115 setting error levels 74
SOAP faults 77
SOAP header objects SOAP message viewers 710
attributes and methods 1133 AppServers for 4GL Web services 72

SOAP header-entryref objects Testing a 4GL Web service 114

attributes and methods 1134 Tools for building Web services 12
SOAP headers
Tuning a 4GL Web service 115
4GL client overview 112
accessing in the 4GL 114 Types section
client handling WSDL
4GL clients 111 4GL Web services 210
4GL Web services 415 generic 122
defining 4GL handlers 1110
request messages 1113
response messages 1112 U
invoking 4GL handlers 118
object model 115 Unit testing 4GL Web services 72
setting access for 4GL clients 103
structure 113 Use attribute 27
SOAP headers in the 4GL
attributes and methods 1133 W
creating and managing 1113
creating for initial request 1126 Web Service Mapping file 12
memory management 1131
reusing 1115 Web service object
reusing with modifications 1120 session models and 34
SOAP message viewers Web service objects 31
4GL clients of Web services 129 clients of 4GL Web services calling 48
4GL Web services 710
Web service operation parameters
Static temp-table parameters 4GL Web services 418
4GL Web services 428
Style attribute 27

SubAppObjects in 4GL Web services 411

Index6
 Index

Web service operations WSDL files

4GL procedure invocation 106 4GL client access to Web services 81
4GL user-defined function invocation 4GL client to XML Schema
106 arrays 836
client management of complex data in the complex types 837
4GL 108 simple types 824
invoking from the 4GL 105 4GL Web services
managing parameters 107 client calls to 4GL procedures 438
creating client interfaces from 42
Web service procedure object 102 mapping operations to 4GL
procedures 435
Web service server objects 93 defining Object IDs for 4GL Web
Web service session models 32 services 416
element overview for 4GL Web services
Web services 29
debugging access from the 4GL 128 mapping to 4GL data types 824
requirements for accessing 22 Open Client Toolkit 17
overview
Web Services Adapter (WSA) 12 for 4GL clients 120
configuring 113 for 4GL Web services 24
overview 18 sources for obtaining 23
URL 25 standards supported 14

Web services in OpenEdge 11 .wsm file 12

industry standards supported 14
WSA 12 X
WSA URL 25 XML Schema
WSAViewer alternate mappings to 4GL client types
831
configuring for the WSA 710
mapping to 4GL
using 129
4GL Web services 418
WSDL Analyzer client data types 824
how to use 82 standards supported 14
HTML documentation 85 suggested mappings to 4GL client types
overview 124 824
source for 4GL client interface 129

Index7
OpenEdge Development: Web Services

Index8