U2 Web Services Developer

Transcription

1 U2 Web Services Developer User Guide Version DEC2015 December 2015 DBT-DEC2015 WSD-01

2 Notices Edition Publication date: December 2015 Book number: DBT-DEC2015 WSD-01 Product version: Version DEC2015 Copyright Rocket Software, Inc. or its affiliates All Rights Reserved. Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners. Examples This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. License agreement This software and the associated documentation are proprietary and confidential to Rocket Software, Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with the terms of such license. Note: This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product. 2

3 Corporate information Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers. Country Toll-free telephone number United States Australia Belgium Canada China France Germany Italy Japan Netherlands New Zealand South Africa United Kingdom Contacting Technical Support The Rocket Customer Portal is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or find answers to in the U2 Knowledgebase. To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go to In addition to using the Rocket Customer Portal to obtain support, you can send an to u2support@rocketsoftware.com or use one of the following telephone numbers. Country Telephone number North America United Kingdom/France +44 (0) or +44 (0) Europe/Africa +44 (0) Australia or +61 (0) New Zealand

4 Contents Notices... 2 Corporate information... 3 Chapter 1: Getting started... 6 Installing U2 Web Services Development Tool...6 Installing and updating the DBTools using the Eclipse Update Manager...6 XTOOLSUB... 7 Installing XTOOLSUB for UniData on Windows... 8 Installing XTOOLSUB for UniVerse on Windows... 8 Installing XTOOLSUB for UNIX/Linux for UniData... 9 Installing XTOOLSUB for UNIX/Linux on UniVerse...10 Installing XTOOLSUB on Windows Chapter 2: Adding and connecting to servers Establishing server connections U2 server definitions Creating U2 server definitions Viewing or editing advanced settings of a U2 server definition Specifying a command to run on connection Setting up SSL settings for a U2 server definition Editing U2 server definitions...15 Importing an existing U2 server definition Connecting to U2 servers...16 Disconnecting from U2 servers...16 Deleting U2 server definitions Creating a SOAP server Viewing the debug log...20 Displaying cached services Chapter 3: Creating a query web service...22 Creating a query web service using drag-and-drop...22 Creating a query web service using the wizard...25 Starting the web service Chapter 4: Creating a Subroutine web service...32 Creating a subroutine web service using drag-and-drop Defining subroutine parameters...34 Creating a subroutine web service using the wizard Starting the web service Chapter 5: Viewing properties and dictionaries Server properties Account properties File properties File dictionaries...45 Chapter 6: Manually accessing the web services Viewing the web service URL...46 Viewing the WSDL file...46 Web services clients Generating a client proxy in IBM Websphere Application Developer...47 Generating a client proxy in Visual Studio.NET...47 Chapter 7: Deploying web services Exporting web services...48 Importing web services

5 Contents Deploying the SOAP server Updating the SOAP server Defining security between the client and the SOAP server Setting connection properties Defining UniData database connection security...54 Deploying the SOAP service as a Windows service Deploying the SOAP service from the command line Starting the SOAP service from the command line Defining connection security between the client and the SOAP server from the command line...58 Defining database connection properties from the command line Defining database connection security...59 Deploying from the command line Deploying a SOAP server from a configuration file...60 Generating a configuration file...61 Running and stopping the SOAP server...62 Monitoring a remote SOAP server Chapter 8: Troubleshooting Adjusting Java heap space in the Developer...64 Adjusting Java heap space in a deployed environment Chapter 9: Sample Code Creating a WSD web service

6 Chapter 1: Getting started Installing U2 Web Services Development Tool To access the U2 Web Services Developer, you must have UniData 7.8 or greater, with connection pooling 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 local Administrators group. Exit any other Windows applications you have open. Procedure Download your UniData products from for the United States and Canada or if not in the United States or Canada. Make sure you have the UniData Product Configuration sheet that is included with your media. You will need this form when you license the product after installation. From the Setup screen, click Install U2 DBTools. Select U2 Web Services Developer from the list. When the Welcome screen opens, choose the appropriate installation option and then click Next. The Choose Destination Location dialog box appears. By default, U2 Web Services Developer is installed in the C:\U2\U2Tools folder. If you want to install U2 Web Services Developer in a different location, click Browse to select that location. Click Next to proceed with the installation. The Select Program Folder dialog box appears. By default, U2 Web Services Developer is installed in the \U2\U2 Tools folder. If you do not want to install it in this folder, select the folder where you want to install the product and click Next to continue with the installation. At this point, the installation process has enough information to begin copying files. Review the information in the Start Copying Files dialog box. If all of the information is correct, click Next to proceed with the installation. If it is not correct, click Back and correct the appropriate information. When the installation is complete, the Setup Complete dialog box appears. Click Finish to complete the installation Installing and updating the DBTools using the Eclipse Update Manager You can update and install any of the U2 DBTools using the Update Manager in Eclipse. Find the latest information about updates for U2 DBTools at Procedure 6 Launch any U2 DBTools or base Eclipse installations (beginning with Galileo) on your computer.

7 XTOOLSUB From the Eclipse Help menu, select Help Install New Software. Click Add, enter a name for the site, such as U2 Update Site, and in the Work with field enter Click OK. Allow the repository to load and then expand the tree for U2 DBTools. Select the updates that you want to apply. You can also choose to install any other U2 DBTools into your existing workspace. Click Next and follow the installation wizard to complete the installation of updates. Updates will take effect the next time an updated tool is launched. Note: Only tools that are installed through separate InstallShield installations will appear on the Start menu. Tools installed using the Eclipse Update Manager are installed as individual perspectives in a single Eclipse instance. You can access the different perspectives by selecting Window Open Perspective and then selecting the appropriate tool. Note: You can check for updates to the DBTools by selecting Help Check for Updates. To use this option, you must have previously defined the location in the Install New Software dialog, as described in step XTOOLSUB This topic describes the XTOOLSUB program and how to upgrade to the latest version of XTOOLSUB on various operating systems. Updating the XTOOLSUB Program The XTOOLSUB program is a U2 database server-side BASIC program used by various U2 Client Tools. This includes U2 DataVu, U2 Web DE, Basic Developer's Toolkit (BDT), Extensible Administration Tool (XAdmin), Web Services Developer, and more. It also includes any tool that uses the U2 Resource View. XTOOLSUB updates itself automatically. However, if something happens to the XTOOLSUB program you can download the latest version from the public Tech Note site at: The XTOOLSUB program contains several zip and tar files, and includes three or four files, depending on the environment. The XTOOLSUB program is used by all the tools, but the other files included are only used for the Basic Developer's Toolkit (BDT). The XTOOLSUB_EXECPRE/XTOOLSUB_XPRE programs are for pre-execution functionality and XTOOLSUB_EXECPOST/XTOOLSUB_XPST are for post-execution functionality. These programs are discussed further in the related public Tech Note, BDT Extensibility Details. If you have added your own code to the pre- and post-functionality, copy those modified programs to the older database versions rather than the pre- and post- files located here. The files included for UniData are: XTOOLSUB XTOOLSUB_EXECPRE XTOOLSUB_EXECPOST EDAMAPSUB (UniData 6.1 and lower) The files included for UniVerse are: XTOOLSUB XTOOLSUB_XPRE 7

8 Chapter 1: Getting started XTOOLSUB_XPST EDAMAPSUB (UniVerse 10.3 and lower) Do not catalog the EDAMAPSUB subroutine when using UDT 7.1 or UV 11 and higher. This program already exists on those versions. There is a difference between the databases because UniVerse's catalog environment is a type 1 file and has a 14 character file name limit. Only extract the file that is needed for the database server/version and OS type you are using. The...UX.tar (Unix) files come from AIX. You will need to run fnuxi/convcode if you use other UNIX/ Linux operating systems. Files are not included for all operating systems in order to avoid unnecessary confusion. The files in the zip/tar files are the object code for the given programs; do not open them in a text editor. Note: Log in as a root or administrator user when doing these steps to avoid any permissions errors. If an overwrite message occurs, select "yes" to overwrite the file in question. 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 Download the latest version of XTOOLSUB from the public Tech Note site at u2tc.rocketsoftware.com/documentation/ asp. Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory on your server (for example, c:\temp). Extract the file to the c:\u2\ud##\sys\sys_bp (where ## refers to the UniData major version. For example, 61, 71, 72, etc.) directory using your preferred unzipping utility. If UniData is installed in another location, change the path accordingly. Log in to the sys account using telnet or execute a udt shell command in the sys directory on the server. Catalog the three XTOOLSUB programs, as follows: CATALOG SYS_BP XTOOLSUB FORCE CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUB FORCE command. 6. Connect with your U2 client tool to the U2 database server. Installing XTOOLSUB for UniVerse on Windows The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates. However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version. 8

9 Installing XTOOLSUB for UNIX/Linux for UniData Procedure Download the latest version of XTOOLSUB from the public Tech Note site at u2tc.rocketsoftware.com/documentation/ asp Copy the XTOOLSUB_UV_NT.zip or XTOOLSUB_UV_103_NT.zip file to a temporary directory on your server. For example, c:\temp. Extract the file to the c:\u2\uv\bp.o directory using your preferred unzipping utility. If UniVerse is installed in another location, change the path accordingly. Log in to the UV home account via Telnet. The account name is UV or uv in the UV.ACCOUNT file. Catalog the three XTOOLSUB programs, as follows: CATALOG SYS_BP XTOOLSUB FORCE CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE Note: You will receive a catalog error if you try to catalog all three programs on the same command line If you are using UniVerse 10.3 or later, also run CATALOG BP *EDAMAPSUB FORCE command. Connect with your U2 client tool to the U2 database server. Installing XTOOLSUB for UNIX/Linux for UniData The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates. However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version. The $UDTBIN referenced below is an environment variable pointing to your UniData bin directory, for example, /usr/ud##/bin (where ##, is 61,71,72, etc.). If this variable is not set, then reference the full path to the UniData bin directory in the commands. Procedure 4. Download the latest version of XTOOLSUB from the public Tech Note site at u2tc.rocketsoftware.com/documentation/ asp. Copy the XTOOLSUB_UDT_UX.tar or XTOOLSUB_UDT_61_UX.tar file to a temporary directory on your server (for example, /tmp). If transferring using ftp, remember to use binary format. Extract the file to the $UDTHOME/sys/SYS_BP directory. a. To install using UniData 6.1 or earlier, the commands will be: cd $UDTHOME/sys/SYS_BP tar -xvf /tmp/xtoolsub_udt_61_ux.tar b. To install UniData 7.1 or later, the commands will be: cd $UDTHOME/sys/SYS_BP tar -xvf /tmp/xtoolsub_udt_ux.tar If you are using a non-aix operating system, run the convcode command, as shown: $UDTHOME/ sys/sys_bp: $UDTBIN/convcode. Note: The convcode command includes a period at the end of the line. This will convert everything in the SYS_BP file to the current format. All files report that they were converted, but this is the default answer for convcode. The existing files should already be in the correct format. 9

10 Chapter 1: Getting started Change directories to the $UDTHOME/sys directory and then and execute the UDT command, as shown: a. CD $UDTHOME/sys b. $UDTBIN/udt Catalog the three XTOOLSUB programs, as follows: CATALOG SYS_BP XTOOLSUB FORCE CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUB FORCE command. 7. Connect with your U2 client tool to the U2 database server. Installing XTOOLSUB for UNIX/Linux on UniVerse The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates. However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version. Procedure Download the latest version of XTOOLSUB from the public Tech Note site at u2tc.rocketsoftware.com/documentation/ asp Copy the XTOOLSUB_UV_UX.tar or XTOOLSUB_UDT_UV_103_UX.tar file to a temporary directory on your server (for example, /tmp). If transferring files using FTP, remember to use binary file format. Extract the file to the /usr/uv/bp.o directory. If UniVerse is installed in another location, change the path accordingly. Use 'cat /.uvhome' to find the path if needed. Note: `cat /.uvhome` references include single backward quotation marks. This command retrieves the current value for the UniVerse home directory before running the command. a To install using UniVerse 10.3 or earlier, the commands to use are: cd `cat /.uvhome`/bp.o tar -xvf /tmp/xtoolsub_uv_103_ux.tar b. To install using UniVerse 11 or later, the commands to use are: cd `cat /.uvhome`/bp.o tar -xvf /tmp/xtoolsub_uv_ux.tar If you are using a non-aix operating system, run the convcode command, as shown: `cat /.uvhome`/bin/fnuxi XTOOLSUB* Change directories to the UniVerse home directory and then and run the UV command, as shown: a. cd `cat /.uvhome` b. bin/uv Click Escape to exit the menu. Catalog the three XTOOLSUB programs, as follows: 10 CATALOG SYS_BP XTOOLSUB FORCE

11 Installing XTOOLSUB on Windows CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE Note: You will see a catalog error if you try to catalog all three programs on the same command line If you are using UniVerse 10.3 or earlier, also run the CATALOG BP *EDAMAPSUB FORCE command. Connect with your U2 client tool to the U2 database server. Installing XTOOLSUB on Windows The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates. However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version. Procedure Download the latest version of XTOOLSUB from the public Tech Note site at u2tc.rocketsoftware.com/documentation/ asp Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory on your server (for example, c:\temp). Extract the file to the c:\u2\ud##\sys\sys_bp (where ## refers to the UDT major version, i.e. 61, 71, 72, etc.) directory using your preferred unzipping utility. If UniData is installed in another location, change the path accordingly. Log into the sys account using telnet or execute a udt shell command in the sys directory on the server. Catalog the three XTOOLSUB programs, as follows: CATALOG SYS_BP XTOOLSUB FORCE CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE Note: If you are using UniData 6.1 or lower, also run the CATALOG SYS_BP EDAMAPSUB FORCE command. 6. Connect with your U2 client tool to the U2 database server. 11

12 Chapter 2: Adding and connecting to servers This section describes how to create UniData and SOAP servers, and how to connect to those servers. From the Start menu, select All Programs > Rocket U2 > Web Services Developer. A window similar to the following example appears: Establishing server connections U2 server definitions The U2 DBTools interface does not detect the presence of UniData or UniVerse (U2) database servers on the network or let you connect to them by default. To work with UniData or UniVerse accounts and data, 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 shared across a network. One or several users can create multiple U2 server definitions on the same client computer. U2 server is the term for a defined connection to a server computer on which U2 accounts and data are stored. All existing U2 servers on the client computer are listed in the U2 Resource view. You can connect 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 that enables the client computer to connect to the U2 database server on which the accounts and data are stored. Prerequisites Open the U2 DBTools workspace from the Start Rocket U2 menu. Procedure 12 To start the Create a New U2 Server wizard, right-click the U2 Servers node in the U2 Resource view, and click New U2 Server.

13 Viewing or editing advanced settings of a U2 server definition In the Name field, enter a unique name to identify the U2 server definition. The name cannot contain a slash (/) or backslash (\) character. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse is running. From the U2 database server options, select UniData or UniVerse. 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 1 Tip: The default values for advanced settings work best in most situations. Alter these settings only if necessary Optional: To view or update the SSL settings, click Setup SSL. Go to Setting up SSL settings for a U2 server definition, on page 14 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 find it 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 server definition 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 when you 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 4. The Protocol Type field displays TCP/IP as the communications protocol used by the UniData or UniVerse to access the internet. At this time, the only supported protocol is TCP/IP, and this setting cannot be changed. In the RPC Port # field, enter the port number of the UniRPC server running on the host. The default port number is In the RPC Service Name field, enter the name of the remote procedure call (RPC) service on the system. For UniData, the name is normally udcs; for UniVerse, the name is normally uvcs. In the Login Account field, enter the full path to the account folder on the server running UniData or UniVerse. You can enter just the account name if the account is defined in the UD.ACCOUNT or UV.ACCOUNT hash file. 13

14 Chapter 2: Adding and connecting to servers If you run a RetrieVe command, a saved paragraph, or a globally cataloged program every time you connect to the U2 server, you can save time by entering the command in the U2 server definition. To enter a command to run on connection, click Add in the Commands to Execute group box. See Specifying a command to run on connection, on page 14. In the Specify the session to run/debug your BASIC program on server side group box, enter details 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 is 2 c. If device licensing is supported on the server, select the Use Device License check box to conserve license usage in the debug session. While running or debugging BASIC programs, you may use multiple server connections to browse files, check data, update records, or perform other tasks. If device licensing is disabled, the debug session consumes one U2 license for each connection. With device licensing enabled, the session consumes 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 License check 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 time you connect to the U2 server. Rather than type the same command each time you connect, you can increase efficiency and save time by entering the command in the U2 server definition. In the Specify a command field, enter a RetrieVe command, the name of a saved paragraph, or the name of a globally cataloged program to run when you connect to the U2 server. To save the changes and return to the details page, click OK. Setting up SSL settings for a U2 server definition On the Database Connection Security page for the server definition, you can turn on SSL, and add a trust 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 Select the Use SSL checkbox to enable SSL. Note: The key store must be an absolute file. 14 Select Use Default Trust Store to enable the trust store.

15 Editing U2 server definitions Enter the location of the trust store you want to use, or click Browse to navigate the correct location. Enter the trust store password. To save changes to the SSL settings and return to the main page, click Finish. Editing U2 server definitions You can modify the details of an existing U2 server definition, with one exception. It is not possible to change 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 4. To start the Edit U2 Server Definition wizard, right-click the name of the U2 server definition in the U2 Resource view, and click Properties. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse is running. From the U2 database server options, select UniData or UniVerse. 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 1 Tip: The default values for advanced settings work best in most situations. Alter these settings 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 find it 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 definition You can import existing U2 server definitions to your XAdmin environment from the XAdmin Resource View. 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 limit restricted access services, depending on your security policy. It is the function of your security administrator to determine if U2 servers can be imported with credentials included. You can save server resources without password credentials. Procedure From the U2 Resource View, right-click the Servers icon and then select Import U2 Servers. 15

16 Chapter 2: Adding and connecting to servers In the Installation path field, enter the location of the server definitions you want to import. This must be an existing U2 DBTools directory. Select the server definitions you want to import, then click OK. The imported server now shows in the U2 Resource View. Connecting to U2 servers You must open a U2 server connection to work with the accounts stored on the associated UniData or UniVerse (U2) database server computer. You can connect to any U2 server that is listed in the U2 Resource view. Prerequisites Creating U2 server definitions, on page 12 Procedure To start the Connect to a U2 Server wizard, double-click the name of the U2 server in the U2 Resource view. In the User ID field, enter the administrator user name or the user name of a valid user on the server computer running UniData or UniVerse. In the Password field, enter the password for the administrator or user on the server computer. 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 client computer. 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. To connect to the U2 server, click Connect. When the connection is established, the U2 Resource view displays a tree view of the U2 accounts and catalog programs on the U2 database server to which you are connected. Disconnecting from U2 servers After completing tasks for a U2 account, you can disconnect from the U2 server. Disconnecting only closes the connection to the U2 server. It does not delete the U2 server definition or remove the U2 server 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, and click Disconnect. Deleting U2 server definitions If you no longer require access to the U2 accounts and catalog programs on a U2 database server, you can delete the associated U2 server definition. It is not possible to change the name of an existing U2 server. 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. 16

17 Creating a SOAP server The name of the U2 server and folders for its U2 accounts and catalog programs are removed from the list in the U2 Resource view. Creating a SOAP server 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. In the Server Name field, enter a unique name for the SOAP server. The remainder of the fields are populated based on information retrieved by the U2 Web Services Developer tool. You can change any of these fields. The following table describes the fields. Field Description URL The URL for the SOAP server you specify. The URL is automatically detected by the U2 Web Services Developer. We recommend that you not change the URL unless you are sure the new URL you specify is valid and accessible. Port Number The port number on which the server will listen. We recommend that you not change the port number unless that port number is used by another service. Root Path The path to the root directory where the definitions to the web services are stored. Debug Log Indicates whether to start the debug log. If you select true, U2 Web Services Developer starts the debug log each time you start the server. To disable the debug log when the server is running, right-click the SOAP server, then select Turn Off SOAP Server Debug. You can also start the debug log when the SOAP server is running, if it is disable. For more information, Viewing the debug log, on page 20. Log File Name The name of the debug log file. By default, the name of the debug log file is soapservername.log. 17

18 Chapter 2: Adding and connecting to servers Field Description Connection Pooling On The Connection Pooling On setting determines whether UniData uses connection pooling with the U2 Web Services Developer. The term connection pooling refers to the technology that pools permanent connections to data sources for multiple threads to share. It improves application performance by saving the overhead of making a fresh connection each time one is required. Instead of physically terminating a connection when it is no longer needed, connections are returned to the pool and an available connection is given to the next thread with the same credentials. Connection Pooling in enabled by default. If you do not want to use Connection Pooling, clear the Connection Pooling On check box. We recommend using Connection Pooling for superior performance and scalability. Connection Pool Size You can set the minimum and maximum size of the connection pool. If you do not define these sizes, the minimum size defaults to 1 and the maximum size defaults to 10. The minimum size determines the initial size of the connection pool. The size of the connection pool changes dynamically between the minimum and maximum sizes you specify, depending on the system demands. When there are no pooled connections available, UniData either creates another connection, if the maximum connection pool size has not been reached, or keeps the thread waiting in the queue until a pooled connection is released or the request times out. If a pooled connection is idle for a specified time, it is disconnected. SOAP Request Validation Specifies whether the server needs to validate the SOAP request before processing. If this value is set to true, you may experience slight performance degradation, but will have an extra layer of security. Default Name Space The name space for the Web Services you define. Service Cache Size For performance purposes, you can set this value to a number greater than 0 to indicate the number of web service definitions you want to keep in the cache. If you set this value, the SOAP Server will always try to read the web service definition from the cache first. If you do not set this value, the SOAP Server reloads the web service each time from disk. If you are developing a web service, we recommend keeping this value at 0. This setting forces the SOAP Server to reload the new web service definition each time. Select the Cached Services tab to display the web services currently loaded in cache. 18

19 Creating a SOAP server Click Next. The SOAP Server - Connection Security dialog box appears. Select the Use SSL check box if you want to define the SSL security parameters. The following table describes the fields. Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Password Reenter the password corresponding to the key store you defined in the Key Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Password Reenter the encryption key password, if one exists. Enable Authentication If you want the client to send its certification for authentication, select the Need Client Authentication check box. 4. Click Next. The U2 Database - Connection Properties dialog box appears. 5. Select the Specify default database connection properties check box. 19

20 Chapter 2: Adding and connecting to servers 6. In the Host field, select host name from the list of available UniData or UniVerse servers. The remaining fields in the dialog box are populated based on the information retrieved by the U2 Web Services Developer, as shown in the following example: 7. To test the connection to the database, click Test Database Connection. If successful, a message appears stating that a connection exists to the U2 server. Viewing the debug log You can enable the debug log when you create a new SOAP server. If you did not, you can also start and use the debug log while the SOAP server is running. If enabled, the debug log starts each time you start the server. The option to enable the debug log is described in Creating a SOAP server, on page 17. To use the debug log, do the following: 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. To erase the contents of the log file click the Erase icon. To refresh the contents of the log file, click the Refresh icon. Displaying cached services When you define the properties for your SOAP server, you can specify the server cache size. 20 For performance purposes, set the server cache size to the number of web services currently running, or larger.

21 Displaying cached services If you do not set this value, the SOAP Server reloads the web service each time. If you do set this value, next time a web service is needed, the SOAP Server reads it from cache. If you are developing a web service, it is recommend you keep this value at 0. Otherwise, the SOAP Server reloads the cache each time the web service is changed. Select the Cached Services tab to display the web services currently loaded in cache. 21

22 Chapter 3: Creating a query web service This section describes how to create a web service using UniQuery or UniData SQL. Note: You cannot publish a query that requires interactive user input as a web service. Creating a query web service using drag-and-drop 22 From the U2 Web Services Developer window, right-click the account for which you want to create a web service. Expand the Database Files node to view the database files available in the account, as shown in the following example: 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. In the Service Name field, enter a name for the web service you are creating.

23 Creating a query web service using drag-and-drop 4. In the Namespace field, verify or enter the namespace. Click Finish. When you click the service name, information about the SOAP service appears in the Web Service portion of the U2 Web Services Developer dialog box, as shown in the following example: By default, the U2 Web Services Developer creates a LIST statement which includes each D-Type dictionary record contained in dictionary for the file you selected. Click the query statement to view the details for the statement. The Query Details dialog box appears. UniData and UniVerse only support the UniQuery or UniVerse RetrieVe LIST and SORT commands, or the SQL SELECT command. If you want to add an input parameter: a. Modify the statement that appears in the Command Text field, as shown in the following example: The question mark acts as a placeholder for the input value. Press Ctrl+S to save the query, or click the Save icon. The input parameter now appears under the Web Service Input parameter, as shown in the following example: 23

24 Chapter 3: Creating a query web service b. Click the input parameter then click Edit. The Define Parameter dialog box appears. 24 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. e. In the Position field, enter the prompting order of the input parameter. In the Type field, select the data type for the input parameter from the list. Valid types are String and Dynamic array.

25 Creating a query web service using the wizard Creating a query web service using the wizard 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. In the Service Name field, enter a name for the web service you are creating. In the Namespace field, verify or enter the namespace. Click Finish. The U2 Database - Connection Properties dialog box appears. 4. If you have not defined the database connection properties at the SOAP Server-level, you must define them for this Web Service. For more information about defining the data base connections at the SOAP Server-level, see Creating a SOAP server, on page 17. Select the Specify default database connection properties check box. 25

26 Chapter 3: Creating a query web service 5. In the Host field, select host name from the list of available UniData or UniVerse servers. The remaining fields in the dialog box are populated based on the information retrieved by the U2 Web Services Developer, as shown in the following example: 6. To test the connection to the database, click Test Database Connection. If successful, a message appears stating that a connection exists to the U2 server. 26

27 Creating a query web service using the wizard 7. Click Next. The SOAP Server - Connection Security dialog box appears. Select the Use SSL check box if you want to define the SSL security parameters. The following table describes the fields. Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Password Reenter the password corresponding to the key store you defined in the Key Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Password Reenter the encryption key password, if one exists. Enable Authentication If you want the client to send its certification for authentication, select the Need Client Authentication check box. 27

28 Chapter 3: Creating a query web service 8. Click Next. The SOAP Server - Connection Security dialog box appears. Select the Use SSL check box if you want to define the SSL security parameters. The following table describes the fields. 9. Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Password Reenter the password corresponding to the key store you defined in the Key Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Password Reenter the encryption key password, if one exists. Enable Authentication If you want the client to send its certification for authentication, select the Need Client Authentication check box. Click Next. The Operation dialog box appears. 10. In the Name field, enter the name for the web service you are creating. 28

29 Creating a query web service using the wizard 1 From the Type options, select Query. 1 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 SORT commands, or the UniData SQL SELECT statement. If you want to add an input parameter, use a question mark as a placeholder for the input value. Optional: In the Map FileName field, enter the name of the mapping file you want to use, located in the _XML_ directory. c. Optional: In the Record Name field, enter the name of the root element in the XML document the web service creates for the query you specify. If you have two or more query operations within the same web service using the same data file, make sure the record name is different for each operation. d. Press Ctrl+S to save the query, or click the Save icon. 1 Click Next. The Input/Output Parameters dialog box appears. b. 14. Click Finish. The web service definition appears in the Web Service area of U2 Web Services Developer window. 29

30 Chapter 3: Creating a query web service 15. If you specified a placeholder in the web service command, click the input parameter, then click arg_ The Parameter Details dialog box appears. 16. In the Name field, enter a meaningful name of the input parameter. This is the name for which you are prompted when you invoke the service. 17. In the Position field, enter the prompting order of the input parameter. 18. In the Type field, select the data type for the input parameter from the list. Valid types are String and Dynamic array. Starting the web service 30 To start a web service, click the Launch icon from the toolbar. The Web Services Explorer window appears. Click the WSDL icon. Under the Navigator area of the Web Services Explorer window, click WSDL Main. The Open WSDL dialog box appears.

31 Starting the web service 4. From the U2 Web Service area of the Web Services Developer window, click the highlighted web service. The properties of the web service appear in the Properties area of the Web Service window, as shown in the following example: The Web Service operation prompts you for input parameters you previously defined, as shown in the following example: 5. Enter the input value, then click GO. The U2 Web Services Developer displays the resulting XML document in the Status area of the Invoke a WSDL Operation dialog box, as shown in the following example: 6. Click Source to view the XML source for the output. 31

32 Chapter 4: Creating a Subroutine web service This section describes how to create a web service using a UniBasic subroutine. Note: You cannot publish a subroutine that requires interactive user input as a web service. Creating a subroutine web service using drag-and-drop About this task In this example, the following subroutine is used: SUBROUTINE CUSTOMERSUB(ID, REC) OPEN "CUSTOMER" TO F.CUST ELSE REC = "" READ REC FROM F.CUST, ID ELSE REC = "" CLOSE F.CUST RETURN Procedure From the U2 Web Services Developer window, right-click the account for which you want to create a web service. Expand the Cataloged Program node to view the subroutines available in the account, as shown in the following example: Note: You must catalog the subroutine before you start the U2 Web Services Developer. You can globally, locally, or directly catalog subroutines. For information about cataloging UniBasic programs, see UniData Commands Reference. For information about cataloging UniVerse BASIC programs, see UniVerse User Reference. 32

33 Creating a subroutine web service using drag-and-drop Drag the subroutine for which you want to create a web service to the appropriate SOAP Server, as shown in the following figure. 4. In the Service Name field, enter a name for the web service you are creating. Click Finish. Because the program is globally cataloged, the Connection Properties dialog box appears. When the subroutine is not globally cataloged, the Connection Properties dialog box does not appear. Select the Specify default database connection properties check box. Verify the Account field to make sure it defines the account you want to execute the subroutine against, then click Finish

34 Chapter 4: Creating a Subroutine web service 7. In the Namespace field, verify or enter the namespace. Click Finish. When you click the service name, information about the SOAP service appears in the Web Service portion of the U2 Web Services Developer dialog box, as shown in the following example: Defining subroutine parameters Click the subroutine for which you are defining parameters. The Subroutine Details dialog box appears. In the Subroutine Name field, enter the name of the subroutine. In the Number of Parameters field, enter the total number of parameters defined for the subroutine. In the example subroutine, there are two parameters, one input, and one output. From the Input area, click Add. The Define Parameter dialog box appears. a. In the Name field, enter a meaningful name of the input parameter

35 Defining subroutine parameters This name does not have to be the same as the one defined in the UniBasic program. In the Position field, enter the position the input parameter appears in the subroutine. In the Type field, select the data type for the input parameter from the list. Valid types are String and Dynamic array. d. Click OK. From the Output area of the Subroutine Details dialog box, click Add. The Define Parameter dialog box appears. b. c. 5. a. b. c. In the Name field, enter the name of the output parameter. In the Position field, enter the position of the output parameter in the subroutine. In the Type field, enter the data type of the output parameter. In this example, the output parameter is a dynamic array. 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 you specify 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: 35

36 Chapter 4: Creating a Subroutine web service 6. Double-click the dynamic array for which you want to define fields. The Dynamic Array Fields dialog box appears 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.

37 Creating a subroutine web service using the wizard 8. To populate the fields, from the Database Files in the account for which you are creating the web service, drag-and-drop the file pertaining to the dynamic array. The U2 Web Services Developer populates the U2 Dictionary dialog box with each D-type dictionary record, as shown in the following example. 9. Select the check boxes next to the dictionary record ID you want to include in the dynamic array. The number of attributes you select must match the number of fields in the parameter in the subroutine. In this example, the entire record should be returned, so each dictionary attribute is selected except for the CUSTID. 10. Press Ctrl+S to save the query, or click the Save icon. Results When you have finished defining the parameters of the subroutine, the input parameters, output parameters, and dynamic arrays appear in the Web Services area of the U2 Web Services Developer window, as shown in the following example: Creating a subroutine web service using the wizard To create a query web service using the wizard, right-click the SOAP server where you want to create the service, then click New Web Service. In the Service Name field, enter a name for the web service you are creating. In the Namespace field, verify or enter the namespace. Click Next. The U2 Database - Connection Properties dialog box appears. 37

38 Chapter 4: Creating a Subroutine web service If you have not defined the database connection properties at the SOAP Server-level, you must define them for this Web Service. For more information about defining the data base connections at the SOAP Server-level, see Creating a SOAP server, on page 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 want to attach when you connect from the list. This account must contain the data files that you are accessing with the subroutine. 7. In the User ID field, type your login name for the server. Type the corresponding password in the Password field. 8. In the UniRPC Service Name field, type the appropriate UniRPC service name. For UniData, the service name is uvcs. For UniData, the service name is udcs. 9. In the UniRPC Port Number field, type the port number of the UniRPC server running on the host. The default port number is 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. 1 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 following table describes the fields. 38 Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Password Reenter the password corresponding to the key store you defined in the Key Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Password Reenter the encryption key password, if one exists. Enable Authentication If you want the client to send its certification for authentication, select the Need Client Authentication check box.

39 Creating a subroutine web service using the wizard 1 Click Next. The Operation dialog box appears. 1 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. In the Position field, enter the position of the output parameter in the subroutine. In the Type field, select the data type for the input parameter from the list. Valid types are String and Dynamic array. d. Click OK. 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. b. c. 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 you specify does not exist, the following message appears. e. Click Yes to define the new dynamic array. 39

40 Chapter 4: Creating a Subroutine web service 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. 2 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 d. 40 mv - Multivalued ms - Multi-subvalued Click OK.

41 Starting the web service 2 To populate the fields, from the Database Files in the account for which you are creating the web service, drag-and-drop the file pertaining to the dynamic array. The U2 Web Services Developer populates the U2 Dictionary dialog box with each D-type dictionary record, as shown in the following example. 2 Select the check boxes next to the dictionary record ID you want to include in the dynamic array. The number of attributes you select must match the number of fields in the parameter in the subroutine. In this example, the entire record should be returned, so each dictionary attribute is selected except for the CUSTID. 24. Press Ctrl+S to save the query, or click the Save icon. Results When you have finished defining the parameters of the subroutine, the input parameters, output parameters, and dynamic arrays appear in the Web Services area of the U2 Web Services Developer window, as shown in the following example: Starting the web service To start a web service, click the Launch icon from the toolbar. The Web Services Explorer window appears. Click the WSDL icon. 41

42 Chapter 4: Creating a Subroutine web service 42 Under the Navigator area of the Web Services Explorer window, click WSDL Main. The Open WSDL dialog box appears. 4. From the U2 Web Service area of the Web Services Developer window, click the highlighted web service. The properties of the web service appear in the Properties area of the Web Service window, as shown in the following example: In the WSDL URL dialog box, enter the value of the End Point property, then click Go. In the WSDL Details window, select the operation you want to execute, as shown in the following example: 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.

43 Starting the web service 8. Enter the input value, then click GO. The U2 Web Services Developer displays the resulting XML document in the Status area of the Invoke a WSDL Operation dialog box, as shown in the following example: 43

44 Chapter 5: Viewing properties and dictionaries This section describes how to view the properties of accounts, servers, and files, and the file dictionaries. Server properties To display the properties of a server, select the server for which you want to display properties. The properties of that server appear in the Properties area of the U2 Web Services Developer window, as shown in the following example: Property Value Database Name The name of the server you created. Database Type The type of database to which you are connected. Valid types are UniVerse or UniData. Host The host name. Version The version number of the Database Type to which you are connected. XTOOLSUB The version of the XTOOLSUB server subroutine. Account properties To display the properties of an account, click the account for which you want to display properties. The properties of that account appear in the Properties area of the U2 Web Services Developer window, as shown in the following example: Property Value Account Name The name of the account on the server. Account Path The full path to the account on the server. File properties To display the properties of a file, click the account where the file resides, then click the file for which you want to display properties The properties of that file appear in the Properties area of the Web Services Developer window, as shown in the following example: 44

45 File dictionaries Property Value Data File Path The path to the file. If the file resides locally, this field displays the name of the file. If the file resides in a remote location, this field displays the full path to the file. Dictionary Path The name of the dictionary for the file you selected. File Name The name of the file. File Type The type of file. Is EDA File? Indicates whether the file is an EDA file. File dictionaries To display the dictionary of a file, click the file for which you want to display the dictionary, the click the U2 Dictionary tab. Information similar to the following example appears: Property Value ID Dictionary record ID TYPE Type of dictionary record. LOC Field location of the dictionary record if a D-type record, formula if an Itype record, or association components if a PH-type record. CONV Conversion formula, if specified. NAME Display name, if specified. FORMAT Format code. SM Single-valued multivalued, or multi-subvalued code. ASSOC Association name, if part of an association. 45

46 Chapter 6: Manually accessing the web services The section describes how to access web services programmatically. A defined web service is identified by its URL. The format of the URL is: SOAPserverURL/virtual_directory_path/servicename Variable Description SOAPserverURL Defined when you create a new SOAP server. virtual_directory_path A path relative to the configurable root directory of the SOAP server. servicename The name of the web service. You can identify the URL for the web service from the U2 Web Services Developer. Viewing the web service URL You can use the U2 Web Services Developer main window to view the URLs for your web services, as shown in the following example: 4. Open the U2 Web Services Developer main window. Expand the web server where the web service is located. Click the web service for which you want to view the URL. Select the Properties tab. The URL for the web service appears in the End Point field. Viewing the WSDL file You can use a web browser to view WSDL files. Type the URL in a browser. The contents of the WSDL file appears. Web services clients To write a Web Services client program, you create an object of a proxy class, then call the methods for that object. Many software tools can accept a WSDL file and generate proxy classes in many kinds of languages, including Java, C#, VB.NET, and so forth. Proxy classes can be generated automatically because the definition contained in a WSDL file gives a complete description of the interfaces to the Web service you define, including the XML schemas of the input and output data, the SOAP bindings to these schemas, the transportation protocol, and so forth. The proxy classes include a service proxy class, as well as several classes that represent data structures used in the web services. These classes are self-explanatory. 46

47 Generating a client proxy in IBM Websphere Application Developer Generating a client proxy in IBM Websphere Application Developer To generate a Web Service client proxy in IBM Websphere Application Developer, select New. Select the web service client and the project type. Follow the steps in the wizard, and provide the URL of the WSDL file. For more information, see the documentation for the IBM Websphere Application Developer. Generating a client proxy in Visual Studio.NET To generate a Web Service client proxy in Visual Studio.NET, start a new project, then add a Web Reference. The Add Web Reference wizard prompts for the URL for the WSDL file. Provide the URL. The wizard generates a set of proxy classes for the current project. For more information, see the documentation or Visual Studio.NET. 47

48 Chapter 7: Deploying web services The U2 Web Services Developer deployment feature enables you to select a SOAP server defined locally and generate a deployment package, in the form of a zip file, that contains the following: WSDL files The runsoapserver and stopsoapserver scripts All required files for a runtime SOAP server The zip file contains both a.bat and.sh script which enables you to deploy your web services on any platform. Exporting web services You can create a zip file to deploy your web services. 48 Right-click the SOAP server that contains the web service you want to deploy, and select Export. The Export SOAP Servers dialog box appears. In the Available SOAP Servers section, select the SOAP servers you want to export. Enter the path for the zip file you want to create in the Archive File field, or click Browse to search for the location. By default, the U2 Web Services developer places the zip file in C:\U2\U2Tools \v3\soapservername.zip. The zip file contains the following contents:

49 Importing web services 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 services After exporting a SOAP web service from the source development system, you can import it on the target developer web service system. The zip file must be extracted on the target system. For example c:\temp. 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 developer system. Only the web services can be imported, not complete SOAP servers and their services. If a web service of the same name already exists, it will be overwritten. Procedure Right-click the SOAP server that contains the web service that you to import, and select Import. Click Browse to select the root directory for the SOAP server(s) that you want to import. for example, C:\temp\Test\u2soapdeploy. Select the servers that you want to import, and then click Finish. Deploying the SOAP server Extract the zip file on the target machine. From the directory where you unzipped the file, execute the rundeploytool command: rundeploytool current_directory target_directory For example, rundeploytool.bat. C:\temp\myservice 49

50 Chapter 7: Deploying web services Expand Deployable SOAP Servers, right-click the SOAP server you want to deploy, then click Deploy. If the SOAP server already exists, click Deploy Into. The U2 SOAP Service Deployment dialog box appears. 4. The Deployment tool populates the window with information from your local machine. You can change this information if necessary. After making all configuration selections, click Next. The configuration options are described in the following table. Configuration options Description Server Name The name of the SOAP server. Site URL The URL for the SOAP server you specify. Make sure the URL you specify is valid and accessible. Port Number The port number on which the server will listen. Root Path The path to the root directory where the definitions to the web service are stored. Debug On Select the Debug On check box if you want to capture debugging information. If you select this check box, the U2 Web Services Developer starts the debug log each time you start the server. Log File Name The name of the debug log. Connection Pooling On The Connection Pooling On setting determines whether a U2 database uses connection pooling with the U2 Web Services Developer. The term connection pooling refers to the technology that pools permanent connections to a data source for multiple threads to share. It improves application performance by saving the overhead of making a fresh connection each time one is required. Instead of physically terminating a connection when it is no longer needed, connections are returned to the pool and an available connection is given to the next thread with the same credentials. Connection Pooling in enabled by default. If you do not want to use Connection Pooling, clear the Connection Pooling On check box. It is recommended you use Connection Pooling for superior performance and scalability. 50

51 Updating the SOAP server Configuration options Description Connection Pool Size You can set the minimum and maximum size of the connection pool. If you do not define these sizes, the minimum size defaults to 1 and the maximum size defaults to 10. The minimum size determines the initial size of the connection pool. The size of the connection pool changes dynamically between the minimum and maximum sizes you specify, depending on the system demands. When there are no pooled connections available, UniData either creates another connection, if the maximum connection pool size has not been reached, or keeps the thread waiting in the queue until a pooled connection is released or the request times out. If a pooled connection is idle for a specified time, it is disconnected. Message Validation Checks the SOAP request again the schema defined in the WSDL file. This option is time consuming. By default, message validation is not selected. Default Name Space The name space for the Web Services you define. Server Cache Size For performance purposes, you can set this value to a number greater than 0 to indicate the number of web service definitions you want to keep in the cache. If you set this value, the SOAP Server will always try to read the web service definition from the cache first. If you do not set this value, the SOAP Server reloads the web service each time from disk. If you are developing a web service, it is recommended you keep this value at 0. This setting forces the SOAP Server to reload the new web service definition each time. Select the Cached Services tab to display the web services currently loaded in cache. Updating the SOAP server You can update the configuration file used to deploy the SOAP server from the development computer to the deployment environment. The configuration file holds information such as server name, port number, and connection pool information. Open the Web Services Developer tool. In the U2 Web Services pane, right-click the resource you want to update and then select Properties. Follow the menu prompts and update the SOAP server information as needed. 51

52 Chapter 7: Deploying web services Defining security between the client and the SOAP server Click the Specify Connection Security check box if you want to define connection security between the client and the SOAP server. The SOAP Server Connection Security dialog box appears. Select the Use SSL check box if you want to define the SSL security parameters. The following table describes the parameters. 52 Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Password Reenter the password corresponding to the key store you defined in the Key Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Password Reenter the encryption key password, if one exists. Enable Authentication If you want the client to send its certification for authentication, select the Need Client Authentication check box. Click Finish.

53 Setting connection properties Setting connection properties Click the DB Connection tab to define the connection properties for the SOAP server. The U2 Database - Connection Properties dialog box appears. In the Host field, select the name of the host server from the list of UniData servers you have defined. The server should be running. In the Account field, select the account name of the UniData server you specified where you want to attach when you connect from the list. This account must contain the data files that you are accessing with the subroutine. In the User ID field, type your login name for the server. Type the corresponding password in the Password field. In the UniRPC Service Name field, type the appropriate UniRPC service name. For UniData, the service name is uvcs. For UniData, the service name is udcs. In the UniRPC Port Number field, type the port number of the UniRPC server running on the host. The default port number is To test the connection to the database, click Test Database Connection. If successful, a message appears stating that a connection exists to the U2 server. If you want to use the connection properties you specified for subsequent SOAP servers you deploy, select the Use this database connection and security for subsequent SOAP services during deployment check box. Click Next

54 Chapter 7: Deploying web services Defining UniData database connection security 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. 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 to navigate to the key store. Key Store Password Enter the password corresponding to the key store you defined in the Key Store field. Confirm Key Store Password Reenter the password corresponding to the key store you defined in the Key Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Password Reenter the encryption key password, if one exists. Enable Authentication If you want the client to send its certification for authentication, select the Need Client Authentication check box. Click Next. Results U2 Web Services Developer deploys the web services you specified. When deployment is complete, a window similar to the following example appears: 54

55 Deploying the SOAP service as a Windows service The deployable web services appear in the SOAP Servers area of the U2 SOAP Service Deployment dialog box, and shown in the following example: Deploying the SOAP service as a Windows service The u2soapservice.exe is an executable program that is used to create or remove a SOAP service as a Windows service. It is located in the zip file that was created during the export process. Prerequisites The SOAP server must have already been deployed. On Windows 7 and Windows 2008, you must run the Windows Command Prompt as an administrator. To do this, click Start > Accessories > Command Prompt. Right-click the Command Prompt option and select Run as administrator. Java Development Kit 8. If you do not already have JDK 8 installed, you must complete the following steps: Download and install the Java Development Kit, version 8 from the Oracle archive download site. Locate the javaw.exe file in C:\Program Files\Java\jdk8.0_66\bin. 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\jdk8.0_66\bin. 6. Click OK. For this to take effect, the machine must be rebooted. 55

56 Chapter 7: Deploying web services About this task Note: A Windows service can only be created on a deployed package. The syntax for creating a SOAP service is as follows: U2soapservice.exe i u2soap-server-name [-s u2soap-service-name] [-d u2soap-service-description ] The following table lists the options available for deploying a SOAP server as a Windows service. Option Description -i Installs a new U2 SOAP service as a Windows service. -s The name of the U2 SOAP service. -d Description of the U2 SOAP service. The default value is â œu2 SOAP service to start and stop U2 SOAP serverâ. The text of the description must be enclosed in quotation marks (â œâ ). -r Removes the U2 SOAP service. After installing the U2 SOAP service, it can started and stopped as a Windows service from the Windows control panel. When the service starts, it runs the runsoapserver.bat u2soap-server program and waits until this bat file exits. When the service stops, it runs the stopsoapserver.bat u2soapserver program. Additional arguments can be passed to the runsoapserver.bat by specifying the start parameters to the service. Note: If you are creating a Windows service using the u2soapservice.exe program and you get an error similar to the one shown below, you must run the vcredist_x86.exe program supplied with the U2 WSD product to ensure the Windows platform has the compatible Microsoft Visual C redistributable runtime environment: Error: The application has failed to start because its side-by-side configuration is incorrect. Please see the application event log for more details. The syntax for removing a U2 SOAP service is as follows: U2soapservice.exe r u2soap-server Deploying the SOAP service from the command line Use the command line options to deploy the U2 SOAP server from the development computer to the deployment environment. The command line options allow for option-driven, interactive command line deployment. Starting the SOAP service from the command line After exporting the SOAP services, extract the zip file on to the target machine. The zip file contains the following contents: 56 runtime u2soap_deploy servername_deploy_config.xml runsoapserver.bat

57 Starting the SOAP service from the command line stopsoapserver.bat rundeploytool.bat runsoapserver.sh stopsoapserver.sh rundeploytool.sh u2soapservice.exe vcredist_x86.exe EncodingMap.txt U2SOAP_deploy.config Note: Some OS environments, such as those running UNIX, cannot use zip files. If this occurs, recompress the file with a non-zip extraction tool such as 7zip into a gz (gzip) type file. Navigate to the server directory where you extracted the zip file and locate the U2 SOAP deployment tool. Run the rundeploytool command, as shown in the following example: rundeploytool.bat. C:\temp\myservice -s testserver -t prodserver The following table describes each parameter of the syntax: rundeploytool[.sh.bat] deployable_server_dir [target_server_dir]-s server_name [-t target_server] [-f config_file [-u] ] Option Description rundeploytool[.bat.sh] The command to start the deployment tool. Use the.bat script for Windows applications and the.sh script for UNIX/Linux applications. deployable_server_dir The current directory. This can be either the full path or a dot (.) for current directory. target_server_dir The target directory where you want to deploy your U2 SOAP service. -s source_server_name The name of the source server. 4. -t target_server_name The name of the server on which the U2 SOAP server will be deployed. -f config_file (Optional). Add this parameter to input all data from the configuration file. -u The parameter to manually change the database connection credentials. This requires using the -f parameter If the -u parameter is not included in the command, while the connection credentials will be visible, they will not be editable. -l Lists the servers available for deployment. The U2 SOAP server configuration options open in the command line window. Select the appropriate command-line option, as described in the following table. Command line option Description X exit. A Accept. When all of the configuration options are set correctly, click A to continue to the next set of configuration options. 1 Server name. A unique name for your SOAP server. The Site URL field displays the valid URL for the SOAP server. You cannot change the information in this field. 57

58 Chapter 7: Deploying web services Command line option Description 2 Port number. The port number on which the server will listen. Root Path. Displays the path to the root directory where the definitions to the Web service are stored. You cannot change the information in this field. 3 Debug on. Set this value to true to turn on the debug log. Set this value to false to turn the log off. By default, this value is set to false. 4 Log file name. Edit the name of the log file. By default, the name of the log file is defined by the name of the target server. 5 Connection Pooling On. Set this value to true to enable connection pooling. 6 Minimum Connection Pool Size. Sets the minimum number of connections in the connection pool. The minimum size defaults to 7 Maximum Connection Pool Size. Sets the maximum number of connections in the connection pool. The minimum size defaults to Checks the SOAP request again the schema defined in the WSDL file. This option is time consuming. By default, message validation is not selected. 9 The name space for the Web Services you define. 10 For performance purposes, you can set this value to a number greater than 0 to indicate the number of web service definitions you want to keep in the cache. If you set this value, the SOAP Server will always try to read the web service definition from the cache first. If you do not set this value, the SOAP Server reloads the web service each time from disk. If you are developing a web service, we recommend keeping this value at 0. This setting forces the SOAP Server to reload the new web service definition each time. Select the Cached Services tab to display the web services currently loaded in cache. 5. After making any changes to the deployment configuration options, click A to continue. Defining connection security between the client and the SOAP server from the command line After defining the connection configuration, you can define the connection security for the SOAP server. 58 The U2 SOAP connection security options open in the command line window. Select S to view the security options. Select the appropriate action from the options presented in the command line window, as described in the following table. Command line option Description X exit. D Do not specify connection security. Select this option if connection security is not required. 1 Use SSL. Select this option to turn on SSL. 2 Key Store. Enter the name of the Key Store.

59 Defining database connection properties from the command line Command line option Description 3 Key Store password. Enter the password for the Key Store. 4 Key Password. Enter the password for the Key. Use Default Trust Store. Set this value to true to use the default trust store. 5 Need Client Authentication. Set this value to true for the client to send its certification for authorization. After defining any connection security settings for the server, enter A to continue. Defining database connection properties from the command line After defining the server connection properties, you can define the properties for the selected resource folder. The Resource folder property options open in the command line window. Select the appropriate action from the options presented in the command line window, as described in the following table: Command line option Description X Exit. A Accept. Accepts the options as defined. D Do not specify a default database connection. Select this option if connection security is not required. T Test. Tests the database connection. U Use this database connection and security for subsequent SOAP services during deployment. 1 The name of the U2 data server to which you are connecting. 2 The name of the U2 account to which you are connecting. 3 The name of the UniRPC service to which you are connecting. 4 The port number to which you are connecting. 5 The correct user name. 6 The correct password. 7 Select the check box to use SSL. 8 The type of encoding, if any, to use for this web service from the Client Encoding list. After defining any connection security settings for the server, enter A to continue. Defining database connection security After defining the database connection properties, you can define the security for the U2 database connection. Select S from the command line options to access the connection security from the command line. Select the appropriate action from the options presented in the command line window, as described in the following table: 59

60 Chapter 7: Deploying web services Command line option Description X Exit. D Do not specify connection security. Select this option if connection security is not required. 1 Use SSL. Select this option to turn on SSL. 2 Key Store. Enter the name of the Key Store. 3 Key Store password. Enter the password for the Key Store. 4 Key Password. Enter the password for the Key. Use Default Trust Store. Set this value to true to use the default trust store. 5 Need Client Authentication. Set this value to true for the client to send its certification for authorization. Deploying from the command line After any required changes are made to the Resource folder properties, the U2 SOAP server is ready to deploy on the deployment environment. The Resource folder property options open in the command line window. Procedure Select the appropriate action from the options presented in the command line window, as described in the following table. Command line option Description X Exit. G Generate configuration file. This option generates an XML file, server_name_ deploy_configuration.xml, that contains all of the configuration information. Select this option to make changes to the configuration file before deploying. C Continue. This option deploys the server to the deployment environment. Results The U2 SOAP server was deployed to the deployment environment. Deploying a SOAP server from a configuration file A U2 SOAP service can be deployed onto a deployment environment using a generated configuration file. The configuration file is an XML file, server_name_ deploy_configuration.xml, that contains all of the configuration information. The configuration file specifies values that can be changed during deployment, such as login credentials. 60

61 Generating a configuration file Generating a configuration file Use the U2 SOAP deployment tool to generate a configuration file that can be used to deploy the U2 SOAP server from the development computer to the deployment environment. Extract the zip file on to the target machine. The contents of the zip file are extracted into the u2soapdeploy folder, which should contain the following files: rundeploytool.bat rundeploytool.sh runsoapserver.bat runsoapserver.sh runtime stopsoapserver.bat stopsoapserver.sh u2soap U2SOAP_deploy.conf u2soap_workspace u2soapservice.exe vcredist_x86.exe Navigate to the server directory where you extracted the zip file and locate U2SOAP deployment tool. Run the rundeploytool command, as shown in the following example: rundeploytool.bat. C:\temp\myservice The following table describes each parameter of the syntax: rundeploytool[.sh.bat] deployable_server_dir source_target_directory. Parameter Description rundeploytool[.bat.sh] The command to start the deployment tool. Use the.bat script for Windows applications and the.sh script for UNIX/Linux applications. deployable_server_dir The current directory. This can be the full path or a dot (.) for the current directory. source_target_directory The directory where the deployable U2 SOAP server will be located. Running the command opens the U2 Web Services Developer tool Expand the Deployable SOAP Servers node in the SOAP servers pane. Right-click the SOAP server you want to deploy, then click Generate configuration file. Click Browse to select a different configuration file or accept the default configuration file. Click Next. The SOAP Server Configuration dialog box opens. You can specify the environment for the new SOAP server by changing any of the fields. For more information about environment specifications, see Setting connection properties, on page 5 Click Next. The SOAP Server Connection Security dialog box opens. Select the Specify Connection Security check box to make changes to the security settings. Click Next to continue. 61

62 Chapter 7: Deploying web services For more information, see Defining security between the client and the SOAP server, on page 5 The U2 Database Connection Properties window opens. Make any necessary changes to the properties and then click Next. For more information about the connection properties, see Setting connection properties, on page 5 The U2 Database Connection Security window opens. Make any changes and then click Finish. Run the rundeploytool command to deploy the configuration file created in the last step, as shown in the following example: rundeploytool.bat. C:\temp\myservice -s testserver -t prodserver f config_file_name Results The U2 SOAP service is now deployed in the deployment environment. Running and stopping the SOAP server To run the SOAP server, in the target directory, enter: runsoapserver soap_server_name To stop the SOAP server, in the target directory, enter: stopsoapserver soap_server_name Monitoring a remote SOAP server Through the U2 Web Services Developer, you can monitor a remote SOAP server. Complete the following steps to set up remote monitoring Define the remote server by right-clicking SOAP Servers, and selecting New SOAP Server. The Add a New SOAP Server dialog box appears. In the Server Name field, enter a unique name for the SOAP server. In the URL field, enter the URL for the remote server. Based on this URL, U2 Web Services Developer detects that the server is remote, and dims unavailable options. In the Port Number, enter the port number for the remote server. If the remote SOAP server is running, a green icon appears next to the SOAP server, as shown in the following example:

63 Monitoring a remote SOAP server 5. To turn on logging, right-click the remote SOAP server, then click Turn on SOAP Server Debug. U2 Web Services Developer displays the log from the remote server as shown in the following example: To stop the remote SOAP server, right-click the remote server you want to stop, then click Stop SOAP server. Note: You cannot start the remote SOAP server from U2 Web Service Developer. 63

64 Chapter 8: Troubleshooting Adjusting Java heap space in the Developer This topic describes how to modify the heap size for a Java virtual machine when starting a SOAP server. This option is not enabled by default. Description Under most conditions the U2 SOAP products work as expected. However, when moving extremely large amounts of data, it is possible to crash the Java Runtime engine if the default memory limit is exceeded. If this occurs, you will see an out-of-memory error similar to the following: java.lang.outofmemoryerror: Java heap space Explanation A larger heap size will affect garbage collection, as it will run more frequently. This may affect the performance of the application. Careful application design is important to ensure that this does not occur. Resolution If you get this error, you must adjust the heap memory to a larger value. The default values are 256 MB (initial size) and 512 MB (maximum size) Open the Web Services Developer. Navigate to Window > Preferences and then expand the UniData/UniVerse node. Select U2 Web Services Developer. Select the Set Java heap sizes option and then modify the sizes as necessary.

65 Adjusting Java heap space in a deployed environment 5. Click Apply to apply the settings, and then click OK. Adjusting Java heap space in a deployed environment Under most conditions the U2 web services work as expected. However, when moving extremely large amounts of data the Java Runtime engine may fail if the default memory limit is exceeded. If this occurs, you will see an out-of-memory error similar to the following: java.lang.outofmemoryerror: Java heap space If you get this error, you must adjust the heap memory to a larger value. The default values are 256 MB (initial size) and 512 MB (maximum size). A larger heap size will affect garbage collection, as it will run more frequently. This may affect the performance of the application. Careful application design is important to ensure that this does not occur. Modifying the runsoapserver.bat file on Windows Open the runsoapserver.bat file using an editor. Locate the following line: start javaw.exe -classpath... Modify the command to the following: start javaw.exe -Xms512m -Xmx1024m -classpath... 65

66 Chapter 8: Troubleshooting 4. Save the file and then restart the SOAP server. Modifying the runsoapserver.sh file on UNIX Open the runsoapserver.sh file using an editor. Locate the following line: start javaw -classpath... Modify the command to the following: start javaw -Xms512m -Xmx1024m -classpath Save the file and then restart the SOAP server. Note: The JVM startup parameters offer a variety of options for operating the JVM. For details and a complete list of the available JVM startup parameters, refer to 66

67 Chapter 9: Sample Code Creating a WSD web service The instructions in this section uses two example BASIC programs and an XML file: XMLREPSUB, SOAPXMLREPSUB, and ROCKET.XML The XMLREPSUB program is a database subroutine that is called and used by the SOAP web service. * For UniData use the following include. * $INCLUDE INCLUDE XML.H * * Universe use the following include. SUBROUTINE XMLRETSUB(P1,P2) P2="Hello Rocket" END The SOAPXMLRETSUB program is the client-side BASIC subroutine that calls the SOAP web service using the SOAP API. It is used to test your SOAP web service. *************************************************************** * SOAPXMLRETSUB * * For UniData use the following include. * $INCLUDE INCLUDE XML.H * * Universe use the following include. * $INCLUDE UNIVERSE.INCLUDE XML.H * * Example of Sending a ZIP SOAP 0 Request from BASIC * * SOAPXMLRETSUB - PROGRAM TO CALL a BASIC SUBROUTINE "XMLRETSUB" * using SOAP API (UniData 7.7, Universe 13) * Sample program only, not intended for commercial use * This program shows testing SOAP API request to a U2 WSD WEB SERVICE * The XMLRETSUB subroutine called will return a "Hello Rocket" XML Page * * Turn on logging * myfil = "c:\temp\soapxmlretsub.log" RESULT=protocolLogging(myfil,"ON",10) CRT "Logging started = ":RESULT * PROMPT "" CRT DISPLAY "U2 SOAP EXAMPLE" * URL = " SoapAction="CALL_XMLRETSUB" * SoapAction="" Timeout = * Create the Request Ret = SoapCreateRequest(URL, SoapAction, SoapReq) IF Ret <> 0 THEN STOP "Error in SoapCreateRequest: " : Ret END 67

68 Chapter 9: Sample Code * inpfile = "ROCKET.XML" * Set the content Ret = soapsetrequestcontent(soapreq, inpfile, 0) IF Ret <> 0 THEN STOP "Error in SoapSetRequestContent: " : Ret END * Save request reqdoc="c:\u2\ud73\demo\soapxmlretsub.txt" Ret=SOAPRequestWrite(SoapReq, reqdoc, 0) IF Ret <> 0 THEN STOP "Error in SoapRequestWrite: " : Ret END * PRINT "Request Content Status = ":SETREQUEST.STATUS * * Submit the Request Ret = SoapSubmitRequest(SoapReq, Timeout, RespHeaders, RespData, SoapStatus) IF Ret <> 0 THEN CRT "Error in SoapSubmitRequest: " : Ret STATUS=getSocketErrorMessage(Ret, errmsg) CRT errmsg STOP END * PRINT "Response status : " : SoapStatus PRINT "Response headers: " : RespHeaders PRINT "Response data : " : RespData * RESULT=protocolLogging(myfil,"OFF",10) CRT "Logging started = ":RESULT The ROCKET.XML file contains the request information needed by the SOAP web service. This file was created from the request information found in the Source section of the Web Services Explorer WSDL Main utility. For more information on using the WSDL Main utility, see Starting the web service, on page 4 <soapenv:envelope xmlns:soapenv=" xmlns:q0=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <q0:call_xmlretsub> <q0:inp>hello</q0:inp> </q0:call_xmlretsub> </soapenv:body> </soapenv:envelope> Create a new SOAP server. For details on this, see Creating a SOAP server, on page 17. In the U2 Web Services pane, right-click the SOAP Servers node and then select Add new server. Enter the name of the new service name and then click Next. Enter the appropriate database connection properties and then click Next. Enter the correct connection security information. Make sure that the URL parameter in the SOAPXMLRETSUB subroutine matches that of the SOAP server and then click Next. For more information about the SoapCreateRequest function, see the U2 Basic Extensions.

69 Creating a WSD web service 5. Specify the correct Operation information. Add the name of the subroutine you want to call and specify the number of parameters in the subroutine. Click Next to continue. The screen should look similar to the following example. Figure 1: Specifying the subroutine Operation information Specify the input and output parameters specified in the subroutine. The XMLRETSUB subroutine has two parameters: an input and an output. To add a new parameter, select Add and then add the parameter information in the Define Parameter dialog box, as shown in this example. See Defining subroutine parameters, on page 34 for more information. Click Finish. Start the web service. For details on starting the web service, see Starting the web service, on page 4 Results After running the example from the WSDL Main utility, you should see a response similar to the following: 69