Version 5.3.0 Environment - Rocket Softwaredocs.rocketsoftware.com/nxt/gateway.dll/RKBnew20/... · Rocket U2 Web Development Environment Web Designer User’s Guide Version 5.3.0

Rocket U2 Web DevelopmentEnvironment

Web Designer User’s Guide

Version 5.3.0

July 2017WDE-530-ALL-UG-01

2

NoticesEdition

Publication date: July 2017Book number: WDE-530-ALL-UG-01Product version: Version 5.3.0

Copyright© Rocket Software, Inc. or its affiliates 1996-2017. All Rights Reserved.

Trademarks

Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay 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 ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe 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 withthe terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict theuse, import, or export of encryption technologies, and current use, import, and export regulationsshould be followed when exporting this product.

http://www.rocketsoftware.com/about/legal

3

Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.

Website: www.rocketsoftware.com

Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA

To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.

Country Toll-free telephone number

United States 1-855-577-4323Australia 1-800-823-405Belgium 0800-266-65Canada 1-855-577-4323China 400-120-9242France 08-05-08-05-62Germany 0800-180-0882Italy 800-878-295Japan 0800-170-5464Netherlands 0-800-022-2961New Zealand 0800-003210South Africa 0-800-980-818United Kingdom 0800-520-0439

Contacting Technical Support

The Rocket Community is the primary method of obtaining support. If you have current support andmaintenance agreements with Rocket Software, you can access the Rocket Community and reporta problem, download an update, or read answers to FAQs. To log in to the Rocket Community or torequest a Rocket Community account, go to www.rocketsoftware.com/support.

In addition to using the Rocket Community to obtain support, you can use one of the telephonenumbers that are listed above or send an email to [email protected].

http://www.rocketsoftware.com

http://www.rocketsoftware.com/support

mailto:[email protected]

4

Contents

Notices................................................................................................................................................................................... 2

Corporate information......................................................................................................................................................... 3

Part I: Rocket U2 Web Development Environment overview............................................................................................ 6Chapter 1: Introduction............................................................................................................................................7

Web DE components.................................................................................................................................... 7

Part II: RBOs and RPCs.........................................................................................................................................................8Chapter 2: Application development with the RBO model................................................................................... 9

RedBack objects (RBOs) overview...............................................................................................................9RBO properties and methods...................................................................................................................... 9RBO classes................................................................................................................................................. 10Session and state overview....................................................................................................................... 11

Sessions........................................................................................................................................... 11State.................................................................................................................................................12Understanding how session and state work together................................................................. 13

Chapter 3: Developing RBOs..................................................................................................................................15Getting started with Web Designer........................................................................................................... 15Developing RBOs........................................................................................................................................ 15

Creating or editing RBOs................................................................................................................15Creating an RBO............................................................................................................................. 15Editing an RBO................................................................................................................................19Creating an RBO from a U2 database file.....................................................................................20

Deleting an RBO..........................................................................................................................................20Locking and unlocking an RBO................................................................................................................. 20Maintaining logical file definitions............................................................................................................ 21Creating a subroutine.................................................................................................................................22

Editing a subroutine....................................................................................................................... 24Chapter 4: Developing server code for RBOs........................................................................................................25

Server API functions................................................................................................................................... 25RBO.createObject()......................................................................................................................... 25RBO.getProperty()...........................................................................................................................25RBO.setProperty()........................................................................................................................... 26RBO.callMethod()............................................................................................................................ 26RBO.setError()................................................................................................................................. 27RBO.getDBVals()..............................................................................................................................27RBO.setDBVals().............................................................................................................................. 27WW.FILEVAR.S................................................................................................................................. 28Options for setting text with RBO.setMessage and RBO.setError............................................... 28Caching and storing file handles...................................................................................................29

Essentials to add to a BASIC subroutine.................................................................................................. 29Automatically calling subroutines.................................................................................................30Status values returned from RBO function calls.......................................................................... 31

Chapter 5: Testing RBOs........................................................................................................................................ 32RBO debug logging.....................................................................................................................................32

debug property............................................................................................................................... 32debug_id property..........................................................................................................................33Debug log information................................................................................................................... 33Manually invoking the RBO debug process.................................................................................. 34

RBO testing overview................................................................................................................................. 35Accessing the RBOScope testing tool from Web Designer...........................................................35Testing an RBO............................................................................................................................... 36Accessing the stand-alone JSP RBOScope testing tool............................................................... 37

Contents

5

Testing RBOs with the stand-alone JSP RBOScope testing tool................................................. 37Configuring the encoding of the JSP RBOScope testing tool......................................................38

Chapter 6: RBO debug logging.............................................................................................................................. 40debug property........................................................................................................................................... 40debug_id property...................................................................................................................................... 40Debug log information............................................................................................................................... 41Manually invoking the RBO debug process.............................................................................................. 42

Chapter 7: Creating HTML documentation for RBOs........................................................................................... 43Generating RBO HTML documentation.....................................................................................................43

Chapter 8: Setting up remote procedure calls..................................................................................................... 44RPCs overview.............................................................................................................................................44Setting up RPCs.......................................................................................................................................... 44Writing an RPC subroutine.........................................................................................................................45Calling an RPC subroutine from Java or C#............................................................................................. 46Using the Overload RPC.............................................................................................................................47

Part III: Using SB/XA with the Web Designer.................................................................................................................... 48Chapter 9: Introduction to the Web DE-SB/XA interface......................................................................................49

Compliant SB/XA processes and functions...............................................................................................49Supported SB/XA server versions.............................................................................................................. 50Compatibility of the COMMON block........................................................................................................ 50Web DE and SB/XA coexistence.................................................................................................................51

Chapter 10: Using the Web DE-SB/XA interface....................................................................................................52Enabling Web DE in an SB/XA account..................................................................................................... 52Setting up security associations................................................................................................................53Properties and methods............................................................................................................................ 53

sbObject class................................................................................................................................. 54User-defined method..................................................................................................................... 55

Chapter 11: Web DE subroutines for SB/XA access.............................................................................................. 57WW.SB.COMMON()...................................................................................................................................... 57WW.SB.PROCESS()...................................................................................................................................... 60

Appendix A: Configuration files......................................................................................................................................... 61JavaScheduler.ini file............................................................................................................................................. 61

Sections of the JavaScheduler.ini file.......................................................................................................62[LogLevel] section...........................................................................................................................62[Default] section..............................................................................................................................62[account] section............................................................................................................................ 64

rgw5.ini file..............................................................................................................................................................66Sections of rgw5.ini file..............................................................................................................................67

[LogLevel] section...........................................................................................................................67[Default] section..............................................................................................................................68[accountname] section...................................................................................................................68

Appendix B: Web DE with Rocket Aldon LM(e)................................................................................................................. 71Modifying RBOs.......................................................................................................................................................71Checking the LME status........................................................................................................................................ 74

6

Part I: Rocket U2 Web DevelopmentEnvironment overview

Rocket U2 Web Development Environment (Web DE) is an application development toolkit for buildinginteractive client/server applications for deployment on the World Wide Web or on a corporateintranet.

7

Chapter 1: IntroductionThis document describes how to develop applications using the RedBack Objects (RBO) model. Itprovides instructions about how to develop and test RBOs, and how to set up remote procedure calls(RPCs). This document also contains steps for enabling Web DE in an SB/XA account and calling SB/XAprocesses from Web DE. Additional topics include Web DE configuration files and information aboutintegrating Web DE with Aldon Lifecycle Manager for Rocket U2 (LMU2) to manage your data andapplications through all stages of development.

Web DE componentsWeb DE consists of the RedBack Object Server, Java Scheduler, RedBeans and RedPages.NET, andWeb Designer.

The following table describes the role of each Web DE component.

Table 1: Web DE components

Component Description

RedBack ObjectServer

The RedBack Object Server manages access to RedBack applications andimplements dynamic runtime interfaces to server-side application resources.

The RedBack Object Server also maintains the repository that contains all thedefinitions and code that define an application.

Java Scheduler(ConnectionManager)

The Java Scheduler manages data transfer between the RedBack ObjectServer and the web server, handling requests from RedBeans andRedPages.NET. It also performs the job of load balancing, processing thequeue of connection requests by allocating U2 licenses as webshares.

Admin API Server The Admin API web server hosts a Web API and accompanying Web UI for JavaScheduler (Connection Manager) administration.

RedBeans andRedPages.NET

The RedBeans and RedPages.NET components are the Java and .NETapplication programming interfaces (APIs) that enable you to connect yourapplication to RedBack Objects (RBOs). These components are the interfacebetween the web server and the RedBack Object Server. The role of thesecomponents is to establish and maintain connection pool connections orwebshare connections between the web server and the RedBack ObjectServer.

Web Designer This suite of designer tools runs in an Eclipse development environment andprovides an interface for designing RBOs.

8

Part II: RBOs and RPCsThe following sections give an overview of RedBack objects (RBOs) and their function in webapplication 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 WebDesigner, testing RBOs with the built-in RBOScope testing tool or the standalone JSP RBOScopetesting tool, and developing server code for RBOs. For more information, see Application developmentwith the RBO model, on page 9.

RPCs

You can use RPCs to call a UniVerse BASIC or UniBasic subroutine directly and receive a RecordSet. Formore information, see Setting up remote procedure calls, on page 44.

9

Chapter 2: Application development with theRBO model

RBOs represent the logical design of the application in an object-oriented environment. The beststrategy is to design the RBOs and their structure based on the requirements of your application. It isrecommend that you design and plan the RBO implementation to make use of inheritance, planningwhich classes provide which data and methods.

The RBOs that you design and build provide an interface to your data and code. You create an objectlayer on top of what would normally not be viewed as an object environment. This means that yourdesign follows object-oriented techniques rather than standard UniData or UniVerse developmenttechniques. This is important because the RBOs will often be referenced by developers who do notunderstand UniData or UniVerse, or have any experience in multivalued data or UniBasic/UniVerseBASIC code.

The following sections provide an overview of developing applications by using the RBO model.

RedBack objects (RBOs) overviewWeb DE allows data access to a U2 database from a web application. You use RBOs to define thataccess. An RBO is a kind of data envelope that moves back and forth between the middleware andthe U2 data server. It moves data to the U2 data server when you call a method from a middlewareroutine, 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 dataabstraction 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 business-specific object definitions. You can create and maintain your RBOs in the RBO perspective of WebDesigner. In addition, the RBO perspective offers an editor tool for editing, compiling, and catalogingyour UniBasic or UniVerse BASIC subroutines.

You can test your RBOs by using the RBOScope testing tool that is included with Web DE. This toolallows you to test objects before you write your own middleware calling subroutines.

RBO properties and methodsRBOs have properties and methods. The properties are data and parameter placeholders, and themethods are aliases to subroutine calls. Some of these subroutines are included with Web DE, andothers you write yourself.

For example, you can create an RBO called “Order” by inheriting the stateless RBO (SLRBO) classthat 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 createthe subroutines that these methods reference.

In this example, there are two types of properties: those that contain database data, and those suchas ErrorCode and ErrorMessage that you use for communication from the UniBasic or UniVerse BASICprograms back to the calling routines in the middle tier. For example, if a program could not opena file or was not passed mandatory input, you want to report that information back to the callingsubroutine. You can accomplish this only by using the properties of the RBO through which it wascalled.

Chapter 2: Application development with the RBO model

10

RBO classesThe 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 fromthis class, and properties and methods can be added. With the RBO, you can create objects that youwant to keep in a user’s session by using the U2 data server. Web DE keeps the object data in theWWSTATE file. Keeping a handle to the object enables you to request the previously used object. Everymethod call flushes the data in the object to the record in WWSTATE. Every open, when using thepreviously stored handle from a cookie, hidden field, or variable, brings back the object with any datastored 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 itsstatefulness. This object is stateful; a stateless, faster version of it is the SLRBO class. You typically useeither 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 besent from the RedBack Object Server. This object runs the unix_command or nt_command yousupply, 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 actuallyrunning the mail command. Most web applications do not send email messages from the RedBackObject 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 theoperating 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 andUniVerse databases with prewritten UniBasic or UniVerse BASIC methods to auto-read and auto-write records. If you use this object in a stateful manner, the object can trigger a lock or optimisticconcurrency control error that you can handle by writing a subroutine for the UpdateLockError

Session and state overview

11

method. This object also has PostRead, PreWrite, and PostWrite methods for which you can writesubroutines. 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 queriesagainst UniData and UniVerse databases. A uQuery object returns a RecordSet that you can scrollthrough, displaying fields from each row as you scroll. If you gather data using a single SELECTstatement, you can use this object. Being a stateful object, it supports paging through the datawithout repeating the SELECT statement. If you cannot use a single SELECT statement to gather thedata, 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 aboutaccessing 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 theRedBack 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, forexample in the middle tier, or where the RBO does not actually require any state to be stored. Yourapplication might require storage of session IDs for stateless RBOs to ensure that a request is valid andallowed.

Session and state overviewThe main difference between designing applications for the web and designing applications fortraditional 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 tothe target web server. The target web server runs a process or script. This process sends a web pageback to your web browser, and then breaks the connection. If the web page contains images or otherfiles, multiple connections are made to download these items. In these situations, your web browsermakes, and breaks, multiple connections to the target web server.

You are connected to the web server (and ultimately the RedBack Object Server) only while therequest is made and resolved.

For web pages that only publish information, the stateless nature of the web does not pose any majordesign issues. However, for transactional applications, the lack of a permanent connection means thatyou can no longer use some of the traditional functionality of BASIC applications, such as COMMONmemory, in the same way.

Sessions

Because the web is stateless, there is no concept of logging on and logging off. These conceptstranslate in Web DE to the concept of session. A session is user information that defines a “virtualconnection.” Because there is no permanent connection, a session consists of a series of requestsbetween 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 fromyour web browser. The session information maintained on the RedBack Object Server includes the


12

results of queries and lookups. The session information maintained on the web server identifies theuser and the current session. The information used to identify the user includes the user's name, initialIP 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 tomaintain session information to identify you when you make subsequent requests. Unless the RBOsubclass 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 isthe first request, and creates a session and a session ID. Each subsequent request should pass backthat 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 moreinformation 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 webbrowser that does not contain any session information, it creates a new session. You cannot end asession, but you can start a new session. The session information maintained on the RedBack ObjectServer can remain there after a session life is complete.

The RedBack Object Server automatically deletes session information on a periodic basis through thebuilt-in garbage collection function. You can fine-tune garbage collection handling, if necessary. Formore 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 requiredfor your relational database management system (RDBMS) than are required for traditional host-based applications with the same number of users. There is no direct mapping between an end-userand 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 applicationdata in COMMON memory. The concept of COMMON memory translates in Web DE to the concept ofstate.

As you progress through a Web DE-based application, the RedBack Object Server stores objectstate for RBO objects that are instantiated, with the exception of stateless RBOs (SLRBO or any ofits subclasses). For example, if you select an RBO form from a menu, the RedBack Object Servermaintains object state for that form, including all fields and any values that you enter. Within eachobject 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 applicationtakes you back to RBO A, and the data is redisplayed in RBO A (stored in state). However, if you re-create RBO A at some point in the application, Web DE destroys any previous data state for RBO A. Youcannot have multiple instances of the same object.

The way in which your application navigates between objects is important because there is adifference between returning to and creating an object. With each request, the RedBack Object Serverreturns all current data for the object submitted to the RedBack Object Server and updates state. Ifyou need to reference a previous object, you can store the handle to the object in either RBO state orclient state (or both).

Understanding how session and state work together

13

It is important that you preserve the current session ID outside of the RedBack Object Server by thetier that makes the RBO request. If RBO A has state that is not required by the other RBOs, part ofyour design process needs to decide whether this RBO could be subclassed from SLRBO and becomestateless.

Stateless RBOs do not have to store state within the RedBack Object Server. This may make sense ifits state is not required at a later stage, or if the state is to be stored in a tier outside of the RedBackObject Server.

A stateless RBO cannot access data from another RBO method. The RedBack Object Server enginemust preserve the current RBO state, but a stateless RBO cannot have its state preserved. This is onlyapplicable 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 stateinformation is available to RedBack Object Server code through the server API functions. If the RBOis subclassed from SLRBO (a stateless RBO), this state is available only during the request and notafterward, 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 bereferenced by other RBOs. For this process to work, the RedBack Object Server must pass the sessionID with every request. Without a session ID, the RedBack Object Server has no way of determiningto which session the request belongs, and cannot reference state from that session's other RBOinstances.

The RedBack Object Server uses the session ID to validate a request and determine whether thesession is still active. If you use stateless RBOs, you might want to implement your own form of sessionand 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 amethod on an RBO. You can call a method from the client code or from the UniVerse BASIC or UniBasiccode.

Web DE associates each method with a class and interacts with an instance of that class. The methoddoes not control the browser. By default, Web DE refreshes the current object for the initial methodcalled with its current state.

A method can create other instances of classes and interact with those instances' methods. Methodscan also retrieve information from state for their own instance and other class instances if the handleto 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 thatvalidates an employee salary. From your Employee RBO, you add a method called ValidateSalary andassociate the ValSal subroutine with that method.

The following figure shows the example of the ValSal subroutine in the Employee RBO.


14

Figure 2: Employee RBO

When the client makes a request to call the method ValidateSalary, the RedBack Object Server enginemakes a call to the ValSal subroutine.

Each method uses one or more of the server API functions to interact with RBO State for its instanceof the RBO class. For example, the ValSal subroutine looks at the salary entered, and then checks thatthe salary falls within the allowed salary ranges for the employee's department. The code creates aninstance of the Department RBO and calls its CheckSalary method. If the salary is outside of the salaryrange, 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 methodscalled directly through your RBOs. Instead, use your method subroutines to call business logicsubroutines, receiving data and status or error messages. All RBO.getProperty and RBO.setPropertycommands should be in the method subroutine that you call directly through the RBOs; none shouldbe in the business logic subroutines. This makes testing and debugging of your business logicsubroutines possible outside of Web DE.

15

Chapter 3: Developing RBOsThe following sections provide information about using the RBO perspective of the Web Designer.

Getting started with Web DesignerAfter you install Web DE, you can develop RBOs in the Web Designer. The Web Designer has an intuitiveuser interface to help you design and modify RBOs quickly. The components of the Web Designerworkspace are defined by the perspective that is selected. A perspective is a collection of views. Theviews in the RBO perspective of Web DE enable you to build, maintain, and test RBOs for your webapplication.

1. Open the Web Designer by clicking Start → All Programs → Rocket U2 → Web DevelopmentEnvironment → U2 Web Designer.

2. By default, the perspective opens to the RBO perspective. If the Web Designer does not open tothis by default, select Window → Open Perspective → RBO Perspective.

Developing RBOsDo the following tasks before you create or edit RBOs. These tasks are described in more detail inAdministering 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 totest 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 databasefile, 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 cancreate an RBO for the module. A module is a repository for all of the RBO class definitions that relate toa 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 NewRBO.

Chapter 3: Developing RBOs

16

2. In the Select Inheritance window, select the class from which the RBO inherits properties andmethods, 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 SHAREDmodule, and all classes in the current module that are not final classes. For more informationabout these types of classes, see RBO classes, on page 10.

Note: RBOs cannot inherit from final classes; therefore, final classes are not displayed in theSelect Inheritance window. RBOs can, however, inherit from system objects, but you cannotmodify system objects. Custom-developed objects do not have the word ‘SYSTEM’ next totheir title, but they have the word “SHARED” next to their title if they were created in theSHARED 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 theRBO is “new.” Inherited properties and methods are populated in the RBO Editor tabs, as shownin the following figure.

Figure 3: New RBO

3. Add identifying information, as described in Entering identifying information for the new RBO, onpage 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 forRBOs must not be used for the user-defined RBOs:

▪ rbo

▪ sysinfo

▪ emailobject

▪ uobject

Entering identifying information for the new RBO

17

▪ sbobject

▪ uquery

▪ logon

Note: The names are not case-sensitive. For example, you cannot have “RBO” and “rbo,” asthey both will appear as “rbo.”

Entering identifying information for the new RBOWhen you have a new RBO in edit mode, you must enter some identifying information such as a nameand description to identify the object.

1. From the RBO Editor pane, in the Description 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 HTMLdocumentation tool. The long description can contain HTML tags that help the RBO HTMLdocumentation tool display this description. For more information, see Creating HTMLdocumentation for RBOs, on page 43.

The Group field allows you to group RBOs for documentation purposes only. For example, if youhave an RBO related to updating accounts, you could define a group as UpdateAccounts andassign 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 theFinal Class check box.

Defining properties of the RBOIn the Properties tab of the RBO Editor, you can create new properties or edit existing propertieswhere 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 youset here is assigned to the property by default when a user creates an instance of the RBO at runtime.

To change the default value at any point for a user-defined property, click the cell to enable editmode.

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 Description

String Denotes that the value for the property is a string.mvString Denotes that the value for the property is a string that contains

multivalued data (U2 values, subvalues, or both).


18

Type Description

File Denotes that the value for the property is the name of a file.LogicalFile Denotes that the value for the property is the name of a logical file.Ref 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 RBOproperty of type Ref. This handle is then used by client code, such asRedPages.NET code, to interact with the object.

mvRef Denotes that the value for the property contains the names of a numberof Refs.

Field Denotes that the value for the property is a field from the UniData orUniVerse dictionary file defined for this RBO. The dict_file or logical_fileproperty determines the dictionary for this RBO.

mvField Denotes that the value for the property is a field containing multivalueddata from the UniData or dictionary file defined for this RBO. The dict_fileor logical_file property determines the dictionary for this RBO.

FieldNames Denotes that the value of the property is a list of selected field namesfrom the UniData or UniVerse dictionary file defined for this RBO. Thedict_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 theRBO HTML Documentation tool (detailed in Creating HTML documentation for RBOs, on page43) from Web Designer and give the output to RedPages.NET or RedBeans developers sothat 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 afield column for an RBO, depending on whether any of its properties are of the field type.

5. In the Description cell, click the ellipsis button (...) and enter a short and long description and agroup, if applicable.

6. The Field cell is populated for the RBO if any of its properties are of the type “Field.” If theproperty type is Field or mvField, select a database field name.

Note: You must define either the dict_file property or logical_file property before fieldsbecome available to assign to properties of type “Field.” The fields in the selection list comefrom the dictionary specified in the dict_file or logical_file property. If both the dict_file andlogical_file properties are defined, the logical_file property determines the dictionary fieldsand 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 atdesign 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 Description

C Create. You can set a default value for the property at design time inthe RBO Editor. This default value is assigned to the property when anobject of this class is instantiated at run time.

Defining methods of the RBO

19

Value Description

R Read. The value of the property can be read at run time using theRBO.getProperty() function call.

W Write. The value of the property can be set at run time using theRBO.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 tohave a red line through it, indicating that drop lists are disabled.

Defining methods of the RBOIn the Methods tab of the RBO Editor, you can create new methods or edit existing methods whereallowed.

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 Description 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 outputproperties are the properties that will be set by the method. Setting these properties providesmore 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 inthe 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 requiredproperties before calling the method and then 'get' the values of these properties once in theBASIC subroutine.

5. The Superclass cell displays the name of the class from which the method was inherited. Themethod’s superclass cannot be changed. If you are defining a new method of the RBO, superclassis 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 amodule, and double-click an existing RBO to edit.

Tip: Select Window → Show View → RBO Hierarchy to display all RBOs in a hierarchicalstructure. In this view, all objects supplied with Web Designer are marked SYSTEM todistinguish 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 unlockingan RBO, on page 20.


20

3. Edit identifying information, as described in Entering identifying information for the new RBO, onpage 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 Filesnode 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, onpage 15.

5. Select the check box next to the dictionary field definitions that you want to use as properties ofthe RBO.If you selected the Query RBO superclass on the previous wizard page, continue with thefollowing 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 RBOYou can delete an RBO by using the Web Designer. If other objects inherit from an object that youdelete, they become orphaned, and can be identified in the RBO Hierarchy view under the OrphanedClasses 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 RBOYou must lock an RBO to edit its attributes, properties, or methods. Only one user can lock an RBO ata time. This prevents multiple developers from overwriting each others’ changes. Locking is based onthe full path of the object, meaning that application IDs and account names can be duplicated on aserver, but the object can still be unique. When you lock an object, the definition is downloaded andan entry is created in the WWLOCKS file to indicate that you have opened the object. The RedBack

Maintaining logical file definitions

21

Object Server timestamps the entry in the WWLOCKS file. The entry in the WWLOCKS file remains untilyou close the object or unlock it. When you close the Web Designer, all open objects are closed, andtheir entries are removed from the WWLOCKS file.

Caution: Locking an RBO prevents others from modifying the RBO structure, attributes,properties, and methods when you are working on it, but does not prevent others from editing thesubroutine code. However, if the subroutine is locked at the database level and another developertries to access it, (for example, in the After Effects editor) Web DE will deny them access.

1. From the RBO List, U2 Resource, or RBO Hierarchy view, right-click the name of an RBO and selectLock 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 versionof 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 definitionsYou can combine the field definitions from a number of physical files into a single ‘logical’ filedefinition. This logical file definition is used during development and at run time as if it were a singlephysical file. You can specify the name of the logical file definition in the logical_file property of auObject 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 Description 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 notselect this check box, the RedBack Object Server locks each file that is defined in the logical filedefinition, 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. Tomove 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 logicalview. The following table describes the source files.


22

Table 4: Source files and descriptions

File Description

Dict File Select the dictionary file from the Dict File list. If you define a dictionaryfile used to describe data from a file of a different name, you must alsoenter the data file name in the next column.

Data File Select the data file from the Data File list.Key SourceField

If a primary file, the field is not editable, as the primary file is not accessedthrough a key source file. The RedBack Object Server accesses the primaryfile by using the key data from the RBO class definition. As with otherapplication objects, the key data passed to the read method describes asingle 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 physicalfile. The value must be an existing field name in the collection of selectedfield 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 databaseitem, or can be a virtual field that derives a value. For example, considera file with a multivalued list of product numbers. The key to a secondfile can be made up of the key to the first file, an asterisk, and then theproduct number. You can create a virtual field formula to represent this.

MV Key If a primary file, the field cannot have a multivalued key. For otherphysical files, if the data in the key source field is multivalued, you mustclick the cell to read “Yes.”

Note: If the MV Key field is “Yes,” and the key value contains multipleentries, the RedBack Object Server reads each individual key value. Inthis way, the RedBack Object Server can read multiple physical recordsto construct multivalued fields in the logical record. Only a single valueis taken from each physical item read. If the field is “No,” the RedBackObject Server performs a single read.

Fields Select the fields from the primary dictionary that you want to include inthe logical file definition. Field names can refer to a physical location in arecord, or can be virtual fields that derive a value.

Note: Selected field names must be unique across the logical filedefinition. 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 currentlyselected one.

5. After you enter information for all physical files to be included in the logical file definition, clickthe Save icon or select File → Save, and enter a unique name for the new logical file.

Creating a subroutineYou can use the Web Designer code editor to create and edit the code for subroutines that are storedon the RedBack Object Server.

Creating a subroutine

23

Prerequisites▪ Defining properties of the RBO, on page 17

▪ Defining methods of the RBO, on page 19

Procedure



3. Click in the Description 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 thePostRead 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 Designerprovides a template text file, Includetemplate.txt, in the directory in which the productwas installed. Modifying this template determines the contents that appear when creating asubroutine.

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 thesubroutine. You might want to add a compile directive in your program to override this defaultand manually recatalog the program from the command line prompt.


24

Editing a subroutine

You can edit an existing subroutine by using the code editor.

Prerequisites▪ Defining properties of the RBO, on page 17

▪ Defining methods of the RBO, on page 19

▪ Creating a subroutine, on page 22

Procedure



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.

25

Chapter 4: Developing server code for RBOsThe 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, andthen setting properties to return to the calling client application, invoking business logic code. Thisinteraction with the RBO structure is achieved by calling RBO API function.

Server API functionsThe following sections describe the server API functions.

RBO.createObject()

Syntax

Status = RBO.createObject(className, handle)

Description

The RBO.createObject function creates an instance of the class you specify and returns a handle to theobject 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 andmethods of that class.

Note: The className must be the RBO name and not the module:RBO name. You can onlyreference 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)

Description

The RBO.getProperty function returns the value of a property that you specify for the objectreferenced 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. Ifno error occurs, the function sets Status to RBO.NO.ERROR.

Chapter 4: Developing server code for RBOs

26

In the following example, the RBO.getProperty function returns the current salary in the argumentvalue. 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 inthe 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)

Description

The RBO.setProperty function sets the value of a property that you specify for the object referencedby handle. If the property is from the current object from which the method is called, you do not passanything 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)

Description

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, thefunction 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 deptHandlehandle.

Status = RBO.callMethod(deptHandle, 'CheckSalary')

RBO.setError()

27

RBO.setError()

Syntax

RBO.setError(text)

Description

The RBO.setError function sets the error message that is passed back to the client for displaypurposes. 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)

Description

The RBO.getDBVals function enables you to retrieve the field values that are received from the U2 dataserver before assigning them to the associated property of an RBO. You can call GetDBVals only froma postRead, preWrite, or postWrite method, and you can use only valid database field names (not RBOproperty names). You can retrieve multiple property names, delimited by @AM.

RBO.setDBVals()

Syntax

RBO.setDBVals(names, values)

Description

The RBO.setDBVals function enables you to manipulate field values that are received from the U2data server before assigning those values to the associated property value of an RBO. You can callsetDBVals 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);


28

WW.FILEVAR.S

Syntax

WW.FILEVAR.S(fname, mode, f.var, err)

Description

The WW.FILEVAR.S subroutine opens and closes files, and maintains the list of open file names andassociated file handles. This subroutine provides additional error handling options and a logical closeoperation, which is not supported by the WW.OPEN.FILE function.

The following table describes the parameters.

Table 5: WW.FILEVAR.S parameters

Parameter Description

fname The name of the file to open or close.

-1 clears the file handle secondary cache.mode 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. WebDE effectively closes the file, and then opens it. Forcing a file to open is useful foropening 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 followingformats:

▪ nwhere n is an attribute in item ERRORS in WWTEXT.

▪ Unwhere n is an attribute in item ERRORS in SHAREDTEXT or in xxTEXT.

▪ stringwhere string is the text to display.

▪ n:VM:data1:VM:data2:VM ...

Caching and storing file handles

29

where n is attribute n in item ERRORS in the file WWTEXT, substituting <1> with data1, <2> withdata2, and so on.

▪ Un:VM:data1:VM:data2:VMwhere n is attribute n in item ERRORS in the file. SHAREDTEXT or xxTEXT, substituting <1> withdata1, <2> with data2, and so forth.

Note: When an error condition occurs, all subsequent server event handling ceases. To send backapplication 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. Youcan write a subroutine that opens files and stores their handles in COMMON , and call the subroutineon connection start. You can also use the file open API, WW.FILEVAR.S, which returns a handle of thefile 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 theapplication. 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 aremote file pointer (Q-Pointer) called QFILE and writes it to the VOC file. The program now callsWW.FILEVAR.S to open the file. The program returns the file handle and the name 'QFILE' is storedin 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 firstcall returns the file handle of the first file. This is because the same file name is being usedfor different files. In this type of situation, the file handle cache should not be searched whenrequesting 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 youopen 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 mightnot be relevant. It might be more appropriate to use existing code and call it during a connectionstartup.

Essentials to add to a BASIC subroutineEvery UniVerse BASIC or UniBasic subroutine should include the following statement to ensure thatyou 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 CheckSalarymethod 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*


30

* now get the salary enteredStatus = RBO.getProperty('', 'Salary', SALARYVALUE)IF Status # RBO.NO.ERROR THENStatus = RBO.setError("CANNOT GET SALARY")RETURNEND* now get the department enteredStatus = RBO.getProperty('', 'Department', DEPTVALUE)IF Status # RBO.NO.ERROR THENStatus = RBO.setError("CANNOT GET DEPARTMENT")RETURNEND** now check if we have an instance to the department RBO and if not then create oneStatus = RBO.getProperty('', 'depObj', DEPTHANDLE)IF Status # RBO.NO.ERROR THENStatus = RBO.setError("CANNOT GET DEPARTMENT HANDLE")RETURNEND*IF DEPTHANDLE = "" THENStatus = RBO.createObject("Department", DEPTHANDLE)IF Status = RBO.NO.ERROR THENStatus = RBO.setProperty('', 'depObj', DEPTHANDLE) ; * set handle for subsequent callsIF Status # RBO.NO.ERROR THENStatus = RBO.setError("CANNOT SET DEPARTMENT HANDLE")RETURNENDEND ELSE RETURNEND** now set the salary value and call the check salary method in department instanceRBO.setProperty(DEPTHANDLE, "Salary", SALARYVALUE)* now set the current department for this employeeRBO.setProperty(DEPTHANDLE, "CheckDept", DEPTVALUE)* now check the salaryRBO.callMethod(DEPTHANDLE, "CheckSalary")* now check the statusRBO.getProperty(DEPTHANDLE, "SalaryStatus", SALSTATUS)IF SALSTATUS = 0 THEN ; * ok so leaveRETURNEND* 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 subroutinesthat you want to call in the SESSION.EVENTHANDLERS item in the WWCONTROL file. All Web DE-enabled U2 accounts share the WWCONTROL file.

The fields of the SESSION.EVENTHANDLERS item are as described in the following table.

Status values returned from RBO function calls

31

Table 6: RBO function status values

Field Description

Att1 Reserved.Att2 Reserved.Att3 Reserved.Att4 Reserved.Att5 Subroutine to call on connection start (applicable only when WWCONTROL is

used).Att6 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 equatedin WWINSERT RBO.H.

Table 7: RBO function status values

Function Description

RBO.NO.ERROR No errors occurred.RBO.BAD.ARRAYSIZE Invalid parameter array size.RBO.BAD.OBJECT Object not found.RBO.BAD.CLASS Class not found.RBO.BAD.PROPNAME Property not found.RBO.BAD.PERMS Permission denied.RBO.ERROR Generic error code.

32

Chapter 5: Testing RBOsThis 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 loggingYou can use RBO debug logging to track values of RBO properties between method calls, as well asprofile the time taken to run a method. Web DE provides a way to automatically log property values aswell 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 orUniVerse 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 theRedBack Object Server internal debug logging program from a method. The RedBack Object Serverplaces 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 followingexample:

001 RBO Debug002 RBO Object Name003 RBO Method Name004 Session ID005 Start timedate006 Finish timedate007 ___Start timedate________________________________________008 property1=value1009 property2=value200n …00n property=value00n ___Finish timedate_______________________________________00n property1=value100n property2=value200n …00n property=value

debug_id property

33

debug_id property

The debug_id property is of type String, and allows you to specify the name of the debug log item theRedBack Object Server writes to the WWLOG file. If you do not specify a value, the key has the format ofclassname.methodname.sessionid. Otherwise, the RedBack Object Server saves the item asdebug_id.value.methodname.

The following is an example item list from the WWLOG file:

LIST WWLOG 19:14:53 MAR 28 2001 1WWLOG...................................................debug_test.ReadDataEmployee.Clear.12141Employee.ReadData.121413 records listed

Debug log information

The RedBack Object Server saves all debug information to items in the WWLOG file. This file is adirectory type file, allowing convenient access at the operating system level. The RedBack ObjectServer saves all items in the format of classname.methodname.sessionid, unless you specifyotherwise 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 onthe Employee RBO, with the debug property flag set to 2. This setting shows the start and finish timesof the method call, as well as the property values at the start and finish times:

RBO DebugEmployeeReadData18:57:32 Mar 28 200118:57:33 Mar 28 2001___18:57:32 Mar 28 2001_________________________EmpId=1006debug=2FirstName=LastName=ImageFile=Salary=HireDate=Interests=Dept=dict_file=EMPLOYEESdata_file=EMPLOYEESDeptCodes=DeptDescs=.....___18:57:33 Mar 28 2001_________________________EmpId=1006debug=2FirstName=MarioLastName=DelasImageFile=emp_mario_delas.jpgSalary=990.00

Chapter 5: Testing RBOs

34

HireDate=05/08/1998Interests=MusicDept=3dict_file=EMPLOYEESdata_file=EMPLOYEESDeptCodes=DeptDescs=.....

Web DE also logs debug information to the COMO files. This information is a summary of the itemssaved to the WWLOG file; it includes the name of the item, the debug flag used, and the start and finishtimes 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 2010WW.RBO.DEBUG: Employee.ReadData.12141 - 2 - 18:57:32 Nov 19 2010WW.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 methodexecution 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 debuginformation 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. Itstarts and completes log properties.

SUBROUTINE RBO.TEST2*$INCLUDE WWINSERT STD.H$INCLUDE WWINSERT SB.COMMON* Log method startedCALL WW.RBO.DEBUG('2')* Body of MethodCALL WW.SB.COMMON(1, ERR)USERDATA(1) = "UserData1!"CALL WW.SB.COMMON(4:AM:6, ERR)* Log method completedCALL WW.RBO.DEBUG('4')*RETURN*END

RBO testing overview

35

RBO testing overviewThe RedBack Object Server processes method calls on objects on request. Using this messagingsystem, Web DE provides an RBO testing tool that you use to test your RBOs in isolation, without theneed 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 isolatingproblems. If there is a problem when calling a method from a RedBeans or RedPages.NET form, butthe method call works from the RBOScope testing tool, the problem points to the client code ratherthan 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 onthe client. It uses a “live” RedBack object from the RedBeans.jar API and requires a valid setting inthe rgw5.ini configuration file.

An Eclipse-based version of the RBOScope testing tool is built into Web Designer. Using this tool, youcan test RBOs from within Web Designer.

A JSP version of the RBOScope testing tool is also available in Web DE. Using this tool, developers cantest 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 withoutleaving 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 theRedBack Object Server Connection wizard to access the RedBack Object Server. If your connectiontimes 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.


36

2. From the RBO List, U2 Resource, or RBO Hierarchy view, right-click the name of the RBO you wantto test, and click Test RBO.

Figure 5: RBOScope testing tool

Testing an RBO

1. To open the RBOScope testing tool, select Window → Show View → RRBOScope 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 testingtool 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 valuesfor the RBO properties. If the method call affected any of the RBO’s properties, the updatedvalues are displayed in the Value column.

5. To monitor the performance of method calls to the RBO, click Start Performance Monitor. Thisopens 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 Changerlist.

Accessing the stand-alone JSP RBOScope testing tool

37

The Open in new tab check box is selected by default. With this check box selected, the tab forthe current RBO remains, and the selected RBO opens in a new tab. If you want the selected RBOto 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 testingtool, 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 developmentenvironment.

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 bedifferent depending on your installation. These steps assume you have chosen the defaultpaths 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 ofthe 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.

http://localhost:8080/rboscope

http://localhost:8080/rboscope/RBOScopeLogin.jsp


38

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.inifile. When configured to a specific encoding type, the JSP RBOScope testing tool will support anysession 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.

Configuring the encoding of the JSP RBOScope testing tool

39

3. Save and close the file.

40

Chapter 6: RBO debug loggingYou can use RBO debug logging to track values of RBO properties between method calls, as well asprofile the time taken to run a method. Web DE provides a way to automatically log property values aswell 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 orUniVerse BASIC SELECT verb that the RedBack Object Server uses to perform a selection.

debug propertyThe debug property is of type String. You can set the debug flag, which is used to automatically call theRedBack Object Server internal debug logging program from a method. The RedBack Object Serverplaces 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 followingexample:

001 RBO Debug002 RBO Object Name003 RBO Method Name004 Session ID005 Start timedate006 Finish timedate007 ___Start timedate________________________________________008 property1=value1009 property2=value200n …00n property=value00n ___Finish timedate_______________________________________00n property1=value100n property2=value200n …00n property=value

debug_id propertyThe debug_id property is of type String, and allows you to specify the name of the debug log item theRedBack Object Server writes to the WWLOG file. If you do not specify a value, the key has the format ofclassname.methodname.sessionid. Otherwise, the RedBack Object Server saves the item asdebug_id.value.methodname.

The following is an example item list from the WWLOG file:

LIST WWLOG 19:14:53 MAR 28 2001 1WWLOG...................................................debug_test.ReadDataEmployee.Clear.12141

Debug log information

41

Employee.ReadData.121413 records listed

Debug log informationThe RedBack Object Server saves all debug information to items in the WWLOG file. This file is adirectory type file, allowing convenient access at the operating system level. The RedBack ObjectServer saves all items in the format of classname.methodname.sessionid, unless you specifyotherwise 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 onthe Employee RBO, with the debug property flag set to 2. This setting shows the start and finish timesof the method call, as well as the property values at the start and finish times:

RBO DebugEmployeeReadData18:57:32 Mar 28 200118:57:33 Mar 28 2001___18:57:32 Mar 28 2001_________________________EmpId=1006debug=2FirstName=LastName=ImageFile=Salary=HireDate=Interests=Dept=dict_file=EMPLOYEESdata_file=EMPLOYEESDeptCodes=DeptDescs=.....___18:57:33 Mar 28 2001_________________________EmpId=1006debug=2FirstName=MarioLastName=DelasImageFile=emp_mario_delas.jpgSalary=990.00HireDate=05/08/1998Interests=MusicDept=3dict_file=EMPLOYEESdata_file=EMPLOYEESDeptCodes=DeptDescs=.....

Web DE also logs debug information to the COMO files. This information is a summary of the itemssaved to the WWLOG file; it includes the name of the item, the debug flag used, and the start and finishtimes for the method called.

Chapter 6: RBO debug logging

42

The following example illustrates a COMO file listing the debug information:

COMO UO.SPIDER_393310 established 15:21:39 19 Nov 2010WW.RBO.DEBUG: Employee.ReadData.12141 - 2 - 18:57:32 Nov 19 2010WW.RBO.DEBUG: Employee.ReadData.12141 - 4 - 18:57:33 Nov 19 2010

Manually invoking the RBO debug processAlthough Web DE provides functionality to automatically log property values as well as profile methodexecution 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 debuginformation 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. Itstarts and completes log properties.

SUBROUTINE RBO.TEST2*$INCLUDE WWINSERT STD.H$INCLUDE WWINSERT SB.COMMON* Log method startedCALL WW.RBO.DEBUG('2')* Body of MethodCALL WW.SB.COMMON(1, ERR)USERDATA(1) = "UserData1!"CALL WW.SB.COMMON(4:AM:6, ERR)* Log method completedCALL WW.RBO.DEBUG('4')*RETURN*END

43

Chapter 7: Creating HTML documentation forRBOs

An automatic documentation tool is available from the Tools menu in Web Designer. This tool parsesall 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 accountserver. For example, /U2/U2WDE521/UVserver/rbexamples. This location contains aDocumenta000 folder that contains all the HTML files for modules, classes, and more that therbexamples account uses. The index-all.html file organizes all these .html files for you. Whenyou generate your own HTML documentation, the files will be similar but placed in a location of yourchoosing.

Generating RBO HTML documentationTo generate RBO HTML documentation, make sure that a Web DE-enabled U2 account is connected tothe 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 HTMLdocumentation.

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.

44

Chapter 8: Setting up remote procedure callsThe 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 overviewThe RPC protocol is an alternative to using RBOs. Web DE RPC allows you to call a UniVerse BASIC orUniBasic 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 toimplement 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 selectcannot gather the data, and you do not want to use an SLRBO to return delimited strings thatrepresent 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 ofyour application outside of Web DE.

Setting up RPCsTo 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 therbdefn account.

▪ If the account is a UniData account, create a DIR-type item in the VOC file pointing toWWPROGS in the rbdefn account.

4. Enter the following command::RUN WWPROGS ENABLE.RBO

Results

The WW.RPC program reads the first parameter in your request, which indicates which subroutine tocall. After calling the subroutine, the program passes your second and third parameters as the firstand second parameters to your subroutine. Web DE uses a third parameter to receive the attributemark-delimited list of data from the subroutine. The RedBack client components convert this attributemark-delimited list of data into the appropriate record and set of records for the calling program.

Writing an RPC subroutine

45

Web DE checks for the first repeating name in the list to determine where to break the returning list ofdata 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, FIRSTNAMEand LASTNAME.

Writing an RPC subroutineThe 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 mark delimited “name=value” pairs, asshown 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 rbexamplesaccount. 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

Chapter 8: Setting up remote procedure calls

46

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=”:COUNTEND ELSE STATUS = 1 MESG = FNAME:’ NOT OPENED!’END*RETURNEND

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 moreinformation 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”);

Using the Overload RPC

47

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 oneString param1 = “myparam1”;// set param2 as required by subroutine you are going to callString param2 = “param”;// call subroutine, getting back a recordset or null objectRecordSet 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();}

Using the Overload RPCThe overload RPC call supports a dynamic argument string of any number of arguments supportedby the unisubroutine in UO.NET and UniObjects for Java. The overloaded callRPC returns a stringinstead of a recordset and the arguments must be cast as objects.

Example

The following example illustrates a Web DE overload RPC call. The first argument must always be thesubroutine name being called.

Connection conn = new Connection(account);RedObject rpc = new RedObject(conn, "");String mysubroutine = "EMP.RPC";String arg1 = "READ" + (char)254 + "EMPLOYEES" + (char)254 + "1001";String arg2 = "";String result = rpc.callRPC ((Object) mysubroutine, (Object)arg1, (Object)arg2);System.Console.Out.WriteLine(result);

48

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

49

Chapter 9: Introduction to the Web DE-SB/XAinterface

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 thebackend. The support is built into Web DE, making Web DE SB/XA-aware, and not the opposite. Forthis reason, you may have to modify existing SB/XA applications to indicate that communication withSB/XA may be from a web browser rather than the customary Telnet session.

Compliant SB/XA processes and functionsFrom 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 placeon 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 notinvolve 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 interfacedoes not provide full access to all of the SB/XA environment, such as input and output processeslike 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 usingWeb 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 canspecify a date and time to start. When running a job schedule from Web DE, you must specify a startdate 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 CheckDD-DD field to “-”.

Chapter 9: Introduction to the Web DE-SB/XA interface

50

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 versionsSB/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 followingvalues:

▪ 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 RBOmethod.

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 determinefrom 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>, whichnormally provides an indication of the type of terminal you are using. When Web DE is interacting withSB/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 toSB.DISP() do not cause the process (or backend) to hang while waiting for input.

Compatibility of the COMMON blockSB/XA BASIC programs use a COMMON block that enables passing variables between programs. TheCOMMON 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 programsmust 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.x3.4.0 3.4.x through 4.2.x4.3.0 4.3.x through 4.5x, and 5.x

Web DE and SB/XA coexistence

51

COMMON block Compatible SB/XA version

6.0.0 6.x

Web DE and SB/XA coexistenceWeb DE and SB/XA share the xxDRIVERS system files. There should not be any conflicts between WebDE 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/XAdrivers.

The system ID can be specified in SBProcess(). If the system ID is invalid, it defaults to the firstsystem ID, SBSYSMENU. If the system ID is not specified, it defaults to the Web DE application ID. If theapplication ID is null, the system ID defaults back to SBSYSMENU.

52

Chapter 10: Using the Web DE-SB/XA interfaceTo use the Web DE-SB/XA interface, you first need to set up an account that can be used for both WebDE 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 accountBefore you can run SB/XA processes from Web DE, you must first set up the account for use with bothWeb 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 samecomputer. This is required to create an environment in which Web DE and SB/XA cancommunicate.

▪ 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\U2WDE521\UDserver\rbdefn\WWPROGS 003= C:\U2\U2WDE521\UDserver\rbdefn\D_WWPROGS

Note: When creating the VOC pointer, use the path of the directory in which Web DE isinstalled, 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, inwhich 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 UniVersecommand 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 WebDE-enabled U2 account to ensure that the correct system programs are set up for that versionof SB/XA.

4. If necessary, repeat steps 2 and 3 as many times as needed for your accounts to refresh pointers.

Setting up security associations

53

Results

WW.INITIATE sets up the Web DE or SB/XA programs for the current version of the SB/XA server byfinding the version details in $SB.RELEASE (VOC).

The appropriate system programs and COMMON variables, including SB.COMMON andSB.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 ObjectServer or SB/XA server. This is accomplished through the WW.SB.RB program and the RedBackenvironment variable.

Setting up security associationsWhen running SB/XA processes from Web DE, SB/XA process security restrictions are applied. It isimportant to make sure that you are using the correct SB/XA user name. The user name is set througheither 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 RBOScopetesting tool, you can specify any Web DE user name, for example, rbadmin. The user name must beassociated 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. Youcan 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 byWW.INITIATE.

Procedure

1. From the operating system prompt, start a UniData ECL or UniVerse TCL session in an SB/XA- orWeb 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.xand 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 ordelete 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 standardSB.LOGIN for an SB/XA session or the standard SPIDER program for a Web DE session.

Properties and methodsYou can call an SB/XA process in Web DE using the Execute method or a user-defined method. Youmust call these methods from a user class that inherits from the sbObject class, and you must have a

Chapter 10: Using the Web DE-SB/XA interface

54

valid SB/XA process defined in the process_name property. Once you define the user class and thecorresponding 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 processesand accessing UniData or UniVerse databases.

The sbObject class properties and methods are described in the following tables.

Table 9: sbObject properties

Property name Description

process_name The process name to execute.parameter An optional parameter.system_id Optional. Specifies the system ID. If you do not specify this

parameter, it defaults to the Web DE application ID. For moreinformation, see Web DE and SB/XA coexistence, on page 51.

sb_user_id Optional. An SB/XA user name. If you do not specify this value, thevalue defaults to the SB/XA user name associated with the Web DEuser name (generally UNKNOWN).

You must enable the Web DE user for SB access. For moreinformation, see Enabling Web DE in an SB/XA account, on page52.

sb_password Optional. The SB/XA password corresponding to thesb_user_id property. If you do not specify this value, NULL isassumed.

The value of the sb_password property is transferredunencrypted between the web server and the RedBack ObjectServer in the Web DE proprietary protocol.

value The SB/XA COMMON variable @VALUE.rtn.flag The SB/XA COMMON variable @RTN.FLAG.userdata# The SB/XA COMMON variable @USERDATA(#).server_status The status of the server after the Execute method. Nonzero

means there was an error.server_message If server_status is a nonzero value, this property contains the

corresponding error.

Table 10: sbObject methods

Method name Description

Execute Executes the process, as specified in the propertyprocess_name within system_id and passing parameter.

Refresh Populates the result set to user interface with server state andchanges. You can use this to reset the user interface to a knownstate if a user wants to cancel last user interface changes.

User-defined method

55

Method name Description

PostCreateServerEvent A server event triggered after the object has been created on theRedBack Object Server.

Server events are predefined events to which applicationdevelopers 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 theWeb 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 therequired process.

Note: The executive method provides server_status and server_message. User-definedmethods in an sbObject class must pass these properties back manually to update the client on thestatus 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 detailsPROCID = ''PARAM = ''SYSID = ''*ERR = RBO.getProperty('', 'process_name', PROCID)IF ERR THENRB.RTN.INFO = 'ERROR ':ERR.CANNOT.FIND:VM:'process_name'RETURNENDERR = RBO.getProperty('', 'system_id', SYSID)* Extract Process detailsZ = INDEX(PROCID, COMMA, 1)IF Z THENPARAM = PROCID[Z+1, LEN(PROCID)]PROCID = PROCID[1, Z-1]END* ParameterERR = RBO.getProperty('', 'parameter', P)IF NOT(ERR) THEN PARAM = P* System IdERR = RBO.getProperty('', 'system_id', SYSID)* ProcidIF PARAM > '' THEN PROCID = PROCID:COMMA:PARAMSet COMMON from State* Get value, rtn.flag and userdata()CALL WW.SB.COMMON(1, ERR)IF NOT(ERR) THEN

Chapter 10: Using the Web DE-SB/XA interface

56

* Call SB+ ProcessCALL WW.SB.PROCESS(PROCID, ERR)IF NOT(ERR) THEN* Set State from COMMON* Update parameter, value, rtn_flag and userdataCALL WW.SB.COMMON(4:AM:6, ERR)ENDEND* Server statusSTATUS = 0MESG = "IF ERR THENSTATUS = ERRMESG = 'ERROR in USER.RBO1'ENDERR = RBO.setProperty(",'server_status',STATUS)ERR = RBO.setProperty(",'server_message',MESG)*RETURN

57

Chapter 11: Web DE subroutines for SB/XAaccess

The following sections detail the methods that the SBProcess() and customer user handlermethods 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 asRecordSet.

The COMMON variables available are listed in the following table.

Table 11: COMMON variables

Variable Description Actions value

RECORD Set to null.

Set from RecordSet

1

3KEY Set to null.

Set from RecordSet

1

3WORK Set to null. 1OTHER.REC Set to null. 1LF.INFO Set to null. 1CNT Set to ‘0’ 1ACTION Set to ‘0’ 1LINE `Set to null. 1MAINFILE Set to null.

Get from RecordSet

1

3F.FILE Set to null.

File handle if MAINFILE is not null

1

2

Chapter 11: Web DE subroutines for SB/XA access

58


ORIG.REC Set to null.

Get from RecordSet

1

3LOCK.KEY Set to null. 1HEAD Set to null. 1SCR.IMAGE Set to null. 1STATUS.LINE Set to null. 1BOX.CORDS Set to null. 1OUTVAL Set to null. 1OUTVAL.FLAGS Set to null. 1F.INDX Set to null. 1F.INDX.DEFNS Set to null. 1GUI Set to ‘0’ 1GUIRES Not applicable.USERDATA(1) Set to null.

Get from user data

Returned to user data

1

3

6FREE.TEMP(20) Not applicable.VALUE Set to null.

Get from value

Return to value

1

3

6RTN.FLAG Set to ‘0’

Get from rtn_flag

Return to value

1

3

6PARAM Set to null.

Get from parameter

Return to value

1

3

6REFRESH Set to ‘0’ 1MENU.OPT Set to null. 1PROC.NAME Set to null. 1LEVEL.NO Set to ‘0’ 1FILES.OPENED Set to null. 1FILEVAR(30) Set to null.

File handle if correspondingFILES.OPENED is not null.

1

2

PARMS(40) Set to null. 1SBPARM(20) Set to null. 1OTHER(20) Set to null. 1SB.CONT Set as normal. 1CONTROL Set as normal. 1PORT Set as normal. 1SYSID Set to SB/XA system ID 1

WW.SB.COMMON()

59


ACNT.NAME Set to account name 1TERM.DEFN Set as normal.

TERM.DEFN<15>=’REDBACK’

TERM.DEFN<41>=2PRINT.DEFN Set as normal. 1PASS.DEFN Set as normal. 1USER.ID Set to SB/XA user ID (as specified

from the security association orsb_user_id property).

1

USER.KEYS Set as normal. 1PCTERM Set to ‘0’ 1F.MD File handle 1F.DMCONT File handle 1F.DMDRIV File handle 1F.PASS File handle 1F.CONT File handle 1F.PROC File handle 1F.MENU File handle 1F.DMPROC File handle 1F.DEFN File handle 1F.G.PROC File handle 1F.G.MENU File handle 1F.G.DEFN File handle 1F.DMSYSDEFN File handle 1BT.NODE(7) Not applicable.BT.LEV.NO Not applicable.BT.ID Not applicable.BT.POS Not applicable.GUIDATA Set to null. 1SBCLIENT SBCLIENT<8>

2 - RBO

SBCLIENT<9,1>

RBO class name

SBCLIENT<9,2>

RBO method name

1

RES1 Not applicable.RES2 Not applicable.

Errors codes are described in the following table.

Table 12: Err codes

Code Description

0 COMMON initialized.

Chapter 11: Web DE subroutines for SB/XA access

60

Code Description

< 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)

Description

From inside the user-defined method or subroutine, you can first call WW.SB.COMMON. This is aBASIC subroutine that sets up COMMON for you. You can then manipulate the contents of COMMON asrequired.

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 Description

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)

Description

This method validates that the SB/XA user exists by checking the Web DE-SB/XA association. If theassociation has not been specified, the UNKNOWN SB/XA user is used. This method also determineswhether the SB/XA process can be called from Web DE.

61

Appendix A: Configuration filesThe following sections describe the content of the Web DE configuration files.

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

Format

The JavaScheduler.ini file format is:

[SectionName]parameter_1=value_xparameter_2=value_y...

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

Example JavaScheduler.ini file

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

[LogLevel]logging.level=SEVERE

[Default]SchedulerPort=7070MonitorPort=7071logpath=C:\U2\U2WDE521\Javascheduler.logRbdefnPath=C:\U2\U2WDE521\UDserver\rbdefnserver=localhostuserId=cbrownpassword=2spwV0hJequEefsSBqK1KQ==ConnectionString=udcscomo=1usingssl=0sslKeyStore=PathToSSLKeystoresslKeyStorePassword=6B6jy5KN5o6l1rY5j26riQ==

[rbexamples]workdir=C:\U2\U2WDE521\UDserver\rbexamplesMinimumPoolSize=2MaximumPoolSize=2ConnectionString=udcsuserId=cbrownpassword=2spwV0hJequEefsSBqK1KQ==server=localhostcomo=1usingssl=0ThreadSocketTimeOut=1000

Appendix A: Configuration files

62

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 towrite to the JavaScheduler.log file for Web DE-enabled U2 accounts. The log level parametersare global; they apply to all Web DE-enabled U2 accounts on the RedBack Object Server computer.

The following example shows the [LogLevel] section:

[LogLevel]logging.level=SEVERE

The following table lists the available logging levels. Each level, with the exception of OFF, enablesthe logging level selected and every logging level beneath the selected level should be sent to theJavaScheduler.log file. For example, selecting the Logging level INFO includes logging at theINFO, WARNING, and SEVERE logging levels. Selecting FINE includes FINE, INFO, WARNING, andSEVERE logging levels.

Table 14: [LogLevel] section parameters

Logging level Description

OFF Log nothingALL Log everythingFINE Log general tracing informationINFO Log reasonably significant informationWARNING Log potential problemsSEVERE Log events preventing proper execution

[Default] section

The parameters in this section define Web DE system defaults. They apply to all Web DE-enabled U2accounts within the system. You can override the defaults within each [account] section.

The following example shows the [Default] section:

[Default]SchedulerPort=7070MonitorPort=7071logpath=C:\U2\U2WDE521\Javascheduler.logRbdefnPath=C:\U2\U2WDE521\UDserver\rbdefnserver=localhostuserId=cbrownpassword=2spwV0hJequEefsSBqK1KQ==ConnectionString=udcs

[Default] section

63

usingssl=0sslKeyStore=PathToSSLKeystoresslKeyStorePassword=6B6jy5KN5o6l1rY5j26riQ==ThreadSocketTimeOut=60

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

Table 15: [Default] section parameters


SchedulerPort The port number on which the Java Scheduler accepts RBO requests. Makenote of this setting when editing the rgw5.ini file.

MonitorPort The port number on which the Java Scheduler accepts monitor andmaintenance requests.

logpath The path to the JavaScheduler.log file.RbdefnPath The path to the deployed rbdefn account.server The name or IP address of the computer on which the RedBack Object Server

is installed.userId The operating system-level user ID for the RedBack Object Server computer.password The password associated with the user ID.ConnectionString Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs) or

connection.como Use this option to start or stop copying server logs to the account _PH_ file

in UniData or the &COMO& file in UniVerse.

▪ 0 – Do not save the logs.

▪ 1 – Save the logs.usingssl Specifies whether to use Secure Sockets Layer (SSL) protocol when making

connections to the U2 server.

0 – Do not use SSL.

1 – Use SSL.sslKeyStore The path to the SSL keystore for the Java Scheduler.sslKeyStorePassword The password for the SSL keystore.ThreadSocketTime

Out

The number of seconds the U2 Web DE clients (RedBeans/RedPages.NET)connections remain open without activity before they time out.

If a ThreadSocketTimeOut entry is not specified in the [Default] section of theJavaScheduler.ini file, the system will use the 8-hour timeout default.You can override this default in the [Default] section of the file.

For example, if you add ThreadSocketTimeout=60 to the [Default]section, each connection will timeout after 60 seconds of inactivity.

Continuing with this example, you can also set timeout defaults for specificaccounts in the [account] section of the file. If you specify an account in[rbexamples] and add ThreadSocketTimeout=120, all connectionsestablished for the rbexamples account will timeout after 2 minutes ofinactivity, while all other connections will timeout after 60 seconds ofinactivity, as specified in the [Default] section.


64

[account] section

The JavaScheduler.ini file contains a section for each account. The name of the section is theconnection 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 canspecify 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\U2WDE521\UDserver\rbexamplesMinimumPoolSize=2MaximumPoolSize=2ConnectionString=udcsuserId=cbrownpassword=2spwV0hJequEefsSBqK1KQ==server=localhostusingssl=0ThreadSocketTimeOut=120unirpcTimeout=100validateClient=1

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

Table 16: [account] section parameters


workdir The physical path to the U2 account on the computer on which theRedBack Object Server is installed.

MinimumPoolSize The minimum number of connections maintained in the connection pool.MaximumPoolSize The maximum number of connections maintained in the connection pool.ConnectionString Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs)

connection.userId The operating system-level user ID for the RedBack Object Server

computer.password The password associated with the user ID specified in the userId parameter.

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

If you edit and save the JavaScheduler.ini file in a text editor, thepassword is saved in plain text. To maintain server security, open and savethe JavaScheduler.ini file in Web Designer to encrypt the password.

server The name or IP address of the computer on which the RedBack ObjectServer is installed.

[account] section

65


como Use this option to start or stop copying server logs to the account _PH_file in UniData or the &COMO& file in UniVerse.


▪ 1 – Save the logs.

If this option is set to 1, the log files contain information about requestsreceived since the last time the Java Scheduler was restarted.

Information about requests received prior to restart are stored in abackup log file named after the account, which is accessible from theBackupLogs folder. The BackupLogs folder is typically located in thesame directory as the JavaScheduler.ini file.

usingssl Specifies whether to use the SSL protocol when connecting to the U2server.

▪ 0 – Do not use SSL.

▪ 1 – Use SSL.ThreadSocketTimeOut The number of seconds the U2 Web DE clients (RedBeans/RedPages.NET)

connections remain open without activity before they time out.

If a ThreadSocketTimeOut entry is not specified in the [Default] sectionof the JavaScheduler.ini file, the system will use the 8-hour timeoutdefault. You can override this default in the [Default] section of the file.

For example, if you add ThreadSocketTimeout=60 to the [Default]section, each connection will timeout after 60 seconds of inactivity.

Continuing with this example, you can also set timeout defaults for specificaccounts in the [account] section of the file. If you specify an account in[rbexamples] and add ThreadSocketTimeout=120, all connectionsestablished for the rbexamples account will timeout after 2 minutes ofinactivity, while all other connections will timeout after 60 seconds ofinactivity, as specified in the [Default] section.

unirpcTimeout Optional parameter that specifies the maximum amount of time the JavaScheduler is going to wait for a response before it considers the requestas timed out and sends an appropriate message back to the coding client.This parameter needs to be less than the unirpcTimeout parameter set inthe rgw5.ini file. Default is 300 seconds.

validateClient Specifies whether to validate client credentials before sending requeststhrough the Java Scheduler.

▪ 0 - Do not validate client credentials (default).

▪ 1 - Validate client credentials.

The client credentials (user ID and password) are validated against theuserID and password, which is also specified in the [account] section of theJavaScheduler.ini file.

[account.Environment] subsection

This subsection of the [account] section is optional. To define separate environment variable valuesin an account, insert an account environment with appropriate properties and values. In the followingexample, the rbexamples2 environment has the language set to United States English, and the timezone set to Mountain Standard Time (MST) and Mountain Daylight Time (MDT).


66

You can also customize each environment by adding Tcl (Tool Command Language) commands, whichare run when a connection is established. To enter these types of commands, complete the followingsteps:

1. Access the JavaScheduler.ini file by selecting Edit Local Java Scheduler Configurationfrom the Tools menu.

2. If separate environments do not exist, create a new one by right-clicking and selecting InsertAccount Environment from the drop-down menu.

3. Right-click on the environment and select Insert Property from the drop-down menu.4. Enter the command, (for example, RUN BP TEST) in the NewProperty field and leave the

NewValue field blank.5. Click Save to save your changes. The command you entered will run when a connection for that

environment is established.

[rbexamples]workdir=C:\U2\U2WDE521\UDserver\rbexamplesMinimumPoolSize=2MaximumPoolSize=2ConnectionString=udcsuserId=cbrownpassword=2spwV0hJequEefsSBqK1KQ==server=localhostThreadSocketTimeOut=120usingssl=0

[rbexamples.Environment]account_desc=rbexamples2LANG=en_USTZ=MST7MDTRUN BP TEST

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

Format

The rgw5.ini file format is:

[SectionName]parameter_1=value_xparameter_2=value_y...

Each section contains a set of related parameters. Web DE searches the rgw5.ini file for predefinedand 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 thenames of additional sections.

Sections of rgw5.ini file

67

Example rgw5.ini file

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

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

[Default]perfstats=0

[rbexamples]workdir=C:\U2\U2WDE521\UDserver\rbexamplesMinimumPoolSize=2MaximumPoolSize=2ConnectionString=udcsuserId=cbrownpassword=2spwV0hJequEefsSBqK1KQ==server=localhostlogpath=C:\U2\U2WDE521;SchedulerPort=7070como=1usingssl=1PoolingDebug=1IdleRemoveThreshold=15000IdleRemoveExecInterval=1000OpenSessionTimeout=1000unirpcTimeout=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 theclient log files for Web DE-enabled U2 accounts. The log level parameters are global; they apply to allWeb 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 processwith RedPagesNet.dll loaded.


68

The following example shows the [LogLevel] section:

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

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

[Default] section

The parameters in this section define Web DE system defaults. They apply to all Web DE-enabled U2accounts 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 otherdefault parameters in this section, if applicable.

Table 17: [Default] section parameters


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 theWeb DE performance monitor API, such as wait time and number of requestsprocessed for each account.

The Perfstats.log file is written to the C:\U2\U2WDEnnn directory bydefault, 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 connectionname 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 canspecify additional parameters. If you specify a parameter in the [accountname] section that is also inthe [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\U2WDE521\UDserver\rbexamplesMinimumPoolSize=2MaximumPoolSize=2ConnectionString=udcsuserId=cbrown

[accountname] section

69

password=2spwV0hJequEefsSBqK1KQ==server=localhostlogpath=C:\U2\U2WDE521;SchedulerPort=7070como=1usingssl=1PoolingDebug=1IdleRemoveThreshold=15000IdleRemoveExecInterval=1000OpenSessionTimeout=1000unirpcTimeout=500

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

Table 18: [accountname] section parameters


workdir The physical path to the U2 account on the computer on which theRedBack Object Server is installed.

MinimumPoolSize The minimum number of connections maintained in the connection pool.

Setting this value and the MaximumPoolSize value to 0 enables thedeveloper mode, which allows you to execute newly compiled codethrough Web DE processes. Instead of using a cached version of the objectcode, the developer mode allows you to pick up the new object code assoon as it is available by causing the associated database processes torestart after each method call. While allowing newly compiled code to bepicked up, this mode carries a performance overhead as the associateddatabase processes terminate and are recreated after each method calland is not recommended for “live” production use for this reason.

The SchedulerPort must also be commented out to bypass the connectionto the Java Scheduler.

MaximumPoolSize The maximum number of connections maintained in the connection pool.

Setting this value and the MinimumPoolSize value to 0 enables thedeveloper mode. See the description in MinimumPoolSize for informationabout the developer mode.

ConnectionString Specifies whether the connection is a UniData (udcs) or UniVerse (uvcs)connection.

userId The operating system-level user ID for the RedBack Object Servercomputer.

password The password associated with the user ID specified in the userIdparameter.

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

If you edit and save the rgw5.ini file in a text editor, the passwordis saved in plain text. To maintain server security, open and save thergw5.ini file in Web Designer to encrypt the password.

server The name or IP address of the computer on which the RedBack ObjectServer is installed.


70


logpath The full path of the directory in which to store client logfiles for the account on the client computer. The clientlog files are RedBeans_accountname.log andRedPages_accountname_processid.log, where processid is the IDof the Windows process with RedPagesNet.dll loaded.

The directory must already exist; Web DE does not create a new directoryfor you. If the specified logpath directory does not exist, the applicationfails at run time.

SchedulerPort The port number on which the Java Scheduler accepts requests from thisaccount.

If this parameter is commented out, and the MinimumPoolSize andMaximumPoolSize parameters are set to 0, the Java Scheduler connectionis bypassed.

como Specifies whether to save the server logs to the account _PH_ file inUniData or the &COMO& file in UniVerse.


▪ 1 – Save the logs.usingssl Specifies whether to use the SSL protocol when connecting to the U2

server.

▪ 0 – Do not use SSL.

▪ 1 – Use SSL.PoolingDebug Specifies whether to keep a log of UOJ processes for the account for

debugging purposes.

▪ 0 – Do not keep a log of UOJ processes.

▪ 1 – Keep a log of UOJ processes.encoding Allows support of any session encoding for connections using

RedPages.NET or RedBeans.IdleRemoveThreshold The number of milliseconds that a connection pool thread can remain idle

before it is flagged for removal.IdleRemoveExecInterval The number of milliseconds of the interval at which UOJ runs an

executable to remove from a connection pool any threads that haveexceeded the idle threshold.

OpenSessionTimeout The number of milliseconds for which UOJ attempts to acquire a sessionfrom the connection pool before timing out.

unirpcTimeout Optional parameter that specifies the maximum amount of time the client(RedBeans or RedPages.NET) is going to wait for a response from the JavaScheduler before it considers the request as timed out. Default is 300seconds.

71

Appendix B: Web DE with Rocket Aldon LM(e)You can integrate Web DE with Aldon Lifecycle Manager for Rocket U2 (LMU2) to manage your dataand applications through all stages of development.

LMU2 uses Rocket Aldon Lifecycle Manager (Enterprise Edition), referred to in this documentation asLM(e), to manage U2 programs, data records, and dictionary records. LM(e) provides common sourcecontrol features, such as check in and check out, and manages items in the following ways:

▪ Items move through development lifecycle stages to completion.

▪ User authorities can be set at each stage.

▪ Items can be deployed at each stage for testing or production.

▪ Items are tracked through each stage and each deployment, resulting in a clear audit trail.

To learn more about LM(e), visit https://docs.rocketsoftware.com. Navigate to Rocket Aldon →Lifecycle Manager for Rocket U2.

You need a special license to access the LM(e) functionality using Web DE. Contact Rocket U2technical support at [email protected], or Rocket Business Connect at https://rbc.rocketsoftware.com.

If you have purchased the LM(e) edition of Web DE, you will need to perform the following tasks beforegetting started with LM(e):

1. Install LM(e). Follow the instructions in the Rocket Aldon documentation at https://docs.rocketsoftware.com. Navigate to Rocket Aldon → Lifecycle Manager Enterprise Edition.

Note: You do not need to install LMU2. This component is installed automatically with yourLM(e)-enabled installation of Web DE.

2. Complete the tasks listed in the Setup chapter of the Rocket Aldon Lifecycle Manager for Rocket U2User’s Guide at https://docs.rocketsoftware.com.

3. In Web Designer, deploy the RedBack Object Server as described in the deployment chapters ofWeb DE Installation and Configuration.

4. Optional: Verify that attribute 1 of the Aldon item in WWCONTROL or WWTEXT is set to 1.

Modifying RBOsLMU2 allows you to modify RBO methods using source control, thus adding another level of security.To modify RBOs using LMU2, perform the following steps.

Prerequisites

Before editing RBOs, you need to complete the following tasks as described in the Administrator’sGuide.

▪ Create a U2 server

▪ Connect to a U2 server

▪ Enable an account for U2 Web DE

▪ Create a module

https://docs.rocketsoftware.com

mailto:[email protected]

https://rbc.rocketsoftware.com

https://rbc.rocketsoftware.com




Appendix B: Web DE with Rocket Aldon LM(e)

72

Procedure

1. From the U2 Resource view in Web Designer, expand the account you want to work with, anddouble-click U2 Web DE Elements.

2. In the RedBack Object Server Connection wizard, enter your user name and password, and clickFinish.The default user name of the administrator is rbadmin, and the default password is redback. Forincreased security, you can set up single sign-on for the user name and password to connect tothe server.After you log in with your credentials, you are signing into Aldon.

3. Expand the module containing the RBO that you want to open.The available RBOs appear as shown in the following example.

RBOs with a check mark at the bottom right of the icon (for example, "add4" in the previousfigure) indicate RBOs that are "checked out" under Aldon. When developers check out items,the items are copied from an environment in the release to the development account. As itemsare promoted through the development lifecycle, the items move from one environment to thenext in the release. When LM(e) deploys items, the items are deployed from an environment inthe release to a U2 deployment account. For more information about check outs, see https://docs.rocketsoftware.com. Navigate to Rocket Aldon → Lifecycle Manager for Rocket U2.



Modifying RBOs

73

4. Right-click the RBO you want to modify, and select Lock RBO.A dialog box appears requesting the task reference and optional task comment. This allows youto check out an RBO under an Aldon task number. You can modify multiple RBOs under the sametask. After entering the task number and comment, click OK. Alternatively, if you do not wantto enter a task reference or comment, you can click Cancel or the X to continue the RBO editingprocess without a check out. The requirement for a task is dependent on the Aldon configuration.

If you click OK, a message appears confirming the RBO was successfully checked out, as shown inthe following example.

Click OK.

Note: You can modify an RBO without entering a task reference if there is a need, such asmodifying something locally for a test. However, checking something out with a task referenceregisters the RBO for the Aldon project management and source control system.

5. Right-click the module you are working from, and select Refresh.The RBO you are modifying now appears with a check mark, indicating that the RBO is checkedout.

6. Double-click the RBO.The right pane opens, displaying the properties and methods for the RBO.

7. Modify the RBO's properties or methods as necessary.For example, follow the steps below if you want to add a new method:a. Click the Methods tab.b. Click the Insert Row icon.c. In the Name cell, enter a name for the method.d. In the Cataloged Name cell, enter a new value or select one from the list.e. Click the Edit BASIC Source Code Control icon.

A dialog box appears requesting the task reference and comment. Click Cancel. You cannotassociate a task with this new method yet because the task has not been fully created yet.Clicking Cancel allows you to create the method, then you will be able to check in the task.

A new tab appears that allows you to edit the method, as shown in the following figure.

Appendix B: Web DE with Rocket Aldon LM(e)

74

f. Edit the method as necessary. When finished, click the Save icon and close the tab.g. Add the method to source control by clicking the Add to Source Control icon.

A dialog box appears requesting the task reference and comment. Enter an associated taskand click OK.

A message appears confirming the method is now added to source control. Click OK.h. Check the method in by highlighting it and then clicking the Check in BASIC Source Code

icon.In the dialog box that appears, enter an optional comment and click OK.

8. When finished editing the RBO, right-click the RBO from the left U2 Resource pane, and select oneof the following options.

▪ Task Check In: Checks the RBO back in with the associated task entered from a previous step.Enter the task reference and an optional comment in the dialog box that appears, and clickOK.

▪ Check in RBO: Checks the RBO back in with no associated task. Enter an optional comment inthe dialog box that appears, and click OK.

Checking the LME statusAt any point, you can check the LM(e) status to view what RBOs, methods, or properties are checkedout or checked in. You can also view the type of file, such as data or source code, at any time.

From the U2 Resource pane, right-click an RBO, and select Check LME Status.The LME Status window appears, as shown in the following figure.

Checking the LME status

75

In the previous figure:▪ The "O" status indicates that the item is checked out.

▪ The "-" status indicates that the item is checked in.

▪ The "*" type indicates that the item is a data type.

▪ The "P" type indicates that the item is a source code type.

For more information about other LM(e) statuses and types, see https://docs.rocketsoftware.com.Navigate to Rocket Aldon → Lifecycle Manager for Rocket U2.


Documents

Version 5.3.0 Environment - Rocket Softwaredocs.rocketsoftware.com/nxt/gateway.dll/RKBnew20/... · Rocket U2 Web Development Environment Web Designer User’s Guide Version 5.3.0