Rocket U2 Web Development Environment

Transcription

1 Rocket U2 Web Development Environment Administrator s Guide Version July 2017 WDE-530-ALL-AM-01

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

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

4 Contents Notices... 2 Corporate information... 3 Chapter 1: Rocket U2 Web Development Environment overview... 7 Introduction...7 Web DE components... 7 Chapter 2: Creating a Web DE-enabled U2 account... 8 Creating a U2 server definition...8 Editing a U2 server definition... 9 Connecting to a U2 server... 9 Disconnecting from a U2 server... 9 Creating a U2 account...10 Enabling an account for U2 Web DE Editing the configuration files Inserting an account reference in the JavaScheduler.ini file Inserting an account reference in the rgw5.ini file Editing the rgw5.ini file on a remote web server Encrypting a password...15 Chapter 3: Setting up application modules...16 Creating a module Deleting a module Chapter 4: Creating files...18 Creating U2 database files...18 Chapter 5: Managing garbage collection Starting phantom control Viewing the log Stopping the phantom control...25 Running garbage collection without the phantom...25 State management WWSTATE file size guidelines WWSESSION file size guidelines Chapter 6: Managing users Creating a Web DE user...27 Viewing, editing, or deleting a user...28 Application security and Web DE Chapter 7: Restricting administrative views and functionality Creating, compiling, and cataloging the subroutine Viewing the activity log Chapter 8: Managing concurrency control Concurrency control in Web DE...34 Locking and unlocking an RBO Chapter 9: Managing revision control Setting up revision control Chapter 10: Configuring and running the Java Scheduler Managing the Java Scheduler on Windows...37 Configuring the Java Scheduler (Windows)...37 Modifying default global settings (Windows) Modifying account settings (Windows)

5 Contents Inserting an account in the Java Scheduler configuration file (Windows)...42 Running the Java Scheduler on Windows Viewing the Java Scheduler log Monitoring performance on Windows...44 Defining the yellow and red triggers of the monitor from the cm.ini file...46 Viewing RBO process details and the BASIC call stack Viewing exceptions Changing the monitor settings Filtering accounts in the monitor table Monitoring client threads...50 Configuring the monitor table columns...51 Configuring the parameters to work with your system Registering or unregistering the Java Scheduler as a Windows service Managing the Java Scheduler on UNIX...53 Configuring the Java Scheduler (UNIX)...53 Modifying environment variables (UNIX) Modifying account settings (UNIX) Adding an account to the Java Scheduler configuration file (UNIX) Modifying environment variables on UNIX Running the Java Scheduler on UNIX Monitoring performance on UNIX...58 Chapter 11: Using the Admin API Server Configuring, starting, and stopping the Admin API Server...61 The Connection Manager Admin API Server...62 Connection Manager Admin API paths Start the Connection Manager Stop the Connection Manager...62 Get accounts Get account information...63 Update account Restart account...64 Get config file...65 Save config file...65 Get log entries...66 Get log errors Get status of performance statistics logger...67 Start performance statistics logger...67 Stop performance statistics logger Get API process information...68 Set logging level Get call stack...69 Get Connection Manager status Get user Get session ID Connection Manager Admin API Server models...71 Account...72 Response entity Config...74 CmAccount ModelMap Collection<<Account>>...76 Environment variable CmPerfStats CmStatus CmStats CmLog

6 Contents API GET example...78 Chapter 12: Troubleshooting Troubleshooting client logging issues Setting up the local log folder to produce a client log file Troubleshooting Java Scheduler issues Starting the Java Scheduler in the rbexamples account...81 Updating the number of webshares Appendix A: Configuration files JavaScheduler.ini file Sections of the JavaScheduler.ini file...84 [LogLevel] section...84 [Default] section...84 [account] section rgw5.ini file...88 Sections of rgw5.ini file...89 [LogLevel] section...89 [Default] section...90 [accountname] section...90 The application.properties file Appendix B: Error codes...96 Error codes

7 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, managing the Java Scheduler, 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 RedBack Object Server The RedBack Object Server manages access to RedBack applications and 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 (Connection Manager) 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. Admin API Server The Admin API web server hosts a Web API and accompanying Web UI for Java Scheduler (Connection Manager) administration. RedBeans and RedPages.NET The RedBeans and RedPages.NET components are the Java and.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 Web Designer User s Guide. 7

8 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 8 Editing a U2 server definition, on page 9 Connecting to a U2 server, on page 9 Disconnecting from a U2 server, on page 9 Creating a U2 account, on page 10 Enabling an account for U2 Web DE, on page 10 Editing the configuration files, on page 11 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. Prerequisites Install Web DE as described in Installation and Configuration. Deploy the RedBack Object Server to a UNIX or Windows computer as described in Installation and Configuration. Procedure Open Web Designer by clicking Start All ProgramsRocket U2 Web Development Environment U2 Web Designer. From the U2 Resource view, right-click Servers and select New U2 Server. 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 Select UniData or UniVerse, depending on the database you use. 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. 8 In the RPC Port# field, enter the port number of the UniRPC server running on the host. The default port number is

9 Editing a U2 server definition 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. 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. Click Finish to create the U2 server. b. 6. 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. 2. 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. 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. Prerequisites Creating a U2 server definition, on page 8 Procedure From the U2 Resource view, double-click the name of the U2 server to which you want to connect. In the Connect to a U2 Server window, enter your user ID and password. If you are using a proxy server, select the Use Proxy Server check box, and enter the proxy host and port. 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 9

10 Chapter 2: Creating a Web DE-enabled U2 account 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. 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. Prerequisites Connecting to a U2 server, on page 9 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 From the U2 Resource view, right-click Accounts and select New U2 Account. 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. 3. Select the flavor of UniVerse to use, and optionally select the Use Default Login check box. 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. 10

11 Editing the configuration files Prerequisites Creating a U2 account, on page 10 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. 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 From the U2 Resource view, expand Accounts, right-click the account you want to enable, and select Enable for U2 Web DE. 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 12 Inserting an account reference in the rgw5.ini file, on page 14 Editing the rgw5.ini file on a remote web server, on page 15 11

12 Chapter 2: Creating a Web DE-enabled U2 account 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. Prerequisites Enabling an account for U2 Web DE, on page 10 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 83. Procedure From the Tools menu, select Edit Java Scheduler Configuration. In the Open window, browse to the C:\U2\U2WDE directory and double-click the JavaScheduler.ini file. 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 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 that are 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. To modify the account s connection pool parameters, click Next and enter details in the Establish account connection details page in the wizard. e. Table 3: Connection pool parameters 12 Parameter Idle Remove Threshold To set an idle remove threshold parameter for the account, select 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.

13 Inserting an account reference in the JavaScheduler.ini file f. Parameter Idle Remove Exec Interval To set an idle remove execution interval for the account, select the 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. 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. 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 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. g. Enable SSL for this account s connection(s) to server To use the SSL protocol when making connections to the U2 server, select this check box. Enable server-side logging for this account Specifies whether to save the server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. Create the uoj_trace.log file To keep a log of UOJ processes for the account, select this check box. Enable tcp keep alive for account threads To keep alive scheduler threads that take client requests, select this check box. Enable scheduler developer mode for this account Automatically resets all available connections in the connection pool to load source code that has been created or modified. To modify the monitor parameters for the account, click Next and complete the Establish monitor warning thresholds page in the wizard. Table 5: Monitor threshold parameters Parameter Average Response Time Triggers monitor warnings when the overall average request response time exceeds these values. The average covers the period since the Connection ManagerScheduler was last started. Select the amount of milliseconds for when to trigger yellow and when to trigger red. 13

14 Chapter 2: Creating a Web DE-enabled U2 account Parameter Average Response Time Interval Triggers monitor warnings when the average request response time exceeds these values. The average covers a single monitor refresh interval. Select the amount of milliseconds for when to trigger yellow and when to trigger red. Account Requests Queued Triggers monitor warnings when the number of requests waiting to be served exceeds these values. Select the amount of milliseconds for when to trigger yellow and when to trigger red. Slow Process Time Triggers monitor warnings when any requests exceeds this value. Select the amount of milliseconds for when to trigger red. h. Click Finish. In the JavaScheduler.ini tabbed page, review the changes in the new account section and make corrections if necessary. 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. Prerequisites Enabling an account for U2 Web DE, on page 10 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 88. Procedure From the Tools menu, select Edit Gateway Configuration. 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. 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 12. In the rgw5.ini tabbed page, review the changes in the new account section and make corrections, if necessary. To save the changes to the rgw5.ini file, select File Save.

15 Editing the rgw5.ini file on a remote web server Editing the rgw5.ini file on a remote web server Encrypting a password When deploying a Web DE application to a web server, you need to establish the rgw5.ini file on that server. While rgw5.ini does support unencrypted passwords, having a plain-text passwords on a server is not secure. Previously, to encrypt the password, you had to use the Web Designer to edit the rgw5.ini file, save it locally, then deploy it to the server. Now, you can edit the rgw5.ini file outside of Web Designer, and use a command to encrypt the password and send it back to the web server without interacting with the Web Designer. Prerequisites Before you can encrypt plain-text passwords in the rgw5.ini file on a remote web server, you must have a v5.2.0 or higher of RedBeans.jar, and Java 6 or higher installed on the remote web server. To edit and encrypt plain text passwords in the rgw5.ini file, perform the following steps: Procedure Open the rgw5.ini file in text editor on the remote web server. Enter one or more plain-text passwords, and save the file. Open a command prompt, and run the following command: java -cp /path/to/redbeans.jar com.rs.u2.wde.redbeans.verifyini./ rgw5.ini The password encrypts in the rgw5.ini file. 15

16 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. Prerequisites Connecting to a U2 server, on page 9 Enabling an account for U2 Web DE, on page 10 Procedure From an expanded Web DE-enabled account, double-click the U2 Web DE Elements node.

17 Deleting a module 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 28. When the connection to the RedBack Object Server opens, the U2 Web DE Elements tree displays one or more modules. Figure 2: Modules Right-click U2 Web DE Elements and select New Module. 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 Expand the U2 Web DE Elements tree, right-click a module, select U2 Web DE Elements, and then select Delete. 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. 17

18 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. Prerequisites Connecting to a U2 server, on page 9 Enabling an account for U2 Web DE, on page 10 Creating a module, on page 16 Procedure 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. From the Database Files node, select New U2 File. 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. 4. To continue, click Next. 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 6: UniData file options Field or Option 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 18 The number of data groups in the file. Applicable only to Hashed and MULTIFILE file types.

19 Creating U2 database files Field or Option Block Size The block size of data groups in the file. Applicable only to Hashed file types. 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 8: UniVerse dynamic file options, on page

20 Chapter 4: Creating files Table 7: UniVerse static file options Field or Option 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. 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. 20

21 Creating U2 database files Table 8: UniVerse dynamic file options Field or Option 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 Algorithm Select one of the following options: 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. 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. 21

22 Chapter 4: Creating files 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 22

23 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. 23

24 Chapter 5: Managing garbage collection 3. 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 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. 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 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. 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.

25 Stopping the phantom control Expand the various nodes in the tree view to see more detail about each garbage collection run. Garbage collection logs are ordered by week. Click Clear Log Data to clear the data from the WWLOG file on the connection s rbdefn account. 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 From the Garbage Collect tab, click Run GC Now. In the Run Garbage Collection Now dialog box, click Yes to accept the warning message that the process may take extra time. State management As part of the state file management system, a session repository called WWSESSION contains a list of the state (WWSTATE) items created for each session, as well as a list of saved lists (SAVEDLISTS on UniData and &SAVEDLISTS& on UniVerse). The date and time is stored and updated every time a session-related state item or saved list is written. Garbage collection uses the last update date and time in WWSESSION to determine whether a session has expired. If the session is expired, Web DE deletes the entire list of state and saved list items within the session item. This provides a much quicker and cleaner method to clean WWSTATE. By default, state management functionality is disabled. To enable it, set the value of the WWSESSION environment variable to 1 in the JavaScheduler.ini file, for example: [rbexamples] workdir=c:\u2\u2wde521\udserver\rbexamples MinimumPoolSize=1 MaximumPoolSize=10 ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost como=1 usingssl=0 [rbexamples.environment] account_desc=rbexamples GMT TZ=GMT 25

26 Chapter 5: Managing garbage collection WWSESSION=1 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 and a block size of 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. WWSESSION file size guidelines The size of the WWSESSION file is highly application-dependent. The file will hold one record for each unique session stored in WWSESSION with a list of the individual records associated with each sessions and is used to speed up the process of garbage collection. In most cases, a database administrator must resize the WWSESSION file in conjunction with the WWSTATE file. However, you can determine whether resizing needs to take place. For more specific steps, refer to Administering UniVerse on Windows Platforms or Administering UniVerse on UNIX Platforms. You should use the same factors considered in sizing WWSTATE when sizing the WWSESSION file. As a general guideline, the size of the WWSESSION file would be proportional to the size of WWSTATE and the two files would be jointly resized as needed. 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. 26

27 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 Enter the information for the new user. 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. 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 Web Designer User s Guide. 5. To save the new user, select File > Save. 27

28 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 From the Users tab, click List Users. From the user list, select a user to view, edit, or delete, and click OK. 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 9: Security aspects Type of security SSL SSL (Secure Sockets Layer) is the standard security technology for establishing an encrypted link between a web server and a browser. This link ensures that all data passed between the web server and browsers remain private and integral. SSL is an industry standard and is used by millions of websites in the protection of their online transactions with their customers. 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 access Through your application code, you can prompt for a user name and password, 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. 28

29 Application security and Web DE Type of security PCI DSS Compliant The PCI-DSS (Payment Card Industry Data Security Standard) is an information security standard for organizations that handle credit cards, and was created to increase controls around cardholder data to reduce credit card fraud. This standard requires strong cryptography and security protocols be used to safeguard sensitive cardholder data during transmission over open public networks (e.g. the Internet, wireless technologies, cellular technologies, GRPS (General Packet Radio Service), and satellite communications) including: Only trusted keys and certificates are accepted. The protocol in use only supports secure versions or configurations. The encryption strength is appropriate for the encryption methodology in use. Important: Web-DE uses the latest security libraries in Java 1.8, which means that security protocol of TLSv1.1 and TSL1.2 will meet PCI 3.2 requirements. Early SSL and TLS protocols, such as SSLv2, SSLv3, and TLSv1, should not be used for secure communication as they will not meet the minimum PCI requirements. 29

30 Chapter 7: Restricting administrative views and functionality Often times, it is only appropriate for administrators to see all of the accounts and information on a server and be able to perform administrative tasks, such as setting up new users and deleting accounts. With Web DE, you can control what users can see and do through subroutines, which are run when users connect to the server. To restrict administrative views and functionality from non-administrative users, create a new subroutine or edit an existing one, compile it, and globally catalog it. The new subroutine will automatically run when users connect to the server where the subroutine was cataloged. Activity logging is also available for troubleshooting purposes. Review the logs to examine server activity and determine which options are in effect for the client. Creating, compiling, and cataloging the subroutine You can restrict administrative views and functionality by creating or modifying the XTOOLSUB program, compiling the subroutine, and globally cataloging it. About this task The XTOOLSUB program is a U2 database server-side BASIC program used by a variety of U2 client tools, including Web DE. This program contains several different files, including XTOOLSUB_XPRE and XTOOLSUB_EXECPRE, which control pre-execution functionality, and XTOOLSUB_XPST and XTOOLSUB_EXECPOST, which control post-execution functionality. You might already have XTOOLSUB installed. If not, you can install a new version or create a new one altogether. Note: This chapter provides an overview of the process, intended for advanced users. For details regarding the XTOOLSUB program, refer to DBTools User Guide. Procedure 1. Locate the program files or create new files, using the Basic Developer Toolkit or your favorite text editor. For UniVerse: XTOOLSUB_XPRE XTOOLSUB_XPST For UniData: XTOOLSUB_EXECPRE XTOOLSUB_EXECPOST Edit the subroutines, as appropriate. The following tables explain the incoming and outgoing arguments. Incoming argument Incoming value X_CODE Controls whether to treat the connected user (server-side log-in) as an administrative user.

31 Creating, compiling, and cataloging the subroutine Incoming argument Incoming value Controls the U2 activity bitmask. X_PARAMS Unused This argument is not used. Outgoing argument Return value X_ERROR X0: Success If X_CODE was successfully handled by this subroutine, XTOOLSUB will not attempt to handle X_CODE. Xn: If n is not 0, an error occurred and X_OUTPUT contains the error details message. X_OUTPUT 1 or 0 if X_CODE = X_OUPUT if X_CODE = Returns 1 if the user is an administrative user. Returns 0 (zero) if the user is not an administrative user. Returns a bitmask of U2 activity options: 0: No effect. 1: User can perform administrative tasks. 2: User can only see U2 Web DEenabled accounts. Returns the sum of selected options, which indicates what the user can see and do in the program. For example, 3 indicates the user can perform administrative tasks, but they can only see U2 Web DEenabled accounts. 4: Show mobility (currently has no effect). Sample code is shown below, for your reference. 3. SUBROUTINE XTOOLSUB_EXECPRE(X_CODE, X_PARAMS, X_OUTDATA, X_ERROR) BEGIN CASE CASE X_CODE = * Return a 1 for admin user or 0 for non-admin X_OUTDATA = "0" X_ERROR = "X0" * code to determine if user is admin and if so, set X_OUTOUT to 1 = "jadmin" THEN X_OUTDATA = 1 END CASE X_CODE = * Return a bitmask of U2Activity options * 0 = none (same as it was before changes) * 1 = Enforce Admin * 2 = Show WEBDE/hide other * 4 = Show Mobility X_OUTDATA = "3" ;* Enforce admin user for admin commands AND hide non-webde stuff X_ERROR = "X0" END CASE RETURN END Save your changes. For UniVerse from the TCL prompt: >ED BP XTOOLSUB_XPRE For UniData from the ECL prompt: :AE BP XTOOLSUB_EXECPRE 31

32 Chapter 7: Restricting administrative views and functionality 4. In these examples, the subroutines were saved in the BP folder. Compile the subroutine. For UniVerse from the TCL prompt: >BASIC BP XTOOLSUB_XPRE For UniData from the ECL prompt: :BASIC BP XTOOLSUB_EXECPRE 5. Globally catalog the subroutine. For UniVerse from the TCL prompt: >CATALOG BP * XTOOLSUB_XPRE XTOOLSUB_XPRE FORCE For UniData from the ECL prompt: :CATALOG BP XTOOLSUB_EXECPRE GLOBAL FORCE The new subroutine will automatically run when users connect to the server where the subroutine was cataloged. Viewing the activity log Activity logging is available for troubleshooting purposes. Review the logs to examine server activity and determine which options are in effect for the client. The logs are created in the same folder U2WebDesigner.exe is run. The default is %U2WEBDE%\U2 Web Designer. To turn on the activity log, complete the following steps: From the U2 Resource view, select Window Preferences. In the Preferences dialog, click on UniData/UniVerse on the left side of the pane, select the Turn on U2 activity logging option, and click OK.

33 Viewing the activity log Important: This log grows quickly, so turn it off after you collect the information you need. Log file naming conventions, location, and formats are described below. Log name format: Log location: Log format 1: Log format 2: U2Activity_yyyyMMdd_hhmmss.log Example: U2Activity_ _ log Wherever the U2WebDesigner.exe is located on the client. yyyy-mm-dd,hhmmss.ms,event,message Example: ,09:53:32.204,LogLevel Change,Logging level set to "ALL" yyyy-mm-dd,hhmmss.ms,[server] U2Activity Name,message Example: ,09:54:16.306,[eng46 ud] Deploy to U2 Server,true A sample log is shown below. Selected options appear in bold for readability purposes ,09:53:32.204,LogLevel Change,Logging level set to "INFO" ,09:53:32.204,LogLevel Change,Logging level set to "ALL" ,09:53:33.421,[null] Delete Action,true ,09:53:33.437,[null] Create New Account,false ,09:53:33.437,[null] Create New Account,handler: com.rs.u2webbuilder.ui.u2resource.u2activity.u2activityadminonlyenabler. isenableready(): false ,09:53:33.437,[null] Enable Account for Web DE,false ,09:53:33.437,[null] Enable Account for Web DE,handler: com.rs.u2webbuilder.ui.u2resource.u2activity.u2activityadminonlyenabler. isenableready(): false ,09:53:33.437,[null] Enable U2 Working Set Menu,false ,09:53:33.437,[null] Enable U2 Working Set Menu,handler: com.rs.u2webbuilder.ui.u2resource.u2activity.u2activityallownonwebdeenabler.isenableready(): false ,09:54:16.290,[eng46 ud] Delete Action,true ,09:54:16.290,[eng46 ud] WebdeActivitiesUtil.getWebdeOptions() optsmask= ,09:54:16.290,[eng46 ud] WebdeActivitiesUtil.isEnforceAdmin(),true ,09:54:16.290,[eng46 ud] WebdeActivitiesUtil.isAdminUser(),isAdmin=true ,09:54:16.290,[eng46 ud] Create New Account,true ,09:54:16.306,[eng46 ud] WebdeActivitiesUtil.getWebdeOptions(),optsMask= ,09:54:16.306,[eng46 ud] WebdeActivitiesUtil.isEnforceAdmin(),true ,09:54:16.306,[eng46 ud] WebdeActivitiesUtil.isAdminUser(),isAdmin=true ,09:54:16.306,[eng46 ud] Enable Account for Web DE,true ,09:54:16.306,[eng46 ud] Deploy to U2 Server,true ,09:54:16.306,[eng46 ud] WebdeActivitiesUtil.isAdminUser(),isAdmin=true ,09:54:16.306,[eng46 ud] Enable U2 Working Set Menu, WebdeActivitiesUtil.isFilterNonWebde() This user is an admin user. No filtering of non-webde elements will take place ,09:54:16.306,[eng46 ud] Enable U2 Working Set Menu,true 33

34 Chapter 8: 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 others 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. Caution: Locking an RBO prevents others from modifying the RBO structure, attributes, properties, and methods when you are working on it, but does not prevent others from editing the subroutine code. However, if the subroutine is locked at the database level and another developer tries to access it, (for example, in the After Effects editor) Web DE will deny them access. 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 Make any changes to the RBO by double-clicking it and editing the details. For more information, see Web Designer User s Guide. To save the changes, select File Save. To unlock the RBO, right-click it and select Unlock RBO. Alternatively, an Unlock icon ( 34 ) is available on the toolbar.

35 Chapter 9: 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 10: Subroutine parameters Parameter 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. 35

36 Chapter 9: Managing revision control Parameter 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 36

37 Chapter 10: Configuring and running the Java Scheduler The following sections describe the steps for setting up and getting started managing with the Java Scheduler. For more information about managing the Java Scheduler, see the Administrator s Guide. Managing the Java Scheduler on Windows The Java Scheduler can be installed on or deployed to a Windows computer and managed in several administration tasks: Configuring the Java Scheduler (Windows), on page 37 Running the Java Scheduler on Windows, on page 42 Monitoring performance on Windows, on page 44 Registering or unregistering the Java Scheduler as a Windows service, on page 52 Configuring the Java Scheduler (Windows) Global and account-related parameters provide the settings that the Java Scheduler requires to process HTTP requests. After installing Web DE, configure the Java Scheduler by modifying settings with a wizard in the Web Designer. Prerequisites Before you can configure the Java Scheduler, you need to have Web DE installed with the RedBack Object Server and Java Scheduler deployed to a Windows computer. For more information, see Installation and Configuration. A U2 server must also be defined, as described in Creating a U2 server definition, on page 8. Procedure Modifying default global settings (Windows), on page 37 Modifying account settings (Windows), on page 39 Inserting an account in the Java Scheduler configuration file (Windows), on page 42 Modifying default global settings (Windows) The Default section of the JavaScheduler.ini file contains global parameters that apply to all U2 accounts on the RedBack Object Server computer. Global parameters include connection settings and credentials, Secure Sockets Layer (SSL) security parameters, and settings for logging errors and warnings. Modifying the global settings that are used by the Java Scheduler allows you to process requests for all accounts On the Windows computer on which Web DE is installed, start the Web Designer. In the U2 Resource view, connect to the U2 server on which the RedBack Object Server component is installed. From the Tools menu, select Edit Local Java Scheduler Configuration. 37

38 Chapter 10: Configuring and running the Java Scheduler From the Open window, browse to C:\U2\U2WDEnnn\JavaScheduler and double-click the JavaScheduler.ini file to open this configuration file in the Editor pane. In the JavaScheduler.ini tabbed page, edit the parameters in the Default section: a. Maximize the JavaScheduler.ini tabbed page and expand the Default section. b. Double-click any property in the Default section and complete the form in the wizard. In the Server area, enter the details that are required to make connections between the Java Scheduler and the RedBack Object Server. Table 11: Server parameters Field Host name or IP address Enter the name or IP address of the RedBack Object Server computer. Server Type Select the type of U2 data server running on the RedBack Object Server computer: UniData or UniVerse. User Enter the operating system-level user ID for the RedBack Object Server computer. Password Verify Password Enter the password associated with the user ID, and reenter the password to verify it. In the Scheduler area, enter details for the Java Scheduler. Table 12: Connection parameters Field Server port Enter the port number on which the Java Scheduler accepts requests. Make note of this setting; you need it later when editing the rgw5.ini file. Monitor port Log path Enter the port number on which the Java Scheduler accepts monitor and maintenance requests. Enter the path to the Java Scheduler log (for example, C: \U2\U2WDEnnn\JavaScheduler\JavaScheduler.log). rbdefn account path Enter the path to the deployed rbdefn account (for example, C: \U2\U2WDEnnn\rbdefn). c. To test the settings that are entered for connection parameters, click Test Connection Settings. If the connection succeeds, the wizard returns the message Successful connection. If the connection fails, make changes to correct the error condition and test again. d. To modify global settings for Secure Sockets Layer (SSL) processing through the Java Scheduler, click Next and complete the second page in the wizard. Table 13: SSL parameters 38 Field SSLkeystore path Enter the path to the SSL keystore for the Java Scheduler. SSLkeystore password Verify password Enter the password for the SSL keystore, and reenter the password to verify it. Enable SSL client connections to the scheduler To allow SSL client applications to make connections to the Java Scheduler, select this check box.

39 Modifying account settings (Windows) To apply the changes, click Finish. In the JavaScheduler.ini tabbed page, review the changes in the Default section of the file and make corrections if necessary. To modify global parameters for Java Scheduler logging, in the Logging Settings area at the bottom of the JavaScheduler.ini tabbed page, select the check box for each type of information to write to the JavaScheduler.log file. e. f. 6. The following table describes each parameter. Each parameter is selected by default. If you do not want the parameter, clear the check box. Table 14: Logging settings 7. Parameter Panic To log unrecoverable errors, select the Panic check box. Error To log serious errors, select the Error check box. Warning To log warning messages, select the Warning check box. Inf To log informational messages, select the Inf check box. Init To log initialization/termination messages, select the Init check box. To save the changes to the JavaScheduler.ini file, select File Save. Modifying account settings (Windows) Each account section in the JavaScheduler.ini file contains parameters that apply to connections made to the associated U2 account only. Tip: The rbexamples section is provided as an example that shows the values to enter for each account to which the Java Scheduler needs to connect. 1. In the JavaScheduler.ini tabbed page, edit the parameters in the account section: a. Maximize the JavaScheduler.ini tabbed page and expand the section for the account to be modified. b. Double-click any property in the associated account section. In the Establish server details for this account connection page of the account editor wizard, enter the server details for the account connection. Table 15: Server parameters c. Field 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. In the Connection area, enter the details required to make connections between the account and the Java Scheduler. 39

40 Chapter 10: Configuring and running the Java Scheduler Table 16: Connection parameters Field 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 Password Enter the password that is associated with the user ID, and reenter the password to verify it. d. To test the settings that are entered for connection parameters, click Test Connection Settings. If the connection fails, make changes to correct the error condition and test again. e. In the Scheduler to Database Connections area, enter or select the minimum and maximum number of pooled connections available to the account. To modify the account s connection pool parameters, click Next and enter details in the Establish account connection details page in the wizard. f. Table 17: Connection pool parameters g. Parameter Idle Remove Threshold To set an idle remove threshold parameter for the account, select 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 Interval To set an idle remove execution interval for the account, select the 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. 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. To modify optional parameters for the account, click Next and complete the Set optional account and connection properties page in the wizard. Table 18: Optional parameters Parameter 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 this account s connection(s) to server 40 To use the SSL protocol when making connections to the U2 server, select this check box.

41 Modifying account settings (Windows) h. Parameter Enable server-side logging for this account Specifies whether to save the server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. Create the uoj_trace.log file To keep a log of UOJ processes for the account, select this check box. Enable tcp keep alive for account threads To keep alive scheduler threads that take client requests, select this check box. Enable scheduler developer mode for this account Automatically resets all available connections in the connection pool to load source code that has been created or modified. To modify the monitor parameters for the account, click Next and complete the Establish monitor warning thresholds page in the wizard. Table 19: Monitor threshold parameters Parameter Average Response Time Triggers monitor warnings when the overall average request response time exceeds these values. The average covers the period since the Connection ManagerScheduler was last started. Select the amount of milliseconds for when to trigger yellow and when to trigger red. Average Response Time Interval Triggers monitor warnings when the average request response time exceeds these values. The average covers a single monitor refresh interval. Select the amount of milliseconds for when to trigger yellow and when to trigger red. Account Requests Queued Triggers monitor warnings when the number of requests waiting to be served exceeds these values. Select the amount of milliseconds for when to trigger yellow and when to trigger red. Slow Process Time Triggers monitor warnings when any requests exceeds this value. Select the amount of milliseconds for when to trigger red. To apply the changes, click Finish. In the JavaScheduler.ini tabbed page, review the changes in the account section and make corrections if necessary. Optional: To define separate environment variable values in an account, insert an account environment: a. On the JavaScheduler.ini tabbed page, in the Section/Property Name column, right-click the name of the account and select Insert Account Environment. b. In the Environment subsection, in the Value column for the account_desc property, enter an alternative description for the account. c. Insert additional property and value pairs for each environment variable to be defined for the account, for example, LANG=en_US TZ=MST7MDT Tip: You can use this technique to create an alias that points to the same account, but uses a different environment variable for connection pools. 5. To save the changes to the JavaScheduler.ini file, select File Save. 41

42 Chapter 10: Configuring and running the Java Scheduler Inserting an account in the Java Scheduler configuration file (Windows) After creating a U2 account, you can insert a reference to the account in the JavaScheduler.ini file and configure the account settings In the JavaScheduler.ini tabbed page, add an account to the JavaScheduler.ini file: a. Maximize the JavaScheduler.ini tabbed page. b. To add an account in the JavaScheduler.ini file, right-click in any empty cell and select Insert Account. c. Complete the form in the wizard, following the same instructions for step 1 as described in Modifying account settings (Windows), on page 39. To apply the new account details, click Finish. In the JavaScheduler.ini tabbed page, review the changes in the new account section and make corrections if necessary. To save the changes to the JavaScheduler.ini file, select File Save. Running the Java Scheduler on Windows After configuring the Java Scheduler, start the Java Scheduler service so it can process RedBeans and RedPages.NET connections from client applications. You can start or stop the Java Scheduler from the Web Designer interface. Prerequisites Configuring the Java Scheduler (Windows), on page 37 Procedure On the Windows computer on which Web Designer is installed, start and run Web Designer as an administrator. In the U2 Resource view, connect to the U2 server on which the RedBack Object Server component is installed. Expand the Accounts node. Expand the node of the U2 Web DE-enabled U2 account in which you want to work. Click the U2 Elements node and enter the RedBack administrator login credentials. The default user name of the administrator is rbadmin and the default password is redback. Right-click U2 U2 Elements and select Manage Java Scheduler. On the Scheduler Maintenance tab, start the Java Scheduler: a. In the Scheduler area, click Start. b. If the Java Scheduler cannot locate the Scheduler.jar file, you are prompted to browse to the path containing Scheduler.jar. The Scheduler.jar file default location is C: \U2\U2WDEnnn\JavaScheduler by default. To continue, click Scheduler.jar and then click Start again. Note: Subsequent attempts to start the Java Scheduler do not require you to browse to the Scheduler.jar file Optional: If you need to edit the JavaScheduler.ini file, click Edit Configuration and follow the steps in Configuring the Java Scheduler (Windows), on page 37. Optional: Click Restart account to restart the connection pool for the current account.

43 Viewing the Java Scheduler log You might make changes to account parameters after starting the Java Scheduler. The changes are not applied until the account is restarted. The default account restart time is 60 seconds. To modify this amount of time, add MaxRestartWait=nnn to the JavaScheduler.ini file, where nnn is the amount of seconds to wait. 10. The Java Scheduler can be left running in the background. If you need to stop the process for any reason, on the Scheduler Maintenance tab, click Stop. Viewing the Java Scheduler log When the Java Scheduler starts successfully, a JavaScheduler.log file is generated, which contains information about requests processed by the Java Scheduler. You can view this log file by navigating to it outside of Web DE, or you can view the file directly in the Web Designer. The location of the Javascheduler.log file is specified in the logpath parameter of the Javascheduler.inifile In the Web Designer, with the Java Scheduler started, click the Scheduler Maintenance tab. Click View Log. The Scheduler Log View tab displays. The log displays information about requests processed since the last time the Java Scheduler was restarted. Information about requests processed prior to the restart are stored in the Javascheduler.txt backup log file, which is accessible from the BackupLogs folder. The BackupLogs folder is typically located in the same directory as the Javascheduler.ini file. Figure 7: Scheduler Log View tab a. b. c. To view the next screen of the log, click More. To view the end of the log, click End. To view the beginning of the log again, click Start. 43

44 Chapter 10: Configuring and running the Java Scheduler 3. To view the level of detail provided in the logs, click Set Log Level. The Set log level dialog displays with the current log level selected. Note: You can change the log level when the Java Scheduler is running without stopping and restarting. The new log level remains until you change it again, or until the Java Scheduler is stopped. This logging level is transient and not saved in the Java Scheduler configuration file. Figure 8: Set log level 4. Select the appropriate log level option and click Set log level. Monitoring performance on Windows The Java Scheduler implements a performance monitor that records statistics on the requests processed for each account, and displays results in a table as well as a visual traffic light display. These statistics provide data to help you manage request processing and determine whether to make adjustments. The performance monitor runs as a separate process and can only be started when the Java Scheduler is running. Prerequisites Running the Java Scheduler on Windows, on page 42 Verify that the Java Scheduler is installed. For details, review Java Scheduler configuration information in Installation and Configuration. Note: You must use the same version of Web Designer as the Java Scheduler or else the monitor will not work properly. For example, use versions of both components of Web DE. Procedure Start the Java Scheduler and click the Scheduler Monitor tab.

45 Monitoring performance on Windows Figure 9: Scheduler Monitor tab The Scheduler Monitor tab displays the traffic light indicator, which allows a quick method of identifying the overall performance of the system. When the system starts to slow its response to requests, the traffic light shows a yellow light. When the number of licenses gets to a critical level, the yellow light turns to red. When the stop light displays these colors is configurable in the JavaScheduler.ini file. To run the performance monitor, in the Monitor area, click Start. If the monitor starts successfully, the Monitor Data area is displayed. If the monitor does not start, make sure that the Java Scheduler is running with administrator rights. Review the Webshares section to make sure they match up with what you have licensed for Web DE. This section shows the number of webshares that are licensed, busy, idle, and how many requests are waiting. Figure 10: Webshares section Review the table. The traffic light indicator changes colors based on performance levels that are defined in the JavaScheduler.ini file. You can modify these parameters to better suit your environment. For more information, see Defining the yellow and red triggers of the monitor from the cm.ini file, on page 46. The performance monitor can be left running in the background. If you need to stop the monitor for any reason, in the Monitor area, click Stop. To write performance statistics to a log, start the Performance Statistics Logger and specify how information is displayed in the log. To turn the logger on and off, or change the format of the log file from this tab, complete the following steps. To turn it on and off, or change the format of the log file from the command line, refer to Monitoring performance on UNIX. 45

46 Chapter 10: Configuring and running the Java Scheduler a. b. c. d. e. f. Click the Scheduler Maintenance tab. In the Performance Statistics Logger area, click Start. If the performance statistics logger starts successfully, the Perfstats.log file is created in the U2WDEnnn folder. The default location of this folder is C:\U2\U2WDEnnn, where nnn is the version number you installed. Review the output in this log. To view the statistics log as comma-delimited, select the Comma delimit log check box. To log only the request distribution processed by each database session or license during the specified time interval, select the Log license distribution check box. The performance statistics logger can be left running in the background. To stop it for any reason, click Stop in the Performance Statistics Logger area. Next step With the monitor running, you can perform the following tasks to help you manage your environment: Configure the monitor to display yellow or red according to values that are more suitable for you. See Defining the yellow and red triggers of the monitor from the cm.ini file, on page 46. View the process details for an account and the call stack when you encounter slow processes. See Viewing RBO process details and the BASIC call stack, on page 47. View the exceptions that are thrown and reset the counter when the exceptions are addressed to restart the count. See Viewing exceptions, on page 48. Change the monitor settings such as the interval at which the monitor updates and the account history information for the monitor. See Changing the monitor settings, on page 49. Filter the accounts that are displayed in the monitor table. See Filtering accounts in the monitor table, on page 50. Change which columns are displayed and in what order. See Configuring the monitor table columns, on page 51. Defining the yellow and red triggers of the monitor from the cm.ini file The triggers for the Connection Managertraffic light indicator for the Java Scheduler monitor can be modified in the cm.inijavascheduler.ini file. Open the cm.inijavascheduler.ini file in a text editor and add the following parameters to the appropriate account section: Note: You can also modify these in the Web Designer using a wizard, as described in step 3g of Inserting an account reference in the JavaScheduler.ini file, on page 12. Table 20: Monitor parameters 46 Parameter Table field affected AvgRespTime=n1 n2 Triggers monitor warnings when the Avg Wait overall average request response time exceeds these values. The average covers the period since the Connection ManagerScheduler was last started. n1 is the amount of time in milliseconds when the monitor displays yellow; n2 is the amount of time in milliseconds when the monitor displays red.

47 Viewing RBO process details and the BASIC call stack Parameter Table field affected AcctRequestsQueued=n1 n2 Triggers monitor warnings when the Requests Waiting number of requests waiting to be served exceeds these values. n1 is the amount of time in milliseconds when the monitor displays yellow; n2 is the amount of time in milliseconds when the monitor displays red. AvgRespTimeIteration=n1 Triggers monitor warnings when the Avg Wait Response n2 average request response time exceeds these values. The average covers a single monitor refresh interval. n1 is the amount of time in milliseconds when the monitor displays yellow; n2 is the amount of time in milliseconds when the monitor displays red. SlowProcessTime=n1 Triggers monitor warnings when any Slow Requests requests exceeds this value. n1 is the amount of time in milliseconds when the monitor displays red. Note: The traffic light indicator reflects the state of the table, not the status of a specific time. The longer your history is, the longer a color may appear on the traffic light indicator. For example, if your history is set to 50 lines, and you only had one red trigger occur, the traffic light will remain in a red state until the trigger is done running through each of the 50 lines. Viewing RBO process details and the BASIC call stack When you encounter a slow process, you can view the BASIC call stack to help you troubleshoot the problem. Note: The BASIC call stack is viewable with UniData versions 8.1 and higher. 47

48 Chapter 10: Configuring and running the Java Scheduler On the monitor table, when the Slow Req column appears red, select the account and click RBO Process Details. The Process Information for account window appears. This window shows you all of the slow requests that are building up. Optional: Sort the columns by clicking a column header. Optional: Click Refresh Process Info to refresh the window and see new process information that occurs with each passing interval of time. Select a process, and click View Call Stack. The call stack appears. Here, you see the last basic subroutine in the call stack where the process is taking an inordinate amount of time. Click OK. Viewing exceptions You can view the exceptions that occurred while running the monitor. 48

49 Changing the monitor settings 1. From the Performance and Error Counters group, click Exceptions thrown. The Scheduler Log View pane appears with only the exceptions displayed. 2. Optional: To view the beginning of the entire log, and not just the exceptions, click Start. 3. Optional: To clear the exceptions, click Reset Counter. Changing the monitor settings You can update the monitor interval time, change the amount of historical lines per account, and how webshare usage should be displayed by changing the settings for the monitor. 1. Click the Gear icon ( ), and select Filters Settings. Note: The same options accessed from the Gear icon are available by right-clicking the table. The Monitor Settings window appears. 2. Change the settings for the performance monitor. 49

50 Chapter 10: Configuring and running the Java Scheduler The following table describes the settings. Table 21: Performance monitor settings Parameter Interval Enter or select the number of seconds to delay between requests for data from the monitor thread. The default interval is 1 second. The minimum setting is 1; the maximum setting is 300. History Enter or select the number of lines of history to keep in the Monitor table area of the Scheduler Monitor tab for each account. The default number of lines of history is 5. The minimum setting is 1; the maximum setting is unlimited. Webshare Usage Display Options 3. Select whether to display the Busy and Idle webshare information as a whole number of as a percentage. Click OK to accept the changes. Filtering accounts in the monitor table Some sites require multiple accounts, but you might only need to monitor a few at a time. You can filter which accounts you want to see and then restart the Monitor to have only the selected accounts displayed. The filtered accounts are then the only accounts that trigger the yellow and red alerts instead of all the accounts. 1. Click the Gear icon ( ), and select Filters Accounts. Note: The same options accessed from the Gear icon are available by right-clicking the table. The Monitor Accounts Filter window appears. Figure 11: Monitor Accounts Filter window 2. Select the check box next to the account that you want to display, and click Accept Changes. The monitor restarts so it can apply the filter. Monitoring client threads Use the Scheduler Monitor pane to show the status of client threads and thread pools. 50

51 Configuring the monitor table columns 1. Click the Gear icon ( ), and select Account Thread Details. 2. In the Client Thread Information dialog, click Refresh Thread Info to view the current client IP addresses that are being used and the associated client threads. Click OK to return to the Scheduler Monitor pane. 3. Configuring the monitor table columns You can configure which columns are displayed in the table and reorganize them to the order you want. 1. Click the Gear icon ( ), and select Filters Table columns. Note: The same options accessed from the Gear icon are available by right-clicking the table. The Monitor Columns Filter window appears. 51

52 Chapter 10: Configuring and running the Java Scheduler Figure 12: Monitor Columns Filter window Clear the check boxes for the columns that you do not want displayed. By default, all columns are displayed. Click Accept Changes. Configuring the parameters to work with your system When you add the parameters to the JavaScheduler.ini file that affect the data table, as described in Defining the yellow and red triggers of the monitor from the cm.ini file, on page 46, you might not get the results to appear how you want. To adjust your system properly to show each scenario, you need to understand the normal behavior of your environment. This allows you to determine the appropriate value for the monitor. For example, if your Web DE average response is 100ms, then you should consider changing the yellow setting if the average increases to 200ms, and changing the red setting if the average increases to 500ms. Careful consideration should be taken when assigning these values. Registering or unregistering the Java Scheduler as a Windows service The Java Scheduler process is registered as a Windows service by default, but the service can be unregistered as a Windows service, registered again through the Web Designer interface, or both. About this task When the Java Scheduler is registered as a Windows service, it offers the same conveniences as any other Windows service: 52

53 Managing the Java Scheduler on UNIX The process restarts automatically after the server computer is restarted. The service can be started or stopped from the Control Panel Administrative Tools Services panel. Regardless of whether you run the Java Scheduler as a Windows service, you can start or stop the process through the Web Designer. If you prefer not to run the Java Scheduler as a Windows service, unregister the service and manage it from the Web Designer interface only. Procedure On the Windows computer on which Web Designer is installed, start and run Web Designer as an administrator. In the U2 Resource view, connect to the U2 server on which the RedBack Object Server component is installed. Expand the Accounts node. Expand the node of the U2 Web DE-enabled U2 account in which you want to work. Click the U2 Elements node and enter the RedBack administrator login credentials. The default user name of the administrator is rbadmin and the default password is redback. Right-click U2 U2 Elements and select Manage Java Scheduler. On the Scheduler Maintenance tab, in the Windows Scheduler service area, unregister or register the Java Scheduler as a Windows service: If the Java Scheduler is currently registered as a Windows service, the Unregister button is active; click Unregister. If the Java Scheduler is not currently registered as a Windows service, the Register button is active; click Register. Managing the Java Scheduler on UNIX The Java Scheduler can be installed on or deployed to a UNIX computer and managed on UNIX in several administration tasks: Configuring the Java Scheduler (UNIX), on page 53 Modifying environment variables on UNIX, on page 56 Running the Java Scheduler on UNIX, on page 57 Monitoring performance on UNIX, on page 58 Configuring the Java Scheduler (UNIX) Global and account-related parameters provide the settings that the Java Scheduler requires to process HTTP requests. After installing Web DE, configure the Java Scheduler, configure the Java Scheduler by editing the JavaScheduler.ini file. Prerequisites Before you can configure the Java Scheduler, you need to have Web DE installed with the RedBack Object Server and Java Schedulerr deployed to a UNIX computer. For more information, see Installation and Configuration. A U2 server must also be defined, as described in Creating a U2 server definition, on page 8. 53

54 Chapter 10: Configuring and running the Java Scheduler About this task Configure the Java Scheduler on UNIX by editing the configuration file on Windows in the Web Designer, which encrypts passwords in the file, and then deploy the file to a UNIX computer On a Windows computer, open Web Designer and edit a local version of the JavaScheduler.ini file from Tools Edit Java Scheduler Configuration. For detailed steps, see Configuring the Java Scheduler (Windows), on page 37. Select Tools Deploy to U2 server Deploy a file or folder to deploy the JavaScheduler.ini file to the target UNIX computer. As an alternative, you can modify the JavaScheduler.ini file directly in an editor such as vi. Important: The alternative method is the easiest way to edit the configuration file on a UNIX computer, but it does not encrypt passwords. Procedure Modifying environment variables (UNIX), on page 54 Modifying account settings (UNIX), on page 54 Inserting an account in the Java Scheduler configuration file (Windows), on page 42 Modifying environment variables (UNIX) To run on a UNIX computer, the Java Scheduler needs the values of environment variables that supply the information required to process requests. After configuring the Java Scheduler, you must set environment variables on the UNIX server computer. Prerequisites Configuring the Java Scheduler (UNIX), on page 53 Procedure On the UNIX computer to which Web Designer is installed, set the value of the LANG environment variable to en_us. Set the CLASSPATH environment variable to the Java Scheduler directory (for example, CLASSPATH=/U2/U2WDEnnn/JavaScheduler). Set the PATH environment variable to the directory containing JRE 6 or later. Set the U2WDE environment variable to the parent directory in which components of Web DE are deployed (for example, U2WDE=/U2/U2WDEnnn, where nnn is the version number you installed). Modifying account settings (UNIX) Each account section in the JavaScheduler.ini file contains parameters that apply to connections made to the associated U2 account only. Tip: The rbexamples section is provided as an example that shows the values to enter for each account to which the Java Scheduler needs to connect With the JavaScheduler.ini file still open in the editor, edit parameters in the [account] section:

55 Modifying account settings (UNIX) a. b. On the first line of the section in the file, change the name of the account, if necessary. The account name must be enclosed in square brackets (for example, [myaccount]) Change the value of any parameter, if necessary. Table 22: Account parameters Parameter workdir Enter the physical path to the account directory on the RedBack Object Server computer. MinimumPoolSize Enter the minimum number of api_slave processes to be started and run by the Java Scheduler for the account. MaximumPoolSize Enter the maximum number of api_slave processes to be started and run by the Java Scheduler for the account. ConnectionString Enter udcs for UniData or uvcs for UniVerse. userid Enter the operating system-level user ID for the RedBack Object Server computer. password Enter the password associated with the user ID server Enter the name or IP address of the RedBack Object Server computer. como Use this option to start or stop copying server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. 0 Do not save the logs. usingssl 1 Save the logs. Enter a value to indicate whether to use the SSL protocol when making connections to the U2 server. 0 Do not use SSL. 1 Use SSL. 2. Optional: To define separate environment variable values in an account, insert an account environment: a. In the [account] section, insert a subsection: [account.environment] where account is the same name as the [account] section. b. In the [account.environment] subsection, insert the following parameter and value: account_desc=account_description where account_description is an alternative description for the account. c. Insert additional property and value pairs for each environment variable to be defined for the account, for example, LANG=en_US TZ=MST7MDT Tip: You can use his technique to create an alias that points to the same account, but uses a different environment variable for connection pools. 3. To save the changes to the JavaScheduler.ini file, select File Save. 55

56 Chapter 10: Configuring and running the Java Scheduler Adding an account to the Java Scheduler configuration file (UNIX) After creating a U2 account, you can add the account to the JavaScheduler.ini file and configure the account settings. Tip: The [rbexamples] section is provided as an example that shows the values to enter for each account to which the Java Scheduler needs to connect. 1. With the JavaScheduler.ini file still open in the editor, add a section for an account: a. On the first blank line in the accounts section of the file, enter the name of the new account, enclosed in square brackets (for example, [myaccount]. b. On each subsequent line, enter the name of the parameter, the equal sign, and a value for the parameter (for example, password=falc0n399, as shown in the column of the following table. Table 23: Account parameters Parameter workdir Enter the physical path to the account directory on the RedBack Object Server computer. MinimumPoolSize Enter the minimum number of api_slave processes to be started and run by the Java Scheduler for the account. MaximumPoolSize Enter the maximum number of api_slave processes to be started and run by the Java Scheduler for the account. ConnectionString Enter udcs for UniData or uvcs for UniVerse. userid Enter the operating system-level user ID for the RedBack Object Server computer. password Enter the password associated with the user ID, and reenter the password to verify it. server Enter the name or IP address of the RedBack Object Server computer. como Use this option to start or stop copying server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. 0 Do not save the logs. usingssl 1 Save the logs. Enter a value to indicate whether to use the SSL protocol when making connections to the U2 server. 0 Do not use SSL. 1 Use SSL. 2. To save the changes to the JavaScheduler.ini file, select File Save. Modifying environment variables on UNIX To run on a UNIX computer, the Java Scheduler needs the values of environment variables that supply the information required to process requests. After configuring the Java Scheduler, you must set environment variables on the UNIX server computer. interface. 56

57 Running the Java Scheduler on UNIX Prerequisites Configuring the Java Scheduler (UNIX), on page 53 Procedure On the UNIX computer where Web Designer is installed, set the value of the LANG environment variable to en_us. Set the CLASSPATH environment variable to the Java Scheduler directory. For example, CLASSPATH=/U2/U2WDEnnn/JavaScheduler. Set the PATH environment variable to the directory containing JRE 6 or later. Set the U2WDE environment variable to the parent directory in which components of Web DE is deployed (for example, U2WDE=/U2/U2WDEnnn, where nnn is the version number you installed). Running the Java Scheduler on UNIX When you deploy the Java Scheduler to a UNIX computer, the wizard copies a standard script to the Java Scheduler directory on the target computer. You can modify the deployed script for the environment and run it as needed to manage the Java Scheduler on UNIX. The script runs the Java Scheduler as a background process on the UNIX computer. Prerequisites Modifying environment variables on UNIX, on page 56 You must set the U2WDE environment variable to parent directory in which components of Web DE were deployed to the UNIX computer (for example, U2WDE=/U2/U2WDEnnn, where nnn is the version number you installed). The U2 data server to which the Java Scheduler is connected must be running in order to make successful connections to each U2 account. The Java Scheduler can run on a separate computer from the U2 data server; no checking is performed to ensure that the U2 data server is running. Procedure On the UNIX computer to which the Java Scheduler is deployed, open a command window and change directory to the Java Scheduler path. In the Java Scheduler directory, open the U2WebDESchedulerScript file for editing. Review the content of the U2WebDESchedulerScript file. If necessary, modify the content of the script for the environment and save the changes to the file. To start the Java Scheduler, open a command window and run the script with the start command: U2WebDESchedulerScript start You can leave the Java Scheduler running in the background. To stop the Java Scheduler at any time, in the command window run the script with the stop command: U2WebDESchedulerScript stop To restart the Java Scheduler, in the command window run the script with the restart command: U2WebDESchedulerScript restart 57

58 Chapter 10: Configuring and running the Java Scheduler The default account restart time is 60 seconds. To modify this amount of time, add MaxRestartWait=nnn to the JavaScheduler.ini file, where nnn is the amount of seconds to wait. When the Java Scheduler starts successfully, a JavaScheduler.log file is generated in the directory specified in the JavaScheduler.ini file. The log contains information similar to the following: Jan 11, :40:27 AM com.rs.u2.u2cm.h INFO: Thread[main,5,main]--- U2CM Logging started at Fri Jan 11 08:40:27 MST Jan 11, :40:27 AM com.rs.u2.u2cm.h a INFO: Thread[main,5,main]Scheduler licensed for 10 webshares. Jan 11, :40:27 AM com.rs.u2.u2cm.h a INFO: Thread[main,5,main]Starting database sessions. Jan 11, :40:28 AM com.rs.u2.u2cm.h a INFO: Thread[main,5,main] 10 udcs database processes started for /U2/ U2WDE521/rbodemo Jan 11, :40:28 AM com.rs.u2.u2cm.h a INFO: Thread[main,5,main]The monitor for U2 Connection Manager has started on port 7071 Jan 11, :40:28 AM com.rs.u2.u2cm.h a INFO: Thread[main,5,main]Database check started You can navigate to the JavaScheduler.log file to view the log, or you can use the Web Designer to view it, as described in Viewing the Java Scheduler log, on page 43. Monitoring performance on UNIX The performance monitor on the Scheduler Monitor tab of the Web Designer can be used to monitor connections on a UNIX computer. If you prefer, you can run the performance monitor directly on the UNIX computer to which the Java Scheduler was deployed. The performance monitor runs as a separate, but dependent process and can be started only when the Java Scheduler is running. Prerequisites Running the Java Scheduler on UNIX, on page 57 Start the Java Scheduler and keep it running for this task. Procedure 1. With the Java Scheduler running on the UNIX computer, open a separate command window to the Java Scheduler path. 2. In the command window, enter the following command to start the performance monitor: java -jar getrequests.jar The first parameter is the number of iterations to run. You can run any number of iterations. The second parameter is the interval of each iteration in seconds. The interval is the number of seconds of delay between requests for data from the monitor thread. Increase or decrease this setting as necessary. The output of the monitor is similar to the following: Run queue is 0 Busy webshares are 0 rbodemo Requests are Avg license wait time is 4 Run queue is 0 Busy webshares are 0 rbodemo Requests are Avg license wait time is 4 58

59 Monitoring performance on UNIX 3. To write performance statistics to a log, start the Performance Statistics Logger and specify how information is displayed in the log. When the logger starts, a Perfstats.log file is created in the U2WDEnnn folder. The default location of this folder is C:\U2\U2WDEnnn, where nnn is the version number you installed. Enter the appropriate combination of command line options, as shown in the following examples: To start the logger without specifying how the log file format, enter -start in the command line. The log file will look similar to the following example: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: ,18:10: Requests Request Avg Resp Total per wait wait per wait Account Name Requests Interval time interval time rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples To start the logger and view the log as comma-delimited, enter -start -cd in the command line: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: ,18:16: To start the logger and log only the request distribution processed by each databases session or license during the specified time interval, enter -start -ld in the command line: ,18:17: ,18:17: ,18:17: ,18:17: ,18:17: ,18:17: ,18:17: ,18:17: ,18:17:27.614,rbexamples,4,0,804,0,0,0,2,0,0,rbexamples,4,0,804,0,0,0,2,0,0,rbexamples,4,0,804,0,0,0,2,0,0,rbexamples,4,0,804,0,0,0,2,0,0,rbexamples,4,0,804,0,0,0,2,0,0,rbexamples,4,0,804,0,0,0,2,0,0,rbexamples,5,1,643,0,0,0,1,1,0,rbexamples,5,0,643,0,0,0,1,1,0,rbexamples,5,0,643,0,0,0,1,1,0,rbexamples,5,0,1246,3013,0,0,2,0,0,rbexamples,5,0,1246,0,0,0,2,0,0 rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples rbexamples To start the logger, log only the request distribution processed by each databases session or license during the specified time interval, and view the log as comma-delimited, enter start -ld -cd in the command line: ,18:18: ,18:18: ,18:18: ,18:18:31.602,rbexamples,0,0,rbexamples,0,0,rbexamples,0,0,rbexamples,0,0 59

60 Chapter 10: Configuring and running the Java Scheduler ,18:18:32.602,rbexamples,0,0 To specify how often the data is collected, include a number before the command. For example, entering 5 -start -cd specifies that data is collected every five seconds, as shown in the following example: ,07:31: ,07:31: ,07:31: ,07:31: ,07:31: ,rbexamples,8,0,1157,0,0,0,2,0,0,rbexamples,8,0,1157,0,0,0,2,0,0,rbexamples,8,0,1157,0,0,0,2,0,0,rbexamples,8,0,1157,0,0,0,2,0,0,rbexamples,8,0,1157,0,0,0,2,0,0

61 Chapter 11: Using the Admin API Server The Admin API Server hosts a Web-based API and UI, which controls the administration of the Java Scheduler (Connection Manager). For detailed instructions on installing the Admin API Server, see the Web DE Installation and Configuration guide. Configuring, starting, and stopping the Admin API Server The application.properties file is the configuration file for the Admin API Server, and is located in the apiserver directory of the Web DE installation directory. Refer to the Web DE Installation and Configuration guide for details regarding this file Open the application.properties file with a text editor. In the [DB] section, set the properties to connect to the rbdefn account and validate credentials from the WWUSERS file. Ensure db.port is set to the database server port that stores the rbdefn account. Ensure db.user contains the user name of a person with permission to access the rbdefn account. Ensure db.host contains the host of the database server that stores the rbdefn account. Ensure db.account contains the complete path to the rbdefn account on the database server Ensure db.service contains the name to use to connect to the database server storing the rbdefn account. Use uvcs for UniVerse, or udcs for UniData. Generate an encrypted form of the password for the db.user specified in the previous step by running the following program, which accepts a password and then returns an encrypted string for the password: $ java -jar hazify.jar -i Enter password: <hidden-password> [Enter] Enter password again: <hidden-password> [Enter] Encrypted password is: 5ngyZOfm3M0kxWUi2SdUlA== Copy the encrypted password string and paste it into the db.pass field. Save the application.properties file. Start the Admin API Server. On Windows, start the Admin API Server from Windows Services. On UNIX, start the Admin API Server from the command line using the following shell command: $ start-admin.sh & 7. It might take several minutes for the service to start, depending on your installation configuration. Runtime errors are stored in the cm-admin.log file, which is located in the apiserver logs directory. By default, the Admin API server is listening on port You can access it in a browser at The default login user name and password are rbadmin and redback. Secure the connections between the rbdefn account and the Admin API server, and the connections between the Admin API Server and the browser client. Refer to the Web DE Installation and Configuration guide for instructions on securing these connections. 61

62 Chapter 11: Using the Admin API Server 8. You can stop the Admin API Server at any time. On Windows, stop the Admin API Server from Windows Services. On UNIX, stop the Admin API Server from the command line using the following command: $ stop-admin.sh The Connection Manager Admin API Server In addition to the Web Admin User Interface, you can drive the Connection Manager (a.k.a. Java Scheduler) admin functionality through an HTTP 1.1 application programming interface using your own client. This section details the API language for Connection Manager. Connection Manager Admin API paths Use the following POST, GET, and PUT paths to perform Connection Manager (Java Scheduler) tasks, such as starting the Connection Manager or setting the logging level. Start the Connection Manager POST /api/manager/_start Starts the Connection ManagerJava Scheduler Responses Table 24: Start Connection ManagerJava Scheduler Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Stop the Connection Manager POST /api/manager/_stop Stops the Connection ManagerJava Scheduler Responses Table 25: Stop Connection ManagerJava Scheduler Responses 62 Code 200 OK 401 Unauthorized 403 Forbidden Schema

63 Get accounts Get accounts GET /api/manager/accounts Returns a JSON encoding representing a list of accounts. The decoded response is a list containing accounts. Each account in the list is a dictionary containing statistics and information about the account. Responses Table 26: Get Accounts Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get account information GET /api/manager/accounts/stats Returns a JSON encoding representing account information along with a list of accounts. The decoded response is a dictionary containing a list of accounts and several key value pairs describing connection manager information. Each account in the list is a dictionary containing statistics about the account. Responses Table 27: Get Account Information Responses Code 200 Success 401 Unauthorized 403 Forbidden 500 Failure Schema 63

64 Chapter 11: Using the Admin API Server Update account POST /api/manager/accounts/{accountname} Updates a Connection ManagerJava Scheduler account Parameters Table 28: Update Account Parameters Name Located In Required accountname path accountname Yes data body data Yes Schema Responses Table 29: Update Account Responses Code 200 OK 201 Created 401 Unauthorized 403 Forbidden Schema Restart account POST /api/manager/accounts/{accountname}/_restart Restarts the account specified in the accountname path parameter Parameters Table 30: Restart Account Parameters 64 Name Located In Required accountname path accountname Yes Schema

65 Get config file Responses Table 31: Restart Account Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get config file GET /api/manager/config Body of HTTP response contains a JSON representation of the Connection ManagerJava Scheduler configuration file. Responses Table 32: Get Config Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Save config file PUT /api/manager/config Saves Connection ManagerJava Scheduler configuration file. Parameters Table 33: Save Config Parameters Name Located In Required config body Connection Manager configuration Yes Schema 65

66 Chapter 11: Using the Admin API Server Responses Table 34: Save Config Responses Code 200 Success 401 Unauthorized 403 Forbidden 500 Failure Schema Get log entries GET /api/manager/log Returns log entries from the cm logjava Scheduler file. Takes an optional query string value offset to determine which part of and how much of the log is returned. Note the value must be an integer. There are three different options for the offset value: -1 returns the last 8 KB of data from the log file. This is helpful for getting the latest entries to the log. An offset of 0 returns up to 4 MB of data starting at the beginning of the log. Any other positive integer offset value returns the next 4 MB of data from the log after skipping over number of bytes. This can be used to retrieve the entire log if it is larger than 4 MB. If number is larger than the log size the log value with be the empty string. Parameters Table 35: Get Log Entries Parameters Name Located In Required offset query offset No Responses Table 36: Get Log Entries Responses Code 200 OK 401 Unauthorized 403 Forbidden Get log errors GET /api/manager/logerrors Returns all error log entries from the cm logjava Scheduler file. 66 Schema Schema

67 Get status of performance statistics logger Responses Table 37: Get Log Errors Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get status of performance statistics logger GET /api/manager/perfstats Returns operational status of the performance statistics logger. Responses Table 38: Performance Statistics Logger Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Start performance statistics logger POST /api/manager/perfstats/_start Start the performance statistics logger 67

68 Chapter 11: Using the Admin API Server Parameters Table 39: Start Performance Statistics Logger Parameters Name Located In cmperfstats body Required Schema cmperfstats Yes Responses Table 40: Start Performance Statistics Logger Responses Code 200 OK 401 Unauthorized 403 Forbidden Stop performance statistics logger POST /api/manager/perfstats/_stop Stop the performance statistics logger Responses Table 41: Stop Performance Statistics Logger Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get API process information GET /api/manager/processinfo Get API process information. 68 Schema

69 Set logging level Parameters Table 42: Get API Process Information Parameters Name Located In Required account query account Yes Schema Responses Table 43: Get API Process Information Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Set logging level POST /api/manager/setloglevel/{loglevel} Set the logging level for Connection Managerthe Java Scheduler. Options are INFO, WARNING, SEVERE (errors), FINE (debug). Parameters Table 44: Set Logging Level Parameters Name Located In Required loglevel path loglevel Yes Schema Responses Table 45: Set Logging Level Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get call stack GET /api/manager/stack Get the call stack. 69

70 Chapter 11: Using the Admin API Server Parameters Table 46: Get Call Stack Parameters Name Located In Required pid query pid Yes Responses Table 47: Get Call Stack Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get Connection Manager status GET /api/manager/status Returns basic status information for Connection Managerthe Java Scheduler. Responses Table 48: Get Connection Manager Status Responses Code 200 OK 401 Unauthorized 403 Forbidden Get user GET /api/user Get the logged in user. 70 Schema Schema

71 Get session ID Responses Table 49: Get User Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Get session ID GET /api/token Gets the session ID for this session. Responses Table 50: Get Session ID Responses Code 200 OK 401 Unauthorized 403 Forbidden Schema Connection Manager Admin API Server models The Connection Manager AdminWeb API Server uses a set of JSON model structures in its request and response payloads. These models are described in the sections that follow. 71

72 Chapter 11: Using the Admin API Server Account 72

73 Response entity Response entity 73

74 Chapter 11: Using the Admin API Server Config 74

75 CmAccount CmAccount 75

76 Chapter 11: Using the Admin API Server ModelMap Collection<<Account>> Environment variable CmPerfStats 76

77 CmStatus CmStatus CmStats CmLog 77