Rocket U2 DBTools
User Guide
Version 4.2.0
October 2016 DBT-420-UG-01 Notices
Edition Publication date: October 2016 Book number: DBT-420-UG-01 Product version: Version 4.2.0
Copyright © Rocket Software, Inc. or its affiliates 2011-2016. All Rights Reserved.
Trademarks Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners.
Examples This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
License agreement This software and the associated documentation are proprietary and confidential to Rocket Software, Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with the terms of such license.
Note: This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.
2 Corporate information
Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: www.rocketsoftware.com Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA 02451-1468 USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers.
Country Toll-free telephone number United States 1-855-577-4323 Australia 1-800-823-405 Belgium 0800-266-65 Canada 1-855-577-4323 China 800-720-1170 France 08-05-08-05-62 Germany 0800-180-0882 Italy 800-878-295 Japan 0800-170-5464 Netherlands 0-800-022-2961 New Zealand 0800-003210 South Africa 0-800-980-818 United Kingdom 0800-520-0439
Contacting Technical Support The Rocket Customer Portal is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or read answers to FAQs. To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go to www.rocketsoftware.com/support. In addition to using the Rocket Customer Portal to obtain support, you can use one of the telephone numbers that are listed above or send an email to [email protected].
3 Contents
Notices...... 2 Corporate information...... 3 Chapter 1: Installing DBTools...... 13 New features...... 13 System requirements...... 14 Installing and upgrading DBTools...... 16 Creating server definitions...... 16 Configuring advanced settings of server definitions...... 17 Connecting to servers...... 18 Disconnecting from servers...... 18 Deleting server definitions...... 18 Setting up SSL settings for a U2 server definition...... 19 Importing server definitions...... 19 Creating U2 accounts...... 19 Updating the XTOOLSUB Program...... 20 Installing XTOOLSUB for UniVerse...... 21 Installing XTOOLSUB for UniVerse on Windows...... 21 Installing XTOOLSUB for UNIX/Linux on UniVerse...... 21 Installing XTOOLSUB for UniData...... 22 Installing XTOOLSUB for UniData on Windows...... 22 Installing XTOOLSUB for UNIX/Linux for UniData...... 23 Chapter 2: Basic Developer Toolkit...... 24 Basic Developer Toolkit perspectives...... 24 Filters...... 25 Comparing BASIC programs...... 27 Customizing, compiling, and cataloging for BASIC programs...... 29 Displaying a specific page...... 29 Adding dictionary records...... 30 Code Assist...... 30 Using Code Assist...... 32 Python APIs...... 34 Collapsing blocks of text...... 34 The Outline view...... 34 Creating code templates...... 35 Refactoring programs...... 36 Editing programs...... 36 Creating programs...... 36 Compiling programs...... 36 Customizing syntax colors...... 36 Debugging programs...... 37 The Debug view...... 38 Monitoring program variables...... 39 Default symbols and words...... 39 Default symbols in code assist...... 39 Default words in code assist...... 41 Basic Developer Toolkit and Rocket Aldon LM(e)...... 57 Configuring BDT to use LMU2 commands...... 57 Enabling the LM(e) plugin...... 58 Signing on to and off of LM(e)...... 58 Adding object items...... 59 Checking in object items...... 61
4 Contents
Checking in object items by task...... 61 Checking out object items...... 62 Editing object items...... 65 Marking object items for deletion...... 66 Getting the latest version of object items...... 66 Performing LM(e) actions at the dictionary or folder level...... 67 Displaying LM(e) status...... 69 Shutting down LM(e)...... 70 Chapter 3: EDA Replication Configuration tool...... 71 Starting the EDA Replication Config tool...... 71 Configuring EDA replication...... 71 Defining EDA replication parameters...... 71 Configuring the replication system...... 73 Specifying files to replicate...... 75 Defining EDA data sources...... 77 Defining an EDA data source connection...... 77 Synchronizing replicated files...... 77 Converting U2 files to EDA files...... 78 EDA Schema Manager...... 78 Starting the EDA Schema Manager...... 79 Creating a new U2 server connection...... 79 Connecting to the U2 server...... 81 Managing connections...... 81 About data sources...... 81 Connecting to SQL server, Oracle, or IBM DB2...... 81 Connecting to Microsoft SQL server using the Native Client...... 83 Defining a data source...... 83 Creating EDA schemas...... 85 Creating EDA schemas for selected attributes...... 88 Creating default EDA schemas for the replicated files...... 88 Defining attribute details...... 88 Defining options...... 90 Viewing EDA server details...... 92 Viewing U2 server details...... 93 EDA schema examples...... 93 Scalar function...... 94 TRANS function...... 95 Table function example...... 98 Verifying EDA schemas...... 100 Adding attributes to EDA schemas...... 102 Viewing the DDL scripts...... 103 Converting data from U2 to an external database...... 103 Accessing data in an external database...... 104 Listing data using RetrieVe...... 104 Listing data using UniData/UniVerse SQL...... 105 Working with U2 virtual fields against SQL Server 2008...... 105 Chapter 4: U2 Extensible Administration Tool (XAdmin)...... 108 Getting started...... 108 Starting XAdmin...... 108 Extensible Administration Tool (XAdmin) perspectives...... 108 Managing U2 Audit Logging...... 110 Configuring U2 Audit Logging...... 110 Managing disk space...... 111 Viewing disk space usage...... 111 Managing Secure Sockets Layer (SSL)...... 112
5 Contents
Generating certificate signing requests...... 112 Starting the Generate Certificate Signing Request wizard...... 112 Specifying a file and algorithm for the CSR...... 112 Defining properties of the CSR...... 113 Selecting a key pair option...... 113 Supplying key pair parameters...... 113 Entering a password for the private key file...... 114 Verifying the status of generating the certificate...... 115 Generating SSL certificates...... 115 Starting the Generate SSL Certificate wizard...... 116 Specifying a certificate file name...... 116 Setting the validity period for a new certificate...... 116 Selecting a certificate type...... 117 Optional: Defining certificate extensions...... 117 Selecting required files to generate a certificate...... 118 Selecting the private key file of the CSR...... 118 Selecting the signing certificate file and private key file...... 118 Entering the password for the private key file...... 119 Creating security context records...... 119 Starting the Security Context Record wizard...... 120 Specifying the record ID and protocol...... 120 Selecting server or client usage...... 121 Setting authentication properties...... 121 Setting server authentication properties...... 121 Setting client authentication properties...... 122 Adding trusted peer names...... 123 Selecting the certificate path rule...... 123 Associating certificates to the security context...... 124 Associating server/client certificates to a security context...... 124 Associating a server certificate to a security context...... 125 Optional: Associating a client certificate to a security context...... 125 Selecting the private key file for the server or client certificate...... 126 Optional: Associating CA certificates to a security context record...... 126 Selecting or generating a random file...... 126 Optional: Generating a random file...... 127 Adding seed source files...... 127 Optional: Specifying ciphers...... 128 Optional: Specifying a certificate revocation list...... 128 Setting a password for the SCR...... 128 Verifying the status of generating the SCR...... 129 Configuring SSL for U2 servers...... 129 FIPS mode support...... 130 Managing automatic data encryption...... 130 Administering data encryption...... 130 Managing encryption keys...... 131 Creating encryption keys (XAdmin)...... 131 Deleting encryption keys...... 132 Managing the credential wallet...... 132 U2 servers token-based authentication...... 132 Overview of IdM and token-based authentication...... 132 Token-based authentication...... 133 Authentication token...... 133 Credential mapping record...... 134 Credential wallet...... 134 Creating credential-mapping records...... 134 Updating mapping records...... 136
6 Contents
Deleting mapping records...... 137 Sending the token to the U2 Server...... 138 Managing licenses...... 138 Updating license information...... 139 Obtaining an authorization code...... 140 Configuring account-based licenses...... 140 Managing U2 Data Replication...... 141 Configuring U2 Data Replication...... 141 Defining replication systems...... 142 Adding a publishing group...... 143 Adding a subscribing group...... 144 Optional: Changing a replication group definition...... 146 Verifying the account defaults...... 146 Starting replication...... 147 Disabling replication...... 148 Replication pacing...... 148 Diagnosis utility...... 149 Replication recovery log...... 149 Monitoring replication...... 149 The Replication Status Monitor tab...... 152 Managing Locks in UniVerse...... 156 File and record locks...... 156 Group locks...... 156 Clearing locks...... 157 To clear a file or record lock...... 157 To clear a group lock...... 157 To clear all locks...... 158 Managing locks in UniData...... 158 File/Record Locks tab...... 158 System Resource Locks tab...... 159 Lock Waiting Queue tab...... 159 Clearing locks...... 160 Managing deadlocks (UniVerse)...... 160 Starting and stopping the deadlock manager...... 162 Using the uvdlockd command...... 163 Resolving deadlocks automatically...... 163 Managing Windows Telnet Sessions (Windows only)...... 164 Modifying the Telnet session parameters...... 165 Changing the telnet session port number...... 165 Defining the Telnet user policy...... 165 Setting the Telnet connection parameters...... 166 Setting keep alive parameters...... 166 Specifying the Telnet logon banner...... 166 Specifying the termination pause...... 166 Administering Telnet users (UniVerse)...... 167 Adding Telnet users...... 167 Add a UniVerse domain user...... 168 Adding a local machine user...... 168 Configuring Telnet user profiles...... 168 Default user profile...... 169 Specify default shell...... 170 Specify startup directory...... 170 Specify arguments...... 170 Specify UDTHOME...... 170 Determine ANSI version...... 170 Determine how to map characters...... 170
7 Contents
Prompt for working directory...... 171 Customizing Telnet user profiles...... 171 Generated profiles...... 172 UniVerse file utilities...... 174 Administering UniVerse files...... 174 Listing files in a UniVerse account...... 175 View file properties...... 175 Base information...... 176 Header information...... 176 National Language Support (NLS) information...... 177 Transaction logging information...... 178 Indexes information...... 179 Backup and replication information...... 180 View file statistics...... 181 File information...... 182 File statistics...... 182 Running file diagnostics...... 183 Repairing damaged files...... 184 Administering UniData Files...... 186 Listing files that are level 2 overflow...... 187 Administering the Convcode file tool...... 188 Administering the Convdata file tool...... 188 Administering the Convidx file tool...... 189 Converting ASCII values...... 190 Extracting readable records from corrupted files...... 191 Administering the Filever file tool...... 192 Administering the Fixfile file tool...... 193 Administering the Guide file tool...... 195 Optimizing file size...... 197 Converting a file to a sequentially hashed file...... 198 Administering the Udfile file tool...... 200 Monitoring system activity in UniVerse...... 200 Listing active UniVerse processes and jobs...... 200 Terminating a process...... 201 Monitoring system activity in UniData...... 201 Chapter 5: U2 Metadata Manager...... 203 Getting started...... 203 Prerequisites...... 203 Starting U2 MDM...... 203 U2 MDM perspective...... 204 U2 Resource view...... 204 U2 MDM editor views...... 205 Options available in the Metadata view...... 205 Fields in the metadata graphical editor...... 206 Fields in the metadata text editor...... 206 Null values...... 207 Options available in the 1NF Map view...... 207 Fields in the 1NF graphic pane...... 208 Fields in the 1NF text view...... 208 Generated Keys...... 209 Tutorial...... 210 Creating metadata files...... 210 Creating 1NF files...... 210 Choosing virtual attributes...... 211 Creating schemas...... 211 Data type enforcement...... 212
8 Contents
(Optional) Changing the data type enforcement...... 212 (Optional) Enabling data type enforcement...... 212 Enabling data type enforcement in the graphical editor...... 212 Enabling UniData data type enforcement in the metadata text editor...... 213 Generating metadata and 1NF maps...... 214 Generating metadata files...... 214 Adding virtual fields to metadata...... 215 Generating 1NF maps...... 215 Editing data in U2 MDM...... 216 Editing files in the graphical editor...... 216 Editing metadata table properties in the graphical view...... 216 Editing 1NF table properties in the graphical view...... 217 Editing metadata files in the text editor...... 218 Editing 1NF files in the text editor...... 218 Working with schemas...... 219 UniData schema rules...... 219 Making your non-compliant UniData file names accessible...... 220 UniVerse schema rules...... 220 Generating schemas...... 220 Viewing the schema...... 221 Testing the schema...... 221 Creating metadata for a schema...... 222 Synchronizing metadata repository with the dictionary...... 224 Synchronizing the data using the Metadata Synchronization wizard...... 224 Enforcing data types...... 225 Selecting an attribute for data type enforcement...... 225 Creating and deleting a metadata list...... 226 CREATE.METADATA...... 226 DELETE.METADATA...... 226 LIST.METADATA...... 227 Data type enforcement (DTENF) commands...... 228 ENABLE.DTENF...... 228 DISABLE.DTENF...... 229 LIST.METADATA...... 229 VERIFY.DTENF...... 231 SET.DTELOG...... 231 INMAT function...... 232 Deployment for UniData...... 232 UniData metadata repository...... 232 Deploying a metadata map...... 232 Deploying the UniData metadata repository...... 232 Deploying a UniData metadata file...... 233 Deploying a relational schema...... 234 Example: Deploying a single SQLDEF file...... 234 Example: Deploying all SQLDEF files...... 235 Deployment for UniVerse...... 235 UniVerse metadata repository...... 235 Deploying a schema for UniVerse...... 236 Chapter 6: U2 RESTful Web Service Developer...... 237 U2 RESTful web services...... 237 U2 REST server...... 238 U2 REST resources...... 238 REST resource folders...... 239 URI addresses...... 239 U2 REST subroutine resources...... 240 HTTP methods (U2 REST)...... 241
9 Contents
HTTP GET method...... 241 HTTP POST method...... 245 HTTP PUT method...... 247 HTTP DELETE method...... 248 U2 REST connection pooling...... 249 U2 REST transaction support...... 250 U2 RESTful Web Service Developer...... 250 U2 RESTful Web Services Developer...... 251 U2 REST workspace...... 252 Tutorial...... 254 Creating a U2 server entry...... 254 Creating a REST server...... 255 Creating a resource folder...... 256 Creating a data resource...... 257 Testing a data resource...... 259 (Optional) Linking multiple resources using a foreign key...... 260 Creating a REST subroutine resource...... 264 Defining input parameters...... 266 Defining output parameters...... 267 Testing the REST subroutine service...... 269 Manually testing the REST subroutine service...... 270 U2 REST security...... 272 User authentication and authorization...... 273 Authorizing a user...... 274 Authenticating a user...... 275 SB+ and RESTful web services...... 276 Accessing SB+ files...... 276 Modifying SB+ parameters...... 276 Regenerating files...... 278 Deployment...... 280 Deployment environment requirements...... 280 Creating a deployment package...... 280 Exporting RESTful web services...... 281 Importing RESTful web services...... 282 Deploying a U2 RESTful server as a Windows service...... 282 Generating a configuration file...... 283 Deploying a RESTful server using the U2 REST deployment tool...... 286 Starting the U2 REST GUI deployment tool...... 286 Defining security between the client and the REST server...... 288 Defining user access...... 289 Defining the Resource folder properties in the GUI tool...... 290 Deploying a REST server from the command line...... 291 Starting the U2 REST deployment tool from the command line...... 291 Defining U2 RESTful server connection security from the command line...... 293 Defining Resource folder properties from the command line...... 294 Deploying a REST server from the command line...... 294 Deploying a REST server from a configuration file...... 295 Updating the configuration file using the GUI tool...... 296 Disabling security protocols from the configuration file...... 296 Starting a RESTful service...... 297 Stopping a RESTful service...... 297 Remote servers...... 298 Code samples...... 298 UniBasic code samples...... 298 UniBasic HTTP GET...... 298 UniBasic HTTP POST...... 299
10 Contents
UniBasic HTTP PUT...... 300 UniBasic HTTP DELETE...... 301 UniBasic REST subroutine...... 302 UniBasic RETSUB...... 302 UniBasic URLENC...... 303 UniVerse BASIC code samples...... 303 UniVerse BASIC HTTP GET...... 303 UniVerse BASIC HTTP POST...... 304 UniVerse BASIC HTTP PUT...... 305 UniVerse BASIC HTTP DELETE...... 306 UniVerse BASIC REST subroutine...... 307 UniVerse BASIC RETSUB...... 307 UniVerse BASIC URLENC...... 308 Python for UniData code samples...... 308 Python for UniData: HTTP GET...... 308 Python for UniData: HTTP POST...... 309 Python for UniData: HTTP PUT...... 310 Python for UniData: HTTP DELETE...... 310 Python for UniData: REST subroutine...... 311 Python for UniVerse code samples...... 312 Python for UniVerse: HTTP GET...... 312 Python for UniVerse: HTTP POST...... 312 Python for UniVerse: HTTP PUT...... 313 Python for UniVerse: HTTP DELETE...... 314 Python for UniVerse: REST subroutine...... 314 Authenticating a U2 REST server...... 315 U2 BASIC subroutine...... 316 Output types...... 317 Troubleshooting...... 322 Backing up the U2 REST Developer workspace...... 322 Adjusting Java heap space...... 322 Adjusting Java heap space in a deployed environment...... 323 Defining web server listening IP addresses...... 324 Defining the JRE_HOME environment variable...... 324 Chapter 7: U2 Web Service Developer...... 326 U2 Web Service Developer perspectives...... 326 Creating a query web service...... 327 Defining SOAP servers...... 327 Viewing the debug log...... 331 Displaying cached services...... 332 Creating a query web service...... 332 Starting the web service...... 338 Creating a subroutine web service...... 339 Creating subroutine web services...... 340 Defining dynamic arrays...... 343 Starting the web service...... 344 Viewing properties and dictionaries...... 346 Server properties...... 346 Account properties...... 347 File properties...... 347 File dictionaries...... 347 Manually accessing the web services...... 348 Viewing web service URLs...... 348 Viewing the WSDL file...... 348 Web services clients...... 349 Deploying web services...... 349
11 Contents
Deploying SOAP Server...... 349 Exporting and importing web services...... 349 Deploying the SOAP server...... 351 Updating the SOAP server...... 353 Defining security between the client and the SOAP server...... 353 Setting connection properties...... 354 Defining database connection security...... 355 Deploying the SOAP service as a Windows service...... 356 Deploying the SOAP service from the command line...... 357 Starting the SOAP service from the command line...... 357 Defining connection security between the client and the SOAP server from the command line...... 359 Defining database connection properties from the command line...... 359 Defining database connection security...... 360 Deploying from the command line...... 361 Deploying a SOAP server from a configuration file...... 361 Generating a configuration file...... 361 Starting and stopping SOAP servers...... 363 Enabling logging for remote SOAP servers...... 363 Troubleshooting...... 364 Adjusting Java heap space in the Developer...... 364 Adjusting Java heap size in a deployed environment...... 365 Defining web server listening IP addresses...... 366 Sample Code...... 366 Creating a WSD web service...... 366
12 Chapter 1: Installing DBTools
Rocket U2 DBTools is a set of Eclipse-based applications for programming and administration. DBTools includes the following programs: ▪ Basic Developer Toolkit (BDT) Use the Basic Developer Toolkit (BDT) to write and manage code more efficiently. Users are able to do in-line syntax checking, check code completion, use hover help, refactor, use code style templates, compile and catalog programs, edit dynamic array and HTML, debug a program, and manage applications that are integrated with Rocket Aldon LM(e). ▪ External Database Access (EDA) Schema Manager Use the EDA Schema Manager to create a mapping file, called EDA Schema, for a U2 file you are converting to the external database. Then use the mapping file to convert the U2 data to the external database format. ▪ EDA Replication Configuration tool Use the EDA Replication Config tool to edit EDA map schemas, edit data source definitions, and convert UniData or UniVerse files to EDA files. ▪ U2 Metadata Manager Use the U2 Metadata Manager (MDM) to view the dictionary, define metadata, and create 1NF maps of metadata files. ▪ RESTful Web Service Developer Use the U2 RESTful Web Services Developer to define and publish U2 resources, such as data files and subroutines, to a U2 REST server. ▪ Web Service Developer Use the U2 Web Services Developer to define and publish U2 resources, such as data files and subroutines, to a SOAP server. ▪ Extensible Administration Tool (XAdmin) Use the U2 Extensible Administration Tool (XAdmin) to administer UniData or UniVerse (U2) database servers.
Additional resources For additional information about U2 products, training, and technical resources go to http:// www.rocketsoftware.com/products/rocket-u2. New features
The following are new features for DBTools.
Basic Developer Toolkit (BDT) Beginning at this release, BDT is now integrated with Aldon. To enable Aldon, click Windows → Preferences → UniData/UniVerse → LMe and check the LMe flag. At this release, the Basic Developer Toolkit now recognizes U2 Python APIs.
13 Chapter 1: Installing DBTools
EDA Replication Configuration tool There are no new features at this release.
EDA Schema Manager There are no new features at this release.
U2 Metadata Manager There are no new features at this release.
U2 RESTful Web Service Developer
Beginning at this release, -Dloopbackonly=true can be added to the startup script to change the IP address to 127.0.0.1. Changing the IP address to 127.0.0.1 enables only the local server to connect to any port that the web server has enabled.
Web Service Developer There are no new features at this release.
Extensible Administration tool (XAdmin) Beginning at this release, Credential Wallet administration tasks have been added for UniVerse. Users are able to add, update, or delete credential mapping records. Users are also able to configure and manage wallet tasks such as changing a password and adding or removing machine tags. System requirements
Before you install DBTools, make sure that the computer you are installing it on meets the following requirements.
Basic Developer Toolkit ▪ The installation computer must be running Microsoft Windows Server 2008 SR2 or Windows 7, or later. ▪ The data server must be running UniData 7.1 or later, or UniVerse 10.3 or later.
EDA Schema Manager ▪ The installation computer must be running Microsoft Windows Server 2008 SR2 or Windows 7, or later. ▪ The data server must be running UniData 7.1 or later, or UniVerse 11.1 or later
Metadata Manager ▪ The installation computer must be running Microsoft Windows Server 2008 SR2 or Windows 7, or later. ▪ UniData or UniVerse services must be currently running on the server. ▪ UniVerse 11.1.11 or later must be running on the server.
▪ UniData 7.3 or later must be running on the server, and the udtconfig file must contain the QUOTED_IDENTIFIER=1 parameter.
14 System requirements
RESTful Web Service Developer ▪ The installation computer must be running Microsoft Windows Server 2008 SR2 or Windows 7, or later. ▪ UniVerse 11.2.5 or later must be running on the server (UniVerse only) for security compliance reasons. ▪ UniData 8.1.0 or later must be running on the server (UniData only) for security compliance reasons. ▪ U2 RESTful web services use port number 9191 as the default port when the first RESTful web services is created. Each subsequent web service port number will increase in increments of two. A second port number is also used when the U2 RESTful web service is started and it is always the defined port number plus one. For example, 9191 and 9192. ▪ The default port number used by the U2 RESTful web services to communicate to the U2 database engine is always 31438 unless changed. ▪ Firewalls must be open for incoming and outgoing traffic on all defined ports. ▪ Java Runtime Environment (JRE) 1.8 must be installed on the target deployment platform. Currently, JRE 1.8 is the only version supported by U2 REST. Problems may occur if other versions are used. ▪ The U2 DBTools are shipped with Java 8u60, which is the minimum security requirement for deploying RESTful web services. ▪ The JRE_HOME environment variable must point to the location of the JRE installation directory.
Web Service Developer ▪ The installation computer must be running Microsoft Windows Server 2008 SR2 or Windows 7, or later. ▪ UniVerse 11.2.5 or later must be running on the server (UniVerse only) for security compliance reasons. ▪ UniData 8.1.0 or later must be running on the server (UniData only) for security compliance reasons. ▪ U2 RESTful web services use port number 9191 as the default port when the first RESTful web services is created. Each subsequent web service port number will increase in increments of two. A second port number is also used when the U2 RESTful web service is started and it is always the defined port number plus one. For example, 9191 and 9192. ▪ The default port number used by the U2 RESTful web services to communicate to the U2 database engine is always 31438 unless changed. ▪ Firewalls must be open for incoming and outgoing traffic on all defined ports. ▪ Java Runtime Environment (JRE) 1.8 must be installed on the target deployment platform. Currently, JRE 1.8 is the only version supported by U2 REST. Problems may occur if other versions are used. ▪ The U2 DBTools are shipped with Java 8u60, which is the minimum security requirement for deploying RESTful web services. ▪ The JRE_HOME environment variable must point to the location of the JRE installation directory.
15 Chapter 1: Installing DBTools
Extensible Administration Tool (XAdmin) ▪ The installation computer must be running Microsoft Windows Server 2008 SR2 or Windows 7, or later. ▪ The data server must be running UniData 7.1 or later, or UniVerse 10.3 or later.
Installing and upgrading DBTools
Use the Update Manager in Eclipse to install and upgrade DBTools. For the latest information about updates to U2 DBTools, go to http://updates.rocketsoftware.com/u2.
Procedure
1. Launch a DB tool or base Eclipse installation (beginning with Galileo) on your computer. 2. To install new software, click Help → Install New Software, or, to check for updates, click Help → Check for Updates. 3. Click Add, enter a name for the site, such as U2 Update Site, and in the Work with field enter http://updates.rocketsoftware.com/u2. Click OK. 4. After the repository loads, expand the tree for U2 DBTools. Select the tools to install or the updates to apply. 5. Click Next, and follow the installation wizard to complete the installation. Updates to a tool take effect the next time that you launch the tool. Each tool is installed as a perspective in a single Eclipse instance. To access a tool, click Window → Open Perspective and select the tool.
Creating server definitions
To connect to accounts and data, you must create a server definition on the compter that hosts DBTools.
About this task A server definition is stored on the computer on which it was created and is not shared across a network. Multiple users can create multiple server definitions on the same computer. When you create a server definition, the name of the new server is added to the U2 Resource view. You cannot change the name of an existing server. However, you can delete the server definition and create it again using a new name.
Procedure
1. Open the U2 DBTools workspace from the Start → Rocket U2 menu. 2. Right-click the U2 Servers node in the U2 Resource view, and click New U2 Server. 3. In the Name field, enter a unique name for the server definition. The name cannot contain a slash (/) or backslash (\) character. 4. In the Host field, enter the name or IP address of the computer on which UniData or UniVerse is running. 5. From the U2 database server options, select UniData or UniVerse.
16 Configuring advanced settings of server definitions
6. Optional: To view or edit the unirpc service name, port number, and other advanced settings that define the connection, click Advanced. The default values for advanced settings work best in most situations. Alter these settings only if necessary. For more information about altering the settings, go to Configuring advanced settings of server definitions, on page 17. 7. Optional: To view or update the SSL settings, click Setup SSL. For information about altering the SSL settings, go to Setting up SSL settings for a U2 server definition, on page 19. 8. Click Finish to save the server definition.
Configuring advanced settings of server definitions
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.
Procedure
1. The Protocol Type field displays TCP/IP as the communications protocol used by that the server uses to access the internet. At this time, the only supported protocol is TCP/IP, and this setting cannot be changed. 2. In the RPC Port # field, enter the port number of the UniRPC server running on the host. The default port number is 31438. 3. In the RPC Service Name field, enter the name of the remote procedure call (RPC) service on the system. For UniData, the name is normally udcs; for UniVerse, the name is normally uvcs. 4. In the Login Account field, enter the full path to the account folder on the server running UniData or UniVerse. You can enter just the account name if the account is defined in the UD.ACCOUNT or UV.ACCOUNT hash file. 5. To enter a command to run on connection, click Add in the Commands to Execute group box. 6. 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. 7. 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 22. 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.
17 Chapter 1: Installing DBTools
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.
8. To save changes to advanced settings and return to the main page, click Finish.
Connecting to servers
After you connect to a server, you can work with the accounts in the database. 1. Double-click the name of the server in the U2 Resource view. 2. 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. 3. In the Password field, enter the password for the administrator or user on the server computer. 4. Optional: 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. 5. If you are using a proxy server, select the Use Proxy Server check box. a. In the Proxy Host field, enter the name or IP address of the computer that hosts the proxy server. b. In the Proxy Port field, enter the number of the port on which the proxy server listens for communication from UniData or UniVerse. 6. To connect to the 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 server to which you connected.
Disconnecting from servers
Disconnecting closes the connection to the server. Disconnecting does not delete the server definition or remove the server from the U2 Resource view. In the U2 Resource view, right-click the name of the server from which you want to disconnect, and click Disconnect.
Deleting server definitions
If you no longer require access to the accounts and catalog programs on a server, delete the server definition.
About this task When you delete a server definition, the server name and the folders for its accounts and catalog programs are removed from the U2 Resource view.
Procedure
In the U2 Resource view, right-click the name of the U2 server to delete, and click Delete.
18 Setting up SSL settings for a U2 server definition
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.
Procedure
1. Select the Use SSL checkbox to enable SSL. 2. Select Use Default Trust Store to enable the trust store. 3. Enter the location of the trust store you want to use, or click Browse to navigate the correct location.
Note: The trust store must be an absolute file.
4. Enter the trust store password. 5. To save changes to the SSL settings and return to the main page, click Finish.
Importing server definitions
You can import existing server definitions to your environment.
Prerequisites When you import a server definition, 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
1. From the U2 Resource view, right-click the Servers icon and select Import U2 Servers. 2. In the Installation path field, enter the location of the server definitions to import. 3. Select the server definitions to import, and click OK. The U2 Resource view displays the imported server definitions.
Creating U2 accounts
An account is a container for a collection of related files for a business purpose or activity.
About this task A U2 account is a virtual container used to organize a collection of related files and data for a specific business purpose or activity. For example, a business organization might create a U2 account to track sales data. More technically, a U2 account is a UNIX or Windows directory in hashed format that contains a vocabulary (VOC) file and other U2 system files that provide the environment in which to run U2 tools and applications. An account can be configured to meet the needs of one user, a job function, a department, or an entire company.
19 Chapter 1: Installing DBTools
A U2 account is associated with a specific U2 server definition.
Procedure
1. Open the DBTools workspace from the Start → Rocket U2 menu. 2. From the Select U2 server list, select the name of the server to associate with the new U2 account. 3. In the Account Name field, enter a unique name for the account. 4. In the Account Path field, enter the full path for the account, or click Browse to select a location. To create the account in a path that does not already exist, select the Create the account path if it does not exist check box. 5. Click Finish. 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 Toolkit (BDT), Extensible Administration Tool (XAdmin), Web Services Developer, and more. It also includes any tool that uses the U2 Resource View. XTOOLSUB updates itself automatically. However, if something happens to the XTOOLSUB program you can download the latest version from the public Tech Note site at: https://u2tc.rocketsoftware.com/documentation/1410028.asp The XTOOLSUB program contains several zip and tar files, and includes three or four files, depending on the environment. The XTOOLSUB program is used by all the tools, but the other files included are only used for the Basic Developer 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 earlier) The files included for UniVerse are: ▪ XTOOLSUB ▪ XTOOLSUB_XPRE ▪ XTOOLSUB_XPST ▪ EDAMAPSUB (UniVerse 10.3 and earlier) Do not catalog the EDAMAPSUB subroutine when using UDT 7.1 or UV 11.1 and later. 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
20 Installing XTOOLSUB for UniVerse
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.
Installing XTOOLSUB for UniVerse
Installing XTOOLSUB for UniVerse on Windows
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates. However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https:// u2tc.rocketsoftware.com/documentation/1410028.asp 2. Copy the XTOOLSUB_UV_NT.zip or XTOOLSUB_UV_103_NT.zip file to a temporary directory on your server. For example, c:\temp. 3. Extract the file to the c:\u2\uv\BP.O directory. If UniVerse is installed in another location, change the path accordingly. 4. Log into the UV home account via Telnet. The account name is UV or uv in the UV.ACCOUNT file. 5. Catalog each of the following XTOOLSUB programs separately:
▪ CATALOG SYS_BP XTOOLSUB FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE 6. If you use UniVerse 10.3 or later, run the CATALOG 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.
Prerequisites 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.
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https:// u2tc.rocketsoftware.com/documentation/1410028.asp 2. Copy the XTOOLSUB_UV_UX.tar or XTOOLSUB_UDT_UV_103_UX.tar file to a temporary directory on your server (for example, /tmp). If you use FTP to transfer files, remember to use binary file format. 3. Extract the file to the /usr/uv/BP.O directory. If UniVerse is installed in another location, change the path accordingly. If necessary, use the following command to find the path: 'cat /.uvhome' a. To install using UniVerse 10.3 or earlier, the commands to use are:
21 Chapter 1: Installing DBTools
cd `cat /.uvhome`/BP.O tar -xvf /tmp/XTOOLSUB_UV_103_UX.tar b. To install using UniVerse 11.1 or later, the commands to use are: cd `cat /.uvhome`/BP.O tar -xvf /tmp/XTOOLSUB_UV_UX.tar 4. If you are using a non-AIX operating system, run the convcode command, as shown: `cat /.uvhome`/bin/fnuxi XTOOLSUB* 5. Change directories to the UniVerse home directory and then and run the UV command, as shown: a. cd `cat /.uvhome` b. bin/uv 6. Click Escape to exit the menu. 7. Catalog each of the following XTOOLSUB programs separately:
▪ CATALOG SYS_BP XTOOLSUB FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE 8. If you are using UniVerse 10.3 or earlier, also run the CATALOG BP *EDAMAPSUB FORCE command. 9. Connect with your U2 client tool to the U2 database server.
Installing XTOOLSUB for UniData
Installing XTOOLSUB for UniData on Windows
The XTOOLSUB program is installed and updated automatically through the U2 DBTools updates. However, if your version of XTOOLSUB somehow becomes unusable, you can install a new version.
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https:// u2tc.rocketsoftware.com/documentation/1410028.asp. 2. Copy the XTOOLSUB_UDT_NT.zip or XTOOLSUB_UDT_61_NT.zip file to a temporary directory on your server (for example, c:\temp). 3. Extract the file to the c:\u2\ud##\sys\SYS_BP directory. In the directory, ## represents a major version number, such as 61, 71, 72, and so on. If UniData is installed in another location, change the path accordingly. 4. Log into the sys account using Telnet or execute a udt shell command in the sys directory on the server. 5. Catalog each of the following XTOOLSUB programs, separately:
▪ CATALOG SYS_BP XTOOLSUB FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE 6. If you are using UniData 6.1 or earlier, run the CATALOG SYS_BP EDAMAPSUB FORCE command. 7. Connect with your U2 client tool to the U2 database server.
22 Installing XTOOLSUB for UNIX/Linux for UniData
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.
Prerequisites Log in as a root or administrator user. If an overwrite message occurs, select yes to overwrite the file in question.
About this task In the following task, $UDTBIN is an environment variable that points to the UniData bin directory, for example, /usr/ud##/bin, where ##, is a major version number, such as 61,71,72, and so on. If this variable is not set, specify the full path to the UniData bin directory in the commands.
Procedure
1. Download the latest version of XTOOLSUB from the public Tech Note site at https:// u2tc.rocketsoftware.com/documentation/1410028.asp. 2. Copy the XTOOLSUB_UDT_UX.tar or XTOOLSUB_UDT_61_UX.tar file to a temporary directory on your server (for example, /tmp). If you use FTP to transfer files, remember to use binary format. 3. Extract the file to the $UDTHOME/sys/SYS_BP directory. a. On UniData 6.1 or earlier, enter the following commands: cd $UDTHOME/sys/SYS_BP tar -xvf /tmp/XTOOLSUB_UDT_61_UX.tar b. On UniData 7.1 or later, enter the following commands: cd $UDTHOME/sys/SYS_BP tar -xvf /tmp/XTOOLSUB_UDT_UX.tar 4. If you are using a non-AIX operating system, run the following convcode command to convert everything in the SYS_BP file to the current format. Include the period at the end of the command:
$UDTHOME/sys/SYS_BP: $UDTBIN/convcode . 5. Change directories to the $UDTHOME/sys directory and then and execute the UDT command, as shown: CD $UDTHOME/sys $UDTBIN/udt 6. Catalog each of the following XTOOLSUB programs separately:
▪ CATALOG SYS_BP XTOOLSUB FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPRE FORCE ▪ CATALOG SYS_BP XTOOLSUB_EXECPOST FORCE 7. If you use UniData 6.1 or earlier, run the CATALOG SYS_BP EDAMAPSUB FORCE command. 8. Connect with your U2 client tool to the U2 database server.
23 Chapter 2: Basic Developer Toolkit
Use the Basic Developer Toolkit (BDT) to write and manage code more efficiently. Users are able to do in-line syntax checking, check code completion, use hover help, refactor, use code style templates, compile and catalog programs, edit dynamic array and HTML, debug a program, and manage applications that are integrated with Rocket Aldon LM(e). Basic Developer Toolkit perspectives
The following example illustrates the default Basic Developer Toolkit perspective:
By default, the workspace is arranged in a standard layout, but you can move or resize views. Each view contains its own controls for minimizing and maximizing the space consumed within the workspace. Alternatively, you can drag the border of a view to increase or decrease its size. A view may contain just one item or tabs for multiple items. Each view or tab within the view has a Close (X) button to close the entire pane or to close a tab within the pane. You can do no damage in experimenting with the workspace. If you close a view and want to show it again later, you can select it from the Window menu. Otherwise, if you want to reset the main window to show all views in their default locations, you can select Window → Reset.
24 Filters
U2 Resource view The U2 Resource view displays information about each account on the server to which you are connected. This information includes accounts, data files, dictionary files, BASIC programs, XML/DB mapping files, and cataloged programs.
Properties view The Properties view displays the properties for each file, account, program, server, and resource available. Select a node in any view to see the properties for that node. The first time that you select a file in the Resource view, the file path and dictionary path information might show as "unknown" in the Properties pane. This behavior improves the initial loading of content in the U2 Resource view. To populate the file information, select another file and then reselect the original file.
U2 Dictionary view The U2 Dictionary view displays the dictionary information about the database files in the U2 Resource view. You can see data source information and view the structure of the file system from in this view.
Filters
You can establish filters to filter out information you do not want the Basic Developer Toolkit to display. There are two types of filters, Resource-type filters and pattern filters.
Resource-type Filters Resource-type filters include server filters, account filters, and file filters. ▪ Server Filter - Use the server filter to exclude UniData or UniVerse servers from being displayed in the Basic Developer Toolkit. By default, the server filter is empty.
25 Chapter 2: Basic Developer Toolkit
▪ Account Filter - Use the account filter to exclude UniData or UniVerse accounts from being displayed in the Basic Developer Toolkit. By default, the Basic Developer Toolkit filters out UniData and UniVerse system accounts using the following pattern: Master*, sys*, bin_*. ▪ File Filter - Use the file filter to exclude UniData or UniVerse files from being displayed in the Basic Developer Toolkit. By default, UniData excludes the following files: CTLG SAVELISTS _HOLD_ _PH_ _XML_ savedlists _MAP_ _report_ AE-related files CTLGTB ENGLISH.MSG ERRMSG HELP.FILE MENUFILE REP_RECV_LOG REP_RECV_REC VOC _DEBUG_ voc privilege _REPORT_ _SCREEN APP.PROGS BASIC.HELP catdir GLOBAL.CATDIR DICT.files By default, UniVerse excludes the following files: CTLG SAVEDLISTS &HOLD& &PH& &XML& savedlists &MAP& &report& AE-related files CTLGTB
26 Comparing BASIC programs
ENGLISH.MSG ERRMSG HELP.FILE MENUFILE REP_RECV_LOG REP_RECV_REC VOC &DEBUG& &MAP& voc privilege &REPORT& &SCREEN& UV.ACCOUNT APP.PROGS BASIC.HELP catdir GLOBAL.CATDIR NLS-related files DICT.files UNIVERSE.files UV_files UV.files SYS.files REVISE.files
Pattern Filters Use a pattern filter to exclude any name defined by the pattern you specify from being displayed in the Basic Developer Toolkit. This filter is disabled by default. 1. To enable, select Window → Preferences → UniData/UniVerse. 2. Select Enable Pattern Configuration, and then click Apply. 3. In the U2 Resource View, click Accounts to open the filter dialog box.
Comparing BASIC programs
You can compare two BASIC programs and display the differences between them. 1. From the U2 Resource view, select the first program you want to compare in the account and file where it resides. 2. Next, press CTRL and click the second program. 3. Right-click Compare With and select Each Other.
27 Chapter 2: Basic Developer Toolkit
The two programs are displayed side-by-side, and the differences between the programs are highlighted. You can also compare the history of changes to a program made on your local machine.
28 Customizing, compiling, and cataloging for BASIC programs
4. To compare local history, right-click the program for which you want to view history, then select Team → Show Local History. The Basic Developer Toolkit shows the local history for the program you selected.
5. You can compare changes made to the program by selecting the two revision times you want to compare, then repeat steps 1-3.
Customizing, compiling, and cataloging for BASIC programs
You can specify compilation and cataloging options for BASIC programs at the account level or the program level. Program options set at the directory level override program options set at the account level.
1. Right-click the account or directory file for which you want to set options, then click U2 Basic Program Options. 2. To set options for UniData, complete the following steps: a. Select the BASICTYPE to use. b. If you want reserved words to be case insensitive, select the Reserved words in UniBasic are case insensitive check box. c. Select the catalog options for the directory or account, and click Finish.
3. To set options for UniVerse, complete the following steps: a. If you want variables and labels to be case insensitive, select the Variables and labels in UniVerse BASIC are case insensitive check box. b. Select the catalog options for the directory or account, and click Finish.
Displaying a specific page
When a directory contains many items, select a specific page to display. 1. From the U2 Resource view, to select the page you want to display, right-click the file containing the items, then highlight Switch displaying page, then click the page where you want to begin the display. 2. To configure a pattern for the page to display, right-click the file containing the items, then click Configure Patterns.
29 Chapter 2: Basic Developer Toolkit
3. In the Configure Name Patterns dialog box, enter the file name patterns you want to match. Separate each pattern with a comma. Pattern matching characters are: ▪ * = any string ▪ ? = any character ▪ ,, (2 commas) = , (comma) 4. Select the page where you want to start displaying the filtered items in the Go To Page field.
Adding dictionary records
Dictionary records define the fields of a file. Each field has 8 attributes that you can add or change. Dictionary records are used by the query language and are not required when creating a program. 1. To add a dictionary record, from the U2 Resource view, right click the file, and click Add. 2. In the ID field, enter the ID for the dictionary record. 3. In the Type field, enter the type of dictionary record. Valid values are: ▪ D - Numeric and alphabetic character ▪ V or I - Virtual attribute formula ▪ PH - Phrase ▪ X - User-defined phrase 4. If the dictionary record is a D-type, enter the location of the attribute in the Formula field. 5. If the dictionary record is a V-type or I-type, click Build under the Formula field. a. Compose the virtual formula, or click the type of function, expression, or operator you need to build the formula. 6. If the dictionary record is a PH-type, enter the phrase in the Formula field. 7. If the dictionary record is an X-type, enter the phrase in the Formula field. 8. Optional: Enter a conversion code in the Conversion field. 9. Optional: Enter a column heading, if different from the record ID, in the Display Name field. 10. Optional: Enter the length, justification, and other formatting codes in the Display Format field. 11. Select the type of attribute in the SM box. ▪ For UniData, valid values are S for singlevalued, MV for multivalued, and MS for multi- subvalued. ▪ For UniVerse, valid values are S for singlevalued or M for multivalued. 12. Optional: If the dictionary record is part of an association, select the name of the association in the Association box. If you edit a dictionary record using the Dynamic Array Editor, you can add, delete, or update any field. This is useful for Pick-type dictionary records, where A-type and S-type dictionary records have different field definitions. For example, field 3 is defined as the column heading for A-type and S-type dictionary records, but is the conversion code for D-type, I-type, and V-type records. Dictionary records are verified and an error or warning is returned if the record contains an invalid or missing value. Code Assist
Code Assist uses code templates and helps in avoiding syntax errors.
30 Code Assist
Code Assist checks the following elements in addition to the code template: ▪ Verbs ▪ Keywords ▪ Functions ▪ @ Variables ▪ $ Variables ▪ Defined labels ▪ Defined variables ▪ Defined user functions
The Basic Developer Toolkit uses a set of default verbs, keywords, functions, @variables, and $ variables. To override these defaults, create a file named XTOOLSUB.DATA file in the udthome/ sys directory, for UniData, or the universe_home/include directory for UniVerse. In the file, create two sections: one for symbols and one for words.
Enter *symbols to indicate the beginning of the symbol section. On each line of the section, use the following syntax to specify a symbol:
{"symbol_name", symbol_type, 0} where symbol_type is one of the following values: ▪ Vavariable - @ Variable (read/write) ▪ Vrvariable - @Variable (read only) ▪ Vprequate - Pre-defined equate statement The following example illustrates the symbols section of the file:
* *symbols * {"@SYSTEM.RETURN.CODE", Vavariable, 0} {"@STDFIL", Vavariable, 0} {"@SELECTED", Vavariable, 0} {"@IM", Vprequate, 0, "Add: more ITM"} {"@FM", Vprequate, 0} {"@AM", Vprequate, 0} {"@VM", Vprequate, 0} . . .
Enter *words to indicate the beginning of the words section. On each line of the section, use the following syntax to specify a word:
{“name”, type, num_of_args, max_num_of_args, optional_arg_flag, left_value_arg_list, optional_description} where name is and type is one of the following values:
Value Description Lunknown Type unknown Lbflag Statement that starts at the line.
31 Chapter 2: Basic Developer Toolkit
Value Description Lbfunc Function style statement (CONVERT, DELETE, REMOVE) Lbos Beginning of line statement Lelse Special case: 'ELSE' Lend Special case: 'END' Lflag Check keyflag Lfunct Check for following '(' Lloc Special case: 'LOCATE' Llock Special case: 'LOCKED' (also checks keyflag) Lloop Special case: 'UNTIL' & 'WHILE' Lnext Special case: 'NEXT' Lsub Special case: 'SUBROUTINE' Lthen Special case: 'THEN' Lget Special case: 'GET(' Lseek Special case: 'SEEK(' Lprntr Special case: 'PRINTERR' Lexec Special case: 'PERFORM' Lstat Special case: 'STATUS' Lerror Special case: '(ON) ERROR' Lbig Special case: '$DEFINE, $UNDEFINE' Lcdir Special case: '$ELSE, $ENDIF'
The code assist feature uses the num_of_args, max_num_of_args, optional_arg_flag, and left_value_arg_list for functions only.
The following example illustrates the words portion of the XTOOLSUB.DATA file:
* *words * {"$DEFINE", Lbos, 0, 0, 0, 0} {"$ELSE", Lcdir, 0, 0, 0, 0} {"$ENDIF", Lcdir, 0, 0, 0, 0} {"$F", 0, 0, 0, 0, 0} {"$FALSE", 0, 0, 0, 0, 0} {"$IFDEF", Lbig, 0, 0, 0, 0} {"$IFNDEF", Lbig, 0, 0, 0, 0} {"$OPTIONS", Lbos, 0, 0, 0, 0} . . .
Using Code Assist
Using Code Assist with GOSUB If you enter a GOSUB or GOTO statement, the Basic Developer Toolkit displays all the labels contained in the program. Enter:
GOSUB(CTRL+SPACE)
32 Using Code Assist
Select the correct subroutine from the list.
Using Code Assist with CALL If you enter a CALL statement followed by a (CTRL+SPACE), the Basic Developer Toolkit displays all globally and locally cataloged programs in alphabetical order.
Using Code Assist with Functions When you enter the name of UniBasic or UniVerse function, the Basic Developer Toolkit displays detailed information for the function. If you enter the following statement:
RET = XDOM(CTRL+SPACE) The Basic Developer Toolkit will display all functions beginning with "XDOM." When you select the function, the Basic Developer Toolkit inserts the function as a template:
RET = XDOMOpen(xmlDocument, docLocation, domHandle) Press the tab key to enter your values for the function parameters.
33 Chapter 2: Basic Developer Toolkit
Viewing Syntax You can hover over a UniBasic or UniVerse BASIC function or statement to view the syntax. After the syntax appears, press F2 to keep the syntax on the screen.
Python APIs
BDT recognizes the following Python APIs: ▪ @variables ▫ @PYEXCEPTIONMSG ▫ @PYEXCEPTIONTRACEBACK ▫ @PYEXCEPTIONTYPE ▪ PyCall function ▪ PyCallFunction function ▪ PyCallMethod function ▪ PyGetAttr function ▪ PyImport function ▪ PySetAttr function For more information, see U2 Python User Guide.
Collapsing blocks of text
You can collapse certain blocks of text within the program. If you click the "-" icon, the Basic Developer Toolkit collapses the statement. After the statement is collapsed, you can hover over the "+" to view the statements.
The Outline view
The Basic Developer Toolkit displays all procedures and labels that appear in the source code you specify. With this outline, you can easily jump to appropriate reference in the source code.
34 Creating code templates
The Basic Developer Toolkit uses the following icons:
Included File
Label
Variable or user function
Common variable
Array
Creating code templates
Create code templates that simplify your work. For example, create a code template to insert the author and date for the source code.
Procedure
1. From the Basic Developer Toolkit Editor, click Window → Preferences → UniData/UniVerse → U2 Basic → Editor → Templates. 2. In theTemplate dialog box, click New, and then enter a name and description. 3. From the Basic Developer Toolkit Editor, you can automatically create a template by marking a segment of the source code. After marking the source code, click U2 Basic, then click Copy Selection as Template. In addition, you can edit, import, or remove a code template.
35 Chapter 2: Basic Developer Toolkit
Refactoring programs
Refactoring changes the internal structure of a program without modifying its external behavior or existing functionality. You usually refactor a program to improve the readability or extensibility of the code or to simplify the structure of the code.
Procedure
1. From the Basic Developer Toolkit Editor, right-click the name of the element to change and expand Refactor, and click Rename. 2. In the New name field, enter the name for the element, and click Preview to display instances of the original name and a preview of the changes. 3. Click OK.
Editing programs
Use a dynamic array editor or an XML editor to edit programs. 1. From the Editing area, select the source code to edit. 2. Click the U2 Basic menu, and then click Edit Selection as Dynamic Array or Edit Selection as XML.
Creating programs
Procedure
1. From the U2 Resource view, right-click the database file where you want to create the program, and click New → Basic Program. 2. In the Basic Program Name field, enter the name of the program, and click Finish. 3. Create the program, and select File → Save..
Compiling programs
From the U2 Basic menu, click Compile U2 Program. The U2 Console displays messages generated during the compilation process.
Customizing syntax colors
The Basic Developer Toolkit recognizes UniBasic and UniVerse BASIC syntax, and provides syntax highlighting. You can configure the color and format for the code.
About this task The Basic Developer Toolkit highlights syntax errors after each unsuccessful compilation. Press F2 to switch focus to the window that contains the syntax. Scroll up and down to see the full syntax.
36 Debugging programs
Procedure
1. From the Basic Program Editor, click Window → Preferences → UniData/UniVerse → U2 Basic → Syntax Coloring. 2. Customize the color for one or more elements. Debugging programs
Procedure
1. From the Basic Developer Toolkit toolbar, click the arrow next to the debug icon. 2. Click Debug Configurations.
3. On the Main tab of the Debug dialog box, expand the account of the program that you want to debug.. 4. Click the Source tab. In this tab, the Basic Developer Toolkit displays directory files for the source locator to find the source code. 5. Click Add to include another path for the source code. 6. Click the Terminal tab. 7. In the User ID box, enter the login ID on the server to which you want to connect. Enter the corresponding password in the Password box. 8. Select the terminal type you want to use in the Terminal Type box. 9. Enter the port number you want to use in the Port Number box. 10. Click Debug.
37 Chapter 2: Basic Developer Toolkit
The Debug view
When you debug a UniVerse BASIC program in the Basic Developer Toolkit, the debug perspective appears, consisting of the several views. The sections include: ▪ Stack view ▪ Variable View ▪ Breakpoints View ▪ Outline View ▪ Console View ▪ U2 Console View ▪ U2 Debug Terminal View
Stack view The Stack View shows the current calling stack, as shown in the following example:
Variable view The Variable View displays all the variables contained in the program and their values in the program that is currently running, as shown in the following example:
38 Monitoring program variables
Monitoring program variables
The Basic Developer Toolkit does not automatically monitor all variables. 1. To monitor a variable, right-click the variable, and select Enable Watch Flag. 2. To show only monitored variable in the list, right-click in the Variables view, and select Show Monitored Variable Only. Default symbols and words
If you do not specify a symbol or word in the XTOOLSUB.DATA file, the code assist feature uses default symbols and words.
Default symbols in code assist
This section describes the default symbols used by the code assist feature of the Basic Developer Toolkit.
Note: The BDT client does not support hard-coded marks (CHAR(251) - CHAR(255)) directly. Instead, users can use up arrow (^) sequences on the BDT client-side for hard-coded marks. For example, in a BDT BASIC program editor, the users will see ^253 for VM marks and ^094 for up arrow marks.
*symbols * {"@SYSTEM.RETURN.CODE", Vavariable, 0} {"@STDFIL", Vavariable, 0} {"@SELECTED", Vavariable, 0} {"@IM", Vprequate, 0, "Add: more ITM"} {"@FM", Vprequate, 0} {"@AM", Vprequate, 0} {"@VM", Vprequate, 0} {"@SM", Vprequate, 0} {"@SVM", Vprequate, 0} {"@TM", Vprequate, 0} {"@CRTHIGH", Vprequate, 0} {"@CRTWIDE", Vprequate, 0} {"@LPTRHIGH", Vprequate, 0} {"@LPTRWIDE", Vprequate, 0} {"@WHO", Vrvariable, 0} {"@LOGNAME", Vrvariable, 0} {"@ACCOUNT", Vrvariable, 0}
39 Chapter 2: Basic Developer Toolkit
{"@USERNO", Vrvariable, 0} {"@USER.NO", Vrvariable, 0} {"@COMMAND", Vrvariable, 0} {"@SENTENCE", Vavariable, 0} {"@PARASENTENCE", Vrvariable, 0} {"@SYS.BELL", Vrvariable, 0} {"@LEVEL", Vrvariable, 0} {"@TIME", Vavariable, 0} {"@DATE", Vavariable, 0} {"@DAY", Vavariable, 0} {"@MONTH", Vavariable, 0} {"@YEAR", Vavariable, 0} {"@FILENAME", Vavariable, 0} {"@FILE.NAME", Vavariable, 0} {"@RECORD", Vavariable, 0} {"@ID", Vavariable, 0} {"@USER.RETURN.CODE", Vavariable, 0} {"@SYSTEM.SET", Vavariable, 0} {"@TERM.TYPE", Vrvariable, 0} {"@NB", Vavariable, 0} {"@ND", Vavariable, 0} {"@NI", Vavariable, 0} {"@RECCOUNT", Vavariable, 0} {"@NV", Vavariable, 0} {"@MV", Vavariable, 0} {"@NS", Vavariable, 0} {"@ANS", Vavariable, 0} {"@CONV", Vavariable, 0} {"@DICT", Vavariable, 0} {"@FORMAT", Vavariable, 0} {"@HEADER", Vavariable, 0} {"@OPTION", Vavariable, 0} {"@USER0", Vavariable, 0} {"@USER1", Vavariable, 0} {"@USER2", Vavariable, 0} {"@USER3", Vavariable, 0} {"@USER4", Vavariable, 0} {"@RECUR0", Vavariable, 0}
40 Default words in code assist
{"@RECUR1", Vavariable, 0} {"@RECUR2", Vavariable, 0} {"@RECUR3", Vavariable, 0} {"@RECUR4", Vavariable, 0} {"@TTY", Vavariable, 0} {"@NULL", Vrvariable, 0} {"@NULL.STR", Vrvariable, 0} {"@SQL.ERROR", Vrvariable, 0} {"@SQL.WARNING", Vrvariable, 0} {"@SQL.CODE", Vrvariable, 0} {"@SQL.STATE", Vrvariable, 0} {"@SCHEMA", Vrvariable, 0} {"@TRANSACTION.ID", Vrvariable, 0} {"@AUTHORIZATION", Vrvariable, 0} {"@ABORT.CODE", Vrvariable, 0} {"@COMMAND.STACK", Vprequate, 0} {"@DATA.PENDING", Vprequate, 0} {"@PATH", Vrvariable, 0} {"@TRANSACTION", Vrvariable, 0} {"@ISOLATION", Vrvariable, 0} {"@TRANSACTION.LEVEL", Vrvariable, 0} {"@TRUE", Vprequate, 0} {"@FALSE", Vprequate, 0} {"@HENV", Vrvariable, 0} {"@HDBC", Vrvariable, 0} {"@HSTMT", Vrvariable, 0} {"@SQLPROC.NAME", Vrvariable, 0} {"@SQLPROC.TX.LEVEL", Vrvariable, 0} {"@SQL.DATE", Vrvariable, 0} {"@SQL.TIME", Vrvariable, 0} {"@CASCADE", Vrvariable, 0} {"@YEAR4", Vavariable, 0} {"@DF.IOTYPE", Vrvariable, 0}
Default words in code assist
This section describes the default words used by the code assist feature of the Basic Developer Toolkit. *words
41 Chapter 2: Basic Developer Toolkit
* {"$DEFINE", Lbos, 0, 0, 0, 0} {"$ELSE", Lcdir, 0, 0, 0, 0} {"$ENDIF", Lcdir, 0, 0, 0, 0} {"$F", 0, 0, 0, 0, 0} {"$FALSE", 0, 0, 0, 0, 0} {"$IFDEF", Lbig, 0, 0, 0, 0} {"$IFNDEF", Lbig, 0, 0, 0, 0} {"$OPTIONS", Lbos, 0, 0, 0, 0} {"$T", 0, 0, 0, 0, 0} {"$TRUE", 0, 0, 0, 0, 0} {"$UNDEFINE", Lbos, 0, 0, 0, 0} {"ABORT", Lbflag, 0, 0, 0, 0} {"ABORTE", Lbos, 0, 0, 0, 0} {"ABORTM", Lbos, 0, 0, 0, 0} {"ABS", Lfunct, 1, 1, 0, 0} {"ABSS", Lfunct, 1, 1, 0, 0} {"acceptConnection", Lfunct, 6, 6, 0, LVA_4|LVA_5|LVA_6} {"ACOS", Lfunct, 1, 1, Ftrig, 0} {"ACTIVATEKEY", Lbos, 0, 0, 0, 0} {"addAuthenticationRule",Lfunct, 4, 4, 0, 0} {"addCertificate", Lfunct, 5, 5, 0, 0} {"addRequestParameter", Lfunct, 4, 4, 0, 0} {"ADDS", Lfunct, 2, 2, 0, 0} {"ALL", Lflag, 0, 0, 0, 0} {"ALPHA", Lfunct, 1, 1, 0, 0} {"amInitialize", Lfunct, 4, 4, 0, LVA_1|LVA_4} {"amReceiveMsg", Lfunct, 9, 10, 0, LVA_6|LVA_7|LVA_9} {"amReceiveRequest",Lfunct, 9, 10, 0, LVA_5|LVA_6|LVA_9} {"amSendMsg", Lfunct, 6, 6, 0, LVA_6} {"amSendRequest", Lfunct, 7, 7, 0, LVA_7} {"amSendResponse", Lfunct, 7, 7, 0, LVA_7} {"amTerminate", Lfunct, 3, 3, 0, LVA_1|LVA_3} {"analyzeCertificate", Lfunct, 3, 3, 0, 0} {"AND", 0, 0, 0, 0, 0} {"ANDS", Lfunct, 2, 2, 0, 0} {"ARG.", Lflag, 0, 0, 0, 0} {"ASCII", Lfunct, 1, 1, 0, 0}
42 Default words in code assist
{"ASIN", Lfunct, 1, 1, Ftrig, 0} {"ASSIGN", Lbos, 0, 0, 0, 0} {"ASSIGNED", Lfunct, 1, 1, 0, 0} {"ATAN", Lfunct, 1, 1, Ftrig, 0} {"AUTHORIZATION", Lbos, 2, 2, 0, 0} {"AUTHORIZE", Lfunct, 2, 2, 0, 0} {"AUXMAP", Lbos, 0, 0, 0, 0} {"BCONVERT", Lfunct, 2, 2, 0, 0} {"BEFORE", Lflag, 0, 0, 0, 0} {"BEGIN", Lbos, 0, 0, 0, 0} {"BITAND", Lfunct, 2, 2, 0, 0} {"BITNOT", Lfunct, 1, 2, Fnego, 0} {"BITOR", Lfunct, 2, 2, 0, 0} {"BITRESET", Lfunct, 2, 2, 0, 0} {"BITSET", Lfunct, 2, 2, 0, 0} {"BITTEST", Lfunct, 2, 2, 0, 0} {"BITXOR", Lfunct, 2, 2, 0, 0} {"BREAK", Lbos, 0, 0, 0, 0} {"BSCAN", Lbos, 0, 0, 0, 0} {"BY", Lflag, 0, 0, 0, 0} {"BYTE", Lfunct, 1, 1, 0, 0} {"BYTELEN", Lfunct, 1, 1, 0, 0} {"BYTETYPE", Lfunct, 1, 1, 0, 0} {"BYTEVAL", Lfunct, 1, 2, Fone, 0} {"CALL", Lbos, 0, 0, 0, 0} {"CALLING", Lflag, 0, 0, 0, 0} {"CAPTURING", Lflag, 0, 0, 0, 0} {"CASE", Lbflag, 0, 0, 0, 0} {"CAT", 0, 0, 0, 0, 0} {"CATS", Lfunct, 2, 2, 0, 0} {"CENTURY.PIVOT", Lfunct, 1, 1, 0, 0} {"CHAIN", Lbos, 0, 0, 0, 0} {"CHANGE", Lfunct, 3, 5, 0, 0} {"CHAR", Lfunct, 1, 1, 0, 0} {"CHARS", Lfunct, 1, 1, 0, 0} {"CHECKSUM", Lfunct, 1, 1, 0, 0} {"CLEAR", Lbos, 0, 0, 0, 0} {"CLEARCOMMON", Lbos, 0, 0, 0, 0}
43 Chapter 2: Basic Developer Toolkit
{"CLEARDATA", Lbos, 0, 0, 0, 0} {"CLEARDIAGNOSTICS", Lfunct, 0, 0, 0, 0} {"CLEARFILE", Lbos, 0, 0, 0, 0} {"CLEARINPUT", Lbos, 0, 0, 0, 0} {"CLEARPROMPTS", Lbos, 0, 0, 0, 0} {"CLEARSELECT", Lbos, 0, 0, 0, 0} {"CLOSE", Lbflag, 0, 0, 0, 0} {"CLOSESEQ", Lbos, 0, 0, 0, 0} {"closeSocket", Lfunct, 1, 1, 0, LVA_1} {"CloseXMLData", Lfunct, 1, 1, 0, 0} {"COL1", Lfunct, 0, 0, 0, 0} {"COL2", Lfunct, 0, 0, 0, 0} {"COM", Lbos, 0, 0, 0, 0} {"COMMIT", Lbflag, 0, 0, 0, 0} {"COMMON", Lbflag, 0, 0, 0, 0} {"COMPARE", Lfunct, 2, 3, Fnull, 0} {"CONTINUE", Lbos, 0, 0, 0, 0} {"CONVERT", Lbfunc, 3, 3, 0, 0} {"COS", Lfunct, 1, 1, Ftrig, 0} {"COSH", Lfunct, 1, 1, Ftrig, 0} {"COUNT", Lfunct, 2, 2, Fovlap, 0} {"COUNTS", Lfunct, 2, 2, 0, 0} {"CREATE", Lbos, 0, 0, 0, 0} {"createCertificate", Lfunct, 8, 8, 0, 0} {"createCertRequest", Lfunct, 9, 9, 0, 0} {"createRequest", Lfunct, 3, 3, 0, LVA_3} {"createSecureRequest", Lfunct, 4, 4, 0, LVA_3} {"createSecurityContext", Lfunct, 2, 2, 0, LVA_1} {"CRT", Lbos, 0, 0, 0, 0} {"DATA", Lbos, 0, 0, 0, 0} {"DATE", Lfunct, 0, 0, 0, 0} {"DCOUNT", Lfunct, 2, 2, Fovlap, 0} {"DEACTIVATEKEY", Lbos, 0, 0, 0, 0} {"DEBUG", Lbos, 0, 0, 0, 0} {"DECLARE", Lbos, 0, 0, 0, 0} {"DEFFUN", Lbos, 0, 0, 0, 0} {"DEL", Lbos, 0, 0, 0, 0} {"DELETE", Lbfunc, 2, 4, 0, 0}
44 Default words in code assist
{"DELETELIST", Lbos, 0, 0, 0, 0} {"DELETEU", Lbos, 0, 0, 0, 0} {"DESCRINFO", Lfunct, 2, 2, 0, 0} {"DIAGNOSTICS", Lfunct, 1, 2, 0, 0} {"DIGEST", Lfunct, 4, 4, 0, LVA_4} {"DIM", Lbos, 0, 0, 0, 0} {"DIMENSION", Lbos, 0, 0, 0, 0} {"DISABLEDEC", Lbos, 0, 0, 0, 0} {"DISPLAY", Lbos, 0, 0, 0, 0} {"DIV", Lfunct, 2, 2, 0, 0} {"DIVS", Lfunct, 2, 2, 0, 0} {"DO", Lflag, 0, 0, 0, 0} {"DOWNCASE", Lfunct, 1, 1, 0, 0} {"DQUOTE", Lfunct, 1, 1, 0, 0} {"DTX", Lfunct, 1, 2, 0, 0} {"EBCDIC", Lfunct, 1, 1, 0, 0} {"ECHO", Lbos, 0, 0, 0, 0} {"ELSE", Lelse, 0, 0, 0, 0} {"ENABLEDEC", Lbos, 0, 0, 0, 0} {"ENCODE", Lfunct, 6, 6, 0, LVA_5} {"ENCRYPT", Lfunct, 11, 11, 0, LVA_10} {"END", Lend, 0, 0, 0, 0} {"ENTER", Lbos, 0, 0, 0, 0} {"EOF", Lfunct, 0, 0, 0, 0} {"EQ", 0, 0, 0, 0, 0} {"EQS", Lfunct, 2, 2, 0, 0} {"EQU", Lbos, 0, 0, 0, 0} {"EQUATE", Lbos, 0, 0, 0, 0} {"EREPLACE", Lfunct, 3, 5, 0, 0} {"ERRMSG", Lbos, 0, 0, 0, 0} {"ERROR", Lerror, 0, 0, 0, 0} {"EXCHANGE", Lfunct, 0, 0, 0, 0} {"EXEC", Lbos, 0, 0, 0, 0} {"EXECUTE", Lbos, 0, 0, 0, 0} {"EXIT", Lbos, 0, 0, 0, 0} {"EXP", Lfunct, 1, 1, 0, 0} {"EXTRACT", Lfunct, 2, 4, 0, 0} {"FADD", Lfunct, 2, 2, 0, 0}
45 Chapter 2: Basic Developer Toolkit
{"FDIV", Lfunct, 2, 2, 0, 0} {"FFIX", Lfunct, 1, 1, 0, 0} {"FFLT", Lfunct, 1, 1, 0, 0} {"FIELD", Lfunct, 3, 4, Fone, 0} {"FIELDS", Lfunct, 3, 4, Fone, 0} {"FIELDSTORE", Lfunct, 5, 5, 0, 0} {"FILEINFO", Lfunct, 2, 2, 0, 0} {"FILELOCK", Lbos, 0, 0, 0, 0} {"FILEUNLOCK", Lbos, 0, 0, 0, 0} {"FIND", Lbos, 0, 0, 0, 0} {"FINDSTR", Lbos, 0, 0, 0, 0} {"FIX", Lfunct, 1, 3, 0, 0} {"FLUSH", Lbos, 0, 0, 0, 0} {"FMT", Lfunct, 2, 2, 0, 0} {"FMTDP", Lfunct, 2, 3, Fnull, 0} {"FMTS", Lfunct, 2, 2, 0, 0} {"FMTSDP", Lfunct, 2, 3, Fnull, 0} {"FMUL", Lfunct, 2, 2, 0, 0} {"FOLD", Lfunct, 2, 2, 0, 0} {"FOLDDP", Lfunct, 2, 3, 0, 0} {"FOOTING", Lbos, 0, 0, 0, 0} {"FOR", Lbos, 0, 0, 0, 0} {"FORMLIST", Lbos, 0, 0, 0, 0} {"FROM", Lflag, 0, 0, 0, 0} {"FSUB", Lfunct, 2, 2, 0, 0} {"FUNCTION", Lbos, 0, 0, 0, 0} {"GARBAGECOLLECT", Lbos, 0, 0, 0, 0} {"GCI", Lflag, 0, 0, 0, 0} {"GE", 0, 0, 0, 0, 0} {"generateKey", Lfunct, 8, 8, 0, LVA_1|LVA_2} {"GES", Lfunct, 2, 2, 0, 0} {"GET", Lget, 0, 0, 0, 0} {"getCipherSuite", Lfunct, 2, 2, 0, LVA_2} {"GETCONVERTTERMEURO", Lfunct, 0, 0, 0, 0} {"GETDIAGNOSTICS", Lfunct, 0, 0, 0, 0} {"getHTTPDefault", Lfunct, 2, 2, 0, LVA_2} {"GETLIST", Lbos, 0, 0, 0, 0} {"GETLOCALE", Lfunct, 1, 1, 0, 0}
46 Default words in code assist
{"GETREM", Lfunct, 1, 1, 0, 0} {"getResponseHeader", Lfunct, 3, 3, 0, LVA_3} {"getSocketErrorMessage",Lfunct, 2, 2, 0, LVA_2} {"getSocketInformation",Lfunct, 3, 3, 0, LVA_3} {"getSocketMap", Lfunct, 2, 2, 0, LVA_2} {"getSocketOptions", Lfunct, 2, 2, 0, LVA_2} {"GETSQLNULL", Lfunct, 0, 0, 0, 0} {"GETSYSTEMEURO", Lfunct, 0, 0, 0, 0} {"GETTERMEURO", Lfunct, 0, 0, 0, 0} {"GETX", Lbos, 0, 0, 0, 0} {"GO", Lbflag, 0, 0, 0, 0} {"GOSUB", Lbflag, 0, 0, 0, 0} {"GOTO", Lbflag, 0, 0, 0, 0} {"GROUP", Lfunct, 3, 4, Fone, 0} {"GROUPSTORE", Lbos, 0, 0, 0, 0} {"GT", 0, 0, 0, 0, 0} {"GTS", Lfunct, 2, 2, 0, 0} {"HEADING", Lbos, 0, 0, 0, 0} {"HEADINGE", Lbos, 0, 0, 0, 0} {"HEADINGN", Lbos, 0, 0, 0, 0} {"HUSH", Lbos, 0, 0, 0, 0} {"ICHECK", Lfunct, 2, 4, Fnego, 0} {"ICONV", Lfunct, 2, 2, 0, 0} {"ICONVS", Lfunct, 2, 2, 0, 0} {"IF", 0, 0, 0, 0, 0} {"IFS", Lfunct, 3, 3, 0, 0} {"ILPROMPT", Lfunct, 1, 1, 0, 0} {"IN", Lflag, 0, 0, 0, 0} {"INDEX", Lfunct, 3, 3, Fovlap, 0} {"INDEXS", Lfunct, 3, 3, 0, 0} {"INDICES", Lfunct, 1, 2, Fnull, 0} {"initSecureServerSocket",Lfunct, 5, 5, 0, LVA_4} {"initServerSocket", Lfunct, 4, 4, 0, LVA_4} {"INMAT", Lfunct, 0, 0, 0, 0} {"INPUT", Lbflag, 0, 0, 0, 0} {"INPUTCLEAR", Lbos, 0, 0, 0, 0} {"INPUTDISP", Lbos, 0, 0, 0, 0} {"INPUTDP", Lbflag, 0, 0, 0, 0}
47 Chapter 2: Basic Developer Toolkit
{"INPUTERR", Lbos, 0, 0, 0, 0} {"INPUTIF", Lbos, 0, 0, 0, 0} {"INPUTNULL", Lbos, 0, 0, 0, 0} {"INPUTTRAP", Lbos, 0, 0, 0, 0} {"INS", Lbos, 0, 0, 0, 0} {"INSERT", Lfunct, 3, 5, Fsemi, 0} {"INT", Lfunct, 1, 1, 0, 0} {"ISNULL", Lfunct, 1, 1, 0, 0} {"ISNULLS", Lfunct, 1, 1, 0, 0} {"ISOLATION", Lflag, 0, 0, 0, 0} {"ITYPE", Lfunct, 1, 1, 0, 0} {"KEY", Lflag, 0, 0, 0, 0} {"KEYEDIT", Lbos, 0, 0, 0, 0} {"KEYEXIT", Lbos, 0, 0, 0, 0} {"KEYIN", Lfunct, 0, 0, 0, 0} {"KEYTRAP", Lbos, 0, 0, 0, 0} {"LE", 0, 0, 0, 0, 0} {"LEFT", Lfunct, 2, 2, 0, 0} {"LEN", Lfunct, 1, 1, 0, 0} {"LENDP", Lfunct, 1, 2, Fnull, 0} {"LENS", Lfunct, 1, 1, 0, 0} {"LENSDP", Lfunct, 1, 2, Fnull, 0} {"LES", Lfunct, 2, 2, 0, 0} {"LET", Lbos, 0, 0, 0, 0} {"LEVEL", Lflag, 0, 0, 0, 0} {"LIT", Lflag, 0, 0, 0, 0} {"LITERALLY", Lflag, 0, 0, 0, 0} {"LN", Lfunct, 1, 1, 0, 0} {"loadSecurityContext", Lfunct, 3, 3, 0, LVA_1} {"LOCALEINFO", Lfunct, 1, 1, 0, 0} {"LOCATE", Lloc, 0, 0, 0, 0} {"LOCK", Lbos, 0, 0, 0, 0} {"LOCKED", Llock, 0, 0, 0, 0} {"LOOP", Lbos, 0, 0, 0, 0} {"LOWER", Lfunct, 1, 1, 0, 0} {"LPTR", Lflag, 0, 0, 0, 0} {"LT", 0, 0, 0, 0, 0} {"LTS", Lfunct, 2, 2, 0, 0}
48 Default words in code assist
{"MAT", Lbflag, 0, 0, 0, 0} {"MATBUILD", Lbos, 0, 0, 0, 0} {"MATCH", 0, 0, 0, 0, 0} {"MATCHES", 0, 0, 0, 0, 0} {"MATCHFIELD", Lfunct, 3, 3, 0, 0} {"MATPARSE", Lbos, 0, 0, 0, 0} {"MATREAD", Lbos, 0, 0, 0, 0} {"MATREADL", Lbos, 0, 0, 0, 0} {"MATREADU", Lbos, 0, 0, 0, 0} {"MATWRITE", Lbos, 0, 0, 0, 0} {"MATWRITEU", Lbos, 0, 0, 0, 0} {"MAXIMUM", Lfunct, 1, 1, 0, 0} {"MESSAGE", Lbos, 0, 0, 0, 0} {"MINIMUM", Lfunct, 1, 1, 0, 0} {"MOD", Lfunct, 2, 2, 0, 0} {"MODS", Lfunct, 2, 2, 0, 0} {"MTU", Lflag, 0, 0, 0, 0} {"MULS", Lfunct, 2, 2, 0, 0} {"NAP", Lbos, 0, 0, 0, 0} {"NE", 0, 0, 0, 0, 0} {"NEG", Lfunct, 1, 1, 0, 0} {"NEGS", Lfunct, 1, 1, 0, 0} {"NES", Lfunct, 2, 2, 0, 0} {"NEXT", Lnext, 0, 0, 0, 0} {"NO.ISOLATION", Lflag, 0, 0, 0, 0} {"NOBUF", Lbos, 0, 0, 0, 0} {"NOT", Lfunct, 1, 1, 0, 0} {"NOTS", Lfunct, 1, 1, 0, 0} {"NULL", Lbos, 0, 0, 0, 0} {"NUM", Lfunct, 1, 1, 0, 0} {"NUMS", Lfunct, 1, 1, 0, 0} {"OCONV", Lfunct, 2, 2, 0, 0} {"OCONVS", Lfunct, 2, 2, 0, 0} {"OFF", Lflag, 0, 0, 0, 0} {"ON", Lbflag, 0, 0, 0, 0} {"OPEN", Lbos, 0, 0, 0, 0} {"OPENCHECK", Lbos, 0, 0, 0, 0} {"OPENDEV", Lbos, 0, 0, 0, 0}
49 Chapter 2: Basic Developer Toolkit
{"OPENPATH", Lbos, 0, 0, 0, 0} {"openSecureSocket", Lfunct, 6, 6, 0, LVA_5} {"OPENSEQ", Lbos, 0, 0, 0, 0} {"openSocket", Lfunct, 5, 5, 0, LVA_5} {"OpenXMLData", Lfunct, 3, 3, 0, LVA_3} {"OR", 0, 0, 0, 0, 0} {"ORS", Lfunct, 2, 2, 0, 0} {"OUT", Lflag, 0, 0, 0, 0} {"PAGE", Lbos, 0, 0, 0, 0} {"PASSLIST", Lflag, 0, 0, 0, 0} {"PCDRIVER", Lbos, 0, 0, 0, 0} {"PERFORM", Lexec, 0, 0, 0, 0} {"PRECISION", Lbos, 0, 0, 0, 0} {"PrepareXML", Lfunct, 2, 2, 0, LVA_2} {"PRINT", Lbos, 0, 0, 0, 0} {"PRINTER", Lbos, 0, 0, 0, 0} {"PRINTERIO", Lbos, 0, 0, 0, 0} {"PRINTERR", Lprntr, 0, 0, 0, 0} {"PROCREAD", Lbos, 0, 0, 0, 0} {"PROCWRITE", Lbos, 0, 0, 0, 0} {"PROG", Lbos, 0, 0, 0, 0} {"PROGRAM", Lbos, 0, 0, 0, 0} {"PROMPT", Lbos, 0, 0, 0, 0} {"protocolLogging", Lfunct, 3, 3, 0, 0} {"PWR", Lfunct, 2, 2, 0, 0} {"QUOTE", Lfunct, 1, 1, 0, 0} {"RAISE", Lfunct, 1, 1, 0, 0} {"RANDOMIZE", Lbos, 0, 0, 0, 0} {"READ", Lbos, 0, 0, 0, 0} {"READ.COMMITTED", Lflag, 0, 0, 0, 0} {"READ.UNCOMMITTED", Lflag, 0, 0, 0, 0} {"READBLK", Lbos, 0, 0, 0, 0} {"READL", Lbos, 0, 0, 0, 0} {"READLIST", Lbos, 0, 0, 0, 0} {"READNEXT", Lbos, 0, 0, 0, 0} {"READSEQ", Lbos, 0, 0, 0, 0} {"readSocket", Lfunct, 6, 6, 0, LVA_2|LVA_6} {"READT", Lbos, 0, 0, 0, 0}
50 Default words in code assist
{"READU", Lbos, 0, 0, 0, 0} {"READV", Lbos, 0, 0, 0, 0} {"READVL", Lbos, 0, 0, 0, 0} {"READVU", Lbos, 0, 0, 0, 0} {"ReadXMLData", Lfunct, 2, 2, 0, LVA_2} {"REAL", Lfunct, 1, 1, 0, 0} {"RECIO", Lfunct, 2, 4, 0, 0} {"RECORDLOCKED", Lfunct, 2, 2, 0, 0} {"RECORDLOCKL", Lbos, 0, 0, 0, 0} {"RECORDLOCKU", Lbos, 0, 0, 0, 0} {"RELEASE", Lbos, 0, 0, 0, 0} {"ReleaseXML", Lfunct, 1, 1, 0, 0} {"REM", Lfunct, 2, 2, 0, 0} {"REMOVE", Lbfunc, 2, 2, 0, 0} {"REPEAT", Lloop, 0, 0, 0, 0} {"REPEATABLE.READ", Lflag, 0, 0, 0, 0} {"REPLACE", Lfunct, 3, 5, Fsemi, 0} {"RESET", Lflag, 0, 0, 0, 0} {"RETURN", Lsub, 0, 0, 0, 0} {"RETURNING", Lflag, 0, 0, 0, 0} {"REUSE", Lfunct, 1, 1, 0, 0} {"REVREMOVE", Lbos, 0, 0, 0, 0} {"REWIND", Lbos, 0, 0, 0, 0} {"RIGHT", Lfunct, 2, 2, 0, 0} {"RND", Lfunct, 1, 1, 0, 0} {"ROLLBACK", Lbos, 0, 0, 0, 0} {"RPC.CALL", Lfunct, 0, 0, 0, 0} {"RPC.CONNECT", Lfunct, 2, 2, 0, 0} {"RPC.DISCONNECT", Lfunct, 1, 1, 0, 0} {"RQM", Lbos, 0, 0, 0, 0} {"RTNLIST", Lflag, 0, 0, 0, 0} {"SADD", Lfunct, 2, 2, 0, 0} {"saveSecurityContext", Lfunct, 3, 3, 0, 0} {"SCMP", Lfunct, 2, 2, 0, 0} {"SDIV", Lfunct, 2, 3, Fnego, 0} {"SEEK", Lseek, 0, 0, 0, 0} {"SELECT", Lbflag, 0, 0, 0, 0} {"SELECTE", Lbos, 0, 0, 0, 0}
51 Chapter 2: Basic Developer Toolkit
{"SELECTINDEX", Lbos, 0, 0, 0, 0} {"SELECTINFO", Lfunct, 2, 2, 0, 0} {"SELECTN", Lbos, 0, 0, 0, 0} {"SELECTV", Lbos, 0, 0, 0, 0} {"SEND", Lbos, 0, 0, 0, 0} {"SENTENCE", Lfunct, 0, 0, 0, 0} {"SEQ", Lfunct, 1, 1, Fseq, 0} {"SEQS", Lfunct, 1, 1, 0, 0} {"SEQSUM", Lfunct, 1, 1, 0, 0} {"SERIALIZABLE", Lflag, 0, 0, 0, 0} {"SET", Lbos, 0, 0, 0, 0} {"setAuthenticationDepth",Lfunct, 3, 3, 0, 0} {"setCipherSuite", Lfunct, 2, 2, 0, 0} {"setClientAuthentication", Lfunct, 2, 2, 0, 0} {"SETCONVERTTERMEURO", Lfunct, 1, 1, 0, 0} {"SETDIAGNOSTICS", Lfunct, 1, 3, Fnull, 0} {"setHTTPDefault", Lfunct, 2, 2, 0, 0} {"SETLOCALE", Lfunct, 2, 2, 0, 0} {"setPrivateKey", Lfunct, 6, 6, 0, 0} {"setRandomSeed", Lfunct, 4, 4, 0, 0} {"SETREM", Lbos, 0, 0, 0, 0} {"setRequestHeader", Lfunct, 3, 3, 0, 0} {"setSocketMap", Lfunct, 1, 1, 0, 0} {"setSocketOptions", Lfunct, 2, 2, 0, 0} {"SETSYSTEMEURO", Lfunct, 1, 1, 0, 0} {"SETTERMEURO", Lfunct, 1, 1, 0, 0} {"SETTING", Lflag, 0, 0, 0, 0} {"showSecurityContext", Lfunct, 2, 2, 0, 0} {"SIGNATURE", Lfunct, 10, 10, 0, LVA_9} {"SIN", Lfunct, 1, 1, Ftrig, 0} {"SINH", Lfunct, 1, 1, Ftrig, 0} {"SLEEP", Lbos, 0, 0, 0, 0} {"SMUL", Lfunct, 2, 2, 0, 0} {"SOAPCreateRequest", Lfunct, 3, 3, 0, LVA_3} {"SOAPCreateSecureRequest", Lfunct, 4, 4, 0, LVA_4} {"SOAPGetDefault", Lfunct, 2, 2, 0, LVA_2} {"SOAPGetFault", Lfunct, 2, 2, 0, LVA_2} {"SOAPGetResponseHeader",Lfunct, 3, 3, 0, LVA_3}
52 Default words in code assist
{"SOAPRequestWrite", Lfunct, 3, 3, 0, LVA_2} {"SOAPSetDefault", Lfunct, 2, 2, 0, 0} {"SOAPSetParameters", Lfunct, 4, 4, 0, 0} {"SOAPSetRequestBody", Lfunct, 2, 2, 0, 0} {"SOAPSetRequestContent",Lfunct, 3, 3, 0, 0} {"SOAPSetRequestHeader",Lfunct, 2, 2, 0, 0} {"SOAPSubmitRequest", Lfunct, 5, 5, 0, LVA_3|LVA_4|LVA_5} {"SOUNDEX", Lfunct, 1, 1, 0, 0} {"SPACE", Lfunct, 1, 1, 0, 0} {"SPACES", Lfunct, 1, 1, 0, 0} {"SPLICE", Lfunct, 3, 3, 0, 0} {"SQLALLOCCONNECT", Lfunct, 2, 2, 0, LVA_2} {"SQLALLOCENV", Lfunct, 1, 1, 0, LVA_1} {"SQLALLOCSTMT", Lfunct, 2, 2, 0, LVA_2} {"SQLBINDCOL", Lfunct, 4, 4, 0, LVA_4} {"SQLBINDPARAMETER", Lfunct, 7, 8, Fone, LVA_7} {"SQLCANCEL", Lfunct, 1, 1, 0, 0} {"SQLCMP", Lfunct, 3, 3, Fnull, 0} {"SQLCOLATTRIBUTES", Lfunct, 5, 5, 0, LVA_4|LVA_5} {"SQLCOLUMNS", Lfunct, 5, 5, 0, 0} {"SQLCONNECT", Lfunct, 4, 4, 0, 0} {"SQLDESCRIBECOL", Lfunct, 7, 7, 0, LVA_3|LVA_4|LVA_5|LVA_6|LVA_7} {"SQLDISCONNECT", Lfunct, 1, 1, 0, 0} {"SQLERROR", Lfunct, 6, 6, 0, LVA_4|LVA_5|LVA_6} {"SQLEXECDIRECT", Lfunct, 2, 2, 0, 0} {"SQLEXECUTE", Lfunct, 1, 1, 0, 0} {"SQLFETCH", Lfunct, 1, 1, 0, 0} {"SQLFREECONNECT", Lfunct, 1, 1, 0, 0} {"SQLFREEENV", Lfunct, 1, 1, 0, 0} {"SQLFREESTMT", Lfunct, 2, 2, 0, 0} {"SQLGETCURSORNAME", Lfunct, 2, 2, 0, LVA_2} {"SQLGETINFO", Lfunct, 3, 3, 0, LVA_3} {"SQLGETTYPEINFO", Lfunct, 2, 2, 0, 0} {"SQLNUMPARAMS", Lfunct, 2, 2, 0, LVA_2} {"SQLNUMRESULTCOLS", Lfunct, 2, 2, 0, LVA_2} {"SQLPARAMOPTIONS", Lfunct, 3, 3, 0, LVA_3} {"SQLPREPARE", Lfunct, 2, 2, 0, 0} {"SQLROWCOUNT", Lfunct, 2, 2, 0, LVA_2}
53 Chapter 2: Basic Developer Toolkit
{"SQLSETCONNECTOPTION", Lfunct, 3, 3, 0, 0} {"SQLSETCURSORNAME", Lfunct, 2, 2, 0, 0} {"SQLSETPARAM", Lfunct, 7, 8, Fone, LVA_7} {"SQLSPECIALCOLUMNS", Lfunct, 7, 7, 0, 0} {"SQLSTATISTICS", Lfunct, 6, 6, 0, 0} {"SQLTABLES", Lfunct, 5, 5, 0, 0} {"SQLTRANSACT", Lfunct, 3, 3, 0, 0} {"SQRT", Lfunct, 1, 1, 0, 0} {"SQUOTE", Lfunct, 1, 1, 0, 0} {"SSELECT", Lbos, 0, 0, 0, 0} {"SSELECTN", Lbos, 0, 0, 0, 0} {"SSELECTV", Lbos, 0, 0, 0, 0} {"SSUB", Lfunct, 2, 2, 0, 0} {"START", Lflag, 0, 0, 0, 0} {"STATUS", Lstat, 0, 0, 0, 0} {"STEP", Lflag, 0, 0, 0, 0} {"STOP", Lbos, 0, 0, 0, 0} {"STOPE", Lbos, 0, 0, 0, 0} {"STOPM", Lbos, 0, 0, 0, 0} {"STORAGE", Lbos, 0, 0, 0, 0} {"STR", Lfunct, 2, 2, 0, 0} {"STRS", Lfunct, 2, 2, 0, 0} {"SUB", Lsub, 0, 0, 0, 0} {"submitRequest", Lfunct, 6, 6, 0, LVA_4|LVA_5|LVA_6} {"SUBR", Lfunct, 0, 0, 0, 0} {"SUBROUTINE", Lsub, 0, 0, 0, 0} {"SUBS", Lfunct, 2, 2, 0, 0} {"SUBSTRINGS", Lfunct, 3, 3, 0, 0} {"SUM", Lfunct, 1, 1, 0, 0} {"SUMMATION", Lfunct, 1, 1, 0, 0} {"SWAP", Lbos, 2, 2, 0, 0} {"SYSTEM", Lfunct, 1, 2, 0, 0} {"TABSTOP", Lbos, 0, 0, 0, 0} {"TAN", Lfunct, 1, 1, Ftrig, 0} {"TANH", Lfunct, 1, 1, Ftrig, 0} {"TERMINFO", Lfunct, 1, 1, 0, 0} {"TESTDIAGNOSTICS", Lfunct, 0, 0, 0, 0} {"THEN", Lthen, 0, 0, 0, 0}
54 Default words in code assist
{"TIME", Lfunct, 0, 0, 0, 0} {"TIMEDATE", Lfunct, 0, 0, 0, 0} {"TIMEOUT", Lbos, 0, 0, 0, 0} {"TO", Lflag, 0, 0, 0, 0} {"TPARM", Lfunct, 1, 9, 0, 0} {"TPRINT", Lbos, 0, 0, 0, 0} {"TRANS", Lfunct, 4, 4, 0, 0} {"TRANSACTION", Lbflag, 0, 0, 0, 0} {"TRIM", Lfunct, 1, 3, 0, 0} {"TRIMB", Lfunct, 1, 1, 0, 0} {"TRIMBS", Lfunct, 1, 1, 0, 0} {"TRIMF", Lfunct, 1, 1, 0, 0} {"TRIMFS", Lfunct, 1, 1, 0, 0} {"TRIMS", Lfunct, 1, 1, 0, 0} {"TTYCTL", Lbos, 0, 0, 0, 0} {"TTYGET", Lbos, 0, 0, 0, 0} {"TTYSET", Lbos, 0, 0, 0, 0} {"UNASSIGNED", Lfunct, 1, 1, 0, 0} {"UNICHAR", Lfunct, 1, 1, 0, 0} {"UNICHARS", Lfunct, 1, 1, 0, 0} {"UNISEQ", Lfunct, 1, 1, 0, 0} {"UNISEQS", Lfunct, 1, 1, 0, 0} {"UNIT", Lfunct, 0, 0, 0, 0} {"UNLOCK", Lbos, 0, 0, 0, 0} {"UNTIL", Lloop, 0, 0, 0, 0} {"UPCASE", Lfunct, 1, 1, 0, 0} {"UPRINT", Lbos, 0, 0, 0, 0} {"USING", Lflag, 0, 0, 0, 0} {"WAITING", Lflag, 0, 0, 0, 0} {"WEOF", Lbos, 0, 0, 0, 0} {"WEOFSEQ", Lbos, 0, 0, 0, 0} {"WHILE", Lloop, 0, 0, 0, 0} {"WORDSIZE", Lbos, 0, 0, 0, 0} {"WORK", Lflag, 0, 0, 0, 0} {"WRITE", Lbos, 0, 0, 0, 0} {"WRITEBLK", Lbos, 0, 0, 0, 0} {"WRITELIST", Lbos, 0, 0, 0, 0} {"WRITESEQ", Lbos, 0, 0, 0, 0}
55 Chapter 2: Basic Developer Toolkit
{"WRITESEQF", Lbos, 0, 0, 0, 0} {"writeSocket", Lfunct, 5, 5, 0, LVA_5} {"WRITET", Lbos, 0, 0, 0, 0} {"WRITEU", Lbos, 0, 0, 0, 0} {"WRITEV", Lbos, 0, 0, 0, 0} {"WRITEVU", Lbos, 0, 0, 0, 0} {"XDOMAddChild", Lfunct, 5, 5, 0, 0} {"XDOMAppend", Lfunct, 5, 5, 0, 0} {"XDOMClone", Lfunct, 3, 3, 0, LVA_2} {"XDOMClose", Lfunct, 1, 1, 0, 0} {"XDOMCreateNode", Lfunct, 5, 5, 0, LVA_5} {"XDOMCreateRoot", Lfunct, 1, 2, 0, LVA_1} {"XDOMEvaluate", Lfunct, 4, 4, 0, LVA_4} {"XDOMGetAttribute", Lfunct, 3, 3, 0, LVA_3} {"XDOMGetNodeName", Lfunct, 2, 2, 0, LVA_2} {"XDOMGetNodeType", Lfunct, 2, 2, 0, LVA_2} {"XDOMGetNodeValue", Lfunct, 2, 2, 0, LVA_2} {"XDOMGetOwnerDocument",Lfunct, 2, 2, 0, LVA_2} {"XDOMGetUserData", Lfunct, 2, 2, 0, LVA_2} {"XDOMImportNode", Lfunct, 4, 4, 0, LVA_4} {"XDOMInsert", Lfunct, 5, 5, 0, 0} {"XDOMLocate", Lfunct, 4, 4, 0, LVA_4} {"XDOMLocateNode", Lfunct, 5, 5, 0, LVA_5} {"XDOMOpen", Lfunct, 3, 3, 0, LVA_3} {"XDOMRemove", Lfunct, 5, 5, 0, LVA_5} {"XDOMReplace", Lfunct, 5, 5, 0, 0} {"XDOMSetNodeValue", Lfunct, 2, 2, 0, 0} {"XDOMSetUserData", Lfunct, 2, 2, 0, 0} {"XDOMTransform", Lfunct, 4, 5, 0, LVA_4} {"XDOMValidate", Lfunct, 4, 5, 0, 0} {"XDOMValidateDom", Lfunct, 3, 4, 0, 0} {"XDOMWrite", Lfunct, 3, 4, 0, LVA_2} {"XLATE", Lfunct, 4, 4, 0, 0} {"XMAPAppendRec", Lfunct, 3, 3, 0, 0} {"XMAPClose", Lfunct, 1, 1, 0, 0} {"XMAPCreate", Lfunct, 3, 3, 0, LVA_3} {"XMAPGetInfo", Lfunct, 2, 2, 0, LVA_2} {"XMAPOpen", Lfunct, 5, 5, 0, LVA_5}
56 Basic Developer Toolkit and Rocket Aldon LM(e)
{"XMAPReadNext", Lfunct, 3, 3, 0, LVA_3} {"XMAPSetOption", Lfunct, 3, 3, 0, 0} {"XMAPToXMLDoc", Lfunct, 3, 4, 0, LVA_2} {"XMLERROR", Lfunct, 1, 1, 0, LVA_1} {"XMLExecute", Lfunct, 4, 4, 0, LVA_3|LVA_4} {"XMLGetError", Lfunct, 2, 2, 0, LVA_1|LVA_2} {"XMLGetOptions", Lfunct, 1, 2, 0, LVA_1} {"XMLGetOptionValue", Lfunct, 2, 2, 0, LVA_1} {"XMLSetOptions", Lfunct, 1, 1, 0, 0, "Since UV 10.3"} {"XTD", Lfunct, 1, 1, 0, 0} Basic Developer Toolkit and Rocket Aldon LM(e)
You can integrate BDT with Aldon Lifecycle Manager for Rocket U2 (LMU2) to manage your data and applications through all stages of development.
Note: A supplementary video is available to help describe the Aldon LM(e) integration with BDT. To watch the video, click here.
LMU2 uses Rocket Aldon Lifecycle Manager (Enterprise Edition), referred to in this documentation as LM(e), to manage U2 programs (PROGs) and dictionary records (DICT). Currently, managing data items (DATA) is not supported in BDT, and should be handled in command mode, not BDT. LM(e) provides source control features, such as check in and check out, and manages items in the following ways: ▪ Items move through development lifecycle stages to completion. ▪ User authorities can be set at each stage. ▪ Items can be deployed at each stage for testing or production. ▪ Items are tracked through each stage and each deployment, resulting in a clear audit trail. To learn more about LM(e), visit https://docs.rocketsoftware.com. Navigate to Rocket Aldon → Lifecycle Manager for Rocket U2. You need a special license to access the LM(e) functionality using BDT. Contact Rocket U2 technical support at [email protected], or Rocket Business Connect at https:// rbc.rocketsoftware.com.
Configuring BDT to use LMU2 commands
If you use BDT with LMU2, you must define and export the LM(e) command line client path in your shell script. Defining and exporting the path enables the unirpc daemon to use the command line client, which it must do to interact with the LM(e) server. In UniData, you must edit the $UDTBIN/ startud script; in UniVerse, you must edit the uv.rc script. 1. In UniData, perform the following steps: a. Open the $UDTBIN/startud file, and find the following lines: # set path to include. # Added mod for Aldon
57 Chapter 2: Basic Developer Toolkit
# b. Below those lines, add the following lines: PATH=.:/opt/aldon/aldonlmc/current/bin/:$PATH export PATH 2. In UniVerse, perform the following steps: a. Enter the following command to find the uv.rc file: cat /.uvhome | xargs -I {} cat {}/.uvrcloc) b. Open the uv.rc file, and find the following section: # Start the RPC daemon c. In that section, below the then statement, add the following lines: PATH=/opt/aldon/aldonlmc/current/bin/:$PATH export PATH For example:
# Start the RPC daemon if [ -r /.unishared ] then PATH=/opt/aldon/aldonlmc/current/bin:$PATH export $PATH
Enabling the LM(e) plugin
To use the LM(e) menu options in BDT, you must first enable the plugin in BDT. 1. From the BDT menu bar, select Window → Preferences. 2. Expand the UniData/UniVerse node, and select LM(e). 3. Select the Enable LM(e) plugin check box. 4. Click Apply, then click OK.
Signing on to and off of LM(e)
After you sign on to LM(e) from an account in the U2 Resource view, you can check items in and out, mark items for deletion, and view LM(e) status.
Prerequisites To sign on to LM(e), connect to a U2 server. If you have not made one yet, see Creating server definitions, on page 16.
About this task When an account is connected with LM(e), a yellow indicator is added to the account icon, as displayed next to BH.BP and BP in the following example:
58 Adding object items
Procedure
1. Right-click the account to work with, and select LM(e) → Signon. 2. To sign on to LM(e), perform the following steps: a. Type your User ID and Password for the LM(e) account. b. Select the Remember me check box to remember this user ID and password. c. Select the Use Server credentials check box to use the default LM(e) connection credentials. d. Click Signon. Your account is enabled for LM(e). A small yellow rectangle appears on each account that is enabled for LM(e). 3. To sign off of LM(e), right-click the account, and select Signoff.
Alternatively, you can sign on and off of the client using the LME.SIGNON and LME.SIGNOFF commands, respectively. If you sign on this way, BDT does not immediately recognize that you have changed your status. You can check the LM(e) status to verify the state of your connection, as described in Displaying LM(e) status, on page 69.
Next step ▪ Adding object items, on page 59 ▪ Checking out object items, on page 62 ▪ Marking object items for deletion, on page 66 ▪ Displaying LM(e) status, on page 69
Adding object items
Adding object items registers them in the development environment of an LM(e) release.
Prerequisites ▪ Signing on to and off of LM(e), on page 58 To add an object item, create a BASIC program locally. For more information, see Creating programs, on page 36
59 Chapter 2: Basic Developer Toolkit
About this task After you add object items, LM(e) sees them and considers them to be checked out, but they are not copied to the LM(e) server until you check them in. The first time that you check in the object items, they are copied to the LM(e) server and promoted to the first environment in the release.
Procedure
1. From the U2 Resource view, perform one of the following steps: ▪ Right-click the object item that you want to add to LM(e), and select LM(e) → Add. ▪ Right-click the directory type folder and selecting LM(e) → Add. 2. Optional: In the Add U2 File dialog box, complete the following fields: ▪ In the Enter task reference field, type the task reference number associated with this file if there is one.
Note: Task references and associated comments are not required, but can be useful when managing items and might be required at your site.
▪ When you enter a task reference number that is associated with multiple files, the Related files table will appear with the other files that use the same task reference number, as displayed in the following example.
3. Optional: In the Enter comments field, enter any relevant comments. 4. Click OK. A white check mark is displayed on each object item that is added to LM(e).
Next step After you add items, you can check them in or out, mark them for deletion, or see their status. See the following sections for more information: ▪ Checking in object items, on page 61 ▪ Checking in object items by task, on page 61 ▪ Marking object items for deletion, on page 66 ▪ Displaying LM(e) status, on page 69
60 Checking in object items
Checking in object items
Check in object items to save edits to LM(e).
Prerequisites You must add object items to LM(e) before you can check them in. For more information, see Adding object items, on page 59.
About this task You can check in only your own local items. Object items that need to be checking in are displayed with a white check mark indicator, as shown beside PROGRAM2 in the following example:
You can also verify the status by using the LM(e) Status window, as described in Displaying LM(e) status, on page 69.
Procedure
1. Right-click the object item to check in, and select LM(e) → Checkin. 2. Optional: In the Checkin U2 File dialog box, enter a comment. 3. Optional: Click OK. The item is checked in and updated on the U2 server, and the check mark indicator is removed.
Next step ▪ Checking in object items by task, on page 61 ▪ Checking out object items, on page 62 ▪ Getting the latest version of object items, on page 66 ▪ Displaying LM(e) status, on page 69
Checking in object items by task
In addition to checking in individual items, you can check in items by checking in the task they are associated with.
Prerequisites You must add object items to LM(e) before you can check them in. For more information, see Adding object items, on page 59.
61 Chapter 2: Basic Developer Toolkit
About this task You can check in only your own local items. Object items that need to be checking in are displayed with a white check mark indicator, as shown beside PROGRAM2 in the following example:
You can also verify the status by using the LM(e) Status window, as described in Displaying LM(e) status, on page 69.
Procedure
1. Right-click the object item or directory folder to check in, and select LM(e) → CheckinTask. Alternatively, click the CheckinTask icon from the toolbar. 2. In the Checkin U2 file by task dialog box, enter or select a task reference number from the Enter task reference list. When you enter a task reference number that is associated with multiple files, the Related files table displays a list of other files that use the same task reference number, as shown in the following example:
3. Optional: Enter a comment. 4. Click OK, and then click Yes to confirm the check in. The item is checked in and updated on the U2 server, and the check mark indicator is no longer displayed.
Next step ▪ Checking out object items, on page 62 ▪ Getting the latest version of object items, on page 66 ▪ Displaying LM(e) status, on page 69
Checking out object items
Check out items to edit the latest LM(e) versions. You can open and edit items from the local computer or U2 server that are not checked out, but those changes are not saved in LM(e). The next time that
62 Checking out object items you check them out, the local versions are overwritten and your work is lost. Only edit items that are not checked out if the edits are temporary and you do not want to save them.
Prerequisites Before you can check out an item, it must be added and checked in to LM(e). See the following sections for more information: ▪ Adding object items, on page 59 ▪ Checking in object items, on page 61 ▪ Checking in object items by task, on page 61
About this task Items available for check out are displayed with a yellow indicator, as displayed next to PROGRAM1 and PROGRAM3 in the following example:
You cannot check out an item that is already checked out by another user on the server. An orange check mark indicates that the file is checked out by another user. In the following example, the BAH.PROG and BH items display an orange check mark:
Procedure
1. Right-click the object item to check out, and select LM(e) → Checkout. 2. Optional: Enter a task reference number, or select one from the Enter task reference drop-down menu.
Note: Task references and their associated comments are not required by BDT to proceed, but can be useful when managing items and might be required at your site.
When you click OK and you are creating a new task reference, a message appears asking you to confirm that you want to create a new task. Click OK to confirm this message. When you enter a task reference number that is associated with multiple files, the Related files table displays a list of other files that use the same task reference number, as shown in the following example:
63 Chapter 2: Basic Developer Toolkit
3. Optional: Enter a comment for this check out. 4. Click OK. The item is checked out, and a white check mark indicator appears next to it to show that is checked out, as displayed by PROGRAM1 in the following example.
Check mark indicators show as different colors. As displayed in the previous example, a white check mark indicates an item is checked out locally. An orange check mark, such as the one next to BAH.PROG in the previous example, indicates that the item is checked out by another user. For more information about the statuses, see Displaying LM(e) status, on page 69. After the item is checked out and copied to the local computer, it is updated on the U2 server. You can now edit the item as needed.
Next step You can continue to check out items using the same task reference or creating new ones, then proceed to editing them, as described in Editing object items, on page 65. When you are ready to check in objects, you can check them in one by one, or by task. ▪ To check in only one object, see Checking in object items, on page 61. ▪ To check in objects under one task reference number, see Checking in object items by task, on page 61. If you do not want to make any changes to the item that you checked out, you can "uncheckout" the item instead of checking it back in so that no changes are committed to the U2 server. To do this, right-click the item, and select LME → Uncheckout. Confirm the uncheckout by clicking Yes to the confirmation message. The white check mark icon is removed. You can update items to what is current on LM(e) by using the Get functionality, as described in Getting the latest version of object items, on page 66. Mark items for deletion to restrict their use, as described in Marking object items for deletion, on page 66.
64 Editing object items
At any point, you can check the item's status as described in Displaying LM(e) status, on page 69.
Editing object items
You can use the Basic Program Editor to edit BASIC programs that are managed in LM(e).
Prerequisites Check out items to edit the latest LM(e) versions. You can open and edit items from the local computer or U2 server that are not checked out, but those changes are not saved in LM(e). The next time that you check them out, the local versions are overwritten and your work is lost. Only edit items that are not checked out if the edits are temporary and you do not want to save them. For more information, see Checking out object items, on page 62.
Procedure
1. From the U2 Resource view, double-click the item that you want to edit. The Basic Program Editor opens in the right pane. If the item is not checked out, the following message appears:
Do you want to checkout (Yes) or edit/view only (No) file "name"? 2. Click Yes if you want to open the Checkout U2 File window and check out this item before you edit it (See Checking out object items, on page 62 for information about how to use this window), or click No to edit the item without being under source control. You cannot check out an item that is already checked out by another user on the server. An orange check mark indicates that the file is checked out by another user. In the following example, the BAH.PROG and BH items display an orange check mark:
Next step When you are done editing the item, check it back in, as described in the following sections: ▪ Checking in object items, on page 61 ▪ Checking in object items by task, on page 61 When you close out of the Basic Program Editor, if the item is only local, the following message appears:
Do you want to add item "name" to LM(e) source control? Click Yes to add the item to LM(e) source control. For more information about using BDT to edit programs, see Code Assist, on page 30.
65 Chapter 2: Basic Developer Toolkit
Marking object items for deletion
Mark items for deletion to restrict their use.
Prerequisites Before you can mark items for deletion, you must check them out as described in Checking out object items, on page 62.
About this task Marking items for deletion does not physically delete the items from the U2 server. After you mark items for deletion, you cannot check them out or get the latest versions. The items are physically deleted from LM(e) after they are promoted to the last environment in the release. Items are physically deleted from deployment accounts after they are deployed. Items that are on your local system, but marked for deletion on the server are indicated with a red X, as displayed next to P0 in the following example.
The following steps describe how to perform this task against a basic program, not a DICT file. To perform this task on items in a DICT file, you need to use the Action Manager. See Performing LM(e) actions at the dictionary or folder level, on page 67.
Procedure
1. Right-click a checked out item, and select LM(e) → Mark for delete. 2. A confirmation appears asking whether you want to mark the selected record for deletion. If you want to remove the item locally as well, select the Remove from local account check box, and click Yes.
Getting the latest version of object items
When multiple developers work on the same items in different development accounts, it can be useful to get the latest version of items. For example, before you build an application locally you might want the version of items with the latest changes from every developer.
Prerequisites Before you can get the latest version of an item, the item must exist in the repository.
About this task "Getting" an object compares items on the U2 server with items in LM(e). Items that are checked out to the U2 server are left alone. Up-to-date items are left alone. Outdated items are overwritten
66 Performing LM(e) actions at the dictionary or folder level
with copies from LM(e). Overwriting only the outdated items is a more efficient way to get the latest versions than overwriting everything. LM(e) determines whether an item is outdated by checking its own database. If you previously used get action to get an item, and someone else has checked in updates since then, LM(e) considers your U2 version outdated and overwrites it. An out-of-date item is marked with a blue square, as shown next to the P0 program in the following example:
Procedure
Right-click an object item or the directory type folder that you want to update (or get), and select LM(e) → Get. The latest version in LM(e) updates your local version of the object item.
Performing LM(e) actions at the dictionary or folder level
When you want to manage and use LM(e) actions on items in the dictionary or at a folder level, for example a type 19 BASIC program folder, use the Action Manager.
Prerequisites Before you can use the Action Manager, you must be signed on to LM(e), as described in Signing on to and off of LM(e), on page 58
About this task The Action Manager allows you to see where items are located - locally or remote - as well as their statuses according to LM(e). The following actions are available from the Action Manager: ▪ Adding an object item ▪ Marking an item for deletion ▪ Getting the latest version of an object item ▪ Checking out or unchecking out an object item ▪ Checking in items To use the Action Manager to execute LM(e) actions, perform the following steps.
67 Chapter 2: Basic Developer Toolkit
Procedure
1. From a dictionary (DICT) type file, or a folder within your account, right-click and select LM(e) → Action Manager. Alternatively, click the Action Manager icon from the toolbar. The Action Manager appears.
If you open the Action Manager for a directory type file, you see two tabs, PROGS and DICT as displayed in the previous figure. If you open the Action Manager for HASH type files, only the DICT tab appears. 2. From the Location section of the PROGS tab, select an option to display programs only in that specific location. ▪ Local: This option displays items that are on your local system, and might not be on LM(e). ▪ Remote: This option displays items that belong to LM(e) but not your local account. Another user has checked these items in, and you do not yet have them on your local system. ▪ Both: This option displays all LM(e) items, locally and remote. 3. Select the item(s) that you want to use for LM(e) actions, then click the buttons on the right. These buttons perform the same functionality as described in previous sections. For more information, see the related task. ▪ Add: See Adding object items, on page 59. ▪ Mark for Delete: See Marking object items for deletion, on page 66. ▪ Get: See Getting the latest version of object items, on page 66. ▪ Checkout: See Checking out object items, on page 62.
68 Displaying LM(e) status
▪ Checkin: See Checking in object items, on page 61. ▪ Uncheckout: If you do not want to make any changes to the item that you checked out, you can "uncheckout" the item instead of checking it back in so that no changes are committed to the U2 server. If any of the items that you select cannot handle the action you request, for example if you try to uncheckout something that is not checked out, the following message appears.
Some items can't be handled. Would you like to continue and skip handling these items? Click Yes or No to confirm or deny this action, or click Details for a list of the items that will be handled. 4. Click the DICT tab to perform the same actions described in the previous step on any dictionary items. 5. Click Close to return to BDT.
Displaying LM(e) status
See the item status to find out where items are checked out and by whom.
Prerequisites ▪ Sign in to LM(e), as described in Signing on to and off of LM(e), on page 58. ▪ The item you are checking must be added to LM(e). See Adding object items, on page 59.
About this task You can see only the status of the item that is currently selected in the editor. Checking the status of an item that was added, but never checked in, returns a message that the item is checked out only by you. Checking the status of an item that was added and checked in can show you much more information, such as whether other developers currently have the item checked out, and whether it is marked for deletion. The following steps describe how to perform this task against a basic program, not a DICT file. To perform this task on items in a DICT file, you need to use the Action Manager. See Performing LM(e) actions at the dictionary or folder level, on page 67.
Procedure
1. Right-click an object item, and select LM(e) → LME Status. Alternatively, click the LM(e) Status icon from the toolbar. The LM(e) Status window appears.
69 Chapter 2: Basic Developer Toolkit
2. Hover over the status in the Status column, or click the Help (?) icon to read more about what each status means. Click OK to close the LM(e) Status window. The following table describes each status type.
Status Description A The artifact is checked out by another user. Indicated in the U2 Resource view as an orange check mark. D The artifact has been marked for delete in any environment. E The artifact is checked out in this development environment, but not by this user. C The artifact is in conflict, checked out by the current user and in this development environment. L The artifact is locked because the release is not active. M The artifact is checked out by multiple users. O The artifact is checked out by the current user and in this development environment. Indicated in the U2 Resource view as a white check mark. S The artifact is out of date. Indicated in the U2 Resource view as a blue square. U The artifact is checked out by the current user but in a different development environment. X The artifact cannot be checked out, it is checked out either to a different user or in a different environment, and the current release is single checkout only. - The artifact is under source control, but not checked out by this user in this development environment. Indicated in the U2 Resource view as a yellow rectangle. ? The artifact is not under source control. If you view the LM(e) Status window at the account or directory type folder level, you see the status for all programs in that account or directory type folder, as shown in the following example.
Shutting down LM(e)
In the case that the LM(e) client experiences an irreparable state, such as being unresponsive to commands, you can shut down the LM(e) server. To shutdown an account in use, right-click the account and select LM(e) → Shutdown. A message appears asking you to confirm the shut down. Click Yes.
70 Chapter 3: EDA Replication Configuration tool
External Database Access (EDA) Replication is useful if you want to maintain an account from which you can create reports. You can replicate your data to a SQL database in addition to keeping your data safely stored in the database. When you store your data in a U2 database, it is simultaneously replicated to Oracle, IBM DB2, or Microsoft SQL Server. Use this replicated database for data mining or reporting while you use U2 as your production workhorse. Use the EDA Replication Config tool to edit EDA map schemas, edit data source definitions, and convert UniData or UniVerse files to EDA files. Starting the EDA Replication Config tool
Before you can manage EDA Replication, you must start the EDA Replication Config tool.
Prerequisites UniData or UniVerse services must be currently running.
Procedure
Click Start → All Programs → Rocket U2 → EDA Replication Config Tool. Configuring EDA replication
• Defining EDA replication parameters You must configure the parameters specific to EDA replication. • Configuring the replication system You must define the system to which you want to replicate EDA data. • Specifying files to replicate You must create a replication group and choose the files to replicate. • Defining EDA data sources You must define a data source pointing to the external database to which you want to connect. • Defining an EDA data source connection You must define a data source pointing to the external database to which you want to connect. • Synchronizing replicated files You must synchronize the files in the source account with the files in the target account. • Converting U2 files to EDA files You can convert the U2 file to an EDA file.
Defining EDA replication parameters
You must configure the parameters specific to EDA replication. 1. From the U2 Resource pane, right-click the account that you want to use to replicate EDA data, and select EDA replication config tool.
71 Chapter 3: EDA Replication Configuration tool
2. From the EDA Replication Config tool, click Configure Replication Parameters. The Configure Replication Parameters pane opens, as shown:
3. On the Configure Replication Parameters dialog box, enter a new value for one or more of the following parameters:
Parameter Description MAX_LRF_FILESIZE The maximum Log Reserve file size, in bytes. The default value is 1,073,741,824 (1 GB). The maximum value is 2,147,483,136. MAX_REP_DISTRIB Reserved for internal use. MAX_REP_SHMSZ The maximum shared memory buffer segment size. The default value is 67,108,864 (64 MB). N_REP_OPEN_FILE The maximum number of open replication log files for a udt or tm process. The default value is 8. REP_CP_TIMEOUT The cm daemon timeout interval, in seconds, for replication at checkpoint. The default value is 200 seconds. To prevent the cm daemon from timing out, set the parameter to 0.
72 Configuring the replication system
Parameter Description REP_FLAG Enable or disable replication. To enable replication, set REP_FLAG to 0. To disable replication, set REP_FLAG to 1. The following table describes REP_FLAG options: Value Description 0 (Zero) The UniData Data Replication System is off. Any positive integer The UniData Replication System is on. REP_LOG_PATH The full path to the location of the replog file. TCA_SIZE The maximum number of entries in the transaction control area (TCA). TCA is used only when more than one replication group is configured and transactions occur across replication groups. The default value is 2048. If you are using transaction processing, set the value of TCA_SIZE to at least the number of users on the system. If you are not using transaction processing, this parameter is irrelevant. UDR_CONVERT_CHAR When this value is set to 1, if the publishing system and the subscribing system have a different I18N group, UniData converts marks and SQLNULL marks to the marks used on the local system. The default value is 0. 4. Click Save Changes. Parent topic: Configuring EDA replication
Configuring the replication system
You must define the system to which you want to replicate EDA data. 1. From the U2 Resource pane, right-click the account to which you want to replicate EDA data, and select EDA replication config tool. 2. In the EDA Replication Config dialog box, click Configure Replication System.
73 Chapter 3: EDA Replication Configuration tool
3. In the Replication Systems list, select the system to which you want to replicate data. This system must be the same system on which the EDA account resides.
4. In the Configure Replication System dialog box, complete the following fields:
Field Action
System ID Enter a unique name for the replication system. The System ID can contain a combination of alphabetic characters, numbers, and any of the following characters: ~ ! @ $ % ^ & * - + . / \.
Host Name Enter the host name of the replication system location. A system can have only one host name.
Version Select the version of the U2 database running on the system location.
DHCP Select the check box if the local system has a dynamic IP address.
Auto Resume Select Yes if you want to automatically synchronize and resume when the U2 database starts, or No if you want to manually synchronize.
74 Specifying files to replicate
Field Action
Sync Interval Enter or select the time interval, in minutes, in which the replication system automatically synchronizes replication. A value of 0 specifies manual synchronization. The sync interval applies only to those subscribing groups that have deferred replication.
Connect (Optional) Select the check box to verify the subscribing system. Authorization U2 Data Replication performs an authorization check when it receives a SYNC request from the subscribing system.
Timeout Enter or select the number of seconds to wait if no packets are received from the system before suspending replication. If the value of timeout is 0, no timeout occurs. We recommend not setting this value to less than 2 minutes.
Exception Action If you want to execute a shell script on a UNIX platform or a batch program on a Windows platform when an exception occurs, specify the full path to the script in the field, or click Browse to locate the path.
Add Click to define a different account to replicate EDA data. The account definition is automatically populated with the account you previously defined.
5. Click Save Changes to save your settings. Parent topic: Configuring EDA replication
Specifying files to replicate
You must create a replication group and choose the files to replicate. 1. From the U2 Resource pane, right-click the account to which you want to replicate EDA data, and select EDA replication config tool.
75 Chapter 3: EDA Replication Configuration tool
2. From the EDA Replication Config tool, select Choose Files to Replicate.
3. If you have not previously defined a replication group, click Create from the Configure Replication Group window. 4. In the Group ID field, enter a unique name for the subscribing group. 5. Open the Source Account list and select the source account from the list. 6. In the Level field, select the level of replication. For EDA Replication, you can only choose FILE. 7. In the Files area, click Add to select the files you want to publish. 8. If you do not want to publish the data portion of the file, clear the Data check box. If you do not want to publish the dictionary portion of the file, clear the Dict check box. 9. To enable the ability to update the file on the subscribing system, select the Sub Writeable column. 10. In the Distributions area, click Add to define replication distribution details. 11. In the System Name field, select the local system from the list. 12. Select the Replication mode you want to use. 13. Click Finish.
76 Defining EDA data sources
14. If you want this publishing group to automatically failover to a standby system, select the standby system in the RFS Failover System field. 15. Set any of the configuration parameters necessary for your environment in the Configuration area. 16. Click Save Changes. Parent topic: Configuring EDA replication
Defining EDA data sources
You must define a data source pointing to the external database to which you want to connect. 1. After you connect to your U2 server, right-click EDA Data Sources, then click New EDA Data Source. 2. In the Name field, enter a unique name to identify the external data source. The name cannot contain a slash (/) or backslash (\) character. 3. In the DSN/Net Service/DB Alias field, enter the name of the external database to which you are connecting. The name must be the data source defined in the ODBC Data Source Administrator. 4. From the Driver list, select the type of driver. 5. To define an EDA data source connection, click Add. Parent topic: Configuring EDA replication
Defining an EDA data source connection
You must define a data source pointing to the external database to which you want to connect. 1. In the Login User ID field, enter the user ID on the external server. 2. In the Password field, enter the password corresponding to the user ID. 3. In the Re-enter Password field, type the password again for verification. 4. In the Hold Flag field, select YES if you want to maintain the connection on the external server after a transaction commits. Select NO if you want to disconnect from the external server after the transaction commits. 5. In the Qualified Users field, enter the UniData or UniVerse user IDs of users who can access the external server from the UniData or UniVerse account using the external login user ID you specify. Separate the users by a pipe ("|") symbol. If all users can access the external account, enter an asterisk ("*"). 6. Click Test to test the connection to the external data source. Parent topic: Configuring EDA replication
Synchronizing replicated files
You must synchronize the files in the source account with the files in the target account. 1. Select the files from the source account to synchronize with files in the target account. 2. Click Start File Synchronization. 3. Choose whether to overwrite existing files in the target account. Parent topic: Configuring EDA replication
77 Chapter 3: EDA Replication Configuration tool
Converting U2 files to EDA files
You can convert the U2 file to an EDA file.
Prerequisites Synchronize the files.
Procedure
1. Select the files you want to convert. 2. Add an attribute to the EDA Schema, as described in Creating EDA schemas for selected attributes, on page 88. 3. Click Convert the U2 File to EDA File. 4. Select the type of conversion to use: ▪ Force – Drops existing tables before creating new ones ▪ Verbose – Displays detailed messages during the conversion process 5. Click EDA Convert. Replication is suspended during file conversion. Parent topic: Configuring EDA replication EDA Schema Manager
Use the EDA Schema Manager to convert U2 files to an external database format.
To convert U2 files to an external database format, EDA Schema Manager performs the following steps: 1. The EDA Schema processor receives information from the dictionary file for the data file you are converting and other user input. 2. From this information, the EDA Schema Processor creates an EDA schema. This EDA schema is a record in the _EDAMAP_ (UniData) or &EDAMAP& (UniVerse) file.
78 Starting the EDA Schema Manager
3. Optionally, you can verify the EDA schema. 4. The conversion process uses the EDA schema record and the U2 physical file to create tables and views in the external database. 5. The U2 physical file is replaced by an EDA file in the U2 account. The original data file is saved as filename.edasave.
Starting the EDA Schema Manager
Use the EDA Schema Manager to create a mapping file, called EDA Schema, for a U2 file you are converting to the external database. Then use the mapping file to convert the U2 data to the external database format. From the Windows Start menu, click Programs → Rocket U2 → EDA Schema Manager.
Creating a new U2 server connection
To create a new U2 server connection, perform the following steps.
Procedure
1. Right-click Servers and select New → U2 Server. 2. In the Create a New U2 Server wizard, from the Name field, enter a unique identifier for the new server. 3. In the Host field, enter the network name of the host computer where the U2 database resides, or the IP address. 4. From the U2 database options, select UniData or UniVerse. 5. If you want to define the protocol type, RPC port number, RPC service name, or the login account, click Advanced.
79 Chapter 3: EDA Replication Configuration tool
A dialog box similar to the following example appears:
a. In the Protocol Type field, select the type of communication you are using for the server. You can select Default, TCP/IP, or Lan Manager. The default is TCP/IP. b. In the RPC Port # field, enter the port number of the UniRPC server running on the host. The default port number is 31438. c. In the RPC Service Name field, enter the name of the RPC service on your system. For UniData, this is normally udcs For UniVerse, this is normally uvcs. d. In the Login Account field, enter the name of the account to which you want to log on when accessing the U2 database. e. In the Commands to Execute field, click Add to enter commands that you want to execute when you log on to the server. Enter commands in the dialog box that appears, then click OK when finished. f. In the Specify the session to run/debug your BASIC programs on server side area, specify the type of connection that you want to make to the server. You can specify Telnet or SSH. g. In the Port Number field, enter the port number you want to use if you do not want to use the default port number of 23.
80 Connecting to the U2 server
h. Select the Use Device License check box if you want to enable device licensing when connecting to the server. i. In the Max # of Sessions field, enter a number. 6. Click Finish. The new server appears in the U2 Resource view.
Connecting to the U2 server
To connect to the U2 server, perform the following steps. 1. Right-click the server name, then click Connect. When you connect to the server, the Connect to U2 Server dialog box appears. 2. In the User ID field, enter the User ID for the machine where U2 is running. 3. Enter the corresponding password in the Password field. 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. 4. 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. 5. Click Finish. The accounts and existing data sources definitions appear in the U2 Resource view.
Managing connections
You must define a data source pointing to the external database to which you want to connect.
About data sources
You must define a data source pointing to the external database client residing on the machine where U2 is installed. The following external databases are supported: ▪ IBM DB2 ▪ Microsoft SQL Server ▪ Oracle Database
Note: For more information regarding the external database that you are accessing, see the information about the supplied drivers in the UniData or UniVerse External Database Access (EDA) Reference.
The external database server can be on the same machine as the U2 server or on a different machine. However, the external database client must be on the same machine where the U2 server is installed.
Connecting to SQL server, Oracle, or IBM DB2 The U2 server can reside on UNIX, Linux, or Windows. After the SQL server, Oracle, or DB2 database server is installed, the appropriate ODBC driver must be installed on the U2 server machine. The drivers for access to the databases are:
81 Chapter 3: EDA Replication Configuration tool
▪ SQL Server - Open source or third-party ODBC library for UNIX ▪ SQL Server - Native client for Windows ▪ Oracle - Oracle Client Library (OCI) ▪ DB2 - DB2 Client Library (CLI) The installation program automatically places the EDA driver library for SQL server (libcomdrv), the EDA driver library for Oracle (liboradrv), and the EDA driver library for DB2 (libdb2drv) in the $UDTBIN (UniData) or $UVBIN (UniVerse) directory.
Note: Microsoft provides SQL server ODBC driver on RedHat and SUSE Linux platforms.
The following examples shows how U2 connects to database servers:
82 Connecting to Microsoft SQL server using the Native Client
Connecting to Microsoft SQL server using the Native Client To use the native Microsoft SQL server client, the database must reside on a Windows platform. After the SQL server database is installed, the appropriate SQL server client library (native client) must be installed on the U2 server machine. The U2 installation automatically places the EDA driver library for SQL server (libsqldrv) in the $UDTBIN (UniData) or $UVBIN (UniVerse) directory. The following example shows how U2 connects to SQL server from a Windows platform:
Defining a data source
You must define a data source pointing to the external database to which you want to connect.
Prerequisites ▪ Connecting to the U2 server, on page 81
Procedure
1. From the U2 Resource view, expand the server you want to use, right-click EDA Data Sources, then click New → EDA Data Source.
83 Chapter 3: EDA Replication Configuration tool
2. In the Create a New EDA Data Source wizard, enter a unique name for the external data source in the Data Source Name field, then click Finish. A data source information tab appears in the right pane of the EDA Schema Manager window, as shown in the following example:
3. In the External DSN field, enter the name of the external database client that provides the connection to the desired external database instance. For Microsoft SQL Server, it is the name of the ODBC Data Source you have defined in ODBC Data Source Administration. For DB2, it is the database name specified in the CATALOG DATABASE command. For Oracle, it is the connection name defined in the tnsnames.ora file. 4. In the Driver field, enter the type of driver and enter any details about it in the Description field. 5. Click Add. In the EDA Data Source Connection dialog box that appears, enter the following information: a. In the Login User ID field, enter the user ID on the external server. b. In the Password field, enter the password corresponding to the User ID. Enter the password again in the Re-enter Password field. c. If you want to maintain the connection to the external server after a transaction commits, select YES from the Hold Flag drop-down menu. If you want to disconnect from the external server after the transaction commits, select NO.
Note: If you do not use UniVerse BASIC transactions, each U2 database operation, such as a READ or WRITE, corresponds to an external transaction.
d. In the Qualified Users field, enter the U2 user IDs of users who can access the external server from the U2 account using the external Login User ID you specify. Separate the users by a “|” symbol. If all U2 users can access the external account, enter an asterisk (“*”). e. Click Finish.
Results The following example shows a completed EDA Data Source:
84 Creating EDA schemas
To test the connection to the external instance, click Test. A success message appears if the connection is successful; otherwise a detailed error message appears. From the File menu, click Save to save your data source definition, or click the Save icon.
Creating EDA schemas
Prerequisites ▪ Connecting to the U2 server, on page 81 ▪ Defining a data source, on page 83
Procedure
1. From the U2 Resource view, expand Accounts and then expand the account where the files you want to convert reside. 2. Right-click the EDA Schema Files, and select New → EDA Map Schema. 3. In the Create New EDA Map Schema wizard that appears, enter a unique name for the EDA schema in the EDA Schema Name field. 4. Select EDA Schema from the Map Format options. Click Next. 5. On the Source U2 file page, click the file for which you are creating a schema.
85 Chapter 3: EDA Replication Configuration tool
6. From the Using Data Source drop-down menu, select the data source you are using. Click Next. The U2 Dictionary Attributes page appears, as shown in the following example:
The U2 Dictionary Attributes page lists the D-type dictionary attribute for the file you specified. Select each dictionary attribute to map to the external database. To select all D-type dictionary attributes, click Select All. To clear all dictionary attributes, click Deselect All. For selective mapping or virtual field mapping, you must click Deselect All. If you want to selectively map U2 attributes to an external database, only select those attributes you want to map. If you do not select any dictionary attributes, the @ID attribute is automatically mapped. In the following example, only @ID and ADDRESS have been selected:
7. Click Finish when you have selected all the dictionary attributes for which you want to create schemas.
86 Creating EDA schemas
Results The EDA schema you created appears in a tab on the right pane of the EDA Schema Manager window and the Outline view on the bottom left populates, as shown in the following example:
The following example illustrates the appearance of the window after the @ID and ADDRESS attributes have been selected. Notice that a red arrow appears next to the attribute in the U2 File Dictionary portion of the window, indicating the attribute has been mapped. Click the mapped attribute you want to display in the EDA Map Schema view.
87 Chapter 3: EDA Replication Configuration tool
Note: The EDA Schema Manager allows 30-character column names for Oracle and DB2 and 60- character column names for SQL Server. If the dictionary ID length is longer, it will be truncated in the EDA Map Schema portion of the window.
Next step ▪ Defining attribute details, on page 88 ▪ Defining options, on page 90
Creating EDA schemas for selected attributes
You can select the dictionary attributes you want to map. 1. Click Create EDA Schemas for the Replicated Files. 2. Select the files for which you want to create schemas. 3. Click Create EDA Schemas. 4. Select the data source for which you want to create schemas from the Data Source list, or click New Data Source to create a new data source. 5. Click Deselect All, then select the dictionary attributes for which you want to create a schema. 6. If you are creating schemas for multiple files, click the arrow next to the current file name to advance to the next file. 7. Click Finish when you have selected all the dictionary attributes for which you want to create schemas. 8. If you want to view the schema that was created, click Open EDA Schemas.
Creating default EDA schemas for the replicated files
You can create a default EDA schema for the files you selected, which maps each D-type attribute, or select the attributes you want to map. 1. Click Create EDA Schemas for the Replicated Files. 2. Select the files for which you want to create schemas, and click Create EDA Schemas. 3. Select the data source for which you are creating the schema from the list. 4. Click OK. EDA Replication pauses the database and maps each D-type attribute in the dictionary file. 5. To view the schema that was created, click Open EDA Schemas.
Defining attribute details
In the Attribute Details area of the EDA Schema Manager, define the mapping details for the attribute you selected.
Prerequisites ▪ Creating EDA schemas, on page 85
About this task You can change the name, type, data type, formatting, database name, namespace, and data source. Namespace refers to the external schema name where the conversion process will create the corresponding external tables and views.
88 Defining attribute details
The following example shows the Attribute Details (right) for the @ID mapped attribute.
Procedure
1. Select an Occurrence: Once or Once or More. 2. In the Name field, enter the name of the column in the resulting external table. 3. In the Type field, select the type of attribute. Valid types are: ▪ DATA: used to store attribute values allowed by the data type you specify. This option creates a column in the external database. If this is a D-type attribute, its values are stored in this column. If it is defined as a virtual attribute or V-type(UniData) or I-descriptor (UniVerse), the virtual attribute/I-descriptor is evaluated in U2, and the result is stored in this column in the external database. ▪ EXPRESSION: used for virtual attributes (UniData) or I-descriptors (UniVerse) only. Enter the SQL expression for the virtual/I-descriptor attribute in the Expr Body field, such as FNAME CONCAT ‘ ‘ CONCAT LNAME. ▪ ID DATA: the primary key in the external table ▪ NOT NULL DATA: specifies that the external database column cannot contain the null value. ▪ SCALAR FUNCTION: used to define a scalar function to execute an equivalent virtual attribute/I-descriptor on the external database. For information about creating a scalar function, see Scalar function, on page 94. ▪ TABLE FUNCTION: used to define a table function For information about creating a table function, see Table function example, on page 98. ▪ TRANS: used for virtual attributes/ I-descriptors containing a TRANS clause only. If you specify TRANS, you must also specify Reference and Parameters. For more information, see TRANS function, on page 95. ▪ UNIQUE DATA: specifies that values in the external database column must be unique 4. In the Data Type field, enter the data type for the mapped attribute. In this case, the data type is VARCHAR. The EDA Schema Manager automatically converts the data type based on the dictionary record. If an application attempts to insert or update an external attribute with a value that does not match the data type you define, the EDA system rejects the operation.
89 Chapter 3: EDA Replication Configuration tool
5. In UniData, the Reference field is used for V-type attributes that contain a TRANS clause. In UniVerse, this field is used for I-type attributes that contain a TRANS clause. Enter the name of the external table TRANS clause reference in this field. You can alternatively drag and drop the applicable attribute from the U2 File Dictionary area to the Attribute Details area. 6. If the mapped attribute is an expression, enter the SQL expression in the Expr Body field. This field applies to the virtual attribute/I-descriptor that contains a user-defined function or expression. Use the Expr Body field to enter the equivalent SQL statement for the expression or function. 7. Specify the attribute or expression in the TRANS function that returns the record ID in the table you are referencing in the external database. Click the plus sign (+) in the Parameters portion of the window. In the dialog box that appears, enter a Parameter. Click Finish. 8. In the Formatting field, select the appropriate format for the attribute.
Note: The Index field is no longer supported.
Results If you select all dictionary attributes, U2 maps only D-type attributes. You must map virtual attributes/ I–descriptors manually. You cannot map unassociated multivalued or I-descriptors. You also cannot map associations that contain only I-descriptors.
Defining options
You can view the options from a mapped EDA Schema.
Prerequisites ▪ Creating EDA schemas, on page 85
90 Defining options
Procedure
1. Click Options in the EDA Map Schema area of the U2 EDA Schema Manager. The Options area (right) appears in the EDA Map Schema area.
2. From the Whole Record drop-down menu, select Yes or No to specify whether to store the entire U2 record in the RECORD_BLOB column on the EDA server at the same time the individually mapped U2 fields are written to their mapped columns.
Note: This option can improve the performance of READ operations, especially when mapping multivalued and multi-subvalued attributes since you avoid complex outer-joins.
If the value of Whole Record is Yes, the entire U2 record will be stored in the RECORD_BLOB on the EDA server. If the value is No, only unmapped fields are stored in the RECORD_BLOB. The default value is No. If you select Yes, you should not be updating the data from the external database; only update it through UniVerse BASIC or UniData/UniVerse SQL. A failure to comply with this rule can result in inconsistent data. 3. In the Unmapped Field Block (KB) field, specify the size of the character large object (RECORD_BLOB) in kilobytes. The default value is 16. The RECORD_BLOB serves several purposes: ▪ To hold all attributes that are not explicitly mapped ▪ To hold the entire U2 record when the WHOLE_RECORD flag is set to “Yes” ▪ To hold nonconforming records 4. From the Nonconforming Record drop-down menu, select Yes or No to specify whether to return validation or truncation errors generated by the external database to your application so the behavior of your application does not change. A nonconforming record is a U2 record that generates an exception error when it is written to the EDA server database, but does not cause an error in the U2 database. For example, U2 allows you to store a text string in an attribute defined as having a numeric conversion, such as MD2, Date or Time, but this will generate an error in the external database.
91 Chapter 3: EDA Replication Configuration tool
If the value of Nonconforming Record is set to Yes, a NONCONFORMING_FLAG column is created in the EDA file. When a U2 record is determined to be a NONCONFORMING record, the ID of that record is inserted in the primary key column of the external table, the NONCONFORMING column is set to 1, and the entire U2 record is written to the RECORD_BLOB column. In this case, no error is returned to the U2 application. If U2 attempts to write the nonconforming data to a RECORD_BLOB that is not large enough to contain the data, the write fails and U2 writes the record to the EDA_EXCEPTION file on the U2 database and an error is returned to the U2 application. If the value of Nonconforming Record is No, the nonconforming data is only written to the EDA_EXCEPTION file on the U2 database and an error is returned to the U2 application. For more information about retrieving nonconforming data, see the information about SELECT.EDA.NONCONFORMING in the UniData or UniVerse External Database Access (EDA) Reference. 5. From the Table Space (KB) drop-down menu, select the default page size. The maximum page size is 256 KB. A table space is the basic storage structure on an external database. By default, U2 creates all tables in USERSPACE 1, the default user table space. This table space has a 4 KB page size, so the length of a row of a table is limited to less than 4 KB. If the row length is exceeded, U2 generates an error during the conversion process. When you select a table space size, for example, 8 KB, the EDA Schema Manager creates the table space EDATBSPC8K if it does not already exist, then creates the EDA tables in this table space.
Viewing EDA server details
To view information about the EDA server, click the external Schema Name/Table Name in the EDA Map Schema pane of the U2 EDA Schema Manager. Information about the EDA server is displayed, as shown in the following example:
The U2 EDA Schema Manager displays the following details about the EDA server: ▪ The DBInstance field displays the name of the instance on the EDA server. ▪ The DBMSName field displays the name and version of the database on the EDA server. ▪ The DBMSFamily field displays the database family to which the DBMS name belongs. ▪ The DBModel field displays the type of database. U2 only supports 1NF databases.
92 Viewing U2 server details
▪ The Name Space (Schema) field displays the name of the schema on the EDA server. You can change the name of the schema. ▪ The Root Name field displays the name of the table on the EDA server. You can change the name of the table. ▪ The Data Source field displays the name of the data source on the EDA server.
Viewing U2 server details
To view information about the U2 server, click the U2 file name in the EDA Map Schema area of the EDA Schema Manager. Information about the U2 server appears, as shown in the following example:
The EDA Schema Manager displays the following details about the U2 server: ▪ The U2 Host field displays the name of the U2 host server where the file resides. ▪ The U2 System field displays the type of database on the server where the file resides. ▪ The U2 Version field displays the version of the database on the U2 server where the file resides. ▪ The U2 Account field displays the full path to the account on the U2 server where the file resides. ▪ The File Name field displays the name of the file on the U2 server.
EDA schema examples
Use the following sections to see examples of different types of EDA schemas:
• Scalar function This example illustrates a scalar function, used to execute an equivalent virtual attribute/I- descriptor on the external database. • TRANS function This example illustrates the TRANS function, used for virtual attributes/I-descriptors containing a TRANS clause. • Table function example
93 Chapter 3: EDA Replication Configuration tool
U2 allows you to use the DB2 table function concept to evaluate multiple virtual attributes/I- descriptors at the same time. In some cases, you are able to map more than one virtual attribute/I- descriptor with one DB2 user-defined table function.
Scalar function This example illustrates a scalar function, used to execute an equivalent virtual attribute/I-descriptor on the external database. Assume you have the following I-descriptor attribute defined for the CUSTOMER file in your UniVerse database:
:AE DICT CUSTOMER UPCASE.LNAME Top of "UPCASE.LNAME" in "DICT STUDENT", 6 lines, 25 characters. 001: I 002: UPCASE(LNAME) 003: 004: 005: 30L 006: S
This I-descriptor converts the customer’s last name to uppercase.
1. To convert this I-descriptor to a scalar function using the EDA Tool, drag UPCASE.LNAME from the U2 File Dictionary pane under CUSTOMER in the EDA Map Schema pane. 2. In the Attribute Details pane, change the Type to SCALAR FUNCTION. 3. In the Data Type field, define the data type for the output 4. In the Reference field, enter the external database function and data type for the value you are passing to the function. In this example, the DB2 system function that corresponds to the UniData or UniVerse UPCASE function is UCASE, which resides in the SYSFUN Schema in the DB2 database. Enter the following formula in the Reference field:
SYSFUN.UCASE(VARCHAR(30))
94 TRANS function
5. In the Parameters field, click the plus sign (+), and enter the field to pass to the scalar function. The Attribute Details should now look like the following example:
The following example contains the output from U2 when you run this scalar function:
>LIST CUSTOMER UPCASE.LNAME LIST CUSTOMER UPCASE.LNAME 03:48:02pm 09 Jun 2010 PAGE 1 CUSTOMER...... 2 MORRIS 4 KAHN 6 BURKE 3 ARGONNE 5 WILLIAMS 7 GILL 10 MCCAIG 8 HOLLAND 12 PATRY 1 SMITH 9 ORLANDO 11 LEWIS 12 records listed.
Parent topic: EDA schema examples
TRANS function This example illustrates the TRANS function, used for virtual attributes/I-descriptors containing a TRANS clause. Assume you have the following U2 virtual attribute/I-descriptor defined in the dictionary of the CUSTOMER file:
001: I Product description 002: TRANS(PRODUCTS,PRODID,DESCRIPTION,"C") 003: 004: Product Description 005: 20T
95 Chapter 3: EDA Replication Configuration tool
006: M 007: ORDERS
1. To convert this virtual attribute to a trans function using the EDA Tool, drag TEACHER from the U2 File Dictionary pane under the COURSES node of STUDENT in the EDA Map Schema pane, as shown in the following example:
This I-descriptor executes a translate from the CUSTOMER file to the PRODUCTS file and returns DESCRIPTION. 2. To convert this I-descriptor to a trans function using the EDA Tool, drag DESCRIPTION from the U2 File Dictionary pane under the ORDERS_MV node of CUSTOMER in the EDA Map Schema pane, as shown in the following example:
96 TRANS function
3. Click DESCRIPTION in the EDA Map Schema portion of the window to define the Attribute Details for this function. The following example illustrates the details of the DESCRIPTION function:
4. In the Attribute Details pane, change the Type to TRANS. 5. In the Data Type field, define the data type for the output. 6. In the Reference field, enter the name of the external table that contains the DESCRIPTION information. In this example, the information resides in PRODUCTS.PRODUCTS/DESCRIPTION. 7. In the Parameters field, click the plus sign (+) and enter the field to pass to the TRANS function. In this example, PRODID is passed to the TRANS function. The following example illustrates output from the DESCRIPTION TRANS scalar function:
Parent topic: EDA schema examples
97 Chapter 3: EDA Replication Configuration tool
Table function example U2 allows you to use the DB2 table function concept to evaluate multiple virtual attributes/I- descriptors at the same time. In some cases, you are able to map more than one virtual attribute/I- descriptor with one DB2 user-defined table function. Assume you create a monthly report containing product descriptions and prices. To create this report from UniVerse, you use the following I-descriptors for product description and list price:
:AE DICT CUSTOMER DESCRIPTION 001: I 002: TRANS(PRODUCTS,PRODID,DESCRIPTION,“C”) 003: 004: Product Description 005: 20T 006: M 007: ORDERS
:AE DICT STUDENT LIST_PRICE 001: I 002: TRANS(PRODUCTS,PRODID,LIST,”C”) 003:MD0,$ 004: List Price 005: 7R 006: M 007: Orders
To map these I-descriptors, drag each one from the U2 File Dictionary pane to the ORDERS_MV node in the EDA Map Schema pane, as shown in the following example:
Although you map DESCRIPTION and LIST_PRICE separately, some external databases allow you to create one function for use with multiple attributes. You have to define the EDA Map Schema for both I-descriptors, but you only have to define the function once. The following example illustrates how you would use a DB2 table function in order to evaluate both DESCRIPTION and LIST_PRICE on the DB2 database. First, let’s map the DESCRIPTION I-descriptor: In the Attribute Details portion of the window, change the Type to TABLE FUNCTION.
98 Table function example
In the Data Type field, enter the data type for the output of the attribute you specified in the Name field. In the Reference field, enter the external database schema name, the name of user-defined function you are defining in the Expr Body field, the data type for the input value, and the external function attribute name, as shown in the following example:
CUSTOMER2.GET_PRODUCT(VARCHAR(20))/DESCRIPTION
In this example, the user-defined function will be named GET_PRODUCT and reside in the CUSTOMER2 schema in the external database. The data type of the input parameter is VARCHAR(20), and you are using the output parameter PRODUCT. In the Expr Body field, enter the table function body. In this example, the function is defined as:
PRODID F1:BEGIN ATOMIC RETURN SELECT B.DESCRIPTION, B.LIST_PRICE FROM PRODUCTS.PRODUCTS AS B WHERE B.ID=PRODID; END
In the Parameters field, click the plus sign (+) to define the parameter to pass to the table function and the output parameters you want to return. For output parameters, you specify OUTPUT, the name of the attribute to return, and the data type. In this example, the output parameters are defined as:
OUTPUT DESCRIPTION VARCHAR(50) OUTPUT LIST_PRICE VARCHAR(10)
The following example shows the DDL scripts UniVerse creates for this table function:
CREATE FUNCTION CUSTOMER2,GET_PRODUCT(PRODID VARCHAR(5)) RETURNS TABLE(DESCRIPTION VARCHAR(50),LIST_PRICE VARCHAR(10)) F1:BEGIN ATOMIC RETURN SELECT B.DESCRIPTION,B.LIST_PRICE FROM PRODUCTS.PRODUCTS AS B WHERE B.ID=PRODID; END
Next, let’s map the LIST_PRICE I-descriptor. Click the LIST_PRICE attribute. The following example illustrates the Attribute Details for this attribute:
99 Chapter 3: EDA Replication Configuration tool
In the Attribute Details portion of the window, change the Type to TABLE FUNCTION. In the Data Type field, enter the data type for the output of the attribute you specified in the Name field. In the Reference field, enter the DB2 Schema name, the name of user-defined function you previously defined in the DESCRIPTION table function (GET_PRODUCT), the data type for the input value, and the external database function attribute name, as shown in the following example:
CUSTOMER2.GET_PRODUCT(VARCHAR(5))/LIST_PRICE
In this example, the user-defined function GET_PRODUCT resides in the CUSTOMER2 schema in the DB2 database. The data type of the input parameter is VARCHAR(5), and you are using the output parameter LIST_PRICE. Since you previously defined the GET_PRODUCT function, you do not need to enter data in the Expr Body. In the Parameters field, click the plus sign (+) to define the parameter to pass to the table function. You do not need to define the output parameters since they were previously defined in the GET_PRODUCT function.
Note: For information about creating external database user-defined functions, see the external database documentation.
Parent topic: EDA schema examples
Verifying EDA schemas
After you have created an EDA Schema, you can verify the EDA Schema.
100 Verifying EDA schemas
1. To verify the EDA Schema, click the Verify icon on the toolbar. A dialog box similar to the following example appears:
2. In the Verify the EDA Map Schema dialog box, select one of the following verification types: ▪ Syntax – Verifies that the syntax of the SQL statements that creates the external tables is correct. ▪ Metadata – Verifies that all the metadata required to create the external tables exists. ▪ Data – Verifies that the UniVerse data meets the requirements for the external tables. You can select one of the following options when verifying your data: ▫ All Records – analyzes each record in the UniVerse data file ▫ Specified Records– you can enter specific record IDs to analyze. Separate each record ID with a right brace (}). ▫ First n Records – the system verifies the first n records you specify. ▫ Every n-th Records – the system verifies every n-th record you specify.
101 Chapter 3: EDA Replication Configuration tool
3. To view the EDA schema, click Show Schema. The schema appears in the dialog box, as shown in the following example:
Adding attributes to EDA schemas
You can alter existing schemas for UniData without having to reload the existing tables.
Prerequisites ▪ UniData only ▪ Only ADD attributes are allowed in S-field or MV/MS fields. ▪ The fields must be in the existing tables. ▪ The server options cannot be changed, while the client options can be different. ▪ The WHOLE RECORD and UNMAPPED settings must not affect the BLOB field definitions. The settings must be either WHOLEREC=1, or UNMAPPED = 0 and Non-Conforming= No
Procedure
1. Click Create EDA Schemas for the Replicated File. 2. Select the files for which you want to alter the schemas. 3. Click Open EDA Schemas. 4. Add the new dictionary to the EDA Map Schema, and save the schema. 5. Click Convert the U2 File to EDA File. 6. Select the type of conversion you want to use: ▪ Force – Drops existing tables before creating new ones ▪ Verbose – Show detailed messages during the conversion process 7. Click EDA Alter .
102 Viewing the DDL scripts
Note: For more information about the ALTER.EDAMAP command, see the UniData External Database manual.
The database suspends replication during the conversion process, and the new attribute is appended to the table without having to reload the table.
Viewing the DDL scripts
To view the DDL script that UniData or UniVerse will use to generate the data on the external table, click the DDL Scripts icon on the toolbar. Get DDL Scripts appear in the window, as shown in the following example:
Converting data from U2 to an external database
You can convert data from U2 to the external database. 1. Click the Convert Data icon. 2. In the Convert the U2 File to EDA File dialog box, select the type of conversion to use: ▪ Click Force to drop existing tables on the external database before creating new ones. You must select this option if you are reconverting data. ▪ Click Verbose to display detailed messages and DDL scripts during the conversion process. 3. Click EDA Convert. If the conversion is successful, a message reports the total number of converted records . If the conversion is not successful, error messages describe the problems.
103 Chapter 3: EDA Replication Configuration tool
4. To see which files were converted from U2 to the external database, from the EDA Schema Manager, click the plus sign next to expand EDA Schema files.
Accessing data in an external database
Use RetrieVe, UniData/UniVerse SQL, and UniVerse BASIC to access the data in the external database.
Listing data using RetrieVe
You can use the RetrieVe LIST command to view the converted data on the external database, as shown in the following example:
104 Listing data using UniData/UniVerse SQL
Listing data using UniData/UniVerse SQL
You can use the SQL SELECT command to view the converted data on the external database, as shown in the following example:
>SELECT FNAME, LNAME, CITY, STATE FROM CUSTOMER, First Name.. Last Name...... City...... State
Morris Waltham MA Kahn Boston MA Burke White River Jun VT Agronne Bedford MA Williams Providence RI Gill Derry NH McCaig Brattleboro VT Holland Lowell MA Patry Littleton MA Smith Concord NH Orlando Burlington MA Lewis Plymouth MA 12 records listed.
Working with U2 virtual fields against SQL Server 2008
This appendix provides some examples for working with UniVerse virtual fields against SQL Server 2008. In the UniVerse External Database Access (EDA) Reference, the virtual field mapping examples might work with DB2 or Oracle, but not for SQL Server.
Examples When creating a new EDA Map Schema, the EDA tool only maps the D-type fields, not virtual fields. The primary key field is set to ID DATA type and the other fields are set to DATA type.
Adding the FULLNAME virtual field to a schema map To create the schema map, add the FULLNAME virtual field to the CUSTOMER schema map. The FULLNAME virtual field will concatenate the first name with the last name. The type field can be defined as DATA or EXPRESSION. When the type is defined as a DATA type, the FULLNAME field will be physically created and part of the CUSTOMER.CUSTOMER table. The following code sample demonstrates the SQL syntax to create the CUSTOMER.CUSTOMER table:
CREATE TABLE CUSTOMER.CUSTOMER(FULLNAME VARCHAR(120), ID VARCHAR(20) NOT NULL, SAL VARCHAR(10), FNAME VARCHAR(24), LNAME VARCHAR(32), COMPANY VARCHAR(40), ADDR1 VARCHAR(60), ADDR2 VARCHAR(60), CITY VARCHAR(24), STATE VARCHAR(4), ZIP VARCHAR(60), PHONE VARCHAR(60), NONCONFORMING_FLAG SMALLINT, UNMAPPED_U2FIELD VARCHAR(MAX), PRIMARY KEY (ID))
When defined as an expression type, the FULLNAME field will be part of CUSTOMER.CUSTOMER_V view. The following code sample demonstrates the SQL syntax to create the CUSTOMER.CUSTOMER_V view:
CREATEVIEWCUSTOMER.CUSTOMER_V(FULLNAME, ID, SAL, FNAME, LNAME, COMPANY, ADDR1, ADDR2, CITY, STATE, ZIP, PHONE, NONCONFORMING_FLAG, UNMAPPED_U2FIELD) AS SELECT FNAME+' '+LNAME, CUSTOMER.ID, CUSTOMER.SAL, CUSTOMER.FNAME,
105 Chapter 3: EDA Replication Configuration tool
CUSTOMER.LNAME, CUSTOMER.COMPANY, CUSTOMER.ADDR1, CUSTOMER.ADDR2, CUSTOMER.CITY, CUSTOMER.STATE, CUSTOMER.ZIP, CUSTOMER.PHONE, CUSTOMER.NONCONFORMING_FLAG, CUSTOMER.UNMAPPED_U2FIELD FROM CUSTOMER.CUSTOMER CUSTOMER
Adding the UPCASELNAME virtual field to the schema map To update the schema map, add the UPCASE.LNAME virtual field to the CUSTOMER schema map. The UPCASE.LNAME virtual field will change the case of the last name to upper case using the SQL Server UPPER function. The type field can be defined as DATA or EXPRESSION. The following sample code demonstrates the SQL syntax to create the CUSTOMER.CUSTOMER_V view using the UPPER function.
CREATE VIEW CUSTOMER.CUSTOMER_V( UPCASE_LNAME, ID, SAL, FNAME, LNAME, COMPANY, ADDR1, ADDR2, CITY, STATE, ZIP, PHONE, NONCONFORMING_FLAG, UNMAPPED_U2FIELD) AS SELECT UPPER(LNAME), CUSTOMER.ID, CUSTOMER.SAL, CUSTOMER.FNAME, CUSTOMER.LNAME, CUSTOMER.COMPANY, CUSTOMER.ADDR1, CUSTOMER.ADDR2, CUSTOMER.CITY, CUSTOMER.STATE, CUSTOMER.ZIP, CUSTOMER.PHONE, CUSTOMER.NONCONFORMING_FLAG, CUSTOMER.UNMAPPED_U2FIELDFROMCUSTOMER.CUSTOMERCUSTOMER
Adding the UPCASE.LNAME virtual field to the schema map To update the schema map, add the UPCASE.LNAME virtual field to the CUSTOMER schema map. The UPCASE.LNAME virtual field will change the case of the last name to upper case using a newly created SQL Server CUSTOMER.XUPPERCASE function. The type field is defined as SCALAR. The following sample code demonstrates how to create a new CUSTOMER.XUPPERCASE function on SQL Server 2008:
CREATE FUNCTION CUSTOMER.XUPPERCASE(@LNAME VARCHAR(30)) RETURNS varchar(30) BEGIN RETURN (UPPER(@LNAME)) END
The following sample code demonstrates the SQL syntax on the EDA Schema Manager tool:
CREATE VIEW CUSTOMER.CUSTOMER_V( UPCASE_LNAME, ID, SAL, FNAME, LNAME, COMPANY, ADDR1, ADDR2, CITY, STATE, ZIP, PHONE, NONCONFORMING_FLAG, UNMAPPED_U2FIELD) AS SELECT CUSTOMER.XUPPERCASE(CUSTOMER.LNAME), CUSTOMER.ID, CUSTOMER.SAL, CUSTOMER.FNAME, CUSTOMER.LNAME, CUSTOMER.COMPANY, CUSTOMER.ADDR1, CUSTOMER.ADDR2, CUSTOMER.CITY, CUSTOMER.STATE, CUSTOMER.ZIP, CUSTOMER.PHONE, CUSTOMER.NONCONFORMING_FLAG, CUSTOMER.UNMAPPED_U2FIELD FROM CUSTOMER.CUSTOMER CUSTOMER
Adding the DESCRIPTION virtual field to the schema map To update the schema map, add the DESCRIPTION virtual field to the CUSTOMER schema map. The DESCRIPTION virtual field will retrieve the description information from the PRODUCTS.PRODUCTS table using the TRANS function. The type field is defined as TRANS. Note: The PRODUCTS.PRODUCTS table must first be created on SQL Server 2008, before you use the TRANS function. The DESCRIPTION field is a multivalue virtual field that is part of CUSTOMER.ORDERS_MV_V view. The following sample code demonstrates the SQL syntax:
CREATE VIEW CUSTOMER.ORDERS_MV_V(ID, ORDERS_MV_POS, DESCRIPTION, PRODID,
106 Working with U2 virtual fields against SQL Server 2008
SER_NUM, PRICE, BUY_DATE, PAID_DATE, SVC_PRICE, SVC_START, SVC_END, SVC_PAID_DATE) AS SELECT ORDERS_MV.ID, ORDERS_MV.ORDERS_MV_POS, VA2.DESCRIPTION, ORDERS_MV.PRODID, ORDERS_MV.SER_NUM, ORDERS_MV.PRICE, ORDERS_MV.BUY_DATE, ORDERS_MV.PAID_DATE, ORDERS_MV.SVC_PRICE, ORDERS_MV.SVC_START, ORDERS_MV.SVC_END, ORDERS_MV.SVC_PAID_DATE FROM CUSTOMER.ORDERS_MV ORDERS_MV LEFT OUTER JOIN PRODUCTS.PRODUCTS VA2 ON ORDERS_MV.PRODID = VA2.ID
After the CUSTOMER.ORDERS_MV_V view is created, it can be accessed on SQL Server 2008.
107 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Use the U2 Extensible Administration Tool (XAdmin) to administer UniData or UniVerse (U2) database server. After you become proficient with the standard interface, you can customize the tool by adding your own tasks. You can also contribute menus to call your own UniBasic or UniVerse BASIC programs. Getting started
Starting XAdmin
Before you can perform UniData or UniVerse administration tasks, you must start the U2 Extensible Administration Tool (XAdmin).
Prerequisites ▪ XAdmin must be installed on a Microsoft Windows computer that is on the same network as the computer that hosts UniData or UniVerse. ▪ UniData or UniVerse services must be running.
Procedure
From the Windows Start menu, click All Programs → Rocket U2 → Extensible Administration Tool.
Extensible Administration Tool (XAdmin) perspectives
The following example illustrates the default Extensible Administration Tool (XAdmin) perspective:
108 Extensible Administration Tool (XAdmin) perspectives
U2 Resource view The U2 Resource view contains information about each U2 account on the server to which you are connected. This information includes accounts, data files, dictionary files, UniBasic programs, UniVerse BASIC programs, XML/DB mapping files, and cataloged programs.
Admin Tasks view The Admin Tasks view is where you perform a variety of administrative tasks, such as managing licenses, managing files, and monitoring performance.
Properties view The Properties view displays the properties for each file, account, program, server, and resource available. Select a node in any view to see the properties for that node. The first time that you select a file in the Resource view, the file path and dictionary path information might show as "unknown" in the Properties pane. This behavior improves the initial loading of content in the U2 Resource view. To populate the file information, select another file and then reselect the original file.
109 Chapter 4: U2 Extensible Administration Tool (XAdmin)
U2 Dictionary view The U2 Dictionary view displays the dictionary information about the database files in the U2 Resource view. You can see data source information and view the structure of the file system from in this view. Managing U2 Audit Logging
Starting at 11.3.1, UniVerse is authorized for U2 Audit Logging. You must have a separate audit license for UniVerse to turn on U2 Audit Logging. After it is licensed, you cannot completely disable the audit subsystem. UniVerse always audits certain security related events. UniVerse ships with a default audit configuration, which has one active audit log file in the audit subdirectory of UVHOME, and, except for certain system security related events, no other events are enabled for auditing by default. When UniVerse is running, it is capable of writing to any one of three log destinations: ▪ hashed file ▪ sequential file
▪ syslog file (UNIX and Linux only) You can dynamically switch to a different destination without the need to restart UniVerse – the change is applied immediately to all UniVerse processes already started. The default log file type is the sequential file, which has the best overall U2 Audit Logging performance among the log file types. UniVerse ensures that the audit log files are valid and ready at startup. It loads the audit configuration into shared memory for use by other UniVerse processes.
Use the audman utility or XAdmin to control certain audit system behaviors, such as suspending and resuming active log files, clearing an audit log file, or notifying the uvsmm daemon to reload configuration data which takes effect immediately for existing and new UniVerse processes.
If the log file type is a hashed file, you can use query commands such as LIST, SELECT or SQL SELECT, to query the contents of the files. Any attempt to change the contents of these files through UniVerse is blocked.
Note: Care should be taken when deciding which events to audit. The more events and more objects (files, processes, users, and so on) you select to audit, the more impact on performance.
After you enable U2 Audit Logging, an event triggers the creation of a record in the audit log file. If you encrypt the file, read and query operations automatically decrypt the record. Writing to the hashed type audit log file is always a synchronous operation. UniVerse blocks the event triggering the UniVerse process until the audit log write completes. Writing to the sequential type audit log file is always an asynchronous operation. UniVerse resumes the normal UniVerse process as soon as the audit log record is put into the system memory buffer. When the log records are physically written to the sequential log file depends on system activities and audit configuration. If a write error happens for any reason, the operation either proceeds or stops, depending on the configuration. For detailed information about U2 Audit Logging, see UniVerse Security Features.
Configuring U2 Audit Logging
You can access the configuration settings of the audman utility in XAdmin. From the Admin Task list, double-click Audit Configuration. The Audit Configuration pane opens.
110 Managing disk space
Managing disk space
The Disk Space tool enables you to view statistics on a U2 file system's current disk space usage, helping you gauge whether the file system is working optimally—or is overloaded, or is allocated too much space. The total amount of disk space available, the amount of free space, and the percentage of disk space currently in use are all factors that help you determine whether to make adjustments.
Viewing disk space usage
To determine whether a file system needs space adjustments, you can view statistics on disk space usage. 1. From the Admin Tasks view, select Disk Space. 2. From the Block Size options, select a block size for expressing units of disk space: 512 bytes or 1024 bytes. The default is 1024 bytes. 3. To view statistics on disk space usage for U2 file systems, check information in the grid: File System lists the full path of each U2 file system. Total Size displays the total amount of disk space allocated to the file system. Free Space displays the remaining amount of disk space available for use by the file system. % in Use displays the percentage of total disk space currently in use by the file system. 4. Optional: To sort the data for all U2 file systems in the list, click any column heading to sort on that column. 5. Optional: To filter the results, in the Filters field above any column, select an operator (=, >, or <) from the drop-down list and enter a string in the associated field. 6. Optional: To refresh the results with current disk space usage data, click Refresh.
111 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Managing Secure Sockets Layer (SSL)
To use the Secure Sockets Layer (SSL) protocol, you must perform some initial setup to create certificates and configure SSL for the U2 server. You can set up and manage SSL certificates and configuration details on an ongoing basis using the editor tool inside XAdmin. ▪ Generating certificate signing requests, on page 112 ▪ Generating SSL certificates, on page 115 ▪ Creating security context records, on page 119 ▪ Configuring SSL for U2 servers, on page 129
Generating certificate signing requests
Before you can obtain or create an SSL certificate, you must generate an X.509-compliant certificate signing request (CSR) containing a digital signature. You can send the CSR to a third-party certificate authority (CA) to obtain a certificate, or use the CSR as input to generate a certificate with the wizard in XAdmin.
Starting the Generate Certificate Signing Request wizard
The Generate Certificate Signing Request wizard leads you through the process of generating a CSR. You can start the wizard from the editor view.
Procedure
1. To open the Configure SSL for Servers editor, in the Admin Tasks list, double-click SSL Configuration. 2. In the Configure SSL for Servers editor, click the Certificate Signing Request tab. 3. To start the Generate Certificate Signing Request wizard, click Generate a Certificate Request. The Generate Certificate Signing Request dialog box contains an introduction to this task. 4. To continue, click Next.
Specifying a file and algorithm for the CSR
In this child task of generating a certificate signing request, you can specify the file to contain the CSR and select the algorithm to use in generating the digital signature for the CSR.
Procedure
1. In the Certificate Signing Request File field, enter the full path of the operating system-level file to contain the certificate signing request, or click Browse to search for the file location. 2. From the Digest Algorithm options, select the algorithm to use to generate the digital signature for the certificate signing request: ▪ SHA1 – SHA1 cryptographical hash function ▪ SHA224 — SHA2 cryptographical hash function (available for UniData 8.1 or later and UniVerse 11.2.4 or later) ▪ SHA256 — SHA2 cryptographical hash function (available for UniData 8.1 or later and UniVerse 11.2.4 or later)
112 Defining properties of the CSR
▪ SHA384 — SHA2 cryptographical hash function (available for UniData 8.1 or later and UniVerse 11.2.4 or later) ▪ SHA512 — SHA2 cryptographical hash function (available for UniData 8.1 or later and UniVerse 11.2.4 or later) ▪ MD5 – MD5 cryptographical hash function 3. To continue, click Next.
Defining properties of the CSR
In this child task of generating a certificate signing request, you can enter required and optional properties to define the CSR.
Procedure
1. In the Request Properties dialog box, from the C (Country Code) list, select the two-letter code for the country in which the requesting organization is located. 2. Optional: In the ST (Province) field, enter the full name of the state or province of the organization requesting the SSL certificate. Example: Massachusetts. 3. Optional: In the L (Locality) field, enter the full name of the city or locality of the requesting organization. Example: Newton. 4. In the O (Organization) field, enter the full legal name of the company or person requesting the certificate, as legally registered in the locality. Example: Rocket Software, Inc. 5. Optional: In the OU (Organization Unit) field, enter the name of the requesting business unit or branch within the organization. Example: Information Technologies 6. In the CN (Common Name) field, enter the fully qualified domain name for which you are requesting the certificate. 7. Optional: In the Email field, enter the e-mail address of the primary contact requesting the certificate. 8. To continue, click Next.
Selecting a key pair option
In this child task of generating a certificate signing request, you can choose to use an existing key pair or generate a new key pair for the CSR.
Procedure
1. In the Key Pair Selection dialog box, select one of the following key pair options: ▪ Use existing key pair ▪ Generate new key pair 2. To continue, click Next.
Supplying key pair parameters
The tool needs several pieces of information to generate a new key pair or find an existing key pair.
113 Chapter 4: U2 Extensible Administration Tool (XAdmin)
About this task In this child task of generating a certificate signing request, you will either: ▪ Select the format and private key file of an existing key pair, or ▪ Select the parameters required to generate a new key pair.
Procedure
1. In the Key Pair Info dialog box, from the Key Algorithm options, select the algorithm to use to generate a new key pair or select the algorithm that was used to generate an existing key pair: ▪ RSA – RSA key algorithm ▪ DSA – Digital signature algorithm 2. The Key Length list is enabled only if you selected the Generate new key pair option in the previous task. From this list, select the length of the key in bits. Key length is the primary measure of the cryptographic strength of the key. Valid values are multiples of 64, ranging from 512 to 16384.
Note: The larger the key length, the longer it takes to create the key. For example, a key length of 16384 can take up to ten minutes to create. Specify a minimum length of 2048.
3. From the Key File Format options, select the format for private and public key files: ▪ PEM – Privacy Enhanced Mail format ▪ DER – Distinguished Encoding Rules format 4. The Parameter File field is enabled only if you selected DSA as the Key Algorithm option. ▪ For a new key pair, enter the full path of an existing parameter file, or click Browse to search for the file location. The UniData or UniVerse (U2) data server uses the selected parameter file to generate the key pair. If you leave this field blank, the U2 database server uses its default parameters table to generate the key pair. ▪ For an existing key pair, enter the full path or browse for the parameter file that was used to generate the key pair. 5. In the Private Key File field, enter the name of the file to contain the private key, or click Browse to search for an existing private key file. 6. The Public Key File field is enabled only if you selected the Generate new key pair option in the previous task. In this field, enter the name of the file to contain the public key, or click Browse to search for an existing public key file. 7. To continue, click Next.
Entering a password for the private key file
The private key file must be password-protected to maintain its security.
About this task In this child task of generating a certificate signing request, you will: ▪ Enter the password previously established for an existing private key file, or ▪ Create a password for a new private key file.
114 Verifying the status of generating the certificate
Procedure
1. In the Password for Private Key field, enter the password for the private key file. XAdmin does not enforce password length or strength rules on this password; however, as a best practice, create a strong password to protect the private key. 2. In the Confirm Password field, enter the password again for verification. The wizard now has all the information required to generate the certificate signing request file. 3. To generate the CSR file, click Next. Otherwise, to review selections or make changes, click Back.
Verifying the status of generating the certificate
In this child task of generating an SSL certificate, you can check the status message to see whether the certificate was generated successfully. If it was not, you can go back to make corrections.
Procedure
1. In the Review Status and Finish dialog box, check the message indicating the status of generating the certificate. If the certificate was created successfully, the dialog box contains the following message: Certificate was generated successfully. If the process did not generate a certificate, the dialog box contains the following message: Failed to create certificate. To return to previous dialog boxes and correct the error, click Back. 2. To close the Generate SSL Certificate wizard and return to the Configure SSL for Servers editor, click Finish.
Generating SSL certificates
Using a wizard, you can create three types of X.509 SSL certificate: A certificate is used to bind the name of an entity with its public key. It is used as a means of distributing a public key. A certificate always contains three pieces of information: ▪ Name ▪ Public key ▪ Digital signature signed by a trusted third party, called a certificate authority (CA), with its private key If you have the public key of the CA (contained in the CA certificate), you can verify that the certificate is authentic. SSL protocol specifies that when two parties start a handshake, the server must send its certificate to the client for authentication. It may also require the client to send its certificate to the server for authentication. U2 servers that act as HTTP clients are not required to maintain a client certificate. U2 applications that act as SSL socket servers must install a server certificate. UniObjects for Java servers and Telnet servers also require a server certificate. There can be only one server/client certificate per security context record. Adding a new certificate automatically replaces an existing certificate. However, for issuer certificates, the U2 data server chains a new certificate with existing certificates so U2 applications can perform chained authentication.
115 Chapter 4: U2 Extensible Administration Tool (XAdmin)
If the issuer certificate is in PEM format, it can contain multiple certificates by concatenating certificates together. All certificates that form an issuer chain must be of the same type. ▪ Self-signed root certificate ▪ Intermediate CA certificate ▪ Server or client certificate You can also use the wizard to view the details of existing SSL certificates stored on the computer.
Starting the Generate SSL Certificate wizard
The Generate SSL Certificate wizard leads you through the process of generating or viewing an SSL certificate. You can start the wizard from the editor view.
Procedure
1. To open the Configure SSL for Servers editor, in the Admin Tasks list, double-click SSL Configuration. 2. In the Configure SSL for Servers editor, click the Certificate tab. 3. To start the Generate SSL Certificate wizard, click Generate a Certificate. The Generate SSL Certificate dialog box contains an introduction to this task. 4. To continue, click Next.
Specifying a certificate file name
In this child task of generating an SSL certificate, you can specify the name for a new certificate file. Alternatively, you can use the wizard to select the name of an existing certificate file and view its details.
Procedure
1. In the Certificate File field, enter a unique name or full path for a new certificate file, or click Browse to search for the location of an existing certificate file. 2. The appropriate action in this step depends on whether you entered a new file name or selected an existing file name. ▪ To continue with creating a new certificate, click Next. ▪ To view the details of an existing certificate, click Show. When you finish viewing the certificate details, you can close the wizard and perform another task.
Setting the validity period for a new certificate
An SSL certificate is valid only for a specified time period. In this child task of generating an SSL certificate, you will set the number of days for which the new certificate is valid.
Procedure
1. From the Validity Period list, select the number of days for which the new SSL certificate is to be valid. The certificate is valid starting from the current date until the specified number of days elapses. The default value is 365 days.
116 Selecting a certificate type
2. To continue, click Next.
Selecting a certificate type
An X.509 SSL certificate can be one of three types, depending on the purpose it serves. In this child task of generating an SSL certificate, you can select the type of certificate to create.
Procedure
1. From the Certificate Type options, select the type of SSL certificate to create: ▪ Self-signed root certificate ▪ Intermediate CA certificate ▪ Server/Client certificate 2. From the Signing Algorithm options, select a signing algorithm. The default selection is SHA1. ▪ SHA224 ▪ SHA256 ▪ SHA384 ▪ SHA512 ▪ SHA1 ▪ MD5 3. To continue, click Next.
Next step The next step depends on the certificate type you selected: ▪ Self-signed root certificate: Selecting the private key file of the CSR, on page 118 ▪ Intermediate CA certificate or Server/Client certificate: Optional: Defining certificate extensions, on page 117
Optional: Defining certificate extensions
Extensions can be used to further define the purpose or provide identifiers for an intermediate CA certificate or server/client certificate. In this child task of creating a certificate of either type, you have the option of defining relevant certificate extensions.
Procedure
1. In the X.509 v3 Certificate Extensions dialog box, select the check box for each certificate extension that you want to define for the new certificate: ▪ Subject Alt Name – The subject alternative name extension allows additional identities to be bound to the subject of the certificate. ▪ Key Usage – This extension defines the purpose of the key contained in the certificate and can be used to put certain restrictions on key usage. ▪ Basic Constraints – This extension indicates whether the subject of the certificate is a certificate authority (CA).
117 Chapter 4: U2 Extensible Administration Tool (XAdmin)
▪ Subject Key Identifier – This extension provides a means of identifying certificates that contain a particular public key. ▪ Authority Key Identifier – This extension identifies the public key corresponding to the private key used to sign the certificate. When you select an extension, help text for that extension is displayed in the lower half of the dialog box, along with the relevant options for defining the extension. If no extensions are relevant, leave all check boxes cleared. 2. To continue, click Next.
Selecting required files to generate a certificate
Selecting the private key file of the CSR
A private key was used to generate the certificate signing request (CSR) you selected in a previous step. In this child task of creating a self-signed root certificate, you will select the private key file of the CSR associated with the new certificate.
Prerequisites Selecting a certificate type, on page 117
Procedure
1. In the Private Key File field, enter the full path of the private key file used to generate the certificate signing request associated with the new certificate, or click Browse to search for the file location. 2. To continue, click Next.
Next step Entering the password for the private key file, on page 119
Selecting the signing certificate file and private key file
In this child task of creating an SSL certificate, you will select the signing certificate file to use in signing the new certificate and the private key file of the signing certificate.
About this task Two files are required as input to generate an intermediate CA certificate or server/client certificate: ▪ A signing certificate file to use in signing the new SSL certificate. ▪ A private key file that was used to generate the signing certificate file.
Prerequisites Optional: Defining certificate extensions, on page 117
118 Entering the password for the private key file
Procedure
1. In the Signing Certificate File field, enter the full path of the certificate file to use in signing the new certificate, or click Browse to search for the file location. 2. In the Private Key File field, enter the full path of the private key file that was used to generate the signing certificate file, or click Browse to search for the file location. 3. To continue, click Next.
Next step Entering the password for the private key file, on page 119
Entering the password for the private key file
A private key file is password-protected. In this child task of generating an SSL certificate, you will enter the password for the private key file you selected in the previous step.
Prerequisites The prerequisite task depends on the type of certificate you are creating: ▪ Self-signed root certificate:Selecting the private key file of the CSR, on page 118 ▪ Intermediate CA certificate or Server/Client certificate: Selecting the signing certificate file and private key file, on page 118
Procedure
1. In the Password for Private Key field, enter the password for the private key file selected in the previous step, as follows: ▪ For a Self-signed root certificate, enter the password for the private key file used to generate the certificate signing request file. ▪ For an Intermediate CA certificate or Server/Client certificate, enter the password for the private key file used to generate the signing certificate file. 2. In the Confirm Password field, reenter the password for verification. The wizard now has all the information required to generate the certificate. 3. To generate the new certificate, click Next. Otherwise, to review selections or make changes, click Back.
Next step Verifying the status of generating the certificate, on page 115
Creating security context records
A security context record (SCR) is a data structure that holds the security properties that the application associates with a secured connection. The Security Context Record wizard leads you through the steps of creating or modifying an SCR, which the application requires for secured communication through SSL.
119 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Starting the Security Context Record wizard
The Security Context Record wizard leads you through the procedure of creating a new security context record (SCR). You can start the wizard from the editor view.
Prerequisites Generating SSL certificates, on page 115
Procedure
1. To open the Configure SSL for Servers editor, in the Admin Tasks list, double-click SSL Configuration. 2. In the Configure SSL for Servers editor, select the Security Context Record tab. 3. From the SCR Database list, select the database account in which to create or view the security context record. The full path of the selected database account is populated in the Path field.
Note: If the database account you want to use is not shown in the list, you can add it using the XAdmin Accounts option, as described in Creating U2 accounts, on page 19.
Note: When creating a new Security Context Record for the first time, you could get the following error:
Failed to Open File … _SECUCTX_ or &SECUCTX&. If you receive the previous error message, manually create a file for UniData called _SECUCTX_ or &SECUCTX& for UniVerse.
4. To start the Security Context Record wizard, click Add. The Security Context Record (SCR) dialog box contains an introduction to the task of creating an SCR. Make sure you have generated the necessary keys and certificates before proceeding. 5. To continue, click Next.
Specifying the record ID and protocol
A unique record ID is used to identify each security context record (SCR), and one of several transport layer protocols can be used to generate the SCR. In this child task of creating a security context record, you will assign a record ID to the SCR and select the protocol to use in generating the new SCR.
Procedure
1. In the Security Context Record ID field, enter a unique ID for the security context record. 2. From the SSL/TLS Version list, select the appropriate transport layer protocol version to use in generating the security context record. Valid versions are: ▪ SSLv2 ▪ SSLv3 ▪ TLSv1 ▪ TLSv1.2 (available for UniData 8.1 or later or UniVerse 11.2.4 or later) ▪ TLSv1.2 (available for UniData 8.1 or later or UniVerse 11.2.4 or later)
120 Selecting server or client usage
Tip: For increased security, select TLSv1.2 or TLSv1. Use of either protocol is recommended as a best practice.
3. To continue, click Next.
Selecting server or client usage
Either a server or a client accesses the security context record (SCR) to get the properties to associate with a secured connection. In this child task of creating a security context record, you will select an option indicating whether the new SCR is to be used by a server or a client.
Procedure
1. From the SCR Usage Type options, select an option indicating how the security context record is to be used: ▪ SCR for server – The security context record is to be used by a server ▪ SCR for client – The security context record is to be used by a client 2. To continue, click Next.
Setting authentication properties
The server or the client must authenticate the validity of certificates during handshake negotiations. In this child task of creating a security context record, you will set the parameters that the server or the client uses to authenticate certificates.
Procedure
▪ For an SCR for server, go to Setting server authentication properties, on page 121. ▪ For an SCR for client, go to Setting client authentication properties, on page 122.
Setting server authentication properties With an SCR for server, the server must verify the validity of incoming certificates during handshake negotiations. In this child task of creating a security context record, you will set the parameters that the server uses to authenticate certificates.
Prerequisites Selecting server or client usage, on page 121
Procedure
1. In the Server Authentication Properties dialog box, from the Authentication Depth list, select a value to indicate the level of verification the UniData or UniVerse (U2) database server is to perform before determining that a certificate is not valid. Depth is the maximum number of intermediate issuer certificates, or CA certificates, the U2 database server must examine while verifying an incoming certificate. A depth of 0 indicates that the certificate must be self-signed. A depth of 1 means that the incoming certificate can be either self-signed or signed by a CA known to the security context record. The default value is 3. 2. Optional: In the Trusted Peer Names field, you can add one or more trusted peer names, as explained here.
121 Chapter 4: U2 Extensible Administration Tool (XAdmin)
The U2 database server uses this list of peer names to determine whether to trust a peer in handshake negotiations. Trusted server/client names are stored in the security context record. If no trusted peer name is set, any peer is considered legitimate. To add trusted peer names, click Add. For steps, go to Adding trusted peer names, on page 123. 3. From the Authentication Strength options, select the level of security to be used in the authentication process: ▪ Generous – The certificate need only contain the subject name (common name) that matches one specified by “PeerName” to be considered valid. ▪ Strict – The incoming certificate must pass a number of checks, including signature check, expiry check, purpose check, and issuer check.
Tip: Use the Generous option for development or testing purposes only, and the Strict option for any other purpose.
4. If the server is to use client authentication during the handshake, select the Client Authentication check box. With this check box selected, the server sends a client authentication request to the client during the initial handshake. The server also receives the client certificate and performs authentication according to the issuer’s certificate (or certificate chain) set in the security context record. 5. To continue, click Next.
Next step Selecting the certificate path rule, on page 123
Setting client authentication properties With an SCR for client, the client must verify the validity of certificates during handshake negotiations. In this child task of creating a security context record, you will set the parameters that the client uses to authenticate certificates.
Prerequisites Selecting server or client usage, on page 121
Procedure
1. In the Client Authentication Properties dialog box, from the Authentication Depth list, select a value to indicate the level of verification the client is to perform before determining that a certificate is not valid. Depth is the maximum number of intermediate issuer certificates, or CA certificates, the client must examine while verifying an incoming certificate. A depth of 0 indicates that the certificate must be self-signed. A depth of 1 means that the incoming certificate can be either self-signed or signed by a CA known to the security context record. The default value is 3. 2. Optional: In the Trusted Peer Names field, you can add one or more trusted peer names, as explained here. The client uses this list of peer names to determine whether to trust a peer in handshake negotiations. Trusted server/client names are stored in the security context record. If no trusted peer name is set, any peer is considered legitimate. To add trusted peer names, click Add. For steps, go to Adding trusted peer names, on page 123.
122 Adding trusted peer names
3. From the Authentication Strength options, select the level of security to be used in the authentication process:
Note: Use the Generous option for development or testing purposes only, and the Strict option for any other purpose.
The Client Authentication check box is not applicable to an SCR for client, so it is unavailable in this client dialog box. 4. To continue, click Next.
Next step Selecting the certificate path rule, on page 123
Adding trusted peer names The U2 database server client uses a list of peer names to determine whether to trust a peer in handshake negotiations. Trusted server/client names are stored in the security context record. In this child task of setting authentication properties, you can add the names of trusted peers.
Prerequisites The prerequisite task depends on the authentication method you selected: ▪ Server authentication: Setting server authentication properties, on page 121 ▪ Client authentication: Setting client authentication properties, on page 122
Procedure
1. In the Peer Name field, enter one or more trusted peer names in a comma-separated list.
Note: The trust names can be either fully specified names like [email protected], or wildcard names. There are two wildcard characters: ‘%’ can be used to match ANY character strings, while ‘_’ (underscore) can be used to match a single character. For example, %@us.xyz.com matches both [email protected] and [email protected].
2. To save the changes and return to the parent task, click OK.
Selecting the certificate path rule
When loading a certificate to establish an SSL connection, the UniData or UniVerse (U2) database server retrieves the certificate from its registered full path by default. In this child task of creating a security context record, you can select a certificate path rule to specify the default path or an alternative location in which to search for certificates.
Prerequisites Setting authentication properties, on page 121
Procedure
1. From the Certificate Path Rule options, select a certificate path rule to specify the search path: ▪ Default – When you add a certificate to a security context record, the full path for that certificate is registered in the security context record. This path is derived from the current
123 Chapter 4: U2 Extensible Administration Tool (XAdmin)
directory in which U2 is running. When the certificate is loaded into memory to establish the SSL connection, the U2 database server by default uses the registered full path to retrieve the certificate. ▪ Relative – With this option, the U2 database server looks for the certificate in the current directory in which U2 is running. Be aware that some processes, such as the Telnet server, run from the system directory. ▪ Path – With this option, the U2 database server uses the path you specify here to load the certificate. You can enter either an absolute path or a relative path, or click Browse to search for the path. ▪ Env – If you select this option, enter an environment variable name in the Env field. With this option, the U2 process first obtains the value of the environment variable you specify, and then uses that value as the path to load the certificate. The U2 database server evaluates the environment variable only when the first SSL connection is made. The value is cached for later reference. 2. To continue, click Next.
Associating certificates to the security context
A certificate is used to bind the name of an entity with its public key. It is used as a means of distributing a public key. A certificate always contains three pieces of information: ▪ Name ▪ Public key ▪ Digital signature signed by the private key of a trusted third party, called a certificate authority (CA) If you have the public key of the CA (contained in the CA certificate), you can verify that the certificate is authentic. SSL protocol specifies that when two parties start a handshake, the server must send its certificate to the client for authentication. It may also require the client to send its certificate to the server for authentication. U2 servers that act as HTTP clients are not required to maintain a client certificate. U2 applications that act as SSL socket servers must install a server certificate. UniObjects for Java servers and Telnet servers also require a server certificate. There can be only one server/client certificate per security context record. Adding a new certificate automatically replaces an existing certificate. However, for issuer certificates, the U2 data server new certificate to existing certificates so that U2 applications can perform chained authentication. If the issuer certificate is in PEM format, it can contain multiple certificates by concatenating certificates together. All certificates that form an issuer chain must be of the same type.
Associating server/client certificates to a security context You can select an existing certificate to associate to the security context. This certificate is used as either the server certificate or the client certificate in handshake negotiations.
Procedure
▪ For an SCR for servers, go to Associating a server certificate to a security context, on page 125. ▪ For an SCR for clients, go to Optional: Associating a client certificate to a security context, on page 125.
124 Associating a server certificate to a security context
Associating a server certificate to a security context When you use an SCR for server, the server sends its certificate to the client in handshake negotiations. In this child task of creating a security context record, you can load a server certificate to the security context. Only one server certificate can be associated with a security context. If you add a new certificate, it automatically replaces an existing certificate.
Prerequisites Selecting the certificate path rule, on page 123
Procedure
1. In the Server Certificate File field, enter the full path of the file containing the server certificate, or click Browse to search for the file location. 2. From the Certificate File Format options, select the file format for the server certificate: ▪ PEM – Base64 encoded format ▪ DER – ASN.1 binary format ▪ PKCS #12 – Public-Key Cryptography Standards format 3. To continue, click Next.
Next step Selecting the private key file for the server or client certificate, on page 126
Optional: Associating a client certificate to a security context When you use an SCR for client, the client may be requested to send its certificate to the server in handshake negotiations. In this child task of creating a security context record, you can associate a client certificate to the security context. Only one client certificate can be associated with a security context. If you add a new certificate, it automatically replaces an existing certificate.
Prerequisites Selecting the certificate path rule, on page 123
Procedure
1. In the Client Certificate File field, enter the full path of the file containing the client certificate, or click Browse to search for the file location. 2. From the Certificate File Format options, select the file format for the client certificate: ▪ PEM – Base64 encoded format ▪ DER – ASN.1 binary format ▪ PKCS #12 – Public-Key Cryptography Standards format 3. To continue, click Next.
Next step Selecting the private key file for the server or client certificate, on page 126
125 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Selecting the private key file for the server or client certificate A private key file protects the security of the server or client certificate. In this child task of associating a server or client certificate to a security context record, you can select the private key file of the selected server or client certificate.
Prerequisites Associating a server certificate to a security context, on page 125 or Optional: Associating a client certificate to a security context, on page 125
Procedure
1. In the Private Key File field, enter the full path of the file that contains the private key associated with the server or client certificate, or click Browse to search for the file location. 2. In the Password for Private Key field, enter the password for the private key file. 3. In the Confirm Password field, reenter the password for verification. 4. From the Private Key Format options, select the format of the private key file: ▪ PEM – Base64 encoded format ▪ DER – ASN.1 binary format ▪ PKCS #12 – Public-Key Cryptography Standards format 5. To continue, click Next.
Optional: Associating CA certificates to a security context record A certificate authority (CA) certificate is used to sign other certificates. If a CA certificate is associated to a security context, it can be used to verify incoming certificates. In this optional child task of creating a security context record, you can associate one or more CA certificates to the security context.
Procedure
1. In the CA Certificates dialog box, click Add. 2. The Add CA Certificate dialog box allows you to associate CA certificates to the security context, one at a time. In the Certificate File field, enter the full path of the CA certificate file, or click Browse to search for the file location. 3. From the Format options, select the format of the CA certificate: ▪ PEM – Base64 encoded format ▪ DER – ASN.1 binary format ▪ PKCS #12 – Public-Key Cryptography Standards format 4. To add the CA certificate to the security context, click OK. The full path of the selected CA certificate is populated in the CA Certificates dialog box. 5. Repeat steps 1-4 for each CA certificate to be added to the security context. 6. To continue, click Next.
Selecting or generating a random file
The UniData or UniVerse (U2) database server uses a random (.rnd) file to perform every secured operation, from generating keys to creating certificates and certificate signing requests. In this child task of creating a security context record, you can select a random file or generate a new random file to associate to the security context.
126 Optional: Generating a random file
Procedure
1. In the Random File dialog box, use one of the following three methods to select or generate a random file for use in the security context:
▪ By default, the U2 database server uses the random (.rnd) file in the current account. To use the default random file, leave the Random File field blank.
Tip: The strength of cryptographic functions depends on the true randomness of keys. As a rule, the default random file in the current account is the best means to achieve a secure environment.
▪ To use an alternative random file, in the Random File field enter the full path of an existing random file, or click Browse to search for the file location. ▪ Otherwise, to generate a new random file from seed source files, click New Random File. Go to Optional: Generating a random file, on page 127. 2. To continue, click Next.
Next step Optional: Specifying ciphers, on page 128
Optional: Generating a random file In some cases, you can choose not to associate the default random file or an existing random file to the security context. Alternatively, you can build a new random file from scratch. In this optional child task of creating a security context record, you can generate a new random file from seed source files.
Remember: The strength of cryptographic functions depends on the true randomness of keys. As a rule, the default .rnd file in the current account is the best means to achieve a secure environment.
Procedure
1. In the File Name field, enter a name for the new random file, or click Browse to select the file location. 2. From the File Length list, select a file length for the new random file. 3. In the Random Seed Source Files box, populate a list of one or more seed source files to use in generating the new random file. To select a file, click Add. Go to Adding seed source files, on page 127. 4. Repeat step 3 for each seed source file to be added. 5. When you have finished adding seed source files, click OK. The Random File dialog box is redisplayed. The name of the newly generated random file is populated in the Random File field.
Adding seed source files A seed source file contains the data used to generate random keys. In this child task of generating a random file, you can select one or more seed source files.
127 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Procedure
1. In the File Name field, enter the full path of a file to be used as a seed source file in generating the new random file, or click Browse to search for the seed source file location. 2. To continue, click OK. The New Random File dialog box is redisplayed. The selected random seed source file is populated in Random Seed Source Files list.
Optional: Specifying ciphers
The cipher parameters determine which cipher suites and public key algorithms are supported during the handshake and subsequent data exchanges in the security context. In this child task of creating a security context record, you can specify the ciphers to associate to the security context.
Prerequisites Selecting or generating a random file, on page 126
Procedure
1. In the Ciphers field, enter the CipherSpecs parameter for the cipher suite to use in the security context. The CipherSpecs parameter is a string containing cipher-spec separated by colons. An SSL cipher specification in cipher-spec is composed of four major attributes and several less significant attributes. For detailed information about cipher specifications, see UniData or UniVerse Security Features.
Note: The security context's cipher suites are set automatically to SSLv3 suites supported by the SSL version you selected.
2. To continue, click Next.
Optional: Specifying a certificate revocation list
A certificate revocation list (CRL) is a list of the serial numbers of certificates that have been revoked. In this child task of creating a security context record, you can select one or more files containing a certificate revocation list to use in the security context.
Procedure
1. In the Certificate Revocation List dialog box, populate the list with one or more certificate revocation files to use in the security context. To select a file, click Add. Go to Optional: Specifying a certificate revocation list, on page 128. 2. Repeat step 1 for each certificate revocation file to be added. 3. To continue, click Next.
Setting a password for the SCR
A security context record (SCR) must be password-protected to safeguard its security. In this child task of creating a security context record, you can set a password for the SCR.
128 Verifying the status of generating the SCR
Procedure
1. In the Password for SCR field, enter a password for the security context record. 2. In the Confirm Password field, enter the password again for verification. 3. To create the security context record, click Next.
Verifying the status of generating the SCR
In this child task of generating a security context record, you can check the status message to see whether the SCR was generated successfully. If it was not, you can go back to make corrections.
Procedure
1. In the Review Status and Finish dialog box, check the message indicating the status of generating the security context record. If the security context record was created successfully, the dialog box contains the following message: SCR record was added/updated successfully. If the process did not generate an SCR, the following message is displayed: Failed to save SCR To return to previous dialog boxes and correct the error, click Back. 2. To close the Security Context Record wizard and return to the Configure SSL for Servers editor, click Finish.
Configuring SSL for U2 servers
A security context record contains all SSL-related properties necessary for the UniData or UniVerse (U2) server to establish a secured connection with an SSL client. After creating a security context record, you can configure SSL for a U2 server to process requests by various U2 clients, including UniObjects (UO), UniObjects for Java (UOJ), ODBC, OLEDB, wIntegrate, and others. In this child task of configuring SSL for U2 servers, you can configure a UniData or UniVerse (U2) database server for a selected security context record (SCR).
Prerequisites Creating security context records, on page 119
Procedure
1. To open the Configure SSL for Servers editor, in the Admin Tasks list, double-click SSL Configuration. 2. From the Service Name list, select the name of the U2 service for the U2 database server. 3. From the SCR Database list, select the account where the security context record will be stored. 4. In the Path field, verify that the path to the account it correct. 5. From the SCR Record list, select the security context record for this SSL configuration entry. 6. In the Password Seed field, enter the password for this SSL context record. 7. In the Confirm Password field, enter the password again for verification. 8. Click OK. The new configuration record is listed in the Server Configuration tab of the Configure SSL for Servers editor.
129 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Note: When creating a new Security Context Record for the first time, you may get the following error, Error = Failed to open file … _SECUCTX_ or &SECUCTX&. You will need to manually create file on UniData called _SECUCTX_ or on UniVerse called &SECUCTX&.
FIPS mode support
The Federal Information Processing Standard (FIPS) Publication 140-2 is a United States Federal Government computer security standard used to accredit cryptographic modules. FIPS 140-2 support is essential for a software product to be eligible for procurement by U.S. Federal Government agencies, as well as other government and non-government entities. Starting at UniVerse 11.3.1, U2 uses an embedded FIPS 140-2-validated cryptographic module from OpenSSL under certificate #1747, per FIPS 140-2 Implementation Guidance, section G.5 guidelines. When properly configured, UniVerse servers perform all their crypto-operations through the OpenSSL FIPS module. This applies to U2 servers running on UNIX, Linux, and Windows platforms. FIPS mode enforcement can be effectively done by U2 servers. However, under certain circumstances (for example, a strict audit or compliance requirement), client applications may be required to enforce FIPS mode as well. For U2 clients using UniObjects, ODBC, or wIntegrate, the FIPS_MODE registry value can be used to enforce FIPS mode. The FIPS_MODE value is located in the HKLM \Software\Wow6432Note\Rocket Software\UniClient directory and is created by the client installation procedure. The default value is 0 and has FIPS mode turned off. To turn on FIPS mode, change the value to 1. Managing automatic data encryption
Automatic data encryption (ADE) secures data at rest. The ADE model hinges on a password-protected master key, which it employs in all encryption operations. It uses the master key to derive encryption keys, which are used to encrypt and decrypt the content of U2 data files and index files. When encrypting a file, you must associate an encryption key and an encryption algorithm for each object to encrypt. ADE gives you the ability to encrypt an entire record or just specified fields in the record. The U2 server automatically encrypts data when it writes records to a U2 file. It automatically decrypts data when it reads records from a U2 file. The data read and write operations may be initiated directly by the U2 server or through UniBasic or UniVerse BASIC commands. The U2 automatic data encryption feature supports Federal Information Processing Standards (FIPS) encryption algorithms, including Data Encryption Standard (DES) and Advanced Encryption Standard (AES) algorithms. ADE uses these industry-standard algorithms to produce strong encryption keys that protect the content of U2 data stores. ADE has many advantages, but be aware that it adds to system overhead. When using automatic data encryption, system performance might decrease somewhat due to encryption operations, and more disk space might be required. However, the benefits of securing data at rest in most cases outweigh the disadvantages.
Administering data encryption
The Data Encryption tools inside XAdmin assist you with creating keys, encrypting and decrypting files, managing the key store, setting password policies, and performing associated tasks to administer day- to-day data encryption activities.
130 Managing encryption keys
Managing encryption keys
Automatic data encryption (ADE) uses encryption keys to encrypt, decrypt, and re-encrypt individual U2 files. Encryption keys are derived from a master key. Therefore, the security of the encryption keys requires that the master key is password protected and safely stored. Using the Keys tool inside the Data Encryption editor, you can create and delete encryption keys, view details of encryption keys, grant or revoke user and group access to keys, and change passwords for keys.
About this task All tasks associated with managing encryption keys are performed in the Keys tool of the Data Encryption editor. Opening the Keys tool is the starting point of all encryption key tasks.
Procedure
1. To open the Data Encryption editor, in the Admin Tasks list, double-click Data Encryption. 2. In the Data Encryption editor, click the Keys tab. The Keys tab opens and displays all existing encryption keys in the left pane. Details of the selected encryption key are shown in the right pane. Check the details for the selected encryption key in the right pane, as follows: ▪ Key Name displays the unique name of the selected encryption key. ▪ Creator contains the user ID of the person who created the encryption key. ▪ Date Created displays the month, day, and year (MM/DD/YYYY) on which the encryption key was created. ▪ Time Created displays the time (HH:MM am|pm) at which the encryption key was created. ▪ Date Password Changed displays the month, day, and year (MM/DD/YYYY) on which the password for the encryption key was last updated. If the key is not password-protected, this field contains the date on which the encryption key was created. ▪ Time Password Changed displays the time (HH:MM am|pm) at which the password for the encryption key was last updated. If the key is not password-protected, this field contains the time at which the encryption key was created. ▪ Grantees lists the names of users and groups who are granted access to the encryption key. ▪ References lists the U2 files and fields that reference the selected encryption key.
Creating encryption keys (XAdmin)
Create an encryption key to encrypt, decrypt, and re-encrypt individual files.
Procedure
1. In the Admin Tasks list in XAdmin, double-click Data Encryption. 2. Click the Keys tab, and click Add. 3. In the Key Name field of the New Encryption dialog box, enter a unique name for the new encryption key. 4. Optional: In the Password field, enter a password for the encryption key and confirm in the Confirm Password field. If you specify a password for the encryption key, you must use that password if you later decide to reset the password or delete the key. 5. Click Finish.
131 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Deleting encryption keys
If an encryption key is no longer used or is not needed, you can delete it from the key store.
About this task After you delete a key, any data that was previously encrypted with that key cannot be decrypted. Therefore, before you delete a key, confirm that the key is not needed to decrypt data on the current system and on any backup systems that yo might need to restore and access in the future. If you have any doubt, export the key to an encrypted file, and save the file in a secure location. Then delete the key.
Procedure
1. In the Admin Task list in XAdmin, double-click Data Encryption. 2. Click the Keys tab. 3. In the Keys tool, select the name of the encryption key, and click Delete. 4. If the selected encryption key is password protected, in the Password and Confirm Password field, enter the current password for the encryption key. 5. Click Finish. The Keys page, no longer displays the name of the key, and the associated key file is deleted from the key store. Managing the credential wallet
U2 servers token-based authentication
As customers are moving to a cloud-based Identity Management (IdM) system for user authentication in their application, the current user ID and password method of connecting to U2 servers is becoming less appropriate or even possible. At UniData 8.1.1 and UniVerse 11.3.1, token-based authentication is available to provide security and future extensibility for IdM systems. This section discusses how pre-configured and corresponding credentials are established, verified, and trusted in token-based authentication for connections between applications and U2 servers.
Warning: Token-based authentication is more vulnerable than direct OS user credential-based authentication because if, for example, the token credential is compromised, then potentially any and all OS users can be misrepresented. We strongly recommend that the U2 database is in a DMZ or behind a firewall behind a secure, isolated environment, and the connections are always secure. For more information, see the sections about SSL in this manual.
Overview of IdM and token-based authentication
The following architectural diagram describes the two options available to connect to a U2 Database server. The traditional method requires user name and password, which is used to validate the legality of the connection using operating system calls. Token based connections require username@TOKEN- ID (no password), and providing the username and TOKEN-ID are known to the U2 credential manager, the connection will be allowed through.
132 Token-based authentication
Token-based authentication
Token-based authentication supports no password login to U2 Servers. Prior to UniData 8.1.1 and UniVerse 11.3.1, U2 Servers require actual OS user ID and password to impersonate the user. On Windows, the Active Directory is required for token-based authentication. If authentication involves servers belonging to different domains, a mutual,-two-way trust relationship between domains is required. For obvious security concerns, U2 cannot do this blindly for any client connections; otherwise the database will be open for unauthorized accesses. To authenticate the IdM application, an authentication token is supplied by the connection and points to the U2 server.
Authentication token
The authentication token contains two parts separated by "@". The left side contains information such as the user name, and the right side contains the actual name of the token-ID. Currently this token is nothing but an ID and its password. The ID is not necessarily for an OS user ID, nor is the password.
Auth ID Auth ID is used to search the credential wallet for a mapping to an OS-level user account. Its general format is: OS-user-id@TOKEN-ID Depending on the application’s need, the Auth ID can be in one of the following forms: ▪ OS user account only, such as johnz. In this case, account impersonation is done like previous versions. ▪ TOKEN-ID only, such as @PRODUCTION. Note that the preceding @ is required. ▪ Full format, such as johnz@PRODUCTION
Password Depending on how the Auth ID is formed, the password can be either a direct OS user account password, or a token password set up by the Credential Wallet Manager (credman).
133 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Credential mapping record
The credential mapping record is a multi-column text record that maps a token-ID to an OS user ID. A token record is a logical collection that maps an authentication ID to an OS user or an OS group. Each token record should explicitly specify its members, which can be either individual OS user IDs or OS group IDs. For the latter case, each group ID must be preceded with an asterisk; IDs are separated by commas. If no member is specified, U2 validates the token password only. The AuthID will be used for no password login for the OS ID that the token is part of. If an OS ID is specified for a record, it can be used as a default user ID if the Auth ID is supplied without a specific user ID (such as @PRODUCTION). If the PRODUCTION token does not have an OS ID specified, using @PRODUCTION will result in authentication failure. Allowed services specify which interfaces that can use this mapping record (such as InterCall, UCI, or telnet). Currently, there are 4 valid values: ▪ UDCS or UVCS (for InterCall servers that support UO, UOJ and UO.NET)
Note: Telnet, XAdmin, and UniAdmin connections are not supported.
▪ UDSERVER or UVSERVER (UCI servers support ODBC, OLE DB, and JDBC) A token password must be specified when creating a token record, and it is required whenever a lookup (mapping) is requested. Currently there are no password policies enforced other than requiring a minimum length of 8 characters.
Credential wallet
The credential wallet is a collection of credential mapping records stored as an OS-level opaque file that is automatically encrypted and control-accessed. The only allowed access to this wallet is through the Credential Wallet Manager or through internal calls by U2 Servers. To secure this file, in addition to encryption, a machine tag can be added so that the file cannot be moved to other machines and used directly. An optional wallet password can also be specified for the wallet to protect the integrity of it. If a wallet has password protection, then for any wallet operations, a valid password must be provided. Note that when mapping an Auth ID to OS ID, this wallet password is not required.
Creating credential-mapping records
The credential mapping record maps a token-based ID to a user ID.
134 Creating credential-mapping records
1. In XAdmin, select the server you want to use. From the Admin Tasks pane, double-click Credential Manager. The Credential Mapping Records pane opens, as shown in the following example.
2. Click Add. 3. Enter the values for your mapping record in the dialog box that appears, then click OK. The following table describes each field.
Field Description
Token Type The TokenType of 2 cannot be changed. This value means the token is user defined; whereas 1 is a system-defined meta token.
Token ID The ID of the mapping record
Password Adds a password for the mapping record
Confirm Password Confirms the password
OSID The operating system ID or user
Allowed Services Specifies which interfaces can use this mapping record. Allows services include: ▪ UDCS or UVCS (for InterCall servers that support UO, UOJ and UO.NET) ▪ UDSERVER (UDUCI) or UVSERVER (UVUCI) (UCI servers support ODBC, OLE DB, and JDBC)
Members Specifies which members or groups are added to the mapping record.
135 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Field Description
Domain Specifies the domain added to the mapping record. For a two-way trusted domain, the Domain name\username is needed to log in using S4U. If the domain name is not included, then the LsaLoginUser() API call will fail. After you successfully log in with the domain name from the credential mapping record, the information is stored in the registry for better performance. To enable the domain cache, click the Configuration tab then the Domain Cache tab, and then select the Enable domain name cache for Windows check box.
Note: XAdmin does not support the import file function that the credman utility is able to perform.
After you click OK, the dialog box closes and you can see the mapping record displayed in the Credential Mapping Records tab. 4. Optional: You can search for credential mapping records by entering a search term in the Filters field. 5. Optional: Click the Configuration tab to define or modify the wallet password and machine tags.
Updating mapping records
The credential manager allows you to update the values for your mapping records in XAdmin.
Prerequisites ▪ Creating credential-mapping records, on page 134
Procedure
1. To access the credential manager in XAdmin, select the server you want to use. 2. From the Admin Tasks pane, double-click Credential Manager. The Credential Mapping Records pane opens, as shown in the following example.
136 Deleting mapping records
3. From the Credential Mapping Records tab, select the mapping record you want to update. 4. Click Update. 5. Update the values of your mapping record in the Update Credential Mapping Record dialog box that opens, and click OK. The following table describes each field.
Field Description
Token Type The TokenType of 2 cannot be changed. This value means the token is user defined; whereas 1 is a system-defined meta token.
Token ID The ID of the mapping record
Password Adds a password for the mapping record
Confirm Password Confirms the password
OSID The operating system ID or user
Allowed Services Specifies which interfaces can use this mapping record. Allows services include: ▪ UDCS or UVCS (for InterCall servers that support UO, UOJ and UO.NET) ▪ UDSERVER (UDUCI) or UVSERVER (UVUCI) (UCI servers support ODBC, OLE DB, and JDBC)
Members Specifies which members or groups are added to the mapping record.
Domain Specifies the domain added to the mapping record. For a two- way trusted domain, the Domain name\username is needed to log in using S4U. If the domain name is not included, then the LsaLoginUser() API call will fail. After you successfully log in with the domain name from the credential mapping record, the information is stored in the registry for better performance. To enable the domain cache, click the Configuration tab then the Domain Cache tab, and then select the Enable domain name cache for Windows check box.
After you click OK, the dialog box closes and the updated mapping record displays in the Credential Mapping Records tab.
Deleting mapping records
The credential manager allows you to delete a mapping record.
137 Chapter 4: U2 Extensible Administration Tool (XAdmin)
1. To access the credential manager in XAdmin, select the server you want to use. From the Admin Tasks pane, double-click Credential Manager. The Credential Mapping Records pane opens, as shown in the following example.
2. From the Credential Mapping Records tab, select the mapping record you want to delete. 3. Click Delete. 4. From the Question dialog box, click Yes to delete the mapping record.
Sending the token to the U2 Server
After you have defined a token-ID and its properties, your client application can now start using the token-based authentication method to connect to the U2 server via the unirpc interface using one of the following services: UDCS, UVCS, UDServer, and UVServer. The U2 Server verifies the credentials received using the credential wallet. Once verified, the connection impersonates the corresponding actual OS user. If the wallet is not present on the system, or the authentication token cannot be mapped and verified, then the U2 Server reverts to using the old style OS-ID-password impersonation method. It treats the ID and password as actual OS credential to impersonate. If the “Auth ID” is provided without the token-ID part (@tokenid), then U2 servers perform impersonation as is now – maintaining 100% backward compatibility. When performing mapping lookup, membership checking is tested against each OS-group until either a containing group is found or all OS groups are exhausted. In other word, the OS-group membership is based on conventional system setup outside of this implementation. There is no need to re-specify OS-group membership in the wallet. The membership checking is done each time a connection is requested. If you have many groups or a large number of individual OS user IDs specified in a token record, performance may be adversely affected. Managing licenses
To manage licenses, perform any of the following tasks:
138 Updating license information
Note: Not all of options shown are available for UniData.
Note: Python authorization is available on UniVerse 11.3.1. This option is not available on previous versions.
Note: SystemCure is only authorized for UniVerse 11.3.1 or higher. By default, the SystemCure for UniVerse check box remains deselected.
1. Updating license information After you have opened the License pane, verify that the number of users and expiration date displayed in the License pane matches the configuration on the Product Configuration sheet shipped with U2. 2. Obtaining an authorization code After updating all of the license information, you must obtain an authorization code. You must authorize UniVerse or UniData within 10 days of installation. 3. Configuring account-based licenses You can use XAdmin to configure account-based licensing.
Updating license information
After you have opened the License pane, verify that the number of users and expiration date displayed in the License pane matches the configuration on the Product Configuration sheet shipped with U2.
Prerequisites If you are using UVNet, you must authorize both the UniVerse database and UVNet.
Procedure
1. Click the Update tab, and in the Serial Number field, enter the UniVerse or UniData serial number. 2. In the UniVerse User Limit (UniVerse) or UniData RDBMS (UniData) field, enter the number of users for which you are licensed. 3. In the Connection Pooling field, enter the number of connection pooling licenses. If you are not licensed for any connection pools, enter 0. 4. In the Device License field, enter the number of device licenses for which you are authorized. 5. Select the check boxes for any of the applicable features you are running: ▪ NFA (UniData only.) ▪ RFS (UniData only.) ▪ EDA ▪ AUDIT ▪ SUBKEY ▪ PYTHON ▪ SystemCure for UniVerse (UniVerse only.) 6. In the Expiration Date field, update the expiration date of the license if necessary. Next topic: Obtaining an authorization code
139 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Parent topic: Managing licenses
Obtaining an authorization code
After updating all of the license information, you must obtain an authorization code. You must authorize UniVerse or UniData within 10 days of installation. 1. From the XAdmin menu, double-click Licenses, and then click Authorize. 2. Copy the configuration code shown in the Configuration Code field. 3. Go to the Rocket Authorization page, listed below, and follow the instructions on the website to obtain and copy the authorization code. ▪ US: https://rbc.rocketsoftware.com/authprod.asp?js=y ▪ International: https://rbcint.rocketsoftware.com/authprod.asp?js=y 4. Paste the authorization code into the Authorization Code field. Next topic: Configuring account-based licenses Previous topic: Updating license information Parent topic: Managing licenses
Configuring account-based licenses
You can use XAdmin to configure account-based licensing. 1. From the XAdmin menu, double-click License, and then click the Account-based License tab. The following window opens: 2. In the Logical License Account Definition area, click Add. The Add Account dialog box opens. 3. In the Path field, enter the full path to the account to which you want to allocate licenses, or click Browse to locate the account. 4. In the License Account ID field, enter the logical license account ID for the account. Click OK. 5. In the Account License Configuration area, click Add. The following window opens:
6. Expand the Licn Account ID list and select the Logical Account ID to which you want to allocate licenses. 7. In the Seats/DB field, enter the number of database licenses you want to allocate to the account. 8. In the Seats/CNPL, field the number of connection pool licenses you want to allocate to the account. 9. Optionally, you can enter a description for the license account ID license allocation in the Description box.
140 Managing U2 Data Replication
10. Click Save. If you change the configuration outside of XAdmin, you must Refresh for the change to take effect.
Previous topic: Obtaining an authorization code Parent topic: Managing licenses Managing U2 Data Replication
Use data replication to automatically transmit read-only copies of UniData or UniVerse files to other UniData or UniVerse systems. The system where the source data resides is called the publisher. A system requesting copies of file updates from the publisher is called a subscriber. There are four types of replication: ▪ Real-time: In real-time replication, transactions on the publishing server do not commit until all transaction logs arrive at the subscriber. With this type of replication, if the publishing server fails over to the real-time subscribing system, all committed transactions on the publishing system are guaranteed to apply to the standby system. ▪ Immediate: In immediate replication, the publishing system sends a transaction log to the subscribing system immediately and does not wait to commit the transaction. If the publishing system fails over to the immediate subscribing system, some committed transactions on the publisher might not arrive on the failover system. Administrator intervention might be necessary to recover the system. Immediate replication has better performance than real-time replication. ▪ Deferred: Deferred replication saves transaction logs in a file rather than sending them to the subscriber at a specific time. The subscribing system connects to the publishing server, retrieves all of the logs, and synchronizes its database with the publishing database. Deferred replication can only be used in non-standby replication. ▪ Delayed: Delayed replication allows updates to be delayed by a specified time on the subscribing system in U2 Data Replication. The publishing system can failover to the subscriber system up to a specified time. This will allow you to cancel or void some unwanted updates during the failover to protect the database from accidental misuse or malicious damage. To configure data replication, perform the following tasks:
Configuring U2 Data Replication
To configure U2 Data Replication, perform the following tasks: 1. Defining replication systems Once you have opened the Replication pane, define the replication systems. This task needs to be performed on both the publisher and subscriber servers. 2. Adding a publishing group After you have defined the replication systems, add a publishing group. 3. Adding a subscribing group After you have added a publishing group, add a subscribing group. 4. Optional: Changing a replication group definition You can change a replication group definition without having to stop and restart UniData or UniVerse. 5. Verifying the account defaults
141 Chapter 4: U2 Extensible Administration Tool (XAdmin)
You can view the account defaults to see which files are automatically included (replicated) and excluded. 6. Starting replication After you have defined the replication systems and added both a publishing and subscribing group, you can start replication.
Defining replication systems
Once you have opened the Replication pane, define the replication systems. This task needs to be performed on both the publisher and subscriber servers. 1. In XAdmin, from the U2 Resource pane, select the subscriber server. From the Admin Tasks pane, expand Replication then double-click Configuration. 2. To define replication systems, click the System Definition tab. 3. To add a new system, click Add. The Replication System Definition dialog box appears. 4. In the System ID field, enter the system name. 5. In the Host Name field, enter the host network name or network address of the system. Select the DHCP check box if the remote system has a dynamic IP address. 6. In the Version field, enter the database version on the system. For UniVerse, the version must be 111 or higher. For UniData, the version must be 60 or higher. 7. Auto resume determines if replication from the publishing system you specify will be synchronized and resume automatically when the U2 server starts, or after a reconfiguration. Select Yes if you want the server to automatically resume processing, or No if you want to manually synchronize data and resume processing. 8. In the Sync Interval field, select the time interval, in minutes, in which the replication system automatically synchronizes replication. U2 Data Replication automatically issues a SYNC request to the publishing system every period defined by sync_interval. A sync_interval of 0 indicates a manual synchronization system, where UniVerse or UniData does not automatically synchronize the systems. 9. Optional: Select Connection Authorization. If you select this check box on the subscribing system location definition on the publishing system, you must define the connection user name and password to the publishing system location after you complete this dialog box. 10. In the Timeout field, define the timeout interval. The timeout interval defines the number of seconds to wait if no packets are received before suspending replication. The publishing system sends a packet to the subscribing system approximately every four seconds when replication is idle. If the publishing system had the timeout interval defined, the process counts the time that has elapsed between packets being received. If the amount exceeds the timeout interval, replication is suspended.
Note: Do not set the timeout interval to less than 2 minutes.
11. Enter the full path to the trigger in the Exception Action field, or click Browse to locate the path. The Exception Action is a shell script on UNIX platforms, or a batch program on Windows platforms. 12. In the Failover Action field, enter the full path to the failover action or click Browse to locate the path. 13. To define an account for replication, click Add. 14. In the dialog box that appears, enter a name for the account in the Account Name field.
142 Adding a publishing group
15. Enter the full path to the account in the Account Path field, or click the arrow and select the full path to the account from the list. The account information is written to the repsys file. You can refer to the account name in other areas of replication without having to specify the full path. 16. Click Finish. 17. If you selected Connection Authorization previously, select the system and click Set Connection to define the connection user name and password to the publishing system. 18. In the dialog box that appears, enter the login name and the corresponding password. Reenter the password. Click Finish. Next topic: Adding a publishing group Parent topic: Configuring U2 Data Replication
Adding a publishing group
After you have defined the replication systems, add a publishing group. 1. In XAdmin, from the U2 Resource pane, select the publisher server. From the Admin Tasks pane, expand Replication then double-click Configuration. The Replication pane appears. 2. Click the Replication Group tab. 3. To add a publishing group, from the Publishing Groups area, click Add. 4. In the dialog box that appears, enter the ID of the publishing group in the Group ID field. 5. Specify the publishing account by selecting the account where the files you want to publish reside from the Account list. 6. To define replication level, select the level of replication you want from the Level list. You can select either ACCOUNT or FILE replication. If you select ACCOUNT, replication will occur at the account level for the account you selected. This means every file in that account will be replicated. If you select FILE, only the files selected in the Files area will be replicated for the account you selected. 7. To add files to the publishing group, in the Files area, click Add. A dialog box appears with all the files for your account listed. If you selected ACCOUNT in step 5, you can still select specific files for reasons such as making them sub-writable. If you selected FILE in step 5, select the specific files that you want to publish. When you are done adding files, click Finish. 8. By default, both the Data and the Dict cells of the file are selected. If you do not want to publish the data portion of the file, clear the Data check box (cell). If you do not want to publish the dictionary portion of the file, clear the Dict check box (cell). 9. If you want to make any of the files that you selected sub-writeable, select the cell for that file. A check mark appears in the SUB_WRITABLE column. Making a file sub-writable allows you to edit or change them on the subscriber without error. 10. If you are using account-level replication, select files to exclude from U2 Data Replication. To specify any files that are excluded, in the Excluded Files area, click Add. Select the specific files that you want to exclude, and click Finish. 11. Set any of the configuration parameters necessary for your environment in the Configuration area. The following table describes each of these parameters.
143 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Parameter Description RFS Failover Defines the behavior of U2 Data Replication when a publishing group starts. System If you are running RFS, when UniData starts it checks to see if the system was properly shutdown when UniData stopped. If it was not, UniData runs crash recovery to recover the database.
Note: This parameter is currently only available in UniData. N_LOGINFO The maximum number of replication logs that can be loaded in the shared memory buffer. If the number of logs in the replication buffer exceeds this value, UniVerse or UniData stores the logs in the replication buffer extended file. The default value is 4096. REP_BUFSZ The shared memory buffer size used to hold the log body for the replication group. The default value is 1048576. LARGE_RECSZ When a record is larger than the value of LARGE_RECSZ, UniVerse or UniData stores it in the LEF instead of the Replication buffer. The default value is 64K. RESERVED_FILE_ Defines the amount of file slots to reserve for an account-level group. The SPACE default value is 500. Pacing level The pacing level is a tunable parameter for a replication group that defines the overall delay level of the group. The higher the pacing parameter is, the longer a delay will occur if the other pacing criteria are in effect. The value can be an integer from 0 to 255. A pacing level of 0 turns off replication pacing for the group. The default value is 5.
Note: This parameter is only available in UniData. For more information about pacing, see Replication pacing, on page 148. 12. Click Finish. Next topic: Adding a subscribing group Previous topic: Defining replication systems Parent topic: Configuring U2 Data Replication
Adding a subscribing group
After you have added a publishing group, add a subscribing group. 1. In XAdmin, from the U2 Resource pane, select the subscriber server. From the Admin Tasks pane, expand Replication then double-click Configuration. The Replication pane appears. 2. Click the Replication Group tab. 3. Decide whether you to manually add a subscribing group or you want to import the configuration from the one you set in the publishing server, as described in Adding a publishing group, on page 143. To add one manually, continue to the next step. To import the configuration, click Import. a. In the dialog box that appears, select the server where you set up the publishing group. b. Select the version number. c. Select whether you want to merge or replace the subscribing configuration file with the remote one. d. Click Finish. The configuration is imported, and the values are automatically populated in the dialog box that appears. e. Verify that your configuration is correct, and click Finish.
144 Adding a subscribing group
You have successfully added a subscribing group, and can move on to Verifying the account defaults, on page 146. 4. To add a subscribing group, from the Subscribing Groups area, click Add. 5. In the dialog box that appears, select the publishing system from which this subscribing system is receiving data from the From System list. 6. Select the group ID from the publishing system in the Group ID list. When you select the group ID, XAdmin populates the file list and configuration parameters from the same group ID on the publishing system. 7. Select the account to which you want to replicate data in the Into Account field. XAdmin automatically populates the Account Path field. 8. Click the file you want to receive. You can select multiple files by clicking the file while holding down the CTRL key. 9. By default, both the Data and the Dict cells of the file are selected. If you do not want to receive the data portion of the file, clear the Data check box (cell). If you do not want to receive the dictionary portion of the file, clear the Dict check box (cell). 10. If you want to be able to update the file on the subscribing system, select the SUB_WRITEABLE check box (cell). 11. If you are using account-level replication, select files to exclude from U2 Data Replication. To specify any files that are excluded, in the Excluded Files area, click Add. Select the specific files that you want to exclude, and click Finish. 12. In the Distributions area, click the value in the Type field, then select the ellipsis button (...) that appears. 13. In the dialog box that appears, select the type of replication mode you want and the account for the subscriber. When choosing Realtime or Immediate subscribing, the subscribing system can optionally be defined as a standby system. This can be done by selecting the Hot Standby check box. A standby system can also be optionally configured for delayed standby replication. When selecting the Hot Standby check box, a Delayed Time Period field appears. Enter the amount of time you want to delay the updates on the subscriber in minutes. When using delayed standby replication, the updates are immediately sent to the subscriber but are not applied until the delayed time period has elapsed. Click Finish. 14. Set any of the configuration parameters necessary for your environment in the Configuration area. The following table describes each of these parameters.
Parameter Description RFS Failover Defines the behavior of U2 Data Replication when a publishing group starts. System If you are running RFS, when UniData starts it checks to see if the system was properly shutdown when UniData stopped. If it was not, UniData runs crash recovery to recover the database.
Note: This parameter is currently only available in UniData. N_LOGINFO The maximum number of replication logs that can be loaded in the shared memory buffer. If the number of logs in the replication buffer exceeds this value, UniVerse or UniData stores the logs in the replication buffer extended file. The default value is 4096. REP_BUFSZ The shared memory buffer size used to hold the log body for the replication group. The default value is 1048576.
145 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Parameter Description LARGE_RECSZ When a record is larger than the value of LARGE_RECSZ, UniVerse or UniData stores it in the LEF instead of the Replication buffer. The default value is 64K. RESERVED_FILE_ Defines the amount of file slots to reserve for an account-level group. The SPACE default value is 500. Pacing level The pacing level is a tunable parameter for a replication group that defines the overall delay level of the group. The higher the pacing parameter is, the longer a delay will occur if the other pacing criteria are in effect. The value can be an integer from 0 to 255. A pacing level of 0 turns off replication pacing for the group. The default value is 5.
Note: This parameter is only available in UniData. For more information about pacing, see Replication pacing, on page 148. 15. Click Finish. Next topic: Optional: Changing a replication group definition Previous topic: Adding a publishing group Parent topic: Configuring U2 Data Replication
Optional: Changing a replication group definition
You can change a replication group definition without having to stop and restart UniData or UniVerse. 1. In XAdmin, from the U2 Resource pane, select the subscriber server. From the Admin Tasks pane, expand Replication then double-click Configuration. 2. From the Replication Group tab, select the group that you want to update, then click Detail. 3. Make the appropriate changes, as described in Adding a subscribing group, on page 144 and Adding a publishing group, on page 143, then click Finish. After making your changes, you may need to resubscribe the group to update the subscriber system’s configuration. Next topic: Verifying the account defaults Previous topic: Adding a subscribing group Parent topic: Configuring U2 Data Replication
Verifying the account defaults
You can view the account defaults to see which files are automatically included (replicated) and excluded. 1. In XAdmin, from the U2 Resource pane, select a server. From the Admin Tasks pane, expand Replication then double-click Configuration. The Replication pane appears. 2. Click the Account Default tab. The Files area displays all of the default files that are included in the replication process. The Excluded Files area displays all of the automatically excluded files. 3. Optional: If you want to include or exclude a file, click Add next to Files or Excluded Files. In the dialog box that appears, enter the file name, and select any applicable specifications – Data, Dict, and/or SUB_WRITEABLE. When you are done, click Finish. Next topic: Starting replication Previous topic: Optional: Changing a replication group definition Parent topic: Configuring U2 Data Replication
146 Starting replication
Starting replication
After you have defined the replication systems and added both a publishing and subscribing group, you can start replication. 1. In XAdmin, from the U2 Resource pane, select the publishing or subscribing server. From the Admin Tasks pane, expand Replication then double-click Configuration. The Replication pane appears. 2. Click the Replication Tool tab. 3. From the Functions section, select the type of administrator option that you want to execute. ▪ Report – Reports the current status of a replication. This command is useful after a failure or failover occurs. ▪ Sync – Synchronizes subscribing systems to their publishing systems. The publishing system establishes a connection to the subscribing system and invokes the subscribing process. UniVerse or UniData reads and transfers replication logs from the publishing system to the subscribing system. The subscribing system then applies the updates to the database. ▪ Reconfig – Reconfigures the replication configuration while UniData or UniVerse is running. ▪ Suspend – Suspends a live replication. In a suspended mode, UniVerse or UniData interrupts the connection between the publisher and the subscriber. The publishing system saves the replication log files to the replication logs reserve file rather than transferring them to the subscribing systems. The subscribing system and all replication writer processes stop after they finish updating existing logs in the replication buffer. ▪ Failover – Changes the replication direction on a local system, either from the local system to the publishing system or subscribing system, or changes the subscribing source distribution. ▪ Reset – The reset command clears saved replication logs in the replication log reserve file. Use the reset command after you copy or store database files, since the remaining replication logs are no longer useful. ▪ Enable – Enables replication. ▪ Disable – Disables replication. For more information, see Disabling replication, on page 148. For more information about each of the commands, see the U2 Data Replication User Guide for UniVerse or UniData. 4. The choices in the Options section become available based on which function you select. Select the appropriate options for this replication. 5. Select whether you want a target definition of All or Selected. A target is a replication, a replication group, or a distribution of a replication group. A replication is all data replicated from a remote system to the local system, or from a local system to a remote system. A target definition of ALL represents all replications on the system. One command can have multiple targets. If you want to execute the command against all targets, leave All selected in the Targets area. If you want to select the replication to execute the command against, select the Selected option in the Targets area of the replication tool dialog box, then click Add. In the dialog box that appears, enter the target information, then click Finish. 6. Start the replication process by selecting Execute. Any output from the command appears in the Status box. Previous topic: Verifying the account defaults Parent topic: Configuring U2 Data Replication
147 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Disabling replication
Replication disablement is an enhancement to U2 Data Replication that allows a database administrator to temporarily disable the replication system and stop generating unnecessary replication logs for better performance, and to avoid running out of disk space, which could trigger system crash. U2 Data Replication can be disabled for any of the following reasons: ▪ The administrator determines that it is no longer necessary for the replication system to be running, for example, if problems with the subscribing system occur or changes are necessary for the requirements of replication. ▪ The replication system experiences an unrecoverable failure, for example, the communication link fails between the publisher and subscriber and the log area fills up before the communication link can be restored. A similar situation can occur if a power failure arises at the subscribing system.
To set up replication disablement, you must define the REP_DISABLE_DISK_PCT parameter in the udtconfig file. This parameter defines the system-wide limit of disk usage for replication logs. The value is the maximum percentage the replication log files can consume of the total space available on the file system in which the logs are configured. The default config parameter is 95%. U2 Data Replication is disabled immediately if this limit is reached, and a full resynchronization of the subscriber is required after this event. If the replication log disk is shared with data files or other applications, you should properly define this percentage to prevent application or database failure due to a growing replication log file size. To define this parameter, use the Configuration Editor from the Admin Tasks pane in XAdmin.
For example, REP_DISABLE_DISK_PCT=95.
Replication pacing
Replication pacing allows U2 Data Replication to gracefully slow down the pace of publisher database updates when replication becomes overflowed. This reduces the likelihood of the replication logs overflowing and ultimately disabling U2 Data Replication. Pacing gracefully slows down the database updates to prevent too many replication overflows to the log files. As the publisher process slowly paces the updates, the subscriber is able to catch up according to priorities set by the administrator. Administrators can define a session priority level that guides the pacing mechanism in recognizing when to slow down and when to resume normal speeds. Instead of overflowing the log file, the number of data updates sent to the log file is reduced, minimizing the possibility of disablement.
To define the pacing level, from the Admin Tasks pane, expand U2 Replication > Configuration. Select a publisher or subscriber group (or add a new one as described in Adding a publishing group, on page 143), and click Detail. The Pacing Level field allows an integer from 0 to 255. 0 turns off pacing. The default value is 5.
When the process finishes a single update or transaction commit, all degradation weights are added together to calculate the degradation time. The following formula shows the calculation: Group pacing weight=Sum(Pacing weights)*Group pacing level Delay time=(Group pacing weight)*Session priority level*10 microseconds
148 Diagnosis utility
If there are multiple groups, the group pacing weight would be the sum total of each group being updated. The process sleeps for the amount of the specified replication delay time before continuing to the next instruction.
Diagnosis utility
The diagnosis utility is used by U2 support for diagnosing problems encountered with U2 Data Replication. With the utility, you can view information such as the current configuration, groups, semaphores, and other general information that can help you troubleshoot any issues you have with replication. To access the diagnosis utility, in XAdmin, select the server you want to diagnose. From the Admin Tasks pane, expand Replication, then double-click Configuration. Click the Diagnosis Utility tab.
Replication recovery log
To view the logs from XAdmin, from the Admin Tasks pane, expand Replication, then double-click Configuration. Click the Recovery Logs tab. Select the time stamp for which you want to view the logs from the Time Stamp drop-down list, then select the replication group in the Group ID list. XAdmin displays the recovery status. The replication recovery log has two associated files:
▪ REP_RECV_LOG – records the recovery of publishing groups and the keys of missing transaction. ▪ REP_RECV_REC – records the records and virtual attribute values of the missing transaction.
Monitoring replication
The replication monitoring tool monitors connection status, data transferring, and whether the publisher and subscriber systems are synchronized. 1. To access the replication monitor, in XAdmin, select the publishing server. From the Admin Tasks pane, expand Replication, then double-click Performance and double-click Status. Two tabs appear: the Replication Performance Monitor tab and the Replication Status Monitor tab. These tabs work together to monitor replication. You can monitor two types of replication: ▪ Publishing replication – the data replication from the local system to a remote subscribing system, including all replication groups involved. A publishing system can have more than one publishing replication defined. ▪ Subscribing replication – the data replication from a remote publishing system to the local system, including all replication groups involved. A subscribing system can have more than one subscribing replication defined. 2. Optional: You can perform the previous step again but for the subscribing server. This step is not required, but can be useful because you can see how the publisher and the subscriber communicate with each other. 3. Click the Replication Performance Monitor tab. a. Select the name of the replication you want to monitor from the Replications list.
149 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Each replication is assigned a unique name on one system, consisting of the replication type and the remote system name. A replication type can be one of the following: ▪ Immediate ▪ Standby immediate ▪ Realtime ▪ Standby realtime ▪ Deferred
Note: If a replication has failed over, it still belongs to the same replication as it did before the failover, but the name changes.
b. Select the number of seconds to refresh the monitor in the Interval in seconds field. The default interval is 3 seconds. c. Next to the Server Control field, click Start Test Period. d. Next to the Interval in seconds field, click Start. The replication group status table displays the current status of each replication group belonging to the replication you specify. The following example shows the replication group status table.
e. Select a row, then below the table, select either Buffer Usage, Data Volume, or Latency Split to view the extended results displayed below the table. The following example shows the replication group status table with Buffer Usage selected.
The following example shows the replication group status table with Data Volume selected.
150 Monitoring replication
The following example shows the replication group status table with Latency Split selected.
f. By default, the table displayed with General selected. You can also view the table by test period by selecting TP Split from above the table. The following example shows the results displayed using the TP Split option.
4. Click the Replication Status Monitor tab. a. Select the name of the replication you want to monitor from the Replications list. b. Select the number of seconds to refresh the monitor in the Interval in seconds field. The default interval is 3 seconds. c. Next to the Interval in seconds field, click Start. Two traffic lights appear along with details about the replication, as displayed in the following example.
151 Chapter 4: U2 Extensible Administration Tool (XAdmin)
For more information about what this table displays, see The Replication Status Monitor tab, on page 152 5. Optional: If you opened the Replication Performance Monitor tab and the Replication Status Monitor tab for both the publisher and the subscriber, repeat the previous two steps to start both tests.
The Replication Status Monitor tab
The following table describe the functionality from the Replication Status Monitor tab.
Field/Area Description Replication Status The replication status indicates whether the publisher and subscriber are connected. The status can be one of the following: ▪ Green – The publisher and subscriber are connected for all groups involved in the replication. ▪ Yellow – At least one of the replication groups has been suspended by an administrator. ▪ Red – At least one of the replication groups has been terminated abnormally. Sync Status The sync status indicates whether the subscribing database is synchronized with the publishing database. The status can be one of the following: ▪ Green – The publishing and subscribing databases are synchronized. ▪ Yellow – There are pending updates that have not been applied to the subscribing database. Replication Details Provides specific details about replication as described below.
152 The Replication Status Monitor tab
Field/Area Description Packet The number of packets received from the other party of the replication. Received Types of packets include data packets, confirmation packets, heartbeat packets, and other control packets. Monitoring this information indicates whether the physical connection between the publishing database and the subscribing database is satisfactory. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. Packet Sent The number of packets that have been sent to the other party of the replication. Types of packets include data packets, confirmation packets, heartbeat packets and other control packets. Monitoring this information indicates whether the physical connection between the publishing database and the subscribing database is satisfactory. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. Subscriber The number of data records that have been received by the subscriber. This Received number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured.
Note: When monitoring a publishing replication this number may be out of date if the replication status is not green. Subscriber The number of data records that have been committed on the subscribing Committed database. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured.
Note: When monitoring a publishing replication this number may be out of date if the replication status is not green. Publisher The number of data records that have been committed on the publishing Committed database. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. TP Total The sum of all transactions committed in the replication groups on the local system. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. CGTPs The sum of all transactions committed across more than one replication Resolved group on the local system. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. Disablement The replication log disk percentage defined by the udtconfig or Disk Pct uvconfig file parameter REP_DISABLE_DISK_PCT. Max Replog The limit the replication log file size can reach before U2 Data Replication is Size disabled. Current The total replication log file size for all replication groups. Replog Size Replication group The replication group status table displays the current status of each status table replication group belonging to the replication you specify. See the following table for a description of each column of this table.
The following table describes the columns in the replication group status table.
Column Description Group The name of the replication group. name
153 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Column Description Connection The connection status between the publishing system and the subscribing system in Status the group. The status can be one of the following: ▪ Green – The publisher and subscriber are connected in this group. ▪ Yellow – The replication group has been suspended by an administrator. ▪ Red – The replication group has terminated abnormally. In-Sync Indicates whether the subscribing files are synchronized with the publishing files in the group. The in-sync status can be one of the following: ▪ Green – The publishing and subscribing databases are synchronized. ▪ Yellow – There are pending updates in this replication group that have not been applied to the subscribing database. Rep. Status The current replication group status. ▪ REP_RUNNING – The replication is running. ▪ REP_SYNCING – The replication is performing synchronization. ▪ REP_SUSPENDED – The replication is suspended. ▪ REP_DO_SUSPEND – The replication is in the process of suspending. ▪ REP_EXIT – The replication is suspended due to an abnormal termination. The status can be one of the following on the subscribing system: ▪ SUB_STOP – The replication is stopped. ▪ SUB_EXIT – The subscribing system has exited abnormally. ▪ SUB_SHUTDOWN – The replication on the subscribing system has been shut down. ▪ SUB_RUNNING – The replication on the subscribing system is running. ▪ SUB_DO_RECONFIG – A reconfiguration process is occurring on the subscribing system. ▪ SUB_DO_SUSPEND – The replication is suspended on the subscribing system. ▪ SUB_SYNCING – The replication is performing synchronization on the subscribing system. ▪ SUB_RESYNCING – The replication is performing resynchronization on the subscribing system. ▪ SUB_DO_FAILOVER – The subscribing system is performing a failover. Changed By The event or reason that caused the replication status to change. If the status changed due to an exception, this column displays the error category and error code. A detailed error string is available in the tool tips. See the following table for a description of each of the events. #Recv’d The number of packets received in the group. Monitoring this number indicates if the physical connection between the publishing system and subscribing system is satisfactory. #Sent The number of packets sent in the group. Monitoring this number indicates if the physical connection between the publishing system and subscribing system is satisfactory. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured.
154 The Replication Status Monitor tab
Column Description Data The total amount of data, in bytes, replicated in the group. On a publishing system Replicated this field represents the total amount of data sent out. On a subscribing system, this field represents the total amount of data received from the publishing system. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. SubGot The log sequential number of the latest replication log received by the subscribing system. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. SubAvail The log has been loaded into the replication buffer and is available for the replication writer processes. SubDone The log sequential number of the latest replication log committed to the subscribing database. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. PubDone The log sequential number of the latest replication log committed to the publishing database. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. #TP The number of transactions resolved in this group, including cross-group transactions. This number is cumulative from the last time UniData or UniVerse was started or U2 Data Replication was reconfigured. Data The total amount of transferred data that has been replicated. Transfer Data Size The total size of data replicated. Pacing The replication pacing level in a group, as defined in the REP_PACING parameter in the Level repconfig file. Note: This column is currently only available in . Total The total group pacing weight since the UniData or UniVerse system has started or U2 Degradation Data Replication was reconfigured. Total Rep The current replication log file size including LEF and LRF. Log Size
The following table describes the valid events of reasons that appear in the Changed By column that can cause a change in the replication status.
Event/Reason Description AUTO_SYNC Replication is automatically resuming. CGTP_SUSPEND Cross-group transaction processing is suspended. CM_REQUEST Checkpoint manager is requested (RFS only). DBA_ORDER The system administrator issued a request resulting in a change of status. ENABLE Replication is enabled. FAILOVER A failover has occurred. PUB_REQUEST A request was sent from the publishing system, or an event occurred on the publishing system resulting in a change of status. PUB_STARTUP The publishing system started. RECONFIG Replication is reconfiguring. REMOTE_REQ A subscribing system can request to execute a SYNC command on the publishing system. REP_DISABLED Replication is disabled.
155 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Event/Reason Description SCHEDULED The repmanager process can only schedule a SYNC command for deferred replication. SUB_REQUEST A request was sent from the subscribing system, or an event occurred on the subscribing system resulting in a change of status. SYNCDONE A synchronization process succeeded. SYS_STARTUP The UniData or UniVerse system started.
Managing Locks in UniVerse
Locks are set on UniVerse files by certain BASIC statements and UniVerse commands. The type of lock determines what a process can access while other processes hold locks on records or files
File and record locks
The following information is in the File/Record Locks list:
Parameter Description Device A number that identifies the logical partition of the disk where the file system is located. Inode A number that identifies the file that is being accessed. Net A number that identifies the host from which the lock originated. Zero (0) indicates a lock on the local machine. User# The user ID. Lmode The lock semaphore number and the type of lock. For record locks, there are two settings: ▪ RU for an update lock ▪ RL for a shared lock For file locks, there are six settings: ▪ FS for a shared lock ▪ IX for a shared lock with intent to acquire an exclusive file lock ▪ FX for an exclusive file lock ▪ XU for an exclusive lock set by CLEAR.FILE ▪ CR for a shared file lock set by RESIZE ▪ XR for an exclusive file lock set by RESIZE Pid The process ID number. Login Id The login ID. Record Id The name of the record that is locked.
Group locks
The following information is in the Group Locks list:
156 Clearing locks
Parameter Description Device A number that identifies the logical partition of the disk where the file system is located. Inode A number that identifies the file that is being accessed. Net A number that identifies the host from which the lock originated. Zero (0) indicates a lock on the local machine. User# The user ID. Lmode The lock semaphore number and the type of lock. There are five settings: ▪ EX for an exclusive update lock ▪ SH for a shared lock ▪ RD for a read lock ▪ WR for a write lock ▪ IN for an information lock G-Address The logical disk address of the group. This value is 1 for a type 1 or type 19 file. Any other value is represented in hexadecimal format. Rec Locks The number of locked records in the group. Reader The number of readers in the group. SH The number of shared group locks. EX The number of exclusive update locks.
Clearing locks
You can clear a single file, record, or group lock, or all the locks for a specified user using the Locks window.
To clear a file or record lock
To clear a file or record lock: 1. To access the Locks tool in XAdmin, select the server you want to use. From the Admin Tasks pane, click Locks. 2. Select the lock from the File/Record Locks list. 3. Click Clear Lock. The Lock window is updated.
To clear a group lock
To clear a group lock: 1. To access the Locks tool in XAdmin, select the server you want to use. From the Admin Tasks pane, click Locks. 2. Select the lock from the Group Locks list. 3. Click Clear Group Lock. The Locks window is updated.
157 Chapter 4: U2 Extensible Administration Tool (XAdmin)
To clear all locks
To clear all locks for a specified user: 1. To access the Locks tool in XAdmin, select the server you want to use. From the Admin Tasks pane, click Locks. 2. Click User ID. The Clear User Locks window appears. 3. Enter the user ID in the User Id field. 4. Click OK. The Locks window is updated. Managing locks in UniData
Locks are set on UniData files by certain BASIC statements and UniData commands. The type of lock determines what a process can access while other processes hold locks on records or files. To access the Locks tool in XAdmin, select the server you want to use. From the Admin Tasks pane, expand Locks. The information displayed in the Lock Administration window is a snapshot of the file, record, and group locks when you activated the Locks option. To view the current state of locks, click Refresh.
File/Record Locks tab
The following table describes the column headings of the File/Record Lock section on the Lock Administration window.
Tip: To increase or decrease the size of a column, place the cursor on the line to the right of the column heading you want to change until the cursor becomes a double-headed arrow, then click the mouse button and drag to the proper size.
Column Heading Description UNO The sequential number the database assigns to the process that set the lock. UNBR The process ID of the user who set the lock. UID The user ID of the user who set the lock. UNAME The log on name of the user who set the lock. TTY The terminal device of the user who set the lock. FILENAME The file name in which the record is locked. INBRH The high integer of the inode of the file holding the lock, on Windows platforms only. INBR The Inode of the locked file. On Windows platforms, this is the low integer of the Inode of the file holding the lock. DNBR Used in conjunction with INBR to define the file at the operating system level. RECORD ID The record ID of the locked record. M The type of lock. X indicates an exclusive lock. S indicates a shared lock.
158 System Resource Locks tab
Column Heading Description TIME The time at which the lock was set. DATE The date on which the lock was set.
To refresh the display, click Refresh.
System Resource Locks tab
The System Resource Locks tab on the Lock Administration window displays semaphore-type locks that reserve system resources for exclusive use. These locks can be set individually with the LOCK command. They are also set by other commands, including T.ATT. The following table describes the column headings of the System Resource Locks tab.
Tip: To increase or decrease the size of a column, place the cursor on the line to the right of the column heading you want to change until the cursor becomes a double-headed arrow, then click the mouse button and drag to the proper size.
Column heading Description UNO Sequential number assigns to the session. UNBR Process group ID (pid) of the user setting the lock. UID User ID of the user setting the lock. UNAME Login name of the user setting the lock. FILENAME File name in which the record is locked. INBR I-node of the locked file on for UNIX only. DNBR Used in conjunction with INBR to define the file at the operating system level on for UNIX only. TTY Terminal device of the user setting the lock. RECORD ID Record ID of the locked record. M Record lock mode. TIME The time at which the lock was set. DATE The date on which the lock was set.
To refresh the display, click Refresh.
Lock Waiting Queue tab
The Lock Waiting Queue tab on the Lock Administration window lists processes that currently waiting for locks. If a process is waiting for a lock, this window displays information about the holder of the lock and processes waiting for the lock. Locks are set by each udt process through the General Lock Manager (GLM) module.
UniBasic commands that check for locks, such as READU and READVU, cause processes to wait for locks to be released before proceeding. Information about the owner of the lock is listed above the line. Information about processes waiting for the lock is listed below the line, sorted by the date and time the process requested the lock. The following table describes the column headings that display in the output for the Lock Waiting Queue window for the owner of the lock.
159 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Tip: To increase or decrease the size of a column, place the cursor on the line to the right of the column heading you want to change until the cursor becomes a double-headed arrow, then click the mouse button and drag to the proper size.
Column heading Description FILENAME The name of the file holding the lock. RECORD ID The record ID holding the lock. M The type of lock held. X is an exclusive lock, S is a shared lock. OWNER The user name of the owner of the lock. UNBR The process group ID (pid) of the user who set the lock. UNO The sequential number UniData assigns to the udt process for the owner of the lock. TTY The Terminal device of the user owning the lock. TIME The time the lock was set. DATE The date the lock was set.
The next table describes the Lock Waiting Queue window column headings for the processes waiting for locks.
Column heading Description FILENAME The name of the file for which a lock is requested. RECORD ID The record ID of the record for which a lock is requested. M The type of lock held. X is an exclusive lock, S is a shared lock. OWNER The user name of the process waiting for a lock. UNBR The process group ID (pid) of the user who waiting for the lock. UNO The sequential number assigns to the udt process waiting for the lock. TTY The terminal device of the user waiting for the lock. TIME The time the lock was requested. DATE The date the lock was requested.
To refresh the display, click Refresh.
Clearing locks
To clear a lock displayed in the window, select the lock you want to clear, and then click Clear Lock. Managing deadlocks (UniVerse)
A deadlock occurs when a process tries to acquire a lock that another process owns and the existing lock is incompatible with the requested lock. Conditions such as the following can lead to deadlocks: ▪ Lock promotion from a shared record or shared file lock to a stronger lock ▪ Lock escalation to file locks when two processes try to escalate at the same time You can configure UniVerse to automatically identify and resolve deadlocks as they occur, or you can manually fix a deadlock by stopping one of the deadlocked user processes. The deadlock daemon uvdlockd identifies and resolves deadlocks.
160 Managing deadlocks (UniVerse)
To start, stop, or configure the deadlock manager on the server, or to manually resolve file locking conflicts, select Dead Locks from the XAdmin main window. When the deadlock manager is running on the server, deadlocks are automatically resolved. The deadlock manager keeps a log file that records all deadlocks that it automatically resolved. When you choose Dead Locks from the XAdmin menu, the Deadlocks tab appears, as shown in the following Windows example:
The following information appears in the Dead Lock tab:
Field Description Action Dead Lock State Indicates whether deadlocking is Click Enable to turn on deadlock enabled or disabled, and whether the management with the default deadlock manager process is running. settings. Click Shutdown to disable deadlock management. Click Configure to set deadlock resolution parameters. Click Refresh after changing the current management state. Dead Locks Pending Displays the server’s current deadlock Select a process and click Resolve to processes. terminate the process.
To configure how UniVerse manages deadlocks, click Configure. The Dead Lock Configuration dialog box appears, as shown in the following example:
161 Chapter 4: U2 Extensible Administration Tool (XAdmin)
The following information appears in the Dead Lock Configuration dialog box:
Field Description Action Deadlock Check The number of minutes that the Choose the number of minutes. Interval deadlock process waits before checking deadlock conditions. XAdmin converts that time into seconds and stores it in the uvdlockd.config file. Resolution Determines the action to take if a Select one of the following actions to Strategy deadlock is encountered. resolve the deadlock: ▪ Terminate deadlocked transaction at random ▪ Terminate newest transaction ▪ Terminate transaction with fewest deadlocks Log File Displays the full path of the log file. Click Browse to select the directory for The log file displays information an existing log file. about deadlocks that have been Click Purge to clear an existing log file to automatically resolved and the way save disk space. in which they were resolved. Click Examine to view an existing log file. Startup Determines if UniVerse launches the Select the Launch deadlock process deadlock process when UniVerse is at startup check box if you want it started. launched when UniVerse is started.
Starting and stopping the deadlock manager
From the Admin Tasks pane, click Deadlocks. To start the deadlock manager on the server using system default settings, click Enable. Clicking Shutdown disables the deadlock manager.
162 Using the uvdlockd command
Note: When the deadlock manager is running, you cannot manually resolve deadlocks, and the Resolve button is dimmed. If you stop the deadlock manager, click Refresh to select and resolve deadlocks displayed in the Dead Locks Pending box.
Options available in the dialog box change dynamically according to your choice to back up to disk or tape.
Using the uvdlockd command
Use uvdlockd to administer the deadlock daemon. You must be a UniVerse Administrator to use uvdlockd. You can use the uvdlockd command to automatically identify and resolve deadlocks as they occur, or you can manually fix a deadlock by selecting and aborting one of the deadlocked user processes.
If the deadlock daemon is not running, the uvdlockd command starts it.
Syntax
uvdlockd {[-t time] [-r res] [-l location]} | [-query] | [-stop] | [-v victim]
Parameters The following table describes each parameter of the syntax.
Parameter Description -t time The time interval (in seconds) between the deadlock daemon’s successive checks of the lock-waiter tables. The default is 60 seconds. -r res The resolution strategy the deadlock daemon uses. It can be one of the following: 0: Selects a transaction at random. This is the default. 1: Selects the newest transaction. 2: Selects the transaction with the fewest number of locks held. -l location The location of the deadlock log file. The default location is uvhome/ uvdlockd.log. -query Generates a report based on a one-shot analysis of the lock-waiter tables and any detected deadlocks. -v victim Specifies which user number to select as the process to abort. -stop Shuts down the deadlock daemon.
Resolving deadlocks automatically
The deadlock daemon automatically resolves deadlocks by creating and updating a set of lock-that represent the current state of the locking and transactional system. The daemon continuously reviews the tables for evidence of a deadlock. If the deadock daemon occurs, the daemon stops one of the currently active transactions.
163 Chapter 4: U2 Extensible Administration Tool (XAdmin)
When the transaction stops, active transactional statements are rolled back and any remaining locks are removed. There are provides three options for selecting the transaction to stop. The daemon can select the newest transaction, select the transaction with the fewest number of locks, or select a random transaction. Selecting a random transaction, which is the default option, works well in most situations. Selecting the transaction with the fewest locks or selecting the newest transaction works well when transactions are long. Managing Windows Telnet Sessions (Windows only)
To manage Telnet sessions on a Windows server from XAdmin, double-click Network Services, then double-click Telnet in UniVerse or UDTelnet in UniData. The Network Services dialog box appears, as shown in the following UniVerse example:
The Network Services dialog box contains the following fields and options: ▪ Telnet Port # - This field displays the TCP port that the Telnet session uses. This is taken from the Windows registry information on Windows computers. Windows users can selectively disable the Telnet port or SSL Telnet Port by selecting the relevant Disable option. The default non-secure port number is 23. The default secure port number is 992.
164 Modifying the Telnet session parameters
▪ SSL Port # - The SSL port number that the Telnet service should monitor for client connections. The default value for the Telnet port number is 992. We recommend that you not change this unless you have another service that requires socket 992. ▪ UniVerse only. User Policy (UniVerse) - The User Policy setting determines how the Telnet session is used when a user makes a Telnet connection. ▪ Connection Parameters - Connection Parameters are the current connection values for the Telnet service. UniVerse stores these parameters in the Windows Registry on the Server. ▪ Keep Alive Parameters - The Keep Alive parameters determine intervals when UniVerse checks the viability of a network connection between the client and server. ▪ Set backlog queue - The maximum length of the queue of pending Telnet connections. The default value is 14. ▪ Detach process - If you select this option, the Telnet service as a detached process. ▪ Create desktop - If you select this option, the Telnet service creates its own WinStation/Desktop and assigns it to the process.
Note: Not all of options shown are available for UniData.
Modifying the Telnet session parameters
You can modify any of the telnet session parameters from the Network Services dialog box.
Note: To use the new settings, you must stop and restart the udtelnet (UniData) or uvtelnet (UniVerse) service.
Changing the telnet session port number
To change the port number for the telnet session, enter the new port number in the Port # box. UniVerse stores the new port number as a uvtelnet entry in the services file when you click Save.
Defining the Telnet user policy
UniVerse only. As a UniVerse administrator, you can specify how all users use the Telnet session. Valid user policies are: ▪ Home Account - Users connect to their home directory, which must be a valid UniVerse account. ▪ Home Directory - Users connect to their home directory. If the home directory is not a UniVerse account, users are prompted to set up the account. This is the default setting ▪ Any Account - Users can connect to any valid UniVerse account. ▪ Any Directory - Users can connect to any directory. If the directory is not a UniVerse account, UniVerse prompts to set up the account. ▪ UV Account - Specifies that the user connects to an existing UniVerse account in the UV.LOGINS file. ▪ UV Directory - Users connect to a directory defined in the UV.LOGINS file, and can create a UniVerse account in that directory if the directory is not already configured for UniVerse.
165 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Administrators are prompted for the account to which they want to connect regardless of the User Policy setting.
Setting the Telnet connection parameters
The four valid Telnet connection parameters are: ▪ Max. Logon Attempts - Defines the number of failed log in attempts a user is allowed before the Telnet connection is dropped. The default setting is 4. ▪ Logon Pause - If a login attempt fails, the pause, in seconds between login attempts. The default is 4 seconds. ▪ Logon Timeout - The time, in seconds, that the system waits for a response to a login prompt. When the timeout occurs, the Telnet connection is dropped. The default is 30 seconds. ▪ Termination Pause - The pause, in seconds, after the final failed login attempt. After the specified pause, the connection is dropped. The default is 4 seconds.
Setting keep alive parameters
The Keep Alive feature determines when inactive connections can be disconnected. When a connection becomes inactive, keep-alive packets are periodically exchanged. When a number of consecutive packets remain unanswered, by default 20, the connection is broken. ▪ Keep Alive Interval - The interval, in milliseconds, separating keep alive retransmissions until a response is received. Once a response is received, the delay until the next keep alive transmission is controlled by the value of Keep Alive Time. After the number of retransmissions specified by Max. Data Retransmissions are unanswered, the connection aborts. The default value is 1000 (one second). ▪ Keep Alive Time - This parameter specifies how often TCP attempts to verify that an idle connection is still valid by sending a keep alive packet. If the connection is still valid, the remote system will acknowledge the keep alive transmission. The default value is 7,200,000 milliseconds (two hours). ▪ Max. Data Retransmissions - This parameter specifies the number of times TCP retransmits an individual data segment before aborting the connection. The retransmission timeout is doubled with each successive retransmission on a connection. It is reset when responses resume.
Specifying the Telnet logon banner
You can specify the text that users see when they connect to the host in the Logon Banner box.
Specifying the termination pause
When the telnet client is closed without logging out, the ON.EXIT command is not executed. This can cause an unhandled exception or access violation in the event log. Using XAdmin, the termination pause can be changed to increase the time and allow the main thread to exit properly. 1. On the XAdmin Task list, click Network Services → Telnet. 2. In the Termination Pause field, enter the time you want to delay the exit process.
Note: The default value is 4 seconds.
166 Administering Telnet users (UniVerse)
Administering Telnet users (UniVerse)
UniVerse only. The UV.LOGINS file, which resides in the UV account, contains a list of users and the directories or UniVerse accounts they log on to when they first invoke UniVerse from a Telnet session. Click the Users tab. The UniVerse Users dialog box appears, as shown in the following example.
You can enter users logging on to the system both from the local machine and from domains. You can also maintain entries for users who have accounts on multiple domains with access to this system. You can specify the user’s account either as a case-sensitive entry in the UV.ACCOUNTS file, or as a fully qualified path. If the user logs on to the system using a local machine login ID, UniVerse uses the Local Machine entry. If the user logs on to the system through a domain, UniVerse uses the entry for the domain. If the user enters a login ID without a machine or domain name, UniVerse first uses a local machine login ID if it exists, and then checks domain login IDs.
Adding Telnet users
UniVerse only. To add a new user, click Add from the UniVerse Users tab. A dialog box similar to the following example appears:
167 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Add a UniVerse domain user UniVerse only. To add a domain user, in the Domain area, click Add. The Domain Account Details dialog box appears. Enter the name of the domain to which you want the user to connect in the Domain box. Enter the full path to the account to which the user is to connect, or click Browse to search for the account. Click OK to save the information, or click Cancel to exit without saving changes. The user appears in the Domain area of the User Account Details dialog box.
Adding a local machine user UniVerse only. To add a user to a local machine, in the Local Machines area of the Add Telnet User dialog box, click Add. The Local Machine Account Details dialog box appears, as shown in the following example: Enter the name of the local machine in the Local Machine field. Enter the full path to the account to which the user is to connect, or click Browse to search for the account. Click OK to save the information, or click Cancel to exit without saving changes. The user appears in the Local Machines area of the User Account Details dialog box.
Configuring Telnet user profiles
UniData only. From the Admin Tasks view, double-click UDTelnet Users to specify which users are allowed to connect to your system through UDTelnet, and to create custom user profiles. A window similar to the following example appears when you click the Users tab:
168 Default user profile
This dialog box enables you to specify a list of users that are allowed to connect to your Windows system through UDTelnet. At installation, UDTelnet is started with a default configuration that allows any user who can access your Windows system from the network to access the system through UDTelnet as well. This default behavior is acceptable in many instances. However, administrators may wish to grant only certain users Telnet access, or to create individual user profiles. The Users dialog box allows this flexibility.
Warning: If you remove the Default profile, no user can log on through UDTelnet unless you have created a specific profile for the user.
Default user profile
When you first display the Users dialog box, you see an entry for DEFAULT in the User box. Highlight DEFAULT and click Update to display the default profile. The following example illustrates a sample default profile.
169 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Specify default shell
In the Default Shell box, enter the full path of an executable. In the default profile, this is set to udtbin\udt.exe, which starts a UniData session.
Specify startup directory
Enter the full path of the working directory to which you want to connect when you log on in the Startup Directory box. In the default profile, this is set to the UniData demo account.
Specify arguments
In the Command Line box, enter any arguments you want to pass to the default shell. In the default configuration, this is blank.
Specify UDTHOME
Enter the full path to the UDTHOME directory in the UDTHOME box.
Determine ANSI version
Select the ANSI Version 3.x check box if you want to enable faster screen refreshes for terminals that support ANSI 3.x color. By default, this check box is not selected.
Determine how to map characters
Select the Use Redirection Chars check box if you want to map unprintable characters to printable characters. By default, this check box is selected.
170 Prompt for working directory
Prompt for working directory
Select the Prompt Directory check box if you want the user to select a working directory when they log on. By default, this check box is not selected.
Note: If you want one or more users to see the MS-DOS prompt when they log on, edit the user profile or profiles so that the default shell is%systemroot%\system32\cmd.exe.
Click OK to return to the Telnet Server dialog box, or click Cancel to exit without saving changes.
Customizing Telnet user profiles
Complete the following steps to create a customized profile for a user. 1. Add a Profile. Click Add to add a user profile. The following dialog box appears:
2. Enter the name of the user in the User Name box. Enter the logon name only (for instance, user01). Do not enter the domain name (for instance, do not enter ACCOUNTING\user01). UniData populates the dialog elements with the values from the Default Configuration. Click OK to accept those values, or edit one or more fields to customize the profile.
Note: If you deleted the Default profile, UniData displays a message when you attempt to add new user profiles. You must enter all the configuration settings manually, since UniData cannot copy them from the default profile.
3. Customize a profile. To edit a profile, highlight the user name in the User box, then click Edit. Consider the following points when customizing a user profile: ▪ Specify a full path in the Default Shell box. You can use either drive letters or the Universal Naming Convention (UNC) to specify the path. ▪ By specifying the Startup Directory, you can direct different users to different startup directories, even if they are using the same default shell.
171 Chapter 4: U2 Extensible Administration Tool (XAdmin)
▪ You can allow users to choose their directory when they log on by selecting the Prompt Directory check box. ▪ If you do not know whether a particular terminal supports Version 3 Color, select the ANSI Version 3.x check box. Test the terminal; if screen colors are not displayed correctly, modify the user profile to clear the ANSI Version 3.x check box. The following example shows a sample configuration that allows a user to log on through UDTelnet, select a starting directory, and access the MS-DOS command prompt. The default startup directory is C:\U2\ud73\demo:
Changes to a user’s configuration are visible the next time the user logs in through UDTelnet.
Generated profiles If you selected Prompt Directory in your Default Profile, UniData creates a profile for each user who would normally receive the default user profile. UniData creates the individual profiles the first time a user chooses a startup directory different from the default. The generated profile uses the same configuration settings as the default profile, with the exception of Startup Directory, which is set to the directory chosen by the user when they log on. The following examples show the effect of the Prompt Directory option. In the first example, the default user profile has Prompt Directory selected:
172 Generated profiles
The following example shows the appearance of the screen when a user logs on:
Path (C:\U2\ud73\demo) : \U2\ud73\claireg Notice that the default path is C:\U2\ud73\demo, and the user is selecting an alternate startup directory, \U2\ud73\claireg. Pressing ENTER starts a UniData session in \U2\ud73\claireg. This logon session also creates a profile for the user, which you can view or edit from the Telnet Server dialog box. The generated profile is shown in the following example:
The next time the user logs on through Telnet, the default path is changed, as shown in the following example:
173 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Path (\U2\ud73\claireg) : UniVerse file utilities
There are a number of utilities you can use to keep your files at peak efficiency. The following describes the XAdmin File Tools option. Use the File Tool option of XAdmin for general file administration. Use the format conversion utility to import files and BASIC object code from different hardware platforms. For information about other UniVerse file maintenance commands and techniques, see UniVerse System Description.
Administering UniVerse files
To administer UniVerse files, choose File Tools from XAdmin. The File Tool tab appears, as shown in the following example:
The tasks you can perform from this window include: ▪ Listing all files in all UniVerse accounts ▪ Listing file properties and statistics ▪ Running file diagnostics ▪ Repairing damaged files
174 Listing files in a UniVerse account
Listing files in a UniVerse account
From the File Tools tab, select the account for which you want to view files. All files for that account appear in the tab, as shown in the following example:
View file properties
To view the properties of a file, select the file for which you want to view properties in the File Tools dialog box, then click Properties. The Properties dialog box appears, as shown in the following example:
175 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Base information From the Properties dialog box, select the Base Info tab. XAdmin displays the following information about the file: ▪ File name ▪ File type ▪ Separation and modulus of static hashed file ▪ Dynamic file parameters For a detailed description of UniVerse files, see the UniVerse System Description.
Header information From the Properties dialog box, select the Header Info tab. A dialog box similar to the following example appears:
176 National Language Support (NLS) information
XAdmin displays the following header information for the file: ▪ File version ▪ SICA and schema name, if the file is a table ▪ Free chain ▪ Part block ▪ mkdbstamp If the Read Only check box is selected, the file is read-only.
National Language Support (NLS) information From the Properties dialog box, click the NLS tab. A dialog box similar to the following example appears:
177 Chapter 4: U2 Extensible Administration Tool (XAdmin)
XAdmin displays the following information about NLS: ▪ In the Map Name field, the name of the character set map associated with the file ▪ Map checksum ▪ In the Sort Name field, the Collate convention that determines how to sort file data ▪ Sort checksum For detailed information about NLS, see the NLS Guide.
Transaction logging information From the Properties dialog box, click the Trans Logging tab. A dialog box similar to the following example appears:
178 Indexes information
XAdmin displays the following information about transaction logging: ▪ File number ▪ Number of the last checkpoint log If the Inconsistent check box is selected, and file is inconsistent.
Indexes information From the Properties dialog box, click the Indexes tab. A dialog box similar to the following example appears:
179 Chapter 4: U2 Extensible Administration Tool (XAdmin)
If the file has a secondary index, XAdmin displays the name of the index in the Index File field.
Backup and replication information From the Properties dialog box, click the Backup + Replication tab. A dialog box similar to the following example appears:
180 View file statistics
XAdmin displays the following information about backup and replication: ▪ In the Backup Time field, the date and time of the last backup. ▪ In the Clearfile Time field, the date and time the last CLEARFILE command was executed against the file. ▪ The type of backup, either full, weekly, or daily.
▪ In the File Count field, the number of records in the file, counted by either the last COUNT command executed against the file, the last full backup, or the last restore. If the File Changed check box is selected, the file count may be out of date because the file has been changed since the last file count. ▪ In the Replication area, Stat indicates whether the file is a published file, a subscription file, or a failed-over file. This area also lists the replication ID in the ID field.
View file statistics
To view statistics about a file, from the File Tools window, select the file for which you want to view statistics, then click Statistics. A dialog box similar to the following example appears:
181 Chapter 4: U2 Extensible Administration Tool (XAdmin)
File information In the File Information area of the Statistics dialog box, XAdmin displays the following information: ▪ File Name ▪ Date of the last update ▪ File separation if a static hashed file ▪ Modulus if a static hashed file
File statistics XAdmin displays the following statistics about the file you selected:
Field Description Reads Total number of READ operations on the file. ReadUs Total number of READU operations on the file. Writes Total number of WRITE operations on the file. Write Updates Total number of WRITEU operations on the file. Oversize Reads Total number of READ operations executed against large records. Oversize Writes Total number of WRITE operations executed against large records. Overflow Reads Total number of READ operations that accessed overflow buffers. Deletes Total number of DELETE operations on the file. Selects Total number of SELECT operations on the file.
182 Running file diagnostics
Field Description ReadLs Total number of READL operations on the file. Opens Total number of OPEN operations on the file. Clearfiles Total number of CLEARFILE operations on the file. Write to Locked Total number of WRITE operations executed against a locked record. Writes Blocked Total number of WRITE operations blocked by a record lock. ReadU lock conflict Total number of READU operations that failed because of an existing record lock. ReadL conflicts Total number READL operations that failed because of an existing record lock. Compression Total number of free operations that compacted a group after a record was deleted.
Running file diagnostics
Complete the following steps to run file diagnostics against a file. 1. From the File Tools window, select the file for which you want to run diagnostics, and click Diagnostics. A dialog similar to the following example opens:
2. In the Diagnostics Settings area, select the level of diagnostic detail you want to produce in the Level box. The lowest diagnostic level is 1, while the highest diagnostic level is 10. The default value is 5. The higher this level setting, the longer the diagnostics test takes to complete. Use the Level arrows to select the diagnostic level. 3. In the Diagnostics Settings area, select the types of errors you want to appear in the Error Report window. Select one of the following values: ▪ All - List all diagnostic details in the Error Report window.
183 Chapter 4: U2 Extensible Administration Tool (XAdmin)
▪ Fatal - List only fatal errors in the Error Report window. ▪ None - Do not list any errors in the Error Report window. 4. Optional: If you want to save a report of irreparable groups and record blocks detected by the diagnostic test, select Outpath, then enter the full path to a directory where you want to store the output. 5. Optional: If you want to store a copy of the error report, select Logging, then enter the full path to a directory where you want to store the report.
Note: If you do not specify Outpath or Logging, the output and error report are stored in the directory where the file currently resides.
6. Click Start to start the diagnostic program, or click Cancel to exit without saving changes. 7. After you run the diagnostics program, the Diagnostic Run dialog box displays the account name, the file name, and the progress of the program. It also displays the number of errors encountered and specifies what action to take if an error is detected. The following example illustrates the Diagnostic Run dialog box:
8. After repairing the damaged file, click Rerun to rerun the diagnostic program.
Repairing damaged files
Complete the following steps to repair damaged files.
184 Repairing damaged files
1. To run file diagnostics against a file, from the File Tools window, select the file you want to repair, then click Repair. A dialog box similar to the following example appears:
2. Use the File Repair dialog box to specify how much diagnostic testing to perform on the file, how much diagnostic detail to list in the error report window, and where to store output from the diagnostic test. 3. In the Diagnostics Settings area, select the level of diagnostic detail you want to produce in the Level box. The lowest diagnostic level is 1, while the highest diagnostic level is 10. The default value is 5. The higher this level setting, the longer the diagnostics test takes to complete. Use the Level arrows to select the diagnostic level. 4. In the Diagnostics Settings area, select the types of errors you want to appear in the Error Report window. Select one of the following values: ▪ All - List all diagnostic details in the Error Report window. ▪ Fatal - List only fatal errors in the Error Report window. ▪ None - Do not list any errors in the Error Report window. 5. If you want to save a report of irreparable groups and record blocks detected by the diagnostic test, select Outpath, then enter the full path to a directory where you want to store the output. 6. If you want to store a copy of the error report, select Logging, then enter the full path to a directory where you want to store the report. If you do not specify Output or Logging, the output and error report are stored in the directory where the file currently resides.
185 Chapter 4: U2 Extensible Administration Tool (XAdmin)
7. Click OK to save your changes and run the Repair program, or click Cancel to run the Repair program with default settings. The repair program starts. When the Repair program completes, a dialog box similar to the following example appears:
The File Repair dialog box displays the following information: ▪ The account name where the file resides ▪ The file name ▪ The current stage of the program ▪ The number of errors encountered ▪ What action to take if an error is found If an error is encountered, click the account name to display the Error Report window. 8. After you execute the Repair program, click Rerun to re-execute the program to ensure no errors remain in the file. 9. Click Cancel the exit the dialog box and return to the File Tool window. Repair the file if it is damaged. Administering UniData Files
To administer UniData files, choose File Tool from the Admin Tasks pane and then select the file command you want to work with. The File Tool window opens, as shown in the following Checkover example:
186 Listing files that are level 2 overflow
Listing files that are level 2 overflow
Use the Checkover tool to list all files that are in level 2 overflow.
Procedure
1. Select File Tools → Checkover from the Admin Tasks pane. The Checkover pane opens, as shown:
2. On the Checkover page, browse and select the directory for which you want to view the level 2 overflows. 3. Click Start. The overflow files are shown in the Result box.
187 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Administering the Convcode file tool
The system-level convcode command converts UniData object files from Motorola 68000 internal integer format. Format information is embedded within the file header. This command automatically determines if object files match the present machine integer format. If the files do not need to be converted, UniData displays a message that no files were converted. 1. Select File Tools → Convcode from the Admin Tasks pane. The Convcode pane opens, as shown:
2. Browse to the directory for the account you want to convert. 3. Click Start. The converted files are shown in the Result box.
Administering the Convdata file tool
The system-level convdata command converts UniData hashed data files from Motorola 68000 internal integer format to Intel 386 internal integer format. Format information is embedded within the file header. This command automatically determines if files match the present machine integer format. If files do not need to be converted, UniData displays a message that no data files were converted. You can run convdata more than once on a UniData file.
188 Administering the Convidx file tool
1. Select File Tools → Convdata from the Admin Tasks pane. The Convdata pane opens, as shown:
2. Browse to the directory for the account you want to convert. 3. Optional. Select the Convert sub-directories option if you want to process subdirectories recursively. Used only with the directory option. 4. Click Start. The converted files are shown in the Result box.
Administering the Convidx file tool
The system-level convidx command converts UniData index files from Motorola 68000 internal integer format to Intel 386 internal integer format. Format information is embedded within the file header. This command automatically determines if files match the present machine integer format. If files do not need to be converted, UniData displays a message to that effect. The system-level convidx command converts UniData hashed data files from Motorola 68000 internal integer format to Intel 386 internal integer format. Format information is embedded within the file header. This command automatically determines if files match the present machine integer format. If files do not need to be converted, UniData displays a message that no data files were converted. You can run convidx more than once on a UniData file. Static index files have a prefix of X_. Dynamic index files are named idx001, idx002,....
189 Chapter 4: U2 Extensible Administration Tool (XAdmin)
1. Select File Tools → Convidx from the Admin Tasks pane. The Convidx pane opens, as shown:
2. Browse and select the directory or file to convert. 3. Optional: If you specified a directory, select the Convert sub-directories check box to process subdirectories recursively. 4. Click Start. The converted files are shown in the Result box.
Converting ASCII values
The system-level convmark command searches for and converts ASCII values in UniData files.
190 Extracting readable records from corrupted files
1. Select File Tools → convmark from the Admin Tasks pane. The Convmark pane opens, as shown:
2. Browse to the file to convert. 3. Enter the correct Language Group ID. The language group ID is made up of the ASCII values that represent the record mark, the cursor control escape sequence, and the null value for that language group: ▪ 159/130/129 French, Japanese, and English ▪ 255/192/129 English ▪ 30/31/30 English, Simplified Chinese 4. Enter the original value in the Old value field and perform one of the following step:
▪ To count a value, do not use new_value. Convmark counts the occurrences of old_value. To convert a value, use new_value. Convmark converts from old_value. Must be a single ASCII value from 128 through 255. 5. Enter a single ASCII value from 128 through 255 in the New Value field. If new_value is already in the file, no conversion occurs. 6. Click Start. The converted files are shown in the Result box.
Extracting readable records from corrupted files
The system-level dumpgroup command extracts readable records from a specified group in a UniData file. If the file was corrupted, dumpgroup unloads only the complete, valid records, leaving behind any information it cannot read.
dumpgroup also creates a directory in the /tmp directory on UniData for UNIX or the \TEMP directory on UniData for Windows platforms for each dumped group. The directory is named FILE_GROUP, where FILE and GROUP are the file name and group number you specified. This directory contains an ASCII file for each record, so that you can check them for consistency before reloading the damaged file.
191 Chapter 4: U2 Extensible Administration Tool (XAdmin)
For more information about how to use dumpgroup to recover files, see Administering UniData.
1. Select File Tools → Dumpgroup from the Admin Tasks pane. The Dumpgroup pane opens, as shown:
2. Enter the following information:
Parameter Description File Name of the file that contains groups to be extracted. Group Number of the group to be dumped. Dump info file(-d) Directs output to outputfile.
Warning: Make sure outputfile is not the name of another item in your account. If it is, UniData will overwrite it.
Tip: This file is the input file for the fixgroup command. Convert non-printable(-p) Converts nonprinting field markers to printable characters in output file. Makes outputfile editable. This option is valid only with -d. 3. Click Start. The converted files are shown in the Result box.
If you execute dumpgroup without specifying an output file, the output simply displays on the screen. You will not be able to use that output to verify records or repair the damaged group.
If you do specify an output file, dumpgroup extracts readable records in uneditable form, suitable for reloading.
Administering the Filever file tool
The system-level filever command displays machine type(high-byte or low-byte) and file type (recoverable or non-recoverable).
192 Administering the Fixfile file tool
1. Select File Tools → Filever from the Admin Tasks pane. The filever pane opens, as shown:
2. Click Browse, and select the file to view. 3. Click Start.
Administering the Fixfile file tool
The system-level fixfile command displays machine type (high-byte or low-byte) and file type (recoverable or non-recoverable). 1. Select File Tools → Fixfile from the Admin Tasks pane. The fixfile pane opens, as shown:
2. Select the account name from the Account field.
193 Chapter 4: U2 Extensible Administration Tool (XAdmin)
3. Select the file name you want to repair from the File field. 4. Enter the damaged group number in the Group field. 5. Enter the correct information in the Options fields, as described in the following table.
Note: You must select the check box for each option to be included in the command.
Field Action Output file (-d) For each readable record, UniData creates an ASCII file in a directory in the current UniData account. UniData also takes the following actions for static and dynamic files: Static files – Stores readable records in (uneditable) outputfile. Dynamic files – Stores readable records in (uneditable) outputfile and in a subdirectory in the /tmp directory named filename_groupno on UniData for UNIX, or in the \TEMP directory on UniData for Windows platforms.
Note: To repair files, you must include both the -f parameter (to clear the group) and the -d parameter (to restore readable records). Fix corruption (-f) Clears damaged groups. Must be combined with the -d or -t parameters. Do not clear groups (-k) Does not clear records before reloading them, so that damaged records are retained in the file. Must be combined with the -d or -f parameters. ▪ To copy readable records to another file, include the -k and the -d parameters. ▪ To copy readable records to another file and return them to the file, include the -k, -d, and -f options. Convert non-printable(-p) Combine with the -d option to convert UniData delimiters and nonprinting characters in the ASCII files as follows: ▪ Attribute mark – New line ▪ Value mark – “}” ▪ Subvalue mark – “|” ▪ Text mark – “{“ ▪ Nonprinting – “.” Display only(-t) Record key and the record length are reported for each readable record. Directs output to the terminal only. All attributes in the record are listed, indented by two spaces. In the display, UniData delimiters and nonprinting characters are represented as follows: ▪ Attribute mark – New line ▪ Value mark – “}” ▪ Subvalue mark – “|” ▪ Text mark – “{“ n Nonprinting – “.”
Note: The -t and -d options are mutually exclusive. Message file(-m) Writes error messages and statistics to messagefile instead of the screen.
194 Administering the Guide file tool
Field Action Working directory(-w) Specifies directory for storing work files. Input file(-i) The file containing names of files and groups to be repaired.
inputfile is produced by the guide command. If you do not designate inputfile with guide, fixfile reads damaged file and group names from GUIDE_FIXUP.DAT in the current directory. The following describes the format of GUIDE_FIXUP.DAT: filenameM group_num ... filenameN group_num group_num group_num
Note: -iinputfile and filename group are mutually exclusive. 6. Click Start.
Administering the Guide file tool
The system-level guide command analyzes hashed files, generates statistics, and provides suggestions for optimizing file sizes and ensuring data integrity. UniData must be running when you execute guide. 1. Select File Tools → Guide from the Admin Tasks pane. The guide pane opens, as shown:
2. Select the file name you want to analyze from the File menu, or click Browse. Separate multiple file names with a space. You must have read and write access to these files. 3. Enter the correct information in the Option fields, as described in the following table.
Field Description Brief summary(-b) Summarizes file analysis in b_filename. Default file name is GUIDE_BRIEF.LIS.
195 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Field Description Stat level Reports on file size: 1 — Summarizes file size information. 2 — Reports file size information. This is the default. 3 — Adds information about distribution of data sizes.
Note: Cannot be used with the -ns option. #small rec(-s) Adds to information displayed by -d. Displays, in quotation marks, keys of smallest records. Key ends with * if truncated. count specifies number to list. Default is 3. -l — lists keys only -s — sorts and lists keys
Note: Must be combined with the -d option. # large rec(-s) Adds to information displayed by -d. Displays, in quotation marks, keys of largest records. Key ends with * if truncated. count specifies number to list. Default is 3. -l — lists keys only -s — sorts and lists keys
Note: Must be combined with the -d option. Output file(-o) Combines output in filename, rather than placing it in separate files. If filename is not specified, sends combined output to the standard output device. The default output device is the display screen. Advice file(-a) Default. Reports file management advice in a_filename. Default file name is GUIDE_ADVICE.LIS. Error file(-e) Default. Reports statistical errors in e_filename. Default file name is GUIDE_ERRORS.LIS. Stats file(-s) Default. Reports detailed statistical information in s_filename. Default file name is GUIDE_STATS.LIS. Fixup file(-f) Default. Reports damaged groups in f_filename. Default f_filename is GUIDE_FIXUP.DAT.
f_filename can be used as input for ECL commands fixfile, dumpgroup, and fixgroup. Hash type(-h) Evaluates hash algorithms of type: ▪ a — evaluates all supported hash types ▪ 0 ▪ 1 ▪ 3
Note: This option produces no output for dynamic files. Modulo check(-m) Analyzes the effects a different modulo would have on filename. Must be used with the -h parameter. Input file(-i) Analyzes all files listed in i_filename. Default file name is GUIDE_INPUT.DAT. In i_filename, list one file name per line. Blank lines and lines beginning with! are ignored.
196 Optimizing file size
Field Description Report file(-r) Directs output to UniData database r_filename. r_filename must be the system-level file name. Copy the dictionary for r_filename from udthome/sys/D_UDT_GUIDE (UNIX) or udthome\sys\D_UDTGUIDE (Windows). Later, you can run UniQuery commands against r_filename. #Child processes(-Z) Defines the number of concurrent processes to use when analyzing the file. The default is 4. If the file has fewer than 100 groups, guide only uses one process. Check char(-u) Searches files for the existence of the ASCII character you specify in the records and keys in the file. Saving File Load (-sfl) Updates the data file with the calculated fileload value. Applies to dynamic WHOLEFILE split-style files only. 4. Click Start. The results are shown in the Result box.
Optimizing file size
The system-level memresize command analyzes hashed files, generates statistics, and provides suggestions for optimizing file sizes and ensuring data integrity. UniData must be running when you execute memresize. 1. Select File Tools → Memresize from the Admin Tasks pane. The Memresize pane opens, as shown:
2. Select the file name you want to analyze from the File menu, or click Browse. Separate multiple file names with a space. You must have read and write access to these files. 3. Enter the correct information in the Options fields, as described in the following table.
Parameter Description File The name of the file to be resized. Modulo The new modulo number to be assigned to the file.
197 Chapter 4: U2 Extensible Administration Tool (XAdmin)
Parameter Description Block factor The size, expressed as a multiplier, of each group in a hashed file. If you specify a block size multiplier of 0, UniData creates 512-byte groups. A block size multiplier of 1 represents 1024 bytes, 2 represents 2048 bytes, and so on. For 32-bit files, the maximum block size multiplier is 16. If specifying a larger value, 16 will be used. For 64-bit files, the block size limit is '2 GB - 1' (2,147,483,647). Temp file path The path where UniData locates a working copy of the file during resizing. The default is /tmp on UniData for UNIX or %UDTHOME% \UDxx\TEMP on UniData for Windows platforms. This parameter has no effect if the resulting file is a dynamic file. Hash type Hash type for the resized file. Size in kilobytes of memory buffer used for the operation. memresize may perform faster with a larger memory allocation. The minimum size is 256K. The default on most systems is 8000K (8 MB). You can assign as much memory as is available on your system. For example, 12000 assigns 12 MB of memory to the memresize command. Restore Ignore file corruption that cannot be fixed, but continue resizing the file. Use this parameter when a file must be restored regardless of corruption. Static After resizing, the file is a static hashed file. Dynamic After resizing, the file is a dynamic hashed file. Whole File After resizing, the file is dynamic and the split/merge type is WHOLEFILE. The default split load is 75.
Note: This option is only available when Dynamic is selected. Key and data After resizing, the file is dynamic and the split/merge type is KEYDATA.
Note: This option is only available when Dynamic is selected. Key only After resizing the file is dynamic and the split/merge type is KEYONLY (the default).
Note: This option is only available when Dynamic is selected. Part file After resizing, file is a dynamic file. part_tbl is the path and file name of a previously established part table. memresize copies part_tbl into the dynamic file directory. The copy of part_tbl in the dynamic file directory serves as the “per-file” part table for the dynamic file. Note: This option is supported on UniData for UNIX only. 64-bit Sets the addressing type of the file to 64-bit mode. See details above for 32-bit vs 64-bit. 32-bit Sets the addressing type of the file to 32-bit mode. This is the default addressing type. 4. Click Start. The results show in the Result box.
Converting a file to a sequentially hashed file
The system-level shfbuild command is used to create a sequentially hashed file by converting an existing dynamic or static file. UniData must be running when you execute shfbuild. Each sequentially hashed file contains a static, read-only file that is called the gmekey file. This file is read
198 Converting a file to a sequentially hashed file into memory when you open a sequentially hashed file. The gmekey file contains information about the type of keys in the file (alphabetic or numeric), and controls which group a record is hashed to when it is written. 1. Select File Tools → Shfbuild from the Admin Tasks pane. The Shfbuild pane opens, as shown:
2. Select the file name you want to work with from the File menu, or click Browse. Separate multiple file names with a space. You must have read and write access to these files. 3. Enter the correct information in the Option fields, as described in the following table.
Parameter Description Append only(-a) Only rebuild the last group of the sequentially hashed file. UniData splits the last group into groups according to the records in the group. If you use this option, the outfile should be the name of the sequentially hashed file. Do not specify infile. Key file only(-k) Build the gmekey file only. If you use this option, outfile should be the name of the sequentially hashed file. Do not specify infile. UniData rebuilds the gmekey file according to the keys in each group of outfile. Numeric(-n)/ Force the outfile to be in numeric or alphabetic order. By default, the Alphabetic(-t) order of outfile is determined by the infile primary key type. If infile is a sequentially hashed file, UniData uses the same order in outfile. If infile is not a sequentially hashed file, the order of outfile is determined by the justification of the @ID of the infile dictionary record. If it is right justified, it is numeric. Otherwise, it is alphabetic. If you use the -a or the -k option, these options have no effect. Modulo(-m) Specifies the new modulo of outfile. Empty percent(-e) Empty percent. This percent is a number between 0 - 99 which indicates how much space in the rebuilt groups to reserve. UniData calculates the new modulo of the file from empty_percent and the number of records in the rebuilt groups. If you do not specify -e or -m, UniData rebuilds the sequentially hashed file according to the default empty percent of 20. Block size Specifies the block size of the sequentially hashed file in kilobytes. multiplier(-b) Input file(-) Load the contents from infile instead of outfile. infile can be any type of UniData file.
199 Chapter 4: U2 Extensible Administration Tool (XAdmin)
4. Click Start. The converted files are shown in the Result box.
Administering the Udfile file tool
The system-level udfile command converts a UniData file to or from recoverable state. 1. Select File Tools → Udfile from the Admin Tasks pane. The udfile pane opens, as shown:
2. Select the file name you want to convert from the File menu, or click Browse. Separate multiple file names with a space. You must have read and write access to these files. 3. Select one of the following options: ▪ Change to a recoverable file ▪ Change to a non-recoverable file ▪ Display current file status 4. Click Start. The converted files are shown in the Result box. Monitoring system activity in UniVerse
One of the more important jobs of the system administrator is to monitor activity on the system (such as disk use and CPU use) and to deal with bottlenecks and other potential problems before they impact users. This section describes ways to find out who is doing what in UniVerse and at the operating system level.
Listing active UniVerse processes and jobs
To view UniVerse processes, select Users from the Admin Tasks view in XAdmin. The Users window appears, as shown in the following example:
200 Terminating a process
Terminating a process
You can terminate a user or background process using XAdmin. 1. To terminate a user process, choose Users from the Admin Tasks view in XAdmin. a. Select the user from the Interactive Users list. b. Click Logout. c. At the confirmation message dialog box, click Yes. An attempt is made to log the user off the server. 2. To terminate a background process, choose Users from the Admin Tasks view in XAdmin. a. Choose the process from the Background Processes list. b. Click Logout. c. At the confirmation message dialog box, click Yes. The chosen process is immediately terminated and XAdmin is updated. Monitoring system activity in UniData
To view UniData processes, choose Users from the Admin Tasks view in the U2 Extensible Administration Tool. The Users window appears, as shown in the following example:
201 Chapter 4: U2 Extensible Administration Tool (XAdmin)
This window contains a snapshot of the user and background processes at the time the window was invoked. To view the current user and background processes, click Refresh. Click Kill to end a UniData session.
202 Chapter 5: U2 Metadata Manager
Use the U2 Metadata Manager (MDM) to view the dictionary, define metadata, and create 1NF maps of metadata files. MDM is helpful when you create SQL-compliant files for JDBC and ODBC applications. MDM is helpful when you create SQL-compliant files for JDBC and ODBC applications. A schema, in U2 terms, is a set of catalog tables that contain names of 1NF views that map U2 nested data into 1NF format and names and data types. Each U2 account is a separate namespace and therefore, it fits the definition of one schema. In U2, the term schema means the metadata that describes the U2 data. In SQL, a schema is a collection of database objects, such as tables, views, and indexes that share the same namespace. The U2 MDM perspective contains multiple panes, or views. From these views, you can view the dictionary, define metadata, and create 1NF maps of metadata files. UniData users can use the metadata files for data type enforcement (DTE). U2 MDM generates metadata based on existing dictionaries and dictionaries' relationship to the data files. If you are a UniData user, you can create a base for generating account-level repositories that are used for data type enforcement and take advantage of additional DTE capabilities. If you are a UniData developer, you can use DTE to specify the type of data expected for some or all data locations within a file. Then before writing data to a file, UniData inspects the locations to determine if the correct data types are used. If any data violates the specified data type, the database logs the violation and can prevent the write of the record, depending on the data type enforcement configuration for the file. Getting started
Prerequisites
Before you install U2 Metadata Manager, make sure that the you have completed the following prerequisites.
▪ If the account is UniVerse 11.1.10 or earlier, run the updaccount command to upgrade the VOC file, or the first time that you log into the account, click Yes in response to the prompt to update the VOC file.
▪ If you are using UniData VSG schema version 4000.00.01, you must run the MIGRATE.SQL command on the UniData files.
▪ You must run the MIGRATE.SQL command on the UniData account if it is not a new account and you have never run this command on the account.
▪ If the account was created on UniData 7.2 or earlier, you must run the updatevoc command to upgrade the VOC file.
▪ The udtconfig file must contain the QUOTED_IDENTIFIER=1 parameter.
Starting U2 MDM
Before you can create a metadata file or a 1NF map or schema, you must start the U2 Metadata Manager (U2 MDM).
203 Chapter 5: U2 Metadata Manager
Prerequisites ▪ Make sure that UniData or UniVerse services are currently running on the server computer.
Procedure
From the Windows Start menu, click All Programs → Rocket U2 → U2 Metadata Manager.
U2 MDM perspective
Once the Metadata Manager is installed, the U2 MDM perspective is displayed. The U2 MDM perspective contains multiple panes, called views. Views structure the workspace and serve as a device to organize similar items inside a defined work area. As an example, the U2 Resource view, the U2 MDM editor, and the U2 Dictionary view can all be open in the workplace at the same time. By default, the perspective is arranged in a standard layout, but you can move or resize views to suit your needs. Each view contains controls for minimizing and maximizing the space consumed within the U2 MDM perspective. You can also adjust the border of a view to increase or decrease its size. A view can contain one item or tabs for multiple items. After you close a view, you can select it from the Window menu to reopen it. You can also reset the main window to show all views in their default locations by clicking Window → Rest Perspective. The following figure highlights the different views found in the U2 MDM perspective.
U2 Resource view
The U2 Resource view contains an expandable tree view of all U2 servers that have been defined on your computer. You can connect to an existing U2 server or define a new one in this view. When you expand the tree view for a U2 server, the associated U2 accounts and catalog programs are shown in the list. By default, this view is located in the upper left pane of the U2 MDM workspace.
204 U2 MDM editor views
U2 MDM editor views
Graphical view The Graphics view displays both the metadata file and the 1NF map in a graphical representation of the files. The information is presented in two editable panes: Metadata and 1NF Map.
Pane Description Metadata The metadata pane is used to create the metadata you will use in your map file. You can use the editor to determine the data type that is mapped to each attribute in a file. You can view and modify the data using in either this graphical view or a text view. 1NF Map The 1NF Map pane uses the metadata information you defined to view and edit the tables and columns you want to expose in your 1NF map. You can view and modify the data using in this graphical view or a text view.
Metadata view The Metadata view gives you a text representation of your file's metadata. This pane is accessed by selecting the Metadata tab at the bottom of the U2 MDM editor, and allows you to view all of the fields representing the file in a table format, including their dictionary and metadata information. The metadata settings can be viewed and some settings can be altered.
The 1NF view The 1NF (first normal form) view allows you to view all of the tables and columns being exposed to the 1NF world in a table format, including their dictionary and metadata information. You can access this pane by selecting the 1NF tab at the bottom of the U2 MDM editor.
Options available in the Metadata view
Tip: You must save any changes to the editor before trying to do related tasks, such as generating a schema with the Schema Tool.
Metadata pane Use the metadata pane to create the metadata you will use in your map file. You can use the editor to determine the data type mapped to each attribute in a file. You can view and modify the data using either a graphical view or text view.
Graphical view The graphical view, accessed by selecting the Graphic tab at the bottom of the U2 MDM editor, contains a birds-eye view of the metadata, and the relationships between single valued and multivalued fields for a given file with the option to drill down and view the metadata or dictionary data for a given field. The metadata settings can be viewed and some settings can be altered.
Text view The text view, accessed by selecting the Metadata tab at the bottom of the U2 MDM editor, allows you to view all of the fields representing the file in a table format, including their dictionary and metadata information. The metadata settings can be viewed and some settings can be altered. The U2 MDM
205 Chapter 5: U2 Metadata Manager
Editor and the U2 Dictionary view are synchronized. Clicking a column in the 1NF view automatically exposes the dictionary field defining this column in the U2 Dictionary view.
Fields in the metadata graphical editor The graphical pane of the Metadata editor displays three columns of tables, corresponding to single valued fields, multivalued fields, and multi-subvalued fields. (Multi-subvalued fields are available in UniData only) The first column displays the single valued fields. These values have a dictionary SM value of "S". The second column displays the multivalued data. These fields have a dictionary SM value of "MV". The fields are grouped into boxes representing associations. This means that if a set of multivalued fields are related by an association, they are grouped together in a box with the association name as the title. If the named association is not present in the dictionary, or if the SM value for the field is MV and there is no ASSOC value set, the field displays in a box with the field name where the association title would normally be. This represents an unassociated multivalued data field, meaning that it is multivalued but not associated with any of the other multivalued data in the file. The last column displays the multi-subvalued data from UniData. These fields have a dictionary SM value of "MS" or "M". The fields in the column are grouped into boxes representing associations. If the multi-subvalued field is unassociated, a multivalued association appears in the column to the left. This multivalued association contains no fields. Each item in the graphical view contains a white arrow on the left side of the box. Clicking the arrow causes the box to expand or collapse, displaying more or less detail. The displayed details can be changed by right-clicking the title area and choosing either Show Metadata or Show DICT Field. Some of the data in the expanded area may be editable. If editable, the background color for the data cell is white. If not editable, the background color for the cell is gray. To edit, double-click any cell in an expanded box that has a white background.
Tip: You must save any changes that you make in the editor before trying to do a related task, such as generating a schema. When you make a change in the editor, the tab at the top will change, preceding the file name with an asterisk (*). This indicates the file's data has changed, but it has not yet been saved. To save the data, make sure that the editor has focus and click File > Save.
Fields in the metadata text editor In the metadata view, you can view and edit several fields in your metadata file.
Field name Description ID The dictionary field name representing this location for this file. This column cannot be modified. LOC The location (attribute) number in the file represented by this field. This column cannot be modified. Data Type The 1NF data type derived from any output conversion (CONV in the U2 Dictionary View) defined in the dictionary for the field. If the dictionary has no CONV value, the data type would be VARCHAR, representing a string of character data. If the CONV is MD0, the data type would be INT (integer), while MD2 would be FLOAT (a number containing a decimal point). In UniVerse, the SQL-type listed in dictionary position 8 (if one is specified) determines the data type.
206 Null values
Field name Description Enforced UniData only. Contains true and false values that indicate whether data type enforcement is used. If true, the data type for this field is examined by the database when new records are written to the file. Depending on the DTE settings on the server, records that violate the data type may be rejected. Only data types other than VARCHAR support the true setting for this column. Clicking the column heading presents a dialog allowing you to set all the enforceable (non-VARCHAR) data types to true or false in one operation. Nullable The true and false values that indicate whether or not a field can be set to the SQL NULL value. Location 0 (primary key field) can never have a value of true for nullable. Description Optional. The text describing the data field and is optional. Comments are not added to the dictionary field, but are added to the metadata repository about this field. If the record from the dictionary contained a comment after the initial "D" character in attribute 1 (for example, "D Warehouse identification number"), that comment will appear here. This field can be updated or created whether or not a comment was present in the dictionary when imported to this tool.
Null values Null values have the following characteristics in UniData SQL when null value handling is on: ▪ When used in any expression, the result of the expression is null. ▪ When compared to any other value, including itself, the result is false. The only way to compare a null value is to use the keywords IS [NOT] NULL. ▪ The null value is the lowest value.
Options available in the 1NF Map view
1NF Map pane The 1NF Map pane uses the metadata information you defined in the metadata editor to view and edit the tables and columns you want to expose in your 1NF map. You can edit the 1NF information either in a graphical view or a text view.
Graphical view To access the graphical view, click the Graphic tab on the U2 MDM editor. This view contains a 1NF Map view that provides a birds-eye view of the relationships between single-valued and multivalued tables and their columns for a given file. While in this view, you can view the column settings or dictionary data for a given column within the table. The 1NF settings can be viewed and some settings can be altered.
Text view Click the 1NF tab on the U2 MDM editor to view all of the tables and columns being exposed to the 1NF world in a table format, including their dictionary and metadata information. Unlike the graphical view, you cannot view the dictionary data from within the text view. To view the dictionary data, click the U2 Dictionary view. The U2 MDM Editor and the U2 Dictionary view are synchronized. Clicking a column in the 1NF view automatically exposes the dictionary field defining this column in the U2 Dictionary view.
207 Chapter 5: U2 Metadata Manager
Fields in the 1NF graphic pane The graphical pane of the 1NF map displays three columns of tables, corresponding to single valued fields, multivalued fields, and multi-subvalued fields (multi-subvalued fields are available in UniData only). The first column contains a single entry. It represents a table containing the single-valued fields you want to make available to 1NF. This table and its columns derive from the metadata single-valued fields. The center column contains the tables representing multivalued data. These tables correspond to the associations defined in the metadata. The last column contains the multi-subvalued data from UniData. These fields have a dictionary SM value of "MS" or "M". The fields in the column are grouped into boxes representing a table of associated data. Each of these tables correspond to an association in the metadata view. If the multi- subvalued field is unassociated, a multivalued association appears in the second column and contains no fields. A line between the columns connects the related MV and MS associations to give you a visual picture of the associations. Each item in the graphical view contains a white arrow on the left side of the box. Clicking the arrow causes the box to expand or collapse, displaying more or less detail. The displayed details can be changed by right-clicking on the title area and choosing either Show 1NF Map or Show DICT Field. Some of the data in the expanded are may be editable. If editable, the background color for the data cell is white. If not editable, the background color for the cell is gray. To edit, double-click any cell in an expanded box that has a white background.
Note: UniVerse only. When you create a schema, U2 MDM adds an @SELECT record in the dictionary that contains the fields included in the 1NF map. Field visibility in ODBC is determined by the fields in the @SELECT clause. For this reason, this record is created by U2 MDM according to the selections made in the wizard. This record is maintained by U2 MDM and should not be modified or deleted.
Tip: You must save any changes that you make in the editor before trying to do a related task, such as generating a schema. When you make a change in the editor, the tab at the top will change, preceding the file name with an asterisk (*). This indicates that the file's data has changed, but it has not yet been saved. To save the data, make sure that the editor has focus select File > Save.
Fields in the 1NF text view In the 1NF view, you can view and edit several fields in your 1NF map. Those fields are described below.
Field name Description Table/Column The name of the table or column as the 1NF world will see it. Name In UniData, this column is editable and you can change the names to any compliant name. Certain characters, such as "@" are not allowed. U2 database reserved words are also not allowed. For example, "TIME" and "DESC" are reserved words. If you enter an illegal character or reserved word, the editor will flag it with a warning icon. Hovering the mouse over the icon displays details about the problem. You must fix any problem names before you can successfully generate a schema. Column Dict The name of the dictionary field used to establish the column. This field is for reference purposes only and is not editable.
208 Generated Keys
Field name Description Column Data Type The data type as a 1NF application sees the column. U2 assumes a default length for VARCHAR data types of 254 characters. If a longer length is specified in the dictionary FORMAT field, for example, L500, then that value displays. Column Primary Contains true and false values. If true, the column represents key data. This can Key be the primary key field (location 0) or a key generated to support multivalued data tables. In UniVerse, multivalued tables contain a single generated key with a default column name of ASSOC_ROW. In UniData, multivalued tables contain a single generated key with a default column name of KEY_POS. This name can be changed, but only in the multivalued table's definition. Multi-subvalued tables sharing the key are automatically updated. Multi-subvalued tables share their related multivalued table's keys and contain an additional generated key with a default column name of MS_KEY_POS. This column name can be changed. Generated keys are necessary to unnest the multivalued data so that 1NF applications can view the U2 native nested data structures. For more information, see Generated Keys, on page 209. Column Key Pos The key number is for reference purposes only. If the field is a primary key, the column indicates the level of nested data this key controls. 0 - Primary key for the entire record. 1 - Primary key defining the multivalue being accessed. 2 - UniData only. Primary key defining the multi-subvalue being accessed. Column Optional. The text describing the data field. Comments are not added to the Description dictionary field, but are added to the metadata repository about this field. If the record from the dictionary contained a comment after the initial "D" character in attribute 1, for example, "D Warehouse identification number", that comment appears in this field. This field can be updated or created whether a comment was present in the dictionary when imported to this tool.
Note: UniVerse only. When you create a schema, U2 MDM adds an @SELECT record in the dictionary that contains the fields included in the 1NF map. Field visibility in ODBC is determined by the fields in the @SELECT clause. For this reason, this record is created by U2 MDM according to the selections made in the wizard. This record is maintained by U2 MDM and should not be modified or deleted.
Tip: You must save any changes that you make in the editor before trying to do a related task, such as generating a schema. When a change is made in the editor, the tab the top will change, preceding the file name with an asterisk (*). This indicates the file's data has changed, but it has not yet been saved. To save the data, make sure that the editor has focus and select File > Save.
Generated Keys A generated key provides uniqueness in cases where there is no unique key attribute in a table. In addition to serving as a unique record identifier, a generated key provides information about the order in which rows are stored. 1NF databases assume that the order of rows in a table is not important: every row is identified with the values of its attributes, not the order in which it is stored. In a UniData table though, the order in which values of a multivalued or a multi-subvalued attribute are stored within a record can be important. This type of list structure is not supported by 1NF databases.
209 Chapter 5: U2 Metadata Manager
Generated keys provide support for the list structures that exist in UniData and UniVerse tables. Tutorial
Use the U2 Metadata Manager to create metadata files, first normal form (1NF) maps, and schemas.
Creating metadata files
Use MDM to create a metadata file that contains an accurate description of your data files.
About this task The metadata file is later used to map your file to first normal form (1NF) to determine which synonyms to use in cases where multiple field aliases exist and to map field conversions and format specifications to the corresponding SQL data type.
Procedure
1. Open U2 MDM and navigate to the U2 Resource view. 2. Navigate to the UniData or UniVerse server to which the U2 MDM tool will connect. Right-click the name of the server, and click Connect. 3. Expand the Accounts node, and then expand Database Files. Select the file that you want to work with from the U2 Resource view. In this example, the Orders file is used. 4. Right-click the Orders file and select U2 Metadata Manager → Create New U2 MDM File. The Choose Dictionary Locations wizard starts. 5. Select the dictionary fields that you want to accurately represent each dictionary location in the selected file. For this example, accept the default selections. 6. Click Next.
Creating 1NF files
U2 files must be presented to JDBC or ODBC applications as a set of related first normal form (1NF) tables. To do this, you must create a 1NF map of your UniData or UniVerse data that will contain the 1NF tables.
Procedure
1. Select the fields and attributes that you want to include in your 1NF map. For this example, choose Select All. 2. Optional: (Available for UniData only). Select Automatically fix non-compliant table and column names if you want the U2 MDM tool to generate ODBC-compliant names. 3. Optional: Select Create schema to create a schema automatically when the wizard finishes. 4. Click Finish. Both the metadata file and the 1NF map open in the U2 MDM editor.
210 Choosing virtual attributes
In the metadata pane, each single valued, multivalued, and multi-subvalued (UniData only) field is grouped together in a graphical representation of the locations that you made available to first normal form. The 1NF pane displays the first normal form tables that you just created, along with the required primary key. If the Create Schema option was selected, then the schema tool will open behind the U2 MDM editor.
Tip: UniData only. In this example if the compliant name option is not selected, the @ID column name is not SQL-compliant and a warning symbol is displayed next to the column name. Select the white arrow next to the column name to expand the table properties, click in the Column Name text field, then enter ID. The name of the column changes to ID. All multivalued and multi- subvalued tables in the 1NF map reference this key field and now reflect the new column name. Click the Save icon to save your changes.
Choosing virtual attributes
The virtual attributes defined in UniData or UniVerse can be included in the metadata file.
Procedure
Select the virtual fields to include in the metadata file, and click Next.
Note: Virtual fields must be valid for the schema processing and for JDBC and ODBC access to succeed.
Creating schemas
After you define the 1NF map for your file, you can generate a deployable 1NF schema that you use to access JDBC or ODBC applications.
Procedure
1. In the U2 Resource View, navigate to the Metadata Repository files, and select the file to work with. 2. Right-click the file name and select U2 Metadata Manager → Schema Tools. 3. At the prompt, click Yes to generate a new schema. The Schema Data viewer opens, and displays the 1NF schema information comprising the schema on the server.
Tip: If the Create Schema option was selected when you created the 1NF map, and there were no errors during schema creation, the schema tool opens as a tab to the left of the U2 MDM editor for the currently selected file.
211 Chapter 5: U2 Metadata Manager
Data type enforcement
The following options are only available on UniData.
(Optional) Changing the data type enforcement
UniData only. After the wizard closes, your metadata files and 1NF map are visible in the U2 MDM editor, in either the Metadata pane or the 1NF pane. At the bottom of the U2 MDM editor are three tabs: Graphic, Metadata, and 1NF.
Procedure
1. If the ORDERS file is not already open, from the U2 Resource view, right-click the ORDERS file and click U2 Metadata Manager → Open U2 MDM Editor. 2. Select the Metadata tab from the bottom of the U2 MDM editor. 3. Locate the ORD_DATE field. In the Enforced column, select true to enable data type enforcement on the file. 4. Click File → Save to save your changes.
(Optional) Enabling data type enforcement
UniData only. After you have defined your data type enforcement changes in the Metadata editor, you need to apply those changes.
Procedure
1. In the U2 Resource view, navigate to the Metadata Repository files. 2. Right-click the ORDERS file, and click U2 Metadata Manager → Data Type Enforcement → Apply Metadata Settings. 3. Click OK.
Enabling data type enforcement in the graphical editor
This topic applies only to UniData. While viewing the data in the graphical view, you can turn data type enforcement on or off.
Procedure
1. Open U2 MDM. 2. From the U2 Resource view, right-click the database file and select U2 Metadata Manager → Open U2 MDM Editor. 3. From the U2 MDM editor, right-click a field name from the graphical view. 4. Select Show Metadata. 5. In the Enforced field, select True or False ▪ INTEGER (SMALLINT) ▪ NUMERIC (DECIMAL, FLOAT, REAL) ▪ DATE (D2, D4, and so forth) ▪ TIME
212 Enabling UniData data type enforcement in the metadata text editor
Example
The following example shows the DATE_OUT options are expanded, and the Enforced menu is shown.
Enabling UniData data type enforcement in the metadata text editor
UniData only. Data type enforcement can be turned on or off from within the metadata text editor.
Procedure
1. Open a file in the U2 MDM editor. 2. Select the Metadata tab. 3. In the Enforced field, turn data type enforcement on or off by selecting True or False from the drop down menu.
Example
The following example shows the DATE_OUT options are expanded, and the Enforced menu is shown.
213 Chapter 5: U2 Metadata Manager
Generating metadata and 1NF maps
A metadata file maps metadata to a 1NF file. In UniData, the metadata can provide data type enforcement on files. The metadata file specifies the synonym to use when multiple field aliases exist and maps field conversions and format specifications to corresponding SQL data types. To use a U2 file with JDBC or ODBC, you use U2 MDM to create a 1NF mapping of the data. The mapping defines a set of 1NF tables that represents the U2 data. The data itself remains in the original files.
Generating metadata files
Use the wizard to select the dictionary locations to include in the metadata file.
Procedure
1. In the U2 Resource view, right-click the file to work with and select U2 Metadata Manager → Create U2 MDM file. 2. For each dictionary location, select a dictionary field (D-type field) to represent the location. Locations that do not have dictionary fields are not available for metadata settings and 1NF mapping.
Note: 1NF mapping is a mechanism that enables data stored in UniData and UniVerse files to be viewed (read-only mapping) or updated (updatable mapping) by applications that operate on 1NF data. The applications assume that the data conforms to the 1NF model in which all attribute values are atomic.
3. Click Next to proceed to the next step, or select Finish to close the wizard.
214 Adding virtual fields to metadata
Note: If you click Finish after this step and do not proceed with the rest of the wizard, you will not be able to add any virtual fields to the metadata file or the 1NF map.
Results Creating metadata is done at an account level. When you generate metadata for the first time, a metadata repository file is created, which is the account level metafile. In UniData, this is the _METADATA_REPOSITORY_ file. In UniVerse, this is the &METADATA_REPOSITORY& file.
Adding virtual fields to metadata
After selecting the dictionary fields that define the physical locations of a U2 file, you have the option to include important virtual fields. If you choose to create a 1NF map, you can select the virtual fields you need to make available to 1NF applications. These virtual fields also provide a more accurate representation of the metadata available for your U2 file. The tool generates a valid SQL data type for these fields based on any conversion and format information in the field definition.
Procedure
1. After you click Next in the Metadata wizard, the Choose Virtual Attributes page opens. Select the virtual fields you want to include in the metadata for this file. If you make selection at the association level, then everything in the association is selected. 2. Click Next to proceed to the next step. If you do not want to generate a 1NF map, click Finish to close the wizard. Clicking Finish opens the U2 Metadata Manager editor containing only your metadata selections.
Results Virtual data is calculated during queries and does not physically reside in the U2 file, and so cannot support data type enforcement.
Generating 1NF maps
U2 files must be presented to JDBC or ODBC applications as a set of related first normal form (1NF) tables. To do this, you must create a 1NF map of your UniData or UniVerse data. 1. After you click Next in the Metadata wizard, the Choose 1NF Map Attributes page opens. Select the fields and associations to include in the 1NF map. 2. Optional: (UniData only). By default, table and column names are verified to ensure that they are SQL-compliant, and names that are not SQL-compliant are automatically fixed. If you do not want to fix non-compliant names automatically, clear the Automatically fix non-compliant table and client names check box. If you clear this check box, you must manually create SQL-compliant names before you generate the schema and use the 1NF map. 3. Optional: Select the Create schema check box to automatically create the schema when the wizard finishes. 4. Click Finish. The metadata file and the 1NF map open in the U2 MDM editor.
215 Chapter 5: U2 Metadata Manager
In the metadata pane, each single-valued, multivalued, and multi-subvalued field is grouped together in a graphical representation of the locations that you made available in first normal form. The 1NF pane displays the first normal form tables and the required primary key.
Note: If there are any problems with the file names, a yellow warning indicator is displayed. Hover over the indicator to display a description of the problem.
You can bypass the wizard and create a first normal form map based on the dictionary field choices. To do this, with the metadata file open in the Metadata graphical pane, select the fields and attributes that you want to include in your 1NF map, and then drag those files onto the 1NF Mapping view. After your metadata is generated, an entry is created in the metadata repository file containing information describing the fields that you previously selected. In UniData, this is the METADATA_REPOSITORY_ file. In UniVerse, this is the &METADATA&REPOSITORY& file. Editing data in U2 MDM
After you have created metadata and maps, you can view the files and edit your changes in the U2 MDM view. The default view is the Graphic view, which provides a graphical representation of the metadata files and 1NF maps. This is a more review-oriented representation of the information than the text view. You can also choose to view the metadata in a text editor. To view metadata as text files, click the Metadata tab, located on the bottom of the U2 MDM editor. To view 1NF maps as text files, click the 1NF tab. This is a more detail-oriented representation of the information than the Graphic view.
Editing files in the graphical editor
After you have created a metadata file or a 1NF map, you can edit this metadata.
Procedure
1. Open U2 MDM. 2. From the U2 Resource view, right-click the database file and click U2 Metadata Manager → Open U2 MDM Editor. The metadata pane displays the fields chosen to represent the data in the file. These fields display in containers related fields at the single-valued, multivalued, and multi-subvalued (UniData only) level. The 1NF pane displays the fields selected for exposure to 1NF tools as column names in table containers. Here again, each table contains related fields at the single- valued, multivalued, and multi-subvalued level, along with the related key information. 3. Make changes, and click File → Save.
Editing metadata table properties in the graphical view
While viewing your data in the graphical view, you can view your dictionary fields, view and edit metadata fields, and change your metadata field locations.
216 Editing 1NF table properties in the graphical view
Procedure
1. Open U2 MDM. 2. From the U2 Resource view, right-click the database file and select U2 Metadata Manager → Open U2 MDM Editor. 3. From the U2 MDM editor, right-click a field name from the graphical view. 4. Select one of the following options to view the data for the selected field: ▪ Choose field: Opens the Choose Dictionary Locations editor for that field. This option is only available when there are synonyms present for a given file's location. ▪ Show metadata: Shows the metadata for the selected field. ▪ Show DICT field: Shows the DICT information for the selected field. 5. Select one of the Show options to see an expanded view of the available data.
Next step You can also directly view and/or edit the table properties by selecting the white arrow next to the column name to expand the view. The metadata information is shown by default. When you expand the view, fields that can be edited have a white background, while fields that cannot be edited have a gray background.
Editing 1NF table properties in the graphical view
While viewing your 1NF data in the graphical view, you can rename the tables (UniData only), delete tables, edit, and delete fields in the current 1NF map, and view the DICT information for that field.
Procedure
1. Open U2 MDM. 2. From the U2 Resource view, right-click the database file and select U2 Metadata Manager → Open U2 MDM Editor. 3. From the U2 MDM editor, right-click a field name from the graphical view. 4. Select one of the following options to view the data for the selected field: ▪ Show 1NF Map: Shows the metadata information for the selected field. ▪ Show DICT Field: Shows the DICT information for the selected field. ▪ Delete: Deletes the selected table from the 1NF map. If the table has dependent tables, it cannot be deleted until the table that depends on it has been deleted. All multi-subvalued tables (UniData only) are dependents of the single-valued table. All multivalued tables are dependents of the single-valued table and a dependent of one multivalue table. The Delete option is context sensitive. For example, if a table name is right-clicked, the table is deleted; similarly, if a column name is right-clicked, then the column is deleted from the table. 5. Select a Show options to display an expanded view of the available data.
Next step To view or edit the table properties, select the white arrow beside the column name. By default, the 1NF map information is displayed. Editable fields have a white background.
217 Chapter 5: U2 Metadata Manager
Editing metadata files in the text editor
You can choose to edit your metadata files in a text editor. Any changes that you make in the text editor are immediately seen by the graphical editor as well, allowing you to work with your files in whatever way works best for you. While viewing your 1NF data in the graphical view, you can rename your tables, delete your tables, edit fields in the current 1NF map, and view the DICT information for that field.
Procedure
1. Open U2 MDM. 2. From the U2 Resource view, right-click the database file and select U2 Metadata Manager → Open U2 MDM Editor. 3. Open a file in the U2 MDM editor. 4. Click the Metadata tab, located at the bottom of the U2 MDM editor. 5. UniData only. In the Enforced field, you can turn data type enforcement on or off by selecting True or False from the drop down menu.
Example
The following UniData example shows metadata for the Customer account. In UniVerse, the Enforced column is not available.
Editing 1NF files in the text editor
Any changes made in the text editor are immediately seen by the graphical editor as well, allowing you to work with the files in whatever way works best. While viewing the 1NF data in the text view, you can rename tables and columns, delete tables, and edit description fields if you are using UniData. With UniVerse, you can delete tables and edit description fields.
Procedure
1. Open U2 MDM.
218 Working with schemas
2. From the U2 Resource view, right-click the database file and select U2 Metadata Manager → Open U2 MDM Editor. 3. Open a file in the U2 MDM editor. 4. Click the 1NF tab. A text editor opens and displays all of the available 1NF information 5. Click in a field to make changes. 6. Click the Save option from the Eclipse menu to save the changes.
Note: In UniVerse, table names or column names are un-editable.
Example
The following example shows metadata for the Customer account.
Working with schemas
UniData schema rules
The UniData schema rules follow a simple hierarchy of single values and multivalues. In general, single valued attributes will form one normalized ODBC table. Each association will form a separate child association table. Each non-associated field will form a separate child ODBC table. U2 MDM does not support schemas that contain the following elements: ▪ Views ▪ Multiple single-valued attribute subtables Virtual fields are supported in U2 MDM, and the Metadata wizard contains a virtual attributes section where you can select the virtual fields that will be included in the metadata. Virtual data is calculated during queries and does not physically reside in the U2 file, and so cannot support data type enforcement. Virtual fields must be valid for the schema processing and ODBC access to proceed.
219 Chapter 5: U2 Metadata Manager
Making your non-compliant UniData file names accessible
Beginning at UniData 7.3, UniData provides a QUOTED_IDENTIFIER configuration parameter. The configuration parameters are located in the udtconfig file located in the udthome\include directory.
Procedure
1. Open the udtconfig file, which is located in the udthome\include directory. 2. Confirm that the QUOTED_IDENTIFIER parameter is set correctly for your needs: ▪ When the value of QUOTED_IDENTIFIER is 1, identifiers can be delimited by double quotation marks, and literals must then be delimited by single quotation marks. This is the default setting. ▪ When the value of QUOTED_IDENTIFIER is 0, identifiers cannot be quoted, and literals can be delimited by either single or double quotation marks. If the file or field name is not SQL-compliant, enclose the file name in double quotation marks and it will be read without causing an error.
UniVerse schema rules
U2 MDM supports the PICK and IDEAL flavors of UniVerse files. The UniVerse schema hierarchy is determined by the rules that govern UniVerse SQL dynamic normalization. In general, all of the single valued attributes form one normalized ODBC table. Each association forms a separate child association table. Each non-associated field forms a separate child ODBC table. Fields that contain controlling or dependent attributes are mapped into a separate child table with a name that matches that of the controlling field name. To contain system information, U2 MDM creates the following account-level system tables: ▪ LC_TABLES ▪ LC_COLUMNS ▪ LC_ASSOC ▪ LC_FKEY All mapping tables use UVACCT as the schema name in the LC_xxx tables. For mapped UniVerse files, the name of the schema is always set to UVACCT. Virtual fields are supported. The virtual fields must be valid and pass the compile dictionary (CD) command; otherwise, JDBC and ODBC queries fail at runtime. For more information about SQL dynamic normalization for UniVerse, see the UniVerse SQL User Guide.
Generating schemas
After you define a 1NF map for a file, generate a deployable 1NF schema that can be used to access U2 data from JDBC and ODBC applications.
220 Viewing the schema
Prerequisites ▪ You must be the file administrator or the original owner of the file.
About this task When you create a schema, _SQLDEF files are created. These files are 1NF representations of the schema. After you create a schema, you change it. If you need to change the schema, you must generate a new one.
Procedure
1. In the U2 Resource view, navigate to the Metadata Repository files, and right-click the file to work with and select U2 Metadata Manager → Schema Tools. 2. From the schema tool, do one of the following actions: ▪ If there is no schema data present on the server, a pop-up opens asking if you want to generate schema using the existing 1NF map. Click Yes to open the 1NF editor. ▪ If a 1NF file does not already exist, you must create it manually by dragging the fields you want mapped from the metadata file onto the 1NF editor. Click Save from the Eclipse menu to save the file. ▪ If there is already schema data present on the server, a pop-up opens asking if you want to overwrite the existing server schema. Click Yes to overwrite the existing schema, or click No to cancel. The Schema Data viewer opens, and displays the 1NF schema information comprising the schema on the server. After you generate the schema, metadata and 1NF mapping choices are accessible through JDBC and ODBC applications.
Viewing the schema
After you create a schema, you may want to view the contents. 1. In the U2 Resource view, right-click the file name of the schema that you want to view from either the Database files or Metadata Repository files. 2. Select U2 Metadata Manager > Schema Tools. If you did not overwrite the schema with the new 1NF map data, the schema tool will warn you that it is opening the existing schema that might not be based on your current 1NF map. This only occurs if the 1NF map data has changes since the schema was last created.
Testing the schema
To verify that your schema files are SQL-compliant, use the schema that was generated from the 1NF map to run JDBC queries against the U2 database.
Procedure
1. Right-click the name of the schema to test and, select U2 Metadata Manager → Schema Tools. 2. On the Verify tab, enter a query in the SQL Statement field. 3. To specify the query, you can select columns from the table or enter a SQL statement.
221 Chapter 5: U2 Metadata Manager
4. Optional: In the Maximum records field, select the maximum number of records to return. 5. Click Execute SQL Statement. The results of the query are displayed in a table. 6. Optional: In the JDBC trace level field, select the information to log. The following table describes the different trace level options:
Trace level Description No logging Default. No trace. Log errors General error message Log variable values Data variable dump Log messages to/from Message passed to/from the server server Log data values Data shipped to/from the server Log method entry/exit Method's entry/exit
The MDM_jdbc_unidata.trace file is created in the directory where the U2MDM.exe file is located. In a default installation, this file is located in the C:\U2\U2Tools\v4 directory. a. Click View Trace to view the trace file.
Example
The following UniData example shows the results of a JDBC query that ran against the CLIENTS_PHONE_ITEMS_MV_SUB table.
Note: UniVerse only: Double quotes are added around all column and table names.
Creating metadata for a schema
Use the Metadata Repository wizard to create a metadata repository record from an existing schema.
222 Creating metadata for a schema
About this task Occasionally, you might need to create a metadata repository from an existing schema, for example if a schema was originally created in VSG (UniData only) or if a schema was created in U2 MDM and then the corresponding metadata repository was subsequently deleted. If a schema does not have corresponding metadata, then a metadata repository file must be created before the schema can be edited. The U2 MDM tool can take existing schema information and create a new metadata repository based on the information in the schema. To do this, U2 MDM provides a wizard that compares the information from the schema to that in the dictionary. When inconsistencies are found, the tool relies on the information in the dictionary file to create the metadata, as the metadata files must accurately reflect the dictionary definition contents. If a field in the schema is not in the dictionary, the field is not included in the metadata. If a location in the dictionary is not in the schema, the location must be represented in the metadata repository. Creation of metadata for these locations does not require the location's inclusion in the schema. If a virtual attribute exists in the dictionary, it can optionally be represented in the metadata.
Procedure
1. In the U2 Resource view, right-click the name of the file for which you want to create metadata, and select Schema Tools. If a schema exists without any corresponding metadata, a dialog box opens and asks if you want to proceed with the schema data. Click Yes. The Schema Data editor opens and the Create Metadata Repository button appears in the Eclipse toolbar. 2. Click the Create Metadata Repository button to start the wizard. 3. Select the Open the metadata editor when the wizard finishes check box if you want the metadata editor to open when the wizard steps are complete. Click Next to proceed through the wizard steps. The Metadata/Dictionary Conflicts page opens and displays a list of any conflicts between the schema information and that in the dictionary. The information in the metadata must match that in the dictionary, so any differences between the two will be changed to match that in the dictionary. 4. After reviewing the conflicts, click Next. The Schema Fields Not Found in Dictionary page opens and displays a list of fields found in the schema that are not in the dictionary. These fields will not be included in the metadata. 5. After reviewing the information, click Next. The Choose Dictionary Locations for Metadata page opens, listing only the dictionary locations that are not found in the schema and for which there are one or more dictionary fields describing that location. 6. Select a dictionary field to represent each location in the file and then click Next. The Choose Virtual Attributes page opens, listing any virtual fields in the dictionary that are not found in the schema. Virtual fields in the dictionary that are not included in the metadata cannot be exposed to 1NF tools. 7. Select the virtual fields that you want to include in the metadata and then click Finish.
Results After the wizard steps complete, the U2 MDM tool creates a metadata repository file based on the selections made in the wizard. In UniData, the metadata repository is called _METADATA_REPOSITORY_. In UniVerse, the metadata repository is called &METADATA_REPOSITORY&.
223 Chapter 5: U2 Metadata Manager
Synchronizing metadata repository with the dictionary
When new fields are added, changed, or removed in a dictionary after the file has been loaded into the metadata repository, the information in the metadata repository becomes out of sync with that in the dictionary. You need to refresh the information in the metadata to synchronize it with the dictionary. You can do this with the Metadata Synchronization wizard. The Metadata Synchronization wizard compares the information in the metadata repository to that in the dictionary. When inconsistencies are found, the tool relies on the information in the dictionary file to create the metadata. If a field in the metadata repository is not in the dictionary, the field is removed from the metadata. Conversely, if a location in the dictionary is not in the metadata, the location must be added to the metadata repository. If the dictionary contains a virtual attribute, you can choose whether to represent the attribute in the metadata.
Synchronizing the data using the Metadata Synchronization wizard
Use the Metadata Synchronization wizard to compare and update the metadata repository record from the information found in the dictionary.
About this task
Note: The wizard steps described in the procedure below contain examples of all possible conflicts that might be encountered when synchronizing a metadata repository from an existing dictionary. Depending on the information in the dictionary, some of these steps may not be visible.
Procedure
1. In the U2 Resource view, select the file for which you want to synchronize the metadata repository with the dictionary. 2. Right-click the file and then select Sync metadata with dictionary. 3. Select the Open the metadata editor when the wizard finishes check box if you want the metadata editor to open when the wizard steps are complete. Click Next to proceed through the wizard steps. The Metadata/Dictionary Conflicts page opens and displays a list of any conflicts between the schema information and that in the dictionary. The information in the metadata must match that in the dictionary, so any differences between the two will be changed to match that in the dictionary. 4. After reviewing the conflicts, click Next. The Metadata Fields Not Found in Dictionary page opens and displays a list of fields found in the metadata that are not in the dictionary. These fields will be removed from the metadata 5. After reviewing the information, click Next. The Choose Dictionary Locations for Metadata page opens, listing dictionary locations that are not found in the metadata and for which there are one or more dictionary fields describing that location. 6. Select a dictionary field to represent each location in the metadata and then click Next. The Choose Virtual Attributes page opens, listing any virtual fields in the dictionary that are not found in the metadata. Virtual fields in the dictionary that are not included in the metadata cannot be exposed to 1NF tools. 7. Select the virtual fields that you want to include in the metadata and then click Finish.
224 Enforcing data types
Results After the wizard steps complete, the U2 MDM tool updates the information in the metadata repository file based on the selections made in the wizard. In UniData, the metadata repository is called _METADATA_REPOSITORY_. In UniVerse, the metadata repository is called &METADATA_REPOSITORY&. Enforcing data types
UniData only. Beginning with UniData 7.3, UniData provides a data type check on data that you write to a file in an effort to avoid writing bad data to the database. This data type check is file-based. You can define the fields that you want to check in the metadata file. UniData then checks these fields for each record write. If a write fails, UniData reports the record ID and the data that failed the check. Data type enforcement provides logging and blocking of specific data that does not match the defined data type that had been previously defined through its metadata on a file-level basis. You can use ECL- level data type enforcement commands to measure or limit this data access. You can define the following data types to check: ▪ DATE (D2, D4, and so forth) ▪ TIME ▪ INTEGER (SMALLINT) ▪ NUMERIC (DECIMAL, FLOAT, REAL) The data type is determined by the conversion code in the dictionary record of the attribute, described in the following table:
Conversion code Data type Dn DATE MT TIME MD0 INTEGER (SMALLINT) MD2, MR2 NUMERIC (DECIMAL, FLOAT, REAL)
Selecting an attribute for data type enforcement
UniData only. To select an attribute on which to apply data type enforcement (DTE), use the U2 MDM tool.
Procedure
1. Start U2 MDM by clicking Start → All Programs → Rocket U2 → U2 Metadata Manager. 2. From the U2 Resource View, expand Accounts, and then expand the account where the file for which you want to define the DTE attributes resides. Drag the file name to the Metadata pane, or right-click the file name and select U2 Metadata Manager > U2 Metadata Manager > Open U2 MDM Editor. 3. Click the Metadata tab, and then select the attribute for which you want to enforce the data type. In the Enforced column, select True. 4. In the U2 Resource view, navigate to the Metadata Repository files. 5. Right-click the file that you want to apply the data type enforcement changes to, then select U2 Metadata Manager > Data Type Enforcement > Apply Metadata Settings. If you make changes
225 Chapter 5: U2 Metadata Manager
in the Metadata editor and attempt to apply those changes before you have saved the Metadata file, your changes will not be applied.
Creating and deleting a metadata list
UniData only. Use the CREATE.METADATA, DELETE.METADATA, and LIST.METADATA to create, delete, and view metadata.
CREATE.METADATA
UniData only. The CREATE.METADATA command creates a metadata list for a file from the account metadata repository file (_METADATA_REPOSITORY_) that contains all of the D-type attributes for which you want to enforce the data type. You can define only one definition for each location.
To use the metadata that you previously generated, issue the CREATE.METADATA command.
Syntax
CREATE.METADATA filename USING RESPOSITORY
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The hash file for which you want to define metadata to check USING REPOSITORY The name of the core mapping file that is generated from the U2 Metadata Manager
Example
The following example illustrates the CREATE.METADATA command:
:CREATE.METADATA INVENTORY USING REPOSITORY Metadata is created.
DELETE.METADATA
UniData only. The DELETE.METADATA command deletes a metadata list previously created for the file. The command also deletes the DTENF record.
Syntax
DELETE.METADATA filename
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The name of the file for which you created metadata.
226 LIST.METADATA
LIST.METADATA
UniData only. The LIST.METADATA command lists all of the D-type attributes and associations that were previously defined for the file name. The command also lists all of the metadata information that has been defined for this file.
Syntax
LIST.METADATA filename
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The name of the file for which you created metadata
Example
The following example illustrates the output from the LIST.METADATA command:
:LIST.METADATA INVENTORY Data for Column @ID Position: 0 Data Type: VARCHAR Type Enf: 0 dict info: 'INVENTORY' 10R S Data for Column INV_DATE Position: 1 Data Type: DATE Type Enf: 1 dict info: D4/ 'Inventory}Date' 10R S Data for Column INV_TIME Position: 2 Data Type: TIME Type Enf: 1 dict info: MTH 'Inventory}Time' 5R S Data for Column PROD_NAME Position: 3 Data Type: VARCHAR Type Enf: 0 dict info: 'Product}Name' 10T S Data for Column FEATURES Position: 4 Data Type: VARCHAR Type Enf: 0 dict info: 'Features' 30T S Data for Column COLOR Position: 5 Data Type: VARCHAR Type Enf: 0 dict info: 'Color' 10T MV LINE_ITEMS Data for Column QTY Position: 6 Data Type: INT Type Enf: 0 dict info: MD0 'Quantity' 6R MV LINE_ITEMS Data for Column PRICE Position: 7 Data Type: FLOAT
227 Chapter 5: U2 Metadata Manager
Type Enf: 1 dict info: MD2,$ 'Price' 10R MV LINE_ITEMS Data for Column REORDER Position: 8 Data Type: VARCHAR Type Enf: 0 dict info: 'Reorder}Point' 6R MV LINE_ITEMS Data for Association_0 Name: SingleValuedFields SM Type: S Data Type Enforcement 2-8 Field List: @ID INV_DATE INV_TIME PROD_NAME FEATURES Data for Association_1 Name: LINE_ITEMS SM Type: MV Field List: COLOR QTY PRICE REORDER
Data type enforcement (DTENF) commands
UniData only. UniData provides ECL commands for data type enforcement. These commands maintain the data type enforcement (DTE) list in the file property group (FPG) of the hash file. UniData provides a data type check on data that you write to a file in an effort to avoid writing bad data to the database. This data type check is file-based. You can define the fields that you want to check in the metadata file. UniData then checks these fields for each record write. If a write fails, UniData reports the record ID and the data that failed the check.
ENABLE.DTENF
UniData only. The ENABLE.DTENF command enables one or more items in a metadata list. You can generate or add items to the DTENF list that will be physically saved to the file property group (FPG) of the file. For WRITE operations, data type enforcement goes through the LOCLIST and returns an error when the first location fails the data type check.
Syntax
ENABLE.DTENF filename [ALL | FIELDLIST name_list | LOCLIST loc_list] [DTE.OPT {IGNORE | LOG | ON.ERROR}]
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The name of the file for which you want to enable data type enforcement. ALL Enable all fields in the _METADATA_REPOSITORY_ record. FIELDLIST name_list Enables the fields defined by name. name_list is defined as name1, name2, name3 ... LOCLIST loc_list Enables the fields by location. loc_list is defined as location1, location2, location3 ...
228 DISABLE.DTENF
Parameter Description DTE.OPT The error handling option to use when a data type enforcement check fails. Valid options are: ▪ IGNORE - UniData takes no action if the SET.DTELOG option is ON, and error is written to the DTE_acct_pid record. ▪ LOG - Write the error to the DTE_acct_filename record in the DTE log. ▪ ON.ERROR - Returns a WRITE error and sets an error status.
Use the ON.ERROR option in conjunction with the WRITE/ON ERROR statements in your BASIC program to detect the attribute location with data that is incompatible with your metadata. If the ON.ERROR statement executes, then use the INMAT() function to determine the attribute location of the incompatible data.
Example
The following example illustrates the ENABLE.DTENF command:
:ENABLE.DTENF CUSTOMER ALL DTE.OPT LOG DTE has not been added on file CUSTOMER
DISABLE.DTENF
UniData only. Use the DISABLE.DTENF command to delete items from the DTENF list. If the DTENF list is empty, UniData removes the list.
Syntax
DISABLE.DTENF filename [ALL | FIELDLIST name_list | LOCLIST loc_list]
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The name of the file for which you want to disable data type enforcement. ALL Disable all fields in the DTE list. FIELDLISTname_list Disables the fields defined by name. name_list is defined as name1, name2,name3 ... LOCLISTloc_list Disables the fields by location. loc_list is defined as location1, location2,location3 ...
LIST.METADATA
UniData only. The LIST.METADATA command lists all of the D-type attributes and associations that were previously defined for the file name. The command also lists all of the metadata information that has been defined for this file.
Syntax
LIST.METADATA filename
229 Chapter 5: U2 Metadata Manager
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The name of the file for which you created metadata
Example
The following example illustrates the output from the LIST.METADATA command:
:LIST.METADATA INVENTORY Data for Column @ID Position: 0 Data Type: VARCHAR Type Enf: 0 dict info: 'INVENTORY' 10R S Data for Column INV_DATE Position: 1 Data Type: DATE Type Enf: 1 dict info: D4/ 'Inventory}Date' 10R S Data for Column INV_TIME Position: 2 Data Type: TIME Type Enf: 1 dict info: MTH 'Inventory}Time' 5R S Data for Column PROD_NAME Position: 3 Data Type: VARCHAR Type Enf: 0 dict info: 'Product}Name' 10T S Data for Column FEATURES Position: 4 Data Type: VARCHAR Type Enf: 0 dict info: 'Features' 30T S Data for Column COLOR Position: 5 Data Type: VARCHAR Type Enf: 0 dict info: 'Color' 10T MV LINE_ITEMS Data for Column QTY Position: 6 Data Type: INT Type Enf: 0 dict info: MD0 'Quantity' 6R MV LINE_ITEMS Data for Column PRICE Position: 7 Data Type: FLOAT Type Enf: 1 dict info: MD2,$ 'Price' 10R MV LINE_ITEMS Data for Column REORDER Position: 8 Data Type: VARCHAR Type Enf: 0 dict info: 'Reorder}Point' 6R MV LINE_ITEMS Data for Association_0 Name: SingleValuedFields SM Type: S Data Type Enforcement 2-8
230 VERIFY.DTENF
Field List: @ID INV_DATE INV_TIME PROD_NAME FEATURES Data for Association_1 Name: LINE_ITEMS SM Type: MV Field List: COLOR QTY PRICE REORDER
VERIFY.DTENF
UniData only. The VERIFY.DTENF command checks the locations defined in the DTE list and generates a list of @IDs that contain invalid data types.
Syntax
VERIFY.DTENF filename
Parameters The following table describes each parameter of the syntax.
Parameter Description filename The name of the file for which you want to verify data types
Example
The following example illustrates the VERIFY.DTENF command. One record is selected because Robert is the value of the INV_DATE attribute, which is defined as a DATE datatype.
VERIFY.DTENF INVENTORY 1 records selected to list 0. > LIST INVENTORY INV_DATE INV_TIME PROD_NAME FEATURES COLOR PRICE QTY REORDER DI 09:26:59 Feb 24 2012 1 INVENTORY 56060 Inventory Date Robert Inventory Time 12:00PM Product Name Trackball Features Super Deluxe Model Color Price Quantity Reorder Difference Gray $98.99 494 70 424 1 record listed
SET.DTELOG
UniData only. The SET.DTELOG command enables or disables the DTE log. The name of the log file is DTE_acct_pid, and is located in the $UDTTMP directory.
Syntax
SET.DTELOG [ON | OFF]
Parameters The following table describes each parameter of the syntax.
231 Chapter 5: U2 Metadata Manager
Parameter Description ON Enables the DTE log file OFF Disables the DTE log file
INMAT function
UniData only. The INMAT function returns the following values for each the previously described functions: ▪ 0 – The command completed successfully ▪ Any positive integer– The command failed Deployment for UniData
UniData metadata repository
The _METADATA_REPOSITORY_ file is a UniData hash file that is on every account to which the U2 MDM tool has successfully connected. The _METADATA_REPOSITORY_ is a system file containing the U2 Metadata Manager's data regarding metadata and 1NF maps for an account's database files. This file should not be modified by anything but the U2 MDM tool. Modification to the file or its contents may corrupt the file and cause a loss of information needed by the U2 MDM tool.
Deploying a metadata map
Deploying the UniData metadata repository
The UniData _METADATA_REPOSITORY_ is the deployment mechanism for users to apply Data Type Enforcement (DTE) settings for an account's database files.
Prerequisites ▪ System requirements, on page 14
Procedure
1. Copy the _METADATA_REPOSITORY_ file to the destination account. 2. For each file that is contained in the _METADATA_REPOSITORY_ file and has DTE settings established, run the following ECL commands:
▪ DELETE.METADATA filename ▪ CREATE.METADATA filename USING REPOSITORY ▪ ENABLE.DTENF filename ALL
Next step To automate this task, use standard statements such as LIST, SORT, SELECT, and SSELECT and provide the file names to a program or paragraph. To verify any of the above commands, use the following commands:
232 Deploying a UniData metadata file
▪ LIST.METADATA filename ▪ LIST.DTENF filename
Deploying a UniData metadata file
If you use a test account to set up data-type enforcement, you can copy the changes that made in the test account to the live account if the dictionary files in the live account are identical to the test account using a paragraph similar to the following example. The following paragraph creates a pointer to the source file and runs another paragraph called DTE_SETUP to apply the DTE settings from the _METADATA_REPOSITORY_.
:AE VOC DTE_DEPLOY Top of New "DTE_DEPLOY" in "VOC". 001= PA 002= SETFILE <
The following code copies the item from the source repository to the local repository, creates the metadata, and enables DTE:
Sample Code
Top of New "DTE_SETUP" in "VOC". 001: PA 002: * 003: DISPLAY 004: DISPLAY -----Clearing any existing METADATA for <
233 Chapter 5: U2 Metadata Manager
Deploying a relational schema
There is a BASIC subroutine on the server that is used to deploy 1NF maps to another account. When you use the U2 MDM tool to successfully generate a schema, it creates a deployable file named filename_SQLDEF.
Procedure
1. Copy the filename_SQLDEF file from the account where you generated the schema and place it into the account folder where you want to deploy the schema (the destination account). 2. Use the SQLDEF_2_ODBC subroutine to generate a schema on the destination account. The SQLDEF_2_ODBC subroutine must be invoked from a BASIC program.
Example: Deploying a single SQLDEF file
You can generate a schema for a single file name that you have copied to the destination account.
About this task
Assume that the following sample code is located the BP folder in a file named SCHEMAGEN.
Procedure
1. From the ECL prompt, compile the program, as shown: :BASIC BP SCHEMAGEN 2. Run the program using a file name for which you have successfully generated a 1NF map in the U2 MDM tool, as shown: :RUN BP SCHEMAGEN STUDENT In this example, the STUDENT file is used. This step creates a STUDENT_SQLDEF file in the account directory. The STUDENT_SQLDEF file is copied to the account where the deployment is to occur.
Results
CMD = TRIM(@COMMAND) IF UPCASE(CMD[1,3]) = "RUN" THEN fn = 4 END ELSE fn = 2 END filename = FIELD(CMD, ' ', fn) CALL SQLDEF_2_ODBC(filename, errcode, errmsg) IF errcode = 0 THEN CRT 'Successfully generated the schema for file ':filename END ELSE CRT 'Failed to generate the schema for file ':filename CRT 'errcode: ':errcode CRT 'errmsg: ':errmsg END
234 Example: Deploying all SQLDEF files
Example: Deploying all SQLDEF files
In this example, you generate a schema for each filename_SQLDEF file that you copied to the destination account.
About this task
Assume that the following sample code is in the BP folder in a file named SCHEMAGEN_ALL.
Procedure
1. From the ECL prompt, compile the program, as shown: :BASIC BP SCHEMAGEN_ALL 2. Run the program using a file name for which you have successfully generated a 1NF map in the U2 MDM tool, as shown: :RUN BP SCHEMAGEN_ALL In this example, the STUDENT file is used. This creates a STUDENT_SQLDEF file in the account directory. The STUDENT_SQLDEF file is copied to the account where the deployment is to occur.
Results
EXECUTE "SELECT VOC WITH @ID LIKE '..._SQLDEF'" DONE = 0 LOOP READNEXT SQLDEF_NAME ELSE DONE = 1 UNTIL DONE DO SQL_LEN = LEN(SQLDEF_NAME) NAME = SQLDEF_NAME[1, SQL_LEN-7] PRINT "Generating schema for file: ":NAME CALL SQLDEF_2_ODBC(NAME, ErrCode, ErrMsg) IF ErrCode <> 0 THEN PRINT " ":ErrMsg END REPEAT
Deployment for UniVerse
UniVerse metadata repository
The UniVerse &METADATA_REPOSITORY& is a UniVerse hash file that is on every account to which the U2 MDM tool has successfully connected. The &METADATA_REPOSITORY& is a system file containing the UniVerse Metadata Manager's data regarding metadata and 1NF maps for an account's database files. This file should not be modified by anything but the UniVerse MDM tool. Modification to the file or its contents may corrupt the file and cause a loss of information needed by the UniVerse MDM tool.
235 Chapter 5: U2 Metadata Manager
Deploying a schema for UniVerse
There is a BASIC subroutine on the server that is used to deploy 1NF maps to another account. When you use the U2 MDM tool to successfully generate a schema, it creates a deployable file named filename_SQLDEF.
Procedure
1. Execute the LC.INIT program in the destination account. 2. Copy the filename_SQLDEF file from the account where you generated the schema and place it into the account folder where you want to deploy the schema (the destination account). 3. Use the SQLDEF_2_ODBC subroutine to generate a schema on the destination account. The SQLDEF_2_ODBC subroutine must be invoked from a BASIC program. 4. On the destination machine, define the account in HS.SALES. 5. Test the deployment using an ODBC client.
236 Chapter 6: U2 RESTful Web Service Developer
Use the U2 RESTful Web Services Developer to define and publish U2 resources, such as data files and subroutines, to a U2 REST server. Then access those resources in a RESTful manner. Representational State Transfer (REST) defines a software architecture style of networked systems such as the World Wide Web, and is a popular way to build Web services. Systems that follow REST principles are often referred to as RESTful. A RESTful web service, or RESTful web API, is a software system that supports machine-to-machine interactions that use Hypertext Transfer Protocol (HTTP). In a RESTful system, a client uses a Universal Resource Identifier (URI) to request a specific resource from a server. The server responds by sending a representation of the requested resource. U2 RESTful web services provides a resource-oriented view of the data and subroutines in U2 databases and supports simple, lightweight, HTTP-based access to these resources. The U2 RESTful web services are ideal for developing browser-based and mobile applications.
Principles of a RESTful system RESTful systems typically adhere to the following design principles: ▪ A URI identifies each resource. ▪ Hyperlinks are used for navigation. ▪ Standard HTTP GET, PUT, POST, and DELETE methods are used on the resources. ▪ Server resources can have multiple representations, such as JSON and XML. ▪ Stateless communication ensures scalability .
RESTful web services A RESTful web service exposes many resources (URIs), but accepts a fixed set of methods (HTTP GET, PUT, POST, and DELETE). All operation details are included in the HTTP request. A RESTful web service offers a resource-based interface to the service consumers. A RESTful web service has a uniform interface and always uses HTTP GET, PUT, POST, and DELETE requests on the resources. In a RESTful system, all meaningful resources, such as web pages, blog entries, pictures, and data records are identified by a URI or URL. These resources contain URIs to other related resources and resources that contain specialized information. U2 RESTful web services
U2 RESTful web services (U2 REST) consists of a U2 REST server and the U2 RESTful Web Services Developer, which is an Eclipse-based development tool. Using U2 REST, you can quickly and easily expose U2 data and subroutines as RESTful resources that are accessible through the environment that you use to debug and deploy web services. U2 REST offers SSL support for secure communications and HTTP-based user authentication and authorization. Optimistic concurrency control and connection pooling are also supported to provide greater accessibility. U2 REST supports JavaScript Object Notation (JSON), which is a lightweight data-interchange format that is part of the JavaScript language specification and is supported by all Internet browsers.
237 Chapter 6: U2 RESTful Web Service Developer
Using the U2 RESTful Web Services Developer, you can define and publish U2 resources, such as data files and subroutines, to a U2 REST server. After the resources are published, they can be accessed in a RESTful manner. Using the Web Services Developer, you can start and stop a local RESTful server and stop a remote RESTful server. Using .sh and .bat files, you can manually start and stop the RESTful servers. A server log is provided to aid in debugging and tracing. You can quickly turn the server log on and off in the U2 RESTful Web Services Developer, and view the log results directly within the developer. If the server response is not what you expect, you can re-run the operation and turn on the log. U2 REST server
The U2 REST server is built on top of the Jetty HTTP server. It includes a U2 resource handler that processes HTTP requests for defined U2 REST resources. The U2 resource handler calls the U2 Java Persistence API (U2JPA), via a UniObjects for Java (UOJ) call to complete data and subroutine requests to the database server. The U2 resource handler converts native U2 data formats, or dynamic arrays, into human-readable formats such as JSON. The following illustration shows the architecture of a U2 RESTful system and its relationship with a U2 database:
Figure 1: U2 REST architecture
In a U2 RESTful system, the client computer uses a secure HTTP connection to connect to the U2 REST server. The U2 REST server uses the U2JPA to connect to the U2 database. U2 REST servers use U2JPA connect to the database through a UniObjects for Java connection or an UniObjects for Java (SSL) connection.
U2 REST resources
U2 REST resources are defined on the U2 REST server and are accessible through HTTP requests. There are two types of U2 REST resources: data resources and sub-resources. In U2, a REST data resource is a Java Persistence API (JPA) that maps fully or partially to a data field. Therefore, the value of a data resource is always a string, even if the dictionary conversion code specifies a non-string type.
A data resource is a primary top-level resource or a sub-resource. A primary resource corresponds to a data file, and a sub-resource corresponds to a data file association. A primary resource typically contains collections of sub resources. A sub-resources can contain a collection of other sub-resources. For example, the HS.SALES Customer resource is a primary resource that maps to the CUSTOMER file. The HS.SALE Customer resource contains a collection of sub-resources, including the Order resource, which corresponds to the ORDER association. The Order resource, in turn, contains a collection of sub-
238 REST resource folders
resources, including Item, which represents all of the items in a single order and includes all of the multi-subvalue fields in the ORDER association.
Foreign resources A referenced primary resource is a foreign resource to the host data source. Foreign resources can contain references to other primary resources. The references correspond to the TRANS () virtual fields in the host data file. In the preceding example, the sub-resource Item references the primary resource Product, which is mapped to the PRODUCT data file that contains the detailed information about an ordered product.
Virtual fields A data resource can contain D-type fields and V-type fields. A V-type, or virtual, field contain virtual information that is calculated or derived from an attribute, field, or other information in the database. The result of a virtual field is information that does not actually exist in the data portion of a file. In the preceding example, instead of referencing the Product resource, the sub-resource Item can include several TRANS () virtual fields that read data from the PRODUCT data file. Because the item sub-resource contains the product information, reading the Product resource is necessary.
REST resource folders
REST resources are grouped under the resource folders on the REST server. A resource folder maps to a U2 account on the database server, which is where the REST server accesses data and calls subroutines. A resource folder contains properties such as the host server name or IP address, UniRPC service name, UniRPC port number, account path, database user name and password, and SSL options. TheREST server to uses this information to complete the request for database access.
URI addresses
A REST resource URI is designed to impart the resource location, the resource type (data or subroutine), and any parent-child relationships. Each resource address contains three distinct parts: the REST server URI, the Resource folder name, and the relative path of the URI. The three parts of the resource address are separated by a forward slash, “/”, and are described below: ▪ REST Server URI: Each REST server listens on a unique port number on the server machine. A REST server URI is an HTTP URL, and is formed by combining the host name or IP address with its port number, as shown: http://myserver:9191 or https://myserver:9191
Note: The REST server URI cannot be accessed directly.
▪ Resource folder name: The name of a resource folder that maps to a database account such as HS.SALES. The resource folder can be accessed via its URI using the HTTP GET method. This results in a list of URIs of all the top-level data resources in the folder.
239 Chapter 6: U2 RESTful Web Service Developer
▪ Relative paths For data resources: ▫ For a collection-type resource, use the data resource name, as shown in the examples below: http://myserver:9191/HS_SALES http://myserver:9191/HS_SALES/CUSTOMER http://myserver:9191/HS_SALES/CUSTOMER/2/ORDERS Each of the above examples returns a list of the requested resources, such as CUSTOMER or ORDERS, in JSON. In a single primary resource, add the ID value after the data resource name, as shown: http://myserver:9191/HS_SALES/CUSTOMER/2 The above example returns a JSON object representing a Customer with an ID of 2. For a single sub-resource, include the resource’s position in the association after its name, as shown: http://myserver:9191/HS_SALES/CUSTOMER/2/ORDERS http://myserver:9191/HS_SALES/CUSTOMER/2/ORDERS/2 Sub-resources must always be accessed under a single top-level resource. ▫ For Subroutines: In order to distinguish subroutines from data resources, the relative path of a subroutine must always begin with the word subroutine, followed by its name, as shown: http://myserver:9191/HS_SALES/subroutine/CalculateCharge The HTTP POST method is the only method that can be used to call a subroutine. The U2 REST server checks for the HTTP POST method on a subroutine URI before further processing occurs. URI encoding must be applied on the resource URI in the HTTP request to U2 REST server. This is to avoid having URI-reserved delimiters in the text contained in the resource URI. For example, if a resource ID contains any of the following characters: “:, /,?, #, &, space” then the URI must be URI-encoded before sending the HTTP request to the U2 REST server. The U2 REST server decodes the URI to get the correct resource ID. In the example below, the product ID contains an illegal “#” character: http://myserver:9191/HS_SALES/CUSTOMER/Product/12#345 The U2 REST server sees the URI-reserved delimiter and decodes it using the standard %23 replacement, as shown: http://myserver:9191/HS_SALES/CUSTOMER/Product/12%23345
U2 REST subroutine resources
U2 subroutines implement all of the server-side business logic of U2 applications. A subroutine must be cataloged, either locally or globally, on the U2 server and then mapped on the REST server. The resource then becomes a U2 REST subroutine resource and can be called by a service consumer. You can map a subroutine on the REST server by defining its parameters.
Subroutine parameters You can use a subroutine parameter for input only, output only, or for both input and output purposes. Subroutine parameters can be one of three data types: strings, dynamic arrays, or JSON. A string type is a series of characters that is enclosed in double quotes. Dynamic array parameters must reference a dynamic array definition. A dynamic array definition describes the structure of the dynamic arrays it represents. In a U2 dictionary, it does this by specifying all the fields contained in the dynamic array
240 HTTP methods (U2 REST)
and also their value types and associations. The input and output JSON objects that move to and from the subroutine must be correctly formed JSON objects. It is expected that the U2 Dynamic Object (UDO) will be used to consume and present the JSON object both to and from the subroutine, which will ensure the correct JSON format is used. For more information about the U2 dynamic object, see UniData UniBasic Extensions
Note: If connection pooling is enabled, any change to a cataloged subroutine requires the connection pool to be restarted. It is suggested that connection pools be disabled during basic subroutine development.
HTTP POST The HTTP POST method is the only HTTP method that can be used to call a subroutine; however, for testing purposes you can issue a GET request and will be prompted for input to execute a POST request. In a RESTful definition, you can use HTTP POST to create a resource on the server. You can also use an HTTP specification to send information to a Web server, such as submitting a Web form. If the requested subroutine has input parameters, including parameters for both input and output purposes, the content of the HTTP POST request must contain a JSON object that includes all of the input parameters and their values. Missing input parameter values are treated as empty strings. If the subroutine has output parameters, including parameters for both input and output purposes, the content of the HTTP response will contain a JSON object that includes all of the output parameters and their values.
Note: If you are using SSL and want to make a subroutine resource available in a new U2 RESTful web server, you must first create a dummy data resource for the RESTful service to work. This requirement is a permanent restriction of the U2 RESTful web service.
HTTP methods (U2 REST)
U2 REST supports the following HTTP methods: GET (read), PUT (update), POST (create or call subroutine), and DELETE (delete). You can use the PUT, POST, and DELETE methods only on a single data resource, not a collection. U2 REST does not support batch operations, which group multiple requests into one HTTP POST request.
HTTP GET method
The HTTP GET method can only be used on U2 REST data resources. The following example illustrates a typical BASIC CallHTTP GET request. The request uses a GET statement to call the U2 REST server, and returns the customer record that corresponds to the specified customer record ID.
logfile = "restget" stat = protocolLogging(logfile, "ON", 10) PRINT "Which customer record ID do you want to get?" INPUT CUSTID * * URL returned as html or json data * url="http://den-l-nk01.rocketsoftware.com:9191/HS_SALES/Customer/":CUSTID:"?tohtml= true" url="http://den-l-nk01.rocketsoftware.com:9191/HS_SALES/Customer/":CUSTID method="GET"
241 Chapter 6: U2 RESTful Web Service Developer
* stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = setRequestHeader(restGET, "Content-Type", "application/json;charset=utf-8") stat = submitRequest(restGET, 5000, "", Header, restData, httpStatus) * GET response parser restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * a = protocolLogging(logfile, "OFF", 10) END
In the above example, the HTTP function is called to perform the HTTP GET request. Then, create a simple parser for display purposes. The output of our GET request, which displays the information for CUSTID 2, is shown below:
{ @uri: http://den-l-aw03:9191/HS_SALES/Customer/2?tohtml=true statename: "Massachusetts" state: "MA" u2version: "8258654354592452458" fname: "Diana" city: "Waltham" lname: "Morris" sal: "Ms." phone: "(617)555-9823" fulladdr: "431 Third Ave." custid: "2" fullname: "Ms. Diana Morris" addr1: "431 Third Ave." ... }
Data Selection, Sorting, and Paging with HTTP GET Different query strings can be specified on a URI using the HTTP GET method to shape or alter the return results.
Note: All HTTP GET query string keywords, such as select, sort, field, etc., must be made using lowercase commands.
Selection U2 query conditions can be specified on a primary REST data resource to limit the return results to only those that meet the conditions, as shown in the examples below:
http://myserver:9191/HS_SALES/Customer?select=ZIP="01382" &tohtml=true
http://myserver:9191/HS_SALES/Customer?select=ZIP="01382" AND fname LIKE "S..."&tohtml=true
http://myserver:9191/HS_SALES/Customer?select=ZIP="01382""75201" "80202"
242 HTTP GET method
U2 query SORT expressions (except BY.EXP and BY.EXP.DSND) can be applied on top-level REST data resources to put the return results in certain order, as shown in the examples below:
http://myserver:9191/HS_SALES/Customer?sort=BY fname
http://myserver:9191/HS_SALES/Customer?select=fname LIKE “D...”&sort=BY.DSND LNAME&tohtml=true
In order for these query strings to work, the query itself must follow the uQuery conventions for the account. The selection attributes must follow the dictionary conventions, including case.
Note: For best results, enclose selection criteria in quotation marks.
Projection Projection limits the return results on a data resource to only a few specified fields, instead of all of them, as shown below:
http://myserver:9191/HS_SALES/Customer?fields=lname, fname
Paging Two sets of query string parameters can be used to specify the desired starting position and the size of data returned, described in the examples below. In the first example, we use the pageno and pagesize parameters to specify that the default page size is 20 and the minimum pageno is 1, as shown:
http://myserver:9191/HS_SALES/Customer?pageno=3&pagesize=20
In this next example, we use the start and max parameters to specify that the default start value is 0, and the default max value is 20, as shown:
http://myserver:9191/HS_SALES/Customer?start=0&max=20
Detail level The detail_level query string parameter is used to determine the level of nesting in a query. U2 REST supports the detail_level parameter, and uses it to expand or collapse the return results. The value of the detail_level is either 1, 2, or 3. The default value is 3. Each value is described in the following table:
detail_level Description 1 Top-level resources in the query 2 Top-level, multivalue resources in the query. 3 Top-level, multivalue, multi-subvalue resources in the query.
In the following example, the detail_level is set to 3, as shown:
http://myserver:9191/HS_SALES/Customer/2?detail_level=3
The query then returns all the data, including the multi-subvalue information and the Orders information nested within the order _list association:
{ @uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2? detail%5Flevel=3&tohtml=true company: "Fast Copy Center"
243 Chapter 6: U2 RESTful Web Service Developer
zip: "01133" addr2: "" addr1: "431 Third Ave." -orders_list: { @uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2/Orders -Orders: [ -{ @uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2/Orders/1 list_price: "$6,890" ser_num: "600782" svc_price: "$900" svc_start: "01/13/91" u2version: "8258654354592452458" paid_date: "02/05/91" buy_date: "01/08/91" description: "Moderate duty, entry level, color copier" svc_end: "01/15/92" svc_paid_date: "02/05/91" prodid: "C2000" price: "$6,600" discount: "4.2" } -{ @uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2/Orders/2 list_price: "$12,990" ser_num: "700422" svc_price: "$500" svc_start: "01/13/91" u2version: "8258654354592452458" paid_date: "02/05/91" buy_date: "01/08/91" description: "Heavy duty monochrome copier" svc_end: "06/12/91" svc_paid_date: "02/05/91" prodid: "M3000" price: "$12,000" discount: "7.6" } -{ @uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2/Orders/3 list_price: "$1,990" ser_num: "101456" svc_price: "$150" svc_start: "01/13/91" u2version: "8258654354592452458" paid_date: "02/12/91" buy_date: "01/22/91" description: "Sorting attachment for M3000/C3000" svc_end: "01/15/92" svc_paid_date: "02/12/91" prodid: "S3000" price: "$900" discount: "54.8" } ] } fullname: "Ms. Diana Morris" custid: "2" fulladdr: "431 Third Ave." phone: "(617)555-9823" sal: "Ms." city: "Waltham"
244 HTTP POST method
lname: "Morris" fname: "Diana" u2version: "8258654354592452458" state: "MA" statename: "Massachusetts" }
If we change the URI in the above HTTP GET request to detail_level = 1,
http://myserver:9191/HS_SALES/Customer/2?detail_level=1
we see a much smaller result set that includes only the top-level field values and references, as shown:
@uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2?detail %5Flevel=1&html=true company: "Fast Copy Center" zip: "01133" addr2: "" addr1: "431 Third Ave." -orders_list: { @uri: http://den-l-aw03.rocketsoftware.com:9191/HS_SALES/Customer/2/Orders } fullname: "Ms. Diana Morris" custid: "2" fulladdr: "431 Third Ave." phone: "(617)555-9823" sal: "Ms." city: "Waltham" lname: "Morris" fname: "Diana" u2version: "8258654354592452458" state: "MA" statename: "Massachusetts" }
HTTP POST method
The HTTP POST method is used to create a new data record or to call a BASIC subroutine. The following example demonstrates how to use the BASIC CallHTTP POST request. In this program, we call the U2 REST server using an HTTP POST request. The request uses postData information to create a new record based on the CUSTID parameter. An HTTP GET request automatically runs when the request completes.
* logfile="restpost" url="http://den-l-nk01.rocketsoftware.com:9191/HS_SALES/Customer" * method="POST" * stat = protocolLogging(logfile, "ON", 10) stat = setHTTPDefault("VERSION", "1.1") * * postData json record * PRINT "Enter Unique Customer ID to create: " INPUT CUSTID * * Customer Record to be written to record CUSTID * postData=""
245 Chapter 6: U2 RESTful Web Service Developer
postDATA='{' postDATA:=' "statename" : "Colorado",' postDATA:=' "state" : "CO",' postDATA:=' "fname" : "Neddy",' postDATA:=' "city" : "Denver",' postDATA:=' "lname" : "Seagoon",' postDATA:=' "sal" : "Mr.",' postDATA:=' "phone" : "8007293553",' postDATA:=' "custid" : "':CUSTID:'",' postDATA:=' "addr1" : "4700 South Syracuse Street",' postDATA:=' "addr2" : "",' postDATA:=' "zip" : "80237",' postDATA:=' "company" : "IBM Corporation."' postDATA:='}' * CRT stat = createRequest(url, method, restPOST) stat = setRequestHeader(restPOST, "Content-Type", "application/json; charset=utf-8") stat = submitRequest(restPOST, 5000, postDATA, Header, restData, httpStatus) * POST response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfile, "OFF", 10) restPOST="" END
Using HTTP POST to call a subroutine resource An HTTP POST request must point to the resource URI when it is used to call a subroutine. The body of the HTTP POST request must include one unnamed JSON object that includes all the input parameters and their values. If the subroutine has output parameters, the U2 REST server sends back an HTTP response whose body contains an unnamed JSON object that encompass all of the output parameters and their values. The following example illustrates how to use HTTP POST to call a locally cataloged subroutine:
a = protocolLogging("httpreq.log", "ON", 10) * call the REST subroutine service with HTTP POST url="http://DEN-L-AW01.rocketsoftware.com:9191/HS_SALES/subroutine/CUSTOMERSUB" method="POST" a = setHTTPDefault("VERSION", "1.1") a = createRequest(url, method, req4) a = setRequestHeader(req4, "Content-Type", "application/json; charset=utf-8") postData = '{"id":"2"}' Header = "" Data = "" httpStatus = "" a = submitRequest(req4, 5000, postData, Header, Data, httpStatus) * response PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Length of response data:":LEN(Data) PRINT "Response Data:":Data UV BASIC Subroutine - SUBROUTINE CUSTOMERSUB (ID, REC)
246 HTTP PUT method
OPEN "CUSTOMER" TO F.CUSTOMER ELSE REC = "" END READ REC FROM F.CUSTOMER, ID ELSE REC = "" END CLOSE F.CUSTOMER RETURN
HTTP PUT method
The HTTP PUT method is used to update a single data resource. In order to update a U2 REST data resource, a client program must read the resource first. It does this by issuing an HTTP GET request to the U2 REST server. To meet the optimistic locking requirement of U2REST, an HTTP PUT request must include the If- Match field in the HTTP header. The value of the If-Match field is the value of the u2version name/value pair in the HTTP GET response. The client program sends the changed data fields with an HTTP PUT request to the U2 REST server to persist the changes. If the data resource has changed since the client program performed the HTTP GET request, then an HTTP 412 error is returned, indicating that optimistic locking failed and the update was terminated. If a data resource contains collections of subresources, such as the orders_list association, changes to the sub-resources are ignored. A client program must modify each of the subresources individually, using an HTTP PUT method. Refer to the section on detail_level for more information. After the data resource is updated, the U2 REST server returns an HTTP 200 OK response, with a JSON object representing the updated data resource. The following example shows a BASIC CallHTTPGET/PUT combination being used to update a resource. A GET request executes to retrieve the contents of the u2version parameter, which is the record’s LastUpdate ID of the record. The client program then calls the U2 REST server with an HTTP PUT request, using the postData information to modify an existing record based on the CUSTID parameter. The value of the u2version parameter must be used in the If-Match HTTP header.
logfil="restput" a = protocolLogging(logfil, "ON", 10) * method="GET" * EXECUTE "CLS" EXECUTE "LIST CUSTOMER CUSTID" CRT PRINT "Which ID would you like to Update?" INPUT CUSTID url="http://den-l-nk01.rocketsoftware.com:9191/HS_SALES/Customer/":CUSTID * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = setRequestHeader(restGET, "Content-Type", "application/json;charset=utf-8") * stat = submitRequest(restGET, 5000, "", Header, restData, httpStatus) * response PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":restData * * Get Data Record u2version ID * MYSTRING = CHANGE(restData, '"u2version"', @AM )
247 Chapter 6: U2 RESTful Web Service Developer
U2VERSION = FIELD(MYSTRING<2>, '"', 2) * putData="" putDATA='{' putDATA:=' "statename" : "Colorado",' putDATA:=' "state" : "CO",' putDATA:=' "fname" : "Neddy",' putDATA:=' "city" : "Denver",' putDATA:=' "lname" : "Seagoon",' putDATA:=' "sal" : "Ms.",' putDATA:=' "phone" : "(800)729-3553",' putDATA:=' "custid" : "':CUSTID:'",' putDATA:=' "addr1" : "4600 South Ulster Street.",' putDATA:=' "addr2" : "",' putDATA:=' "zip" : "80237",' putDATA:=' "company" : "Rocket Software, Inc."' putDATA:='}' * * call the REST subroutine service with HTTP POST url="http://den-l-nk01:9191/HS_SALES/Customer/":CUSTID method="PUT" * stat = createRequest(url, method, restPUT) stat = setRequestHeader(restPUT, "Content-Type", "application/json; charset=utf-8") stat = setRequestHeader(restPUT, "If-Match", U2VERSION) * stat = submitRequest(restPUT, 5000, putDATA, Header, restData, httpStatus) * put response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData a = protocolLogging(logfil, "OFF", 10) END
HTTP DELETE method
The HTTP DELETE method is used to delete a single data record. In order to delete a U2 REST data record, a client program must first read the record by issuing an HTTP GET request to the U2 REST server. To meet the optimistic locking requirement of U2REST, an HTTP DELETE request must include the If- Match field in the HTTP header. The value of the If-Match field is the value of the u2version name/value pair in the HTTP GET response. The client program sends an HTTP DELETE request to the U2 REST server to persist the changes. If the data resource has changed since it was last read, then an HTTP 412 error is sent to the client indicating that optimistic locking failed and that the delete operation aborted. The following example demonstrates how to use the BASIC CallHTTP DELETE function in U2 REST. An HTTP GET request is called first, followed by the HTTP DELETE request. An existing RECORD ID record, based on the CUSTID parameter, is deleted. The value for the u2version parameter must be used in the If-Match HTTP DELETE header.
* logfile = "restdelete" a = protocolLogging(logfile, "ON", 10) * EXECUTE "CLS"
248 U2 REST connection pooling
EXECUTE "LIST CUSTOMER CUSTID" CRT PRINT "WHICH ID WOULD YOU LIKE TO DELETE?" INPUT CUSTID * url="http://den-l-nk01.rocketsoftware.com:9191/HS_SALES/Customer/":CUSTID method="GET" * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = setRequestHeader(restGET, "Content-Type", "application/json;charset=utf-8") * a = submitRequest(restGET, 5000, "", Header, restData, httpStatus) * GET response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":restData * * Get Data Record u2version ID * MYSTRING = CHANGE(restData, '"u2version"', @AM ) U2VERSION = FIELD(MYSTRING<2>, '"', 2) * * call the REST subroutine service with HTTP POST url="http://den-l-nk01.rocketsoftware.com:9191/HS_SALES/Customer/":CUSTID method="DELETE" * stat = createRequest(url, method, restDELETE) stat = setRequestHeader(restDELETE, "Content-Type", "application/json; charset=utf-8") stat = setRequestHeader(restDELETE, "If-Match", U2VERSION) stat = submitRequest(restDELETE, 5000, "", Header, restData,| httpStatus) * DELETE response * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header * PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfile, "OFF", 10) END
U2 REST connection pooling
The U2 REST server, by default, is configured to use connection pooling when making connections to a U2 database. Connection pooling is highly recommended because it improves both performance and scalability, both of which are vital in a Web environment. Connection pooling is an optional configuration and can be turned off on a REST server in the U2 RESTful Web Services Developer. When connection pooling is turned on, the U2 REST server sets up connection pooling via a UOJ connection and relies on UOJ to manage the connection pools. Because UOJ connection pools are process-based, there is no connection pool sharing between different U2 REST servers, even if they are on the same machine, as each runs in a separate Java runtime process. Connection pooling can only be utilized at the REST-server level only. Individual resource folders cannot be configured to use connection pooling.
249 Chapter 6: U2 RESTful Web Service Developer
U2 REST transaction support
U2 REST does not support running transactions across multiple HTTP requests. This means a user cannot group a set of REST requests (operations) together into one single transaction.
Optimistic concurrency control U2 REST implements optimistic locking to prevent concurrent updates to the same data. Optimistic locking is a means of ensuring that no locks are put on a resource when it is read. However, when changes to the resource are ready to be written back, U2 REST first locks it and then checks to see whether the resource has been changed since it was first read. If a change occurs, an optimistic locking violation error is thrown. Since changes (including update, delete, and create requests) are generally much less frequent than reads, this technique improves performance and scalability, while at the same time guaranteeing data consistency.
The u2version field The u2version field holds a calculated value when a data resource is read and sent back to the client as a name/value pair. When the client wants to make a change to the resource, the HTTP PUT or HTTP DELETE request must include the original u2version value in the If-Match HTTP header field. The U2 REST server uses this value to check against the current data on the U2 server. If they match, it allows the update or delete request to be processed; otherwise, it sends back an HTTP 412 error indicating an optimistic locking violation error has occurred. At this time, the client must re-read the data and try the update again. A data resource shares the same u2version value with all of its sub-resources. Thus, when you update a sub resource, even though it may not have changed since first read, if the top-level resource or any of its sub-resources has changed, the update fails. The same process is true for a top-level resource.
Transactions in subroutines U2 database server supports traditional ACID transactions. A U2 REST-based application can carry out transactions by putting them in the subroutines and enabling the client to call these subroutines. The only requirement is that a top-level transaction must be completely embedded within a single subroutine because of the non-persistent database connection model of U2REST. U2 RESTful Web Service Developer
Use the U2 RESTful Web Services Developer to define and publish U2 resources, such as data files and subroutines, to a U2 REST server. Then access those resources in a RESTful manner. Representational State Transfer (REST) defines a software architecture style of networked systems such as the World Wide Web, and is a popular way to build Web services. Systems that follow REST principles are often referred to as RESTful. A RESTful web service, or RESTful web API, is a software system that supports machine-to-machine interactions that use Hypertext Transfer Protocol (HTTP). In a RESTful system, a client uses a Universal Resource Identifier (URI) to request a specific resource from a server. The server responds by sending a representation of the requested resource. U2 RESTful web services provides a resource-oriented view of the data and subroutines in U2 databases and supports simple, lightweight, HTTP-based access to these resources. The U2 RESTful web services are ideal for developing browser-based and mobile applications.
250 U2 RESTful Web Services Developer
Principles of a RESTful system RESTful systems typically adhere to the following design principles: ▪ A URI identifies each resource. ▪ Hyperlinks are used for navigation. ▪ Standard HTTP GET, PUT, POST, and DELETE methods are used on the resources. ▪ Server resources can have multiple representations, such as JSON and XML. ▪ Stateless communication ensures scalability .
RESTful web services A RESTful web service exposes many resources (URIs), but accepts a fixed set of methods (HTTP GET, PUT, POST, and DELETE). All operation details are included in the HTTP request. A RESTful web service offers a resource-based interface to the service consumers. A RESTful web service has a uniform interface and always uses HTTP GET, PUT, POST, and DELETE requests on the resources. In a RESTful system, all meaningful resources, such as web pages, blog entries, pictures, and data records are identified by a URI or URL. These resources contain URIs to other related resources and resources that contain specialized information.
U2 RESTful Web Services Developer
The U2 RESTful Web Services Developer (U2RSD) is an Eclipse-based IDE that includes a number of views, which allow users to easily connect to U2 data servers, create and manage U2 REST server instances, and define U2 REST resources on the REST servers. U2RSD makes use of the U2JPA Eclipse plug-in to map U2 data files to U2JPA entities, which are the underlying objects for U2 REST resources. It also includes a U2 subroutine resource wizard, which creates U2 subroutine resources on the REST server. The subroutine is then implemented as a U2JPA native query. The following figure shows the default U2 RESTful Web Services Developer perspective:
251 Chapter 6: U2 RESTful Web Service Developer
U2 REST workspace
The U2 REST workspace contains multiple panes, called views. Views structure the workspace and serve as a device to organize similar items inside a defined work area. ▪ U2 Resource view ▪ U2 REST Servers view ▪ Properties view ▪ U2 Dictionary view ▪ U2 REST server log view By default, the workspace is arranged in a standard layout, but you can move or resize views. Each view contains its own controls for minimizing and maximizing the space consumed within the XAdmin workspace. Alternatively, you can drag the border of a view to increase or decrease its size. A view may contain just one item or tabs for multiple items. Each view or tab within the view has a Close (X) button to close the entire pane or to close a tab within the pane. You can do no damage in experimenting with the workspace. If you close a view and want to show it again later, you can select it from the Window menu. Otherwise, if you want to reset the main window to show all views in their default locations, you can select Window > Reset.
U2 Resource view The U2 Resource view contains information about each U2 account on the server to which you are connected. This information includes accounts, data files, dictionary files, UniBasic programs, UniVerse BASIC programs, XML/DB mapping files, and cataloged programs. The following figure shows the U2 Resource information for the HS.SALES account:
Right-click on any of the nodes in this view to see the different options available to each node, including Open Dictionary.
U2 REST Servers view The U2 REST Servers view contains information about each REST server and resource that you create. You can manage you RESTful servers, resources, and subroutine services from within this view. The following example illustrates the U2 REST information about the MyRestServer server:
252 U2 REST workspace
When you create a new resource or subroutine service within the RESTful Developer, it appears in the RESTful Servers view. All data files are grouped under the Data Resources node. Subroutines are grouped under the Subroutine Resources node, with dynamic arrays nested together within Subroutine Resources under the Dynamic Array Definitions node. Right-click on any of the nodes in this pane to view the different options available to each node. To start a REST server, for example, right-click your RESTful server and select Start REST Server. You can also double-click any of the data resources in your REST server to test the service in the Test Browser. If the REST server is not running, double-click the resource to start the REST server.
Properties view The Properties view displays the properties defined for each file, account, program, server, and resource available. The following example illustrates the properties of HS_SALES folder, highlighted in the U2 Resource view:
Select a node in any of the views to see the properties for that node.
U2 Dictionary view The U2 Dictionary view displays the dictionary information about the database files in the U2 Resource view. You can see data source information and view the structure of the file system from within this view. The following example illustrates how the CUSTOMER file displays in the U2 Dictionary view:
253 Chapter 6: U2 RESTful Web Service Developer
U2 REST server log view The Server Log view displays the logging details about your Web services. To enable the debug log when the server is running, right-click the REST server and then select Turn On REST Server Debug, as shown in the following example:
You can also turn logging on by changing the Debug Log option in the RESTful server properties. If you select true, the U2 RESTful Web Services Developer starts the debug log each time you start the server. You can only make this change when the server is not running. To disable the debug log when the server is running, right-click the REST server and then select Turn Off REST Server Debug. To view a REST server log, in the U2 REST Servers view, click the REST server. Tutorial
Use the U2 RESTful Web Service Developer to create U2 RESTFul web services that includes data resources and subroutine resources. The examples are written using the UniVerse HS.SALES file.
Creating a U2 server entry
The virtual attributes defined in UniData or UniVerse can be included in the metadata file.
Procedure
1. Start the U2 RESTful Web Services Developer. 2. Right-click the U2 Servers node in the U2 Resource view, and click New U2 Server. 3. In the Name field, enter localuv. 4. In the Host field, enter localhost.
254 Creating a REST server
5. From the U2 data server options, select UniVerse. 6. To save the U2 server definition, click Finish. 7. Right-click the U2 Server you just created and then click Connect to establish a connection to the server. 8. Provide the valid login criteria for the server to which you are connecting. 9. If you do not want to enter your user ID and password in subsequent sessions, select the Remember Me check box. 10. Click Connect. Your U2 data files are now available in the U2 Resource View. Click the white arrow symbol to expand the nodes.
Creating a REST server
After creating a U2 server entry, you must create a RESTful hosting server in the U2 REST Servers view, which is located under the U2 Resource view. When you create a new REST server, you can either create a new entry in the RESTful server configuration file, or you can create a pointer to an existing RESTful server. The U2 REST server is used to access a U2 database server, which holds the collection of resources to which you are connecting.
Procedure
1. Right-click the U2 REST Servers view, and select the New REST Server option from the menu. The New REST Server dialog box opens. 2. Enter the correct information into the fields, as described in the following table.
Field name Description Server Name The name of the REST server to which your web services will connect. Note: After you create the REST server, you cannot rename it later. URL The Uniform Resource Identifier (URL) that specifies where the resource will be available. Port Number The port number to which your RESTful web service requests will connect. Root Path Specifies the path name where your RESTful services will reside. Debug Log Set this option to True if you want the debug log to start each time you start the server. You can only change this setting when the server is not running. Log File Name The name of the debug log file.
255 Chapter 6: U2 RESTful Web Service Developer
Field name Description Connection Pooling Select this option if you want to use connection pooling. Max Pool Size The maximum size of the connection pool. Min Pool Size The minimum size of the connection pool. Authentication Type This feature is used only when UAC is enabled. ▪ http-digest (Default) ▪ http-basic (Not recommended) 3. Click Next. The Database Connection Security dialog box opens. If you do not want to use SSL to define your connection security at this time, simply click NEXT and continue on to step 5. 4. Select the Use SSL check box. The SSL options are now be visible. Enter the appropriate Trust Store information, as described in the following table. For more information about using SSL, refer to the Managing Secure Sockets Layer (SSL), on page 112.
Field name Description Trust Store Enter the full path to the key store on the local server machine, or click Browse to navigate to the trust store. Trust Store The password corresponding to the Trust store you defined in the Trust Password Store.. Confirm Trust Store Confirm the Trust Store password. Password 5. When you are done, click Finish. Focus returns to the U2 REST Servers view.
Creating a resource folder
After creating a REST server, you must create a resource folder for the U2 files and subroutine access definitions in the REST server. This allows the REST server to publish the resource. The resource folder holds all data resources mapped from the database account.
Procedure
1. In the U2 Resource View, locate the folder you want to make available as a RESTful web service. In this example, we select the HS.SALES folder. 2. Drag the HS.SALES folder from the U2 Resource view onto the MyRestServer server you created in the last exercise. 3. Enter the correct information into the fields, as described in the following table.
Field name Description Name The name of the resource folder. U2 Data Server The name of the U2 data server to which you are connecting. The server is defined as MyRestServer for the examples. U2 Account The U2 account to which you are connecting. UniRPC Service The name of the UniRPC service. For UniData, this is udcs and for Name UniVerse it is uvcs. User ID The user ID for the server to which you are connecting.
256 Creating a data resource
Field name Description Login Password The login password for the server to which you are connecting. SSL Select this box if you want to enable SSL. Connection Pooling Select this box if you want to enable connection pooling. Max Pool Size The maximum number of sessions that may be contained within the pool. Min Pool Size The minimum number of sessions that may be contained within the pool. Client Encoding Select the type of encoding, if any, you want to use for this web service from the Client Encoding list. You can verify that you have connection pooling licenses on the U2 server by running confprod in UniData or uvregen in UniVerse. For UniData, refer to the UniData Commands Reference manual for more information. For UniVerse, refer to the Administering UniVerse guide the for more information. SB+ System Id (For SB+ users only) Enter the abbreviation code, or system ID, for your SB+ System. The SB+ fields are optional and are only required if you have SB+ activated on your database account. Refer to the SB+ manuals and the SB/XA manuals for more information on using SB+ and SB/XA systems. SB+ User Id (For SB+ users only) Enter the user ID for the SB+ system to which you are connecting. SB+ Password (For SB+ users only) Enter the password for the SB+ system to which you are connecting. 4. Enter a name for the resource folder. In this example, we name the folder HS.SALES. You can also change the connection information using the fields on this form. For this exercise, however, we accept all defaults. When you enter HS.SALES as the name, it automatically changes to HS_SALES to ensure the URL is valid. 5. Click Finish. Focus returns to the U2 REST Servers view, and an HS_SALES node now appears in the U2 REST Servers view.
Creating a data resource
After you make your data available for publication as a RESTful service, it is time to actually create your data resource.
257 Chapter 6: U2 RESTful Web Service Developer
Procedure
1. In the U2 Resource view, navigate to the file you want to use. In this example, navigate to the HS.SALES > Database Files > CUSTOMER file and then drag it into the HS_SALES folder we created in the U2 REST Servers view.
2. Select the fields that you want to include in the data resource. In this example, we choose Select All.
Note: If you use a very large dictionary and receive a OutOfMemoryError.Java heap space error, you need to change your RESTful server startup parameters in the u2rest.ini file. Add the following parameters to increase the Java memory: -Xms40m -Xmx1200m
3. To filter the results, click the Filter button. a. In the Filter field, enter the information you want to view. b. Click OK. c. To reset the filter and view all files, click Rest Filter and click OK.
258 Testing a data resource
4. Click Next. The Change Resource Names dialog box opens.
You can change the names or descriptions of the items in the resource file. In this example, we change the Orders resource name to Order. 5. Click Finish. Focus returns to the U2 REST Servers view. You now see the Customer and Order resources in the HS_SALES resource folder. The Order resource is a sub-resource of the Customer resource.
Testing a data resource
After creating the data resource, you can test it in the RESTful test browser.
Procedure
1. In the U2 REST Servers pane, right-click the MyRestServer server and select the Start REST Server option to start the server.
259 Chapter 6: U2 RESTful Web Service Developer
2. Expand the Data Resources node and then double-click the CUSTOMER resource. The results appear in the Test Browser.
Results When the test browser opens, the URL displays in the text field. It’s important to notice three things about this URL. ▪ The IP address in your test browser will be different than the one shown here. ▪ The max = 10 option, embedded in the URL, limits the number of results that are returned. You can change the number of results displayed by modifying this option. ▪ The tohtml=true option, embedded in the URL, is typically used for interactive testing only. If the option is set to tohtml=false or left off the URL request, the results are returned as pure JSON text.
(Optional) Linking multiple resources using a foreign key
You can link the data resources from related files through the use of a foreign key. In native U2, a foreign key is a field that is used in the TRANS virtual field to bring data from another file into the host file.
About this task This is an optional exercise. If you want to continue with this exercise, delete the Customer resource you created in the last section.
260 (Optional) Linking multiple resources using a foreign key
Procedure
1. In the U2 REST Servers view, right-click the resource node you want to work with. In this example, select the Customer node. The foreign key is the second parameter in a TRANS function. In our Customer resource example, there is a virtual field named DESCRIPTION that contains a TRANS function, which uses the PRODID field to fetch the product descriptions from the PRODUCTS file, shown in the following figure.
2. Select all of the fields that you want to generate in the U2 REST resource first, then locate the field that you want to link to another resource. You are going to define it as a foreign key. In this example, PRODID is the foreign key field. It is a member of the ORDERS association, which will be mapped to the Orders resource. 3. Click the empty Foreign Key column next to PRODID. Select the Foreign Key option from the list, as shown:
261 Chapter 6: U2 RESTful Web Service Developer
4. Click Next. The Products resource, associated with the Orders resource, is now highlighted in yellow, and linked to the CUSTOMER resource.
5. When you assign a foreign key, you need to make sure that you deselect any of the corresponding virtual fields. In this example, deselect the DESCRIPTION and LIST_PRICE fields. 6. Click Finish. Focus returns to the U2 REST Servers view. A red X now appears next to the Orders resource in the U2 REST Servers view, as shown:
A red X next to any of the resources indicates some type of resource-related error. In this instance, the X is there because we have not yet added the Products file to our available RESTful resources. You cannot create a REST server if there are resource-related errors.
262 (Optional) Linking multiple resources using a foreign key
7. Drag the PRODUCTS file from the U2 Resource view into the HS_SALES folder in the U2 REST Servers view. The Select Fields for Resources dialog box opens.
8. Select the U2 fields you want to generate. In this example, we choose to Select All. 9. Click Next. Make any changes that you want to the resource names, then click Finish. Focus returns to the U2 REST Servers view.
The resources are now linked, and the Orders resource can pull information from the Products resource.
263 Chapter 6: U2 RESTful Web Service Developer
10. Double-click the CUSTOMER resource to test the service. The results appear in the Test Browser view.
Notice that the Orders information now contains a URL to the PRODUCTS information, instead of listing it directly into the Test Browser. If you click the URL, more detailed information about the specified product appears.
Creating a REST subroutine resource
In this exercise, you will create a UniVerse BASIC subroutine exposed as a REST service. Before you can create a REST subroutine resource, you need to create a subroutine.
Prerequisites You must catalog the subroutine before you start the U2 RESTful service. Subroutines may be cataloged globally, locally, or directly. For information about cataloging UniBasic programs, see the UniBasic Commands Reference. For information about cataloging UniVerse BASIC programs, see the UniVerse User Reference. After you create the subroutine, you are ready to create your REST subroutine resource.
About this task For this example, we use a locally cataloged subroutine named CUSTOMERSUB, as shown:
SUBROUTINE CUSTOMERSUB(ID, REC) OPEN "CUSTOMER" TO F.CUST ELSE REC = "" READ REC FROM F.CUST, ID ELSE REC = "" CLOSE F.CUST RETURN
264 Creating a REST subroutine resource
END
Procedure
1. In the U2 Resource view, right-click the account for which you want to create a Web service. Click the white arrow symbol next to the HS.SALES Catalog Program to view the cataloged subroutines available in the account. These are locally cataloged subroutines; globally cataloged subroutines appear in the main Catalog Programs section, which does not reside within your database account. Parameter values entered in a RESTful subroutine are pre-processed by the parser and string values can be altered. For example: ▪ Strings are trimmed for leading, trailing, and multiple embedded spaces. ▪ Non-significant leading zeroes before the decimal point and trailing zeroes after the decimal point are removed from numbers. ▪ The backslash character in a string is used to indicate that the special character following a backslash should be treated in it's literal form rather than interpreted. For example, the UniVerse &COMO& file will be addressed as \&COMO\&. Otherwise, the special character will not be used as intended. In order to preserve exact formatting of data that contains normally non-significant zeroes or spaces, the string should be enclosed in double-quotes. The following examples illustrate how data can be modified and how to avoid the modification.
Parameter name Input value Result Number 1E3 1000.0 Number 012345 5431 Number 012345.670 12345.67 Number 1234567890123456789 1234567890123456789 Number 12345678901234567890 1.2345678901234567E19 Number 1234567890123456789 1.23456789012345677E18 String "012345.670" 012356.670 String "A012345.670" A012345.670 String
265 Chapter 6: U2 RESTful Web Service Developer
3. Drag the CUSTOMERSUB subroutine onto the MyRestServer server. The New Subroutine Service dialog box opens.
4. Enter a relevant name for your subroutine in the Subroutine Name box. In our example, we name the subroutine CUSTOMERSUB. 5. Enter the total number of parameters defined for your subroutine. In the example subroutine, two parameters are defined, one input and one output.
Defining input parameters
You must define the input parameters for your subroutine service.
Procedure
1. Click Add in the Input Parameters area of the New Subroutine Services dialog box. The Define Parameters dialog box opens.
In the example subroutine, the input parameter is the customer ID, and it is the first parameter in the subroutine. 2. In the Name box, enter a relevant name for the parameter. This name does not have to be the same as the one defined in the UniVerse BASIC program. In this example, we define the name as ID. 3. Change the position and type information as necessary. Enter the position the input parameter appears in the subroutine in the Position box. 4. In the Type box, select one of the following data types for the input parameter: ▪ string
266 Defining output parameters
▪ dynamic array ▪ json In this example, we accept the defaults. 5. Click OK. Focus returns to the New Subroutine dialog box.
Defining output parameters
You must define the output parameters for your subroutine service.
Procedure
1. Click Add in the Output Parameters area of the New Subroutine Services dialog box. The Define Parameters dialog box opens.
2. Enter the name of the output parameter in the Name box. 3. Enter the position of the subroutine’s output parameter in the Position box. 4. Enter the data type of your output parameter in the Type box. In our example, the output parameter is a dynamic array. 5. Enter the name of the dynamic array definition in the Dynamic Array Name box. You can choose an existing dynamic array, or create a new one. 6. Click OK to save you parameter changes and then click Finish. Focus returns to the U2 REST Servers view. You now see the subroutine and dynamic array listed under the Subroutine Service node.
267 Chapter 6: U2 RESTful Web Service Developer
7. Double-click the dynamic array for which you want to define the fields. The Edit Dynamic Array dialog box opens.
8. Click Import. The Import U2 Dictionary Attributes dialog box opens. Select the U2 source file from which the dictionary attributes are imported. In this example, we select the CUSTOMER file.
268 Testing the REST subroutine service
9. Click Next. Select the dictionary attributes that you want to import.
Note: The LOC value must be unique for each attribute, and the number of attributes you select must match the number of fields in the parameter of the subroutine. To ensure this is correct, in this example we do not select any ID fields and only import the D-type dictionary attributes.
10. After you select the appropriate attributes, click Finish. The Edit Dynamic Array dialog box opens again, populated with all of the relevant attributes. 11. If everything is correct, click Finish. Focus returns to the U2 REST Servers view.
Testing the REST subroutine service
After you define all of the subroutine parameters, you want to test your REST subroutine service. In the following sections, we test the service in two ways. In the first example, we test the service within the U2 REST tool. In the second example, we use the CallHTTP function to consume our subroutine service.
For information about CallHTTP, refer to either the UniVerse BASIC Extensions manual, or the UniBasic Extensions manual.
269 Chapter 6: U2 RESTful Web Service Developer
Procedure
1. Double-click the subroutine service you defined in the last exercise. In this example, we double-click the CUSTOMERSUB subroutine. The results appear in the Test Browser.
When the test browser opens, the input and output parameters display, along with a Call service button. In this example, the input parameter is ID and the output parameter is the customer record. 2. Enter the appropriate input information. In this example, we enter 2. 3. Click Call service. The REST service calls the subroutine and searches for the information requested in the input parameter. It then displays the results in the Results field.
Manually testing the REST subroutine service
If you do not want to use the test browser, you can choose to manually test the REST subroutine service.
Procedure
1. Right-click the MyRestServer node in the U2 REST Servers pane. Select the Start REST Server option.
270 Manually testing the REST subroutine service
2. Click the CUSTOMERSUB node to highlight the subroutine. In the properties pane to the right, you can see the subroutine resource properties. Note the service URI for the resource. It should look similar to the following service URI:
3. Send a request to the subroutine service. In the UniVerse BASIC example below, use the CallHTTP API to send a request to the subroutine service:
Note: You must change the UTRL value to the one you used in Step 2.
a = protocolLogging("httpreq.log", "ON", 10)
* call the REST subroutine service with HTTP POST url="http://DEN-L-AW01.rocketsoftware.com:9191/HS_SALES/subroutine/CUSTOMERSUB" method="POST" a = setHTTPDefault("VERSION", "1.1") a = createRequest(url, method, req4) a = setRequestHeader(req4, "Content-Type", "application/json; charset=utf-8") postData = '{"id":"2"}' Header = "" Data = "" httpStatus = "" a = submitRequest(req4, 5000, postData, Header, Data, httpStatus)
* response PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Length of response data:":LEN(Data) PRINT "Response Data:":Data
Note: You can also choose to use a Web debugging tool, such as Rest Client or Fiddler, to send an HTTP POST request to the U2 RESTful service to test your subroutine service.Subroutine resources can only be tested using a POST method, and the parameter must be made in JSON format.
Results After the U2 RESTful service receives the HTTP POST request, it returns a response similar to the following:
Response status: 200 @VM OK Response headers:Date @VM Mon, 15 Nov 2010 16:35:56 GMT @FM Server @VM Jetty/4.2.x (Windows XP/5.1 build 2600 Service Pack 3 x86 java/1.5.0) @FM Content-Type @VM application/json;
271 Chapter 6: U2 RESTful Web Service Developer
charset=UTF-8 @FM Content-Length @VM 707 Length of response data:70
The status and headers contain strings separated by field marks (@FM) and value marks (@VM). Data returned from a generic Web debugging tool does not contain these marks. The raw data returned from the U2 RESTful service is in JSON format, as shown below:
Response Data:{"CustomerRec":{"SAL":"Ms.","FNAME":"Diana","LNAME":"Morris", "COMPANY":"Fast Copy Center","ADDR1":"431 Third Ave.","ADDR2":"","CITY": "Waltham","STATE":"MA","ZIP":"01133", "PHONE":"(617)555-9823", "ORDERS":[{"PRODID":"C2000","SER_NUM":"600782","PRICE":"6600", "BUY_DATE":"8409","PAID_DATE":"8437","SVC_PRICE":"900", "SVC_START":"8414","SVC_END":"8781","SVC_PAID_DATE":"8437"}, {"PRODID":"M3000","SER_NUM":"700422","PRICE":"12000", "BUY_DATE":"8409","PAID_DATE":"8437","SVC_PRICE":"500", "SVC_START":"8414","SVC_END":"8564","SVC_PAID_DATE":"8437"}, {"PRODID":"S3000","SER_NUM":"101456","PRICE":"900", "BUY_DATE":"8423","PAID_DATE":"8444","SVC_PRICE":"150", "SVC_START":"8414","SVC_END":"8781","SVC_PAID_DATE":"8444"}]}
U2 REST security
U2 REST provides two methods of security for a RESTful Web project: communication security via a Secure Sockets Layer (SSL), and user authentication and authorization (Digest or Basic). On Digest authentication, U2 REST server enforces a qop=auth quality of protection value. Therefore, your client software must support qop=auth. Refer to RFC-2617 for more information.
Communication security U2 REST supports SSL connections between the U2 REST server and its clients. It also supports connections between the U2 REST server and the U2 database server. For instructions on how to set up and use SSL with U2, refer to the UniData Security Features manual or the UniVerse Security Features manual.
Secure client HTTPS connections When a U2 RESTful service is SSL enabled, the server connection and all of the resources under it are changed from an HTTP connection to a secure HTTPS connection. Secure U2 RESTful services are enabled using the U2 RESTful Web Services Developer.
Secure U2 database connections You can create secure connections between the U2 REST server and the U2 database server. 1. Enable the U2 database server for SSL connection using XAdmin to secure the UOJ service connection (uvcs or udcs). 2. Install the U2 database server certificates in the U2 REST server’s keystore file. The JRE directory is located, by default, in the following location:
$INSTALL_DIR/jre/jre/lib/security/cacerts You can use tools such as Java keytool, the Java key and certificate management tool, to create and maintain the JRE. The keytool utility is installed with Oracle’s JDK. 3. Check the SSL property on the resource folder inside U2 RESTful Web Services Developer.
272 User authentication and authorization
Note: For information about how to set up and use SSL with U2, refer to the UniData Security Features manual or the UniVerse Security Features manual. For more information on the Java keytool, see http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html .
User authentication and authorization
U2 REST makes use of the Jetty HTTP server’s role-based user authentication and authorization to provide secure access to the web services. This allows you to manage how and by whom different files are accessed.
User authorization User authorization, or user access control (UAC), is used to determine whether a user with the correct credentials is allowed to access a specific U2 REST resource. This is done by restricting access of certain resources to a set of roles. For example, only users who are in the HR role can access the resources under the resource folder “Human Resources”. In U2 REST, such restrictions are specified as a set of access control rules. Each rule has three parts: ▪ A URI. This can be the URI of a REST server, a resource folder, a top-level data resource, or a subroutine resource. This rule applies to this URI. ▪ A set of HTTP methods. These are the operations that can be performed on the resource in the URI, or the resources under the URI if it points to a resource container such as a REST server or resource folder. ▪ A set of roles that define who is allowed to perform the operations defined on the resources. When multiple rules can be applied to an HTTP request, the most specific rule is applied. For example, the following table has three access control rules:
Rule URI HTTP method Roles 1 /* * Any 2 /xdemo/Product POST, PUT, DELETE Admin 3 /xdemo/Member * Admin, Sales, Service
In this example, both rule 1 and rule 2 can be applied to an HTTP POST request to /xdemo/Product. However, rule 2 is the one applied because it dictates that only the user defined as Admin can modify Product resources. If no access control rules are applied to an HTTP request, it will be served by U2 REST server. There is no validation.
User authentication You can control access to various accounts by defining a user ID and password for each user. Each user ID must also be assigned one or more user roles. User roles are defined by grouping a set of user privileges together, and then giving that group a meaningful name, such as Administrator or Guest. After you define a user role, you can assign each role(s) to a user ID. Multiple user IDs can be assigned to the same user role. This allows you to quickly and easily change the privileges for all users assigned to a specific user role simultaneously.
273 Chapter 6: U2 RESTful Web Service Developer
Authorizing a user
You can restrict access to certain resources by authorizing levels of access defined by various job roles, such as an administrator role or an HR role.
Procedure
1. Right-click the U2 REST server connection from the U2 REST server view. Select Access Control Setup from the U2RSD menu. When you select the Access Control Setup menu option, the Define Access Control dialog box opens.
2. Click Add. The Add New Access Constraint dialog box opens.
274 Authenticating a user
3. Expand the navigation tree in the Path field and select the location for which you are creating a user role. In our example, we choose the TestServer file, as shown.
When you select a location, the directory path appears in the Path text box. 4. Select the privileges that will be available to the user role you are defining by checking the appropriate Methods check boxes. You can choose one or more methods, or you can select All to grant full privileges to the user. 5. Click Finish. Focus returns to the Developer. 6. After you define the privileges you want to assign for a given role, you need to define that role. To select a role, choose an existing role from the list of available roles. If there are no roles defined yet, or if you need to create a new role, click Add Role.
Authenticating a user
You can control access to various accounts by defining a user ID and password for each user. Each user ID must also be assigned one or more user roles.
Procedure
1. Right-click the U2 REST server connection from the U2 REST server view. Select Define HTTP Users from the U2RSD menu. The Define HTTP Users dialog box opens.
275 Chapter 6: U2 RESTful Web Service Developer
2. Click Add to define a new user role. The Add New HTTP User dialog box opens.
3. Enter the correct user information, as described below. a. In the User Name field, enter the correct user name. b. In the Password field, enter the password. c. In the Confirm Password field, reenter the password. d. In the Roles field, select the appropriate user role from the list. To select multiple user roles for a specific user, hold down Ctrl while selecting the appropriate roles from the list. 4. When you are finished, click OK. Focus returns to the HTTP Users dialog box. 5. If you are satisfied with your user definitions, click Finish. Focus returns to the Developer. SB+ and RESTful web services
Accessing SB+ files
You can view and manipulate your SB+ files in U2 RESTful web services, just as you can any other U2 files. However, you may need to complete a few extra steps to make your SB+ derived files and dynamic fields accessible. Specifically, you may need to change the SB+ configuration parameters and run the REGEN.EXP process against your SB+ files. If you are using a version prior to SB/XA v6.2, you also need to add the SB.REMOTE.DBCLIENT program to your application account.
Modifying SB+ parameters
When you view items in SBClient, your data is presented in a PICK-style format, as shown:
276 Modifying SB+ parameters
You may need to change your SB+ parameters to make your files accessible to U2 RESTful Web Services Developer.
Procedure
1. In the SB text editor, change the SB+ configuration parameters to generate I-type and D-type dictionaries, as shown in the example below: Top of "SB.CONTROL" in "DMCONT", 45 lines, 301 characters.
*--: 34
034: ýýýýý1
*--: C//1
034: 1ýýýýý1
*--: FI
Filed "SB.CONTROL" in file "DMCONT" 2. If you want to use subroutines in your dictionary, you need to ensure the Use Subroutines in Dictionaries flag is set appropriately. If the Use Subroutines in Dictionaries flag is set to 0, change the flag to 1, as shown: Top of "SB.CONTROL" in "DMCONT", 45 lines, 301 characters.
*--: 42
042: 0
*--: C/0/1
042: 1
*--: FI
Filed "SB.CONTROL" in file "DMCONT" This allows you to use subroutines in your dictionaries.
277 Chapter 6: U2 RESTful Web Service Developer
Regenerating files
If you change the SB+ parameters, you must regenerate your files to apply the changes.
Prerequisites
Note: Before you run the REGEN.EXP process, make sure that you are aware of any third-party processes that may be affected. For more information about how to use REGEN.EXP, refer to the SB/XA Application Server Reference manual.
278 Regenerating files
Procedure
1. Run the REGEN.EXP process on each file you want to access using U2 RESTful Web Services Developer, as shown:
You can also choose to enter ALL as the file name. This selects all files in your dictionary. When you run the REGEN.EXP process, it regenerates your files with the parameter changes you made in the last step. The REGEN.EXP process regenerates the following: ▪ All SB expressions found in the SB DICT item ▪ The OE version of the SB DICT item ▪ SB expressions found in screens and reports ▪ All expressions found in xxDEFN ▪ All expressions found in xxPROCESS You can choose to run the REGEN.EXP process against individual files or all files in a system. When the REGEN.EXP process completes, you can view your dictionary changes in SBClient, as shown:
2. After making changes to the SB+ parameters and running the REGEN.EXP process on your files, if you are using version prior to SB/XA v6.2, you also need to add the following SB.REMOTE.DBCLIENT program to your application account: SUBROUTINE SB.REMOTE.DBCLIENT(L.SYSID, L.USER, L.PWD, L.STATE, L.ERR)
279 Chapter 6: U2 RESTful Web Service Developer
$INCLUDE DMSKELCODE COMMON
$INCLUDE DMSKELCODE STANDARD.EQU
*
L.ERR = ""
PARAM<1> = L.USER
PARAM<2> = L.PWD
PARAM<5> = L.STATE
IF PARAM<3> = "" THEN PARAM<3> = "WHO"
SYSID = L.SYSID
CALL SB.REMOTE.PROCESS(PARAM)
OPEN SYSID:"DEFN" TO F.DEFN ELSE CRT "COULD NOT OPEN ":SYSID:"DEFN";L.ERR = "The file ":SYSID:"DEFN was not found"
RETURN 3. Compile and catalog the SB.REMOTE.DBCLIENT program in the SBDEMO account. All SB+ examples are based in this file in the TUBP folder in the SBDEMO account. Your files can now be accessed and utilized in the U2 RESTful Web Services Developer. Deployment
Deployment environment requirements
Before deploying U2 RESTful web services, make sure that the computer it is installed on meets the requirements. ▪ Java Runtime Environment (JRE) 1.8 must be installed on the target deployment platform. Currently, JRE 1.8 is the only version supported by U2 REST. Problems may occur if other versions are used. ▪ The JRE_HOME environment variable must point to the location of the JRE installation directory. ▪ At least 1GB of memory must be available prior to running the development environment. ▪ The memory requirements for the deployment environment depend on a variety of variables, including number of connections, tasks performed, and work load. ▪ Connection pooling licenses on the database server if connection pooling is enabled.
Creating a deployment package
The U2 RESTful Web Services Developer Export option enables you to generate a deployment package of the selected RESTful web service.
280 Exporting RESTful web services
Prerequisites ▪ 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 Runtime Environment (JRE) 1.8 must be installed on the target deployment platform, and the JRE_HOME environment variable must point to the location of the JRE 1.8 installation directory. Currently, JRE 1.8 is the only version supported by U2 REST. Problems may occur if other versions are used. The deployment package is in the form of a zip file that contains the following:
▪ rundeploytool.bat ▪ rundeploytool.sh ▪ runrestserver.bat ▪ runrestserver.sh ▪ runtime ▪ stoprestserver.bat ▪ stoprestserver.sh ▪ u2rest ▪ U2REST_deploy.conf ▪ u2rest_workspace ▪ u2restservice.exe ▪ vcredist_x86.exe The zip file contains script files for Windows (.bat) and UNIX/Linux (.sh) files, which allow you to deploy the RESTful web services on most platforms.
Exporting RESTful web services
You must export your RESTful web services to a .zip file in order to deploy them.
Procedure
1. Right-click the REST server that contains the REST service that you want to export. 2. Select Export. 3. In the Available REST Servers section, select the REST server(s) that you want to export. 4. Enter the path for the zip file that you want to create in the Archive File field. By default, the zip file is created in C:\U2\U2tools\v4\ImpTest.zip. Click Browse to choose a different directory path or file name.
Note: Some computers, such as those running UNIX, cannot use zip files. In those cases, recompress the file with a non-zip extraction tool, such as 7zip, into a ZG-type file.
281 Chapter 6: U2 RESTful Web Service Developer
Importing RESTful web services
After exporting a RESTful web service from the source development system, you can import it on the target RESTful web service system. The zip file must be extracted on the target system. For example c: \temp.
Prerequisites Exporting RESTful web services, on page 281
Procedure
1. Right-click the REST server that contains the REST service that you want to import. 2. Select Import. 3. Click Browse to select the root directory for the REST server(s) that you want to import. For example, C:\temp\ImpTest\u2restdeploy.
Caution: You cannot change the name of the RESTful server after importing the web service. If a REST server with the same name already exists, it will be overwritten when the web service is imported.
4. Select the servers that you want to import and then click Finish.
Figure 2: Importing RESTful web services
Deploying a U2 RESTful server as a Windows service
The u2restservice.exe is an executable program that is used to create or remove a U2 RESTful web service as a Windows service. It is located in the zip file that was created during the export process. ▪ Starting the U2 REST GUI deployment tool, on page 286 ▪ 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.
282 Generating a configuration file
Note: A Windows service can only be created on a deployed package.
The syntax for installing a U2 RESTful web service is as follows:
U2restservice.exe –i u2rest-server-name [-s u2rest-service-name] [-d "u2rest-service-description"] The following table lists the options available for deploying a U2 RESTful web server as a Windows service.
Option Description -i Installs a new U2 RESTful web service as a Windows service. -s The name of the U2 RESTful web service. -d Description of the U2 RESTful web service. The default value is "U2 RESTful service to start and stop U2 RESTful server". The text of the description must be enclosed in quotation marks (“”). -r Removes the U2 RESTful web service.
After installing the U2 RESTful web service, it can started and stopped as a Windows service from the Windows control panel. When the service starts, it runs the runrestserver.bat u2rest-server program and waits until this bat file exits. When the service stops, it runs the stoprestserver.bat u2rest-server program. Additional arguments can be passed to the runrestserver.bat by specifying the start parameters to the service.
Note: If you are creating a Windows service using the u2restservice.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 REST product to ensure the Windows platform has the compatible Microsoft Visual C++ 2005 redistributable runtime environment: Error: The application has failed to start because its side-by-side configuration is incorrect. Please see the application event log for more detail.
To remove the service, use the following syntax:
U2restservice.exe –r u2rest-server
Generating a configuration file
Use the U2 RESTful deployment tool to generate a configuration file that can be used to deploy the U2 RESTful server from the development computer to the deployment environment.
Prerequisites ▪ Exporting RESTful web services, on page 281
Procedure
1. After exporting the U2 RESTful web services from within the U2 RESTful tool, extract the zip file on to the target machine. The contents of the zip file are extracted into the u2restdeploy folder, which should contain the following files:
283 Chapter 6: U2 RESTful Web Service Developer
▪ rundeploytool.bat ▪ rundeploytool.sh ▪ runrestserver.bat ▪ runrestserver.sh ▪ runtime ▪ stoprestserver.bat ▪ stoprestserver.sh ▪ u2rest ▪ U2REST_deploy.conf ▪ u2rest_workspace ▪ u2restservice.exe ▪ vcredist_x86.exe
Tip: Some machines, 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.
284 Generating a configuration file
2. Navigate to the server directory where you extracted the zip file and locate U2RESTdeploytool. Run the rundeploytool command, shown in the example below. rundeploytool[.sh | .bat] deployable_server_dir source_target_directory The following table describes each parameter of the syntax.
Parameter Description rundeploytool[.sh The command to start the deployment tool. Use the .bat | .bat] extension for Windows applications and the .sh extension for UNIX/Linux applications. deployable_server_dir The directory to which you extracted the zip file. This can be the full path or a dot (.) for the current directory. source_target_directory The directory where the deployable U2 RESTful web server will be located.
For example: rundeploytool.bat . C:\temp\myservice
Note: Rocket U2 does not recommend deploying your REST servers within the UniData/UniVerse home or bin installation locations.
Running the command opens the U2 REST Service Deployment tool, as shown:
3. Expand the Deployable REST Servers node in the REST servers pane. Right-click the REST server you to deploy, then click Generate configuration file. 4. Click Browse to select a different configuration file or accept the default configuration file. Click Next. The REST Server Configuration dialog box opens. You can specify the environment for the new REST server by changing any of the fields, as described below. a. In the Server Name field, enter a unique name for your REST server. b. The Site URL field displays the valid URL for the REST server. You cannot change the information in this field. c. In the Port Number field, enter the port number on which the server will listen.
285 Chapter 6: U2 RESTful Web Service Developer
d. The Root Path field displays the path to the root directory where the definitions to the Web service are stored. You cannot change the information in this field. e. Select the Debug On option if you want to capture debugging information. f. In the Log File Name field, enter the name of the log file. g. Select the Connection Pooling On option if you want to use connection pooling. h. In the Minimum Connection Pool Size field, enter the minimum number of pooled connections. The minimum size defaults to 1. i. In the Maximum Connection Pool Size field, enter the maximum number of pooled connections. The minimum size defaults to 10. j. In the Authentication Type field, select the type of HTTP-based user authentication and authorization. This feature is used only when UAC is enabled. The default type is http-digest. 5. Click Next. The REST Server Connection Security dialog box opens. 6. Select the Specify Connection Security check box to make changes to the security settings. Click Next to continue. For more information, see Defining security between the client and the REST server, on page 288. 7. Click Add to add user access controls to the REST server. When you are done making changes, click Next to continue. For more information about user access controls, see Defining user access, on page 289. 8. Make any necessary changes to the Resource folder properties and then click Finish. For more information, see Defining the Resource folder properties in the GUI tool, on page 290.
Deploying a RESTful server using the U2 REST deployment tool
Starting the U2 REST GUI deployment tool
Use the U2 RESTful deployment tool to deploy the U2 RESTful server from the development computer to the deployment environment.
Prerequisites ▪ Exporting RESTful web services, on page 281
Procedure
1. After exporting the U2 RESTful web services from within the U2 RESTful tool, extract the zip file on to the target machine. The contents of the zip file are extracted into the u2restdeploy folder, which should contain the following files:
▪ rundeploytool.bat ▪ rundeploytool.sh ▪ runrestserver.bat ▪ runrestserver.sh ▪ runtime ▪ stoprestserver.bat ▪ stoprestserver.sh
286 Starting the U2 REST GUI deployment tool
▪ u2rest ▪ U2REST_deploy.conf ▪ u2rest_workspace ▪ u2restservice.exe ▪ vcredist_x86.exe
Tip: Some machines, such as those running UNIX, cannot use zip files. If this occurs, recompress the file with a non-zip extraction tool such as 7zip into a gz (gzip) type file.
2. Navigate to the server directory where you extracted the zip file and locate U2RESTdeploytool. Run the rundeploytool command, shown in the example below. rundeploytool[.sh | .bat] deployable_server_dir source_target_directory The following table describes each parameter of the syntax.
Parameter Description rundeploytool[.sh The command to start the deployment tool. Use the .bat | .bat] extension for Windows applications and the .sh extension for UNIX/Linux applications. deployable_server_dir The directory to which you extracted the zip file. This can be the full path or a dot (.) for the current directory. source_target_directory The directory where the deployable U2 RESTful web server will be located.
For example: rundeploytool.bat . C:\temp\myservice
Note: Rocket U2 does not recommend deploying your REST servers within the UniData/UniVerse home or bin installation locations.
Running the command opens the U2 REST Service Deployment tool, as shown:
287 Chapter 6: U2 RESTful Web Service Developer
3. Expand the Deployable REST Servers node in the REST servers pane. Right-click the REST server you want to deploy, then click Deploy. The REST Server Configuration dialog box opens. You can specify the environment for the new REST server by changing any of the fields, as described below. a. In the Server Name field, enter a unique name for your REST server. b. The Site URL field displays the valid URL for the REST server. You cannot change the information in this field. c. In the Port Number field, enter the port number on which the server will listen. d. The Root Path field displays the path to the root directory where the definitions to the Web service are stored. You cannot change the information in this field. e. Select the Debug On option if you want to capture debugging information. f. In the Log File Name field, enter the name of the log file. g. Select the Connection Pooling On option if you want to use connection pooling. h. In the Minimum Connection Pool Size field, enter the minimum number of pooled connections. The minimum size defaults to 1. i. In the Maximum Connection Pool Size field, enter the maximum number of pooled connections. The minimum size defaults to 10. j. In the Authentication Type field, select the type of HTTP-based user authentication and authorization. This feature is used only when UAC is enabled. The default type is http-digest. 4. Click Next. The REST Server Connection Security dialog box opens.
Defining security between the client and the REST server
During the deployment process, you can define the security between the client and the REST server using the deployment tool.
Prerequisites ▪ Starting the U2 REST GUI deployment tool, on page 286
Procedure
1. Click the Specify Connection Security check box if you want to define connection security between the client and the REST server. The security options populate the dialog box, as shown:
2. Enter the correct security connection details, as described below:
288 Defining user access
Field name Description Key Store The full path to the key store on the REST server. Key Store Password The password corresponding to the key store you defined in the Key Store field. Confirm Key Store Reenter the password corresponding to the key store you defined Password in the Key Store field. 3. Click Next to add access controls to your project, or click Finish to exit the wizard.
Defining user access
The access control page allows you to define user access and privileges. The user access control parameters you defined in the developer tool are not transferable and are used primarily for testing purposes. You must define new user access controls when you deploy your U2 RESTful web services.
Prerequisites ▪ Defining security between the client and the REST server, on page 288
Procedure
1. From the Access Control screen, click Add to define a new role. The Add New Access Constraint dialog box opens.
2. Expand the navigation tree in the Path field and select the location for which you are creating a user role. In this example, choose the TestServer file. When you select a location, the directory path appears in the Path text box. 3. Select the privileges that will be available to the user you are defining by checking the appropriate Methods check boxes. You can choose one or more methods, or you can select All to grant full privileges to the user.
289 Chapter 6: U2 RESTful Web Service Developer
4. After you define the privileges you want to assign for a given role, you need to define that role. To select a role, choose an existing role from the list of available roles. If there are no roles defined yet, or if you need to create a new role, click Add Role. 5. Enter a meaningful name for the new role you are creating. In our example, we create the admin role. 6. Click Finish. Focus returns to the Access Control dialog box. 7. Click Next. The HTTP Users dialog box opens. 8. Click Add to designate the users who will be assigned to the user role you just created. 9. Enter the correct user information. To select multiple user roles for a specific user, hold down the Ctrl key while selecting the appropriate roles from the list. 10. When you are done making changes, click Finish. Focus returns to the HTTP Users dialog box. 11. Click Next. The Resource Folder Properties window opens.
Tip: If you find that you need to make more changes to your deployment server, right-click the server name you want to change from the list of available REST servers and select the Update option.
Defining the Resource folder properties in the GUI tool
The Resource Folder Properties page allows you to define the properties for the selected resource folder.
Prerequisites ▪ Defining user access, on page 289
Procedure
1. When the Resource Folder Properties dialog box opens, it displays the properties for the resource folder you defined for your RESTful server. You can edit the resource properties, as defined in the following table:
Field name Description Name Displays the name of the resource folder. You cannot edit this field. U2 Data Server The name of the U2 data server to which you are connecting. U2 Account The name of the U2 account to which you are connecting. UniRPC Service The name of the UniRPC service to which you are connecting. Name UniRPC Port The port number to which you are connecting. User ID The correct user name. Password The correct password. SSL Select the check box if you want to use SSL.
290 Deploying a REST server from the command line
Field name Description Client Encoding The type of encoding, if any, you want to use for this Web service from the Client Encoding list. SB+ System Id The abbreviation code, or system ID, for your SB+ System. Refer to the SB+ manuals and the SB/XA manuals for more information on using systems. SB+ User Id The user ID for the SB+ system to which you are connecting. SB+ Password The password for the SB+ system to which you are connecting. 2. Click Test Database Connection. A pop-up window opens and informs you when the connection is successful. 3. Click OK to close the window. Click Finish to accept the resource folder properties. Focus returns to the REST Server Configuration dialog box.
Tip: If you find that you need to make more changes to your deployment server, right-click the server name you want to change from the list of available REST servers and select the Update option.
The RESTful service is deployed on the deployment computer.
Deploying a REST server from the command line
Starting the U2 REST deployment tool from the command line
Use the command line options to deploy the U2 REST server from the development computer to the deployment environment. The command line options allow for option-driven, interactive command line deployment.
Prerequisites ▪ Exporting RESTful web services, on page 281
Procedure
1. After exporting the U2 RESTful web services from within the U2 RESTful tool, extract the zip file on to the target machine. The contents of the zip file are extracted into the u2restdeploy folder, which should contain the following files:
▪ rundeploytool.bat ▪ rundeploytool.sh ▪ runrestserver.bat ▪ runrestserver.sh ▪ runtime ▪ stoprestserver.bat ▪ stoprestserver.sh ▪ u2rest ▪ U2REST_deploy.conf ▪ u2rest_workspace
291 Chapter 6: U2 RESTful Web Service Developer
▪ u2restservice.exe ▪ vcredist_x86.exe
Tip: Some machines, such as those running UNIX, cannot use zip files. If this occurs, recompress the file with a non-zip extraction tool such as 7zip into a gz (gzip) type file.
2. Navigate to the server directory where you extracted the zip file and locate U2RESTdeploytool. Run the rundeploytool command, shown in the example below. rundeploytool[.sh | .bat] deployable_server_dir [target_server_dir]-s server_name [-t target_server] [-f config_file [-u] ] The following table describes each parameter of the syntax.
Parameter Description rundeploytool[.sh The command to start the deployment tool. Use the .bat | .bat] extension for Windows applications and the .sh extension for UNIX/Linux applications. deployable_server_dir The directory to which you extracted the zip file. This can be the full path or a dot (.) for the current directory. target_server_dir The target directory where you want to deploy your U2 RESTful service. -s The name of the source server. source_server_name -t The name of the server on which the U2 REST server will be target_server_name 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.
For example: For example: rundeploytool.bat . C:\temp\myservice -s testserver -t prodserver
Note: Rocket U2 does not recommend deploying your REST servers within the UniData/UniVerse home or bin installation locations.
3. The U2 RESTful 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 REST server. The Site URL field displays the valid URL for the REST server. You cannot change the information in this field.
292 Defining U2 RESTful server connection security from the command line
Command line option Description 2 Port number. The port number on which the server will listen. Root Path. Displays the path to the root directory where the definitions to the Web service are stored. You cannot change the information in this field. 3 Debug on. Set this value to true to turn on the debug log. Set this value to false to turn the log off. By default, this value is set to false. 4 Log file name. Edit the name of the log file. By default, the name of the log file is defined by the name of the target server. 5 Connection Pooling On. Set this value to true to enable connection pooling. 6 Minimum Connection Pool Size. Sets the minimum number of connections in the connection pool. The minimum size defaults to 1. 7 Maximum Connection Pool Size. Sets the maximum number of connections in the connection pool. The minimum size defaults to 10. 8 Authentication Type. Set the type of HTTP-based user authentication and authorization. This feature is used only when UAC is enabled. ▪ http-digest (Default) ▪ http-basic (Not recommended)
4. After making any changes to the deployment configuration options, enter A to continue.
Defining U2 RESTful server connection security from the command line
After defining the connection configuration, you can define the connection security for the server.
Prerequisites ▪ Deploying a REST server from the command line, on page 291
Procedure
1. The U2 RESTful connection security 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. S Specify the connection security parameters. D Do not specify connection security. Select this option if connection security is not required. 1 Key Store. Enter the name of the Key Store. 2 Key Store password. Enter the password for the Key Store 3 Key Password. Enter the password for the Key.
2. After defining any connection security settings for the server, enter A to continue.
293 Chapter 6: U2 RESTful Web Service Developer
Defining Resource folder properties from the command line
After defining the server connection properties, you can define the properties for the selected resource folder.
Prerequisites ▪ Defining U2 RESTful server connection security from the command line, on page 293
Procedure
1. The U2 RESTful 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:
Field name Description X Exit. A Accept. Accepts the options as defined. T Test. Tests the database connection. 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 if you want to use SSL. 8 The type of encoding, if any, you want to use for this Web service from the Client Encoding list. 9 The abbreviation code, or system ID, for your SB+ System. Refer to the SB+ manuals and the SB/XA manuals for more information on using systems. 10 The user ID for the SB+ system to which you are connecting. 11 The password for the SB+ system to which you are connecting.
2. After making any changes to the Resource folder properties, enter A to continue.
Deploying a REST server from the command line
After any required changes are made to the Resource folder properties, the U2 REST server is ready to deploy on the deployment environment.
Prerequisites ▪ Defining Resource folder properties from the command line, on page 294
Procedure
The U2 RESTful 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:
Field name Description X Exit.
294 Deploying a REST server from a configuration file
Field name Description 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.
The U2 RESTful service is deployed to the deployment environment.
Deploying a REST server from a configuration file
A U2 RESTful 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.
Prerequisites ▪ Generating a configuration file, on page 283
Procedure
After generating a configuration file, open a command prompt (cmd.exe) on the deployment machine. Navigate to the directory in which the configuration files are located. Run the following command to deploy the U2 REST server on the deployment environment: rundeploytool deployable_server_dir [target_server_dir]-s server_name [-t target_server] –f config_file [-u] The following table describes each parameter of the syntax.
Parameter Description rundeploytool[.sh The command to start the deployment tool. Use the .bat | .bat] extension for Windows applications and the .sh extension for UNIX/Linux applications. deployable_server_dir The directory to which you extracted the zip file. This can be the full path or a dot (.) for the current directory. target_server_dir The target directory where you want to deploy your U2 RESTful service. -s The name of the source server. source_server_name -t The name of the server on which the U2 REST server will be target_server_name 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.
295 Chapter 6: U2 RESTful Web Service Developer
Results The U2 RESTful service is deployed to the deployment environment.
Updating the configuration file using the GUI tool
Use the U2 RESTful deployment tool to update the configuration file used to deploy the U2 RESTful server from the development computer to the deployment environment. The configuration file holds information such as server name, port number, and connection pool information.
Prerequisites ▪ Exporting RESTful web services, on page 281 Generating a configuration file, on page 283
Procedure
1. Open the U2 REST Deployment tool. To open the tool, run the rundeploytool command, shown in the example below: rundeploytool[.sh | .bat] deployable_server_dir source_target_directory 2. Expand the Deployable REST Servers node in the REST servers pane. Right-click the REST server you to deploy, then click Update. 3. Select the correct target sever from the list and then click Update. The REST Server Configuration dialog box opens. You can specify the environment for the REST server by changing any of editable fields 4. Change any of the available settings and follow the wizard prompts.
Disabling security protocols from the configuration file
Modify the configuration file to disable SSL protocols. This is a manual process and can only be done from the configuration file.
Prerequisites ▪ Generating a configuration file, on page 283
Procedure
1. After generating a configuration file, open the file in an editor such as Notepad. By default, this is located at C:\U2\U2Tools\v4\U2REST.config. 2. Navigate to the Security section, and modify the excludeProtocols and excludeCipherSuites parameters, as shown in the following example. In this example, all security protocols are excluded except TLSv1.2 and the SSL_RSA_WITH_NULL_SHA and SSL_RSA_WITH_RC4_128_MD5 cipher suites are excluded except . 296 Starting a RESTful service excludeProtocols ="SSLv2 SSLv3 TLSv1 TLSv1.1" excludeCipherSuites="SSL_RSA_WITH_NULL_SHA SSL_RSA_WITH_RC4_128_MD5" />
Starting a RESTful service
After exporting the U2 RESTful web project and running it through the deployment tool, start the RESTful web services in the deployment environment. 1. Use the following command to start a U2 RESTful service: runrestserver[.sh | .bat] rest_server_name . [rest_server_directory] The following table describes each parameter of the syntax.
Parameter Description runrestserver[.bat | .sh] The command to run the REST server in the deployed environment. Use the .bat extension for Windows applications and the .sh extension for UNIX/Linux applications. . The current directory. You must include this parameter. rest_server_name The name of the REST server to which you are connecting. source_target_directory The target directory where the RESTful service will be deployed
For example: runrestserver.bat . C:\temp\mynewservice 2. Your can check to ensure that the RESTful service is running by opening a browser window and navigating to the URL where the service is running.
Note: UNIX users may want to run the runrestserver command as a background process, using a NOHUP command when the terminal session exits. For example: nohup runrestserver.sh rest_server_name path_to_U2REST.config directory &
Stopping a RESTful service
You can stop any of the U2 RESTful web services running in the deployment environment. Use the following command to stop a U2 RESTful service: stoprestserver[.sh | .bat] . source_target_directory The following table describes each parameter of the syntax.
Parameter Description stoprestserver[.bat | .sh] The command to stop the REST server in the deployed environment. Use the .bat extension for Windows applications and the .sh extension for UNIX/Linux applications. . The current directory. You must include this parameter.
297 Chapter 6: U2 RESTful Web Service Developer
Parameter Description source_target_directory The target directory where the RESTful service will be deployed
For example: stoprestserver.bat . C:\temp\mynewservice
Remote servers
U2 RESTful web service allows for limited remote RESTful server monitoring. You can use this functionality to stop a remote server, but you cannot restart the server remotely. You can also turn the REST Server Debug On/OFF remotely. Code samples
UniBasic code samples
The U2 RESTful web service code samples in this section are written for UniData in UniBasic. They demonstrate the following methods: ▪ HTTP GET ▪ HTTP POST ▪ HTTP PUT ▪ HTTP DELETE ▪ RESTSUB - An HTTP subroutine ▪ RETPROG - A subroutine test program ▪ RETSUB - A UniBasic subroutine ▪ URLENC - An encoding program
UniBasic HTTP GET
The HTTP GET method can only be used on U2 REST data resources. The following example illustrates a typical HTTP GET request. The request calls the U2 REST server using a GET statement, and then returns a customer record based on the requested CUSTID:
* logfile = "restget" * stat = protocolLogging(logfile, "ON", 10) * PRINT "WHICH CUSTOMER record ID would you like to GET?" INPUT CUSTID * * URL returned as html or json data url="http://myserver.com:9191/demo/Customer/":CUSTID method="GET" * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = submitRequest(restGET, 5000, "", Header, restData,| httpStatus) *
298 UniBasic HTTP POST
* GET response parser restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * * stat = protocolLogging(logfile, "OFF", 10) END
UniBasic HTTP POST
The HTTP POST method is used to create a new data record or to call a BASIC subroutine. The following example demonstrates how to use the HTTP POST request. In this program, we call the U2REST server using an HTTP POST request. The request then uses postData information to create a new record based on the CUSTID parameter.
* logfile="restpost" * stat = protocolLogging(logfile, "ON", 10) * method="POST" url="http://myserver.com:9191/demo/Customer" stat = setHTTPDefault("VERSION", "1.1") * PRINT "Enter Unique Customer ID to create: " INPUT CUSTID * * Customer Record to be written to record CUSTID * postDATA = '{' postDATA:=' "_id" : "':CUSTID:'",' postDATA:= "'_original': 'null'," postDATA:= "'_synonym': 'null'," postDATA:= "'activity': ''," postDATA:= "'address': ['4700 South Syracuse Street']," postDATA:= "'avg_out': ''," postDATA:= "'categories_liked': ['C']," postDATA:= "'city': 'Denver'," postDATA:= "'cur_balance': '0.00'," postDATA:= "'name': 'Seagoon, Neddy'," postDATA:= "'phone': '3034495641'," postDATA:= "'state': 'CO'," postDATA:= "'up_name': ''," postDATA:= "'zip': '80237'," postDATA:=' }' * stat = createRequest(url, method, restPOST) stat = setRequestHeader(restPOST, "Content-Type",| "application/json; charset=utf-8") stat = submitRequest(restPOST, 5000, postDATA, Header, restData,| httpStatus) * POST response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus *PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData
299 Chapter 6: U2 RESTful Web Service Developer
* * stat = protocolLogging(logfile, "OFF", 10) * restPOST="" END
UniBasic HTTP PUT
The following example demonstrates a typical GET/PUT combination being used to update a resource. A GET request executes to retrieve the contents of the u2version parameter, which is the record’s LastUpdate ID. The client program then calls the U2 REST server with an HTTP PUT request, using the postData information to modify an existing record based on the CUSTID parameter. The value of the u2version parameter must be used in the If-Match HTTP header.
* logfile="restput" * a = protocolLogging(logfil, "ON", 10) * PRINT "WHICH ID WOULD YOU LIKE TO Update?" INPUT CUSTID * method="GET" url="http://myserver.com:9191/demo/Customer/":CUSTID * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = submitRequest(restGET, 5000, "", Header, restData,| httpStatus) * * Get Data Record u2version ID * MYSTRING = CHANGE(restData, '"u2version"', @AM ) U2VERSION = FIELD(MYSTRING<2>, '"', 2) PRINT MYSTRING * putDATA = '{' putDATA:=' "_id" : "':CUSTID:'",' putDATA:= "'_original': 'null'," putDATA:= "'_synonym': 'null'," putDATA:= "'activity': ''," putDATA:= "'address': ['4600 South Ulster Street']," putDATA:= "'avg_out': ''," putDATA:= "'categories_liked': ['C']," putDATA:= "'city': 'Denver'," putDATA:= "'cur_balance': '0.00'," putDATA:= "'name': 'Seagoon, Neddy'," putDATA:= "'phone': '8007293553'," putDATA:= "'state': 'CO'," putDATA:= "'up_name': ''," putDATA:= "'zip': '80237'," putDATA:=' }' * * call the REST subroutine service with HTTP POST method="PUT" * stat = createRequest(url, method, restPUT) stat = setRequestHeader(restPUT, "Content-Type",| "application/json; charset=utf-8") stat = setRequestHeader(restPUT, "If-Match", U2VERSION) * stat = submitRequest(restPUT, 5000, putDATA, Header, restData,| httpStatus) * put response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10))
300 UniBasic HTTP DELETE
restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfil, "OFF", 10) END
UniBasic HTTP DELETE
The following example demonstrates how to use the HTTP DELETE function in U2 REST. An HTTP GET request is called first, followed by the HTTP DELETE request. An existing RECORD ID record, based on the CUSTID parameter, is deleted. The value for the u2version parameter must be used in the If-Match HTTP DELETE header.
* logfile = "restdelete" * stat = protocolLogging(logfile, "ON", 10) PRINT "WHICH ID WOULD YOU LIKE TO DELETE?" INPUT CUSTID
url="http://myserver.com:9191/demo/Customer/":CUSTID method="GET" * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) * stat = submitRequest(restGET, 5000, "", Header, restData,| httpStatus) * restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * * Get Data Record u2version ID * MYSTRING = CHANGE(restData, '"u2version"', @AM ) U2VERSION = FIELD(MYSTRING<2>, '"', 2) PRINT U2VERSION * * call the REST subroutine service with HTTP DELETE method="DELETE" * stat = createRequest(url, method, restDELETE) stat = setRequestHeader(restDELETE, "Content-Type", "application/json; charset=utf-8") stat = setRequestHeader(restDELETE, "if-match", U2VERSION) stat = submitRequest(restDELETE, 5000, "", Header, restData,| httpStatus) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header * PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfile, "OFF", 10) END
301 Chapter 6: U2 RESTful Web Service Developer
UniBasic REST subroutine
This program calls a U2 Subroutine from the U2 REST Server with HTTP POST. Data in the procDATA indata field is sent to the U2 subroutine. Data from the subroutine attaches to the indata field and displays as returned data in the outdata field, as shown:
Note: U2 REST service fields are case sensitive.
* logfile="restpost" * stat = protocolLogging(logfile, "ON", 10) * method="POST" url="http://myserver.com:9191/demo/subroutine/RETSUB" stat = setHTTPDefault("VERSION", "1.1") * PRINT "Enter the data to send to RETSUB: " INPUT INDATA * * Customer Record to be written to record CUSTID * procDATA = "{" procDATA:=' "indata" : "':INDATA:'",' procDATA := "}" * stat = createRequest(url, method, procPOST) stat = setRequestHeader(procPOST, "Content-Type",| "application/json; charset=utf-8") stat = submitRequest(procPOST, 5000, procDATA, Header, restData,| httpStatus) * POST response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus *PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * * stat = protocolLogging(logfile, "OFF", 10) * END
UniBasic RETSUB
RETSUB is a UniBasic subroutine that returns a "Calling Program sent:" message to the U2 REST server. Data from this subroutine attaches to the indata field and displays as returned data in the outdata field, as shown:
Note: The U2 REST service fields are case sensitive.
SUBROUTINE RETSUB(p1, p2)
p2="Calling Program sent: ":p1
302 UniBasic URLENC
RETPROG This program tests the RETSUB subroutine by parsing the value “NED” and printing the return results.
A="NED: " B="" CALL RETSUB(A,B) PRINT B
UniBasic URLENC
The URLENC program takes the data in the mydata file and URL encodes it. The URL encoded data is sent to myresult. The program then decodes myresult and is URL decoded in myresult2.
CRT "URLEncode and URLDecode example" mydata=": / ? # &" encstat=ENCODE("URLENCODE", 1, mydata, 1, myresult, 1) PRINT "enco stat : ":encstat PRINT myresult encstat=ENCODE("URLENCODE", 2, myresult, 1, myresult2, 1) PRINT encstat PRINT myresult2
UniVerse BASIC code samples
The U2 RESTful web services sample codes in this section are written for UniVerse in UniBasic. They demonstrate the following methods: ▪ HTTP GET ▪ HTTP POST ▪ HTTP PUT ▪ HTTP DELETE ▪ RESTSUB - An HTTP subroutine ▪ RETPROG - A subroutine test program ▪ RETSUB - A UniVerse BASIC subroutine ▪ URLENC - An encoding program
UniVerse BASIC HTTP GET
The HTTP GET method can only be used on U2 REST data resources. The following example illustrates a typical HTTP GET request. The request calls the U2 REST server using a GET statement, and then returns a customer record based on the requested CUSTID:
* * logfile = "restget" * stat = protocolLogging(logfile, "ON", 10) * PRINT "WHICH CUSTOMER record ID would you like to GET?" INPUT CUSTID * * URL returned as html or json data
303 Chapter 6: U2 RESTful Web Service Developer
url="http://myserver.com:9193/HS_SALES/Customer/":CUSTID method="GET" * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = submitRequest(restGET, 5000, "", Header, restData,| httpStatus) * * GET response parser restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * * stat = protocolLogging(logfile, "OFF", 10) END
UniVerse BASIC HTTP POST
The HTTP POST method is used to create a new data record or to call a BASIC subroutine. The following example demonstrates how to use the HTTP POST request. In this program, we call the U2 REST server using an HTTP POST request. The request then uses postData information to create a new record based on the CUSTID parameter.
* logfile="restpost" * stat = protocolLogging(logfile, "ON", 10) * method="POST" url="http://myserver.com:9193/HS_SALES/Customer" stat = setHTTPDefault("VERSION", "1.1") * PRINT "Enter Unique Customer ID to create: " INPUT CUSTID * * Customer Record to be written to record CUSTID * postDATA='{' postDATA:=' "statename" : "Colorado",' postDATA:=' "state" : "CO",' postDATA:=' "fname" : "Neddy",' postDATA:=' "city" : "Denver",' postDATA:=' "lname" : "Seagoon",' postDATA:=' "sal" : "Mr.",' postDATA:=' "phone" : "8007293553",' postDATA:=' "custid" : "':CUSTID:'",' postDATA:=' "addr1" : "4700 South Syracuse Street",' postDATA:=' "addr2" : "444",' postDATA:=' "zip" : "80237",' postDATA:=' "company" : "IBM Corporation."' postDATA:='}' * stat = createRequest(url, method, restPOST) stat = setRequestHeader(restPOST, "Content-Type",| "application/json; charset=utf-8") stat = submitRequest(restPOST, 5000, postDATA, Header, restData,| httpStatus) * POST response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10))
304 UniVerse BASIC HTTP PUT
restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus *PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfile, "OFF", 10) END
UniVerse BASIC HTTP PUT
The following example demonstrates a typical GET/PUT combination being used to update a resource. A GET request executes to retrieve the contents of the u2version parameter, which is the record’s LastUpdate ID. The client program then calls the U2 REST server with an HTTP PUT request, using the postData information to modify an existing record based on the CUSTID parameter. The value of the u2version parameter must be used in the If-Match HTTP header.
* logfile="restput" * a = protocolLogging(logfile, "ON", 10) * PRINT "WHICH ID WOULD YOU LIKE TO Update?" INPUT CUSTID * method="GET" url="http://myserver.com:9193/HS_SALES/Customer/":CUSTID * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = submitRequest(restGET, 5000, "", Header, restData,| httpStatus) * * Get Data Record u2version ID * MYSTRING = CHANGE(restData, '"u2version"', @AM ) U2VERSION = FIELD(MYSTRING<2>, '"', 2) * putDATA='{' putDATA:=' "statename" : "Colorado",' putDATA:=' "state" : "CO",' putDATA:=' "fname" : "Neddy",' putDATA:=' "city" : "Denver",' putDATA:=' "lname" : "Seagoon",' putDATA:=' "sal" : "Ms.",' putDATA:=' "phone" : "(800)729-3553",' putDATA:=' "custid" : "':CUSTID:'",' putDATA:=' "addr1" : "4600 South Ulster Street.",' putDATA:=' "addr2" : "",' putDATA:=' "zip" : "80237",' putDATA:=' "company" : "Rocket Software, Inc."' putDATA:='}' * * call the REST subroutine service with HTTP POST method="PUT" * stat = createRequest(url, method, restPUT) stat = setRequestHeader(restPUT, "Content-Type",| "application/json; charset=utf-8") stat = setRequestHeader(restPUT, "if-match", U2VERSION) * stat = submitRequest(restPUT, 5000, putDATA, Header, restData,| httpStatus) * put response restData=CHANGE(restData, "{", "{":CHAR(10))
305 Chapter 6: U2 RESTful Web Service Developer
restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfil, "OFF", 10) END
UniVerse BASIC HTTP DELETE
The following example demonstrates how to use the HTTP DELETE function in U2 REST. An HTTP GET request is called first, followed by an HTTP DELETE request. An existing RECORD ID record, based on the CUSTID parameter, is deleted. The value for the u2version parameter must be used in the If-Match HTTP DELETE header.
* logfile = "restdelete" * stat = protocolLogging(logfile, "ON", 10) * *PRINT "WHICH ID WOULD YOU LIKE TO DELETE?" INPUT CUSTID * url="http://myserver.com:9193/HS_SALES/Customer/":CUSTID method="GET" * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) * stat = submitRequest(restGET, 5000, "", Header, restData,| httpStatus) * restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * * Get Data Record u2version ID * MYSTRING = CHANGE(restData, '"u2version"', @AM ) U2VERSION = FIELD(MYSTRING<2>, '"', 2) PRINT U2VERSION * * call the REST subroutine service with HTTP DELETE method="DELETE" * stat = createRequest(url, method, restDELETE) stat = setRequestHeader(restDELETE, "Content-Type",| "application/json; charset=utf-8") stat = setRequestHeader(restDELETE, "if-match", U2VERSION) stat = submitRequest(restDELETE, 5000, "", Header, restData,| httpStatus) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header * PRINT "Response data:":CHAR(10):restData * stat = protocolLogging(logfile, "OFF", 10) END
306 UniVerse BASIC REST subroutine
UniVerse BASIC REST subroutine
This program calls a U2 Subroutine from the U2 REST Server with HTTP POST. Data in the procDATA indata field is sent to the U2 subroutine. Data from the subroutine attaches to the indata field and displays as returned data in the outdata field, as shown:
Note: U2 REST service fields are case sensitive.
* logfile="restpost" * stat = protocolLogging(logfile, "ON", 10) * method="POST" url="http://myserver.com:9193/HS_SALES/subroutine/RETSUB" stat = setHTTPDefault("VERSION", "1.1") * PRINT "Enter the data to send to RETSUB: " INPUT INDATA * * Customer Record to be written to record CUSTID * procDATA = "{" procDATA:=' "indata" : "':INDATA:'",' procDATA := "}" * stat = createRequest(url, method, procPOST) stat = setRequestHeader(procPOST, "Content-Type",| "application/json; charset=utf-8") stat = submitRequest(procPOST, 5000, procDATA, Header, restData,| httpStatus) * POST response restData=CHANGE(restData, "{", "{":CHAR(10)) restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus *PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * * stat = protocolLogging(logfile, "OFF", 10) * END
UniVerse BASIC RETSUB
RETSUB is a UniBasic subroutine that returns a "Calling Program sent:" message to the U2 REST Server. Data from this subroutine attaches to the indata field and displays as returned data in the outdata field, as shown:
Note: Note: The U2 REST service fields are case sensitive.
* SUBROUTINE RETSUB(p1, p2) p2="Calling Program sent: ":p1 * CONVERT @AM TO CHAR(10):CHAR(13) IN p2 END
307 Chapter 6: U2 RESTful Web Service Developer
RETPROG This program tests the RETSUB subroutine by parsing the value “NED” and printing the return results.
A="NED: " B="" CALL RETSUB(A,B) PRINT B
UniVerse BASIC URLENC
The URLENC program takes the data in themydata file and URL encodes it. The URL encoded data is sent to myresult. The program then decodes myresult and is URL decoded in myresult2.
CRT "URLEncode and URLDecode example" mydata=": / ? # &" encstat=ENCODE("URLENCODE", 1, mydata, 1, myresult, 1) PRINT "enco stat : ":encstat PRINT myresult encstat=ENCODE("URLENCODE", 2, myresult, 1, myresult2, 1) PRINT encstat PRINT myresult2 *
Python for UniData code samples
The U2 RESTful web services sample codes in this section are written for UniData in Python. The Python examples demonstrate the following methods: ▪ HTTP GET ▪ HTTP POST ▪ HTTP PUT ▪ HTTP DELETE ▪ RESTSUB - An HTTP subroutine The following examples were written using Python 3.2. Refer to www.python.org for more information on Python.
Note: The samples in this appendix are provided to demonstrate how Python can be used within U2 RESTful web services. UniData and UniVerse do not offer any support for Python.
Python for UniData: HTTP GET
The HTTP GET method can only be used on U2 REST data resources. The following example illustrates a typical HTTP GET request. The request calls the U2 REST server using a GET statement, and then returns a customer record based on the requested CUSTID:
import httplib2 import json from pprint import pprint # custid = str(input("WHICH CUSTOMER record ID would you like to GET? "))
308 Python for UniData: HTTP POST
# UniData url (Select record id 2) url = "http://myserver.com:9191/demo/Customer/"+custid method="GET" # stat = httplib2.Http(".cache") restStatus, restData = stat.request(url, method) # print ("\nResponse Status: ", restStatus.status) # data = json.loads(restData.decode("UTF-8")) pprint(data)
Python for UniData: HTTP POST
The HTTP POST method is used to create a new data record or to call a BASIC subroutine. The following example demonstrates how to use the HTTP POST request. In this program, we call the U2 REST server using an HTTP POST request. The request then uses postData information to create a new record based on the CUSTID parameter.
import httplib2 import json from pprint import pprint # #custid = str(input("Enter Unique Customer ID to create: ")) url = "http://myserver.com:9191/demo/Customer" method="POST" headers = {"Content-type": "application/json;charset=utf-8"} # # Customer Record to be written to record CUSTID # postDATA={ '_id' : ''+custid+'', '_original': 'null', '_synonym': 'null', 'activity': '', 'address': ['4700 South Syracuse Street'], 'avg_out': '', 'categories_liked': ['C'], 'city': 'Denver', 'cur_balance': '0.00', 'name': 'Seagoon, Neddy', 'phone': '3034495641', 'state': 'CO', 'up_name': '', 'zip': '80237', } # postDATA = json.dumps(postDATA) stat = httplib2.Http(".cache") restStatus, restData = stat.request(url,method, postDATA, headers) # print ("\nResponse Status: ", restStatus.status) data = json.loads(restData.decode("UTF-8")) pprint(data)
309 Chapter 6: U2 RESTful Web Service Developer
Python for UniData: HTTP PUT
The following example demonstrates a typical GET/PUT combination being used to update a resource. A GET request executes to retrieve the contents of the u2version parameter, which is the record’s LastUpdate ID. The client program then calls the U2 REST server with an HTTP PUT request, using the postData information to modify an existing record based on the CUSTID parameter. The value of the u2version parameter must be used in the If-Match HTTP header.
import httplib2 import json from pprint import pprint # custid= str(input("WHICH ID WOULD YOU LIKE TO Update? ")) # UniData url (Select record id 2) url = "http://myserver.com:9191/demo/Customer/"+custid method = "GET" # statget = httplib2.Http(".cache") restStatus, restData = statget.request(url, method) data = json.loads(restData.decode("UTF-8")) # u2version = (data["u2version"]) pprint (u2version) # method = "PUT" # putDATA={ '_id' : ''+custid+'', '_original': 'null', '_synonym': 'null', 'activity': '', 'address': ['4600 South Ulster Street'], 'avg_out': '', 'categories_liked': ['C'], 'city': 'Denver', 'cur_balance': '0.00', 'name': 'Seagoon, Neddy', 'nbr_tapes': '', 'num_rentals': '', 'phone': '8007293553', 'state': 'CO', 'up_name': '', 'zip': '80237' } # putDATA = json.dumps(putDATA) statput = httplib2.Http(".cache") headers = {"Content-type": "application/json;charset=utf-8", "If-Match": (u2version)} restStatus, restData = statput.request(url,method, putDATA,| headers=headers) # print ("\nResponse Status: ", restStatus.status) data = json.loads(restData.decode("UTF-8")) pprint(data) #
Python for UniData: HTTP DELETE
The following example demonstrates how to use the HTTP DELETE function in U2 REST. An HTTP GET request is called first, followed by the HTTP DELETE request. An existing RECORD ID record, based on
310 Python for UniData: REST subroutine
the CUSTID parameter, is deleted. The value for the u2version parameter must be used in the If-Match HTTP DELETE header.
import httplib2 import json from pprint import pprint # custid= str(input("WHICH ID WOULD YOU LIKE TO Delete? ")) url = "http://myserver.com:9191/demo/Customer/"+custid method = "GET" # statget = httplib2.Http(".cache") restStatus, restData = statget.request(url, method) data = json.loads(restData.decode("UTF-8")) # u2version = (data["u2version"]) #print (u2version) # method = "DELETE" # statdelete = httplib2.Http(".cache") headers = {"Content-type": "application/json;charset=utf-8", "If-Match": (u2version)} restStatus, restData = statdelete.request(url,method, headers=headers) # print ("\nResponse Status: ", restStatus.status)
Python for UniData: REST subroutine
This program calls a U2 subroutine from the U2 REST Server with HTTP POST. Data in the procDATA indata field is sent to the U2 subroutine. Data from the subroutine attaches to the indata field and displays as returned data in the outdata field, as shown:
Note: U2 REST service fields are case sensitive.
import httplib2 import json from pprint import pprint # inpdata = str(input("Enter the data to send to RETSUB: ")) url="http://myserver.com:9191/demo/subroutine/RETSUB" method="POST" headers = {"Content-type": "application/json;charset=utf-8"} # # Customer Record to be written to record CUSTID # procDATA={ 'indata' : ''+inpdata+'', } procDATA = json.dumps(procDATA) # stat = httplib2.Http(".cache") restStatus, restData = stat.request(url,method, procDATA, headers) # print ("\nResponse Status: ", restStatus.status) data = json.loads(restData.decode("UTF-8")) pprint(data)
311 Chapter 6: U2 RESTful Web Service Developer
Python for UniVerse code samples
The U2 RESTful web services sample codes in this section are written for UniVerse in Python. The Python examples demonstrate the following methods: ▪ HTTP GET ▪ HTTP POST ▪ HTTP PUT ▪ HTTP DELETE ▪ RESTSUB - An HTTP subroutine The following examples were written using Python 3.2. Refer to www.python.org for more information on Python.
Note: The samples in this appendix are provided to demonstrate how Python can be used within U2 RESTful web services. UniData and UniVerse do not offer any support for Python.
Python for UniVerse: HTTP GET
The HTTP GET method can only be used on U2 REST data resources. The following example illustrates a typical HTTP GET request. The request calls the U2 REST server using a GET statement, and then returns a customer record based on the requested CUSTID:
import httplib2 import json from pprint import pprint # # This program calls the CUSTOMER file in UniVerse HS.SALES account with HTTP GET. This call returns a Customer record based on custid # Use custid = 2 # Wr # custid = str(input("WHICH CUSTOMER record ID would you like to GET? ")) url = "http://myserver.com:9193/HS_SALES/Customer/"+custid method="GET" # stat = httplib2.Http(".cache") restStatus, restData = stat.request(url, method) # print ("\nResponse Status: ", restStatus.status) # data = json.loads(restData.decode("UTF-8")) pprint(data)
Python for UniVerse: HTTP POST
The HTTP POST method is used to create a new data record or to call a BASIC subroutine. The following example demonstrates how to use the HTTP POST request. In this program, we call the U2 REST server using an HTTP POST request. The request then uses postData information to create a new record based on the CUSTID parameter.
import httplib2
312 Python for UniVerse: HTTP PUT
import json from pprint import pprint # custid = str(input("Enter Unique Customer ID to create: ")) url="http://myserver.com:9193/HS_SALES/Customer" method="POST" headers = {"Content-type": "application/json;charset=utf-8"} # # Customer Record to be written to record CUSTID # postDATA={ 'statename' : 'Colorado', 'state' : 'CO', 'fname' : 'Neddy', 'city' : 'Denver', 'lname' : 'Seagoon', 'sal' : 'Mr.', 'phone' : '8007293553', 'custid' : ''+custid+'', 'addr1' : '4700 South Syracuse Street', 'addr2' : '', 'zip' : '80237', 'company' : 'IBM Corporation.', } # postDATA = json.dumps(postDATA) stat = httplib2.Http(".cache") restStatus, restData = stat.request(url,method, postDATA, headers) # print ("\nResponse Status: ", restStatus.status) data = json.loads(restData.decode("UTF-8")) pprint(data)
Python for UniVerse: HTTP PUT
The following example demonstrates a typical GET/PUT combination being used to update a resource. A GET request executes to retrieve the contents of the u2version parameter, which is the record’s LastUpdate ID. The client program then calls the U2 REST server with an HTTP PUT request, using the postData information to modify an existing record based on the CUSTID parameter. The value of the u2version parameter must be used in the If-Match HTTP header.
import httplib2 import json from pprint import pprint # custid= str(input("WHICH ID WOULD YOU LIKE TO Update? ")) url="http://myserver.com:9193/HS_SALES/Customer/"+custid method = "GET" # statget = httplib2.Http(".cache") restStatus, restData = statget.request(url, method) data = json.loads(restData.decode("UTF-8")) # u2version = (data["u2version"]) pprint (u2version) method = "PUT" # putDATA ={ 'statename' : 'Colorado', 'state' : 'CO',
313 Chapter 6: U2 RESTful Web Service Developer
'fname' : 'Neddy', 'city' : 'Denver', 'lname' : 'Seagoon', 'sal' : 'Ms.', 'phone' : '(800)729-3553', 'custid' : ''+custid+'', 'addr1' : '4600 South Ulster Street.', 'addr2' : '', 'zip' : '80237', 'company' : 'Rocket Software, Inc.' } # putDATA = json.dumps(putDATA) statput = httplib2.Http(".cache") headers = {"Content-type": "application/json;charset=utf-8", "If-Match": (u2version)} restStatus, restData = statput.request(url,method, putDATA, headers) #print ("\nResponse Status: ", restStatus.status) data = json.loads(restData.decode("UTF-8")) pprint(data)
Python for UniVerse: HTTP DELETE
The following example demonstrates how to use the HTTP DELETE function in U2 REST. An HTTP GET request is called first, followed by an HTTP DELETE request. An existing RECORD ID record, based on the CUSTID parameter, is deleted. The value for the u2version parameter must be used in the If-Match HTTP DELETE header.
import httplib2 import json from pprint import pprint # custid= str(input("WHICH ID WOULD YOU LIKE TO Delete?")) url="http://myserver.com:9193/HS_SALES/Customer/"+custid method = "GET" # stat = httplib2.Http(".cache") restStatus, restData = stat.request(url, method) # data = json.loads(restData.decode("UTF-8")) # u2version = (data["u2version"]) #print (u2version) # method = "DELETE" # headers = {"Content-type": "application/json;charset=utf-8", "If-Match": (u2version)} restStatus, restData = stat.request(url,method, headers=headers) # print ("\nResponse Status: ", restStatus.status)
Python for UniVerse: REST subroutine
This program calls a U2 Subroutine from the U2 REST Server with HTTP POST. Data in the procDATA indata field is sent to the U2 subroutine. Data from the subroutine attaches to the indata field and displays as returned data in the outdata field, as shown:
314 Authenticating a U2 REST server
Note: U2 REST service fields are case sensitive.
import httplib2 import json from pprint import pprint # inpdata = str(input("Enter the data to send to RETSUB: ")) url="http://myserver.com:9193/HS_SALES/subroutine/RETSUB" method="POST" headers = {"Content-type": "application/json;charset=utf-8"} # # Customer Record to be written to record CUSTID # procDATA={ 'indata' : ''+inpdata+'', 'outdata': '', } procDATA = json.dumps(procDATA) # stat = httplib2.Http(".cache") restStatus, restData = stat.request(url,method, procDATA, headers) #print ("\nResponse Status: ", restStatus.status) data = json.loads(restData.decode("UTF-8")) pprint(data)
Authenticating a U2 REST server
Authenticating a U2 REST server using an HTTP GET request. The following UniBasic example illustrates how to call a U2 REST server RESTful service using an HTTP GET request. The call will return a customer record based on the CUSTID account.
logfile = "restget" stat = protocolLogging(logfile, "ON", 10) * Ret = setHTTPDefault("HEADERS","") Ret = setHTTPDefault("VERSION","1.1") Status = setHTTPDefault("AUTHENTICATE","RestUser:MyPassword") PRINT Status Ret=setHTTPDefault("HEADERS", "User-Agent":@VM:"Company A") PRINT "Def: ":Ret * PRINT "WHICH CUSTOMER record ID would you like to GET?" INPUT CUSTID * * URL returned as HTML or JSON data url="http://den-l-nk01.rocketsoftware.com:9191/demo/Customer/" url:=CUSTID method="GET" * stat = setHTTPDefault("VERSION", "1.1") stat = createRequest(url, method, restGET) stat = submitRequest(restGET, 5000, "", Header, restData, httpStatus) * * GET response parser restData=CHANGE(restData, "{", "{":CHAR(10))
315 Chapter 6: U2 RESTful Web Service Developer
restData=CHANGE(restData, ",", ",":CHAR(10)) restData=CHANGE(restData, "}", "}":CHAR(10)) * PRINT "Response status: ":httpStatus * PRINT "Response headers:":Header PRINT "Response data:":CHAR(10):restData * a = protocolLogging(logfile, "OFF", 10) END
U2 BASIC subroutine
The following U2 BASIC Subroutine UDOSUB performs a tax calculation on the input data from the U2 REST Server. The input JSON object from the U2 REST server attaches to the INJSON parameter and performs a tax calculation on the subtotal parameter. The subtotal, Tax and Total value pairs are returned as JSON objects in the OUTJSON parameter. The OUTJSON parameter must be a correctly formed JSON object if the data has been manipulated inside a subroutine. U2 Dynamic Object (UDO) is the perfect consumer and provider of a JSON object. Refer to the UniData UniBasic Extensions manual for more information about the U2 Dynamic Object.
$INCLUDE INCLUDE UDO.H udohandle = "" STATUS =UDORead(INJSON, UDOFORMAT_JSON, udoHandle ) propertyName = "subTotal" STATUS = UDOGetProperty(udoHandle, propertyName, valueOut, valueTypeOut) TAX = valueOut * 0.085 TOTAL = valueOut + TAX STATUS = UDOSetProperty(udoHandle, "tax", TAX) totalProperty = "total" STATUS = STATUS = UDOSetProperty(udoHandle, totalProperty, TOTAL) STATUS = UDOWrite(udoHandle, UDOFORMAT_JSON, OUTJSON) RETURN
After you create the subroutine, set up the parameters for your subroutine service in the U2 RESTful Web Services Developer. It should look similar to the following example:
316 Output types
When you run the subroutine service in the U2 RESTful Web Services Developer, the return value should look similar to the following:
Output types
The following example shows how to create a multivalue array in a subroutine, based on a RESTful service. When creating a RESTful call to a BASIC subroutine, the inputs and outputs can be defined as one of the following:
Input/Output type Description String The contents of the variable are returned as one long string in the response. Dynamic array Attributes, values and sub-values are mapped to JSON.
317 Chapter 6: U2 RESTful Web Service Developer
Input/Output type Description JSON The variable returned from the subroutine returns a JSON string.
The following subroutine returns all three output types: String, Dynamic array, and JSON.
SUBROUTINE exampleSub( string, dynamicArray, json ) * Start by building a simple U2 Dynamic array OUTPUT = "" OUTPUT<1> = "Doe, John" OUTPUT<2> = "34" OUTPUT<3,1> = "Jane" OUTPUT<3,2> = "Jim" * * Returns the same data for both the string and dynamic array. string = OUTPUT dynamicArray = OUTPUT * ** Create a JSON string from the data in the dynamic array json = '{ name: "':OUTPUT<1>:'", age: ':OUTPUT<2>:', children: [ "':OUTPUT<3, 1>:'", "':OUTPUT<3,2>'" ] }' * RETURN
Procedure
1. Add the subroutine to a DIR type file, and then compile and catalog the subroutine so that it is visible to the Restful web server.
318 Output types
2. In the RESTful Web Services Developer, create a subroutine resource for the subroutine you cataloged in the previous step. Define the input/output parameters based on your subroutine. When you are done defining the subroutine resource output parameters, click Finish. In this example, only the output parameters are defined.
3. From the U2 REST Servers pane, double-click the dynamic array for which you want to define the fields. The Edit Dynamic Array dialog box opens.
319 Chapter 6: U2 RESTful Web Service Developer
4. Enter the data type information for your dynamic array. When you are done, click Finish. In this example, name and age are single-valued data types and children is a multivalued data type.
5. From the U2 REST server pane, double-click the name of the subroutine to run the test subroutine service. The results appear in the Test Browser.
320 Output types
6. Click Call Service to invoke the RESTful service and view the multivalued output you defined earlier. In this example, age is returned as a number type.
Note: The string type returns the attribute marks and value marks, the dynamic array returns the value mapped as a JSON object (all values are strings), and the JSON output type allows you to create more complex JSON requests in the subroutine.
321 Chapter 6: U2 RESTful Web Service Developer
Troubleshooting
Backing up the U2 REST Developer workspace
There are two ways you can back up your U2 REST workspace: a complete backup and a partial backup. ▪ To completely back up your workspace, navigate to the directory where the U2 REST Developer is located and then backup the directory. By default, the developer located in C:\U2\U2Tools\v4. ▪ To partially back up your workspace, export the U2 REST server project and then back up the exported zip file. This solution backs up all the necessary components of the project.
Adjusting Java heap space
You are able to modify the heap size for a Java virtual machine when starting a U2 RESTful server. This option is not enabled by default. Under most conditions the U2 REST products 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.
Procedure
1. Open the U2 RESTful Web Services Developer. 2. Navigate to Window → Preferences and then expand the UniData/UniVerse node. 3. Select U2 RESTful Web Services Developer.
322 Adjusting Java heap space in a deployed environment
4. Select the Set Java heap sizes option, and then modify the sizes as necessary.
Figure 3: RESTful web services UniData/UniVerse Preferences
5. Select Apply to apply the settings and then click OK .
Adjusting Java heap space in a deployed environment
Under most conditions the U2 REST products 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 runrestserver.bat file on Windows 1. Open the runrestserver.bat file using an editor.
323 Chapter 6: U2 RESTful Web Service Developer
2. Locate the following line:
start javaw.exe -classpath... 3. Modify the command to the following:
start javaw.exe -Xms512m -Xmx1024m -classpath... 4. Save the file and then restart the U2 REST server.
Modifying the runrestserver.sh file on UNIX 1. Open the runrestserver.sh file using an editor. 2. Locate the following line:
start javaw -classpath... 3. Modify the command to the following:
start javaw -Xms512m -Xmx1024m -classpath... 4. Save the file and then restart the U2 REST server.
Note: The JVM startup parameters offer a variety of options for operating the JVM. For details and a complete list of the available JVM startup parameters, refer to www.oracle.com.
Defining web server listening IP addresses
Web servers listen when started on IP address 0.0.0.0, which allows clients outside of that server on the network to connect. It is sometimes necessary to restrict outside access to the server by changing the listening address to 127.0.0.1. By doing so, only the local server can connect to any port the web server has enabled. This feature is only available on a deployed server and not from the U2 RESTful Web Service Developer.
To change the web server IP address to 127.0.0.1, add -Dloopbackonly=true to the startup script as shown in the following examples.
System Script name Script Windows runrestserver.bat javaw.exe –Dloobackonly=true – classpath ... UNIX/Linux runrestserver.sh nohup $JRE_DIR/$JRE_EXE – Dloobackonly=true -Dfile ...
Defining the JRE_HOME environment variable
To deploy a U2 RESTful Server, you must set the JRE_HOME environment variable. The JRE_HOME environment variable must point to the location of the JRE installation directory. For more information about how to locate the JRE on your system, refer to the documentation at http:// www.oracle.com/technetwork/documentation/index.html.
324 Defining the JRE_HOME environment variable
Defining the JRE_HOME variable in a UNIX environment
To locate the JREs on your system, run the find / -name java –print command. This will list all of the available JREs on your computer. Set the value of the JRE_HOME environment variable to point to the appropriate path for your system using the correct UNIX shell command. For example, export JAVA_HOME=/usr/java6/jre.
Defining the JRE_HOME variable in a Windows environment
To locate the JREs on your system, run the C:\>dir /s "java.exe" command. This will list all of the available JREs on your computer. Set the value of the JRE_HOME environment variable to point to the appropriate path for your system. For example, set JRE_HOME= C:\Program Files\Java\jre6.
325 Chapter 7: U2 Web Service Developer
U2 Web Service Developer perspectives
Once the Web Service Developer is installed, the U2 Web Service Developer perspective is displayed. The U2 Web Service Developer perspective contains multiple panes, called views. Views structure the workspace and serve as a device to organize similar items inside a defined work area. As an example, the U2 Resource view, the U2 Web Service Developer editor, and the U2 Dictionary view can all be open in the workplace at the same time. By default, the perspective is arranged in a standard layout, but you can move or resize views to suit your needs. Each view contains controls for minimizing and maximizing the space consumed within the U2 Web Service Developer perspective. You can also adjust the border of a view to increase or decrease its size. A view can contain one item or tabs for multiple items. After you close a view, you can select it from the Window menu to reopen it. You can also reset the main window to show all views in their default locations by clicking Window → Reset Perspective. The following figure highlights the different views found in the U2 Web Service Developer perspective.
326 Creating a query web service
Creating a query web service
Use the U2 Web Service Developer 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.
Defining SOAP servers
1. From the Start menu, select All Programs → Rocket U2 → Web Services Developer. 2. 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 opens.
3. 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, see Viewing the debug log, on page 331.
327 Chapter 7: U2 Web Service Developer
Field Description Log File Name The name of the debug log file. By default, the name of the debug log file is soapservername.log. Connection The Connection Pooling On setting determines whether UniData uses Pooling On 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 You can set the minimum and maximum size of the connection pool. If you Size 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 Specifies whether the server needs to validate the SOAP request Validation 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 The name space for the Web Services you define. Space Service Cache For performance purposes, you can set this value to a number greater than Size 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.
328 Defining SOAP servers
4. Click Next. The SOAP Server - Connection Security dialog box opens.
5. Optional: On the SOAP Server - Connection Security page, 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 Enter the password corresponding to the key store you defined in the Key Password Store field. Confirm Key Reenter the password corresponding to the key store you defined in the Key Store Password Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Reenter the encryption key password, if one exists. Password Enable If you want the client to send its certification for authentication, select the Authentication Need Client Authentication check box.
329 Chapter 7: U2 Web Service Developer
6. Click Next. The U2 Database - Connection Properties dialog box opens.
7. On the U2 Database- Connection Properties page, select the Specify default database connection properties check box.
330 Viewing the debug log
8. In the Host field, select the name of the SOAP server. After you select the SOAP server, the remaining fields in the dialog box are automatically populated with information from the server definition.
9. Optional: To test the connection to the database, click Test Database Connection.
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 Defining SOAP servers, on page 327. To use the debug log, do the following:
1. Click Soap Server Log to display the SOAP Server Logs, as shown in the following example:
U2 Web Services Developer displays the last 64KB in the SOAP Server log. 2. To erase the contents of the log file, click the Erase icon. 3. To refresh the contents of the log file, click the Refresh icon.
331 Chapter 7: U2 Web Service Developer
Displaying cached services
When you define the properties for your SOAP server, you can specify the server cache size. 1. For performance purposes, set the server cache size to the number of web services currently running, or larger. 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. 2. If you are developing a web service, it is recommend you keep this value at 0. Otherwise, the SOAP Server reloads the cache each time the web service is changed. 3. Select the Cached Services tab to display the web services currently loaded in cache.
Creating a query web service
Prerequisites ▪ Defining SOAP servers, on page 327
1. From the Start menu, select All Programs → Rocket U2 → Web Services Developer. 2. To create a Query Web Service, 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 opens.
3. In the Service Name field, enter a name for the web service you are creating.
332 Creating a query web service
4. In the Namespace field, verify or enter the namespace. Click Finish. The Update a SOAP server dialog box opens.
5. On the U2 Database- Connection Properties page, select the Specify default database connection properties check box.
333 Chapter 7: U2 Web Service Developer
6. In the Host field, select the name of the SOAP server. After you select the SOAP server, the remaining fields in the dialog box are automatically populated with information from the server definition.
7. Optional: To test the connection to the database, click Test Database Connection.
334 Creating a query web service
8. Click Next. The SOAP Server - Connection Security dialog box opens.
9. Optional: On the SOAP Server - Connection Security page, 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 Enter the password corresponding to the key store you defined in the Key Password Store field. Confirm Key Reenter the password corresponding to the key store you defined in the Key Store Password Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Reenter the encryption key password, if one exists. Password Enable If you want the client to send its certification for authentication, select the Authentication Need Client Authentication check box.
335 Chapter 7: U2 Web Service Developer
10. Click Next. The Operation dialog box opens.
11. On the Operations page, enter a name for the new web service and select Query as the type. 12. In the Query area, define the query command: a. In the Command field, enter a UniQuery LIST or SORT commands or a UniData SQL SELECT statement. To specify an input parameter, use a question mark as a placeholder for the input value. b. Optional: In the Map FileName field, enter the name of the mapping file you want to use. The mapping file must be located in the _XML_ directory. c. Optional: In the Record Name field, enter a name for the root element in the XML document that the web service creates for the query. If the web service has two or more query operations that the same data file has, enter a unique record name for each operation. d. Click the Save icon.
336 Creating a query web service
13. Click Next. The Input/Output Parameters dialog box opens.
14. If you specified a placeholder in the web service command, click the input parameter, then click arg_1. The Parameter Details dialog box opens.
15. On the Parameter Details page, complete the following fields:
Field Action
Name Enter a meaningful name for the input parameter.
Position Enter the prompting order of the input parameter.
Type Select the data type for the input parameter. Valid values are String and Dynamic array.
337 Chapter 7: U2 Web Service Developer
16. Click Finish. The web service definition appears in the Web Service area of U2 Web Services Developer window.
Starting the web service
1. To start a web service, click the Launch icon from the toolbar. The Web Services Explorer window opens. 2. Click the WSDL icon. 3. Under the Navigator area of the Web Services Explorer window, click WSDL Main. The Open WSDL dialog box opens.
338 Creating a subroutine 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. Creating a subroutine web service
Use a UniBasic subroutine to create a web service.
Note: You cannot publish a subroutine that requires interactive user input as a web service.
339 Chapter 7: U2 Web Service Developer
Creating subroutine web services
▪ Defining SOAP servers, on page 327 You must catalog the subroutine before you start the U2 Web Service Developer. You can globally, locally, or directly catalog subroutines.
1. From the Start menu, select All Programs → Rocket U2 → Web Services Developer. 2. To create a subroutine web service, right-click the SOAP server where you want to create the service, and click New Web Service. 3. Optional: On the U2 Database - Connection Properties page, specify connection properties. 4. Optional: On the U2 Database - Connection Security page, specify the connection security properties for the web service. 5. Click Next. The Operation dialog box opens.
6. In the Operations dialog box, in the Name field, enter the name of the web service you are creating. 7. From the Type options, select Subroutine. 8. In the Subroutine Name field, type the name of the subroutine. 9. In the Number of Parameters field, type the total number of parameters defined for the subroutine. 10. Click Next. The Input/Output Parameters page opens. 11. From the Input area, select the parameter, then click Edit. The Define Parameter dialog box opens. a. In the Name field, enter a meaningful name of the input parameter. This name does not have to match the name in the UniBasic program.
340 Creating subroutine web services
b. In the Position field, enter the position of the output parameter in the subroutine. c. In the Type field, select the data type for the input parameter from the list. Valid types are String and Dynamic array. d. Click OK. 12. 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. 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 opens.
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:
341 Chapter 7: U2 Web Service Developer
13. Double-click the dynamic array for which you want to define fields. The Dynamic Array Fields dialog box opens.
14. To manually add a field, click Add. The Define Field dialog box opens. a. In the Name field, enter the name of the field in the dynamic array. b. In the Location field, enter the location of the field in the dynamic array. c. In the Type field, enter the type of field. Valid types are: ▪ s - Single-valued ▪ mv - Multivalued ▪ ms - Multi-subvalued d. Click OK. 15. To populate the fields, drag and drop the database file from the account you are creating the web service into the Dynamic Array Fields dialog box . The U2 Web Services Developer populates the U2 Dictionary Attributes dialog box with each D- type dictionary record, as shown in the following example.
16. Select the check box beside each attribute you want to include in the dynamic array. The number of attributes that you select must equal the number of fields in the parameter in the subroutine. 17. Click the Save icon.
342 Defining dynamic arrays
Results The input parameters, output parameters, and dynamic arrays are displayed on the Web Service page, as shown in the following example:
Defining dynamic arrays
▪ Creating subroutine web services, on page 340
1. Double-click the dynamic array for which you want to define fields. The Dynamic Array Fields dialog box opens.
2. To manually add a field, click Add. The Define Field dialog box opens. a. In the Name field, enter the name of the field in the dynamic array. b. In the Location field, enter the location of the field in the dynamic array. c. In the Type field, enter the type of field. Valid types are: ▪ s - Single-valued ▪ mv - Multivalued ▪ ms - Multi-subvalued d. Click OK.
343 Chapter 7: U2 Web Service Developer
3. To populate the fields, drag and drop the database file from the account you are creating the web service into the Dynamic Array Fields dialog box . The U2 Web Services Developer populates the U2 Dictionary Attributes dialog box with each D- type dictionary record, as shown in the following example.
4. Select the check box beside each attribute you want to include in the dynamic array. The number of attributes that you select must equal the number of fields in the parameter in the subroutine. 5. Click the Save icon.
Results The input parameters, output parameters, and dynamic arrays are displayed on the Web Service page, as shown in the following example:
Starting the web service
1. To start a web service, click the Launch icon from the toolbar. The Web Services Explorer window opens. 2. Click the WSDL icon.
344 Starting the web service
3. Under the Navigator area of the Web Services Explorer window, click WSDL Main. The Open WSDL dialog box opens.
4. From the U2 Web Service area of the Web Services Developer window, click the highlighted web service. The properties of the web service appear in the Properties area of the Web Service window, as shown in the following example:
5. In the WSDL URL dialog box, enter the value of the End Point property, then click Go. 6. In the WSDL Details window, select the operation you want to execute, as shown in the following example:
7. Click the operation that you want to execute. In this case, CALL CUSTOMERSUB. The Web Service operation prompts you for input parameters you previously defined.
345 Chapter 7: U2 Web Service Developer
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:
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.
346 Account properties
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:
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:
347 Chapter 7: U2 Web Service Developer
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 I- type record, or association components if a PH-type record. CONV Conversion formula, if specified. NAME Display name, if specified. FORMAT Format code. SM Single-valued multivalued, or multi-subvalued code. ASSOC Association name, if part of an association. Manually accessing the web services
The section describes how to access web services manually. 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 web service URLs
You can use the U2 Web Services Developer main window to view the URLs for your web services, as shown in the following example: 1. Open the U2 Web Services Developer main window. 2. Expand the web server where the web service is located. 3. Click the web service for which you want to view the URL. 4. On the Properties tab, the End Point field display the URL for the web service.
Viewing the WSDL file
You can use a web browser to view WSDL files. In the browser, enter the web service URL. The WSDL file opens.
348 Web services clients
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 languages, including Java, C#, and VB.NET. 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. Deploying web services
You can select a SOAP server defined locally and generate a deployment package, in the form of a .zip file, that containing the following: ▪ WSDL files
▪ The runsoapserver and stopsoapserver scripts ▪ All required files for a runtime SOAP server
The .zip file contains a .bat file and .sh file, which you use to deploy web services on any platform.
Deploying SOAP Server
Exporting and importing web services
You can create a .zip file to deploy your web services. 1. From the Start menu, select All Programs → Rocket U2 → Web Services Developer.
349 Chapter 7: U2 Web Service Developer
2. Right-click the SOAP server that contains the web service you want to deploy, and select Export. The Export SOAP Servers dialog box opens.
3. In the Available SOAP Servers section, select the SOAP servers to export. 4. In the Archive File field, enter the path to the location where you want to create the .zip, or click Browse to search for the location. By default, the .zip file is created in the C:\U2\U2Tools\v4\soapservername.zip. The .zip file contains the following contents: ▪ 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 After exporting a web service from the source development system, you can import it on the target developer web service system. The following prerequisites much be completed before importing a web service: ▪ The SOAP server must be created on the target computer. ▪ The name of the target SOAP server must be the name of the source SOAP server.
350 Deploying the 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. 5. Right-click the SOAP server that contains the web service that you want to import, and select Import. 6. Click Browse to select the root directory for the SOAP server(s) that you want to import. for example, C:\temp\Test\u2soapdeploy. 7. Select the servers that you want to import, and then click Finish.
Deploying the SOAP server
1. Extract the .zip file on the target machine. 2. From the directory where you extracted the file, run the rundeploytool command: rundeploytool current_directory target_directory For example, rundeploytool.bat . C:\temp\myservice 3. Expand Deployable SOAP Servers, right-click the SOAP server you want to deploy, then click Deploy. If the SOAP server already exists, click Deploy Into. The SOAP Server Configuration dialog box opens.
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.
351 Chapter 7: U2 Web Service Developer
Configuration options Description 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. 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.
352 Updating the SOAP server
Updating the SOAP server
You can update the configuration file used to deploy the SOAP server from the development computer to the deployment environment. The configuration file holds information such as server name, port number, and connection pool information. 1. Open the Web Services Developer tool. 2. In the U2 Web Services pane, right-click the resource you want to update and then select Properties. 3. Follow the menu prompts and update the SOAP server information as needed.
Defining security between the client and the SOAP server
1. Click the Specify Connection Security check box if you want to define connection security between the client and the SOAP server. The SOAP Server Connection Security dialog box opens.
2. Select the Use SSL check box if you want to define the SSL security parameters. The following table describes the parameters.
Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Enter the password corresponding to the key store you defined in the Key Password Store field. Confirm Key Reenter the password corresponding to the key store you defined in the Key Store Password Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Reenter the encryption key password, if one exists. Password
353 Chapter 7: U2 Web Service Developer
Field Description Enable If you want the client to send its certification for authentication, select the Authentication Need Client Authentication check box. 3. Click Finish.
Setting connection properties
1. Click the DB Connection tab to define the connection properties for the SOAP server. The U2 Database - Connection Properties dialog box opens.
2. In the Host field, select the name of the host server. The server should be running. 3. In the Account field, select the account name of the 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. 4. In the User ID field, type your login name for the server. Type the corresponding password in the Password field. 5. In the UniRPC Service Name field, type uvcs for UniVerse or udcs for UniData. 6. In the UniRPC Port Number field, type the port number of the UniRPC service running on the host. The default port number is 31438. 7. Optional: To test the connection to the database, click Test Database Connection. 8. To use the connection properties for subsequent SOAP servers you deploy, select the Use this database connection and security for subsequent SOAP services during deployment check box. 9. Click Next.
354 Defining database connection security
Defining database connection security
1. Click the DB Security tab to define security between the SOAP server and the U2 database. The U2 Database Connection Security dialog box opens.
2. Select the Use SSL check box if you want to define the SSL security parameters. The following table describes the parameters.
Field Description Key Store Enter the full path to the key store on the SOAP server, or click Browse to navigate to the key store. Key Store Enter the password corresponding to the key store you defined in the Key Password Store field. Confirm Key Reenter the password corresponding to the key store you defined in the Key Store Password Store field. Key Password Enter the encryption key password, if one exists. Confirm Key Reenter the encryption key password, if one exists. Password Enable If you want the client to send its certification for authentication, select the Authentication Need Client Authentication check box. 3. Click Next.
Results When deployment is complete, a window similar to the following example appears:
355 Chapter 7: U2 Web Service Developer
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.
About this task
Note: A Windows service can only be created on a deployed package.
To create a SOAP service, use the following syntax:
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 SOAP service as a Windows service. -s The name of the SOAP service. -d Description of the SOAP service. The default value is “U2 SOAP service to start and stop U2 SOAP service. The text of the description must be enclosed in quotation marks.
356 Deploying the SOAP service from the command line
Option Description -r Removes the SOAP service.
After installing the SOAP service, it can started and stopped as a Windows service from the Windows control panel. When the service starts, it runs the runsoapserver.bat u2soap-server program and waits until this bat file exits. When the service stops, it runs the stopsoapserver.bat u2soapserver program. Additional arguments can be passed to the runsoapserver.bat by specifying the start parameters to the service.
Note: If you are creating a Windows service using the u2soapservice.exe program and you get an error similar to the one shown below, you must run the vcredist_x86.exe program supplied with the U2 WSD product to ensure the Windows platform has the compatible Microsoft Visual C++ 2005 redistributable runtime environment:
Error: The application has failed to start because its side-by-side configuration is incorrect. Please see the application event log for more details.
The syntax for removing a SOAP service is as follows:
U2soapservice.exe –r u2soap-server
Deploying the SOAP service from the command line
Use the command line options to deploy the U2 SOAP server from the development computer to the deployment environment. The command line options allow for option-driven, interactive command line deployment.
Starting the SOAP service from the command line
1. After exporting the SOAP services, extract the .zip file on to the target machine. The .zip file contains the following contents: ▪ 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
357 Chapter 7: U2 Web Service Developer
Note: Some OS environments, such as those running UNIX, cannot use .zip files. If this occurs, recompress the file with a non-zip extraction tool such as 7zip into a gz (gzip) type file.
2. Navigate to the server directory where you extracted the .zip file and locate the U2 SOAP deployment tool. 3. Run the rundeploytool command, as shown in the following example: rundeploytool.bat . C:\temp\myservice -s testserver -t prodserver The following table describes each parameter of the syntax: rundeploytool[.sh | .bat] deployable_server_dir [target_- server_dir]-s server_name [-t target_server] [-f config_file [-u] ]
Option Description rundeploytool[.bat The command to start the deployment tool. Use the .bat script for | .sh] 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. -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. 4. The U2 SOAP server configuration options open in the command line window. Select the appropriate command-line option, as described in the following table.
Option Description X Exit. A Accept the options and continue to the next set of 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. 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.
358 Defining connection security between the client and the SOAP server from the command line
Option Description 6 Minimum Connection Pool Size. Sets the minimum number of connections in the connection pool. The minimum size defaults to 1. 7 Maximum Connection Pool Size. Sets the maximum number of connections in the connection pool. The minimum size defaults to 10. 8 Checks the SOAP request again the schema defined in the WSDL file. This option is time consuming. By default, message validation is not selected. 9 The name space for the Web Services you define. 10 For performance purposes, you can set this value to a number greater than 0 to indicate the number of web service definitions you want to keep in the cache. If you set this value, the SOAP Server will always try to read the web service definition from the cache first. If you do not set this value, the SOAP Server reloads the web service each time from disk. If you are developing a web service, we recommend keeping this value at 0. This setting forces the SOAP Server to reload the new web service definition each time. Select the Cached Services tab to display the web services currently loaded in cache. 5. After making any changes to the deployment configuration options, click A to continue.
Defining connection security between the client and the SOAP server from the command line
After defining the connection configuration, you can define the connection security for the SOAP server. 1. The U2 SOAP connection security options open in the command line window. Select S to view the security options. 2. Select the appropriate action from the options presented in the command line window, as described in the following table.
Command line option Description X Exit. 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. 3. After defining any connection security settings for the server, enter A to continue.
Defining database connection properties from the command line
After defining the server connection properties, you can define the properties for the selected resource folder.
359 Chapter 7: U2 Web Service Developer
The Resource folder property options open in the command line window.
1. Select the appropriate action from the options presented in the command line window, 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. 2. After defining any connection security settings for the server, enter A to continue.
Defining database connection security
After defining the database connection properties, you can define the security for the U2 database connection. 1. Select S from the command line options to access the connection security from the command line. 2. Select the appropriate action from the options presented in the command line window, as described in the following table:
Command line option Description X Exit. 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.
360 Deploying from the command line
Deploying from the command line
After any required changes are made to the Resource folder properties, the 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 SOAP server was deployed to the deployment environment.
Deploying a SOAP server from a configuration file
A 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.
Generating a configuration file
Use the U2 SOAP deployment tool to generate a configuration file that can be used to deploy the U2 SOAP server from the development computer to the deployment environment. 1. Extract the zip file on to the target machine. The contents of the .zip file are extracted into the u2soapdeploy folder, which should contain the following files:
▪ rundeploytool.bat ▪ rundeploytool.sh ▪ runsoapserver.bat ▪ runsoapserver.sh ▪ runtime ▪ stopsoapserver.bat ▪ stopsoapserver.sh ▪ u2soap ▪ U2SOAP_deploy.conf
361 Chapter 7: U2 Web Service Developer
▪ u2soap_workspace ▪ u2soapservice.exe ▪ vcredist_x86.exe 2. 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. 3. Expand the Deployable SOAP Servers node in the SOAP servers pane. Right-click the SOAP server you want to deploy, then click Generate configuration file. 4. Click Browse to select a different configuration file or accept the default configuration file. Click Next. The SOAP Server Configuration dialog box opens. 5. You can specify the environment for the new SOAP server by changing any of the fields. For more information about environment specifications, see Setting connection properties, on page 354. Click Next. The SOAP Server Connection Security dialog box opens. 6. Select the Specify Connection Security check box to make changes to the security settings. Click Next to continue. For more information, see Defining security between the client and the SOAP server, on page 353. The U2 Database Connection Properties window opens. 7. Make any necessary changes to the properties and then click Next. For more information about the connection properties, see Setting connection properties, on page 354. The U2 Database Connection Security window opens. 8. Make any changes and then click Finish. 9. Run the rundeploytool command to deploy the configuration file created in the last step, as shown in the following example: rundeploytool.bat . C:\temp\myservice -s testserver -t prodserver – f config_file_name
Results The U2 SOAP service is now deployed in the deployment environment.
362 Starting and stopping SOAP servers
Starting and stopping SOAP servers
▪ To start 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
Enabling logging for remote SOAP servers
You can monitor a remote SOAP server.
Note: You cannot start the remote SOAP server from U2 Web Service Developer.
1. Define the remote server by right-clicking SOAP Servers, and selecting New SOAP Server. The Add a New SOAP Server dialog box opens. 2. In the Server Name field, enter a unique name for the SOAP server. 3. In the URL field, enter the URL for the remote server. 4. In the Port Number field, enter the port number for the remote server. If the remote SOAP server is running, a green icon us displayed beside the SOAP server name, as shown in the following example:
5. To enable logging, right-click the remote SOAP server, and select Turn on SOAP Server Debug. Log information for the remote server is displayed.
To stop the remote SOAP server, right-click the remote server you want to stop, then click Stop SOAP server.
363 Chapter 7: U2 Web Service Developer
Troubleshooting
Adjusting Java heap space in the Developer
This topic describes how to modify the heap size for a Java virtual machine when starting a SOAP server. This option is not enabled by default.
Description
Under most conditions the U2 SOAP products work as expected. However, when moving extremely large amounts of data, it is possible to crash the Java Runtime engine if the default memory limit is exceeded. If this occurs, you will see an out-of-memory error similar to the following: java.lang.OutOfMemoryError: Java heap space
Explanation
A larger heap size will affect garbage collection, as it will run more frequently. This may affect the performance of the application. Careful application design is important to ensure that this does not occur.
Resolution
If you get this error, you must adjust the heap memory to a larger value. The default values are 256 MB (initial size) and 512 MB (maximum size). 1. Open the Web Services Developer. 2. Navigate to Window > Preferences and then expand the UniData/UniVerse node. 3. Select U2 Web Services Developer. 4. Select the Set Java heap sizes option and then modify the sizes as necessary.
364 Adjusting Java heap size in a deployed environment
5. Click Apply to apply the settings, and then click OK.
Adjusting Java heap size 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.
1. Complete the following steps to modify the runsoapserver.bat file on Windows: a. Open the runsoapserver.bat file using an editor. b. Locate the following line: start javaw.exe -classpath... c. Modify the command to the following: start javaw.exe -Xms512m -Xmx1024m -classpath... d. Save the file and then restart the SOAP server. 2. Complete the following steps to modify the runsoapserver.bat file on UNIX:
365 Chapter 7: U2 Web Service Developer
a. Open the runsoapserver.sh file using an editor. b. Locate the following line: start javaw -classpath... c. Modify the command to the following: start javaw -Xms512m -Xmx1024m -classpath... d. Save the file and then restart the SOAP server.
Note: The JVM startup parameters offer a variety of options for operating the JVM. For details and a complete list of the available JVM startup parameters, refer to www.oracle.com.
Defining web server listening IP addresses
Web servers listen when started on IP address 0.0.0.0, which allows clients outside of that server on the network to connect. It is sometimes necessary to restrict outside access to the server by changing the listening address to 127.0.0.1. By doing so, only the local server can connect to any port the web server has enabled. This feature is only available on a deployed server and not from the U2 RESTful Web Service Developer.
To change the web server IP address to 127.0.0.1, add -Dloopbackonly=true to the startup script as shown in the following examples.
System Script name Script Windows runsoapserver.bat javaw.exe –Dloobackonly=true – classpath ... UNIX/Linux runsoapserver.sh $JRE_DIR/$JRE_EXE – Dloobackonly=true -Dfile ... 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
XMLREPSUB program 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"
366 Creating a WSD web service
END
SOAPXMLRETSUB program The SOAPXMLRETSUB program is the client-side BASIC subroutine that calls the SOAP web service using the SOAP API. It is used to test your SOAP web service.
*************************************************************** * SOAPXMLRETSUB * * For UniData use the following include. * $INCLUDE INCLUDE XML.H * * Universe use the following include. * $INCLUDE UNIVERSE.INCLUDE XML.H * * Example of Sending a ZIP SOAP 1.0 Request from BASIC * * SOAPXMLRETSUB - PROGRAM TO CALL a BASIC SUBROUTINE "XMLRETSUB" - * using SOAP API (UniData 7.3.7, Universe 11.2.3) * Sample program only, not intended for commercial use * This program shows testing SOAP API request to a U2 WSD WEB SERVICE * The XMLRETSUB subroutine called will return a "Hello Rocket" XML Page * * Turn on logging * myfil = "c:\temp\SOAPXMLRETSUB.log" RESULT=protocolLogging(myfil,"ON",10) CRT "Logging started = ":RESULT * PROMPT "" CRT DISPLAY "U2 SOAP EXAMPLE" * URL = "http://den-l-aw01:8185/XMLRETSUB" SoapAction="CALL_XMLRETSUB" * SoapAction="" Timeout = 60000 * Create the Request Ret = SoapCreateRequest(URL , SoapAction , SoapReq) IF Ret <> 0 THEN STOP "Error in SoapCreateRequest: " : Ret END * 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
367 Chapter 7: U2 Web Service Developer
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
ROCKET.XML file
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 344.
1. Create a new SOAP server. For details on this, see Defining SOAP servers, on page 327. 2. In the U2 Web Services pane, right-click the SOAP Servers node and then select Add new server. Enter the name of the new service name and then click Next. 3. Enter the appropriate database connection properties and then click Next. 4. Enter the correct connection security information. Make sure that the URL parameter in the SOAPXMLRETSUB subroutine matches that of the SOAP server and then click Next. For more information about the SoapCreateRequest function, see the U2 Basic Extensions. 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.
368 Creating a WSD web service
6. 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 Creating subroutine web services, on page 340 for more information. 7. Click Finish. 8. Start the web service. For details on starting the web service, see Starting the web service, on page 344. After running the example from the WSDL Main utility, you should see a response similar to the following:
Running the command from the command line gives an output similar to the following:
>LOGTO HS.SALES >RUN BP SOAPXMLRETSUB Logging started = 0
U2 SOAP EXAMPLE Response status : 200²OK Response headers: Jetty-Request²POST /XMLRETSUB HTTP/1.1■Date²Mon, 18 Aug 2014 1 4:20:09 GMT■Server²Jetty/4.2.x (Windows 7/6.1 x86 java/1.7.0_51)■Content-Type²te xt/xml; charset=utf-8■Content-Length²463 Response data :
369 Chapter 7: U2 Web Service Developer
Logging started = 0 >
370