U2 Web Services Developer User Guide

U2 Web Services Developer
User Guide
Version JAN2015
January 2015
DBT-JAN2015–WSD-01
Notices
Edition
Publication date: January 2015
Book number: DBT-JAN2015–WSD-01
Product version: Version JAN2015
Copyright
© Rocket Software, Inc. or its affiliates 1989-2015. All Rights Reserved.
Trademarks
Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go
to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document
may be covered by the trademarks, service marks, or product names of their respective owners.
Examples
This information might contain examples of data and reports. The examples include the names of
individuals, companies, brands, and products. All of these names are fictitious and any similarity to
the names and addresses used by an actual business enterprise is entirely coincidental.
License agreement
This software and the associated documentation are proprietary and confidential to Rocket Software,
Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with
the terms of such license.
Note: This product may contain encryption technology. Many countries prohibit or restrict the
use, import, or export of encryption technologies, and current use, import, and export regulations
should be followed when exporting this product.
2
Corporate information
Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,
and compliance; database servers and tools; business information and analytics; and application
development, integration, and modernization.
Website: www.rocketsoftware.com
Rocket Global Headquarters
77 4th Avenue, Suite 100
Waltham, MA 02451-1468
USA
To contact Rocket Software by telephone for any reason, including obtaining pre-sales information
and technical support, use one of the following telephone numbers.
Country
Toll-free telephone number
United States
1-855-577-4323
Australia
1-800-823-405
Belgium
0800-266-65
Canada
1-855-577-4323
China
800-720-1170
France
0800-180-0882
Germany
08-05-08-05-62
Italy
800-878-295
Japan
0800-170-5464
Netherlands
0-800-022-2961
New Zealand
0800-003210
South Africa
0-800-980-818
United Kingdom
0800-520-0439
Contacting Technical Support
The Rocket Customer Portal is the primary method of obtaining support. If you have current
support and maintenance agreements with Rocket Software, you can access the Rocket Customer
Portal and report a problem, download an update, or find answers to in the U2 Knowledgebase.
To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go to
www.rocketsoftware.com/support.
In addition to using the Rocket Customer Portal to obtain support, you can send an email to
u2support@rocketsoftware.com or use one of the following telephone numbers.
Country
Telephone number
North America
+1 800 729 3553
United Kingdom/France
+44 (0) 800 773 771 or +44 (0) 20 8867 3691
Europe/Africa
+44 (0) 20 8867 3692
Australia
+1 800 707 703 or +61 (0) 29412 5450
New Zealand
+0800 505 515
3
Contents
Notices................................................................................................................................................................................... 2
Corporate information......................................................................................................................................................... 3
Chapter 1: Installing U2 Web Services Development Tool................................................................................................ 6
Chapter 2: Installing and updating the DBTools using the Eclipse Update Manager.......................................................7
Chapter 3: XTOOLSUB.......................................................................................................................................................... 8
Installing XTOOLSUB for UniData on Windows...................................................................................................... 9
Installing XTOOLSUB for UniVerse on Windows..................................................................................................... 9
Installing XTOOLSUB for UNIX/Linux for UniData................................................................................................ 10
Installing XTOOLSUB for UNIX/Linux on UniVerse............................................................................................... 10
Installing XTOOLSUB on Windows.........................................................................................................................11
Chapter 4: Adding and connecting to servers.................................................................................................................. 13
Adding a UniData or UniVerse server....................................................................................................................13
Connecting to the UniData or UniVerse database................................................................................... 15
Creating a SOAP server.......................................................................................................................................... 16
Viewing the debug log................................................................................................................................19
Displaying cached services........................................................................................................................ 19
Chapter 5: Creating a query web service..........................................................................................................................21
Creating a query web service using drag-and-drop.............................................................................................21
Creating a query web service using the wizard....................................................................................................24
Starting the web service........................................................................................................................................ 29
Chapter 6: Creating a Subroutine web service.................................................................................................................31
Creating a subroutine web service using drag-and-drop.................................................................................... 31
Defining subroutine parameters................................................................................................................33
Creating a subroutine web service using the wizard........................................................................................... 36
Starting the web service........................................................................................................................................ 40
Chapter 7: Viewing properties and dictionaries............................................................................................................... 42
Server properties.................................................................................................................................................... 42
Account properties................................................................................................................................................. 42
File properties......................................................................................................................................................... 42
File dictionaries.......................................................................................................................................................43
Chapter 8: Manually accessing the web services............................................................................................................. 44
Viewing the web service URL.................................................................................................................................44
Viewing the WSDL file.............................................................................................................................................44
Web services clients............................................................................................................................................... 44
Generating a client proxy in IBM Websphere Application Developer......................................................45
Generating a client proxy in Visual Studio.NET........................................................................................45
Chapter 9: Deploying web services................................................................................................................................... 46
Exporting web services...........................................................................................................................................46
Importing web services.......................................................................................................................................... 47
Deploying the SOAP server.................................................................................................................................... 47
Updating the SOAP server..................................................................................................................................... 49
Defining security between the client and the SOAP server................................................................................. 50
Setting connection properties............................................................................................................................... 51
Defining UniData database connection security..................................................................................................52
Deploying the SOAP service as a Windows service.............................................................................................. 53
Deploying the SOAP service from the command line.......................................................................................... 54
Starting the SOAP service from the command line................................................................................. 54
4
Contents
Defining connection security between the client and the SOAP server from the command
line..........................................................................................................................................................56
Defining database connection properties from the command line........................................................ 57
Defining database connection security.....................................................................................................57
Deploying from the command line....................................................................................................................... 58
Deploying a SOAP server from a configuration file..............................................................................................58
Generating a configuration file..................................................................................................................59
Running and stopping the SOAP server................................................................................................................60
Monitoring a remote SOAP server......................................................................................................................... 60
Chapter 10: Troubleshooting............................................................................................................................................. 62
Adjusting Java heap space in the Developer........................................................................................................62
Adjusting Java heap space in a deployed environment...................................................................................... 63
Chapter 11: Sample Code.................................................................................................................................................. 65
Creating a WSD web service.................................................................................................................................. 65
5
Chapter 1: Installing U2 Web Services
Development Tool
To access the U2 Web Services Developer, you must have UniData 7.1.8 or greater, with connection
pooling licensed.
Prerequisite
▪
▪
You must log on with Administrator privileges to install U2 Web Service Developer. Either log
on to the Administrator account on the Windows system, or log on as a member of the local
Administrators group.
Exit any other Windows applications you have open.
Procedure
1.
2.
3.
4.
5.
6.
7.
6
Download your UniData products from https://u2tc.rocketsoftware.com for the United States and
Canada or https://u2tcint.rocketsoftware.com if not in the United States or Canada.
Make sure you have the UniData Product Configuration sheet that is included with your media.
You will need this form when you license the product after installation.
From the Setup screen, click Install U2 DBTools. Select U2 Web Services Developer from the
list.
When the Welcome screen opens, choose the appropriate installation option and then click Next.
The Choose Destination Location dialog box appears.
By default, U2 Web Services Developer is installed in the C:\U2\U2Tools folder. If you want
to install U2 Web Services Developer in a different location, click Browse to select that location.
Click Next to proceed with the installation.
The Select Program Folder dialog box appears.
By default, U2 Web Services Developer is installed in the \U2\U2 Tools folder. If you do not
want to install it in this folder, select the folder where you want to install the product and click
Next to continue with the installation.
At this point, the installation process has enough information to begin copying files. Review
the information in the Start Copying Files dialog box. If all of the information is correct, click
Next to proceed with the installation. If it is not correct, click Back and correct the appropriate
information.
When the installation is complete, the Setup Complete dialog box appears.
Click Finish to complete the installation
Chapter 2: Installing and updating the DBTools
using the Eclipse Update Manager
You can update and install any of the U2 DBTools using the Update Manager in Eclipse.
Find the latest information about updates for U2 DBTools at http://updates.rocketsoftware.com/u2.
Procedure
1.
2.
3.
4.
5.
6.
Launch any U2 DBTools or base Eclipse installations (beginning with Galileo) on your computer.
From the Eclipse Help menu, select Help → Install New Software.
Click Add, enter a name for the site, such as U2 Update Site, and in the Work with field enter
http://updates.rocketsoftware.com/u2. Click OK.
Allow the repository to load and then expand the tree for U2 DBTools. Select the updates that you
want to apply. You can also choose to install any other U2 DBTools into your existing workspace.
Click Next and follow the installation wizard to complete the installation of updates.
Updates will take effect the next time an updated tool is launched.
Note: Only tools that are installed through separate InstallShield installations will appear on
the Start menu. Tools installed using the Eclipse Update Manager are installed as individual
perspectives in a single Eclipse instance. You can access the different perspectives by selecting
Window → Open Perspective and then selecting the appropriate tool.
Note: You can check for updates to the DBTools by selecting Help → Check for Updates. To use
this option, you must have previously defined the http://updates.rocketsoftware.com/u2 location
in the Install New Software dialog, as described in step 3.
7
Chapter 3: XTOOLSUB
This topic describes the XTOOLSUB program and how to upgrade to the latest version of XTOOLSUB
on various operating systems.
Updating the XTOOLSUB Program
The XTOOLSUB program is a U2 database server-side BASIC program used by various U2 Client Tools.
This includes U2 DataVu, U2 Web DE, Basic Developer's Toolkit (BDT), Extensible Administration Tool
(XAdmin), Web Services Developer, and more. It also includes any tool that uses the U2 Resource View.
XTOOLSUB updates itself automatically. However, if something happens to the XTOOLSUB program
you can download the latest version from the public Tech Note site at:
https://u2tc.rocketsoftware.com/documentation/1410028.asp
The XTOOLSUB program contains several zip and tar files, and includes three or four files, depending
on the environment. The XTOOLSUB program is used by all the tools, but the other files included are
only used for the Basic Developer's Toolkit (BDT).
The XTOOLSUB_EXECPRE/XTOOLSUB_XPRE programs are for pre-execution functionality and
XTOOLSUB_EXECPOST/XTOOLSUB_XPST are for post-execution functionality. These programs are
discussed further in the related public Tech Note, BDT Extensibility Details. If you have added your own
code to the pre- and post-functionality, copy those modified programs to the older database versions
rather than the pre- and post- files located here.
The files included for UniData are:
▪
▪
▪
▪
XTOOLSUB
XTOOLSUB_EXECPRE
XTOOLSUB_EXECPOST
EDAMAPSUB (UniData 6.1 and lower)
The files included for UniVerse are:
▪
▪
▪
▪
XTOOLSUB
XTOOLSUB_XPRE
XTOOLSUB_XPST
EDAMAPSUB (UniVerse 10.3 and lower)
Do not catalog the EDAMAPSUB subroutine when using UDT 7.1 or UV 11.1 and higher. This program
already exists on those versions.
There is a difference between the databases because UniVerse's catalog environment is a type 1 file
and has a 14–character file name limit.
Only extract the file that is needed for the database server/version and OS type you are using.
The ...UX.tar (Unix) files come from AIX. You will need to run fnuxi/convcode if you use other UNIX/
Linux operating systems. Files are not included for all operating systems in order to avoid unnecessary
confusion. The files in the zip/tar files are the object code for the given programs; do not open them in
a text editor.
Note: Log in as a root or administrator user when doing these steps to avoid any permissions
errors. If an overwrite message occurs, select "yes" to overwrite the file in question.
8
Installing XTOOLSUB for UniData on Windows
Installing XTOOLSUB for UniData on Windows
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates.
However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
Procedure
1.
2.
3.
4.
5.
Download the latest version of XTOOLSUB from the public Tech Note site at https://
u2tc.rocketsoftware.com/documentation/1410028.asp.
Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory on
your server (for example, c:\temp).
Extract the file to the c:\u2\ud##\sys\SYS_BP (where ## refers to the UniData major version. For
example, 61, 71, 72, etc.) directory using your preferred unzipping utility. If UniData is installed in
another location, change the path accordingly.
Log in to the sys account using telnet or execute a udt shell command in the sys directory on the
server.
Catalog the three XTOOLSUB programs, as follows:
▪
▪
▪
CATALOG SYS_BP XTOOLSUB FORCE
CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE
CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE
Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUB
FORCE command.
6.
Connect with your U2 client tool to the U2 database server.
Installing XTOOLSUB for UniVerse on Windows
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates.
However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
Procedure
1.
2.
3.
4.
5.
Download the latest version of XTOOLSUB from the public Tech Note site at https://
u2tc.rocketsoftware.com/documentation/1410028.asp
Copy the XTOOLSUB_UV_NT.zip or XTOOLSUB_UV_103_NT.zip file to a temporary directory on
your server. For example, c:\temp.
Extract the file to the c:\u2\uv\BP.O directory using your preferred unzipping utility. If UniVerse is
installed in another location, change the path accordingly.
Log in to the UV home account via Telnet. The account name is UV or uv in the UV.ACCOUNT file.
Catalog the three XTOOLSUB programs, as follows:
▪
▪
▪
CATALOG SYS_BP XTOOLSUB FORCE
CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE
CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE
Note: You will receive a catalog error if you try to catalog all three programs on the same
command line.
6.
If you are using UniVerse 10.3 or later, also run CATALOG BP *EDAMAPSUB FORCE command.
9
Chapter 3: XTOOLSUB
7.
Connect with your U2 client tool to the U2 database server.
Installing XTOOLSUB for UNIX/Linux for UniData
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates.
However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
The $UDTBIN referenced below is an environment variable pointing to your UniData bin directory, for
example, /usr/ud##/bin (where ##, is 61,71,72, etc.). If this variable is not set, then reference the full
path to the UniData bin directory in the commands.
Procedure
1.
2.
3.
Download the latest version of XTOOLSUB from the public Tech Note site at https://
u2tc.rocketsoftware.com/documentation/1410028.asp.
Copy the XTOOLSUB_UDT_UX.tar or XTOOLSUB_UDT_61_UX.tar file to a temporary directory on
your server (for example, /tmp). If transferring using ftp, remember to use binary format.
Extract the file to the $UDTHOME/sys/SYS_BP directory.
a.
4.
To install using UniData 6.1 or earlier, the commands will be:
cd $UDTHOME/sys/SYS_BP
tar -xvf /tmp/XTOOLSUB_UDT_61_UX.tar
b. To install UniData 7.1 or later, the commands will be:
cd $UDTHOME/sys/SYS_BP
tar -xvf /tmp/XTOOLSUB_UDT_UX.tar
If you are using a non-AIX operating system, run the convcode command, as shown: $UDTHOME/
sys/SYS_BP: $UDTBIN/convcode .
Note: The convcode command includes a period at the end of the line. This will convert
everything in the SYS_BP file to the current format. All files report that they were converted,
but this is the default answer for convcode. The existing files should already be in the correct
format.
5.
6.
Change directories to the $UDTHOME/sys directory and then and execute the UDT command, as
shown:
a. CD $UDTHOME/sys
b. $UDTBIN/udt
Catalog the three XTOOLSUB programs, as follows:
▪
▪
▪
CATALOG SYS_BP XTOOLSUB FORCE
CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE
CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE
Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUB
FORCE command.
7.
Connect with your U2 client tool to the U2 database server.
Installing XTOOLSUB for UNIX/Linux on UniVerse
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates.
However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
10
Installing XTOOLSUB on Windows
Procedure
1.
2.
3.
Download the latest version of XTOOLSUB from the public Tech Note site at https://
u2tc.rocketsoftware.com/documentation/1410028.asp
Copy the XTOOLSUB_UV_UX.tar or XTOOLSUB_UDT_UV_103_UX.tar file to a temporary directory
on your server (for example, /tmp). If transferring files using FTP, remember to use binary file
format.
Extract the file to the /usr/uv/BP.O directory. If UniVerse is installed in another location, change
the path accordingly. Use 'cat /.uvhome' to find the path if needed.
Note: `cat /.uvhome` references include single backward quotation marks. This command
retrieves the current value for the UniVerse home directory before running the command.
a.
5.
To install using UniVerse 10.3 or earlier, the commands to use are:
cd `cat /.uvhome`/BP.O
tar -xvf /tmp/XTOOLSUB_UV_103_UX.tar
b. To install using UniVerse 11.1 or later, the commands to use are:
cd `cat /.uvhome`/BP.O
tar -xvf /tmp/XTOOLSUB_UV_UX.tar
If you are using a non-AIX operating system, run the convcode command, as shown:
`cat /.uvhome`/bin/fnuxi XTOOLSUB*
Change directories to the UniVerse home directory and then and run the UV command, as shown:
6.
7.
a. cd `cat /.uvhome`
b. bin/uv
Click Escape to exit the menu.
Catalog the three XTOOLSUB programs, as follows:
4.
▪
▪
▪
CATALOG SYS_BP XTOOLSUB FORCE
CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE
CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE
Note: You will see a catalog error if you try to catalog all three programs on the same
command line.
8.
9.
If you are using UniVerse 10.3 or earlier, also run the CATALOG BP *EDAMAPSUB FORCE
command.
Connect with your U2 client tool to the U2 database server.
Installing XTOOLSUB on Windows
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates.
However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
Procedure
1.
2.
Download the latest version of XTOOLSUB from the public Tech Note site at https://
u2tc.rocketsoftware.com/documentation/1410028.asp
Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory on
your server (for example, c:\temp).
11
Chapter 3: XTOOLSUB
3.
4.
5.
Extract the file to the c:\u2\ud##\sys\SYS_BP (where ## refers to the UDT major version, i.e. 61, 71,
72, etc.) directory using your preferred unzipping utility. If UniData is installed in another location,
change the path accordingly.
Log into the sys account using telnet or execute a udt shell command in the sys directory on the
server.
Catalog the three XTOOLSUB programs, as follows:
▪
▪
▪
CATALOG SYS_BP XTOOLSUB FORCE
CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE
CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE
Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUB
FORCE command.
6.
12
Connect with your U2 client tool to the U2 database server.
Chapter 4: Adding and connecting to servers
This section describes how to create UniData and SOAP servers, and how to connect to those servers.
▪
From the Start menu, select All Programs > Rocket U2 > Web Services Developer.
A window similar to the following example appears:
Adding a UniData or UniVerse server
1.
From the U2 Web Services Developer window, right-click Servers > New U2 Server.
The Create New U2 Server dialog appears.
2.
3.
4.
In the Name field, enter a unique name of the UniVerse or UniData server.
In the Host field, enter a valid network name for the host.
Select either UniData or UniVerse to define the database you are using.
13
Chapter 4: Adding and connecting to servers
5.
If you want to define the Protocol Type, RPC port number, RPC Service Name, or the account to
access, click Advanced.
The following screen appears:
In the Protocol Type field, choose the type of communication you are using the server.
You can choose Default, TCP/IP, or Lan Manager. The default is TCP/IP.
7. In the RPC Port # field, enter the port number of the UniRPC server running on the host. The
default port number is 31438.
8. In the RPC Service Name field, enter the name of the RPC service on your system. For UniData,
this is normally udcs.
9. In the Login Account field, enter the name of the account to which you want to log on when
accessing UniVerse.
10. Click Add in the Commands to Execute box to enter commands you want to execute when you
log on to the server.
The following dialog box appears:
6.
11. Enter a command, then click OK.
12. In the Specify the session to run/debut your BASIC programs on server side area, specify the
type of connection you want to make to server. You can specify Telnet or SSH.
13. In the Port Number field, enter the port number you want to use if you do not want to use the
default port number of 23.
14. Select the Use Device License check box if you want to enable device licensing when connecting
to the server.
15. Click Finish to establish the UniData server.
The new server appears in the U2 Resource view of the Web Services Developer Tool.
16. Click Finish.
14
Connecting to the UniData or UniVerse database
Connecting to the UniData or UniVerse database
Make sure that UniVerse or UniData are running, and the unirpc daemon is started on the remote host.
1.
Double-click the server to which you want to connect to the database, then click Connect.
The Connect to U2 Server dialog box appears, as shown in the following example.
2.
In the User ID field, enter your log on name for the server. Enter the corresponding password
in the Password field. If you do not want to enter your user ID and password in subsequent
sessions, select the Remember Me check box.
Click Finish.
The existing accounts and globally cataloged programs appear under the UniVerse or UniData
server name, as shown in the following example:
3.
15
Chapter 4: Adding and connecting to servers
Creating a SOAP server
16
1.
In the U2 Web Services portion of the U2 Web Services Developer window, right-click Soap
Server, then click New SOAP Server.
The Add a New SOAP Server dialog box appears.
2.
In the Server Name field, enter a unique name for the SOAP server.
The remainder of the fields are populated based on information retrieved by the U2 Web Services
Developer tool. You can change any of these fields. The following table describes the fields.
Field
Description
URL
The URL for the SOAP server you specify. The URL is automatically detected
by the U2 Web Services Developer. We recommend that you not change the
URL unless you are sure the new URL you specify is valid and accessible.
Port Number
The port number on which the server will listen. We recommend that you
not change the port number unless that port number is used by another
service.
Root Path
The path to the root directory where the definitions to the web services are
stored.
Debug Log
Indicates whether to start the debug log. If you select true, U2 Web Services
Developer starts the debug log each time you start the server. To disable
the debug log when the server is running, right-click the SOAP server, then
select Turn Off SOAP Server Debug. You can also start the debug log when
the SOAP server is running, if it is disable. For more information, Viewing the
debug log, on page 19.
Log File Name
The name of the debug log file. By default, the name of the debug log file is
soapservername.log.
Creating a SOAP server
Field
Description
Connection
Pooling On
The Connection Pooling On setting determines whether UniData uses
connection pooling with the U2 Web Services Developer. The term
connection pooling refers to the technology that pools permanent
connections to data sources for multiple threads to share. It improves
application performance by saving the overhead of making a fresh
connection each time one is required. Instead of physically terminating a
connection when it is no longer needed, connections are returned to the
pool and an available connection is given to the next thread with the same
credentials.
Connection Pooling in enabled by default. If you do not want to use
Connection Pooling, clear the Connection Pooling On check box.
We recommend using Connection Pooling for superior performance and
scalability.
Connection Pool
Size
You can set the minimum and maximum size of the connection pool. If you
do not define these sizes, the minimum size defaults to 1 and the maximum
size defaults to 10. The minimum size determines the initial size of the
connection pool.
The size of the connection pool changes dynamically between the minimum
and maximum sizes you specify, depending on the system demands. When
there are no pooled connections available, UniData either creates another
connection, if the maximum connection pool size has not been reached, or
keeps the thread waiting in the queue until a pooled connection is released
or the request times out. If a pooled connection is idle for a specified time, it
is disconnected.
SOAP Request
Validation
Specifies whether the server needs to validate the SOAP request
before processing. If this value is set to true, you may experience slight
performance degradation, but will have an extra layer of security.
Default Name
Space
The name space for the Web Services you define.
Service Cache
Size
For performance purposes, you can set this value to a number greater than
0 to indicate the number of web service definitions you want to keep in the
cache. If you set this value, the SOAP Server will always try to read the web
service definition from the cache first. If you do not set this value, the SOAP
Server reloads the web service each time from disk.
If you are developing a web service, we recommend keeping this value at 0.
This setting forces the SOAP Server to reload the new web service definition
each time. Select the Cached Services tab to display the web services
currently loaded in cache.
17
Chapter 4: Adding and connecting to servers
3.
Click Next.
The SOAP Server - Connection Security dialog box appears.
Select the Use SSL check box if you want to define the SSL security parameters. The following
table describes the fields.
18
Field
Description
Key Store
Enter the full path to the key store on the SOAP server, or click Browse to
navigate to the key store.
Key Store
Password
Enter the password corresponding to the key store you defined in the Key
Store field.
Confirm Key
Store Password
Reenter the password corresponding to the key store you defined in the Key
Store field.
Key Password
Enter the encryption key password, if one exists.
Confirm Key
Password
Reenter the encryption key password, if one exists.
Enable
Authentication
If you want the client to send its certification for authentication, select the
Need Client Authentication check box.
4.
Click Next.
The U2 Database - Connection Properties dialog box appears.
5.
Select the Specify default database connection properties check box.
Viewing the debug log
6.
In the Host field, select host name from the list of available UniData or UniVerse servers.
The remaining fields in the dialog box are populated based on the information retrieved by the U2
Web Services Developer, as shown in the following example:
7.
To test the connection to the database, click Test Database Connection.
If successful, a message appears stating that a connection exists to the U2 server.
Viewing the debug log
You can enable the debug log when you create a new SOAP server. If you did not, you can also start
and use the debug log while the SOAP server is running.
If enabled, the debug log starts each time you start the server. The option to enable the debug log is
described in Creating a SOAP server, on page 16.
To use the debug log, do the following:
1.
Click Soap Server Log to display the SOAP Server Logs, as shown in the following example:
2.
3.
U2 Web Services developer displays the last 64KB in the SOAP Server log.
To erase the contents of the log file click the Erase icon.
To refresh the contents of the log file, click the Refresh icon.
Displaying cached services
When you define the properties for your SOAP server, you can specify the server cache size.
1.
For performance purposes, set the server cache size to the number of web services currently
running, or larger.
19
Chapter 4: Adding and connecting to servers
2.
3.
20
If you do not set this value, the SOAP Server reloads the web service each time. If you do set this
value, next time a web service is needed, the SOAP Server reads it from cache.
If you are developing a web service, it is recommend you keep this value at 0.
Otherwise, the SOAP Server reloads the cache each time the web service is changed.
Select the Cached Services tab to display the web services currently loaded in cache.
Chapter 5: Creating a query web service
This section describes how to create a web service using UniQuery or UniData SQL.
Note: You cannot publish a query that requires interactive user input as a web service.
Creating a query web service using drag-and-drop
1.
From the U2 Web Services Developer window, right-click the account for which you want to
create a web service. Expand the Database Files node to view the database files available in the
account, as shown in the following example:
2.
Drag the file for which you want to create a web service to the appropriate SOAP Server.
The Add a New Web Service dialog box appears.
3.
In the Service Name field, enter a name for the web service you are creating.
21
Chapter 5: Creating a query web service
4.
In the Namespace field, verify or enter the namespace. Click Finish.
When you click the service name, information about the SOAP service appears in the Web Service
portion of the U2 Web Services Developer dialog box, as shown in the following example:
5.
6.
By default, the U2 Web Services Developer creates a LIST statement which includes each D-Type
dictionary record contained in dictionary for the file you selected.
Click the query statement to view the details for the statement.
The Query Details dialog box appears.
UniData and UniVerse only support the UniQuery or UniVerse RetrieVe LIST and SORT commands,
or the SQL SELECT command.
If you want to add an input parameter:
a.
Modify the statement that appears in the Command Text field, as shown in the following
example:
The question mark acts as a placeholder for the input value. Press Ctrl+S to save the query,
or click the Save icon.
The input parameter now appears under the Web Service Input parameter, as shown in the
following example:
22
Creating a query web service using drag-and-drop
b.
Click the input parameter then click Edit.
The Define Parameter dialog box appears.
c.
In the Name field, enter a meaningful name of the input parameter.
This is the name for which you are prompted when you invoke the service.
In the Position field, enter the prompting order of the input parameter.
In the Type field, select the data type for the input parameter from the list. Valid types are
String and Dynamic array.
d.
e.
23
Chapter 5: Creating a query web service
Creating a query web service using the wizard
1.
To create a Query Web Service using the wizard, right-click the SOAP server where you want to
create the service, then click New Web Service.
The Add a New Web Service dialog box appears.
2.
3.
In the Service Name field, enter a name for the web service you are creating.
In the Namespace field, verify or enter the namespace. Click Finish.
The U2 Database - Connection Properties dialog box appears.
4.
24
If you have not defined the database connection properties at the SOAP Server-level, you must
define them for this Web Service. For more information about defining the data base connections
at the SOAP Server-level, see Creating a SOAP server, on page 16.
Select the Specify default database connection properties check box.
Creating a query web service using the wizard
5.
In the Host field, select host name from the list of available UniData or UniVerse servers.
The remaining fields in the dialog box are populated based on the information retrieved by the U2
Web Services Developer, as shown in the following example:
6.
To test the connection to the database, click Test Database Connection.
If successful, a message appears stating that a connection exists to the U2 server.
25
Chapter 5: Creating a query web service
7.
Click Next.
The SOAP Server - Connection Security dialog box appears.
Select the Use SSL check box if you want to define the SSL security parameters. The following
table describes the fields.
26
Field
Description
Key Store
Enter the full path to the key store on the SOAP server, or click Browse to
navigate to the key store.
Key Store
Password
Enter the password corresponding to the key store you defined in the Key
Store field.
Confirm Key
Store Password
Reenter the password corresponding to the key store you defined in the Key
Store field.
Key Password
Enter the encryption key password, if one exists.
Confirm Key
Password
Reenter the encryption key password, if one exists.
Enable
Authentication
If you want the client to send its certification for authentication, select the
Need Client Authentication check box.
Creating a query web service using the wizard
8.
Click Next.
The SOAP Server - Connection Security dialog box appears.
Select the Use SSL check box if you want to define the SSL security parameters. The following
table describes the fields.
9.
Field
Description
Key Store
Enter the full path to the key store on the SOAP server, or click Browse to
navigate to the key store.
Key Store
Password
Enter the password corresponding to the key store you defined in the Key
Store field.
Confirm Key
Store Password
Reenter the password corresponding to the key store you defined in the Key
Store field.
Key Password
Enter the encryption key password, if one exists.
Confirm Key
Password
Reenter the encryption key password, if one exists.
Enable
Authentication
If you want the client to send its certification for authentication, select the
Need Client Authentication check box.
Click Next.
The Operation dialog box appears.
10. In the Name field, enter the name for the web service you are creating.
27
Chapter 5: Creating a query web service
11. From the Type options, select Query.
12. In the Query area, define the query command:
In the Command field, enter the UniQuery or UniData SQL statement.
At this release U2 Web Services Developer only supports the UniQuery’s LIST and SORT
commands, or the UniData SQL SELECT statement. If you want to add an input parameter,
use a question mark as a placeholder for the input value.
b. Optional: In the Map FileName field, enter the name of the mapping file you want to use,
located in the _XML_ directory.
c. Optional: In the Record Name field, enter the name of the root element in the XML
document the web service creates for the query you specify. If you have two or more query
operations within the same web service using the same data file, make sure the record name
is different for each operation.
d. Press Ctrl+S to save the query, or click the Save icon.
13. Click Next.
The Input/Output Parameters dialog box appears.
a.
14. Click Finish.
The web service definition appears in the Web Service area of U2 Web Services Developer
window.
28
Starting the web service
15. If you specified a placeholder in the web service command, click the input parameter, then click
arg_1.
The Parameter Details dialog box appears.
16. In the Name field, enter a meaningful name of the input parameter.
This is the name for which you are prompted when you invoke the service.
17. In the Position field, enter the prompting order of the input parameter.
18. In the Type field, select the data type for the input parameter from the list. Valid types are String
and Dynamic array.
Starting the web service
1.
2.
3.
To start a web service, click the Launch icon from the toolbar.
The Web Services Explorer window appears.
Click the WSDL icon.
Under the Navigator area of the Web Services Explorer window, click WSDL Main.
The Open WSDL dialog box appears.
29
Chapter 5: Creating a query web service
4.
From the U2 Web Service area of the Web Services Developer window, click the highlighted web
service.
The properties of the web service appear in the Properties area of the Web Service window, as
shown in the following example:
The Web Service operation prompts you for input parameters you previously defined, as shown in
the following example:
30
5.
Enter the input value, then click GO.
The U2 Web Services Developer displays the resulting XML document in the Status area of the
Invoke a WSDL Operation dialog box, as shown in the following example:
6.
Click Source to view the XML source for the output.
Chapter 6: Creating a Subroutine web service
This section describes how to create a web service using a UniBasic subroutine.
Note: You cannot publish a subroutine that requires interactive user input as a web service.
Creating a subroutine web service using drag-and-drop
About this task
In this example, the following subroutine is used:
SUBROUTINE CUSTOMERSUB(ID, REC)
OPEN "CUSTOMER" TO F.CUST ELSE REC = ""
READ REC FROM F.CUST, ID ELSE REC = ""
CLOSE F.CUST
RETURN
Procedure
1.
From the U2 Web Services Developer window, right-click the account for which you want to create
a web service. Expand the Cataloged Program node to view the subroutines available in the
account, as shown in the following example:
Note:
You must catalog the subroutine before you start the U2 Web Services Developer. You can
globally, locally, or directly catalog subroutines.
For information about cataloging UniBasic programs, see UniData Commands Reference. For
information about cataloging UniVerse BASIC programs, see UniVerse User Reference.
31
Chapter 6: Creating a Subroutine web service
2.
Drag the subroutine for which you want to create a web service to the appropriate SOAP Server,
as shown in the following figure.
3.
4.
In the Service Name field, enter a name for the web service you are creating.
Click Finish.
Because the program is globally cataloged, the Connection Properties dialog box appears. When
the subroutine is not globally cataloged, the Connection Properties dialog box does not appear.
Select the Specify default database connection properties check box.
Verify the Account field to make sure it defines the account you want to execute the subroutine
against, then click Finish.
5.
6.
32
Defining subroutine parameters
7.
In the Namespace field, verify or enter the namespace. Click Finish.
When you click the service name, information about the SOAP service appears in the Web Service
portion of the U2 Web Services Developer dialog box, as shown in the following example:
Defining subroutine parameters
1.
Click the subroutine for which you are defining parameters.
The Subroutine Details dialog box appears.
2.
3.
In the Subroutine Name field, enter the name of the subroutine.
In the Number of Parameters field, enter the total number of parameters defined for the
subroutine.
In the example subroutine, there are two parameters, one input, and one output.
From the Input area, click Add.
The Define Parameter dialog box appears.
4.
a.
In the Name field, enter a meaningful name of the input parameter.
33
Chapter 6: Creating a Subroutine web service
This name does not have to be the same as the one defined in the UniBasic program.
In the Position field, enter the position the input parameter appears in the subroutine.
In the Type field, select the data type for the input parameter from the list. Valid types are
String and Dynamic array.
d. Click OK.
From the Output area of the Subroutine Details dialog box, click Add.
The Define Parameter dialog box appears.
b.
c.
5.
a.
b.
c.
d.
e.
34
In the Name field, enter the name of the output parameter.
In the Position field, enter the position of the output parameter in the subroutine.
In the Type field, enter the data type of the output parameter.
In this example, the output parameter is a dynamic array.
In the Dynamic Array Name field, enter the name of the dynamic array.
You can choose an existing dynamic array, or create a new one. If the dynamic array that you
specify does not exist, the following message appears.
Click Yes to define the new dynamic array.
The name of the array appears under the Dynamic Arrays area of the Web Services window,
as shown in the following example:
Defining subroutine parameters
6.
Double-click the dynamic array for which you want to define fields.
The Dynamic Array Fields dialog box appears.
7.
To manually add a field, click Add.
The Define Field dialog box appears.
a.
b.
c.
d.
In the Name field, enter the name of the field in the dynamic array.
In the Location field, enter the location of the field in the dynamic array.
In the Type field, enter the type of field. Valid types are String and Dynamic array.
Click OK.
35
Chapter 6: Creating a Subroutine web service
8.
To populate the fields, from the Database Files in the account for which you are creating the web
service, drag-and-drop the file pertaining to the dynamic array.
The U2 Web Services Developer populates the U2 Dictionary dialog box with each D-type
dictionary record, as shown in the following example.
9.
Select the check boxes next to the dictionary record ID you want to include in the dynamic array.
The number of attributes you select must match the number of fields in the parameter in the
subroutine. In this example, the entire record should be returned, so each dictionary attribute is
selected except for the CUSTID.
10. Press Ctrl+S to save the query, or click the Save icon.
Results
When you have finished defining the parameters of the subroutine, the input parameters, output
parameters, and dynamic arrays appear in the Web Services area of the U2 Web Services Developer
window, as shown in the following example:
Creating a subroutine web service using the wizard
1.
2.
3.
To create a query web service using the wizard, right-click the SOAP server where you want to
create the service, then click New Web Service.
In the Service Name field, enter a name for the web service you are creating.
In the Namespace field, verify or enter the namespace. Click Next.
The U2 Database - Connection Properties dialog box appears.
If you have not defined the database connection properties at the SOAP Server-level, you must
define them for this Web Service. For more information about defining the data base connections
at the SOAP Server-level, see Creating a SOAP server, on page 16.
36
Creating a subroutine web service using the wizard
Select the Specify default database connection properties check box.
In the Host field, select the name of the host server from the list of UniData servers you have
defined.
The server should be running.
6. In the Account field, select the account name of the UniData server you specified where you want
to attach when you connect from the list.
This account must contain the data files that you are accessing with the subroutine.
7. In the User ID field, type your login name for the server. Type the corresponding password in the
Password field.
8. In the UniRPC Service Name field, type the appropriate UniRPC service name.
For UniData, the service name is uvcs. For UniData, the service name is udcs.
9. In the UniRPC Port Number field, type the port number of the UniRPC server running on the host.
The default port number is 31438.
10. To test the connection to the database, click Test Database Connection.
If successful, a message appears stating that a connection exists to the U2 server.
11. Click Next.
The U2 Database - Connection Properties dialog box appears.
4.
5.
Select the Use SSL check box if you want to define the SSL security parameters. The following
table describes the fields.
Field
Description
Key Store
Enter the full path to the key store on the SOAP server, or click Browse to
navigate to the key store.
Key Store
Password
Enter the password corresponding to the key store you defined in the Key
Store field.
Confirm Key
Store Password
Reenter the password corresponding to the key store you defined in the Key
Store field.
Key Password
Enter the encryption key password, if one exists.
Confirm Key
Password
Reenter the encryption key password, if one exists.
Enable
Authentication
If you want the client to send its certification for authentication, select the
Need Client Authentication check box.
12. Click Next.
The Operation dialog box appears.
13. In the Name field, enter the name for the web service you are creating.
37
Chapter 6: Creating a Subroutine web service
14. From the Type options, select Subroutine.
15. In the Subroutine Name field, type the name of the subroutine.
16. In the Number of Parameters field, type the total number of parameters defined for the
subroutine.
In this example subroutine, there are two parameters, one input, and one output.
17. Click Next.
The Input/Output Parameters page appears.
18. From the Input area, select the parameter, then click Edit.
The Define Parameter dialog box appears.
In the Name field, enter a meaningful name of the input parameter.
This name does not have to be the same as the one defined in the UniBasic program.
b. In the Position field, enter the position of the output parameter in the subroutine.
c. In the Type field, select the data type for the input parameter from the list. Valid types are
String and Dynamic array.
d. Click OK.
19. From the Output area, select the parameter, then click Edit.
The Define Parameter dialog box appears.
a.
a.
b.
c.
d.
e.
38
In the Name field, enter the name of the output parameter.
In the Position field, enter the position of the output parameter in the subroutine.
In the Type field, enter the data type of the output parameter.
In this example, the output parameter is a dynamic array.
In the Dynamic Array Name field, enter the name of the dynamic array.
You can choose an existing dynamic array, or create a new one. If the dynamic array that you
specify does not exist, the following message appears.
Click Yes to define the new dynamic array.
The name of the array appears under the Dynamic Arrays area of the Web Services window,
as shown in the following example:
Creating a subroutine web service using the wizard
20. Double-click the dynamic array for which you want to define fields.
The Dynamic Array Fields dialog box appears.
21. To manually add a field, click Add.
The Define Field dialog box appears.
a.
b.
c.
In the Name field, enter the name of the field in the dynamic array.
In the Location field, enter the location of the field in the dynamic array.
In the Type field, enter the type of field. Valid types are:
▪ s - Single-valued
▪ mv - Multivalued
▪ ms - Multi-subvalued
d. Click OK.
22. To populate the fields, from the Database Files in the account for which you are creating the web
service, drag-and-drop the file pertaining to the dynamic array.
The U2 Web Services Developer populates the U2 Dictionary dialog box with each D-type
dictionary record, as shown in the following example.
23. Select the check boxes next to the dictionary record ID you want to include in the dynamic array.
The number of attributes you select must match the number of fields in the parameter in the
subroutine. In this example, the entire record should be returned, so each dictionary attribute is
selected except for the CUSTID.
24. Press Ctrl+S to save the query, or click the Save icon.
39
Chapter 6: Creating a Subroutine web service
Results
When you have finished defining the parameters of the subroutine, the input parameters, output
parameters, and dynamic arrays appear in the Web Services area of the U2 Web Services Developer
window, as shown in the following example:
Starting the web service
1.
2.
3.
40
To start a web service, click the Launch icon from the toolbar.
The Web Services Explorer window appears.
Click the WSDL icon.
Under the Navigator area of the Web Services Explorer window, click WSDL Main.
The Open WSDL dialog box appears.
4.
From the U2 Web Service area of the Web Services Developer window, click the highlighted web
service.
The properties of the web service appear in the Properties area of the Web Service window, as
shown in the following example:
5.
6.
In the WSDL URL dialog box, enter the value of the End Point property, then click Go.
In the WSDL Details window, select the operation you want to execute, as shown in the following
example:
Starting the web service
7.
Click the operation that you want to execute.
In this case, CALL CUSTOMERSUB.
The Web Service operation prompts you for input parameters you previously defined.
8.
Enter the input value, then click GO.
The U2 Web Services Developer displays the resulting XML document in the Status area of the
Invoke a WSDL Operation dialog box, as shown in the following example:
41
Chapter 7: Viewing properties and dictionaries
This section describes how to view the properties of accounts, servers, and files, and the file
dictionaries.
Server properties
To display the properties of a server, select the server for which you want to display properties.
The properties of that server appear in the Properties area of the U2 Web Services Developer window,
as shown in the following example:
Property
Value
Database Name
The name of the server you created.
Database Type
The type of database to which you are connected. Valid types are
UniVerse or UniData.
Host
The host name.
Version
The version number of the Database Type to which you are connected.
XTOOLSUB
The version of the XTOOLSUB server subroutine.
Account properties
To display the properties of an account, click the account for which you want to display properties.
The properties of that account appear in the Properties area of the U2 Web Services Developer
window, as shown in the following example:
Property
Value
Account Name
The name of the account on the server.
Account Path
The full path to the account on the server.
File properties
To display the properties of a file, click the account where the file resides, then click the file for which
you want to display properties
The properties of that file appear in the Properties area of the Web Services Developer window, as
shown in the following example:
42
File dictionaries
Property
Value
Data File Path
The path to the file. If the file resides locally, this field displays the name
of the file. If the file resides in a remote location, this field displays the
full path to the file.
Dictionary Path
The name of the dictionary for the file you selected.
File Name
The name of the file.
File Type
The type of file.
Is EDA File?
Indicates whether the file is an EDA file.
File dictionaries
To display the dictionary of a file, click the file for which you want to display the dictionary, the click
the U2 Dictionary tab.
Information similar to the following example appears:
Property
Value
ID
Dictionary record ID
TYPE
Type of dictionary record.
LOC
Field location of the dictionary record if a D-type record, formula if an Itype record, or association components if a PH-type record.
CONV
Conversion formula, if specified.
NAME
Display name, if specified.
FORMAT
Format code.
SM
Single-valued multivalued, or multi-subvalued code.
ASSOC
Association name, if part of an association.
43
Chapter 8: Manually accessing the web services
The section describes how to access web services programmatically. A defined web service is
identified by its URL.
The format of the URL is:
SOAPserverURL/virtual_directory_path/servicename
Variable
Description
SOAPserverURL
Defined when you create a new SOAP server.
virtual_directory_path
A path relative to the configurable root directory of the SOAP server.
servicename
The name of the web service.
You can identify the URL for the web service from the U2 Web Services Developer.
Viewing the web service URL
You can use the U2 Web Services Developer main window to view the URLs for your web services, as
shown in the following example:
1.
2.
3.
4.
Open the U2 Web Services Developer main window.
Expand the web server where the web service is located.
Click the web service for which you want to view the URL.
Select the Properties tab.
The URL for the web service appears in the End Point field.
Viewing the WSDL file
You can use a web browser to view WSDL files.
▪
Type the URL in a browser.
The contents of the WSDL file appears.
Web services clients
To write a Web Services client program, you create an object of a proxy class, then call the methods for
that object.
Many software tools can accept a WSDL file and generate proxy classes in many kinds of languages,
including Java, C#, VB.NET, and so forth.
Proxy classes can be generated automatically because the definition contained in a WSDL file gives a
complete description of the interfaces to the Web service you define, including the XML schemas of the
input and output data, the SOAP bindings to these schemas, the transportation protocol, and so forth.
The proxy classes include a service proxy class, as well as several classes that represent data
structures used in the web services. These classes are self-explanatory.
44
Generating a client proxy in IBM Websphere Application Developer
Generating a client proxy in IBM Websphere Application Developer
1.
2.
3.
To generate a Web Service client proxy in IBM Websphere Application Developer, select New.
Select the web service client and the project type.
Follow the steps in the wizard, and provide the URL of the WSDL file.
For more information, see the documentation for the IBM Websphere Application Developer.
Generating a client proxy in Visual Studio.NET
1.
2.
To generate a Web Service client proxy in Visual Studio.NET, start a new project, then add a Web
Reference.
The Add Web Reference wizard prompts for the URL for the WSDL file.
Provide the URL. The wizard generates a set of proxy classes for the current project.
For more information, see the documentation or Visual Studio .NET.
45
Chapter 9: Deploying web services
The U2 Web Services Developer deployment feature enables you to select a SOAP server defined
locally and generate a deployment package, in the form of a zip file, that contains the following:
▪
▪
▪
WSDL files
The runsoapserver and stopsoapserver scripts
All required files for a runtime SOAP server
The zip file contains both a .bat and .sh script which enables you to deploy your web services on
any platform.
Exporting web services
You can create a zip file to deploy your web services.
1.
Right-click the SOAP server that contains the web service you want to deploy, and select Export.
The Export SOAP Servers dialog box appears.
2.
3.
In the Available SOAP Servers section, select the SOAP servers you want to export.
Enter the path for the zip file you want to create in the Archive File field, or click Browse to
search for the location.
By default, the U2 Web Services developer places the zip file in C:\U2\U2Tools
\v3\soapservername.zip.
The zip file contains the following contents:
▪
46
runtime
Importing web services
▪
▪
▪
▪
▪
▪
▪
▪
▪
▪
▪
▪
u2soap_deploy
servername_deploy_config.xml
runsoapserver.bat
stopsoapserver.bat
rundeploytool.bat
runsoapserver.sh
stopsoapserver.sh
rundeploytool.sh
u2soapservice.exe
vcredist_x86.exe
EncodingMap.txt
U2SOAP_deploy.config
Importing web services
After exporting a SOAP web service from the source development system, you can import it on the
target developer web service system. The zip file must be extracted on the target system. For example
c:\temp.
Prerequisite
▪
▪
▪
▪
▪
Before importing, the SOAP server must be created on the target computer.
The SOAP server name must match that of the source SOAP server.
The credentials of the target's database connection must be the same as the source developer
system.
Only the web services can be imported, not complete SOAP servers and their services.
If a web service of the same name already exists, it will be overwritten.
Procedure
1.
2.
3.
Right-click the SOAP server that contains the web service that you to import, and select Import.
Click Browse to select the root directory for the SOAP server(s) that you want to import.
for example, C:\temp\Test\u2soapdeploy.
Select the servers that you want to import, and then click Finish.
Deploying the SOAP server
1.
Extract the zip file on the target machine.
2.
From the directory where you unzipped the file, execute the rundeploytool command:
rundeploytool current_directory target_directory
For example,
rundeploytool.bat . C:\temp\myservice
47
Chapter 9: Deploying web services
3.
Expand Deployable SOAP Servers, right-click the SOAP server you want to deploy, then click
Deploy.
If the SOAP server already exists, click Deploy Into.
The U2 SOAP Service Deployment dialog box appears.
4.
The Deployment tool populates the window with information from your local machine. You can
change this information if necessary. After making all configuration selections, click Next.
The configuration options are described in the following table.
Configuration options
Description
Server Name
The name of the SOAP server.
Site URL
The URL for the SOAP server you specify. Make sure the URL you
specify is valid and accessible.
Port Number
The port number on which the server will listen.
Root Path
The path to the root directory where the definitions to the web service
are stored.
Debug On
Select the Debug On check box if you want to capture debugging
information. If you select this check box, the U2 Web Services
Developer starts the debug log each time you start the server.
Log File Name
The name of the debug log.
Connection Pooling
On
The Connection Pooling On setting determines whether a U2
database uses connection pooling with the U2 Web Services
Developer. The term connection pooling refers to the technology that
pools permanent connections to a data source for multiple threads
to share. It improves application performance by saving the overhead
of making a fresh connection each time one is required. Instead of
physically terminating a connection when it is no longer needed,
connections are returned to the pool and an available connection is
given to the next thread with the same credentials.
Connection Pooling in enabled by default. If you do not want to use
Connection Pooling, clear the Connection Pooling On check box.
It is recommended you use Connection Pooling for superior
performance and scalability.
48
Updating the SOAP server
Configuration options
Description
Connection Pool Size
You can set the minimum and maximum size of the connection pool. If
you do not define these sizes, the minimum size defaults to 1 and the
maximum size defaults to 10. The minimum size determines the initial
size of the connection pool.
The size of the connection pool changes dynamically between the
minimum and maximum sizes you specify, depending on the system
demands. When there are no pooled connections available, UniData
either creates another connection, if the maximum connection pool
size has not been reached, or keeps the thread waiting in the queue
until a pooled connection is released or the request times out. If a
pooled connection is idle for a specified time, it is disconnected.
Message Validation
Checks the SOAP request again the schema defined in the WSDL file.
This option is time consuming. By default, message validation is not
selected.
Default Name Space
The name space for the Web Services you define.
Server Cache Size
For performance purposes, you can set this value to a number greater
than 0 to indicate the number of web service definitions you want to
keep in the cache. If you set this value, the SOAP Server will always try
to read the web service definition from the cache first. If you do not
set this value, the SOAP Server reloads the web service each time from
disk.
If you are developing a web service, it is recommended you keep this
value at 0. This setting forces the SOAP Server to reload the new web
service definition each time. Select the Cached Services tab to display
the web services currently loaded in cache.
Updating the SOAP server
You can update the configuration file used to deploy the SOAP server from the development computer
to the deployment environment. The configuration file holds information such as server name, port
number, and connection pool information.
1.
2.
3.
Open the Web Services Developer tool.
In the U2 Web Services pane, right-click the resource you want to update and then select
Properties.
Follow the menu prompts and update the SOAP server information as needed.
49
Chapter 9: Deploying web services
Defining security between the client and the SOAP
server
1.
Click the Specify Connection Security check box if you want to define connection security
between the client and the SOAP server.
The SOAP Server Connection Security dialog box appears.
2.
Select the Use SSL check box if you want to define the SSL security parameters.
The following table describes the parameters.
3.
50
Field
Description
Key Store
Enter the full path to the key store on the SOAP server, or click Browse to
navigate to the key store.
Key Store
Password
Enter the password corresponding to the key store you defined in the Key
Store field.
Confirm Key
Store Password
Reenter the password corresponding to the key store you defined in the Key
Store field.
Key Password
Enter the encryption key password, if one exists.
Confirm Key
Password
Reenter the encryption key password, if one exists.
Enable
Authentication
If you want the client to send its certification for authentication, select the
Need Client Authentication check box.
Click Finish.
Setting connection properties
Setting connection properties
1.
Click the DB Connection tab to define the connection properties for the SOAP server.
The U2 Database - Connection Properties dialog box appears.
2.
In the Host field, select the name of the host server from the list of UniData servers you have
defined.
The server should be running.
In the Account field, select the account name of the UniData server you specified where you want
to attach when you connect from the list.
This account must contain the data files that you are accessing with the subroutine.
In the User ID field, type your login name for the server. Type the corresponding password in the
Password field.
In the UniRPC Service Name field, type the appropriate UniRPC service name.
For UniData, the service name is uvcs. For UniData, the service name is udcs.
In the UniRPC Port Number field, type the port number of the UniRPC server running on the host.
The default port number is 31438.
To test the connection to the database, click Test Database Connection.
If successful, a message appears stating that a connection exists to the U2 server.
If you want to use the connection properties you specified for subsequent SOAP servers you
deploy, select the Use this database connection and security for subsequent SOAP services
during deployment check box.
Click Next.
3.
4.
5.
6.
7.
8.
9.
51
Chapter 9: Deploying web services
Defining UniData database connection security
1.
Click the DB Security tab if you want to define security between the SOAP server and the
UniVerse database.
The U2 Database Connection Security dialog box appears.
2.
Select the Use SSL check box if you want to define the SSL security parameters.
The following table describes the parameters.
3.
Field
Description
Key Store
Enter the full path to the key store on the SOAP server, or click Browse to
navigate to the key store.
Key Store
Password
Enter the password corresponding to the key store you defined in the Key
Store field.
Confirm Key
Store Password
Reenter the password corresponding to the key store you defined in the Key
Store field.
Key Password
Enter the encryption key password, if one exists.
Confirm Key
Password
Reenter the encryption key password, if one exists.
Enable
Authentication
If you want the client to send its certification for authentication, select the
Need Client Authentication check box.
Click Next.
Results
U2 Web Services Developer deploys the web services you specified. When deployment is complete, a
window similar to the following example appears:
52
Deploying the SOAP service as a Windows service
The deployable web services appear in the SOAP Servers area of the U2 SOAP Service Deployment
dialog box, and shown in the following example:
Deploying the SOAP service as a Windows service
The u2soapservice.exe is an executable program that is used to create or remove a SOAP service
as a Windows service. It is located in the zip file that was created during the export process.
Prerequisite
▪
▪
▪
The SOAP server must have already been deployed.
On Windows 7 and Windows 2008, you must run the Windows Command Prompt as an
administrator. To do this, click Start > Accessories > Command Prompt. Right-click the
Command Prompt option and select Run as administrator.
Java Development Kit 1.6. If you do not already have JDK 1.6 installed, you must complete the
following steps:
1.
2.
3.
4.
5.
6.
Download and install the Java Development Kit, version 1.6 from the Oracle archive download
site.
Locate the javaw.exe file in C:\Program Files\Java\jdk1.6.0_45\bin.
Navigate to Control Panel > System > Advanced system settings and then click
Environment Variables.
Locate the System Variable called Path and click Edit.
Add the location of javaw.exe to the end of the list. For example, add C:\Program
Files\Java\jdk1.6.0_45\bin.
Click OK. For this to take effect, the machine must be rebooted.
53
Chapter 9: Deploying web services
About this task
Note: A Windows service can only be created on a deployed package.
The syntax for creating a SOAP service is as follows:
U2soapservice.exe –i u2soap-server-name [-s u2soap-service-name] [-d
“u2soap-service-description”]
The following table lists the options available for deploying a SOAP server as a Windows service.
Option
Description
-i
Installs a new U2 SOAP service as a Windows service.
-s
The name of the U2 SOAP service.
-d
Description of the U2 SOAP service. The default value is “U2 SOAP service
to start and stop U2 SOAP serverâ€. The text of the description must be
enclosed in quotation marks (“â€).
-r
Removes the U2 SOAP service.
After installing the U2 SOAP service, it can started and stopped as a Windows service from
the Windows control panel. When the service starts, it runs the runsoapserver.bat
u2soap-server program and waits until this bat file exits. When the service stops, it runs the
stopsoapserver.bat u2soapserver program. Additional arguments can be passed to the
runsoapserver.bat by specifying the start parameters to the service.
Note: If you are creating a Windows service using the u2soapservice.exe program and you
get an error similar to the one shown below, you must run the vcredist_x86.exe program
supplied with the U2 WSD product to ensure the Windows platform has the compatible Microsoft
Visual C++ 2005 redistributable runtime environment:
Error: The application has failed to start because its side-by-side configuration is incorrect. Please see
the application event log for more details.
The syntax for removing a U2 SOAP service is as follows:
U2soapservice.exe –r u2soap-server
Deploying the SOAP service from the command line
Use the command line options to deploy the U2 SOAP server from the development computer to the
deployment environment. The command line options allow for option-driven, interactive command
line deployment.
Starting the SOAP service from the command line
1.
After exporting the SOAP services, extract the zip file on to the target machine.
The zip file contains the following contents:
▪
▪
▪
▪
54
runtime
u2soap_deploy
servername_deploy_config.xml
runsoapserver.bat
Starting the SOAP service from the command line
▪
▪
▪
▪
▪
▪
▪
▪
▪
stopsoapserver.bat
rundeploytool.bat
runsoapserver.sh
stopsoapserver.sh
rundeploytool.sh
u2soapservice.exe
vcredist_x86.exe
EncodingMap.txt
U2SOAP_deploy.config
Note: Some OS environments, such as those running UNIX, cannot use zip files. If this occurs,
recompress the file with a non-zip extraction tool such as 7zip into a gz (gzip) type file.
2.
3.
Navigate to the server directory where you extracted the zip file and locate the U2 SOAP
deployment tool.
Run the rundeploytool command, as shown in the following example:
rundeploytool.bat . C:\temp\myservice -s testserver -t prodserver
The following table describes each parameter of the syntax:
rundeploytool[.sh | .bat] deployable_server_dir [target_server_dir]-s server_name [-t target_server] [-f config_file [-u] ]
Option
Description
rundeploytool[.bat
| .sh]
The command to start the deployment tool. Use the .bat script for
Windows applications and the .sh script for UNIX/Linux applications.
deployable_server_dir
The current directory. This can be either the full path or a dot (.) for
current directory.
target_server_dir
The target directory where you want to deploy your U2 SOAP service.
-s source_server_name The name of the source server.
4.
-t target_server_name
The name of the server on which the U2 SOAP server will be deployed.
-f config_file
(Optional). Add this parameter to input all data from the configuration
file.
-u
The parameter to manually change the database connection
credentials. This requires using the -f parameter If the -u parameter is
not included in the command, while the connection credentials will be
visible, they will not be editable.
-l
Lists the servers available for deployment.
The U2 SOAP server configuration options open in the command line window.
Select the appropriate command-line option, as described in the following table.
Command line option
Description
X
eXit.
A
Accept. When all of the configuration options are set correctly, click A
to continue to the next set of configuration options.
1
Server name. A unique name for your SOAP server.
The Site URL field displays the valid URL for the SOAP server. You
cannot change the information in this field.
55
Chapter 9: Deploying web services
Command line option
Description
2
Port number. The port number on which the server will listen.
Root Path. Displays the path to the root directory where the
definitions to the Web service are stored. You cannot change the
information in this field.
3
Debug on. Set this value to true to turn on the debug log. Set this
value to false to turn the log off. By default, this value is set to false.
4
Log file name. Edit the name of the log file. By default, the name of the
log file is defined by the name of the target server.
5
Connection Pooling On. Set this value to true to enable connection
pooling. 6
Minimum Connection Pool Size. Sets the minimum number of
connections in the connection pool. The minimum size defaults to 1.
7
Maximum Connection Pool Size. Sets the maximum number of
connections in the connection pool. The minimum size defaults to 10.
8
Checks the SOAP request again the schema defined in the WSDL file.
This option is time consuming. By default, message validation is not
selected.
9
The name space for the Web Services you define.
10
For performance purposes, you can set this value to a number greater
than 0 to indicate the number of web service definitions you want to
keep in the cache. If you set this value, the SOAP Server will always try
to read the web service definition from the cache first. If you do not
set this value, the SOAP Server reloads the web service each time from
disk.
If you are developing a web service, we recommend keeping this value
at 0. This setting forces the SOAP Server to reload the new web service
definition each time. Select the Cached Services tab to display the
web services currently loaded in cache.
5.
After making any changes to the deployment configuration options, click A to continue.
Defining connection security between the client and the SOAP server
from the command line
After defining the connection configuration, you can define the connection security for the SOAP
server.
1.
2.
56
The U2 SOAP connection security options open in the command line window. Select S to view the
security options.
Select the appropriate action from the options presented in the command line window, as
described in the following table.
Command line option
Description
X
eXit.
D
Do not specify connection security. Select this option if connection
security is not required.
1
Use SSL. Select this option to turn on SSL.
2
Key Store. Enter the name of the Key Store.
Defining database connection properties from the command line
Command line option
Description
3
Key Store password. Enter the password for the Key Store.
4
Key Password. Enter the password for the Key.
Use Default Trust Store. Set this value to true to use the default trust
store.
5
3.
Need Client Authentication. Set this value to true for the client to send
its certification for authorization.
After defining any connection security settings for the server, enter A to continue.
Defining database connection properties from the command line
After defining the server connection properties, you can define the properties for the selected resource
folder.
The Resource folder property options open in the command line window.
1.
2.
Select the appropriate action from the options presented in the command line window, as
described in the following table:
Command line option
Description
X
Exit.
A
Accept. Accepts the options as defined.
D
Do not specify a default database connection. Select this option if
connection security is not required.
T
Test. Tests the database connection.
U
Use this database connection and security for subsequent SOAP
services during deployment.
1
The name of the U2 data server to which you are connecting.
2
The name of the U2 account to which you are connecting.
3
The name of the UniRPC service to which you are connecting.
4
The port number to which you are connecting.
5
The correct user name.
6
The correct password.
7
Select the check box to use SSL.
8
The type of encoding, if any, to use for this web service from the Client
Encoding list.
After defining any connection security settings for the server, enter A to continue.
Defining database connection security
After defining the database connection properties, you can define the security for the U2 database
connection.
1.
2.
Select S from the command line options to access the connection security from the command
line.
Select the appropriate action from the options presented in the command line window, as
described in the following table:
57
Chapter 9: Deploying web services
Command line option
Description
X
Exit.
D
Do not specify connection security. Select this option if connection
security is not required.
1
Use SSL. Select this option to turn on SSL.
2
Key Store. Enter the name of the Key Store.
3
Key Store password. Enter the password for the Key Store.
4
Key Password. Enter the password for the Key.
Use Default Trust Store. Set this value to true to use the default trust
store.
5
Need Client Authentication. Set this value to true for the client to send
its certification for authorization.
Deploying from the command line
After any required changes are made to the Resource folder properties, the U2 SOAP server is ready to
deploy on the deployment environment.
The Resource folder property options open in the command line window.
Procedure
▪
Select the appropriate action from the options presented in the command line window, as
described in the following table.
Command line option
Description
X
Exit.
G
Generate configuration file. This option generates an XML file,
server_name_ deploy_configuration.xml, that contains
all of the configuration information. Select this option to make
changes to the configuration file before deploying.
C
Continue. This option deploys the server to the deployment
environment.
Results
The U2 SOAP server was deployed to the deployment environment.
Deploying a SOAP server from a configuration file
A U2 SOAP service can be deployed onto a deployment environment using a generated configuration
file. The configuration file is an XML file, server_name_ deploy_configuration.xml, that
contains all of the configuration information. The configuration file specifies values that can be
changed during deployment, such as login credentials.
58
Generating a configuration file
Generating a configuration file
Use the U2 SOAP deployment tool to generate a configuration file that can be used to deploy the U2
SOAP server from the development computer to the deployment environment.
1.
Extract the zip file on to the target machine.
The contents of the zip file are extracted into the u2soapdeploy folder, which should contain
the following files:
▪
▪
▪
▪
▪
▪
▪
▪
▪
▪
▪
▪
2.
3.
4.
5.
6.
7.
rundeploytool.bat
rundeploytool.sh
runsoapserver.bat
runsoapserver.sh
runtime
stopsoapserver.bat
stopsoapserver.sh
u2soap
U2SOAP_deploy.conf
u2soap_workspace
u2soapservice.exe
vcredist_x86.exe
Navigate to the server directory where you extracted the zip file and locate U2SOAP deployment
tool. Run the rundeploytool command, as shown in the following example:
rundeploytool.bat . C:\temp\myservice
The following table describes each parameter of the syntax:
rundeploytool[.sh | .bat] deployable_server_dir
source_target_directory.
Parameter
Description
rundeploytool[.bat | .sh]
The command to start the deployment tool. Use the .bat script for
Windows applications and the .sh script for UNIX/Linux applications.
deployable_server_dir
The current directory. This can be the full path or a dot (.) for the
current directory.
source_target_directory
The directory where the deployable U2 SOAP server will be located.
Running the command opens the U2 Web Services Developer tool.
Expand the Deployable SOAP Servers node in the SOAP servers pane. Right-click the SOAP
server you want to deploy, then click Generate configuration file. Click Browse to select a different configuration file or accept the default configuration file. Click
Next.
The SOAP Server Configuration dialog box opens.
You can specify the environment for the new SOAP server by changing any of the fields.
For more information about environment specifications, see Setting connection properties, on
page 51. Click Next.
The SOAP Server Connection Security dialog box opens.
Select the Specify Connection Security check box to make changes to the security settings. Click
Next to continue.
For more information, see Defining security between the client and the SOAP server, on page
50.
The U2 Database Connection Properties window opens.
Make any necessary changes to the properties and then click Next.
59
Chapter 9: Deploying web services
8.
9.
For more information about the connection properties, see Setting connection properties, on
page 51.
The U2 Database Connection Security window opens.
Make any changes and then click Finish.
Run the rundeploytool command to deploy the configuration file created in the last step, as
shown in the following example:
rundeploytool.bat . C:\temp\myservice -s testserver -t prodserver –
f config_file_name
Results
The U2 SOAP service is now deployed in the deployment environment.
Running and stopping the SOAP server
▪
▪
To run the SOAP server, in the target directory, enter:
runsoapserver soap_server_name
To stop the SOAP server, in the target directory, enter:
stopsoapserver soap_server_name
Monitoring a remote SOAP server
Through the U2 Web Services Developer, you can monitor a remote SOAP server. Complete the
following steps to set up remote monitoring.
1.
2.
3.
4.
60
Define the remote server by right-clicking SOAP Servers, and selecting New SOAP Server.
The Add a New SOAP Server dialog box appears.
In the Server Name field, enter a unique name for the SOAP server.
In the URL field, enter the URL for the remote server.
Based on this URL, U2 Web Services Developer detects that the server is remote, and dims
unavailable options.
In the Port Number, enter the port number for the remote server.
If the remote SOAP server is running, a green icon appears next to the SOAP server, as shown in
the following example:
Monitoring a remote SOAP server
5.
To turn on logging, right-click the remote SOAP server, then click Turn on SOAP Server Debug.
U2 Web Services Developer displays the log from the remote server as shown in the following
example:
To stop the remote SOAP server, right-click the remote server you want to stop, then click Stop SOAP
server.
Note: You cannot start the remote SOAP server from U2 Web Service Developer.
61
Chapter 10: Troubleshooting
Adjusting Java heap space in the Developer
This topic describes how to modify the heap size for a Java virtual machine when starting a SOAP
server. This option is not enabled by default.
Description
Under most conditions the U2 SOAP products work as expected. However, when moving extremely
large amounts of data, it is possible to crash the Java Runtime engine if the default memory limit is
exceeded. If this occurs, you will see an out-of-memory error similar to the following:
java.lang.OutOfMemoryError: Java heap space
Explanation
A larger heap size will affect garbage collection, as it will run more frequently. This may affect the
performance of the application. Careful application design is important to ensure that this does not
occur.
Resolution
If you get this error, you must adjust the heap memory to a larger value. The default values are 256 MB
(initial size) and 512 MB (maximum size).
1.
2.
3.
4.
62
Open the Web Services Developer.
Navigate to Window > Preferences and then expand the UniData/UniVerse node.
Select U2 Web Services Developer.
Select the Set Java heap sizes option and then modify the sizes as necessary.
Adjusting Java heap space in a deployed environment
5.
Click Apply to apply the settings, and then click OK.
Adjusting Java heap space in a deployed environment
Under most conditions the U2 web services work as expected. However, when moving extremely large
amounts of data the Java Runtime engine may fail if the default memory limit is exceeded. If this
occurs, you will see an out-of-memory error similar to the following:
java.lang.OutOfMemoryError: Java heap space
If you get this error, you must adjust the heap memory to a larger value. The default values are 256 MB
(initial size) and 512 MB (maximum size).
A larger heap size will affect garbage collection, as it will run more frequently. This may affect the
performance of the application. Careful application design is important to ensure that this does not
occur.
Modifying the runsoapserver.bat file on Windows
1.
2.
Open the runsoapserver.bat file using an editor.
Locate the following line:
start javaw.exe -classpath...
3.
Modify the command to the following:
start javaw.exe -Xms512m -Xmx1024m -classpath...
63
Chapter 10: Troubleshooting
4.
Save the file and then restart the SOAP server.
Modifying the runsoapserver.sh file on UNIX
1.
2.
Open the runsoapserver.sh file using an editor.
Locate the following line:
start javaw -classpath...
3.
Modify the command to the following:
start javaw -Xms512m -Xmx1024m -classpath...
4.
Save the file and then restart the SOAP server.
Note: The JVM startup parameters offer a variety of options for operating the JVM. For details and
a complete list of the available JVM startup parameters, refer to www.oracle.com.
64
Chapter 11: Sample Code
Creating a WSD web service
The instructions in this section uses two example BASIC programs and an XML file: XMLREPSUB,
SOAPXMLREPSUB, and ROCKET.XML
The XMLREPSUB program is a database subroutine that is called and used by the SOAP web service.
* For UniData use the following include.
* $INCLUDE INCLUDE XML.H
*
* Universe use the following include.
SUBROUTINE XMLRETSUB(P1,P2)
P2="Hello Rocket"
END
The SOAPXMLRETSUB program is the client-side BASIC subroutine that calls the SOAP web service
using the SOAP API. It is used to test your SOAP web service.
***************************************************************
* SOAPXMLRETSUB
*
* For UniData use the following include.
* $INCLUDE INCLUDE XML.H
*
* Universe use the following include.
* $INCLUDE UNIVERSE.INCLUDE XML.H
*
* Example of Sending a ZIP SOAP 1.0 Request from BASIC
*
* SOAPXMLRETSUB - PROGRAM TO CALL a BASIC SUBROUTINE "XMLRETSUB" * using SOAP API (UniData 7.3.7, Universe 11.2.3)
* Sample program only, not intended for commercial use
* This program shows testing SOAP API request to a U2 WSD WEB SERVICE
* The XMLRETSUB subroutine called will return a "Hello Rocket" XML Page
*
* Turn on logging
*
myfil = "c:\temp\SOAPXMLRETSUB.log"
RESULT=protocolLogging(myfil,"ON",10)
CRT "Logging started = ":RESULT
*
PROMPT ""
CRT
DISPLAY "U2 SOAP EXAMPLE"
*
URL = "http://den-l-aw01:8185/XMLRETSUB"
SoapAction="CALL_XMLRETSUB"
* SoapAction=""
Timeout = 60000
* Create the Request
Ret = SoapCreateRequest(URL , SoapAction , SoapReq)
IF Ret <> 0 THEN
STOP "Error in SoapCreateRequest: " : Ret
END
65
Chapter 11: Sample Code
*
inpfile = "ROCKET.XML"
* Set the content
Ret = soapSetRequestContent(SoapReq, inpfile, 0)
IF Ret <> 0 THEN
STOP "Error in SoapSetRequestContent: " : Ret
END
* Save request
reqDoc="c:\u2\ud73\demo\soapxmlretsub.txt"
Ret=SOAPRequestWrite(SoapReq, reqDoc, 0)
IF Ret <> 0 THEN
STOP "Error in SoapRequestWrite: " : Ret
END
* PRINT "Request Content Status = ":SETREQUEST.STATUS
*
* Submit the Request
Ret = SoapSubmitRequest(SoapReq, Timeout, RespHeaders, RespData, SoapStatus)
IF Ret <> 0 THEN
CRT "Error in SoapSubmitRequest: " : Ret
STATUS=getSocketErrorMessage(Ret, errMsg)
CRT errMsg
STOP
END
*
PRINT "Response status : " : SoapStatus
PRINT "Response headers: " : RespHeaders
PRINT "Response data : " : RespData
*
RESULT=protocolLogging(myfil,"OFF",10)
CRT "Logging started = ":RESULT
The ROCKET.XML file contains the request information needed by the SOAP web service. This file was
created from the request information found in the Source section of the Web Services Explorer WSDL
Main utility. For more information on using the WSDL Main utility, see Starting the web service, on
page 40.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:q0="http://den-l-aw01" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<q0:CALL_XMLRETSUB>
<q0:INP>hello</q0:INP>
</q0:CALL_XMLRETSUB>
</soapenv:Body>
</soapenv:Envelope>
1.
2.
3.
4.
66
Create a new SOAP server. For details on this, see Creating a SOAP server, on page 16.
In the U2 Web Services pane, right-click the SOAP Servers node and then select Add new server.
Enter the name of the new service name and then click Next.
Enter the appropriate database connection properties and then click Next.
Enter the correct connection security information. Make sure that the URL parameter in the
SOAPXMLRETSUB subroutine matches that of the SOAP server and then click Next. For more
information about the SoapCreateRequest function, see the U2 Basic Extensions.
Creating a WSD web service
5.
Specify the correct Operation information. Add the name of the subroutine you want to call and
specify the number of parameters in the subroutine. Click Next to continue. The screen should
look similar to the following example.
Figure 1: Specifying the subroutine Operation information
6.
7.
8.
Specify the input and output parameters specified in the subroutine. The XMLRETSUB subroutine
has two parameters: an input and an output. To add a new parameter, select Add and then add
the parameter information in the Define Parameter dialog box, as shown in this example. See
Defining subroutine parameters, on page 33 for more information.
Click Finish.
Start the web service. For details on starting the web service, see Starting the web service, on
page 40.
Results
After running the example from the WSDL Main utility, you should see a response similar to the
following:
67
Chapter 11: Sample Code
Running the command from the command line gives an output similar to the following:
>LOGTO HS.SALES
>RUN BP SOAPXMLRETSUB
Logging started = 0
U2 SOAP EXAMPLE
Response status : 200²OK
Response headers: Jetty-Request²POST /XMLRETSUB HTTP/1.1■Date²Mon, 18 Aug 2014 1
4:20:09 GMT■Server²Jetty/4.2.x (Windows 7/6.1 x86 java/1.7.0_51)■Content-Type²te
xt/xml; charset=utf-8■Content-Length²463
Response data : <?xml version="1.0" encoding="utf-8" ?><SOAP-ENV:Envelope xmlns:
SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schem
as.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmln
s:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Header/><SOAP-ENV:Bo
dy><ns1:CALL_XMLRETSUBResponse xmlns:ns1="http://den-l-aw01"><ns1:OUTP>Hello Roc
ket</ns1:OUTP></ns1:CALL_XMLRETSUBResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>
Logging started = 0
>
68