U2 Web Services Developer - Rocket...
Transcript of U2 Web Services Developer - Rocket...
U2 Web Services Developer
User Guide
Version DEC2015
December 2015DBT-DEC2015–WSD-01
2
NoticesEdition
Publication date: December 2015Book number: DBT-DEC2015–WSD-01Product version: Version DEC2015
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 goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay 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 ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe 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 withthe terms of such license.
Note: This product may contain encryption technology. Many countries prohibit or restrict theuse, import, or export of encryption technologies, and current use, import, and export regulationsshould be followed when exporting this product.
3
Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.
Website: www.rocketsoftware.com
Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA
To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.
Country Toll-free telephone number
United States 1-855-577-4323Australia 1-800-823-405Belgium 0800-266-65Canada 1-855-577-4323China 800-720-1170France 08-05-08-05-62Germany 0800-180-0882Italy 800-878-295Japan 0800-170-5464Netherlands 0-800-022-2961New Zealand 0800-003210South Africa 0-800-980-818United Kingdom 0800-520-0439
Contacting Technical Support
The Rocket Customer Portal is the primary method of obtaining support. If you have currentsupport and maintenance agreements with Rocket Software, you can access the Rocket CustomerPortal 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 towww.rocketsoftware.com/support.
In addition to using the Rocket Customer Portal to obtain support, you can send an email [email protected] or use one of the following telephone numbers.
Country Telephone number
North America +1 800 729 3553United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691Europe/Africa +44 (0) 20 8867 3692Australia +1 800 707 703 or +61 (0) 29412 5450New Zealand +0800 505 515
4
Contents
Notices................................................................................................................................................................................... 2
Corporate information......................................................................................................................................................... 3
Chapter 1: Getting started................................................................................................................................................... 6Installing U2 Web Services Development Tool.......................................................................................................6Installing and updating the DBTools using the Eclipse Update Manager.............................................................6XTOOLSUB................................................................................................................................................................. 7
Installing XTOOLSUB for UniData on Windows.......................................................................................... 8Installing XTOOLSUB for UniVerse on Windows......................................................................................... 8Installing XTOOLSUB for UNIX/Linux for UniData...................................................................................... 9Installing XTOOLSUB for UNIX/Linux on UniVerse....................................................................................10Installing XTOOLSUB on Windows............................................................................................................ 11
Chapter 2: Adding and connecting to servers.................................................................................................................. 12Establishing server connections............................................................................................................................ 12
U2 server definitions.................................................................................................................................. 12Creating U2 server definitions................................................................................................................... 12
Viewing or editing advanced settings of a U2 server definition.......................................................................... 13Specifying a command to run on connection.......................................................................................... 14
Setting up SSL settings for a U2 server definition............................................................................................... 14Editing U2 server definitions..................................................................................................................................15Importing an existing U2 server definition........................................................................................................... 15Connecting to U2 servers.......................................................................................................................................16Disconnecting from U2 servers..............................................................................................................................16Deleting U2 server definitions............................................................................................................................... 16Creating a SOAP server.......................................................................................................................................... 17
Viewing the debug log................................................................................................................................20Displaying cached services........................................................................................................................ 20
Chapter 3: Creating a query web service..........................................................................................................................22Creating a query web service using drag-and-drop.............................................................................................22Creating a query web service using the wizard....................................................................................................25Starting the web service........................................................................................................................................ 30
Chapter 4: Creating a Subroutine web service.................................................................................................................32Creating a subroutine web service using drag-and-drop.................................................................................... 32
Defining subroutine parameters................................................................................................................34Creating a subroutine web service using the wizard........................................................................................... 37Starting the web service........................................................................................................................................ 41
Chapter 5: Viewing properties and dictionaries............................................................................................................... 44Server properties.................................................................................................................................................... 44Account properties................................................................................................................................................. 44File properties......................................................................................................................................................... 44File dictionaries.......................................................................................................................................................45
Chapter 6: Manually accessing the web services............................................................................................................. 46Viewing the web service URL.................................................................................................................................46Viewing the WSDL file.............................................................................................................................................46Web services clients............................................................................................................................................... 46
Generating a client proxy in IBM Websphere Application Developer......................................................47Generating a client proxy in Visual Studio.NET........................................................................................47
Chapter 7: Deploying web services................................................................................................................................... 48Exporting web services...........................................................................................................................................48Importing web services.......................................................................................................................................... 49
Contents
5
Deploying the SOAP server.................................................................................................................................... 49Updating the SOAP server..................................................................................................................................... 51Defining security between the client and the SOAP server................................................................................. 52Setting connection properties............................................................................................................................... 53Defining UniData database connection security..................................................................................................54Deploying the SOAP service as a Windows service.............................................................................................. 55Deploying the SOAP service from the command line.......................................................................................... 56
Starting the SOAP service from the command line................................................................................. 56Defining connection security between the client and the SOAP server from the command
line..........................................................................................................................................................58Defining database connection properties from the command line........................................................ 59Defining database connection security.....................................................................................................59
Deploying from the command line....................................................................................................................... 60Deploying a SOAP server from a configuration file..............................................................................................60
Generating a configuration file..................................................................................................................61Running and stopping the SOAP server................................................................................................................62Monitoring a remote SOAP server......................................................................................................................... 62
Chapter 8: Troubleshooting............................................................................................................................................... 64Adjusting Java heap space in the Developer........................................................................................................64Adjusting Java heap space in a deployed environment...................................................................................... 65
Chapter 9: Sample Code.................................................................................................................................................... 67Creating a WSD web service.................................................................................................................................. 67
6
Chapter 1: Getting started
Installing U2 Web Services Development ToolTo access the U2 Web Services Developer, you must have UniData 7.1.8 or greater, with connectionpooling licensed.
Prerequisites▪ 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 localAdministrators group.
▪ Exit any other Windows applications you have open.
Procedure
1. Download your UniData products from https://u2tc.rocketsoftware.com for the United States andCanada 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.
2. From the Setup screen, click Install U2 DBTools. Select U2 Web Services Developer from thelist.
3. When the Welcome screen opens, choose the appropriate installation option and then click Next.The Choose Destination Location dialog box appears.
4. By default, U2 Web Services Developer is installed in the C:\U2\U2Tools folder. If you wantto 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.
5. By default, U2 Web Services Developer is installed in the \U2\U2 Tools folder. If you do notwant to install it in this folder, select the folder where you want to install the product and clickNext to continue with the installation.
6. At this point, the installation process has enough information to begin copying files. Reviewthe information in the Start Copying Files dialog box. If all of the information is correct, clickNext to proceed with the installation. If it is not correct, click Back and correct the appropriateinformation.When the installation is complete, the Setup Complete dialog box appears.
7. Click Finish to complete the installation
Installing and updating the DBTools using the EclipseUpdate 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. Launch any U2 DBTools or base Eclipse installations (beginning with Galileo) on your computer.
XTOOLSUB
7
2. From the Eclipse Help menu, select Help → Install New Software.3. 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.4. 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.5. Click Next and follow the installation wizard to complete the installation of updates.6. Updates will take effect the next time an updated tool is launched.
Note: Only tools that are installed through separate InstallShield installations will appear onthe Start menu. Tools installed using the Eclipse Update Manager are installed as individualperspectives in a single Eclipse instance. You can access the different perspectives by selectingWindow → Open Perspective and then selecting the appropriate tool.
Note: You can check for updates to the DBTools by selecting Help → Check for Updates. To usethis option, you must have previously defined the http://updates.rocketsoftware.com/u2 locationin the Install New Software dialog, as described in step 3.
XTOOLSUBThis topic describes the XTOOLSUB program and how to upgrade to the latest version of XTOOLSUBon 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 programyou 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, dependingon the environment. The XTOOLSUB program is used by all the tools, but the other files included areonly used for the Basic Developer's Toolkit (BDT).
The XTOOLSUB_EXECPRE/XTOOLSUB_XPRE programs are for pre-execution functionality andXTOOLSUB_EXECPOST/XTOOLSUB_XPST are for post-execution functionality. These programs arediscussed further in the related public Tech Note, BDT Extensibility Details. If you have added your owncode to the pre- and post-functionality, copy those modified programs to the older database versionsrather 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
Chapter 1: Getting started
8
▪ 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 programalready exists on those versions.
There is a difference between the databases because UniVerse's catalog environment is a type 1 fileand 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 unnecessaryconfusion. The files in the zip/tar files are the object code for the given programs; do not open them ina text editor.
Note: Log in as a root or administrator user when doing these steps to avoid any permissionserrors. If an overwrite message occurs, select "yes" to overwrite the file in question.
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. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp.
2. Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory onyour server (for example, c:\temp).
3. Extract the file to the c:\u2\ud##\sys\SYS_BP (where ## refers to the UniData major version. Forexample, 61, 71, 72, etc.) directory using your preferred unzipping utility. If UniData is installed inanother location, change the path accordingly.
4. Log in to the sys account using telnet or execute a udt shell command in the sys directory on theserver.
5. 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 EDAMAPSUBFORCE 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.
Installing XTOOLSUB for UNIX/Linux for UniData
9
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp
2. Copy the XTOOLSUB_UV_NT.zip or XTOOLSUB_UV_103_NT.zip file to a temporary directory onyour server. For example, c:\temp.
3. Extract the file to the c:\u2\uv\BP.O directory using your preferred unzipping utility. If UniVerse isinstalled in another location, change the path accordingly.
4. Log in to the UV home account via Telnet. The account name is UV or uv in the UV.ACCOUNT file.5. 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 samecommand line.
6. If you are using UniVerse 10.3 or later, also run CATALOG BP *EDAMAPSUB FORCE command.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, forexample, /usr/ud##/bin (where ##, is 61,71,72, etc.). If this variable is not set, then reference the fullpath to the UniData bin directory in the commands.
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp.
2. Copy the XTOOLSUB_UDT_UX.tar or XTOOLSUB_UDT_61_UX.tar file to a temporary directory onyour server (for example, /tmp). If transferring using ftp, remember to use binary format.
3. Extract the file to the $UDTHOME/sys/SYS_BP directory.a. To install using UniData 6.1 or earlier, the commands will be:
cd $UDTHOME/sys/SYS_BPtar -xvf /tmp/XTOOLSUB_UDT_61_UX.tar
b. To install UniData 7.1 or later, the commands will be:cd $UDTHOME/sys/SYS_BPtar -xvf /tmp/XTOOLSUB_UDT_UX.tar
4. 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 converteverything 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 correctformat.
Chapter 1: Getting started
10
5. Change directories to the $UDTHOME/sys directory and then and execute the UDT command, asshown:a. CD $UDTHOME/sysb. $UDTBIN/udt
6. 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 EDAMAPSUBFORCE 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.
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp
2. Copy the XTOOLSUB_UV_UX.tar or XTOOLSUB_UDT_UV_103_UX.tar file to a temporary directoryon your server (for example, /tmp). If transferring files using FTP, remember to use binary fileformat.
3. Extract the file to the /usr/uv/BP.O directory. If UniVerse is installed in another location, changethe path accordingly. Use 'cat /.uvhome' to find the path if needed.
Note: `cat /.uvhome` references include single backward quotation marks. This commandretrieves the current value for the UniVerse home directory before running the command.
a. To install using UniVerse 10.3 or earlier, the commands to use are:cd `cat /.uvhome`/BP.Otar -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.Otar -xvf /tmp/XTOOLSUB_UV_UX.tar
4. If you are using a non-AIX operating system, run the convcode command, as shown:`cat /.uvhome`/bin/fnuxi XTOOLSUB*
5. Change directories to the UniVerse home directory and then and run the UV command, as shown:a. cd `cat /.uvhome`b. bin/uv
6. Click Escape to exit the menu.7. Catalog the three XTOOLSUB programs, as follows:
▪ CATALOG SYS_BP XTOOLSUB FORCE
Installing XTOOLSUB on Windows
11
▪ 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 samecommand line.
8. If you are using UniVerse 10.3 or earlier, also run the CATALOG BP *EDAMAPSUB FORCEcommand.
9. 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. Download the latest version of XTOOLSUB from the public Tech Note site at https://u2tc.rocketsoftware.com/documentation/1410028.asp
2. Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory onyour server (for example, c:\temp).
3. 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.
4. Log into the sys account using telnet or execute a udt shell command in the sys directory on theserver.
5. 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 EDAMAPSUBFORCE command.
6. Connect with your U2 client tool to the U2 database server.
12
Chapter 2: Adding and connecting to serversThis 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:
Establishing server connections
U2 server definitions
The U2 DBTools interface does not detect the presence of UniData or UniVerse (U2) database serverson the network or let you connect to them by default. To work with UniData or UniVerse accounts anddata, you must enable the computer to connect to the server on which the accounts and data reside.The client computer requires a U2 server definition to make a connection with the server.
A U2 server definition is stored on the client computer on which it was created, and is not sharedacross a network. One or several users can create multiple U2 server definitions on the same clientcomputer.
U2 server is the term for a defined connection to a server computer on which U2 accounts and dataare stored. All existing U2 servers on the client computer are listed in the U2 Resource view. You canconnect to any U2 server in the U2 Resource list.
Creating U2 server definitions
To administer UniData or UniVerse accounts and data, you must create a U2 server definition thatenables the client computer to connect to the U2 database server on which the accounts and data arestored.
Prerequisites
Open the U2 DBTools workspace from the Start → Rocket U2 menu.
Procedure
1. To start the Create a New U2 Server wizard, right-click the U2 Servers node in the U2 Resourceview, and click New U2 Server.
Viewing or editing advanced settings of a U2 server definition
13
2. In the Name field, enter a unique name to identify the U2 server definition.The name cannot contain a slash (/) or backslash (\) character.
3. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse isrunning.
4. From the U2 database server options, select UniData or UniVerse.5. Optional: To view or edit the unirpc service name, port number, and other advanced settings
defining the connection, click Advanced.
Go to Viewing or editing advanced settings of a U2 server definition, on page 13.
Tip: The default values for advanced settings work best in most situations. Alter thesesettings only if necessary.
6. Optional: To view or update the SSL settings, click Setup SSL.
Go to Setting up SSL settings for a U2 server definition, on page 147. To save the U2 server definition, click Finish.
The tool creates a directory for the U2 server, registering the server definition so the tool can findit in future sessions. The name of the new U2 server is added to the list in the U2 Resource view.
Next step
Connecting to U2 servers, on page 16
Viewing or editing advanced settings of a U2 serverdefinition
On the advanced settings page of the server definition, you can view or edit the protocol, port number,and other advanced settings that define the connection. You can also specify commands to run whenyou connect to the U2 server. The default values for advanced settings work best in most situations.Alter these settings only if necessary.
Prerequisites
Creating U2 server definitions, on page 12 or Editing U2 server definitions, on page 15
Procedure
1. The Protocol Type field displays TCP/IP as the communications protocol used by the UniData orUniVerse to access the internet.At this time, the only supported protocol is TCP/IP, and this setting cannot be changed.
2. In the RPC Port # field, enter the port number of the UniRPC server running on the host.The default port number is 31438.
3. In the RPC Service Name field, enter the name of the remote procedure call (RPC) service on thesystem.For UniData, the name is normally udcs; for UniVerse, the name is normally uvcs.
4. In the Login Account field, enter the full path to the account folder on the server running UniDataor UniVerse.You can enter just the account name if the account is defined in the UD.ACCOUNT or UV.ACCOUNThash file.
Chapter 2: Adding and connecting to servers
14
5. If you run a RetrieVe command, a saved paragraph, or a globally cataloged program every timeyou connect to the U2 server, you can save time by entering the command in the U2 serverdefinition. To enter a command to run on connection, click Add in the Commands to Executegroup box.See Specifying a command to run on connection, on page 14.
6. In the Specify the session to run/debug your BASIC program on server side group box, enterdetails for connecting to the server in a debug session.a. From the Protocol options, select the network protocol to use when you connect to the U2
server in a debug session: Telnet or SSH (Secure Shell).b. In the Port Number field, enter the port number on which the Telnet or SSH service runs on
the server computer. The default Telnet port number is 23; the default SSH port number is22.
c. If device licensing is supported on the server, select the Use Device License check box toconserve license usage in the debug session.
While running or debugging BASIC programs, you may use multiple server connections to browsefiles, check data, update records, or perform other tasks. If device licensing is disabled, the debugsession consumes one U2 license for each connection. With device licensing enabled, the sessionconsumes one U2 license and one device license for up to 10 connections from a single device.
Tip: If you are unable to establish a Telnet or SSH connection with the Use Device Licensecheck box selected, clear the check box and try again.
7. To save changes to advanced settings and return to the main page, click Finish.
Specifying a command to run on connection
You can run a RetrieVe command, a saved paragraph, or a globally cataloged program every timeyou connect to the U2 server. Rather than type the same command each time you connect, you canincrease efficiency and save time by entering the command in the U2 server definition.
1. In the Specify a command field, enter a RetrieVe command, the name of a saved paragraph, orthe name of a globally cataloged program to run when you connect to the U2 server.
2. To save the changes and return to the details page, click OK.
Setting up SSL settings for a U2 server definitionOn the Database Connection Security page for the server definition, you can turn on SSL, and add atrust store and trust store password for the connection.
Prerequisites
Creating U2 server definitions, on page 12 or Editing U2 server definitions, on page 15
Procedure
1. Select the Use SSL checkbox to enable SSL.
Note: The key store must be an absolute file.
2. Select Use Default Trust Store to enable the trust store.
Editing U2 server definitions
15
3. Enter the location of the trust store you want to use, or click Browse to navigate the correctlocation.
4. Enter the trust store password.5. To save changes to the SSL settings and return to the main page, click Finish.
Editing U2 server definitionsYou can modify the details of an existing U2 server definition, with one exception. It is not possible tochange the name of the U2 server. However, you can create the U2 server again with a new name.
Prerequisites
Creating U2 server definitions, on page 12
Procedure
1. To start the Edit U2 Server Definition wizard, right-click the name of the U2 server definition in theU2 Resource view, and click Properties.
2. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse isrunning.
3. From the U2 database server options, select UniData or UniVerse.4. Optional: To view or edit the unirpc service name, port number, and other advanced settings
defining the connection, click Advanced.
Go to Viewing or editing advanced settings of a U2 server definition, on page 13.
Tip: The default values for advanced settings work best in most situations. Alter thesesettings only if necessary.
5. To save the U2 server definition, click Finish.The tool creates a directory for the U2 server, registering the server definition so the tool can findit in future sessions. The name of the new U2 server is added to the list in the U2 Resource view.
Importing an existing U2 server definitionYou can import existing U2 server definitions to your XAdmin environment from the XAdmin ResourceView.
Prerequisites
Creating U2 server definitions, on page 12 or Editing U2 server definitions, on page 15
Note: When you import U2 servers, all credential information is included. It is important to limitrestricted access services, depending on your security policy. It is the function of your securityadministrator to determine if U2 servers can be imported with credentials included. You can saveserver resources without password credentials.
Procedure
1. From the U2 Resource View, right-click the Servers icon and then select Import U2 Servers.
Chapter 2: Adding and connecting to servers
16
2. In the Installation path field, enter the location of the server definitions you want to import. Thismust be an existing U2 DBTools directory.
3. Select the server definitions you want to import, then click OK.The imported server now shows in the U2 Resource View.
Connecting to U2 serversYou must open a U2 server connection to work with the accounts stored on the associated UniDataor UniVerse (U2) database server computer. You can connect to any U2 server that is listed in the U2Resource view.
Prerequisites
Creating U2 server definitions, on page 12
Procedure
1. To start the Connect to a U2 Server wizard, double-click the name of the U2 server in the U2Resource view.
2. In the User ID field, enter the administrator user name or the user name of a valid user on theserver computer running UniData or UniVerse.
3. In the Password field, enter the password for the administrator or user on the server computer.4. To store the password for future connections, select the Remember me check box.
With this check box selected, Microsoft Windows stores the encrypted password on the clientcomputer.
5. If you are using a proxy server, select the Use Proxy Server check box.a. In the Proxy Host field, enter the name or IP address of the computer on which the proxy
server is running.b. In the Proxy Port field, enter the number of the port on which the proxy server listens for
communication from UniData or UniVerse.6. To connect to the U2 server, click Connect.
When the connection is established, the U2 Resource view displays a tree view of the U2 accountsand catalog programs on the U2 database server to which you are connected.
Disconnecting from U2 serversAfter completing tasks for a U2 account, you can disconnect from the U2 server. Disconnecting onlycloses the connection to the U2 server. It does not delete the U2 server definition or remove the U2server from the list in the U2 Resource view.
In the U2 Resource view, right-click the name of the U2 server from which you want to disconnect, andclick Disconnect.
Deleting U2 server definitionsIf you no longer require access to the U2 accounts and catalog programs on a U2 database server, youcan delete the associated U2 server definition. It is not possible to change the name of an existing U2server. However, you can delete the U2 server definition and create it again using a new name.
In the U2 Resource view, right-click the name of the U2 server you want to delete, and click Delete.
Creating a SOAP server
17
The name of the U2 server and folders for its U2 accounts and catalog programs are removed from thelist in the U2 Resource view.
Creating a SOAP server1. 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 ServicesDeveloper 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 detectedby the U2 Web Services Developer. We recommend that you not change theURL 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 notchange 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 arestored.
Debug Log Indicates whether to start the debug log. If you select true, U2 Web ServicesDeveloper starts the debug log each time you start the server. To disablethe debug log when the server is running, right-click the SOAP server, thenselect Turn Off SOAP Server Debug. You can also start the debug log whenthe SOAP server is running, if it is disable. For more information, Viewing thedebug log, on page 20.
Log File Name The name of the debug log file. By default, the name of the debug log file issoapservername.log.
Chapter 2: Adding and connecting to servers
18
Field Description
ConnectionPooling On
The Connection Pooling On setting determines whether UniData usesconnection pooling with the U2 Web Services Developer. The termconnection pooling refers to the technology that pools permanentconnections to data sources for multiple threads to share. It improvesapplication performance by saving the overhead of making a freshconnection each time one is required. Instead of physically terminating aconnection when it is no longer needed, connections are returned to thepool and an available connection is given to the next thread with the samecredentials.
Connection Pooling in enabled by default. If you do not want to useConnection Pooling, clear the Connection Pooling On check box.
We recommend using Connection Pooling for superior performance andscalability.
Connection PoolSize
You can set the minimum and maximum size of the connection pool. If youdo not define these sizes, the minimum size defaults to 1 and the maximumsize defaults to 10. The minimum size determines the initial size of theconnection pool.
The size of the connection pool changes dynamically between the minimumand maximum sizes you specify, depending on the system demands. Whenthere are no pooled connections available, UniData either creates anotherconnection, if the maximum connection pool size has not been reached, orkeeps the thread waiting in the queue until a pooled connection is releasedor the request times out. If a pooled connection is idle for a specified time, itis disconnected.
SOAP RequestValidation
Specifies whether the server needs to validate the SOAP requestbefore processing. If this value is set to true, you may experience slightperformance degradation, but will have an extra layer of security.
Default NameSpace
The name space for the Web Services you define.
Service CacheSize
For performance purposes, you can set this value to a number greater than0 to indicate the number of web service definitions you want to keep in thecache. If you set this value, the SOAP Server will always try to read the webservice definition from the cache first. If you do not set this value, the SOAPServer 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 definitioneach time. Select the Cached Services tab to display the web servicescurrently loaded in cache.
Creating a SOAP server
19
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 followingtable describes the fields.
Field Description
Key Store Enter the full path to the key store on the SOAP server, or click Browse tonavigate to the key store.
Key StorePassword
Enter the password corresponding to the key store you defined in the KeyStore field.
Confirm KeyStore Password
Reenter the password corresponding to the key store you defined in the KeyStore field.
Key Password Enter the encryption key password, if one exists.Confirm KeyPassword
Reenter the encryption key password, if one exists.
EnableAuthentication
If you want the client to send its certification for authentication, select theNeed 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.
Chapter 2: Adding and connecting to servers
20
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 U2Web 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 startand 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 isdescribed in Creating a SOAP server, on page 17.
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:
U2 Web Services developer displays the last 64KB in the SOAP Server log.2. To erase the contents of the log file click the Erase icon.3. 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 currentlyrunning, or larger.
Displaying cached services
21
If you do not set this value, the SOAP Server reloads the web service each time. If you do set thisvalue, next time a web service is needed, the SOAP Server reads it from cache.
2. 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.
3. Select the Cached Services tab to display the web services currently loaded in cache.
22
Chapter 3: Creating a query web serviceThis 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-drop1. 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 theaccount, 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.
Creating a query web service using drag-and-drop
23
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 Serviceportion of the U2 Web Services Developer dialog box, as shown in the following example:
By default, the U2 Web Services Developer creates a LIST statement which includes each D-Typedictionary record contained in dictionary for the file you selected.
5. 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.
6. 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 thefollowing example:
Chapter 3: Creating a query web service
24
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.
d. In the Position field, enter the prompting order of the input parameter.e. In the Type field, select the data type for the input parameter from the list. Valid types are
String and Dynamic array.
Creating a query web service using the wizard
25
Creating a query web service using the wizard1. 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. In the Service Name field, enter a name for the web service you are creating.3. In the Namespace field, verify or enter the namespace. Click Finish.
The U2 Database - Connection Properties dialog box appears.
If you have not defined the database connection properties at the SOAP Server-level, you mustdefine them for this Web Service. For more information about defining the data base connectionsat the SOAP Server-level, see Creating a SOAP server, on page 17.
4. Select the Specify default database connection properties check box.
Chapter 3: Creating a query web service
26
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 U2Web 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.
Creating a query web service using the wizard
27
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 followingtable describes the fields.
Field Description
Key Store Enter the full path to the key store on the SOAP server, or click Browse tonavigate to the key store.
Key StorePassword
Enter the password corresponding to the key store you defined in the KeyStore field.
Confirm KeyStore Password
Reenter the password corresponding to the key store you defined in the KeyStore field.
Key Password Enter the encryption key password, if one exists.Confirm KeyPassword
Reenter the encryption key password, if one exists.
EnableAuthentication
If you want the client to send its certification for authentication, select theNeed Client Authentication check box.
Chapter 3: Creating a query web service
28
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 followingtable describes the fields.
Field Description
Key Store Enter the full path to the key store on the SOAP server, or click Browse tonavigate to the key store.
Key StorePassword
Enter the password corresponding to the key store you defined in the KeyStore field.
Confirm KeyStore Password
Reenter the password corresponding to the key store you defined in the KeyStore field.
Key Password Enter the encryption key password, if one exists.Confirm KeyPassword
Reenter the encryption key password, if one exists.
EnableAuthentication
If you want the client to send its certification for authentication, select theNeed Client Authentication check box.
9. Click Next.The Operation dialog box appears.
10. In the Name field, enter the name for the web service you are creating.
Creating a query web service using the wizard
29
11. From the Type options, select Query.12. In the Query area, define the query command:
a. 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 SORTcommands, 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 XMLdocument the web service creates for the query you specify. If you have two or more queryoperations within the same web service using the same data file, make sure the record nameis 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.
14. Click Finish.The web service definition appears in the Web Service area of U2 Web Services Developerwindow.
Chapter 3: Creating a query web service
30
15. If you specified a placeholder in the web service command, click the input parameter, then clickarg_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 service1. To start a web service, click the Launch icon from the toolbar.
The Web Services Explorer window appears.2. Click the WSDL icon.3. Under the Navigator area of the Web Services Explorer window, click WSDL Main.
The Open WSDL dialog box appears.
Starting the web service
31
4. From the U2 Web Service area of the Web Services Developer window, click the highlighted webservice.The properties of the web service appear in the Properties area of the Web Service window, asshown in the following example:
The Web Service operation prompts you for input parameters you previously defined, as shown inthe following example:
5. Enter the input value, then click GO.The U2 Web Services Developer displays the resulting XML document in the Status area of theInvoke a WSDL Operation dialog box, as shown in the following example:
6. Click Source to view the XML source for the output.
32
Chapter 4: Creating a Subroutine web serviceThis 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-dropAbout 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.CUSTRETURN
Procedure
1. From the U2 Web Services Developer window, right-click the account for which you want to createa web service. Expand the Cataloged Program node to view the subroutines available in theaccount, as shown in the following example:
Note:
You must catalog the subroutine before you start the U2 Web Services Developer. You canglobally, locally, or directly catalog subroutines.
For information about cataloging UniBasic programs, see UniData Commands Reference. Forinformation about cataloging UniVerse BASIC programs, see UniVerse User Reference.
Creating a subroutine web service using drag-and-drop
33
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. In the Service Name field, enter a name for the web service you are creating.4. Click Finish.
Because the program is globally cataloged, the Connection Properties dialog box appears. Whenthe subroutine is not globally cataloged, the Connection Properties dialog box does not appear.
5. Select the Specify default database connection properties check box.6. Verify the Account field to make sure it defines the account you want to execute the subroutine
against, then click Finish.
Chapter 4: Creating a Subroutine web service
34
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 Serviceportion 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. In the Subroutine Name field, enter the name of the subroutine.3. 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.
4. From the Input area, click Add.The Define Parameter dialog box appears.a. In the Name field, enter a meaningful name of the input parameter.
Defining subroutine parameters
35
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 the input parameter appears 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.
5. From the Output area of the Subroutine Details dialog box, click Add.The Define Parameter dialog box appears.
a. In the Name field, enter the name of the output parameter.b. In the Position field, enter the position of the output parameter in the subroutine.c. In the Type field, enter the data type of the output parameter.
In this example, the output parameter is a dynamic array.
d. 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 youspecify does not exist, the following message appears.
e. 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:
Chapter 4: Creating a Subroutine web service
36
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. In the Name field, enter the name of the field in the dynamic array.b. In the Location field, enter the location of the field in the dynamic array.c. In the Type field, enter the type of field. Valid types are String and Dynamic array.d. Click OK.
Creating a subroutine web service using the wizard
37
8. To populate the fields, from the Database Files in the account for which you are creating the webservice, drag-and-drop the file pertaining to the dynamic array.The U2 Web Services Developer populates the U2 Dictionary dialog box with each D-typedictionary 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 thesubroutine. In this example, the entire record should be returned, so each dictionary attribute isselected 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, outputparameters, and dynamic arrays appear in the Web Services area of the U2 Web Services Developerwindow, as shown in the following example:
Creating a subroutine web service using the wizard1. 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.2. In the Service Name field, enter a name for the web service you are creating.3. In the Namespace field, verify or enter the namespace. Click Next.
The U2 Database - Connection Properties dialog box appears.
Chapter 4: Creating a Subroutine web service
38
If you have not defined the database connection properties at the SOAP Server-level, you mustdefine them for this Web Service. For more information about defining the data base connectionsat the SOAP Server-level, see Creating a SOAP server, on page 17.
4. Select the Specify default database connection properties check box.5. 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 wantto 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 thePassword 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.
Select the Use SSL check box if you want to define the SSL security parameters. The followingtable describes the fields.
Field Description
Key Store Enter the full path to the key store on the SOAP server, or click Browse tonavigate to the key store.
Key StorePassword
Enter the password corresponding to the key store you defined in the KeyStore field.
Confirm KeyStore Password
Reenter the password corresponding to the key store you defined in the KeyStore field.
Key Password Enter the encryption key password, if one exists.Confirm KeyPassword
Reenter the encryption key password, if one exists.
EnableAuthentication
If you want the client to send its certification for authentication, select theNeed Client Authentication check box.
Creating a subroutine web service using the wizard
39
12. Click Next.The Operation dialog box appears.
13. In the Name field, enter the name for the web service you are creating.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.a. 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. In the Name field, enter the name of the output parameter.b. In the Position field, enter the position of the output parameter in the subroutine.c. In the Type field, enter the data type of the output parameter.
In this example, the output parameter is a dynamic array.
d. 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 youspecify does not exist, the following message appears.
e. Click Yes to define the new dynamic array.
Chapter 4: Creating a Subroutine web service
40
The name of the array appears under the Dynamic Arrays area of the Web Services window,as shown in the following example:
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. In the Name field, enter the name of the field in the dynamic array.b. In the Location field, enter the location of the field in the dynamic array.c. In the Type field, enter the type of field. Valid types are:
▪ s - Single-valued
▪ mv - Multivalued
▪ ms - Multi-subvalued
d. Click OK.
Starting the web service
41
22. To populate the fields, from the Database Files in the account for which you are creating the webservice, drag-and-drop the file pertaining to the dynamic array.The U2 Web Services Developer populates the U2 Dictionary dialog box with each D-typedictionary 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 thesubroutine. In this example, the entire record should be returned, so each dictionary attribute isselected except for the CUSTID.
24. 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, outputparameters, and dynamic arrays appear in the Web Services area of the U2 Web Services Developerwindow, as shown in the following example:
Starting the web service1. To start a web service, click the Launch icon from the toolbar.
The Web Services Explorer window appears.2. Click the WSDL icon.
Chapter 4: Creating a Subroutine web service
42
3. 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 webservice.The properties of the web service appear in the Properties area of the Web Service window, asshown in the following example:
5. In the WSDL URL dialog box, enter the value of the End Point property, then click Go.6. In the WSDL Details window, select the operation you want to execute, as shown in the following
example:
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.
Starting the web service
43
8. Enter the input value, then click GO.The U2 Web Services Developer displays the resulting XML document in the Status area of theInvoke a WSDL Operation dialog box, as shown in the following example:
44
Chapter 5: Viewing properties and dictionariesThis section describes how to view the properties of accounts, servers, and files, and the filedictionaries.
Server propertiesTo 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 propertiesTo 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 Developerwindow, 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 propertiesTo display the properties of a file, click the account where the file resides, then click the file for whichyou want to display properties
The properties of that file appear in the Properties area of the Web Services Developer window, asshown in the following example:
File dictionaries
45
Property Value
Data File Path The path to the file. If the file resides locally, this field displays the nameof the file. If the file resides in a remote location, this field displays thefull 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 dictionariesTo display the dictionary of a file, click the file for which you want to display the dictionary, the clickthe U2 Dictionary tab.
Information similar to the following example appears:
Property Value
ID Dictionary record IDTYPE Type of dictionary record.LOC Field location of the dictionary record if a D-type record, formula if an I-
type 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.
46
Chapter 6: Manually accessing the web servicesThe section describes how to access web services programmatically. A defined web service isidentified 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 URLYou can use the U2 Web Services Developer main window to view the URLs for your web services, asshown in the following example:
1. Open the U2 Web Services Developer main window.2. Expand the web server where the web service is located.3. Click the web service for which you want to view the URL.4. Select the Properties tab.
The URL for the web service appears in the End Point field.
Viewing the WSDL fileYou can use a web browser to view WSDL files.
Type the URL in a browser.The contents of the WSDL file appears.
Web services clientsTo write a Web Services client program, you create an object of a proxy class, then call the methods forthat 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 acomplete description of the interfaces to the Web service you define, including the XML schemas of theinput 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 datastructures used in the web services. These classes are self-explanatory.
Generating a client proxy in IBM Websphere Application Developer
47
Generating a client proxy in IBM Websphere Application Developer
1. To generate a Web Service client proxy in IBM Websphere Application Developer, select New.2. Select the web service client and the project type.3. 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. To generate a Web Service client proxy in Visual Studio.NET, start a new project, then add a WebReference.The Add Web Reference wizard prompts for the URL for the WSDL file.
2. 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.
48
Chapter 7: Deploying web servicesThe U2 Web Services Developer deployment feature enables you to select a SOAP server definedlocally 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 onany platform.
Exporting web servicesYou 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. In the Available SOAP Servers section, select the SOAP servers you want to export.3. 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:
Importing web services
49
▪ runtime
▪ 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 servicesAfter exporting a SOAP web service from the source development system, you can import it on thetarget developer web service system. The zip file must be extracted on the target system. For examplec:\temp.
Prerequisites▪ 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 developersystem.
▪ 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. Right-click the SOAP server that contains the web service that you to import, and select Import.2. Click Browse to select the root directory for the SOAP server(s) that you want to import.
for example, C:\temp\Test\u2soapdeploy.3. Select the servers that you want to import, and then click Finish.
Deploying the SOAP server1. 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
Chapter 7: Deploying web services
50
3. Expand Deployable SOAP Servers, right-click the SOAP server you want to deploy, then clickDeploy.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 canchange 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 ServicesDeveloper 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 poolspermanent connections to a data source for multiple threads to share.It improves application performance by saving the overhead of makinga fresh connection each time one is required. Instead of physicallyterminating a connection when it is no longer needed, connections arereturned to the pool and an available connection is given to the nextthread with the same credentials.
Connection Pooling in enabled by default. If you do not want to useConnection Pooling, clear the Connection Pooling On check box.
It is recommended you use Connection Pooling for superiorperformance and scalability.
Updating the SOAP server
51
Configuration options Description
Connection Pool Size You can set the minimum and maximum size of the connection pool. Ifyou do not define these sizes, the minimum size defaults to 1 and themaximum size defaults to 10. The minimum size determines the initialsize of the connection pool.
The size of the connection pool changes dynamically between theminimum and maximum sizes you specify, depending on the systemdemands. When there are no pooled connections available, UniDataeither creates another connection, if the maximum connection poolsize has not been reached, or keeps the thread waiting in the queueuntil a pooled connection is released or the request times out. If apooled 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 notselected.
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 tokeep in the cache. If you set this value, the SOAP Server will always tryto read the web service definition from the cache first. If you do notset this value, the SOAP Server reloads the web service each time fromdisk.
If you are developing a web service, it is recommended you keep thisvalue at 0. This setting forces the SOAP Server to reload the new webservice definition each time. Select the Cached Services tab to displaythe web services currently loaded in cache.
Updating the SOAP serverYou can update the configuration file used to deploy the SOAP server from the development computerto the deployment environment. The configuration file holds information such as server name, portnumber, and connection pool information.
1. Open the Web Services Developer tool.2. In the U2 Web Services pane, right-click the resource you want to update and then select
Properties.3. Follow the menu prompts and update the SOAP server information as needed.
Chapter 7: Deploying web services
52
Defining security between the client and the SOAPserver
1. Click the Specify Connection Security check box if you want to define connection securitybetween 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.
Field Description
Key Store Enter the full path to the key store on the SOAP server, or click Browse tonavigate to the key store.
Key StorePassword
Enter the password corresponding to the key store you defined in the KeyStore field.
Confirm KeyStore Password
Reenter the password corresponding to the key store you defined in the KeyStore field.
Key Password Enter the encryption key password, if one exists.Confirm KeyPassword
Reenter the encryption key password, if one exists.
EnableAuthentication
If you want the client to send its certification for authentication, select theNeed Client Authentication check box.
3. Click Finish.
Setting connection properties
53
Setting connection properties1. 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 havedefined.The server should be running.
3. In the Account field, select the account name of the UniData server you specified where you wantto attach when you connect from the list.This account must contain the data files that you are accessing with the subroutine.
4. In the User ID field, type your login name for the server. Type the corresponding password in thePassword field.
5. 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.
6. In the UniRPC Port Number field, type the port number of the UniRPC server running on the host.The default port number is 31438.
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.
8. If you want to use the connection properties you specified for subsequent SOAP servers youdeploy, select the Use this database connection and security for subsequent SOAP servicesduring deployment check box.
9. Click Next.
Chapter 7: Deploying web services
54
Defining UniData database connection security1. 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.
Field Description
Key Store Enter the full path to the key store on the SOAP server, or click Browse tonavigate to the key store.
Key StorePassword
Enter the password corresponding to the key store you defined in the KeyStore field.
Confirm KeyStore Password
Reenter the password corresponding to the key store you defined in the KeyStore field.
Key Password Enter the encryption key password, if one exists.Confirm KeyPassword
Reenter the encryption key password, if one exists.
EnableAuthentication
If you want the client to send its certification for authentication, select theNeed Client Authentication check box.
3. Click Next.
Results
U2 Web Services Developer deploys the web services you specified. When deployment is complete, awindow similar to the following example appears:
Deploying the SOAP service as a Windows service
55
The deployable web services appear in the SOAP Servers area of the U2 SOAP Service Deploymentdialog box, and shown in the following example:
Deploying the SOAP service as a Windows serviceThe u2soapservice.exe is an executable program that is used to create or remove a SOAP serviceas a Windows service. It is located in the zip file that was created during the export process.
Prerequisites▪ The SOAP server must have already been deployed.
▪ On Windows 7 and Windows 2008, you must run the Windows Command Prompt as anadministrator. To do this, click Start > Accessories > Command Prompt. Right-click theCommand Prompt option and select Run as administrator.
▪ Java Development Kit 1.8. If you do not already have JDK 1.8 installed, you must complete thefollowing steps:1. Download and install the Java Development Kit, version 1.8 from the Oracle archive download
site.2. Locate the javaw.exe file in C:\Program Files\Java\jdk1.8.0_66\bin.3. Navigate to Control Panel > System > Advanced system settings and then click
Environment Variables.4. Locate the System Variable called Path and click Edit.5. Add the location of javaw.exe to the end of the list. For example, add C:\Program
Files\Java\jdk1.8.0_66\bin.6. Click OK. For this to take effect, the machine must be rebooted.
Chapter 7: Deploying web services
56
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 beenclosed in quotation marks (“â€).
-r Removes the U2 SOAP service.
After installing the U2 SOAP service, it can started and stopped as a Windows service fromthe Windows control panel. When the service starts, it runs the runsoapserver.batu2soap-server program and waits until this bat file exits. When the service stops, it runs thestopsoapserver.bat u2soapserver program. Additional arguments can be passed to therunsoapserver.bat by specifying the start parameters to the service.
Note: If you are creating a Windows service using the u2soapservice.exe program and youget an error similar to the one shown below, you must run the vcredist_x86.exe programsupplied with the U2 WSD product to ensure the Windows platform has the compatible MicrosoftVisual C++ 2005 redistributable runtime environment:
Error: The application has failed to start because its side-by-side configuration is incorrect. Please seethe 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 lineUse the command line options to deploy the U2 SOAP server from the development computer to thedeployment environment. The command line options allow for option-driven, interactive commandline 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:
▪ runtime
▪ u2soap_deploy
▪ servername_deploy_config.xml
▪ runsoapserver.bat
Starting the SOAP service from the command line
57
▪ 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. Navigate to the server directory where you extracted the zip file and locate the U2 SOAPdeployment tool.
3. 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 forWindows 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 (.) forcurrent 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.-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 isnot included in the command, while the connection credentials will bevisible, they will not be editable.
-l Lists the servers available for deployment.
4. 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. Youcannot change the information in this field.
Chapter 7: Deploying web services
58
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 definitionsto the Web service are stored. You cannot change the information inthis field.
3 Debug on. Set this value to true to turn on the debug log. Set this valueto 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 thelog file is defined by the name of the target server.
5 Connection Pooling On. Set this value to true to enable connectionpooling.
6 Minimum Connection Pool Size. Sets the minimum number ofconnections in the connection pool. The minimum size defaults to 1.
7 Maximum Connection Pool Size. Sets the maximum number ofconnections 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 notselected.
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 tokeep in the cache. If you set this value, the SOAP Server will always tryto read the web service definition from the cache first. If you do notset this value, the SOAP Server reloads the web service each time fromdisk.
If you are developing a web service, we recommend keeping this valueat 0. This setting forces the SOAP Server to reload the new web servicedefinition each time. Select the Cached Services tab to display theweb 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 serverfrom the command line
After defining the connection configuration, you can define the connection security for the SOAPserver.
1. The U2 SOAP connection security options open in the command line window. Select S to view thesecurity options.
2. Select the appropriate action from the options presented in the command line window, asdescribed 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
59
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 truststore.
5 Need Client Authentication. Set this value to true for the client to sendits certification for authorization.
3. 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 resourcefolder.
The Resource folder property options open in the command line window.
1. Select the appropriate action from the options presented in the command line window, asdescribed 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.
2. 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 databaseconnection.
1. Select S from the command line options to access the connection security from the commandline.
2. Select the appropriate action from the options presented in the command line window, asdescribed in the following table:
Chapter 7: Deploying web services
60
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 truststore.
5 Need Client Authentication. Set this value to true for the client to sendits certification for authorization.
Deploying from the command lineAfter any required changes are made to the Resource folder properties, the U2 SOAP server is ready todeploy 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 describedin 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 allof the configuration information. Select this option to make changes tothe configuration file before deploying.
C Continue. This option deploys the server to the deploymentenvironment.
Results
The U2 SOAP server was deployed to the deployment environment.
Deploying a SOAP server from a configuration fileA U2 SOAP service can be deployed onto a deployment environment using a generated configurationfile. The configuration file is an XML file, server_name_ deploy_configuration.xml, thatcontains all of the configuration information. The configuration file specifies values that can bechanged during deployment, such as login credentials.
Generating a configuration file
61
Generating a configuration file
Use the U2 SOAP deployment tool to generate a configuration file that can be used to deploy the U2SOAP 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 containthe following files:
▪ rundeploytool.bat
▪ rundeploytool.sh
▪ runsoapserver.bat
▪ runsoapserver.sh
▪ runtime
▪ stopsoapserver.bat
▪ stopsoapserver.sh
▪ u2soap
▪ U2SOAP_deploy.conf
▪ u2soap_workspace
▪ u2soapservice.exe
▪ vcredist_x86.exe
2. Navigate to the server directory where you extracted the zip file and locate U2SOAP deploymenttool. 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_dirsource_target_directory.
Parameter Description
rundeploytool[.bat | .sh] The command to start the deployment tool. Use the .bat script forWindows 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 thecurrent 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.3. 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. 4. Click Browse to select a different configuration file or accept the default configuration file. Click
Next.The SOAP Server Configuration dialog box opens.
5. 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, onpage 53. Click Next.The SOAP Server Connection Security dialog box opens.
6. Select the Specify Connection Security check box to make changes to the security settings. ClickNext to continue.
Chapter 7: Deploying web services
62
For more information, see Defining security between the client and the SOAP server, on page52.The U2 Database Connection Properties window opens.
7. Make any necessary changes to the properties and then click Next.For more information about the connection properties, see Setting connection properties, onpage 53.The U2 Database Connection Security window opens.
8. Make any changes and then click Finish.9. 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 serverThrough the U2 Web Services Developer, you can monitor a remote SOAP server. Complete thefollowing steps to set up remote monitoring.
1. Define the remote server by right-clicking SOAP Servers, and selecting 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.3. 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 dimsunavailable options.
4. 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 inthe following example:
Monitoring a remote SOAP server
63
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 followingexample:
To stop the remote SOAP server, right-click the remote server you want to stop, then click Stop SOAPserver.
Note: You cannot start the remote SOAP server from U2 Web Service Developer.
64
Chapter 8: Troubleshooting
Adjusting Java heap space in the DeveloperThis topic describes how to modify the heap size for a Java virtual machine when starting a SOAPserver. This option is not enabled by default.
Description
Under most conditions the U2 SOAP products work as expected. However, when moving extremelylarge amounts of data, it is possible to crash the Java Runtime engine if the default memory limit isexceeded. 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 theperformance of the application. Careful application design is important to ensure that this does notoccur.
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. Open the Web Services Developer.2. Navigate to Window > Preferences and then expand the UniData/UniVerse node.3. Select U2 Web Services Developer.4. Select the Set Java heap sizes option and then modify the sizes as necessary.
Adjusting Java heap space in a deployed environment
65
5. Click Apply to apply the settings, and then click OK.
Adjusting Java heap space in a deployed environmentUnder most conditions the U2 web services work as expected. However, when moving extremely largeamounts of data the Java Runtime engine may fail if the default memory limit is exceeded. If thisoccurs, 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 theperformance of the application. Careful application design is important to ensure that this does notoccur.
Modifying the runsoapserver.bat file on Windows
1. Open the runsoapserver.bat file using an editor.2. Locate the following line:
start javaw.exe -classpath...
3. Modify the command to the following:
start javaw.exe -Xms512m -Xmx1024m -classpath...
Chapter 8: Troubleshooting
66
4. Save the file and then restart the SOAP server.
Modifying the runsoapserver.sh file on UNIX
1. Open the runsoapserver.sh file using an editor.2. 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 anda complete list of the available JVM startup parameters, refer to www.oracle.com.
67
Chapter 9: Sample Code
Creating a WSD web serviceThe 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 serviceusing 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 ""CRTDISPLAY "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
Chapter 9: Sample Code
68
*inpfile = "ROCKET.XML"* Set the contentRet = soapSetRequestContent(SoapReq, inpfile, 0)IF Ret <> 0 THEN STOP "Error in SoapSetRequestContent: " : Ret END * Save requestreqDoc="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 STOPEND *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 wascreated from the request information found in the Source section of the Web Services Explorer WSDLMain utility. For more information on using the WSDL Main utility, see Starting the web service, onpage 41.
<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. Create a new SOAP server. For details on this, see Creating a SOAP server, on page 17.2. 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.3. Enter the appropriate database connection properties and then click Next.4. 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 moreinformation about the SoapCreateRequest function, see the U2 Basic Extensions.
Creating a WSD web service
69
5. Specify the correct Operation information. Add the name of the subroutine you want to call andspecify the number of parameters in the subroutine. Click Next to continue. The screen shouldlook similar to the following example.
Figure 1: Specifying the subroutine Operation information
6. Specify the input and output parameters specified in the subroutine. The XMLRETSUB subroutinehas two parameters: an input and an output. To add a new parameter, select Add and then addthe parameter information in the Define Parameter dialog box, as shown in this example. SeeDefining subroutine parameters, on page 34 for more information.
7. Click Finish.8. Start the web service. For details on starting the web service, see Starting the web service, on
page 41.
Results
After running the example from the WSDL Main utility, you should see a response similar to thefollowing:
Chapter 9: Sample Code
70
Running the command from the command line gives an output similar to the following:
>LOGTO HS.SALES>RUN BP SOAPXMLRETSUBLogging started = 0
U2 SOAP EXAMPLEResponse status : 200²OKResponse headers: Jetty-Request²POST /XMLRETSUB HTTP/1.1■Date²Mon, 18 Aug 2014 14:20:09 GMT■Server²Jetty/4.2.x (Windows 7/6.1 x86 java/1.7.0_51)■Content-Type²text/xml; charset=utf-8■Content-Length²463Response data : <?xml version="1.0" encoding="utf-8" ?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Header/><SOAP-ENV:Body><ns1:CALL_XMLRETSUBResponse xmlns:ns1="http://den-l-aw01"><ns1:OUTP>Hello Rocket</ns1:OUTP></ns1:CALL_XMLRETSUBResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>Logging started = 0>