Rocket U2 Web Development Environment

Rocket U2 Web Development Environment Web Designer User s Guide Version 5.2.0 July 2015 WDE-520-ALL-UG-01

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

Corporate information Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: www.rocketsoftware.com Rocket Global Headquarters 77 4 th Avenue, Suite 100 Waltham, MA 02451-1468 USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers. Country Toll-free telephone number United States 1-855-577-4323 Australia 1-800-823-405 Belgium 0800-266-65 Canada 1-855-577-4323 China 800-720-1170 France 0800-180-0882 Germany 08-05-08-05-62 Italy 800-878-295 Japan 0800-170-5464 Netherlands 0-800-022-2961 New Zealand 0800-003210 South Africa 0-800-980-818 United Kingdom 0800-520-0439 Contacting Technical Support The Rocket Customer Portal is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Customer Portal and report a problem, download an update, or find answers to in the U2 Knowledgebase. To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go to www.rocketsoftware.com/support. In addition to using the Rocket Customer Portal to obtain support, you can send an email to u2support@rocketsoftware.com or use one of the following telephone numbers. Country Telephone number North America +1 800 729 3553 United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691 Europe/Africa +44 (0) 20 8867 3692 Australia +1 800 707 703 or +61 (0) 29412 5450 New Zealand +0800 505 515 3

Contents Notices... 2 Corporate information... 3 Part I: Rocket U2 Web Development Environment overview... 6 Chapter 1: Introduction...7 Web DE components... 7 Part II: RBOs and RPCs...8 Chapter 2: Application development with the RBO model... 9 RedBack objects (RBOs) overview...9 RBO properties and methods... 9 RBO classes... 10 Session and state overview... 11 Sessions... 11 State...12 Understanding how session and state work together... 13 Chapter 3: Developing RBOs...15 Getting started with Web Designer... 15 Developing RBOs... 15 Creating or editing RBOs...15 Creating an RBO... 15 Editing an RBO...19 Creating an RBO from a U2 database file...20 Deleting an RBO...20 Locking and unlocking an RBO... 20 Maintaining logical file definitions... 21 Creating a subroutine...22 Editing a subroutine... 23 Chapter 4: Developing server code for RBOs...25 Server API functions... 25 RBO.createObject()... 25 RBO.getProperty()...25 RBO.setProperty()... 26 RBO.callMethod()... 26 RBO.setError()... 27 RBO.getDBVals()...27 RBO.setDBVals()... 27 WW.FILEVAR.S... 28 Options for setting text with RBO.setMessage and RBO.setError... 28 Caching and storing file handles...29 Essentials to add to a BASIC subroutine... 29 Automatically calling subroutines...30 Status values returned from RBO function calls... 31 Chapter 5: Testing RBOs... 32 RBO debug logging...32 debug property... 32 debug_id property...33 Debug log information... 33 Manually invoking the RBO debug process... 34 RBO testing overview... 35 Accessing the RBOScope testing tool from Web Designer...35 Testing an RBO... 36 Accessing the stand-alone JSP RBOScope testing tool... 37 4

Contents Testing RBOs with the stand-alone JSP RBOScope testing tool... 37 Configuring the encoding of the JSP RBOScope testing tool...38 Chapter 6: RBO debug logging... 40 debug property... 40 debug_id property... 40 Debug log information... 41 Manually invoking the RBO debug process... 42 Chapter 7: Creating HTML documentation for RBOs... 43 Generating RBO HTML documentation...43 Chapter 8: Setting up remote procedure calls... 44 RPCs overview...44 Setting up RPCs... 44 Writing an RPC subroutine...45 Calling an RPC subroutine from Java or C#... 46 Part III: Using SB/XA with the Web Designer... 48 Chapter 9: Introduction to the Web DE-SB/XA interface...49 Compliant SB/XA processes and functions...49 Supported SB/XA server versions... 50 Compatibility of the COMMON block... 50 Web DE and SB/XA coexistence...51 Chapter 10: Using the Web DE-SB/XA interface...52 Enabling Web DE in an SB/XA account... 52 Setting up security associations...53 Properties and methods... 53 sbobject class... 54 User-defined method... 55 Chapter 11: Web DE subroutines for SB/XA access... 57 WW.SB.COMMON()... 57 WW.SB.PROCESS()... 60 Appendix A: Configuration files... 61 JavaScheduler.ini file... 61 Sections of the JavaScheduler.ini file...62 [LogLevel] section...62 [Default] section...63 [account] section... 64 rgw5.ini file...66 Sections of rgw5.ini file...67 [LogLevel] section...67 [Default] section...68 [accountname] section...69 5

Part I: 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. 6

Chapter 1: Introduction This document provides a complete step-by-step guide to installing and setting up U2 Web Development Environment. It contains steps for installing components of Web DE on Windows, UNIX, deploying the RedBack Object Server component to a UNIX or Windows computer, and copying RedBeans components to a UNIX computer. This document also provides instructions for installing two optional features: a RedPages COM Wrapper and a stand-alone JSP RBOScope testing tool. Additional topics include upgrading older U2 accounts to the Web DE 5.x architecture, and licensing and authorizing the product. 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 Java Scheduler RedBeans and RedPages.NET Web Designer 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. 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. 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. This suite of designer tools runs in an Eclipse development environment and provides an interface for designing RBOs. 7

Part II: RBOs and RPCs The following sections give an overview of RedBack objects (RBOs) and their function in web application design. These sections also include a description of Web DE remote procedure calls (RPCs), an alternative to using RBOs. RBOs The RBO information helps you with the basics of developing RBOs in the Eclipse-based U2 Web Designer, testing RBOs with the built-in RBOScope testing tool or the standalone JSP RBOScope testing tool, and developing server code for RBOs. For more information, see Application development with the RBO model, on page 9. RPCs You can use RPCs to call a UniVerse BASIC or UniBasic subroutine directly and receive a RecordSet. For more information, see Setting up remote procedure calls, on page 44. 8

Chapter 2: Application development with the RBO model RBOs represent the logical design of the application in an object-oriented environment. The best strategy is to design the RBOs and their structure based on the requirements of your application. It is recommend that you design and plan the RBO implementation to make use of inheritance, planning which classes provide which data and methods. The RBOs that you design and build provide an interface to your data and code. You create an object layer on top of what would normally not be viewed as an object environment. This means that your design follows object-oriented techniques rather than standard UniData or UniVerse development techniques. This is important because the RBOs will often be referenced by developers who do not understand UniData or UniVerse, or have any experience in multivalued data or UniBasic/UniVerse BASIC code. The following sections provide an overview of developing applications by using the RBO model. RedBack objects (RBOs) overview Web DE allows data access to a U2 database from a web application. You use RBOs to define that access. An RBO is a kind of data envelope that moves back and forth between the middleware and the U2 data server. It moves data to the U2 data server when you call a method from a middleware routine, and returns data to the calling routine when the method is completed on the U2 data server. Using RBOs allows support for a number of clients and middle tier interfaces while providing data abstraction and facilitating teamwork, giving you a fast and reliable data access layer. Web DE supplies some predefined classes that you can inherit and enhance in your own businessspecific object definitions. You can create and maintain your RBOs in the RBO perspective of Web Designer. In addition, the RBO perspective offers an editor tool for editing, compiling, and cataloging your UniBasic or UniVerse BASIC subroutines. You can test your RBOs by using the RBOScope testing tool that is included with Web DE. This tool allows you to test objects before you write your own middleware calling subroutines. RBO properties and methods RBOs have properties and methods. The properties are data and parameter placeholders, and the methods are aliases to subroutine calls. Some of these subroutines are included with Web DE, and others you write yourself. For example, you can create an RBO called Order by inheriting the stateless RBO (SLRBO) class that is included with Web DE. You then add properties, such as OrderID, Items, Qtys, CustomerName, Address, ErrorCode, and ErrorMessage, and methods, such as ReadOrder and WriteOrder, and create the subroutines that these methods reference. In this example, there are two types of properties: those that contain database data, and those such as ErrorCode and ErrorMessage that you use for communication from the UniBasic or UniVerse BASIC programs back to the calling routines in the middle tier. For example, if a program could not open a file or was not passed mandatory input, you want to report that information back to the calling subroutine. You can accomplish this only by using the properties of the RBO through which it was called. 9

Chapter 2: Application development with the RBO model RBO classes The RBO hierarchy is ordered by classes and subclasses. The following figure shows the hierarchy and each class and subclass. Figure 1: RBO hierarchy RBO class The RBO class is the superclass for all the RedBack object classes. Other RBO classes inherit from this class, and properties and methods can be added. With the RBO, you can create objects that you want to keep in a user s session by using the U2 data server. Web DE keeps the object data in the WWSTATE file. Keeping a handle to the object enables you to request the previously used object. Every method call flushes the data in the object to the record in WWSTATE. Every open, when using the previously stored handle from a cookie, hidden field, or variable, brings back the object with any data stored previously in the object, and is flushed to the database by a method call. Because of the input/ output overhead, you should use an RBO in place of an SLRBO only if you intend to make use of its statefulness. This object is stateful; a stateless, faster version of it is the SLRBO class. You typically use either the RBO or SLRBO to read or write a record. emailobject subclass emailobject is a subclass of RBO. It provides properties and methods to allow email messages to be sent from the RedBack Object Server. This object runs the unix_command or nt_command you supply, so you must verify that the command works on your RedBack Object Server or U2 data server. Remember that you can use an SLRBO to do the same thing, with your method subroutine actually running the mail command. Most web applications do not send email messages from the RedBack Object Server or U2 data server, but from the middle tier. However, you might find this object useful. SysInfo subclass SysInfo is a subclass of RBO. It provides properties and methods to obtain information about the operating system, database platform, and Web DE installation. uobject subclass uobject is a subclass of RBO. It provides properties and methods to facilitate access to UniData and UniVerse databases with prewritten UniBasic or UniVerse BASIC methods to auto-read and autowrite records. If you use this object in a stateful manner, the object can trigger a lock or optimistic concurrency control error that you can handle by writing a subroutine for the UpdateLockError 10

Session and state overview method. This object also has PostRead, PreWrite, and PostWrite methods for which you can write subroutines. If you have complex reads or writes to run, an SLRBO class is usually faster. uquery subclass uquery is a subclass of uobject. It provides properties and methods to enable you to run queries against UniData and UniVerse databases. A uquery object returns a RecordSet that you can scroll through, displaying fields from each row as you scroll. If you gather data using a single SELECT statement, you can use this object. Being a stateful object, it supports paging through the data without repeating the SELECT statement. If you cannot use a single SELECT statement to gather the data, you might want to use an SLRBO or RBO and return the records in delimited strings. sbobject subclass sbobject is a subclass of RBO. It is used to interact with SB+ applications. For information about accessing SB+ from Web DE, see Using SB/XA with the Web Designer, on page 48. SLRBO class The SLRBO class is a stateless RBO, the fastest RedBack object, which puts the least load on the RedBack Object Server or U2 data server. No state for the class is stored in the RedBack Object Server, unlike all other classes. The SLRBO can be useful if the application state is to be stored elsewhere, for example in the middle tier, or where the RBO does not actually require any state to be stored. Your application might require storage of session IDs for stateless RBOs to ensure that a request is valid and allowed. Session and state overview The main difference between designing applications for the web and designing applications for traditional host environments is the web's stateless nature. The web has no permanent connections. Web DE provides session and state concepts to overcome these limitations. For example, when you click a link or enter a URL in your web browser, a new connection is made to the target web server. The target web server runs a process or script. This process sends a web page back to your web browser, and then breaks the connection. If the web page contains images or other files, multiple connections are made to download these items. In these situations, your web browser makes, and breaks, multiple connections to the target web server. You are connected to the web server (and ultimately the RedBack Object Server) only while the request is made and resolved. For web pages that only publish information, the stateless nature of the web does not pose any major design issues. However, for transactional applications, the lack of a permanent connection means that you can no longer use some of the traditional functionality of BASIC applications, such as COMMON memory, in the same way. Sessions Because the web is stateless, there is no concept of logging on and logging off. These concepts translate in Web DE to the concept of session. A session is user information that defines a virtual connection. Because there is no permanent connection, a session consists of a series of requests between your web browser and the RedBack Object Server. Web DE maintains session information on the RedBack Object Server and in the data sent to and from your web browser. The session information maintained on the RedBack Object Server includes the 11

Chapter 2: Application development with the RBO model results of queries and lookups. The session information maintained on the web server identifies the user and the current session. The information used to identify the user includes the user's name, initial IP address, and the start time and date of the current session. Beginning a session When you make your first request from your web browser, the RedBack Object Server starts to maintain session information to identify you when you make subsequent requests. Unless the RBO subclass is SLRBO, the RedBack Object Server expects to see a session ID passed with each request. If the RedBack Object Server does not receive a session ID, the RedBack Object Server assumes this is the first request, and creates a session and a session ID. Each subsequent request should pass back that session ID, so that each request can be associated with the session. Both RedBeans and RedPages.NET provide methods to access and set the session ID. For more information see the Application Developer s Guide. Ending a session In Web DE, a session has a life. Whenever the RedBack Object Server receives a request from a web browser that does not contain any session information, it creates a new session. You cannot end a session, but you can start a new session. The session information maintained on the RedBack Object Server can remain there after a session life is complete. The RedBack Object Server automatically deletes session information on a periodic basis through the built-in garbage collection function. You can fine-tune garbage collection handling, if necessary. For more information, see the information about managing garbage collection in Administrator s Guide. Sessions and the RDBMS Because there are no permanent connections in web-based applications, fewer licenses are required for your relational database management system (RDBMS) than are required for traditional hostbased applications with the same number of users. There is no direct mapping between an end-user and an RDBMS license. An RDBMS license can process the requests of many users. State Traditional host-based applications that provide constant connections can store relevant application data in COMMON memory. The concept of COMMON memory translates in Web DE to the concept of state. As you progress through a Web DE-based application, the RedBack Object Server stores object state for RBO objects that are instantiated, with the exception of stateless RBOs (SLRBO or any of its subclasses). For example, if you select an RBO form from a menu, the RedBack Object Server maintains object state for that form, including all fields and any values that you enter. Within each object instance, the RedBack Object Server stores your unique session information. For example, if you create RBO A, enter data, and then create RBO B, at some point the application takes you back to RBO A, and the data is redisplayed in RBO A (stored in state). However, if you recreate RBO A at some point in the application, Web DE destroys any previous data state for RBO A. You cannot have multiple instances of the same object. The way in which your application navigates between objects is important because there is a difference between returning to and creating an object. With each request, the RedBack Object Server returns all current data for the object submitted to the RedBack Object Server and updates state. If you need to reference a previous object, you can store the handle to the object in either RBO state or client state (or both). 12

Understanding how session and state work together It is important that you preserve the current session ID outside of the RedBack Object Server by the tier that makes the RBO request. If RBO A has state that is not required by the other RBOs, part of your design process needs to decide whether this RBO could be subclassed from SLRBO and become stateless. Stateless RBOs do not have to store state within the RedBack Object Server. This may make sense if its state is not required at a later stage, or if the state is to be stored in a tier outside of the RedBack Object Server. A stateless RBO cannot access data from another RBO method. The RedBack Object Server engine must preserve the current RBO state, but a stateless RBO cannot have its state preserved. This is only applicable when calling methods on the RedBack Object Server. Understanding how session and state work together Web DE maintains state for every property that is defined in an RBO class definition. This state information is available to RedBack Object Server code through the server API functions. If the RBO is subclassed from SLRBO (a stateless RBO), this state is available only during the request and not afterward, because the RedBack Object Server does not preserve state beyond each request. For RBOs that are not stateless, the RedBack Object Server stores the state, and the state can be referenced by other RBOs. For this process to work, the RedBack Object Server must pass the session ID with every request. Without a session ID, the RedBack Object Server has no way of determining to which session the request belongs, and cannot reference state from that session's other RBO instances. The RedBack Object Server uses the session ID to validate a request and determine whether the session is still active. If you use stateless RBOs, you might want to implement your own form of session and state to validate that a user has logged in and has an active session. To call server code, you associate a cataloged UniVerse BASIC or UniBasic subroutine call with a method on an RBO. You can call a method from the client code or from the UniVerse BASIC or UniBasic code. Web DE associates each method with a class and interacts with an instance of that class. The method does not control the browser. By default, Web DE refreshes the current object for the initial method called with its current state. A method can create other instances of classes and interact with those instances' methods. Methods can also retrieve information from state for their own instance and other class instances if the handle to those instances is available and none of the RBOs involved are stateless. For example, assume that you write a UniVerse BASIC or UniBasic subroutine called ValSal that validates an employee salary. From your Employee RBO, you add a method called ValidateSalary and associate the ValSal subroutine with that method. The following figure shows the example of the ValSal subroutine in the Employee RBO. 13

Chapter 2: Application development with the RBO model Figure 2: Employee RBO When the client makes a request to call the method ValidateSalary, the RedBack Object Server engine makes a call to the ValSal subroutine. Each method uses one or more of the server API functions to interact with RBO State for its instance of the RBO class. For example, the ValSal subroutine looks at the salary entered, and then checks that the salary falls within the allowed salary ranges for the employee's department. The code creates an instance of the Department RBO and calls its CheckSalary method. If the salary is outside of the salary range, you want the browser to display an error message. Do not put business logic code, such as file opens, reads, calculations, and writes in your methods called directly through your RBOs. Instead, use your method subroutines to call business logic subroutines, receiving data and status or error messages. All RBO.getProperty and RBO.setProperty commands should be in the method subroutine that you call directly through the RBOs; none should be in the business logic subroutines. This makes testing and debugging of your business logic subroutines possible outside of Web DE. 14

Chapter 3: Developing RBOs The following sections provide information about using the RBO perspective of the Web Designer. Getting started with Web Designer After you install Web DE, you can develop RBOs in the Web Designer. The Web Designer has an intuitive user interface to help you design and modify RBOs quickly. The components of the Web Designer workspace are defined by the perspective that is selected. A perspective is a collection of views. The views in the RBO perspective of Web DE enable you to build, maintain, and test RBOs for your web application. 1. Open the Web Designer by clicking Start > All Programs > Rocket U2 > Web Development Environment > U2 Web Designer. 2. By default, the perspective opens to the RBO perspective. If the Web Designer does not open to this by default, select Window > Open Perspective > RBO Perspective. Developing RBOs Do the following tasks before you create or edit RBOs. These tasks are described in more detail in Administering U2 Web DE. Create a U2 server Connect to a U2 server Enable an account for U2 Web DE Create a module The following sections describe how to create RBOs in Web Designer. For information about how to test RBOs, see Testing RBOs, on page 32. Creating or editing RBOs You can create an RBO, edit an existing one, or create one from a U2 database file. The following sections describe each of these processes. To create an RBO in the Web Designer, follow the steps in Creating an RBO, on page 15. To edit an existing RBO, follow the steps in Editing an RBO, on page 19. To create an RBO from a U2 database file, follow the steps in Creating an RBO from a U2 database file, on page 20. Creating an RBO After you connect to a U2 server, enable an account for U2 Web DE, and create a module, you can create an RBO for the module. A module is a repository for all of the RBO class definitions that relate to a convenient grouping. The RBOs are therefore relevant to each module. 1. In the Web Designer, expand the U2 Web DE Elements tree, right-click a module, and select New RBO. 15

Chapter 3: Developing RBOs 2. In the Select Inheritance window, select the class from which the RBO inherits properties and methods, and click OK. There are two tabs available to view the available classes, the Hierarchy View and Flat View. Each view shows all of the possible superclasses, including system classes, classes in the SHARED module, and all classes in the current module that are not final classes. For more information about these types of classes, see RBO classes, on page 10. Note: RBOs cannot inherit from final classes; therefore, final classes are not displayed in the Select Inheritance window. RBOs can, however, inherit from system objects, but you cannot modify system objects. Custom-developed objects do not have the word SYSTEM next to their title, but they have the word SHARED next to their title if they were created in the SHARED module. You cannot add your own system objects. However, if you add a class to the SHARED module, classes in other modules can inherit from it. After you click OK, the new RBO appears in the RBO Editor in edit mode. The default name of the RBO is new. Inherited properties and methods are populated in the RBO Editor tabs, as shown in the following figure. Figure 3: New RBO 3. Add identifying information, as described in Entering identifying information for the new RBO, on page 17. 4. Add properties, as described in Defining properties of the RBO, on page 17. 5. Add methods, as described in Defining methods of the RBO, on page 19. 6. After you add properties and methods, click the Save icon or select File > Save, and enter a unique name for the new RBO. Web Designer stores the RBO definition in the U2 database. The following reserved names for RBOs must not be used for the user-defined RBOs: rbo sysinfo emailobject uobject 16

Entering identifying information for the new RBO sbobject uquery logon Note: The names are not case-sensitive. For example, you cannot have RBO and rbo, as they both will appear as rbo. Entering identifying information for the new RBO When you have a new RBO in edit mode, you must enter some identifying information such as a name and description to identify the object. 1. From the RBO Editor pane, in the field, enter a description to identify the RBO. 2. Click the ellipsis button (...) to enter a long description and to specify the group. The long description appears in the HTML documentation generated by the RBO HTML documentation tool. The long description can contain HTML tags that help the RBO HTML documentation tool display this description. For more information, see Creating HTML documentation for RBOs, on page 43. The Group field allows you to group RBOs for documentation purposes only. For example, if you have an RBO related to updating accounts, you could define a group as UpdateAccounts and assign it to each new RBO that is related to updating accounts. 3. If you want to prevent this class from being used as a superclass for any new classes, select the Final Class check box. Defining properties of the RBO In the Properties tab of the RBO Editor, you can create new properties or edit existing properties where allowed. 1. To the right of the Properties tab, click the Insert Row icon ( ). Note: If you insert a row that you no longer need, click the Delete Row icon ( ) to remove it. 2. In the Name cell of the new row, enter a name for the property that you are defining for the RBO. To change the name for a user-defined property, click the cell to enable edit mode. 3. In the Default Value cell, set the default value for the property, if applicable. The property must have Create (C) access to allow setting a default value. The value that you set here is assigned to the property by default when a user creates an instance of the RBO at run time. To change the default value at any point for a user-defined property, click the cell to enable edit mode. 4. In the Type cell, select a property type. Use the following table to decide which property type to choose. Table 2: Property types Type String mvstring Denotes that the value for the property is a string. Denotes that the value for the property is a string that contains multivalued data (U2 values, subvalues, or both). 17

Chapter 3: Developing RBOs Type File LogicalFile Ref mvref Field mvfield FieldNames Denotes that the value for the property is the name of a file. Denotes that the value for the property is the name of a logical file. This is the RBO object handle created by a BASIC method call on the server. From your BASIC code, you can store the object handle in an RBO property of type Ref. This handle is then used by client code, such as RedPages.NET code, to interact with the object. Denotes that the value for the property contains the names of a number of Refs. Denotes that the value for the property is a field from the UniData or UniVerse dictionary file defined for this RBO. The dict_file or logical_file property determines the dictionary for this RBO. Denotes that the value for the property is a field containing multivalued data from the UniData or dictionary file defined for this RBO. The dict_file or logical_file property determines the dictionary for this RBO. Denotes that the value of the property is a list of selected field names from the UniData or UniVerse dictionary file defined for this RBO. The dict_file or logical_file property determines the dictionary for this RBO. Note: The assignment of a property type is for documentation purposes. You can run the RBO HTML Documentation tool (detailed in Creating HTML documentation for RBOs, on page 43) from Web Designer and give the output to RedPages.NET or RedBeans developers so that they know whether to expect a string or some other type. Web Designer also uses the type internally to determine, for example, whether to display a field column for an RBO, depending on whether any of its properties are of the field type. 5. In the cell, click the ellipsis button (...) and enter a short and long description and a group, if applicable. 6. The Field cell is populated for the RBO if any of its properties are of the type Field. If the property type is Field or mvfield, select a database field name. Note: You must define either the dict_file property or logical_file property before fields become available to assign to properties of type Field. The fields in the selection list come from the dictionary specified in the dict_file or logical_file property. If both the dict_file and logical_file properties are defined, the logical_file property determines the dictionary fields and the dict_file property is ignored. 7. The Superclass cell displays the name of the class from which the property was inherited. The property s superclass cannot be changed. If you are defining a new property of the RBO, superclass is not applicable. 8. In the Access cell, select a setting to indicate whether the value of the property can be created at design time or can be read or written at run time. The default is CRW, which allows create, read, and write access. The following table describes each value. Table 3: Access values Value C Create. You can set a default value for the property at design time in the RBO Editor. This default value is assigned to the property when an object of this class is instantiated at run time. 18

Defining methods of the RBO Value R W Read. The value of the property can be read at run time using the RBO.getProperty() function call. Write. The value of the property can be set at run time using the RBO.setProperty() function call. Tip: You can sort a column by clicking the column heading. If you have large lists, performance can be improved by clicking the Disable drop lists icon ( ). Once disabled, the icon will change to have a red line through it, indicating that drop lists are disabled. Defining methods of the RBO In the Methods tab of the RBO Editor, you can create new methods or edit existing methods where allowed. 1. To the right of the Methods tab, click the Insert Row icon ( ). 2. In the Name cell of the new row, enter a name for the method you are defining for the RBO. To change the name for a user-defined property, click the cell to enable edit mode. 3. In the cell, click the ellipsis button (...) and enter a short and long description, and select the input and output properties. Input properties are the properties that you must set before calling this method, and output properties are the properties that will be set by the method. Setting these properties provides more information to the RedPages.NET or RedBeans programmers. 4. In the Cataloged Name cell, select the name of the BASIC subroutine that has been cataloged in the UniData or UniVerse database. Note: Do not define any parameters for subroutines that are intended to become methods. To pass arguments into a BASIC program, you use properties. Assign values to the required properties before calling the method and then 'get' the values of these properties once in the BASIC subroutine. 5. The Superclass cell displays the name of the class from which the method was inherited. The method s superclass cannot be changed. If you are defining a new method of the RBO, superclass is not applicable and input is disabled. 6. Select File > Save to save the new RBO with its added properties and methods. Editing an RBO You can edit an RBO that already exists in the Web Designer. 1. In the RBO List, U2 Resource, or RBO Hierarchy view, expand the U2 Web DE Elements tree and a module, and double-click an existing RBO to edit. Tip: Select Window > Show View > RBO Hierarchy to display all RBOs in a hierarchical structure. In this view, all objects supplied with Web Designer are marked SYSTEM to distinguish custom-developed object definitions from system-supplied objects. 2. Switch to edit mode by clicking the Lock icon ( ). For more information about why and how you must lock an RBO to edit it, Locking and unlocking an RBO, on page 20. 19

Chapter 3: Developing RBOs 3. Edit identifying information, as described in Entering identifying information for the new RBO, on page 17. 4. Edit properties, as described in Defining properties of the RBO, on page 17. 5. Edit methods, as described in Defining methods of the RBO, on page 19. 6. After you edit properties and methods, click the Save icon or select File > Save. 7. Click the Unlock icon ( ) to release the lock. Creating an RBO from a U2 database file After you connect to a U2 server and enable an account for Web DE, you can use the Database Files node to create an RBO from a U2 database file. 1. Expand an account and the Database Files node. 2. Right-click the name of the U2 database file that you want to use to create an RBO, and select Create RBO from selection. 3. In the Choose a parent module wizard, select the parent module to contain the new RBO, and click Next. 4. Select the RBO s superclass and in the RBO Name field, enter a unique name. Click Next. Note: The name is subject to the restrictions detailed in the last step of Creating an RBO, on page 15. 5. Select the check box next to the dictionary field definitions that you want to use as properties of the RBO. If you selected the Query RBO superclass on the previous wizard page, continue with the following substeps; otherwise proceed to step 6. a. Change the order of the selected items by dragging the fields to a different location above or below their current positions. Click Next. b. Select the fields to determine the sorting of your query results. You can drag the fields to different locations. 6. Click Finish. The RBO is added to the list of RBOs for the parent module that you selected in step 3. Deleting an RBO You can delete an RBO by using the Web Designer. If other objects inherit from an object that you delete, they become orphaned, and can be identified in the RBO Hierarchy view under the Orphaned Classes node. Note that an orphaned object cannot be instantiated. 1. In the RBO List, U2 Resource, or RBO Hierarchy view, right-click the RBO that you want to delete, and select Delete. 2. From the Delete RBO dialog box, click Yes. 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 20

Maintaining logical file definitions you close the object or unlock it. When you close the Web Designer, all open objects are closed, and their entries are removed from the WWLOCKS file. 1. From the RBO List, U2 Resource, or RBO Hierarchy view, right-click the name of an RBO and select Lock RBO. If using the U2 Resource view, you can also press Ctrl to select multiple RBOs to lock. Alternatively, a Lock icon ( ) is available on the toolbar. Note: You cannot lock an RBO that is already locked. You can only access a read-only version of the object definition. 2. Make any changes to the RBO by double-clicking it and editing the details. 3. To save the changes, select File > Save. 4. To unlock the RBO, right-click it and select Unlock RBO. Alternatively, an Unlock icon ( ) is available on the toolbar. Maintaining logical file definitions You can combine the field definitions from a number of physical files into a single logical file definition. This logical file definition is used during development and at run time as if it were a single physical file. You can specify the name of the logical file definition in the logical_file property of a uobject class definition. 1. Expand the U2 Web DE Elements tree, right-click a module, and select New Logical File. 2. From the New Logical File view, in the field, enter an appropriate description for the logical file. 3. If you are sure that the only way to update the primary file in the logical file definition is through the logical file, select the Lock Only Primary Item check box. If you select this check box, the RedBack Object Server locks only the primary file. If you do not select this check box, the RedBack Object Server locks each file that is defined in the logical file definition, which decreases performance. 4. Under Source Files, define the files that you want to include in the logical file definition: a. Click the Insert Row icon ( ). Note: The file on the first row is treated as the primary file in the logical file definition. To move the rows, drag them to the desired location. b. In the Source Files area, enter information for each physical file to be included in the logical view. The following table describes the source files. Table 4: Source files and descriptions File Dict File Data File Select the dictionary file from the Dict File list. If you define a dictionary file used to describe data from a file of a different name, you must also enter the data file name in the next column. Select the data file from the Data File list. 21

Chapter 3: Developing RBOs File Key Source Field MV Key Fields If a primary file, the field is not editable, as the primary file is not accessed through a key source file. The RedBack Object Server accesses the primary file by using the key data from the RBO class definition. As with other application objects, the key data passed to the read method describes a single physical item. For any physical file other than the primary file, enter the key source field. The RedBack Object Server uses the key source field to access the physical file. The value must be an existing field name in the collection of selected field names that you defined for the files above this one in the grid. The key source field name can refer to a physical location in a database item, or can be a virtual field that derives a value. For example, consider a file with a multivalued list of product numbers. The key to a second file can be made up of the key to the first file, an asterisk, and then the product number. You can create a virtual field formula to represent this. If a primary file, the field cannot have a multivalued key. For other physical files, if the data in the key source field is multivalued, you must click the cell to read Yes. Note: If the MV Key field is Yes, and the key value contains multiple entries, the RedBack Object Server reads each individual key value. In this way, the RedBack Object Server can read multiple physical records to construct multivalued fields in the logical record. Only a single value is taken from each physical item read. If the field is No, the RedBack Object Server performs a single read. Select the fields from the primary dictionary that you want to include in the logical file definition. Field names can refer to a physical location in a record, or can be virtual fields that derive a value. Note: Selected field names must be unique across the logical file definition. That is, you cannot select the CUSTOMER field from one file, and then another field called CUSTOMER from a second file. c. Continue inserting rows and entering information in the grid as necessary. As you enter rows, you can select a row, and then click the Insert Row icon to add the row below your currently selected one. 5. After you enter information for all physical files to be included in the logical file definition, click the Save icon or select File > Save, and enter a unique name for the new logical file. Creating a subroutine You can use the Web Designer code editor to create and edit the code for subroutines that are stored on the RedBack Object Server. Prerequisites Defining properties of the RBO, on page 17 Defining methods of the RBO, on page 19 Procedure 1. In the RBO List, U2 Resource, or RBO Hierarchy view, expand the U2 Web DE Elements tree and a module, and double-click an existing RBO to edit. 22

Editing a subroutine 2. Switch to edit mode by clicking the Lock icon ( ). For more information about why and how you must lock an RBO to edit it, Locking and unlocking an RBO, on page 20. 3. Click in the cell, and click the ellipsis button (...). 4. Set the Input Properties and Output Properties of the subroutine as appropriate. Click OK. 5. Click in the Cataloged Name cell of the method for which you are creating a subroutine. 6. Type a descriptive name for the new subroutine or select a name from the list. This subroutine is the BASIC program that is run when the RBO method call is made. In the following example, a cataloged program called Validate runs when RedPages.NET or RedBeans code calls the PostRead method. Figure 4: Validate cataloged program 7. Click the Edit Basic Source Code icon ( ). 8. On the tab that opens, add code to the basic source code as required. Web Designer automatically inserts comments into the code page based on the entries you make. Web Designer automatically inserts a $INCLUDE statement to the code listing. Web Designer provides a template text file, Includetemplate.txt, in the directory in which the product was installed. Modifying this template determines the contents that appear when creating a subroutine. 9. When finished, click the Compile U2 BASIC Subroutine for Method ( ) icon. This action saves, compiles, and catalogs the UniVerse BASIC or UniBasic subroutine on the RedBack Object Server. Note: The RBO Editor compiles the subroutine in Pick flavor and directly catalogs the subroutine. You might want to add a compile directive in your program to override this default and manually recatalog the program from the command line prompt. Editing a subroutine You can edit an existing subroutine by using the code editor. Prerequisites Defining properties of the RBO, on page 17 23

Chapter 3: Developing RBOs Defining methods of the RBO, on page 19 Creating a subroutine, on page 22 Procedure 1. In the RBO List, U2 Resource, or RBO Hierarchy view, expand the U2 Web DE Elements tree and a module, and double-click an existing RBO to edit. 2. Switch to edit mode by clicking the Lock icon ( ). For more information about why and how you must lock an RBO to edit it, Locking and unlocking an RBO, on page 20. 3. In the Cataloged Name column, click the name of the subroutine you want to edit. 4. Click the Edit Basic Source Code icon ( ). 5. On the tab that opens, edit code to the basic source code as needed. 6. When finished, click the Compile U2 BASIC Subroutine for Method ( ) icon. This action saves, compiles, and catalogs the UniVerse BASIC or UniBasic subroutine on the RedBack Object Server. 24

Chapter 4: Developing server code for RBOs The following sections provide an overview of developing server side basic subroutines. Developing RBOs involves specifying the contents of a subroutine to gain access to the properties, and then setting properties to return to the calling client application, invoking business logic code. This interaction with the RBO structure is achieved by calling RBO API function. Server API functions The following sections describe the server API functions. RBO.createObject() Syntax Status = RBO.createObject(className, handle) The RBO.createObject function creates an instance of the class you specify and returns a handle to the object created. If an error occurs, the function passes the error back to that Status. If no error occurs, the function sets Status to 0 or RBO.NO.ERROR. Status = RBO.createObject("Department", depthandle) IF Status # RBO.NO.ERROR THEN (error in creating instance) When you have a handle to the instance, in this case depthandle, you can access properties and methods of that class. Note: The classname must be the RBO name and not the module:rbo name. You can only reference RBOs within the same class in this manner. You cannot create an SLRBO from UniBasic or UniVerse BASIC because it is stateless. RBO.getProperty() Syntax Status = RBO.getProperty(handle, propname, value) The RBO.getProperty function returns the value of a property that you specify for the object referenced by handle. If the property is from the current object from which Web DE calls this method, you do not pass anything in handle. If an error occurs, the function passes the error back to Status. If no error occurs, the function sets Status to RBO.NO.ERROR. 25

Chapter 4: Developing server code for RBOs In the following example, the RBO.getProperty function returns the current salary in the argument value. If an error occurs, the RedBack Object Server sets Status to the appropriate error value. Status = RBO.getProperty('', "Salary", value) In the following example, RBO.setProperty gets the value of the property SalaryStatus that exists in the OFFICE:Department RBO, using the current instance of the class referenced by depthandle. Status = RBO.getProperty(deptHandle, 'SalaryStatus', value) RBO.setProperty() Syntax Status = RBO.setProperty(handle, propname, value) The RBO.setProperty function sets the value of a property that you specify for the object referenced by handle. If the property is from the current object from which the method is called, you do not pass anything in handle. If an error occurs, the function passes the error back to Status. If no error occurs, the function sets Status to RBO.NO.ERROR. The following example sets the value of the ServerStatus property to 1. Status = RBO.setProperty('', 'ServerStatus', 1) RBO.callMethod() Syntax Status = RBO.callMethod(handle, methodname) The RBO.callMethod function calls the method that you specify for the object referenced by handle. If the method is from the current object, you do not pass anything in handle. If an error occurs, the function passes the error back to Status. If no error occurs, the function sets Status RBO.NO.ERROR. The following example calls the CheckSalary method in the class referenced by the depthandle handle. Status = RBO.callMethod(deptHandle, 'CheckSalary') 26

RBO.setError() RBO.setError() Syntax RBO.setError(text) The RBO.setError function sets the error message that is passed back to the client for display purposes. The following example sets the error message to the text string that you specify. RBO.setError("U1") RBO.getDBVals() Syntax Status = RBO.getDBVals(names, values) The RBO.getDBVals function enables you to retrieve the field values that are received from the U2 data server before assigning them to the associated property of an RBO. You can call GetDBVals only from a postread, prewrite, or postwrite method, and you can use only valid database field names (not RBO property names). You can retrieve multiple property names, delimited by @AM. RBO.setDBVals() Syntax RBO.setDBVals(names, values) The RBO.setDBVals function enables you to manipulate field values that are received from the U2 data server before assigning those values to the associated property value of an RBO. You can call setdbvals from only a postread, prewrite or postwrite method, and you can use only valid field names (not RBO property names). You can set multiple property names, delimited by @AM. STATUS = RBO.setDBVals( EMP.ID, EMPID); 27

Chapter 4: Developing server code for RBOs WW.FILEVAR.S Syntax WW.FILEVAR.S(fname, mode, f.var, err) The WW.FILEVAR.S subroutine opens and closes files, and maintains the list of open file names and associated file handles. This subroutine provides additional error handling options and a logical close operation, which is not supported by the WW.OPEN.FILE function. The following table describes the parameters. Table 5: WW.FILEVAR.S parameters Parameter fname mode The name of the file to open or close. -1 clears the file handle secondary cache. 0 Opens the file and reports and errors 1 Opens the file, but does not report errors 2 Closes the file 3 Forces the file to open 4 Forces the file to open, but does not report any errors 5 Invalidates cache entry for fname A forced open means that Web DE ignores any existing handle for the file. Web DE effectively closes the file, and then opens it. Forcing a file to open is useful for opening remote file pointer items. f.var The file variable if mode is 0, 1, 3, or 4. err The file operation was successful. 1 The file operation failed. Options for setting text with RBO.setMessage and RBO.setError You can set the text for RBO.setMessage and RBO.setError by using the following syntax. ERROR message displays error messages as specified in message, which can have one of the following formats: n where n is an attribute in item ERRORS in WWTEXT. Un where n is an attribute in item ERRORS in SHAREDTEXT or in xxtext. string where string is the text to display. n:vm:data1:vm:data2:vm... 28

Caching and storing file handles where n is attribute n in item ERRORS in the file WWTEXT, substituting <1> with data1, <2> with data2, and so on. Un:VM:data1:VM:data2:VM where n is attribute n in item ERRORS in the file. SHAREDTEXT or xxtext, substituting <1> with data1, <2> with data2, and so forth. Note: When an error condition occurs, all subsequent server event handling ceases. To send back application status and messages, use the appropriate properties within the RBO. Caching and storing file handles You can reduce the number of times Web DE needs to open files by caching or storing file handles. You can write a subroutine that opens files and stores their handles in COMMON, and call the subroutine on connection start. You can also use the file open API, WW.FILEVAR.S, which returns a handle of the file that you open. This handle comes from the file cache. Be aware that using the WW.FILEVAR.S subroutine has implications of logical file opens on the application. For example, consider the following sequence of events: 1. You write a program to process a list of files. For each file name in a list, the program creates a remote file pointer (Q-Pointer) called QFILE and writes it to the VOC file. The program now calls WW.FILEVAR.S to open the file. The program returns the file handle and the name 'QFILE' is stored in the cache of 'open file names'. 2. A problem now exists. If you call WW.FILEVAR.S by using mode 0 or 1, each call after the first call returns the file handle of the first file. This is because the same file name is being used for different files. In this type of situation, the file handle cache should not be searched when requesting a file open action. Use of modes 3 or 4 would give the required result. The implication of the preceding example is that applications should not reuse file names unless you open the file by using mode 3 or 4. For file opens in your application that are called from RBO methods, the WW.FILEVAR.S function might not be relevant. It might be more appropriate to use existing code and call it during a connection startup. Essentials to add to a BASIC subroutine Every UniVerse BASIC or UniBasic subroutine should include the following statement to ensure that you have access to property names, which makes your code and error status codes easier to read: $INCLUDE WWINSERT RBO.H Example The following example illustrates a method that is called from an RBO subroutine to validate a salary. It gets the current value for the Salary and Department properties, and then calls the CheckSalary method in the OFFICE:Department RBO. SUBROUTINE ValSal * called to validate salary as the ValidateSalary method from OFFICE:Employee * $INCLUDE WWINSERT RBO.H $INCLUDE WWINSERT STD.H * 29

Chapter 4: Developing server code for RBOs * now get the salary entered Status = RBO.getProperty('', 'Salary', SALARYVALUE) IF Status # RBO.NO.ERROR THEN Status = RBO.setError("CANNOT GET SALARY") RETURN END * now get the department entered Status = RBO.getProperty('', 'Department', DEPTVALUE) IF Status # RBO.NO.ERROR THEN Status = RBO.setError("CANNOT GET DEPARTMENT") RETURN END * * now check if we have an instance to the department RBO and if not then create one Status = RBO.getProperty('', 'depobj', DEPTHANDLE) IF Status # RBO.NO.ERROR THEN Status = RBO.setError("CANNOT GET DEPARTMENT HANDLE") RETURN END * IF DEPTHANDLE = "" THEN Status = RBO.createObject("Department", DEPTHANDLE) IF Status = RBO.NO.ERROR THEN Status = RBO.setProperty('', 'depobj', DEPTHANDLE) ; * set handle for subsequent calls IF Status # RBO.NO.ERROR THEN Status = RBO.setError("CANNOT SET DEPARTMENT HANDLE") RETURN END END ELSE RETURN END * * now set the salary value and call the check salary method in department instance RBO.setProperty(DEPTHANDLE, "Salary", SALARYVALUE) * now set the current department for this employee RBO.setProperty(DEPTHANDLE, "CheckDept", DEPTVALUE) * now check the salary RBO.callMethod(DEPTHANDLE, "CheckSalary") * now check the status RBO.getProperty(DEPTHANDLE, "SalaryStatus", SALSTATUS) IF SALSTATUS = 0 THEN ; * ok so leave RETURN END * if here then salary is not ok! Status = RBO.setProperty('', "ServerStatus", SALSTATUS) Status = RBO.setError("INVALID SALARY ENTERED") RETURN Automatically calling subroutines You can call specific subroutines for a variety of session actions. To do this, specify the subroutines that you want to call in the SESSION.EVENTHANDLERS item in the WWCONTROL file. All Web DEenabled U2 accounts share the WWCONTROL file. The fields of the SESSION.EVENTHANDLERS item are as described in the following table. 30

Status values returned from RBO function calls Table 6: RBO function status values Field Att1 Att2 Att3 Att4 Att5 Att6 Reserved. Reserved. Reserved. Reserved. Subroutine to call on connection start (applicable only when WWCONTROL is used). Subroutine to call on connection stop (applicable only when WWCONTROL is used). Status values returned from RBO function calls The following table describes the Status values returned by RBO functions. These values are equated in WWINSERT RBO.H. Table 7: RBO function status values Function RBO.NO.ERROR RBO.BAD.ARRAYSIZE RBO.BAD.OBJECT RBO.BAD.CLASS RBO.BAD.PROPNAME RBO.BAD.PERMS RBO.ERROR No errors occurred. Invalid parameter array size. Object not found. Class not found. Property not found. Permission denied. Generic error code. 31

Chapter 5: Testing RBOs This chapter provides an overview of using the RBOScope testing tool to test RBOs. Web DE provides two versions of the RBOScope testing tool: Accessing the RBOScope testing tool from Web Designer, on page 35 Accessing the stand-alone JSP RBOScope testing tool, on page 37 RBO debug logging You can use RBO debug logging to track values of RBO properties between method calls, as well as profile the time taken to run a method. Web DE provides a way to automatically log property values as well as profile method execution times, but you can also do this manually. Two properties of the default RBO class, debug and debug_id, provide debug logging capabilities; these properties are inherited by every class. The RBO uquery class also logs the actual UniBasic or UniVerse BASIC SELECT verb that the RedBack Object Server uses to perform a selection. debug property The debug property is of type String. You can set the debug flag, which is used to automatically call the RedBack Object Server internal debug logging program from a method. The RedBack Object Server places all debug information in the WWLOG file located in the rbdefn account. The debug flag can contain one of three values: 0: indicates do not log 1: indicates to log start and finish times only 2: indicates to log start and finish times, as well as RBO property values The debug property has access codes of RW. The format of the debug file is shown in the following example: 001 RBO Debug 002 RBO Object Name 003 RBO Method Name 004 Session ID 005 Start timedate 006 Finish timedate 007 Start timedate 008 property1=value1 009 property2=value2 00n 00n property=value 00n Finish timedate 00n property1=value1 00n property2=value2 00n 00n property=value 32

debug_id property debug_id property The debug_id property is of type String, and allows you to specify the name of the debug log item the RedBack Object Server writes to the WWLOG file. If you do not specify a value, the key has the format of classname.methodname.sessionid. Otherwise, the RedBack Object Server saves the item as debug_id.value.methodname. The following is an example item list from the WWLOG file: LIST WWLOG 19:14:53 MAR 28 2001 1 WWLOG... debug_test.readdata Employee.Clear.12141 Employee.ReadData.12141 3 records listed Debug log information The RedBack Object Server saves all debug information to items in the WWLOG file. This file is a directory type file, allowing convenient access at the operating system level. The RedBack Object Server saves all items in the format of classname.methodname.sessionid, unless you specify otherwise in the debug_id property. Note: Be sure to monitor the size of the items in the WWLOG file and clear items as required. The following partial listing illustrates debug information obtained from a ReadData method call on the Employee RBO, with the debug property flag set to 2. This setting shows the start and finish times of the method call, as well as the property values at the start and finish times: RBO Debug Employee ReadData 18:57:32 Mar 28 2001 18:57:33 Mar 28 2001 18:57:32 Mar 28 2001 EmpId=1006 debug=2 FirstName= LastName= ImageFile= Salary= HireDate= Interests= Dept= dict_file=employees data_file=employees DeptCodes= DeptDescs=... 18:57:33 Mar 28 2001 EmpId=1006 debug=2 FirstName=Mario LastName=Delas ImageFile=emp_mario_delas.jpg Salary=990.00 33

Chapter 5: Testing RBOs HireDate=05/08/1998 Interests=Music Dept=3 dict_file=employees data_file=employees DeptCodes= DeptDescs=... Web DE also logs debug information to the COMO files. This information is a summary of the items saved to the WWLOG file; it includes the name of the item, the debug flag used, and the start and finish times for the method called. The following example illustrates a COMO file listing the debug information: COMO UO.SPIDER_393310 established 15:21:39 19 Nov 2010 WW.RBO.DEBUG: Employee.ReadData.12141-2 - 18:57:32 Nov 19 2010 WW.RBO.DEBUG: Employee.ReadData.12141-4 - 18:57:33 Nov 19 2010 Manually invoking the RBO debug process Although Web DE provides functionality to automatically log property values as well as profile method execution times, you can also directly call the Web DE debug subroutine from your own methods. This enables you to specifically debug isolated sections of your method. Web DE saves all debug information to the WWLOG file and summaries to the COMO file. Use the following call to manually invoke RBO debugging within a method: CALL WW.RBO.DEBUG(RBO.DBG.FLAG) where RBO.DBG.FLAG has four options: 1: Log method started 2: Log method started and includes RBO s properties 3: Log method completed 4: Log method completed and includes RBO s properties The following example illustrates a user method that calls to WW.RBO.DEBUG with options 2 and 4. It starts and completes log properties. SUBROUTINE RBO.TEST2 * $INCLUDE WWINSERT STD.H $INCLUDE WWINSERT SB.COMMON * Log method started CALL WW.RBO.DEBUG('2') * Body of Method CALL WW.SB.COMMON(1, ERR) USERDATA(1) = "UserData1!" CALL WW.SB.COMMON(4:AM:6, ERR) * Log method completed CALL WW.RBO.DEBUG('4') * RETURN * END 34

RBO testing overview RBO testing overview The RedBack Object Server processes method calls on objects on request. Using this messaging system, Web DE provides an RBO testing tool that you use to test your RBOs in isolation, without the need to build an application by using a RedBeans or RedPages.NET form. Testing your method calls with the RBOScope testing tool provides a mechanism for isolating problems. If there is a problem when calling a method from a RedBeans or RedPages.NET form, but the method call works from the RBOScope testing tool, the problem points to the client code rather than the RBO or the RedBack Object Server code. The RBOScope testing tool exercises the RBO in the same way that a Java program would if running on the client. It uses a live RedBack object from the RedBeans.jar API and requires a valid setting in the rgw5.ini configuration file. An Eclipse-based version of the RBOScope testing tool is built into Web Designer. Using this tool, you can test RBOs from within Web Designer. A JSP version of the RBOScope testing tool is also available in Web DE. Using this tool, developers can test RBOs without accessing Web Designer. Accessing the RBOScope testing tool from Web Designer The RBOScope testing tool is a view within Web Designer. In this view, you can test your RBOs without leaving the development environment. When you open the RBOScope testing tool in Web Designer, Web Designer uses the user ID and password you entered in the User Credentials window of the RedBack Object Server Connection wizard to access the RedBack Object Server. If your connection times out, right-click the connection in the U2 Resource view and select Refresh. 1. To open the RBOScope testing tool, select Window > Show View > RBOScope Testing Tool. 35

Chapter 5: Testing RBOs 2. From the RBO List, U2 Resource, or RBO Hierarchy view, right-click the name of the RBO you want to test, and click Test RBO. Figure 5: RBOScope testing tool Testing an RBO 1. To open the RBOScope testing tool, select Window > Show View > RBOScope Testing Tool. 2. In the RBO List, U2 Resource, or RBO Hierarchy view, right-click the RBO you want to test, and select Test RBO. You can also click the RBOScope Testing Tool icon ( ). Tip: You can double-click the view to maximize it so you can work in the RBOScope testing tool easier, as shown in the following figure. 3. Next to the property that you want to include in the method, enter a value in the Value column. 4. From the Methods list, click the link provided for the method name that you want to test. The RBOScope testing tool passes the values to the method, and then displays the current values for the RBO properties. If the method call affected any of the RBO s properties, the updated values are displayed in the Value column. 5. To monitor the performance of method calls to the RBO, click Start Performance Monitor. This opens a table that collects timing results for the methods you test. 6. To switch to a different RBO, select the RBO that you want to test from the RBO Quick Changer list. 36

Accessing the stand-alone JSP RBOScope testing tool The Open in new tab check box is selected by default. With this check box selected, the tab for the current RBO remains, and the selected RBO opens in a new tab. If you want the selected RBO to replace the current RBO in the same tab, clear the check box. To test an RBO outside of Web Designer, see Testing RBOs with the stand-alone JSP RBOScope testing tool, on page 37. Accessing the stand-alone JSP RBOScope testing tool You can use the stand-alone JSP RBOScope testing tool to test RBOs outside the development environment. Prerequisites Installing the JSP RBOScope testing tool in Installation and Configuration. Procedure 1. Open a web browser. 2. In the web browser, navigate to http://localhost:8080/rboscope, which redirects the browser to: http://localhost:8080/rboscope/rboscopelogin.jsp Note: The URL used to navigate to the stand-alone JSP RBOScope testing tool can be different depending on your installation. These steps assume you have chosen the default paths during installation. 3. Select an account, enter the credentials, and then click Connect. The account list is populated with accounts from the rgw5.ini file. The default user name of the administrator is rbadmin and the default password is redback. Testing RBOs with the stand-alone JSP RBOScope testing tool After you access the JSP RBOScope testing tool, you can use it to test RBOs outside of Web Designer. Prerequisites Accessing the stand-alone JSP RBOScope testing tool, on page 37 Procedure 1. From the Module Name droplist, select a module that contains the RBO to test. 37

Chapter 5: Testing RBOs 2. From the Class Name droplist, select an RBO to test. The selected RBO is displayed in the RBO testing grid. Figure 6: JSP RBOScope testing tool 3. In the New Value To Set column, enter a value for the property. 4. From the Methods list, click the link for the method name that you want to test. Configuring the encoding of the JSP RBOScope testing tool You can configure how the JSP RBOScope testing tool handles encoding by updating the rgw5.ini file. When configured to a specific encoding type, the JSP RBOScope testing tool will support any session encoding and display the information correctly. 1. Open the rgw5.ini file in a text editor. 2. In the [accountname] section, add the following: encoding=type, where type is the encoding type. For example, UTF-8, or ISO 8859-1. 38

Configuring the encoding of the JSP RBOScope testing tool 3. Save and close the file. 39

Chapter 6: RBO debug logging You can use RBO debug logging to track values of RBO properties between method calls, as well as profile the time taken to run a method. Web DE provides a way to automatically log property values as well as profile method execution times, but you can also do this manually. Two properties of the default RBO class, debug and debug_id, provide debug logging capabilities; these properties are inherited by every class. The RBO uquery class also logs the actual UniBasic or UniVerse BASIC SELECT verb that the RedBack Object Server uses to perform a selection. debug property The debug property is of type String. You can set the debug flag, which is used to automatically call the RedBack Object Server internal debug logging program from a method. The RedBack Object Server places all debug information in the WWLOG file located in the rbdefn account. The debug flag can contain one of three values: 0: indicates do not log 1: indicates to log start and finish times only 2: indicates to log start and finish times, as well as RBO property values The debug property has access codes of RW. The format of the debug file is shown in the following example: 001 RBO Debug 002 RBO Object Name 003 RBO Method Name 004 Session ID 005 Start timedate 006 Finish timedate 007 Start timedate 008 property1=value1 009 property2=value2 00n 00n property=value 00n Finish timedate 00n property1=value1 00n property2=value2 00n 00n property=value debug_id property The debug_id property is of type String, and allows you to specify the name of the debug log item the RedBack Object Server writes to the WWLOG file. If you do not specify a value, the key has the format of classname.methodname.sessionid. Otherwise, the RedBack Object Server saves the item as debug_id.value.methodname. The following is an example item list from the WWLOG file: LIST WWLOG 19:14:53 MAR 28 2001 1 WWLOG... debug_test.readdata Employee.Clear.12141 40

Debug log information Employee.ReadData.12141 3 records listed Debug log information The RedBack Object Server saves all debug information to items in the WWLOG file. This file is a directory type file, allowing convenient access at the operating system level. The RedBack Object Server saves all items in the format of classname.methodname.sessionid, unless you specify otherwise in the debug_id property. Note: Be sure to monitor the size of the items in the WWLOG file and clear items as required. The following partial listing illustrates debug information obtained from a ReadData method call on the Employee RBO, with the debug property flag set to 2. This setting shows the start and finish times of the method call, as well as the property values at the start and finish times: RBO Debug Employee ReadData 18:57:32 Mar 28 2001 18:57:33 Mar 28 2001 18:57:32 Mar 28 2001 EmpId=1006 debug=2 FirstName= LastName= ImageFile= Salary= HireDate= Interests= Dept= dict_file=employees data_file=employees DeptCodes= DeptDescs=... 18:57:33 Mar 28 2001 EmpId=1006 debug=2 FirstName=Mario LastName=Delas ImageFile=emp_mario_delas.jpg Salary=990.00 HireDate=05/08/1998 Interests=Music Dept=3 dict_file=employees data_file=employees DeptCodes= DeptDescs=... Web DE also logs debug information to the COMO files. This information is a summary of the items saved to the WWLOG file; it includes the name of the item, the debug flag used, and the start and finish times for the method called. 41

Chapter 6: RBO debug logging The following example illustrates a COMO file listing the debug information: COMO UO.SPIDER_393310 established 15:21:39 19 Nov 2010 WW.RBO.DEBUG: Employee.ReadData.12141-2 - 18:57:32 Nov 19 2010 WW.RBO.DEBUG: Employee.ReadData.12141-4 - 18:57:33 Nov 19 2010 Manually invoking the RBO debug process Although Web DE provides functionality to automatically log property values as well as profile method execution times, you can also directly call the Web DE debug subroutine from your own methods. This enables you to specifically debug isolated sections of your method. Web DE saves all debug information to the WWLOG file and summaries to the COMO file. Use the following call to manually invoke RBO debugging within a method: CALL WW.RBO.DEBUG(RBO.DBG.FLAG) where RBO.DBG.FLAG has four options: 1: Log method started 2: Log method started and includes RBO s properties 3: Log method completed 4: Log method completed and includes RBO s properties The following example illustrates a user method that calls to WW.RBO.DEBUG with options 2 and 4. It starts and completes log properties. SUBROUTINE RBO.TEST2 * $INCLUDE WWINSERT STD.H $INCLUDE WWINSERT SB.COMMON * Log method started CALL WW.RBO.DEBUG('2') * Body of Method CALL WW.SB.COMMON(1, ERR) USERDATA(1) = "UserData1!" CALL WW.SB.COMMON(4:AM:6, ERR) * Log method completed CALL WW.RBO.DEBUG('4') * RETURN * END 42

Chapter 7: Creating HTML documentation for RBOs An automatic documentation tool is available from the Tools menu in Web Designer. This tool parses all class definitions for all RBOs in a module and produces HTML pages that show the inheritance, properties, and methods of each class in the module. An example of the HTML documentation is available in your installation directory in the U2 account server. For example, /U2/U2WDE520/UVserver/rbexamples. This location contains a Documenta000 folder that contains all the HTML files for modules, classes, and more that the rbexamples account uses. The index-all.html file organizes all these.html files for you. When you generate your own HTML documentation, the files will be similar but placed in a location of your choosing. Generating RBO HTML documentation To generate RBO HTML documentation, make sure that a Web DE-enabled U2 account is connected to the RedBack Object Server, and any changes to the RBOs are saved. For information about how to edit RBOs, see Developing RBOs, on page 15. 1. From the U2 Resource view, select a module for which you want to generate HTML documentation. 2. Select Tools > Generate RBO HTML Documentation. 3. In the Generate RBO HTML Documentation window, enter the name of the host directory where you want the tool to store the generated HTML documentation, and click OK. 43

Chapter 8: Setting up remote procedure calls The following sections describe Web DE remote procedure calls (RPCs), an alternative to using RBOs. You can use RPCs to call a UniVerse BASIC or UniBasic subroutine directly and receive a RecordSet. RPCs overview The RPC protocol is an alternative to using RBOs. Web DE RPC allows you to call a UniVerse BASIC or UniBasic subroutine directly from the web. You might want to use Web DE RPC for the following reasons: To replace existing middleware that works in the same way, minimizing the changes necessary to implement Web DE. For maximum performance when generating reports that return a large number of records. To receive a RecordSet back from a UniVerse BASIC or UniBasic subroutine, where a uquery select cannot gather the data, and you do not want to use an SLRBO to return delimited strings that represent records. The result of an RPC request is a RecordSet in ASP.NET or Java. A disadvantage of using RPCs is that they provide less data abstraction than RBOs. Note: Web DE RPCs are stateless. If session state is required, you must maintain it in some part of your application outside of Web DE. Setting up RPCs To set up an RPC, you must create a pointer. Procedure 1. Enable the UniData or UniVerse account for RPC access. 2. Log on to the account as the RedBack user. 3. Create a pointer as follows: If the account is a UniVerse account, create an F-pointer in the VOC file to WWPROGS in the rbdefn account. If the account is a UniData account, create a DIR-type item in the VOC file pointing to WWPROGS in the rbdefn account. 4. Enter the following command: Results :RUN WWPROGS ENABLE.RBO The WW.RPC program reads the first parameter in your request, which indicates which subroutine to call. After calling the subroutine, the program passes your second and third parameters as the first and second parameters to your subroutine. Web DE uses a third parameter to receive the attribute mark-delimited list of data from the subroutine. The RedBack client components convert this attribute mark-delimited list of data into the appropriate record and set of records for the calling program. 44

Writing an RPC subroutine Web DE checks for the first repeating name in the list to determine where to break the returning list of data into records. For example, assume the program returns the following string: FIRSTNAME=BOB@AMLASTNAME=SMITH@AMFIRSTNAME=JOHN@AMLASTNAME=DOE Web DE locates FIRSTNAME, and breaks the string into two records, each with two fields, FIRSTNAME and LASTNAME. Writing an RPC subroutine The following sections describe the server API functions. An RPC subroutine must conform to the following requirements: Have three parameters: two input and one output. Cannot process screen input, as this causes the RPC call to hang. Processing of the RPC must finish in less time than it takes for the web request to time out. Must return the third parameter response as attribute markdelimited name=value pairs, as shown in the following example: FNAME=BOB@AMLASTNAME=SMITH@AMFNAME=JOHN@AMLASTNAME=DOE Example Web DE includes an example RPC subroutine, EMP.RPC, in the EXMODLIB directory of the rbexamples account. The following example shows a simplified version of the source code: SUBROUTINE EMP.RPC(PARAMS, RECORD, RESPONSE) *Note we are using PARAMS to get our input (we could also have used RECORD) *We are using RESPONSE to return an @AM delimited string of name=value pairs PROG.ID = EMP.RPC METHOD = PARAMS<1> FNAME = PARAMS<2> ID = PARAMS<3> STATUS = 0 MESG = RESPONSE = BEGIN CASE CASE METHOD = READ ; GOSUB 1000 CASE METHOD = SELECT ; GOSUB 5000 END CASE RESPONSE<-1> = SERVERSTATUS= :STATUS RESPONSE<-1> = SERVERMESSAGE= :MESG RETURN *********************** * Read a Record *********************** 1000* OPEN,FNAME TO F.FILE THEN READ RECORD FROM F.FILE,ID THEN GOSUB 1500 ;* Format Record Set END ELSE STATUS = 1 MESG = ID: NOT FOUND! END END ELSE STATUS = 1 45

Chapter 8: Setting up remote procedure calls MESG = FNAME: NOT OPENED! END * RETURN *********************** * Format Record Set *********************** 1500* RESPONSE<-1> = EMPID= :ID RESPONSE<-1> = FIRSTNAME= :RECORD<1> RESPONSE<-1> = LASTNAME= :RECORD<2> RESPONSE<-1> = DOB= :OCONV(RECORD<3>, D4/ ) RESPONSE<-1> = HIREDATE= :OCONV(RECORD<4>, D4/ ) RESPONSE<-1> = SALARY= :OCONV(RECORD<5>, MR22 ) RESPONSE<-1> = DEPT= :RECORD<6> RESPONSE<-1> = EXEMPT= :RECORD<7> RESPONSE<-1> = INTERESTS= :RECORD<8> RESPONSE<-1> = IMAGEFILE= :RECORD<9> * RETURN * Select a File *********************** 5000* PAGESIZE = PARAMS<4> PAGENO = PARAMS<5> OPEN,FNAME TO F.FILE THEN EXECUTE SSELECT :FNAME COUNT = 0 RESPONSE = PAGESIZE= :PAGESIZE LOOP READNEXT ID ELSE ID = @AM UNTIL ID = @AM DO IF INT(COUNT / PAGESIZE) + 1 = PAGENO THEN READ RECORD FROM F.FILE,ID THEN GOSUB 1500 ;* Format Record Set END END COUNT = COUNT+1 REPEAT RESPONSE<-1> = COUNT= :COUNT END ELSE STATUS = 1 MESG = FNAME: NOT OPENED! END * RETURN END Calling an RPC subroutine from Java or C# You can call an RPC subroutine from Java or C# using the RedObject.CallRPC API call. For more information about using Java or C# with Web DE, see the Application Developer s Guide. Example The following example illustrates a Web DE RPC subroutine from Java or C#. Connection oconn = new Connection( rpcaccountname ); 46

Calling an RPC subroutine from Java or C# RedObject ocust = new RedObject(); ocust.setconnection(oconn); // set param1 as required by subroutine you are going to call // this could be a delimited string of several params in one String param1 = myparam1 ; // set param2 as required by subroutine you are going to call String param2 = param ; // call subroutine, getting back a recordset or null object RecordSet rs = ocust.callrpc( mysubroutinename, param1, param2); // you can then loop thru your recordset so: for(int z =1;z <=10; z++) { if(rs.iseof()) { return; } String s = ; if(!rs.iseof()) { s = rs.getproperty( EMP.ID )+ + rs.getproperty( FIRST.NAME ) + + rs.getproperty( LAST.NAME ); // do something with s //... } rs.movenext(); } 47

Part III: Using SB/XA with the Web Designer The following sections discuss the integration of SystemBuilder Extensible Architecture (SB/XA) and Web Development Environment (Web DE) products. It describes the steps for enabling Web DE in an SB/XA account and how to call SB/XA processes from Web DE. 48

Chapter 9: Introduction to the Web DE-SB/XA interface Web DE is a tool that facilitates web access to UniData- or UniVerse-based applications and data. The Web DE-SB/XA interface enables compliant SB/XA server processes to run from Web DE on the backend. The support is built into Web DE, making Web DE SB/XA-aware, and not the opposite. For this reason, you may have to modify existing SB/XA applications to indicate that communication with SB/XA may be from a web browser rather than the customary Telnet session. Compliant SB/XA processes and functions From Web DE, it is possible to run compliant SB/XA processes and functions. Compliant SB/XA functions do not require input or output. SB/XA and Web DE interaction takes place on the RedBack Object Server; there is no interaction with the client through a web browser. The following list itemizes the main SB/XA functions that can run from Web DE, provided they do not involve input or output: BASIC subroutines (PD.B) Conditional (PD.C) Defaults (PD.D) File updates (PD.F) Job schedules (PD.J) Paragraphs (PD.P) Periodic updates (PD.U) Note: The Web DE-SB/XA interface is provided by Web DE, not SB/XA. For this reason, the interface does not provide full access to all of the SB/XA environment, such as input and output processes like menus and graphs. The web imposes a different architecture than that used with conventional green screen applications or client/server environments. This limitation is not caused by Web DE; it is caused by the web infrastructure. Process considerations Certain SB/XA processes require particular attention when designing applications for access using Web DE. These include job schedules (PD.J) and periodic updates (PD.U). When a job schedule is started, Web DE displays the Launch Job Schedule form, where you can specify a date and time to start. When running a job schedule from Web DE, you must specify a start date and time; otherwise, the server waits for input. The following syntax starts the job schedule JS1 immediately: SBProcess('JS1,\,\') When a periodic update process runs, it may present the following prompt: OK To Continue (Y/N). To avoid this, modify the periodic update process definition from PUD, and change the Period Check DD-DD field to -. 49

Chapter 9: Introduction to the Web DE-SB/XA interface COMMON variables The following SB COMMON variables are available from the client: PARAM VALUE RTN.FLAG USERDATA() For more information, see WW.SB.COMMON() in Web DE subroutines for SB/XA access, on page 57. Supported SB/XA server versions SB/XA versions 5.x and 6.x are able to interface with Web DE. The COMMON variable SBCLIENT<8> contains a Web DE flag, which corresponds to the following values: 0: Not in Web DE mode 2: In Web DE mode Additionally, SBCLIENT<9,1> represents the RBO class name and <9,2> represents the RBO method. Finally, error messages are written to the $ERRORport item in the XXCONTROL file. These hooks into the SB/XA server are provided only as a diagnostics mechanism. SB/XA versions earlier than 5.x cannot interface with Web DE. However, it is possible to determine from an SB/XA process if Web DE is running the current process. You can do this by checking the current value of the COMMON variable TERM.DEFN<15>, which normally provides an indication of the type of terminal you are using. When Web DE is interacting with SB/XA, the value of TERM.DEFN<15> is set to REDBACK. SB/XA s mode of operation is to run processes in the background. The job schedule stack, OTHER(17), contains the Web DE/SB/XA process name. Therefore, error messages and other calls to SB.DISP() do not cause the process (or backend) to hang while waiting for input. Compatibility of the COMMON block SB/XA BASIC programs use a COMMON block that enables passing variables between programs. The COMMON block varies in different versions of SB/XA. When you write your own user handlers or employ any handlers with Web DE and SB/XA, the programs must be compiled with the correct version of COMMON for the version of SB/XA that you are running. Web DE provides several versions of the COMMON block, as listed in the following table. Table 8: COMMON block compatibility COMMON block Compatible SB/XA version 2.3.2 2.3.2 through 3.3.x 3.4.0 3.4.x through 4.2.x 4.3.0 4.3.x through 4.5x, and 5.x 50

Web DE and SB/XA coexistence COMMON block 6.0.0 6.x Compatible SB/XA version Web DE and SB/XA coexistence Web DE and SB/XA share the xxdrivers system files. There should not be any conflicts between Web DE and SB/XA and these files, but careful attention to these files is necessary. Web DE and SB/XA applications are not required to have the same module ID/system ID. However, if they are the same, running the REDBACK.CD program to clear Web DE drivers also clears SB/XA drivers. The system ID can be specified in SBProcess(). If the system ID is invalid, it defaults to the first system ID, SBSYSMENU. If the system ID is not specified, it defaults to the Web DE application ID. If the application ID is null, the system ID defaults back to SBSYSMENU. 51

Chapter 10: Using the Web DE-SB/XA interface To use the Web DE-SB/XA interface, you first need to set up an account that can be used for both Web DE and SB/XA. Once the account is created, you can start using SB/XA processes in Web DE. Enabling Web DE in an SB/XA account Before you can run SB/XA processes from Web DE, you must first set up the account for use with both Web DE and SB/XA. Prerequisites Install Web DE. For steps, see Web DE Installation and Configuration. Install SB/XA. For steps, see SB/XA Getting Started. The RedBack Object Server and SB/XA server components must be installed on the same computer. This is required to create an environment in which Web DE and SB/XA can communicate. Create an SB/XA account. For steps, see Administering SB/XA. Procedure 1. Set up a pointer to the Web DE WWPROGS file. In the following example, the database is UniData and we use AE as the editor. :AE VOC WWPROGS 001= DIR [for UniVerse, enter F instead on this line] 002= C:\U2\U2WDE520\UDserver\rbdefn\WWPROGS 003= C:\U2\U2WDE520\UDserver\rbdefn\D_WWPROGS Note: When creating the VOC pointer, use the path of the directory in which Web DE is installed, which may be different from the path in the example above. Save the record. If you are using the UniVerse data server, you must also set up a pointer to the WWPROGS.O file, in which UniVerse BASIC object files are stored. 2. Enable the SB/XA or U2 account for use with Web DE by running the following UniData or UniVerse command from the ECL/TCL prompt: RUN WWPROGS ENABLE.RBO 3. Enable the SB/XA interface by running the following UniData or UniVerse command from the ECL/ TCL prompt: RUN WWPROGS WW.INITIATE Note: After upgrading the SB/XA server, you must run WW.INITIATE in each SB/XA and Web DE-enabled U2 account to ensure that the correct system programs are set up for that version of SB/XA. 4. If necessary, repeat steps 2 and 3 as many times as needed for your accounts to refresh pointers. 52

Setting up security associations Results WW.INITIATE sets up the Web DE or SB/XA programs for the current version of the SB/XA server by finding the version details in $SB.RELEASE (VOC). The appropriate system programs and COMMON variables, including SB.COMMON and SB.COMMON.ALL, are then set up based on the version of the SB/XA server. WW.INITIATE also modifies the LOGIN process to determine whether to start the RedBack Object Server or SB/XA server. This is accomplished through the WW.SB.RB program and the RedBack environment variable. Setting up security associations When running SB/XA processes from Web DE, SB/XA process security restrictions are applied. It is important to make sure that you are using the correct SB/XA user name. The user name is set through either security associations or the sb_user_id property, which overrides security associations. At runtime, the Web DE user name is UNKNOWN. When you are testing RBOs using the RBOScope testing tool, you can specify any Web DE user name, for example, rbadmin. The user name must be associated with an SB/XA user name when testing sbobject RBOs through the RBOScope testing tool. About this task You set up security associations by running the RB.USERS administration program in Web DE. You can run the RB.USERS program from any account, but it is best to run the program from an SB/ XA- or Web DE-enabled U2 account, where the required DMSECURITY pointer is already set up by WW.INITIATE. Procedure 1. From the operating system prompt, start a UniData ECL or UniVerse TCL session in an SB/XA- or Web DE-enabled U2 account. 2. Run the RB.USERS program and log on with a valid Web DE user name and password. 3. Create a Web DE user, if required. Otherwise, edit the details of an existing user to enable SB/XA access. 4. Optional: Enter the associated SB/XA user name and password of the Web DE user. If you do not enter an SB/XA user name, Web DE uses the UNKNOWN user at run time. SB/XA 5.x and 6.x, the UNKNOWN user is already set up by default. Note: To prevent access by users who do not have an SB/XA association, do not create or delete the UNKNOWN user from the SB/XA server. Results The Web DE WW.INITIATE program changes the LOGIN process to run the WW.SB.RB subroutine. This subroutine determines whether an SB/XA or Web DE session is started, and runs the standard SB.LOGIN for an SB/XA session or the standard SPIDER program for a Web DE session. Properties and methods You can call an SB/XA process in Web DE using the Execute method or a user-defined method. You must call these methods from a user class that inherits from the sbobject class, and you must have a 53

Chapter 10: Using the Web DE-SB/XA interface valid SB/XA process defined in the process_name property. Once you define the user class and the corresponding SB/XA process, you can call the process by running one of these methods. sbobject class The sbobject class inherits from the uobject class. It provides functionality for calling SB/XA processes and accessing UniData or UniVerse databases. The sbobject class properties and methods are described in the following tables. Table 9: sbobject properties Property name process_name parameter system_id sb_user_id sb_password value rtn.flag userdata# server_status server_message The process name to execute. An optional parameter. Optional. Specifies the system ID. If you do not specify this parameter, it defaults to the Web DE application ID. For more information, see Web DE and SB/XA coexistence, on page 51. Optional. An SB/XA user name. If you do not specify this value, the value defaults to the SB/XA user name associated with the Web DE user name (generally UNKNOWN). You must enable the Web DE user for SB access. For more information, see Enabling Web DE in an SB/XA account, on page 52. Optional. The SB/XA password corresponding to the sb_user_id property. If you do not specify this value, NULL is assumed. The value of the sb_password property is transferred unencrypted between the web server and the RedBack Object Server in the Web DE proprietary protocol. The SB/XA COMMON variable @VALUE. The SB/XA COMMON variable @RTN.FLAG. The SB/XA COMMON variable @USERDATA(#). The status of the server after the Execute method. Nonzero means there was an error. If server_status is a nonzero value, this property contains the corresponding error. Table 10: sbobject methods Method name Execute Refresh Executes the process, as specified in the property process_name within system_id and passing parameter. Populates the result set to user interface with server state and changes. You can use this to reset the user interface to a known state if a user wants to cancel last user interface changes. 54

User-defined method Method name PostCreateServerEvent A server event triggered after the object has been created on the RedBack Object Server. Server events are predefined events to which application developers can assign BASIC code routines. User-defined method If you do not want to use the standard execute method, you can write your own method using the Web Designer to replace the standard WW.SB.OBJECT with the name of your own BASIC subroutine. This subroutine calls either WW.PROCESS or WW.SB.COMMON and WW.SB.PROCESS to execute the required process. Note: The executive method provides server_status and server_message. User-defined methods in an sbobject class must pass these properties back manually to update the client on the status of the execution of the user-defined method. For example, SUBROUTINE USER.RBO1 * SB+/Redback RBO Method $INCLUDE WWINSERT STD.H $INCLUDE WWINSERT RBO.H $INCLUDE WWINSERT PROPERTIES.H $INCLUDE WWINSERT SB.COMMON * EQU PROG.ID TO "USER.RBO1" * * Get Process details PROCID = '' PARAM = '' SYSID = '' * ERR = RBO.getProperty('', 'process_name', PROCID) IF ERR THEN RB.RTN.INFO = 'ERROR ':ERR.CANNOT.FIND:VM:'process_name' RETURN END ERR = RBO.getProperty('', 'system_id', SYSID) * Extract Process details Z = INDEX(PROCID, COMMA, 1) IF Z THEN PARAM = PROCID[Z+1, LEN(PROCID)] PROCID = PROCID[1, Z-1] END * Parameter ERR = RBO.getProperty('', 'parameter', P) IF NOT(ERR) THEN PARAM = P * System Id ERR = RBO.getProperty('', 'system_id', SYSID) * Procid IF PARAM > '' THEN PROCID = PROCID:COMMA:PARAM Set COMMON from State * Get value, rtn.flag and userdata() CALL WW.SB.COMMON(1, ERR) IF NOT(ERR) THEN 55

Chapter 10: Using the Web DE-SB/XA interface * Call SB+ Process CALL WW.SB.PROCESS(PROCID, ERR) IF NOT(ERR) THEN * Set State from COMMON * Update parameter, value, rtn_flag and userdata CALL WW.SB.COMMON(4:AM:6, ERR) END END * Server status STATUS = 0 MESG = " IF ERR THEN STATUS = ERR MESG = 'ERROR in USER.RBO1' END ERR = RBO.setProperty(",'server_status',STATUS) ERR = RBO.setProperty(",'server_message',MESG) * RETURN 56

Chapter 11: Web DE subroutines for SB/XA access The following sections detail the methods that the SBProcess() and customer user handler methods call to access SB/XA-compliant processes. WW.SB.COMMON() Syntax WW.SB.COMMON(Actions,Err) where Actions is a multivalued list of the following actions: 1: Initialize COMMON. 2: Set COMMON from state. If state is not found, COMMON is initialized. 3: Set RECORD, KEY, MAINFILE, and ORIG.REG from RecordSet. In RBO mode, set VALUE, RTN.FLAG, and USERDATA() from class properties. 4: Set State from COMMON. 5: Set Record Set from RECORD. 6: Set class properties from PARAM, VALUE, RTN.FLAG, and USERDATA() (RBO mode only). and Err is the error code. Note: Actions 3, 5, and 6 are used to get data from and update data into an input form, such as RecordSet. The COMMON variables available are listed in the following table. Table 11: COMMON variables Variable Actions value RECORD Set to null. Set from RecordSet 1 3 KEY Set to null. Set from RecordSet 1 3 WORK Set to null. 1 OTHER.REC Set to null. 1 LF.INFO Set to null. 1 CNT Set to 0 1 ACTION Set to 0 1 LINE `Set to null. 1 MAINFILE Set to null. Get from RecordSet 1 3 F.FILE Set to null. File handle if MAINFILE is not null 1 2 57

Chapter 11: Web DE subroutines for SB/XA access Variable Actions value ORIG.REC Set to null. Get from RecordSet LOCK.KEY Set to null. 1 HEAD Set to null. 1 SCR.IMAGE Set to null. 1 STATUS.LINE Set to null. 1 BOX.CORDS Set to null. 1 OUTVAL Set to null. 1 OUTVAL.FLAGS Set to null. 1 F.INDX Set to null. 1 F.INDX.DEFNS Set to null. 1 GUI Set to 0 1 GUIRES USERDATA(1) FREE.TEMP(20) VALUE Not applicable. Set to null. Get from user data Returned to user data Not applicable. Set to null. Get from value Return to value RTN.FLAG Set to 0 PARAM Get from rtn_flag Return to value Set to null. Get from parameter Return to value REFRESH Set to 0 1 MENU.OPT Set to null. 1 PROC.NAME Set to null. 1 LEVEL.NO Set to 0 1 FILES.OPENED Set to null. 1 FILEVAR(30) Set to null. File handle if corresponding FILES.OPENED is not null. PARMS(40) Set to null. 1 SBPARM(20) Set to null. 1 OTHER(20) Set to null. 1 SB.CONT Set as normal. 1 CONTROL Set as normal. 1 PORT Set as normal. 1 SYSID Set to SB/XA system ID 1 1 3 1 3 6 1 3 6 1 3 6 1 3 6 1 2 58

WW.SB.COMMON() Variable Actions value ACNT.NAME Set to account name 1 TERM.DEFN Set as normal. TERM.DEFN<15>= REDBACK TERM.DEFN<41>=2 PRINT.DEFN Set as normal. 1 PASS.DEFN Set as normal. 1 USER.ID Set to SB/XA user ID (as specified from the security association or sb_user_id property). USER.KEYS Set as normal. 1 PCTERM Set to 0 1 F.MD File handle 1 F.DMCONT File handle 1 F.DMDRIV File handle 1 F.PASS File handle 1 F.CONT File handle 1 F.PROC File handle 1 F.MENU File handle 1 F.DMPROC File handle 1 F.DEFN File handle 1 F.G.PROC File handle 1 F.G.MENU File handle 1 F.G.DEFN File handle 1 F.DMSYSDEFN File handle 1 BT.NODE(7) BT.LEV.NO BT.ID BT.POS Not applicable. Not applicable. Not applicable. Not applicable. GUIDATA Set to null. 1 SBCLIENT RES1 RES2 SBCLIENT<8> 2 - RBO SBCLIENT<9,1> RBO class name SBCLIENT<9,2> RBO method name Not applicable. Not applicable. Errors codes are described in the following table. Table 12: Err codes Code 0 COMMON initialized. 1 1 59

Chapter 11: Web DE subroutines for SB/XA access Code < or > 0 COMMON could not be initialized. If an error occurs, Err is set to the Action on which it failed. For example, CALL WW.SB.COMMON(4:AM:6, ERR) From inside the user-defined method or subroutine, you can first call WW.SB.COMMON. This is a BASIC subroutine that sets up COMMON for you. You can then manipulate the contents of COMMON as required. WW.SB.PROCESS() Syntax WW.SB.PROCESS(SBprocessname,Err) where SBprocessname is comprised of: <SysId>/SBprocessId,<Param> and Err is the error code. Error codes are described in the following table. Table 13: Err codes Code 0 Process executed. 1 Process could not be executed. For example, CALL WW.SB.PROCESS( XX/MYPROC, 1, ERR) CALL WW.SB.PROCESS( MYPROC, 1, ERR) CALL WW.SB.PROCESS( MYPROC, ERR) This method validates that the SB/XA user exists by checking the Web DE-SB/XA association. If the association has not been specified, the UNKNOWN SB/XA user is used. This method also determines whether the SB/XA process can be called from Web DE. 60

Appendix A: Configuration files The following sections describe the content of the Web DE configuration files. JavaScheduler.ini file The Java Scheduler configuration file, JavaScheduler.ini, is in the directory that is specified by the U2WDE environment variable. The RedBack Object Server uses the JavaScheduler.ini file for global and account-level connection parameters used to process requests. Format The JavaScheduler.ini file format is: [SectionName] parameter_1=value_x parameter_2=value_y... Each section contains a set of related parameters. Web DE searches the JavaScheduler.ini file for predefined and user-defined section names, and updates internal parameters based on the values set in the file. Most of the section names are predefined, so you cannot change them. However, you can define the names of additional sections. Example JavaScheduler.ini file The following example of the JavaScheduler.ini file contains the default sections and settings that show the type of data required for each parameter: [LogLevel] panic=1 err=1 inf=0 init=1 trace=0 wrn=0 [Default] SchedulerPort=7070 MonitorPort=7071 logpath=c:\u2\u2wde520\javascheduler.log RbdefnPath=C:\U2\U2WDE520\UDserver\rbdefn server=localhost userid=cbrown password=2spwv0hjequeefssbqk1kq== ConnectionString=udcs como=1 usingssl=0 sslkeystore=pathtosslkeystore sslkeystorepassword=6b6jy5kn5o6l1ry5j26riq== [rbexamples] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userid=cbrown 61

Appendix A: Configuration files password=2spwv0hjequeefssbqk1kq== server=localhost como=1 usingssl=0 ThreadSocketTimeOut=1000 unirpctimeout=100 Sections of the JavaScheduler.ini file The JavaScheduler.ini file includes three default sections: [LogLevel] section [Default] section [account] section [LogLevel] section This section of the JavaScheduler.ini file contains parameters for the types of information to write to the JavaScheduler.log file for Web DE-enabled U2 accounts. The log level parameters are global; they apply to all Web DE-enabled U2 accounts on the RedBack Object Server computer. The following example shows the [LogLevel] section: [LogLevel] panic=1 err=1 inf=0 init=1 trace=0 wrn=0 The following table lists the log level parameters. Each parameter specifies whether to write details for a type of information to the JavaScheduler.log file. To log a type of information, set the parameter to 1, for example panic=1. To turn off logging for a type of information, set the parameter to 0, for example panic=0. By default, all parameters are turned off, except panic, err, and init. Table 14: [LogLevel] section parameters Parameter panic err inf Specifies whether to log fatal errors. 0 Do not log fatal errors. 1 Log fatal errors. This is the default setting. Specifies whether to log details of serious errors. 0 Do not log serious errors. 1 Log serious errors. This is the default setting. Specifies whether to log informational messages. 0 Do not log informational messages. This is the default setting. 1 Log informational messages. 62

[Default] section Parameter init trace wrn Specifies whether initialization/termination messages are to be logged. 0 Do not log initialization or termination messages. 1 Log initialization/termination messages. This is the default setting. Specifies whether to log program flow tracing messages. This parameter is not included in the JavaScheduler.ini file by default. 0 Do not log program flow tracing messages. This is the default setting. 1 Log program flow tracing messages, including incoming request names, request values, property names, and property values from the client. Also log outgoing property names and values being returned to the client. Specifies whether to log warning messages. 0 Do not log warning messages. This is the default setting. 1 Log warning messages. [Default] section The parameters in this section define Web DE system defaults. They apply to all Web DE-enabled U2 accounts within the system. You can override the defaults within each [account] section. The following example shows the [Default] section: [Default] SchedulerPort=7070 MonitorPort=7071 logpath=c:\u2\u2wde520\javascheduler.log RbdefnPath=C:\U2\U2WDE520\UDserver\rbdefn server=localhost userid=cbrown password=2spwv0hjequeefssbqk1kq== ConnectionString=udcs como=1 usingssl=0 sslkeystore=pathtosslkeystore sslkeystorepassword=6b6jy5kn5o6l1ry5j26riq== The following table lists the default global parameters at the Web DE system level. You can add other default parameters in this section, if applicable. Table 15: [Default] section parameters Parameter SchedulerPort MonitorPort logpath RbdefnPath server userid password The port number on which the Java Scheduler accepts RBO requests. Make note of this setting when editing the rgw5.ini file. The port number on which the Java Scheduler accepts monitor and maintenance requests. The path to the JavaScheduler.log file. The path to the deployed rbdefn account. The name or IP address of the computer on which the RedBack Object Server is installed. The operating system-level user ID for the RedBack Object Server computer. The password associated with the user ID. 63

Appendix A: Configuration files Parameter ConnectionString como usingssl sslkeystore Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) or connection. Specifies whether to save the server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. 0 Do not save the logs. 1 Save the logs. Specifies whether to use Secure Sockets Layer (SSL) protocol when making connections to the U2 server. 0 Do not use SSL. 1 Use SSL. The path to the SSL keystore for the Java Scheduler. sslkeystorepassword The password for the SSL keystore. [account] section The JavaScheduler.ini file contains a section for each account. The name of the section is the connection name of the account, used as a reference by RedBeans or RedPages.NET. In each [account] section, you must define at least the mandatory parameters for the account. You can specify additional parameters. If you specify a parameter in the [account] section that is also in the [Default] section, the value that you set for the account overrides the system default value. The following example shows the [account] section: [rbexamples] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost usingssl=0 ThreadSocketTimeOut=1000 unirpctimeout=100 The following table describes the parameters in the [account] section: Table 16: [account] section parameters Parameter workdir MinimumPoolSize MaximumPoolSize ConnectionString userid The physical path to the U2 account on the computer on which the RedBack Object Server is installed. The minimum number of connections maintained in the connection pool. The maximum number of connections maintained in the connection pool. Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) connection. The operating system-level user ID for the RedBack Object Server computer. 64

[account] section Parameter password server como usingssl ThreadSocketTimeOut unirpctimeout The password associated with the user ID specified in the userid parameter. The password is encrypted when you save the JavaScheduler.ini file in Web Designer. If you edit and save the JavaScheduler.ini file in a text editor, the password is saved in plain text. To maintain server security, open and save the JavaScheduler.ini file in Web Designer to encrypt the password. The name or IP address of the computer on which the RedBack Object Server is installed. Specifies whether to save the server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. 0 Do not save the logs. 1 Save the logs. Specifies whether to use the SSL protocol when connecting to the U2 server. 0 Do not use SSL. 1 Use SSL. The number of milliseconds that sockets can be left open with no activity before they timeout on the listening thread. If not set, the default socket timeout of 8 hours is set on the listening thread. Optional parameter that specifies the maximum amount of time the Java Scheduler is going to wait for a response before it considers the request as timed out and sends an appropriate message back to the coding client. This parameter needs to be less than the unirpctimeout parameter set in the rgw5.ini file. Default is 300 seconds. [account.environment] subsection This subsection of the [account] section is optional. To define separate environment variable values in an account, insert an account environment with property and value pairs, for example: [rbexamples] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost como=1 usingssl=0 [rbexamples.environment] account_desc=rbexamples2 LANG=en_US TZ=MST7MDT An [account.environment] subsection can be used to create an alias that points to the same account but uses a different environment variable for connection pools, for example: [rbexamples] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=1 MaximumPoolSize=10 65

Appendix A: Configuration files ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost como=1 usingssl=0 [rbexamples.environment] account_desc=rbexamples GMT TZ=GMT WWSESSION=1 [rbexamples_alias] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=1 MaximumPoolSize=1 ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost usingssl=0 [rbexamples_alias.environment] account_desc=rbexamples TZ=MST7MDT rgw5.ini file The gateway configuration file, rgw5.ini, is in the directory specified by the U2WDE environment variable. The RedBack gateway components, which run on the web server or the client, use the rgw5.ini file for global parameters and as a reference to the location at which each U2 account resides. Format The rgw5.ini file format is: [SectionName] parameter_1=value_x parameter_2=value_y... Each section contains a set of related parameters. Web DE searches the rgw5.ini file for predefined and user-defined section names, and updates internal parameters based on the values set in the file. Most of the section names are predefined, so you cannot change them. However, you can define the names of additional sections. Example rgw5.ini file The following example rgw5.ini file contains the default sections and settings that show the type of data required for each parameter: [LogLevel] panic=1 err=1 inf=0 init=1 times=1 wrn=1 trace=1 66

Sections of rgw5.ini file [Default] perfstats=0 [rbexamples] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost logpath=c:\u2\u2wde520 ;SchedulerPort=7070 como=1 usingssl=1 PoolingDebug=1 IdleRemoveThreshold=15000 IdleRemoveExecInterval=1000 OpenSessionTimeout=1000 unirpctimeout=500 Sections of rgw5.ini file The rgw5.ini file contains three default sections: [LogLevel] section [Default] section [accountname] section [LogLevel] section This section of the rgw5.ini file contains parameters for the types of information to write to the client log files for Web DE-enabled U2 accounts. The log level parameters are global; they apply to all Web DE-enabled U2 accounts on the RedBack Object Server computer. The client log files are: RedBeans_accountname.log RedPages_accountname_processid.log, where processid is the ID of the Windows process with RedPagesNet.dll loaded. The following example shows the [LogLevel] section: [LogLevel] panic=1 err=1 inf=0 init=1 times=1 wrn=1 trace=1 The following table lists the log level parameters. Each parameter specifies whether to write details for a type of information to the client log files. 67

Appendix A: Configuration files To log a type of information, set the parameter to 1, for example panic=1. To turn off logging for a type of information, set the parameter to 0, for example panic=0. By default, all parameters are turned off, except panic, err, and init. Table 17: [LogLevel] section parameters Parameter panic err inf init times wrn trace Specifies whether to log fatal errors. 0 Do not log fatal errors. 1 Log fatal errors. This is the default setting. Specifies whether to log details of serious errors. 0 Do not log serious errors. 1 Log serious errors. This is the default setting. Specifies whether to log informational messages. 0 Do not log informational messages. This is the default setting. 1 Log informational messages. Specifies whether initialization/termination messages are to be logged. 0 Do not log initialization or termination messages. 1 Log initialization/termination messages. This is the default setting. Specifies whether to log the times (in milliseconds) for executing RBO method calls. 0 Do not log times of method calls. This is the default setting. 1 Log times of method calls. Specifies whether to log warning messages. 0 Do not log warning messages. This is the default setting. 1 Log warning messages. Specifies whether to log program flow tracing messages. 0 Do not log program flow tracing messages. This is the default setting. 1 Log program flow tracing messages, including incoming request names, request values, property names, and property values from the client. Also log outgoing property names and values being returned to the client. [Default] section The parameters in this section define Web DE system defaults. They apply to all Web DE-enabled U2 accounts within the system. You can override the defaults within each [accountname] section. The following example shows the [Default] section: [Default] perfstats=0 The following table lists the default global parameters at the Web DE system level. You can add other default parameters in this section, if applicable. 68

[accountname] section Table 18: [Default] section parameters Parameter perfstats Specifies whether to log performance statistics. 0 Do not log performance statistics. 1 Log performance statistics. The Perfstats.log file includes the same statistics available from the Web DE performance monitor API, such as wait time and number of requests processed for each account. The Perfstats.log file is written to the C:\U2\U2WDEnnn directory by default, where nnn is the version number you installed. [accountname] section The rgw5.ini file contains a section for each account. The name of the section is the connection name of the account, used as a reference by RedBeans or RedPages.NET. In each account section, you must define at least the mandatory parameters for the account. You can specify additional parameters. If you specify a parameter in the [accountname] section that is also in the [Default] section, the value you set for the account overrides the system default value. The following example shows the [accountname] section: [rbexamples] workdir=c:\u2\u2wde520\udserver\rbexamples MinimumPoolSize=2 MaximumPoolSize=2 ConnectionString=udcs userid=cbrown password=2spwv0hjequeefssbqk1kq== server=localhost logpath=c:\u2\u2wde520 ;SchedulerPort=7070 como=1 usingssl=1 PoolingDebug=1 IdleRemoveThreshold=15000 IdleRemoveExecInterval=1000 OpenSessionTimeout=1000 unirpctimeout=500 The following table describes the parameters in the [accountname] section: Table 19: [accountname] section parameters Parameter workdir The physical path to the U2 account on the computer on which the RedBack Object Server is installed. 69

Appendix A: Configuration files Parameter MinimumPoolSize MaximumPoolSize ConnectionString userid password server logpath SchedulerPort como The minimum number of connections maintained in the connection pool. Setting this value and the MaximumPoolSize value to 0 enables the developer mode, which allows you to execute newly compiled code through Web DE processes. Instead of using a cached version of the object code, the developer mode allows you to pick up the new object code as soon as it is available by causing the associated database processes to restart after each method call. While allowing newly compiled code to be picked up, this mode carries a performance overhead as the associated database processes terminate and are recreated after each method call and is not recommended for live production use for this reason. The SchedulerPort must also be commented out to bypass the connection to the Java Scheduler. The maximum number of connections maintained in the connection pool. Setting this value and the MinimumPoolSize value to 0 enables the developer mode. See the description in MinimumPoolSize for information about the developer mode. Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) connection. The operating system-level user ID for the RedBack Object Server computer. The password associated with the user ID specified in the userid parameter. The password is encrypted when you save the JavaScheduler.ini file in Web Designer. If you edit and save the rgw5.ini file in a text editor, the password is saved in plain text. To maintain server security, open and save the rgw5.ini file in Web Designer to encrypt the password. The name or IP address of the computer on which the RedBack Object Server is installed. The full path of the directory in which to store client log files for the account on the client computer. The client log files are RedBeans_accountname.log and RedPages_accountname_processid.log, where processid is the ID of the Windows process with RedPagesNet.dll loaded. The directory must already exist; Web DE does not create a new directory for you. If the specified logpath directory does not exist, the application fails at run time. The port number on which the Java Scheduler accepts requests from this account. If this parameter is commented out, and the MinimumPoolSize and MaximumPoolSize parameters are set to 0, the Java Scheduler connection is bypassed. Specifies whether to save the server logs to the account _PH_ file in UniData or the &COMO& file in UniVerse. 0 Do not save the logs. 1 Save the logs. 70

[accountname] section Parameter usingssl PoolingDebug encoding IdleRemoveThreshold IdleRemoveExecInterval OpenSessionTimeout unirpctimeout Specifies whether to use the SSL protocol when connecting to the U2 server. 0 Do not use SSL. 1 Use SSL. Specifies whether to keep a log of UOJ processes for the account for debugging purposes. 0 Do not keep a log of UOJ processes. 1 Keep a log of UOJ processes. Allows support of any session encoding for connections using RedPages.NET or RedBeans. The number of milliseconds that a connection pool thread can remain idle before it is flagged for removal. The number of milliseconds of the interval at which UOJ runs an executable to remove from a connection pool any threads that have exceeded the idle threshold. The number of milliseconds for which UOJ attempts to acquire a session from the connection pool before timing out. Optional parameter that specifies the maximum amount of time the client (RedBeans or RedPages.NET) is going to wait for a response from the Java Scheduler before it considers the request as timed out. Default is 300 seconds. 71