Rocket U2 Web Development Environment

Administering U2 Web Development Environment

Version 5.1.1

January 2014 WDE-511-ALL-AM-01 Notices

Edition Publication date: January 2014 Book number: WDE-511-ALL-AM-01 Product version: Version 5.1.1

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.

Contact information Website: www.rocketsoftware.com Rocket Software, Global Headquarters 77 4th Avenue Waltham, MA 02451–1468 USA Tel: +1 781 577 4321 Fax: +1 617 630 7100

2 Contacting Global Technical Support

If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or find answers to in the U2 Knowledgebase. The Rocket Customer Portal is the primary method of obtaining support. To log in to the Rocket Customer Portal or obtain a Rocket Customer Portal account, go to www.rocketsoftware.com/support Alternatively, you can contact Global Technical Support by email or telephone: Email: [email protected] Telephone:

North America +1 800 729 3553 United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691 Europe/Africa +44 (0) 20 8867 3692 Australia +1 800 707 703 or +61 (0) 29412 5450 New Zealand +0800 505 515

3 Contents

Notices...... 2 Contacting Global Technical Support...... 3 Chapter 1: Rocket U2 Web Development Environment overview...... 6 Introduction...... 6 Web DE components...... 6 Chapter 2: Creating a Web DE-enabled U2 account...... 7 Creating a U2 server definition...... 7 Editing a U2 server definition...... 8 Connecting to a U2 server...... 8 Disconnecting from a U2 server...... 8 Creating a U2 account...... 9 Enabling an account for U2 Web DE...... 9 Editing the configuration files...... 10 Inserting an account reference in the JavaScheduler.ini file...... 10 Inserting an account reference in the rgw5.ini file...... 12 Chapter 3: Setting up application modules...... 14 Creating a module...... 14 Deleting a module...... 15 Chapter 4: Creating files...... 16 Creating U2 database files...... 16 Chapter 5: Managing garbage collection...... 20 Starting phantom control...... 20 Viewing the log...... 21 Stopping the phantom control...... 22 Running garbage collection without the phantom...... 22 WWSTATE file size guidelines...... 22 Chapter 6: Managing users...... 23 Creating a Web DE user...... 23 Viewing, editing, or deleting a user...... 24 Application security and Web DE...... 24 Chapter 7: Managing concurrency control...... 25 Concurrency control in Web DE...... 25 Locking and unlocking an RBO...... 25 Chapter 8: Managing revision control...... 26 Setting up revision control...... 26 Chapter 9: Troubleshooting...... 28 Troubleshooting client logging issues...... 28 Setting up the local log folder to produce a client log file...... 28 Troubleshooting Java Scheduler issues...... 29 Starting the Java Scheduler in the rbexamples account...... 29 Updating the number of webshares...... 30 Appendix A: Configuration files...... 31 JavaScheduler.ini file...... 31 Sections of the JavaScheduler.ini file...... 32 [LogLevel] section...... 32 [Default] section...... 33 [account] section...... 34

4 Contents rgw5.ini file...... 36 Sections of rgw5.ini file...... 37 [LogLevel] section...... 37 [Default] section...... 38 [accountname] section...... 38

5 Chapter 1: Rocket U2 Web Development Environment overview

Rocket U2 Web Development Environment (Web DE) is an application development toolkit for building interactive client/server applications for deployment on the World Wide Web or on a corporate intranet. Introduction

This manual explains how to create a Web DE-enabled U2 account, set up an application module, create and maintain users, and manage garbage collection. Other subjects include licensing, concurrency control, and revision control. Web DE components

Web DE consists of the RedBack Object Server, Java Scheduler, RedBeans and RedPages.NET, and Web Designer. The following table describes the role of each Web DE component.

Table 1: Web DE components

Component Description RedBack Object The RedBack Object Server manages access to RedBack applications and Server implements dynamic runtime interfaces to server-side application resources. The RedBack Object Server also maintains the repository that contains all the definitions and code that define an application. Java Scheduler The Java Scheduler manages data transfer between the RedBack Object Server and the web server, handling requests from RedBeans and RedPages.NET. It also performs the job of load balancing, processing the queue of connection requests by allocating U2 licenses as webshares. RedBeans and The RedBeans and RedPages.NET components are the Java and .NET RedPages.NET application programming interfaces (APIs) that enable you to connect your application to RedBack Objects (RBOs). These components are the interface between the web server and the RedBack Object Server. The role of these components is to establish and maintain connection pool connections or webshare connections between the web server and the RedBack Object Server. Web Designer This suite of designer tools runs in an Eclipse development environment and provides an interface for designing RBOs. For more information, see Developing RBOs with U2 Web Designer.

6 Chapter 2: Creating a Web DE-enabled U2 account

Creating and setting up a Web DE-enabled U2 account on a Windows- or UNIX-based U2 server computer involves the following tasks: ▪ Creating a U2 server definition, on page 7 ▪ Editing a U2 server definition, on page 8 ▪ Connecting to a U2 server, on page 8 ▪ Disconnecting from a U2 server, on page 8 ▪ Creating a U2 account, on page 9 ▪ Enabling an account for U2 Web DE, on page 9 ▪ Editing the configuration files, on page 10 Creating a U2 server definition

U2 databases are not recognizable by the Web Designer by default. On any U2 database server computer that is to host U2 accounts, you must create a U2 server definition in Web Designer. After you create the server, it appears in the U2 Resource view.

Prerequisite ▪ Install Web DE as described in Getting Started. ▪ Deploy the RedBack Object Server to a UNIX or Windows computer as described in Getting Started.

Procedure

1. Open Web Designer by clicking Start > All Programs > Rocket U2 > Web Development Environment > U2 Web Designer. 2. From the U2 Resource view, right-click Servers and select New U2 Server. 3. In the Create a New U2 Server window, enter the name and host of the server.

Note: The name must be unique and cannot contain a slash (/) or backslash (\) character. You cannot change the name of the server later, so be sure that the name you choose is the one you want. The Host field is the name or IP address of the computer on which the U2 database server is running.

4. Select UniData or UniVerse, depending on the database you use. 5. Optional: Click Advanced to define more details for the U2 server.

Tip: Accept the default settings unless you understand the effect of the changes you are making.

a. In the RPC Port# field, enter the port number of the UniRPC server running on the host. The default port number is 31438. b. In the RPC Service Name field, enter the name of the remote procedure call (RPC) service on your system. For UniData, this name is udcs; for UniVerse, this name is uvcs.

7 Chapter 2: Creating a Web DE-enabled U2 account

c. In the Login Account field, enter the full path to the account folder on the server to which you want to log on when accessing UniData or UniVerse. You can enter just the account name if the account is defined in the UD.ACCOUNT file or the UV.ACCOUNT file. d. In the Commands to Execute group box, if you want to execute a RetrieVe command, a saved paragraph, or a globally cataloged program, click Add. In the window that appears, enter the RetrieVe command, saved paragraph name, or globally cataloged program name, and click OK. The command appears in the group box. e. Next to Protocol, select Telnet or SSH. f. In the Port Number field, enter the port number used for Telnet or SSH communications. The default Telnet port number is 23; the default SSH port number is 22. g. Click Finish to return to the main Create a New U2 Server window. 6. Click Finish to create the U2 server. Editing a U2 server definition

If any of the information for the server is incorrect or needs to be changed, you can edit the server definition. 1. From the U2 Resource view, right-click the server and select Properties. The Edit U2 Server Definition window contains the same details as the Create a New U2 Server window, described in the preceding steps, allowing you to edit any fields you need. As previously stated, the Name field is not editable. However, you can right-click the server and select Delete, and create it again using a new name. 2. Change any of the fields and options, and click Finish. Connecting to a U2 server

The U2 Resource view displays a list of all U2 servers that have been defined in Web Designer. After you connect to a U2 server, the U2 Resource view displays the accounts and cataloged programs on the U2 server to which you are connected. You can connect to any U2 server on the list in this view.

Prerequisite ▪ Creating a U2 server definition, on page 7

Procedure

1. From the U2 Resource view, double-click the name of the U2 server to which you want to connect. 2. In the Connect to a U2 Server window, enter your user ID and password. 3. If you are using a proxy server, select the Use Proxy Server check box, and enter the proxy host and port. 4. Click Connect. Disconnecting from a U2 server

Disconnecting from a U2 server only closes the connection and frees up the license; it does not delete the U2 server definition or remove it from the list in the U2 Resource view. You can connect to the U2 server again by double-clicking the server name and entering your credentials. You do not have to disconnect from one U2 server before connecting to another. You can have connections open to two or more U2 servers at the same time. However, each open connection consumes a U2 database license.

8 Creating a U2 account

▪ From the U2 Resource view, right-click the server and select Disconnect. Creating a U2 account

After you connect to the U2 server that is to store a new account, the next task is to define a U2 account. The U2 account acts as a container for a group of modules that store RBO definitions for a related purpose or business activity. After an account is created, the U2 Resource view displays it in the Accounts folder.

Prerequisite ▪ Connecting to a U2 server, on page 8

Important: When you increase the number of accounts, the load on the RedBack Object Server and the web server might increase, potentially slowing down any connections.

Procedure

1. From the U2 Resource view, right-click Accounts and select New U2 Account. 2. In the Create New U2 Account window, enter the following information: a. In the Select U2 server area, the U2 server to which you are connected is selected by default. If you are currently connected to more than one U2 server, you can select a different U2 server on which to create the account. b. Enter the account name and path. The account name must be unique to the U2 server. The account path defaults to the home directory. Click Browse to select a different location. ▪ If you are adding an account for UniData, the name that you specify is also entered in the UD.ACCOUNT file on the server. ▪ If you are adding an account for UniVerse, the name that you specify is also entered in the UV.ACCOUNT file on the server. If the account is for UniVerse, an Account Flavor drop-down menu appears. Web DE-enabled U2 accounts must be Pick-compatible; however, the files that Web DE accesses may reside in any type of account, as long as there is a valid file pointer to the file. Select the flavor of UniVerse to use, and optionally select the Use Default Login check box. 3. Click Finish. Enabling an account for U2 Web DE

You must enable any new or existing U2 account for Web DE before you can develop RBOs for the account in the Web Designer. You can enable any U2 account that is on the U2 server computer to which you are connected. After the account is enabled, in the U2 Resource view, a U2 Web DE Elements node is added to the account.

Prerequisite ▪ Creating a U2 account, on page 9 ▪ If you upgraded to a new version of RedBack Object Server, be sure that the rbdefn account referenced in the account list is the correct (new) rbdefn account.

9 Chapter 2: Creating a Web DE-enabled U2 account

About this task The enablement process gathers information about the RedBack Object Server from the rbdefn account. If the rbdefn account is in the account list for the selected U2 server, it is used as the source of the RedBack Object Server pieces required to enable the account for Web DE. If no account is named “rbdefn” in the account list, you are prompted to specify the location of the rbdefn account on the server. The rbdefn account is then added to the account list.

Procedure

1. From the U2 Resource view, expand Accounts, right-click the account you want to enable, and select Enable for U2 Web DE. 2. If the rbdefn account is not already defined, you might be prompted to enter or browse to the path of the rbdefn account.

Figure 1: Establish link to rbdefn account

If the enablement process is successfully completed, the message “Enable account for U2 Web DE was successful for account: accountname” is displayed.

Tip: If you are not sure whether an account is enabled, check for the U2 Web DE Elements node in the account’s tree view. An account that is already enabled for Web DE can be enabled again. This is useful if you install a new version of the RedBack Object Server, especially if the location or path of the rbdefn account has changed.

Editing the configuration files

After creating a U2 account and enabling it for Web DE, you must insert a reference to the account in the configuration files.

The following sections describe how to edit the JavaScheduler.ini file and the rgw5.ini file. ▪ Inserting an account reference in the JavaScheduler.ini file, on page 10 ▪ Inserting an account reference in the rgw5.ini file, on page 12

Inserting an account reference in the JavaScheduler.ini file

After you create a new U2 account and enable it for Web DE, you must modify the JavaScheduler.ini file. The JavaScheduler.ini file sets configuration information for the Java Scheduler and is used as a reference to the location of each U2 account.

10 Inserting an account reference in the JavaScheduler.ini file

Prerequisite ▪ Enabling an account for U2 Web DE, on page 9

Note: The Java Scheduler configuration file, JavaScheduler.ini, is in the directory specified by the U2WDE environment variable. For additional information about the JavaScheduler.ini file, see JavaScheduler.ini file, on page 31.

Procedure

1. From the Tools menu, select Edit Java Scheduler Configuration. 2. In the Open window, browse to the C:\U2\U2WDE directory and double-click the JavaScheduler.ini file. 3. In the JavaScheduler.ini tabbed page, add an account to the JavaScheduler.ini file: a. Maximize the JavaScheduler.ini tabbed page. b. Right-click in any empty cell and select Insert Account. In the “Establish server details for this account connection” page of the account editor wizard, enter the server details for the account connection.

Table 2: Server parameters

Field Description Account name Enter the name to use for this account section in the JavaScheduler.ini file. This name is typically the same as the account name that has been assigned to the account. Server Enter the name or IP address of the RedBack Object Server computer for this account. Server Type Select the type of U2 data server running on the RedBack Object Server computer: UniData or UniVerse. c. To test the settings entered for connection parameters, click Test Connection Settings. If the connection fails, make changes to correct the error condition and test again. d. In the Scheduler to Database Connections area, enter or select the minimum and maximum number of pooled connections available to the account. e. To modify the account’s connection pool parameters, click Next and enter details in the “Establish account connection details” page in the wizard.

Table 3: Connection pool parameters

Field Description Idle Remove To set an idle remove threshold parameter for the account, select Threshold the Idle Remove Threshold check box. In the field, enter or select the number of milliseconds that a connection pool thread can remain idle before it is flagged for removal. Idle Remove Exec To set an idle remove execution interval for the account, select the Interval Idle Remove Exec Interval check box. In the field, enter or select the number of milliseconds of the interval at which connections that have been flagged for removal are removed. The sessions will be removed until the pool reaches the minimum connection pool amount.

11 Chapter 2: Creating a Web DE-enabled U2 account

Field Description Open session To set an open session parameter for the account, select the Open session check box. In the field, enter or select the number of milliseconds to acquire a session from the connection pool before timing out. f. To modify optional parameters for the account, click Next and complete the Set optional account and connection properties page in the wizard.

Table 4: Optional parameters

Parameter Description Deactivate account To deactivate the U2 account, select this check box. You can clear the check box to reactivate the account later, if needed. Deactivating a U2 account prevents it from consuming server or connection pooling licenses. It disables use of the account’s RBOs in web applications and in the RBOScope testing tool. However, users can access a deactivated account from the U2 Resource view and work with its RBOs in the RBO Editor. Enable SSL for To use the SSL protocol when making connections to the U2 server, this account’s select this check box. connection(s) to server Create the To keep a log of UOJ processes for the account, select this check uoj_trace.log box. file g. Click Finish. 4. In the JavaScheduler.ini tabbed page, review the changes in the new account section and make corrections if necessary. 5. To save the changes to the JavaScheduler.ini file, select File > Save.

Inserting an account reference in the rgw5.ini file

After you create a new U2 account and enable it for U2 Web DE, modify the rgw5.ini file. The RedBack gateway components, which run on the web server or the client, use the rgw5.ini file as a reference to the location of each U2 account or as a reference to the computer and port number of the Java Scheduler.

Prerequisite ▪ Enabling an account for U2 Web DE, on page 9

Note: The gateway configuration file, rgw5.ini, is in the directory specified by the U2WDE environment variable. For additional information about the rgw5.ini file, see rgw5.ini file, on page 36.

Procedure

1. From the Tools menu, select Edit Gateway Configuration. 2. In the Open window, browse to the C:\U2\U2WDEnnn directory, where nnn is the version number you installed, and double-click the rgw5.ini file.

12 Inserting an account reference in the rgw5.ini file

On UNIX computers, the rgw5.ini file must be created manually or created on your local client and then copied to a UNIX system. The preferred location for this file is in the /etc directory. 3. In the rgw5.ini tabbed page, add an account to the rgw5.ini file as described in step 3 of Inserting an account reference in the JavaScheduler.ini file, on page 10. 4. In the rgw5.ini tabbed page, review the changes in the new account section and make corrections, if necessary. 5. To save the changes to the rgw5.ini file, select File > Save.

13 Chapter 3: Setting up application modules

A RedBack module is a repository for all the RBO class definitions that relate to a convenient grouping, such as a particular business activity. A Web DE-enabled U2 account can have several modules, each of which is a container in which to group related RBOs. For example, a factory might want to create the following modules: ▪ Stock Control ▪ Accounts ▪ Human Resources All the RBOs for the stock control system would be stored inside the Stock Control module. Creating a module

After you connect to a U2 server, you can create a module in a Web DE-enabled account on that U2 server. When you create a module, the module is added to the account’s U2 Web DE Elements node in the U2 Resource view.

Prerequisite ▪ Connecting to a U2 server, on page 8 ▪ Enabling an account for U2 Web DE, on page 9

Procedure

1. From an expanded Web DE-enabled account, double-click the U2 Web DE Elements node. 2. In the RedBack Object Server Connection wizard, enter your user name and password, and click Finish. The default user name of the administrator is rbadmin, and the default password is redback. For increased security, change the default password as described in Viewing, editing, or deleting a user, on page 24. When the connection to the RedBack Object Server opens, the U2 Web DE Elements tree displays one or more modules.

14 Deleting a module

Figure 2: Modules

3. Right-click U2 Web DE Elements and select New Module. 4. In the New Module dialog box, enter a name and description for the new module, and click OK.

Note: Module names are case-sensitive and cannot contain spaces.

The module appears in the U2 Web DE Elements tree. You might have to right-click U2 Web DE Elements and select Refresh to see the new module. Deleting a module

You can delete a module from within the Web Designer.

Warning: Deleting a module deletes all RBO and logical file data that is defined within the module. You cannot undo the module deletion.

1. Expand the U2 Web DE Elements tree, right-click a module, select U2 Web DE Elements, and then select Delete. 2. In the Delete Module dialog box, click Yes. You might have to right-click U2 Web DE Elements and select Refresh to confirm that the module has been deleted.

15 Chapter 4: Creating files

In the Web Designer, you can create U2 database files to store your data. Creating U2 database files

Each account has a Database File node that you use to create new U2 database files.

Prerequisite ▪ Connecting to a U2 server, on page 8 ▪ Enabling an account for U2 Web DE, on page 9 ▪ Creating a module, on page 14

Procedure

1. From an expanded Web DE-enabled account, expand the Account node, and expand the tree for the account in which you want to create a U2 database file. 2. From the Database Files node, select New U2 File. 3. In the Create a New U2 File wizard, select the parent account for the new file and enter a name for it. The current account is selected by default; however, you can select a different account on the server to which you are currently connected, if necessary. To continue, click Next. 4. In the “U2 file options” page of the wizard, enter the information to create a new U2 file. The page is different for UniData and UniVerse, so choose the appropriate option: ▪ For UniData, use the following table to enter file information.

Table 5: UniData file options

Field or Option Description File Type Select the type of database file that you want to create: ▪ Hashed – UniData hashed file: a binary file that consists of a file header and one or more groups of data. ▪ DIR – UniData directory file: a directory that contains text or data files, and each text or data file is a UniData record. ▪ MULTIDIR – UniData multilevel directory (LD-type) file: a system- level directory that contains one or more subdirectories (UniData DIR type files). ▪ MULTIFILE – UniData multilevel (LF-type) file: a directory that contains one or more UniData hashed files that share a common dictionary. For more information about each file type, see “UniData File Types” in Using UniData. Modulo The number of data groups in the file. Applicable only to Hashed and MULTIFILE file types. Block Size The block size of data groups in the file. Applicable only to Hashed file types.

16 Creating U2 database files

Field or Option Description Hash Type Select one of the following options: ▪ 0 – Static hashing with fixed modulo ▪ 1 – Dynamic hashing with changing modulo If applicable, select the Dynamic File check box to create the hashed file as a UniData dynamic file. A dynamic file resizes itself by changing the number of groups required to store records. When records are added and deleted, dynamic files grow and shrink as the modulo (number of groups) changes. If applicable, select the RFS File check box to create the file as a UniData recoverable file, subject to the backup and recovery features of the UniData Recoverable File System. ▪ For UniVerse, select Static or Dynamic. A static file does not change in size to accommodate changes in the amount of data stored in it. A dynamic file resizes itself by changing the number of groups required to store records. For static files, use the following table to enter file information. For dynamic files, use Table 7: UniVerse dynamic file options, on page 18.

Table 6: UniVerse static file options

Field or Option Description Type Select the type of database file that you want to create: 1 A UNIX directory. Sub-UFD type file, for large records or source code. 2 Hashed file. Keys end with numbers. 3 Hashed file that uses numeric keys with separators. Keys end mainly with numbers. 4 Hashed file that uses 64-character ASCII keys. Keys end with letters. 5 Hashed file that uses 256-character ASCII keys. Keys end with full range of ASCII characters. 6 Hashed file. Keys begin with numbers. 7 Hashed file that uses numeric keys with separators. Keys begin mainly with numbers. 8 Hashed file that uses 64-character ASCII keys. Keys begin with letters. 9 Hashed file that uses 256-character ASCII keys. Keys begin with full range of ASCII characters. 10 Hashed file. Keys are all numeric. 11 Hashed file that uses numeric keys with separators. Keys are mainly numbers. 12 Hashed file that uses 64-character ASCII keys. Keys are letters. 13 Hashed file that uses 256-character ASCII keys. Keys are full range of ASCII characters. 14 Hashed file. Keys are all numeric. 15 Hashed file that uses numeric keys with separators. Entire keys are mainly numbers.

17 Chapter 4: Creating files

Field or Option Description 16 Hashed file that uses 64-character ASCII keys. Entire keys are letters. 17 Hashed file that uses 256-character ASCII keys. Entire keys are full range of ASCII characters. 18 Hashed file. Entire keys are of arbitrary form. 19 A UNIX directory. Sub-UFD type file, for large records or source code. 25 A B-tree file. Best for a large file with small static records. Modulo The number of data groups in the file. The number must be a positive whole number. Separation The block size of data groups in the file. Select an integer from 1 through 32 specifying the group buffer size in 512-byte blocks. If you want to create a 64-bit file on a UniVerse system that uses 32-bit file systems, select the 64-bit check box.

Table 7: UniVerse dynamic file options

Field or Option Description Minimum Modulo Specify the initial value of the modulo of the dynamic file as a positive whole number. The default value is 1. Group Size Select one of the following options: ▪ 1 – Group size of 2048 bytes, which is equivalent to a separation of 4. ▪ 2 – Group size of 4096 bytes, which is equivalent to a separation of 8. The default value is 1. Large Record Specify the maximum size of a record to include in the primary group buffer, expressed in bytes. This value must be a whole number. When the size of a record exceeds this value, its data is placed in an overflow buffer, but the record ID is placed in the primary group buffer. This method of large record storage increases access speed. The default value is 1628 bytes. Hashing Select one of the following options: Algorithm ▪ GENERAL – The default hashing algorithm, suitable in most cases. ▪ SEQ.NUM – A hashing algorithm for sequential numbers. Use only for records with IDs that are mainly numeric, sequential, and consecutive. Split Load % Specify the percentage of allocated file space at which the dynamic file’s modulo is to be increased by 1. This value must be a whole number. When the data in the file exceeds this percentage, the data in one of the groups is divided equally between itself and a new group, increasing the modulo by 1. The default percentage is 80.

18 Creating U2 database files

Field or Option Description Merge Load % Specify the percentage of allocated file space at which the dynamic file’s modulo is to be decreased by 1. This value must be a whole number. When the data in the file uses less than this percentage, the data in the last group in the file is merged with another group, decreasing the modulo by 1. The default percentage is 50. If you want to create a 64-bit file on a UniVerse system that uses 32-bit file systems, select the 64-bit check box. 5. Click Finish. The database file is added to the to the account under which it was created. The dictionary opens in the D_filename tabbed page, where filename is the name of the file that you just created. In the following figure, “test” is the new file.

Figure 3: New file

19 Chapter 5: Managing garbage collection

Because there is no permanent connection between your browser and the RedBack Object Server, Web DE stores data between web requests for a session and other information for RBOs in the WWSTATE file. The session information consists of details about the user and objects that have been instantiated. When sessions become inactive, garbage collection uses a background phantom process to automatically expire or purge them to allow for better performance with the WWSTATE file. Garbage collection can quickly clear out all state items from an expired session, rather than remove items one by one. Starting phantom control

Garbage collection runs in the background as a phantom process. You can modify how frequently you want sessions to expire and how often you want to purge these expired sessions. The Garbage Collect tab allows you to manage all garbage collection properties. The purpose of purging your sessions is to provide better performance for your application. The larger the WWSTATE file is, the slower Web DE runs. Setting up frequent expiring and purging times is recommended.

1. To open the Garbage Collect tab, from an expanded Web DE-enabled account, right-click U2 Web DE Elements and select Manage Garbage Collection. The Editor pane of the Web Designer opens with the Garbage Collect tab displayed.

Figure 4: Garbage Collect tab

2. By default, the garbage collection rules are set to expire sessions every 2 hours, and then remove any expired sessions every hour. If the default rules from the Preferences section are acceptable, continue to step 3. If not, change the preferences as described below. ▪ Rules for Expiring Inactive Sessions – These fields allow you to establish how long a web session can remain inactive before it expires. When you have sessions older than the time

20 Viewing the log

selected, the garbage collector expires them, but they remain in the WWSTATE file in case the session is reinstated. Adjust the days, hours, and minutes fields to when you want sessions to expire. ▪ Rules for Purging Expired Sessions – After sessions expire, this rule defines how often to purge sessions from the WWSTATE file. Adjust the days, hours, and minutes fields as you need. To save the changes to the garbage collection preferences, select File > Save. 3. Click Start Phantom. Viewing the log

When you run the phantom control for garbage collection, a log is kept of when and how many sessions have been purged. You can refresh, clear, or change the maximum amount of records to display in the log. The right section of the Garbage Collect tab contains a logging section as shown in the following figure.

Figure 5: Logging section

1. To change the limit of the amount of log data to retrieve from the server, set the number in the Maximum records to fetch spinner control to a higher or lower number. The default value is 500 log records, meaning the 500 newest log records are retrieved from the server. If you need to see data older than these 500 records, you can set the number higher. If there are more records on the server than the limit specifies, an informational message is displayed at the top of the tab, noting that the maximum record count can be increased to show more data. 2. Click Get Logs to retrieve the log data. When the phantom process has been started, the button label changes to Refresh, as shown in the preceding figure. 3. Expand the various nodes in the tree view to see more detail about each garbage collection run. Garbage collection logs are ordered by week. 4. Click Clear Log Data to clear the data from the WWLOG file on the connection’s rbdefn account.

21 Chapter 5: Managing garbage collection

Stopping the phantom control

If you no longer need the phantom control to run automatically, you can stop it. From the Garbage Collect tab, click Stop Phantom. Running garbage collection without the phantom

If you do not need to run garbage collection automatically, you can run the process manually. However, if the phantom process is currently running, you must stop it first before running garbage collection manually.

Note: It is not recommended to run garbage collection manually as the process may take awhile. Running garbage collection with the phantom process is the preferred method. See Starting phantom control, on page 20.

1. From the Garbage Collect tab, click Run GC Now. 2. In the Run Garbage Collection Now dialog box, click Yes to accept the warning message that the process may take extra time. WWSTATE file size guidelines

The size of the WWSTATE file is highly application-dependent. The larger the WWSTATE file, the longer the garbage collection process will take. In most cases, a database administrator must resize the WWSTATE file. However, you can determine if resizing needs to take place. For more specific steps, refer to Administering UniVerse on Windows Platforms or Administering UniVerse on UNIX Platforms.

Use the following factors as guidelines to determine the optimal size of the WWSTATE file: ▪ The number of hits your site receives each day ▪ The length of a session ▪ The specifications of the computer on which the RedBack Object Server is running and the load on the computer at various times of the day ▪ The amount of information the application itself is putting into the WWSTATE file, in addition to the default system information that Web DE requires

If you have a small site with fewer than 100,000 hits per day, a WWSTATE file with a modulo of 7517 and a block size of 1024 might be sufficient. You can schedule garbage collection to run four to eight times per day. If you have a larger site with up to one million hits per day, you can size this file with a modulo of 65521 and a block size of 2048. You can schedule garbage collection to run every 15 minutes to clear items older than 30 minutes. Be cautious when setting cleanup intervals of items as low as 30 minutes, because some valid state objects could be deleted for those users who browse longer than 30 minutes.

It is very important that a database administrator regularly monitor the WWSTATE file to ensure that the size of the file is optimized for performance.

22 Chapter 6: Managing users

The Users tab allows you to manage and create user records, adding users to groups and optionally enabling users to integrate SB/XA with Web DE. You can list users, edit user records, and delete users as needed. Creating a Web DE user

When you create a user, you are giving the user access to the RedBack Object Server from the Web Designer. You can also optionally assign a user to a specific group and grant SB/XA access. 1. To open the Users tab, from an expanded Web DE-enabled account, right-click U2 Web DE Elements and select Manage RedBack Users. The Editor pane of the Web Designer opens with the Users tab displayed.

Figure 6: Users tab

2. Enter the information for the new user. 3. From the User Group drop-down list, select one of the following options: ▪ ROOT: The administrative group, in which all members have full privileges. Members can modify details of other users, as well as create and delete users. ▪ USERS: The default group to which most users belong. Members can modify only their own details. 4. Optional: In the SB+ Access area, select the Enable SB+ Access check box, and enter the path to the SB/XA account in the dialog box that appears. The SB+ User ID field becomes available for you to enter the user ID when the correct SB/XA account path is entered.

Note: If a Web DE user wants to integrate SB/XA with Web DE, the SB+ Access check box must be selected for the user to access the SB/XA server. For more information, see Using SB/XA with U2 Web Designer.

5. To save the new user, select File > Save.

23 Chapter 6: Managing users

Viewing, editing, or deleting a user

A list view is provided for you to view, edit, or delete Web DE users. 1. From the Users tab, click List Users. 2. From the user list, select a user to view, edit, or delete, and click OK. 3. Do one of the following actions: ▪ To edit the user, change any fields necessary and select File > Save. ▪ To delete the user, click Delete User. Deletions cannot be undone. Application security and Web DE

Web DE provides security to control who has access to an account's RBO definitions from Web Designer and the RBOScope testing tool. Web DE does not provide security options for the application itself. The application may require a number of different security aspects such as secure pages (SSL), web server access control, and application access. The following table describes each of these aspects.

Table 8: Security aspects

Type of security Description SSL SSL is controlled from the client navigation. By calling a page through the HTTPS protocol and configuring a secure web server, Web DE sends encrypted data between the browser and Web server. This is an area of security handled by the browser and the web server, and therefore is beyond the scope of this manual. Web server access Web servers allow security to control access. This is a technique often used to control control access to the Web server, and therefore the pages on that web server. For details about setting up access control, see your web server documentation. Application Through your application code, you can prompt for a username and password, access and then determine if that user should have access to the requested RBO. The user details and access rights are part of your application data, and you must determine what level of control to impose. Web DE security does not apply to applications and cannot be used to control application access.

24 Chapter 7: Managing concurrency control

The following sections describe concurrency control in Web DE. Concurrency control in Web DE

Web DE employs “locks” for concurrency control to prevent developers from accessing and amending the same object definition item. Web DE maintains concurrency control information in a file global to all Web DE applications, called WWLOCKS. When you lock an object, an entry is added to the WWLOCKS file and is not removed until the object is saved. An entry is also added to the WWSTATE file when you create a new object so that you can continue to edit it. The entry is added as soon as the object name is entered.

Note: Concurrency control is available only during application development. It is not used in the application run time, where optimistic locking is used instead.

Locking and unlocking an RBO

You must lock an RBO to edit its attributes, properties, or methods. Only one user can lock an RBO at a time. This prevents multiple developers from overwriting each other's changes. Locking is based on the full path of the object, meaning that application IDs and account names can be duplicated on a server, but the object can still be unique. When you lock an object, the definition is downloaded and an entry is created in the WWLOCKS file to indicate that you have opened the object. The RedBack Object Server timestamps the entry in the WWLOCKS file. The entry in the WWLOCKS file remains until you close the object or unlock it. When you close the Web Designer, all open objects are closed, and their entries are removed from the WWLOCKS file. 1. From the RBO List, U2 Resource, or RBO Hierarchy view, right-click the name of an RBO and select Lock RBO. If using the U2 Resource view, you can also press Ctrl to select multiple RBOs to lock.

Alternatively, a Lock icon ( ) is available on the toolbar.

Note: You cannot lock an RBO that is already locked. You can only access a read-only version of the object definition.

2. Make any changes to the RBO by double-clicking it and editing the details. For more information, see Developing RBOs with U2 Web Designer. 3. To save the changes, select File > Save. 4. To unlock the RBO, right-click it and select Unlock RBO.

Alternatively, an Unlock icon ( ) is available on the toolbar.

25 Chapter 8: Managing revision control

Revision control allows a user-defined subroutine to be run automatically on the RedBack Object Server when an RBO definition is read or modified through the Web Designer or the RedBack API. You can control access to RBOs during attempted reads, writes, deletions, and handler compilations. Revision control does not modify or update RBO definitions—this option is up to you, the administrator. Setting up revision control

To activate revision control, you must specify the name of the user-defined ‘hook’ subroutine in the first attribute of the RB.REVISION.HOOK item. Place this item in the xxTEXT file, where xx is the name of the module that is subject to revision control. Otherwise, if revision control is to be enforced on all modules in all accounts, place the RB.REVISION.HOOK item in the global WWCONTROL file. Web DE calls the user-defined subroutine before the following actions take place: ▪ Read an RBO or BASIC handler of an RBO ▪ Write an RBO or BASIC handler of an RBO ▪ Compile a BASIC handler of an RBO ▪ Delete an RBO The user-defined subroutine can then terminate the action based on the user who is attempting to perform the action. The format of the user-defined subroutine statement is as follows:

SUBROUTINE xxx(USERID, FILENAME, ITEMNAME, ITEM, RWDC, ABORT) .... The following table describes each parameter.

Table 9: Subroutine parameters

Parameter Description USERID Identifies the Web DE user (always in uppercase letters). This is a read-only parameter that you can use to specify the procedure for the user-defined subroutine to take based on who is attempting the action. FILENAME Identifies the file that contains the item being accessed (an RBO or a BASIC handler, for example). This is a read-only parameter that you can use to determine the action for the user-defined subroutine to take based on which files are allowed to be accessed. The format is [dict]filename. ITEMNAME Identifies the name of the item (for example, RBO name or BASIC handler name) being accessed. This is a read-only parameter that you can use to specify the procedure for the user-defined subroutine to take based on which items are allowed to be accessed.

26 Setting up revision control

Parameter Description ITEM The actual item variable (for example, object definition for RBO or handler source for BASIC handler). This is a read-only parameter that you can use to determine the action for the user-defined subroutine to take based on values in the variable. RWDC Identifies the operation that was performed to initiate revision control. This is a read-only parameter that you can use to specify the action for the user-defined subroutine to take based on the initiating operation. Setting ABORT to 1 rejects the action identified by the RWDC variable and displays a revision control message to the user. The RWDC variable can have one of the following values: ▪ R: indicates a read operation was attempted on an RBO or handler ▪ W: indicates a write operation was attempted on an RBO or handler ▪ D: indicates a delete operation was attempted on an RBO or handler ▪ C: indicates a compile operation was attempted on an RBO handler Access to a RedBack object through the ASP or Java RBOScope testing tool initiates the Read RWDC action. ABORT A write-only parameter that determines whether or not the action identified in the RWDC variable is rejected. Setting ABORT to 1 indicates the operation will be rejected.

The user-defined subroutine must be correctly compiled and cataloged. The following example is of a subroutine:

SUBROUTINE OFFICE.REV.HOOK(USERID, FILENAME, ITEMNAME, ITEM, RWDC, ABORT) * INCLUDE WWINSERT STD.H * IF USERID = ‘FRED’ AND (RWDC = ‘W’ OR RWDC = ‘D’) THEN ABORT = 1 END * RETURN * END

27 Chapter 9: Troubleshooting

The following sections contain information to help you troubleshoot Web DE. Troubleshooting client logging issues

Client log files capture events that occur when RedBeans or RedPages.NET processes RBO method calls for a Web DE-enabled U2 account. The names of the client log files are:

▪ RedBeans_accountname.log ▪ RedPages_accountname_processid.log, where processid is the ID of the Windows process with RedPagesNet.dll loaded.

Parameters in the rgw5.ini file define the characteristics of client logging for Web DE-enabled U2 accounts. If you experience a problem with client logging, complete the troubleshooting steps in the following procedure.

Setting up the local log folder to produce a client log file

If a RedBeans_accountname.log or RedPages_accountname_processid.log file was not created for an account, the likely cause is an empty setting in the rgw5.ini configuration file. You can specify the location in which to store client logs for each U2 account in the rgw5.ini file. 1. From the Web Designer, select Tools > Edit Gateway Configuration. 2. In the Open window, browse to the C:\U2\U2WDEnnn directory, where nnn is the version number you installed, and double-click the rgw5.ini file. On UNIX computers, the rgw5.ini file must be created manually or created on your local client and then copied to a UNIX system. The preferred location for this file is in the /etc directory. 3. In the RBO Editor pane of the Web Designer, double-click the name of the account for which the client log is missing. 4. In the wizard, perform the following substeps: a. In the “Establish server details for this account connection” page of the account editor wizard, enter server details for the account connection.

Table 10: Server parameters

28 Troubleshooting Java Scheduler issues

Table 11: Connection parameters

Field Description Account path Enter the path to the account directory on the RedBack Object Server computer. User Enter the operating system-level user ID for the RedBack Object Server computer. Password | Verify Enter the password associated with the user ID, and reenter the Password password to verify it. c. To test the settings entered for connection parameters, click Test Connection Settings. If the connection fails, make changes to correct the error condition and test again. 5. To apply the changes, click Finish. Troubleshooting Java Scheduler issues

The Java Scheduler manages data transfer between the RedBack Object Server and the web server. It handles HTTP requests and UO.NET or UOJ connections. If you experience a problem related to the Java Scheduler, complete the troubleshooting steps in the following procedures.

Starting the Java Scheduler in the rbexamples account

If you run a test on an rbexamples account that has not been upgraded to Web DE 5.1.0 or later, errors are written to client, Java Scheduler, and server logs. The Java Scheduler was introduced in 5.1.0, and the rbexamples account must be upgraded to 5.1.0 or later to enable the Java Scheduler. Failure to upgrade the account causes the Java Scheduler to fail at startup.

1. Check for errors in the client log, named RedBeans_accountname.log or RedPages_accountname_processid.log, where processid is the ID of the Windows process with RedPagesNet.dll loaded. If you run a test against a Java Scheduler port when the Java Scheduler is not running, an error similar to the following error is written to the client log:

Exception caught: RedObject.jrgwOpen(): No RPC Connection active. The log entry for the client failure from RedBeans_rbexamples.log. 2013-02-05 08:15:02 Thread[main,5,main] In jrgwOpen UniSessionException [Rocket U2][UniObjects for Java][UniSession Exception][ErrorCode: 81002]No RPC Connection active. 2. Check for errors in the scheduler log, located in the specified scheduler log path. The following error indicates that the Java Scheduler failed at startup:

INFO: Thread[main,5,main]Database check started Feb 5, 2013 7:52:44 AM com.rs.u2.u2cm.U2CMLogger log SEVERE: Thread[Thread-3,5,main]com.rs.u2.u2cm.U2CMDbcheck run 112 [Rocket U2] [UniObjects for Java][UniSubroutine Exception][ErrorCode: 30105]Unable to load the subroutine on the server 3. Check for errors in the serverdebug log.

29 Chapter 9: Troubleshooting

The following error, created by the uniapi_slave process, indicates that the subroutine failed because of a missing catalog pointer:

07:52:44; errno=0: udapi_server non execute command. Tue Feb 05 07:52:44; errno=0: api_slave: function code=52. Tue Feb 05 07:52:44; errno=0: ICSubCall args=7,name=WW.READREC, Tue Feb 05 07:52:44; errno=0: arg[0]=, Tue Feb 05 07:52:44; errno=0: arg[1]=, Tue Feb 05 07:52:44; errno=0: arg[2]=, Tue Feb 05 07:52:44; errno=0: arg[3]=, Tue Feb 05 07:52:44; errno=0: arg[4]=, Tue Feb 05 07:52:44; errno=0: arg[5]=, Tue Feb 05 07:52:44; errno=0: arg[6]=3, subcall [WW.READREC]:'WW.READREC' is not cataloged. Tue Feb 05 07:52:44; errno=0: ICSubCall returned from basic, ReturnCode=-1. Tue Feb 05 07:52:44; errno=0: udapi_server rpc_read_message returncode=81002. Tue Feb 05 07:52:44; errno=0: api_slave: api_pipe_read 1 byte_count = -1 away. Tue Feb 05 07:52:44; errno=0: udapi_server exit connect_number=1. 4. Close Web Designer. 5. Upgrade the rbexamples account to Web DE 5.1.0 or later. 6. Start Web Designer and run the test again in the RBOScope testing tool.

Updating the number of webshares

If the number of webshares is invalid, the following error can occur in the Javascheduler.log file when trying to use the Java Scheduler:

INFO: Thread[main,5,main]Scheduler licensed for 0 webshares. Oct 1, 2013 10:55:24 AM com.rs.u2.u2cm.h a INFO: Thread[main,5,main]Scheduler shutting down due to invalid number of webshares.

To correct this error, configure your server for the number of webshares you have. For more details, see the information about licensing and authorizing Web DE in Getting Started. If connection pooling has been ordered instead of webshares, you must add on webshares to your license rather than connection pooling.

30 Appendix A: Configuration files

The following sections describe the content of the Web DE configuration files. JavaScheduler.ini file

The Java Scheduler configuration file, JavaScheduler.ini, is in the directory that is specified by the U2WDE environment variable. The RedBack Object Server uses the JavaScheduler.ini file for global and account-level connection parameters used to process requests.

Format

The JavaScheduler.ini file format is:

[SectionName] parameter_1=value_x parameter_2=value_y ...

Each section contains a set of related parameters. Web DE searches the JavaScheduler.ini file for predefined and user-defined section names, and updates internal parameters based on the values set in the file. Most of the section names are predefined, so you cannot change them. However, you can define the names of additional sections.

Example JavaScheduler.ini file

The following example of the JavaScheduler.ini file contains the default sections and settings that show the type of data required for each parameter:

[LogLevel] panic=1 err=1 inf=0 init=1 trace=0 wrn=0

[Default] SchedulerPort=7070 MonitorPort=7071 logpath=C:\U2\U2WDE511\Javascheduler.log RbdefnPath=C:\U2\U2WDE511\UDserver\rbdefn server=localhost userId=cbrown password=2spwV0hJequEefsSBqK1KQ== ConnectionString=udcs usingssl=0 sslKeyStore=PathToSSLKeystore sslKeyStorePassword=6B6jy5KN5o6l1rY5j26riQ==

[rbexamples] workdir=C:\U2\U2WDE511\UDserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ==

31 Appendix A: Configuration files

server=localhost usingssl=0

Sections of the JavaScheduler.ini file

The JavaScheduler.ini file includes three default sections: ▪ [LogLevel] section ▪ [Default] section ▪ [account] section

[LogLevel] section

This section of the JavaScheduler.ini file contains parameters for the types of information to write to the JavaScheduler.log file for Web DE-enabled U2 accounts. The log level parameters are global; they apply to all Web DE-enabled U2 accounts on the RedBack Object Server computer. The following example shows the [LogLevel] section:

[LogLevel] panic=1 err=1 inf=0 init=1 trace=0 wrn=0

The following table lists the log level parameters. Each parameter specifies whether to write details for a type of information to the JavaScheduler.log file. To log a type of information, set the parameter to 1, for example panic=1. To turn off logging for a type of information, set the parameter to 0, for example panic=0. By default, all parameters are turned off, except panic, err, and init.

Table 12: [LogLevel] section parameters

Parameter Description panic Specifies whether to log fatal errors. ▪ 0 – Do not log fatal errors. ▪ 1 – Log fatal errors. This is the default setting. err Specifies whether to log details of serious errors. ▪ 0 – Do not log serious errors. ▪ 1 – Log serious errors. This is the default setting. inf Specifies whether to log informational messages. ▪ 0 – Do not log informational messages. This is the default setting. ▪ 1 – Log informational messages. init Specifies whether initialization/termination messages are to be logged. ▪ 0 – Do not log initialization or termination messages. ▪ 1 – Log initialization/termination messages. This is the default setting.

32 [Default] section

Parameter Description trace Specifies whether to log program flow tracing messages.

This parameter is not included in the JavaScheduler.ini file by default. ▪ 0 – Do not log program flow tracing messages. This is the default setting. ▪ 1 – Log program flow tracing messages, including incoming request names, request values, property names, and property values from the client. Also log outgoing property names and values being returned to the client. wrn Specifies whether to log warning messages. ▪ 0 – Do not log warning messages. This is the default setting. ▪ 1 – Log warning messages.

[Default] section

The parameters in this section define Web DE system defaults. They apply to all Web DE-enabled U2 accounts within the system. You can override the defaults within each [account] section. The following example shows the [Default] section:

The following table lists the default global parameters at the Web DE system level. You can add other default parameters in this section, if applicable.

Table 13: [Default] section parameters

Parameter Description SchedulerPort The port number on which the Java Scheduler accepts RBO requests. Make note of this setting when editing the rgw5.ini file. MonitorPort The port number on which the Java Scheduler accepts monitor and maintenance requests. logpath The path to the JavaScheduler.log file. RbdefnPath The path to the deployed rbdefn account. server The name or IP address of the computer on which the RedBack Object Server is installed. userId The operating system-level user ID for the RedBack Object Server computer. password The password associated with the user ID. ConnectionString Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) or connection.

33 Appendix A: Configuration files

Parameter Description usingssl Specifies whether to use Secure Sockets Layer (SSL) protocol when making connections to the U2 server. 0 – Do not use SSL. 1 – Use SSL. sslKeyStore The path to the SSL keystore for the Java Scheduler. sslKeyStorePassword The password for the SSL keystore.

[account] section

The JavaScheduler.ini file contains a section for each account. The name of the section is the connection name of the account, used as a reference by RedBeans or RedPages.NET. In each [account] section, you must define at least the mandatory parameters for the account. You can specify additional parameters. If you specify a parameter in the [account] section that is also in the [Default] section, the value that you set for the account overrides the system default value. The following example shows the [account] section:

[rbexamples] workdir=C:\U2\U2WDE511\UDserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ== server=localhost usingssl=0

The following table describes the parameters in the [account] section:

Table 14: [account] section parameters

Parameter Description workdir The physical path to the U2 account on the computer on which the RedBack Object Server is installed. MinimumPoolSize The minimum number of connections maintained in the connection pool. MaximumPoolSize The maximum number of connections maintained in the connection pool. ConnectionString Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) connection. userId The operating system-level user ID for the RedBack Object Server computer. password The password associated with the user ID specified in the userId parameter.

The password is encrypted when you save the JavaScheduler.ini file in Web Designer.

If you edit and save the JavaScheduler.ini file in a text editor, the password is saved in plain text. To maintain server security, open and save the JavaScheduler.ini file in Web Designer to encrypt the password. server The name or IP address of the computer on which the RedBack Object Server is installed.

34 [account] section

Parameter Description usingssl Specifies whether to use the SSL protocol when connecting to the U2 server. ▪ 0 – Do not use SSL. ▪ 1 – Use SSL.

[account.Environment] subsection This subsection of the [account] section is optional. To define separate environment variable values in an account, insert an account environment with property and value pairs, for example:

[rbexamples] workdir=C:\U2\U2WDE511\UDserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ== server=localhost usingssl=0 [rbexamples.Environment] account_desc=rbexamples2 LANG=en_US TZ=MST7MDT

An [account.Environment] subsection can be used to create an alias that points to the same account but uses a different environment variable for connection pools, for example:

[rbexamples] workdir=C:\U2\U2WDE511\UDserver\rbexamples MinimumPoolSize=1 MaximumPoolSize=10 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ== server=localhost usingssl=0 [rbexamples.Environment] account_desc=rbexamples GMT TZ=GMT

[rbexamples_alias] workdir=C:\U2\U2WDE511\UDserver\rbexamples MinimumPoolSize=1 MaximumPoolSize=1 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ== server=localhost usingssl=0 [rbexamples_alias.Environment] account_desc=rbexamples TZ=MST7MDT

35 Appendix A: Configuration files rgw5.ini file

The gateway configuration file, rgw5.ini, is in the directory specified by the U2WDE environment variable. The RedBack gateway components, which run on the web server or the client, use the rgw5.ini file for global parameters and as a reference to the location at which each U2 account resides.

Format

The rgw5.ini file format is:

[SectionName] parameter_1=value_x parameter_2=value_y ...

Each section contains a set of related parameters. Web DE searches the rgw5.ini file for predefined and user-defined section names, and updates internal parameters based on the values set in the file. Most of the section names are predefined, so you cannot change them. However, you can define the names of additional sections.

Example rgw5.ini file

The following example rgw5.ini file contains the default sections and settings that show the type of data required for each parameter:

[LogLevel] panic=1 err=1 inf=0 init=1 times=1 wrn=1 trace=1

[Default] perfstats=0

[rbexamples] workdir=C:\U2\U2WDE511\UDserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ== server=localhost logpath=C:\U2\U2WDE511 ;SchedulerPort=7070 como=1 usingssl=1 PoolingDebug=1 IdleRemoveThreshold=15000 IdleRemoveExecInterval=1000 OpenSessionTimeout=1000

36 Sections of rgw5.ini file

Sections of rgw5.ini file

The rgw5.ini file contains three default sections: ▪ [LogLevel] section ▪ [Default] section ▪ [accountname] section

[LogLevel] section

This section of the rgw5.ini file contains parameters for the types of information to write to the client log files for Web DE-enabled U2 accounts. The log level parameters are global; they apply to all Web DE-enabled U2 accounts on the RedBack Object Server computer. The client log files are:

▪ RedBeans_accountname.log ▪ RedPages_accountname_processid.log, where processid is the ID of the Windows process with RedPagesNet.dll loaded. The following example shows the [LogLevel] section:

[LogLevel] panic=1 err=1 inf=0 init=1 times=1 wrn=1 trace=1

The following table lists the log level parameters. Each parameter specifies whether to write details for a type of information to the client log files.

To log a type of information, set the parameter to 1, for example panic=1. To turn off logging for a type of information, set the parameter to 0, for example panic=0. By default, all parameters are turned off, except panic, err, and init.

Table 15: [LogLevel] section parameters

37 Appendix A: Configuration files

Parameter Description times Specifies whether to log the times (in milliseconds) for executing RBO method calls. ▪ 0 – Do not log times of method calls. This is the default setting. ▪ 1 – Log times of method calls. wrn Specifies whether to log warning messages. ▪ 0 – Do not log warning messages. This is the default setting. ▪ 1 – Log warning messages. trace Specifies whether to log program flow tracing messages. ▪ 0 – Do not log program flow tracing messages. This is the default setting. ▪ 1 – Log program flow tracing messages, including incoming request names, request values, property names, and property values from the client. Also log outgoing property names and values being returned to the client.

[Default] section

The parameters in this section define Web DE system defaults. They apply to all Web DE-enabled U2 accounts within the system. You can override the defaults within each [accountname] section. The following example shows the [Default] section:

[Default] perfstats=0

The following table lists the default global parameters at the Web DE system level. You can add other default parameters in this section, if applicable.

Table 16: [Default] section parameters

Parameter Description perfstats Specifies whether to log performance statistics. ▪ 0 – Do not log performance statistics. ▪ 1 – Log performance statistics.

The Perfstats.log file includes the same statistics available from the Web DE performance monitor API, such as wait time and number of requests processed for each account.

The Perfstats.log file is written to the C:\U2\U2WDEnnn directory by default, where nnn is the version number you installed.

[accountname] section

The rgw5.ini file contains a section for each account. The name of the section is the connection name of the account, used as a reference by RedBeans or RedPages.NET. In each account section, you must define at least the mandatory parameters for the account. You can specify additional parameters. If you specify a parameter in the [accountname] section that is also in the [Default] section, the value you set for the account overrides the system default value. The following example shows the [accountname] section:

[rbexamples] workdir=C:\U2\U2WDE511\UDserver\rbexamples

38 [accountname] section

MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userId=cbrown password=2spwV0hJequEefsSBqK1KQ== server=localhost logpath=C:\U2\U2WDE511 ;SchedulerPort=7070 como=1 usingssl=1 PoolingDebug=1 IdleRemoveThreshold=15000 IdleRemoveExecInterval=1000 OpenSessionTimeout=1000

The following table describes the parameters in the [accountname] section:

Table 17: [accountname] section parameters

Parameter Description workdir The physical path to the U2 account on the computer on which the RedBack Object Server is installed. MinimumPoolSize The minimum number of connections maintained in the connection pool. Setting this value and the MaximumPoolSize value to 0 enables the developer mode, which allows you to execute newly compiled code through Web DE processes. Instead of using a cached version of the object code, the developer mode allows you to pick up the new object code as soon as it is available by causing the associated database processes to restart after each method call. While allowing newly compiled code to be picked up, this mode carries a performance overhead as the associated database processes terminate and are recreated after each method call and is not recommended for “live” production use for this reason. The SchedulerPort must also be commented out to bypass the connection to the Java Scheduler. MaximumPoolSize The maximum number of connections maintained in the connection pool. Setting this value and the MinimumPoolSize value to 0 enables the developer mode. See the description in MinimumPoolSize for information about the developer mode. ConnectionString Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) connection. userId The operating system-level user ID for the RedBack Object Server computer. password The password associated with the user ID specified in the userId parameter.

The password is encrypted when you save the JavaScheduler.ini file in Web Designer.

If you edit and save the rgw5.ini file in a text editor, the password is saved in plain text. To maintain server security, open and save the rgw5.ini file in Web Designer to encrypt the password. server The name or IP address of the computer on which the RedBack Object Server is installed.

39 Appendix A: Configuration files

Parameter Description logpath The full path of the directory in which to store client log files for the account on the client computer. The client log files are RedBeans_accountname.log and RedPages_accountname_processid.log, where processid is the ID of the Windows process with RedPagesNet.dll loaded. The directory must already exist; Web DE does not create a new directory for you. If the specified logpath directory does not exist, the application fails at run time. SchedulerPort The port number on which the Java Scheduler accepts requests from this account. If this parameter is commented out, and the MinimumPoolSize and MaximumPoolSize parameters are set to 0, the Java Scheduler connection is bypassed. como Specifies whether to save the server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. ▪ 0 – Do not save the logs. ▪ 1 – Save the logs. usingssl Specifies whether to use the SSL protocol when connecting to the U2 server. ▪ 0 – Do not use SSL. ▪ 1 – Use SSL. PoolingDebug Specifies whether to keep a log of UOJ processes for the account for debugging purposes. ▪ 0 – Do not keep a log of UOJ processes. ▪ 1 – Keep a log of UOJ processes. encoding Allows support of any session encoding for connections using RedPages.NET or RedBeans. IdleRemoveThreshold The number of milliseconds that a connection pool thread can remain idle before it is flagged for removal. IdleRemoveExecInterval The number of milliseconds of the interval at which UOJ runs an executable to remove from a connection pool any threads that have exceeded the idle threshold. OpenSessionTimeout The number of milliseconds for which UOJ attempts to acquire a session from the connection pool before timing out.