red pages

A WEB APPLICATION DEVELOPMENT TOOL

RedBack®B

RedPages

All rights to this publication are reserved. No part of this document may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language, in any form or by any means, without prior written permission from Informix Software, Corp. If you are a licensed user of this product, Informix Software, Corp. grants you a limited, nontransferable license to reproduce this particular document. This is limited to photocopy reproduction of a Informix Software-supplied master copy. Copies must include all pages contained in the master copy (including this page) and must be intended strictly for internal distribution and use by the licensee, its employees, and assigns. Reproduced copies may not be transferred, in whole or in part, to any party outside the licensee’s place(s) of business. The software described in this document is furnished under a license agreement. The software may be used or copied only in accordance with the terms of the agree-ment. It is against the law to copy this software on magnetic tape, disk, or any other medium for any purpose other than the licensee's personal use.

Copyright © 2001 Informix Software, Corp.All Rights ReservedRedBack Release 4Documentation DRB-3007Rev.01102000

Informix Software, Corp., reserves the right to make changes to this document and the software described herein at any time and without notice. Informix Software, Corp. makes no warranty, express or implied, other than those contained in the terms and conditions of sale, and in no case is Informix Software, Corp. liable for more than the license fee or purchase price of this product.

Informix Software, Corp.4100 Bohannon Drive

Menlo Park, CA 94025 USA

Phone: (650) 926-6300Fax: (650) 926-6593

World Wide Web: www.informix.com

Principal Technical ProvidereTeam Software

Contributors and Technical ReviewersTim Berry, Mark Chazan, Wayne Fox, Jürgen Joarder, Nghia La, and Colin Reyburn.

Informix Software is a trademark of Informix Software Corp. RedBack, uniVerse, UniData, SB+, SBOPEN, SBClient, SBDesktop, ObjectCall, EasyX, DataStage, ESL, UniVerse Call Interface, UniVerse Objects, uV/Net, RetrieVe, PI/open and Prime INFORMATION are trademarks of Informix Software, Corp. Pick is a regis-tered trademark of Pick Systems. Microsoft, Windows, Windows NT, ActiveX and Visual Basic are registered trademarks of Microsoft Corporation in the United States and or other countries. UNIX is a registered trade-mark in the United States and other countries, licensed through X/Open Company. Java, and JavaBeans are a trademark of Sun MicroSystems. Delphi is a trademark of the Inprise Corporation. All other products, stan-dards, or company names mentioned may be trademarks or registered trademarks of their respective owners.

Contents

Chapter 1 - Installation ..................................................................13

Installation Details ....................................................................................14

Chapter 2 - Introduction ................................................................15

What are Active Server Pages? .................................................................16

What are RedPages? .................................................................................18

RedPage Architecture .........................................................................18

What are RedBack Business Objects? ......................................................21

RBO Class Hierarchy ..........................................................................22

Session object ...........................................................................................24

Limitations ................................................................................................26

Chapter 3 - Using RedPages .........................................................27

Introduction ...............................................................................................28

RedObject .................................................................................................30

RedObject Properties ..........................................................................30

RedObject Methods ............................................................................35

Step-by-Step Instructions for Using RedObject .......................................38

RedPages 5

Contents

Create instance of RedObject .............................................................38

Attach a RBO Class to this object ......................................................38

Get/Set property values of the RBO and call methods .......................39

Destroy object .....................................................................................40

RedObject Code Example .........................................................................41

RedSet Object ...........................................................................................43

RedSet Properties ................................................................................43

RedSet Methods ..................................................................................47

Step-by-Step Instructions for Using RedSet .............................................51

Create an instance of a RedSet object. ................................................51

Call the Open Method .........................................................................51

Add New Records to the Object .........................................................52

Select the Current Record ...................................................................52

Get/Set Property Values ......................................................................52

Destroy the object (optional) ..............................................................52

RedSet Code Example ..............................................................................53

RedField Object ........................................................................................55

Default Property or Method ................................................................55

RedField Properties .............................................................................56

RedField Methods ...............................................................................61

Step-by-Step Instructions for Using RedField ..........................................71

Create an Instance of a RedField Object ............................................71

Assign the RedField a String Value ....................................................71

Manipulate the Field ...........................................................................72

Extract the Modified String ................................................................72

6 RedPages

Contents

Destroy the Object ..............................................................................72

RedField Code Example ...........................................................................73

ADO Object ..............................................................................................75

ADO Object Model .............................................................................75

ADO API Reference ...........................................................................75

Step-by-Step Instructions for Using ADO ................................................76

Create ADO Connection object ..........................................................76

Create an instance of the RedBack Business Object ..........................77

Call RedBack Methods .......................................................................78

Access Field Values ............................................................................79

Destroy objects ...................................................................................80

ADO Code Examples ................................................................................81

Error Handling ..........................................................................................87

Chapter 4 - RBODemo ...................................................................91

RBODemo ................................................................................................92

Design Goals .......................................................................................92

Starting RBODemo .............................................................................93

Overview - Retail Part of RBODemo .................................................94

Step 1: Entering the RedPages Shoe Store .........................................95

Step 2: Login Page ..............................................................................96

Step 3: Choose Shoe Category and Shoe Style ...................................97

Step 4: Selecting Shoes .......................................................................99

Step 5: Shopping Cart .......................................................................100

Step 6: Checkout ...............................................................................101

Step 7: Thank you .............................................................................102

RedPages 7

Contents

Detail - Employee Maintenance .......................................................103

Appendix A - RedPage Configuration Issues............................121

rgw.ini .....................................................................................................122

Example rgw.ini File Settings ...........................................................122

Logging ...................................................................................................124

Example rgw.ini File Settings ...........................................................124

Logging Levels .................................................................................124

Appendix B - RedBack Error Codes...........................................127

Error Codes .............................................................................................128

8 RedPages

Preface - Introduction to Informix Documentation

This preface contains useful information about Informix’s conventions for documenting command syntax and system output, as well as providing explanations of the specially designed icons that indicate important notes, tips, and warnings in the documentation.

Features of Informix ManualsInformix strives to produce useful, high quality documentation while maintaining a consistent look and feel. It will help you to know the following conventions which are common to this and all Informix manuals. This section explains the following:

• conventions

• elements of syntax statements

• notes, warnings, and tips

• screen captures

RedPages 9

ConventionsAll Informix manuals depict command syntax according to industry standards. The following table lists the syntax conventions:

Convention Description

bold courier font Bold courier font indicates text that you must enter in the manner shown. You must enter all punctuation marks that appear in bold, unless otherwise indicated.

courier font Courier font indicates system output, such as prompt signs, responses to commands, and program code. Courier font is also used to depict paths to directories or files.

bold Bold font indicates the name of an element on the screen, such as a menu, a form, or a prompt. It also indicates the names of files or direc-tories, and for the names of objects, properties, methods, events, func-tions, and subroutines where they appear in the main text of the manual.

lower case italics Lower case italics is used for syntactical expression of user-supplied words, variables, and expressions

xx Italic lower-case xx indicates a placeholder for an application id. For example, xxCONTROL.

<> Field, denotes a supplied name or value or an HTML tag.

> The > character separates each option in a menu hierarchy. For exam-ple, “choose Setup > Miscellaneous”, means choose the Setup menu then the Miscellaneous option.

[ ] Square brackets indicate an item that is optional. You may include a number of items enclosed in brackets in a Unidata command or func-tion.

{ } Braces indicate that you must choose one of the items separated by the vertical bar ( | ).

Conventions

10 RedPages

Elements of Syntax StatementsIn some cases you may enter as part of paragraphs. The syntax statement includes the command name, required arguments, and options that you can use with the command. Italics represents a variable that you can replace with any valid option. The following figure illustrates the elements of a syntax statement:

Important Notes, Warnings, and TipsYou will notice several different icons throughout this manual. These icons draw attention to important information about the product.

NoteA Note icon indicates important additional information on the subject.

| Vertical bar separates option arguments from which you may choose.

. . . An ellipsis (...) after an argument indicates that you may use more than one argument on a single command line.

Convention Description

Conventions (continued)

COMMAND required [option] [option1 | option2]{option1 | option2} required... "string"

command names

no brackets or bracesindicates a requiredargument

square brackets indicatean optional argument

a vertical line indicates thatyou may choose betweenthe given arguments

braces indicate that youmust choose betweenthe given arguments

an ellipsis indicates thatyou may enter more thanone argument

quotation marks

appear in boldface

must enclose aliteral string

RedPages 11

WarningA Warning icon alerts you to the danger of deleting or corrupting data.

ReminderA Reminder icon marks information that is discussed in detail in another chapter or Informix manual.

TipA Tip icon denotes shortcuts, commands, or procedures that may help you use Informix products more efficiently.

12 RedPages

Chapter 1 - Installation

This chapter provides general information about the installation of the RedBack Gateway, which contains the Redpages ActiveX component, redpages.dll.

RedPages 13

Chapter 1 - Installation

Installation Details

Microsoft’s Data Access Components (MDAC) version 2.1 or later must be installed prior to the RedBack Gateway installation. This provides the required Microsoft libraries to allow the RedPages ActiveX component to successfully communicate with the web server and ActiveX Data Objects (ADO).

Please refer to the “Getting Started” manual for a step-by-step guide to installing the Redback Gateway.

14 RedPages

Chapter 2 - Introduction

This chapter provides a general introduction to RedPages (RedBack aware Active Server Pages) with RedBack.

NoteThis manual describes the interaction of RedBack with Microsoft’s Active Server Pages technol-ogy. Due to this association all of the code examples shown in this manual refer to VBScript code inside .ASP files and it is assumed that user has some experience in ASP and VBScript.

RedPages 15


What are Active Server Pages?

Active Server Pages (ASP) is a technology available in Microsoft's Internet Information Server (IIS) that enables you to quickly and easily build interactive web pages. This is accomplished by allowing web developers to include server-side executable scripts (written in VBScript or JavaS-cript/JScript) directly in the HTML content. The scripts run on the IIS web server, before the HTML is sent to the web browser, thus allowing for dynamic generation of the HTML page at runtime.

To execute an ASP page, the web browser needs only to request an Active Server Page which has been published on the Microsoft Internet Information Server (IIS). The IIS then calls the ASP DLL, which reads the file from top to bottom, executes commands as specified in your code, and finally sends back HTML content to the web browser.

Active Server Pages use .ASP for the file extension of the basic unit of an ASP application. An ASP application can be said to be all of the .ASP files in a virtual directory and its subdirectories. ASP files consist of ASCII text and contain standard HTML tags plus script commands. Therefore, to create a .ASP file, you can simply rename an HTML file, replace the .HTM or .HTML file extension with .ASP. The Microsoft Internet Information Server uses the .ASP extension to iden-tify Active Server Pages. Whenever a web browser requests a file from IIS that ends with the .ASP extension, IIS first passes the file to the ASP module for processing. In the case of a standard .HTML file converted to a .ASP file no work is performed by the ASP module as no special script commands have been included. To develop interactive web sites, scripts needs to be added to the HTML code. Active Server Page script code is contained in a tag that begin with a "<%" and ends with a "%>".

The scripts in Active Server Pages generally generate HTML code with populated data which will be presented to the web browser.

NoteASP is not a scripting language. ASP simply provides an environment within which you can run script code from your HTML pages.

16 RedPages

What are Active Server Pages?

NoteIt is beyond the scope of this manual to explain the details of ASP. For more information, refer to the documentation provided with the ASP software or the numerous books written on the subject.

NoteScript code can be written in any language for which an ActiveX scripting engine is available. ASP as supplied by Microsoft ships with scripting engines for VBScript and JScript, both of which can be used to develop code that runs on the web server.

NoteRefer to Microsoft documentation supplied with the Microsoft Internet Information Server for more information regarding VBScript and JavaScript.

RedPages 17


What are RedPages?

RedPages is a set of ActiveX components which give access to RedBack Business Objects (RBO's) that reside in a UniVerse/Unidata database via an ADO (ActiveX Data Objects) interface. This allows for easy building of ASP applications against a Universe/Unidata database using stan-dard Microsoft protocols. Any HTML/ASP authoring tools, such as Microsoft's FrontPage and Visual Interdev may be used to design the HTML pages for your website.

Active Server Pages (ASP) connecting to the RedBack Application Server via RedPages can oper-ate and interoperate in the same ASP session with ASPs connecting to other databases. They can also be made to operate and interoperate with existing and off-the-shelf ASP applications because of ADO.

In addition to providing an ADO interface, RedPages also provides a class (called RedObject) that extends ADO to make it easier to manipulate the host RedBack objects in a standard object man-ner, ie create object, get/set properties and call methods. RedObject uses ADO internally but pro-vides a wrapper to shield the developer from needing to know ADO. Developers may choose to either use ADO directly, or use RedObjects or a combination of both.

RedBack RedPages provide the following features:

• full support for the apartment threaded model required for Active Server Pages.

• allows communication from Active Server Pages to RedBack objects and methods.

• full integration with Active Server Pages session management.

• all connection management, pooling etc is completely transparent to the Active Server Page developer.

RedPage ArchitectureRedPages functionality is provided by redpages.dll which is an ActiveX component that develop-ers can access via method calls in their scripting language. The redpages.dll runs in the same pro-cess space as the Microsoft Internet Information Server.

18 RedPages

What are RedPages?

The RedPages DLL provides communication between the web server and the RedBack gateway as shown in the following illustration:

Access to the redpages.dll is made via ActiveX Data Objects (ADO). ADO is a Microsoft technol-ogy for an application-level programming interface. ADO, is a database programming model that allows programmers to write applications over OLE DB from many programming languages including Visual Basic, Java, VBScript, JScript, and C/C++.

Designer

Gateway Requester

Web Server

Gateway Responder

Application Server

UniData

Client

In

tern

et

Web Browser

RedBack components

uniVerse

Web Server RedBack Server

RedPageActiveX

Component

Active

PagesServer OLE DB

/ADO

Scheduler

RedPages 19


The following diagram illustrates the RedBack data access architecture.

RedPages will typically be used as a mechanism to populate the data fields on a form before the HTML page is sent back to the client web browser. RedPages can also be used for queries which will return a table of data for convenient report generation.

The RedPages DLL has two sides to it. On one side it performs the functionality of rgw.dll i.e. pro-vides all of the communication ofthe RedBack Gateway Requester which in turn communicates with the RedBack Scheduler on the uniVerse/UniData backend. On other side, it is an OLE DB provider which, through ADO, exposes methods and a collection of form data fields which are name/value pairs that can be interrogated or overwritten as required.

Data Provider

ConsumerRedPages (.asp)

ActiveX Data Object (ADO)

uniVerse/UniData RDBMS

OLE DB

RedBack Gateway

20 RedPages

What are RedBack Business Objects?


RedBack enables you to design your business rules and logic using objects known as RBOs (Red-Back Business Objects) based on classes that support inheritance.

RBOs reside on the host tier and are independent of the user interface. This provides flexibility to change the user interface without having to modify the RBOs.

A visual tool called RedBack Designer is supplied as part of the RedBack product and is used to design and maintain RBOs. Another tool called the RedBack RBOScope is also provided and is used to test RBOs prior to deployment. For more details on RBOs, the RedBack Designer and the RedBack RBOScope, please refer to the “Developing With RBOs” manual.

The RedBack Business Object model provides the following major benefits:

• Freedom to design HTML pages and graphics using third party web design tools such as Visual Interdev, FrontPage, HomeSite and other HTML/ASP development tools. Accord-ingly RedBack enables developers to use either Active Server Pages (known as RedPages) or RedBack data aware Java components (known as RedBeans) when designing websites or applications.

• Ability to define business objects that contain the business logic (fields, calculations etc) using the RedBack Designer. The RedBack Designer has been designed to be quick and intuitive to use and requires almost no knowledge of the uniVerse/UniData development environment.

RedBack 4 now introduces the option of Remote Procedure Calls (RPC) which allows the user to make requests to RedBack outside of the RBO model. This may prove useful if the user needs to generate recordset output but where the data can not be retrieved from a simple SELECT state-ment. For more details please see Appendix B, RedBack Remote Procedure Calls in the “Develop-ing With RBOs” manual.

RedPages 21


RBO Class HierarchyThe RedBack Business Object hierarchy comprises the following objects (see the “Developing RBO Applications” manual for more information):

RBO

The RBO class is the superclass for all the RedBack Business Object classes.

emailObject

The emailObject class is a subclass of RBO. This class provides properties and methods to allow email messages to be sent from the Application Server.

SysInfo

The SysInfo class is a subclass of RBO. This class provides properties and methods to obtain information about the operating system, database platform and RedBack installation.

uObject

The uObject class is a subclass of RBO. This class provides properties and methods to facilitate access to uniVerse and UniData databases. Typically, any classes that need to read/write data will inherit from this class.

RBO

uObject

SysInfo

emailObject

sbObject

uQuery

22 RedPages


uQuery

The uQuery class is a subclass of uObject. This class provides properties and methods to enable queries to be run against uniVerse and UniData databases.

sbObject

The sbObject class is a subclass of RBO. This class is used to interact with SB+ applications.

RBOs are stored on the uniVerse/UniData backend and RedBack is the vehicle used to retrieve, store or update data associated with RBOs.

For example, you may want to create an RBO called “Employee”. The Employee RBO might con-tain the employee’s name, street address, starting date etc.

NoteSee the “Developing With RBOs” manual for information about building RBOs.

RedPages 23


Session object

ASP provides a Session object that stores each users state on the web server. The ASP page has access to this state and you should use it store data, handles etc. that you will need on subsequent web server submits both for the same page and other pages.

Care should be taken when using the Session object, as it has been found to result in high memory usage on the Web Server. Applications where high hits are expected may be better served by not using Session objects at all.

NoteDue to memory management issues with Microsoft Internet Information Server version 4 and ear-lier, the RBODemo application no longer uses the ASP session object as it has been observed to be inefficient.

Program Example

If IsObject(Session("EmpObj")) then ' Not first time - already have Employee object Set oEmp = Session("EmpObj")End If

First the page checks to see if we have EmpObj in the Session object. If we do then we have already created it and we can retrieve it from Session and set oEmp with its value.

After creating oEmp for the first time it is stored in Session so that subsequent page submits to the web server can retrieve it, for example,

Program Example

Set Session("EmpObj") = oEmp ' Preserve for when page recalled

24 RedPages

Session object

The Session object can also be used to store other information. For example, the EmpLookup.asp example page, stores the recordset handle and also the current page number

Program Example

' Save recordset handle for future calls to this pageSet Session("EmpRecSet") = rsSession("EmpPages") = pageCount

RedPages 25


Limitations

There is a maximum of 1024 fields that can be returned in a recordset.

There is a maximum of 512 accounts that can be setup in the rgw.ini file.

A hostname cannot be longer than 256 characters.

26 RedPages

Chapter 3 - Using RedPages

This chapter provides an overview of using RedPages (RedBack aware Active Server Pages) with RedBack.

RedPages 27


Introduction

As previously mentioned , the RedPages ActiveX component provides an ADO interface to the RedBack host server (RBO Server). ADO is designed to a be a generic interface to retrieve and update data on a host via recordset objects. These recordset objects normally deal with the result of a query on a database table.

This is not the ideal interface for manipulating data that has not been produced as the result of a query. For example, a read on an Employee record. For this reason, RedPages provides an interface to ADO through its RedObject class available from the ASP page on the web server.

The RedObject class is an additional class to make the task of interfacing to a non-query RBO easier and more intuitive. It is not necessary to use RedObjects to make full use of the RedPages functionality, as ADO is still supported, but we recommend you use this object.

Where the data has come from a query, then a RecordSet will be created. The RecordSet allows the code to move through the rows of data returned from the server, and get/set properties for the cur-rent row. Pages of data can be retrieved and then scrolled through and the result can is often dis-played in a report or lookup.

In addition to RedObject, RedPages provides two other classes called RedSet and RedField.

RedSet objects allow you to store information in the same manner as a RecordSet but without hav-ing a connection to any physical RBO on the RBO server.

The RedSet can be used to store multi-dimensional data on the client without the requirement of updating state in a server RBO. For example, the RBODemo shoe store uses a RedSet to store the contents of the basket. Rather than update a Basket RBO on the server each time a shoe is added to the basket, this information is stored on the web server using a RedSet object. This greatly reduces the need to "hit" the server and results in faster pages.

RedField objects allow for easy manipulation of dynamic multi-valued strings within the scripting language. RedField also provides other useful string functions that the Universe/UniData Basic programmer is familiar with.

For details on the properties and methods of RedObject see “RedObject” on page 30, for details on the properties and methods of RedSet see “RedSet Object” on page 43, and for details on the properties and methods of RedField see “RedField Object” on page 55.

28 RedPages

Introduction

The following diagram shows the RedPages components in relation to ASP and ADO:

In summary then the objects provided by RedPages are:

RedObject

This exposes the properties and methods of RBOs to ASP. The EMPMAINT.ASP supplied with the RBOdemo demonstration project supplied with RedBack is an example of using RedObject.

RedSet

This is used to create temporary record storage. To use this you simply define a number of fields, open the recordset and edit as required. A good example of this can be found in the shopping bas-ket in the RBOdemo demonstration project (see BASKET.ASP).

RedField

This is used to manipulate multivalue data/strings. A number of the ASP files in the RBOdemo demonstration project supplied with RedBack use RedField. See, for example, EMPMAINT.ASP.

ASP

ADO.ConnectionADO.Command

RedObject(RBO)

RedSet(local)

RedField

ADO

RedPagesOLEDBProvider

RedBackApplication

Server(RBOs)

IIS WebServer

RedPages

RedPages 29


RedObject

RedObject provides a simple interface for manipulating objects and their properties and is recom-mended instead of using ADO directly. RedObject still uses an ADO connection object to connect to the host and returns standard ADO recordsets for uQuery selects. For other RBO classes, the RedObject object keeps the state of all the properties of the RBO and application developers use standard object methodology to get/set these properties.

NoteThe RedObject class does not add any new functionality to RedPages. RedObject represents an alternative way to create and manipulate RBO objects from the client.

RedObject Properties

Account Property

Description

This is the name of the uniVerse or UniData account.

Properties Access

Account r w

ActiveConnection r w

Errors r

Password r w

Property r w

RBOClass r w

RBOHandle r w

SessionID rw

UserID r w

30 RedPages

RedObject

This can have a number of formats:

1, Accountname

This is a name given to represent a U2 (i.e. uniVerse or UniData) account. This name corresponds to an entry in the rgw.ini file which maps the name to an IP address and port number (see "rgw.ini" on page 104 for more information about this ini file).

2, IPaddress:portnumber

This format specifies the IP number for the host machine and the port number to be used to com-municate with the specific account.

Syntax

handle.Account = AccountName

sAccount = handle.Account

ActiveConnection Property

Description

This is the handle to an ADO connection object that must have been created prior to creation of this RedObject object. An ADO connection object needs only be created once per account that you are connecting to.

NoteThis property has been superceded by the Account, UserID, and Password properties and the Open2 method in release 3.2.3 of RedBack.

Syntax

handle.ActiveConnection = oConnect

oConnect = handle.ActiveConnection

RedPages 31


Errors Property

Description

This property returns the ADO Errors collection. The Errors collection contains any errors that may have been generated during an operation (see Microsoft documentation regarding ADO objects for more information).

Syntax

aErrors = handle.Errors

Password Property

Description

This is the password for the user name specified in the UserID property.

Syntax

handle.Password = "Jupiter10"

Property Property

Description

This is the property to use to get/set any of the RBO properties. As it is the default property of the RedObject class, the Property may be omitted.

Syntax

handle("PropName") = value

NoteDue to issues relating to VBScript it is recommended that handle("propname").Value = Value be used.

or

handle.Property("propname") = value

32 RedPages

RedObject

value = handle("propname")

or

value = handle.Property("propname")

RBOClass Property

Description

This is the class name of the RBO object that you want instantiated on the host (for which this RedObject object is the client proxy for).

Syntax

handle.RBOClass = RBOClass

RBOClass = handle.RBOClass

RBOHandle Property

Description

If you have a handle to an exisiting host RBO object and wish to access its properties or methods, then set this property to that handle (instead of setting the RBOClass property). You may get such a handle as a results of getting a property value on another object.

Syntax

handle.RBOHandle = value

value = handle.RBOHandle

SessionID Property

Description

This is the Session Id generated by RedBack on the application server (normally when the first request is made). Once you have a session Id, you should use if for all subsequent requests (passed as a parameter in the Open2 method. This will associate all RBO instances for a user and allow the RBOs.

RedPages 33


Syntax

handle.SessionId = value

value = handle.SessionId

UserID Property

Description

This is the user name to use when accessing a uniVerse or UniData account and RBO that has secruity restrictions applied to it.

NoteThere currently is no mechanism to apply security restrictions to an account. This property is pro-vided for when that functionality becomes available.

Syntax

handle.UserID = UserName

sUser = handle.UserID

34 RedPages

RedObject

RedObject Methods

Open Method

Description

This is used to physically create the object on the host computer. Once this method has been called, all the initial property values are available to query / set and host methods may be called. The ActiveConnection, RBOClass and RBOHandle property values may optionally be passed to the Open call. If not, they must be set before this method is called else it will fail.

NoteThis method was superceded by the Open2 method in release 3.2.3 of RedBack.

Syntax

handle.Open([oConnect], [RBOClass/RBOHandle])

Open2 Method

Description

This is used to physically create the object on the host computer. Once this method has been called, all the initial property values are avilable to query/set and the host methods may be called. This method should be used in preference to the Open method. It performs the same operation as the Open method but encapsulates the creation of an ADO Connection object that would otherwise need to be supplied in the ActiveConnection property.

Methods

Open

Open2

CallMethod

Close

RedPages 35


The Open2 method also allows client user session information to be saved on the RBO Server and therefore alleviates session management on the web server which may sometimes be a perfor-mance issue. To update client user session information to the RBO Server, the ReCalc method is recommended or any user defined method will also update the client session information to the RBO Server on execution.To restore an object’s session information the Open2 method must be called using a valid RBOHandle or valid session id. The RBOHandle is the only user session infor-mation that needs to be stored by the client (in a browser cookie for example). Please see the RBODemo Shoe Store application for an example.

WarningThe RBODemo application is an example demonstration only and real world applications will require different considerations and methodologies.

NoteThe user login and user password arguments are only used by the RedBack RBOScope applica-tion.

Syntax

Handle.Open2([Account], [RBOClass|RBOHandle], [User], [Password], [SessionId])

CallMethod Method

Description

This is used to call a method of the RBO.

Syntax

obj = handle.CallMethod(MethodName)

Where:

• obj is equal to null for any method other than Select on a uQuery object.

• Select method returns an ADO recordset.

36 RedPages

RedObject

• the session id should be passed with every Open2 method call as it will associate the cur-rent RBO with previously created RBO’s within that session instance. It is recommended that you preserve the session id after you create the first RBO so that it can be used in each subsequent Open2 method call.

Close Method

Description

This is used to close the object. Closing the object releases all resources associated with the RBO object on the client. The object may be reused by either re-opening the RBO object or by specify-ing a new RBOClass/RBOHandle and then calling Open2 again.

Syntax

handle.Close

RedPages 37


Step-by-Step Instructions for Using RedObject

These are the typical steps you use to access RedBack Business Objects on the host computer via RedObjects. For full example ASP pages to maintain a data file, and display queries, see the Emp-Maint and EmpLookup code pages in Chapter 4.

1. Create an instance of a RedObject

2. Attach a RBO Class to this object

3. Get/set property values of the RBO and call methods

4. Destroy object (optional)

Create instance of RedObject

Syntaxhandle = Server.CreateObject("RedBack.RedObject")

Attach a RBO Class to this objectUse the Open method to attach this object to a RBO. The Open will instantiate the RBO on the host and make available the getting and setting of its properties via the RedObject.

Syntax

Preferred Method

handle.Open2 Account RBOClass/RBOHandle

Alternatively, it is possible to specify the following sequence:

handle.Account = Account


handle.Open2

38 RedPages

Step-by-Step Instructions for Using RedObject

Alternate Method

handle.Open oConnect, RBOClass

Alternately, you may do the following:

handle.ActiveConnection = oConnect


handle.Open

Get/Set property values of the RBO and call methods

Get Property Value

variable = handle("propname")

or within HTML code in an ASP page :

<%=obj("propname")%>

Set Property Value:

handle("propname").Value = variable

Call RBO method

handle.CallMethod methodName

If the method is a "Select" on a RBO query object, then it returns a recordset object else a null object pointer is returned.

Program Example

Set rs = obj.CallMethod ("Select")

RedPages 39


Destroy object

Syntax

There are three steps.

Firstly it is necessary to notify the RedBack backend to destroy the RBO. The syntax to do this is:

handle.CallMethod(“Destroy”)

Next it is necessary to make the RedObject release all resources beying used by RedObject. The syntax to do this is:

handle.Close

Finally, it is necessary to notify the Microsoft IIS to release all resources associated with RedOb-ject. The syntax to do this is:

Set handle = Nothing

Program Example

oEmp.CallMethod("Destroy")oEmp.CloseSet oEmp = Nothing

40 RedPages

RedObject Code Example

RedObject Code Example

Program Example

<HTML><HEAD><TITLE>RedPages RedObject Example</TITLE></HEAD><BODY><%On error Resume Next

'1. Create a RedObject instance that will be used to communicate'with the RBO Server

'Set oEmp = Server.CreateObject("RedBack.RedObject")

'2. Attach the Employee RBO to this local object, at the same time'setting the account details

'oEmp.Open2 "RBODemo", "OFFICE:Employee"

'3. Now we can specify the read. First we set the EmpId value in the'RedObject, this is because with RedObjects, all changed data will be'sent to the server, rather than the page having to specify each data'element individually. Note: ASP has problems assigning values to a'default property so we have to explicitly specify the Value property.

''oEmp("EmpId").Value = Request.QueryString("EmpId")oEmp("EmpId").Value = "1002"' Hard coded for test runoEmp.callMethod "ReadData"

'5. Now in order to get the property values you would do the following'FirstName = oEmp("FirstName")LastName = oEmp("LastName")Response.Write ("First Name=" & FirstName & " LastName=" & LastName)

'6. Destroy the object when finished with it. This releases any resources

RedPages 41


'that it uses.'oEmp.CallMethod("Destroy")oEmp.CloseSet oEmp = Nothing%></BODY></HTML>

See “EmpMaint.asp” on page 110 for a complete listing of the program example sup-plied with RBOdemo.

42 RedPages

RedSet Object

RedSet Object

RedSet provides a mechanism to create your own local objects to save state or record information. RedSet does not make any connection to the backend but keeps the state of the object in memory.

RedSet Properties

AbsolutePosition Property

Specifies the ordinal position of a RedSet object's current record.

Syntax

handle.AbsolutePosition = 2

pos = handle.AbsolutePosition

Settings and Return Values

Sets or returns a Long value from 1 to the number of records in the RedSet object (RecordCount), or returns one of the following constants.

Constant Description

adPosUnknown(-1)

The Recordset is empty, the current position is unknown.

Properties Access

AbsolutePosition r w

BOF r

EOF r

Property r w

RecordCount r

RedSet Object Properties

RedPages 43


adPosBOF(-2)

The current record pointer is at BOF (that is, the BOF property is True).

adPosEOF(-3)

The current record pointer is at EOF (that is, the EOF property is True).

Remarks

Use the AbsolutePosition property to move to a record based on its ordinal position in the RedSet object, or to determine the ordinal position of the current record.

AbsolutePosition is 1-based and equals 1 when the current record is the first record in the RedSet. You can obtain the total number of records in the RedSet object from the RecordCount property.

You should not use the AbsolutePosition property as a surrogate record number.

The position of a given record changes when you delete a preceding record.

BOF, EOF Properties

BOF indicates that the current record position is before the first record in a RedSet object.

EOF indicates that the current record position is after the last record in a RedSet object.

Syntax

If handle.BOF then ...

If handle.EOF then ...

Return Value

The BOF and EOF properties return Boolean values.

Remarks

Use the BOF and EOF properties to determine whether a RedSet object contains records or whether you've gone beyond the limits of a RedSet object when you move from record to record.

The BOF property returns True (-1) if the current record position is before the first record and False (0) if the current record position is on or after the first record.

44 RedPages

RedSet Object

The EOF property returns True if the current record position is after the last record and False if the current record position is on or before the last record.

If either the BOF or EOF property is True, there is no current record.

When you first open the RedSet, the BOF and EOF properties are set to True, and the Recordset object's RecordCount property setting is zero.

If you delete the last remaining record, the BOF and EOF properties may remain False until you attempt to reposition the current record.

This table shows which Move methods are allowed with different combinations of the BOF and EOF properties.

Allowing a Move method doesn't guarantee that the method will successfully locate a record; it only means that calling the specified Move method won't generate an error.

The following table shows what happens to the BOF and EOF property settings when you call various Move methods but are unable to successfully locate a record.

MoveFirst, MoveLast

MovePrevious,Move < 0 Move 0 MoveNext

Move > 0

BOF=True,

EOF=False

Allowed Error Error Allowed

BOF=False,

EOF=True

Allowed Allowed Error Error

Both True Error Error Error Error

Both False Allowed Allowed Allowed Allowed

Permissable Move Methods with BOF and EOF Properties

BOF EOF

MoveFirst, MoveLast Set to True Set to True

BOF/EOF Settings With Unsuccessful Location of Record

RedPages 45


Property Property

Description

This is the property to use to get/set any of the properies in the RedSet Object. As it is the default property of the RedSet class, the Property word may be omitted.

Syntax

handle("propname") = value

value = handle("propname")

Or

value = handle.Property("propname")

handle("propname").Property = value

NoteDue to issues relating to VBScript it is recommended that handle("propname").value be used when setting a property value.

RecordCount Property

Indicates the current number of records in a RedSet object.

Syntax

count = handle.RecordCount

Move 0 No change No change

MovePrevious, Move < 0 Set to True No change

MoveNext, Move > 0 No change Set to True

BOF EOF

BOF/EOF Settings With Unsuccessful Location of Record

46 RedPages

RedSet Object

Return Value

Returns a Long value.

Remarks

Use the RecordCount property to find out how many records are in a RedSet object.

The property returns -1 when ADO cannot determine the number of records. Reading the RecordCount property on a closed RedSet causes an error.

RedSet Methods

AddNew Method

Creates a new record in the RedSet object.

Syntax

handle.AddNew FieldList, Values

Methods

AddNew

Close

Delete

Move

MoveFirst

MoveLast

MoveNext

MovePrevious

Open

RedSet Object Methods

RedPages 47


Parameters

FieldList

Optional. A single name, or an array of names or ordinal positions of the fields in the new record.

Values

Optional. A single value, or an array of values for the fields in the new record. If Fields is an array, Values must also be an array with the same number of members; otherwise, an error occurs. The order of field names must match the order of field values in each array.

Remarks

Use the AddNew method to create and initialize a new record.

After you call the AddNew method, the new record becomes the current record.

Close Method

Closes an open object and any dependent objects.

Syntax

handle.Close

Remarks

Use the Close method to close a RedSet object to free any associated system resources. Closing an object does not remove it from memory; you can still open it again later. To completely eliminate an object from memory, set the object variable to Nothing.

Delete Method

Deletes the current record.

Syntax

handle.Delete

48 RedPages

RedSet Object

Move Method

Moves the position of the current record in a RedSet object.

Syntax

handle.Move NumRecords, Start

Parameters

NumRecords

Signed Long expression specifying the number of records the current record position moves.

Start

Optional. One of the following BookmarkEnum values:

adBookmarkCurrent

Default. Start at the current record.

AdBookmarkFirst

Start at the first record.

adBookmarkLast

Start at the last record.

Remarks

If the NumRecords argument is greater than zero, the current record position moves forward (toward the end of the RedSet). If NumRecords is less than zero, the current record position moves backward (toward the beginning of the RedSet).

If the Move call would move the current record position to a point before the first record, ADO sets the current record to the position before the first record in the RedSet (BOF is True). An attempt to move backward when the BOF property is already True generates an error.

If the Move call would move the current record position to a point after the last record, ADO sets the current record to the position after the last record in the RedSet (EOF is True). An attempt to move forward when the EOF property is already True generates an error.

Calling the Move method from an empty RedSet object generates an error.

RedPages 49


If you pass the Start argument, the move is relative to the record with this.

MoveFirst, MoveLast, MoveNext, and MovePrevious Methods

Moves to the first, last, next, or previous record in the RedSet object and makes that record the current record.

Syntax

handle.{MoveFirst | MoveLast | MoveNext | MovePrevious}

Remarks

Use the MoveFirst method to move the current record position to the first record in the RedSet.

Use the MoveLast method to move the current record position to the last record in the RedSet.

Use the MoveNext method to move the current record position one record forward (toward the bottom of the RedSet). If the last record is the current record and you call the MoveNext method, ADO sets the current record to the position after the last record in the RedSet (EOF is True). An attempt to move forward when the EOF property is already True generates an error.

Use the MovePrevious method to move the current record position one record backward (toward the top of the RedSet).

Open Method

Opens a RedSet object. The field list passed to the Open method defines the fields that will be cre-ated in the internal ADORecordset object.

Syntax

handle.Open fieldlist

Where fieldlist is a comma separated list of names of properties the object should support.

Remarks

Initially the RedSet object is created with no records. No other operation is permitted until the Open method has been called to define the RedSet.

50 RedPages

Step-by-Step Instructions for Using RedSet

Step-by-Step Instructions for Using RedSet

These are the typical steps you use to create a RedSet object:

1. Create an instance of a RedSet object

2. Call the Open method

3. Add new records to the object

4. Select the current record.

5. Get/Set property values of the RedSet Object

6. Destroy the object (optional)

Create an instance of a RedSet object.This creates an empty shell for a new RedSet object. Before anything can be done with the object it must first be opened and the properties it supports defined. This is done with the Open method

Syntax

handle = Server.CreateObject("RedBack.RedSet")

Call the Open MethodCall the Open method, passing the list of property names the object should contain.

Opening a RedSet object defines the fields that will be supported in its internal ADORecordset.

Syntax

handle.Open fieldlist

Where fieldlist is a comma separated list of names of properties the object should support.

RedPages 51


Add New Records to the ObjectTo save data in the RedSet object you must first add a new record. This is done by calling the AddNew method. After you call the AddNew method, the new record becomes the current record.

Syntax

handle.AddNew

Select the Current RecordMoves to the first, last, next, or previous record in a specified RedSet object and makes that record the current record.

Syntax

handle.{MoveFirst | MoveLast | MoveNext | MovePrevious}

Get/Set Property Values

Syntax for Get Property Value

variable = handle("propname")

or within HTML code in an ASP page:

<%=handle("propname")%>

Syntax for Set Property Value

handle("propname").Value = variable

Destroy the object (optional)

Syntax

handle.Close

52 RedPages

RedSet Code Example

RedSet Code Example

Program Example

<HTML><HEAD><TITLE>RedPages RedSet Example</TITLE></HEAD><BODY><%On error Resume Next

'1. First create a RedSet object instance'Set oSet = Server.CreateObject("RedBack.RedSet")

'2. Next Open the RedSet object and define the properties or fields it will'support.

'oSet.Open "Name, PhoneNo"

'3. Now to add some records'oSet.AddNewoSet("Name").Value = "Colin Reyburn"oSet("PhoneNo").Value = "5550-1234"oSet.AddNewoSet("Name").Value = "Tony Watkins"oSet("PhoneNo").Value = "5550-1235"oSet.AddNewoSet("Name").Value = "Jurgen Joarder"oSet("PhoneNo").Value = "5550-1236"

'4. Move to the first record in the RedSet'oSet.MoveFirst

'5. Do stuff with the RedSet'Response.Write("Name PhoneNo.")

RedPages 53


While Not oSet.EOFResponse.Write(oSet("Name") & " " & oSet("PhoneNo"))oSet.MoveNext

WEnd

'6. Close and Release the RedSet object when finished.'oSet.CloseSet oSet = Nothing%></BODY></HTML>

54 RedPages

RedField Object

RedField Object

RedField is a nested data structure, that can represent uniVerse/UniData nested data-base fields. It is limited to two levels of nesting.

Notechr(253) and chr(252) are the default values for ValueMarker and SubValueMarker. It is possible to change these values using the ValueMark property.

Access to each of the two levels uses a syntax similar to that found in the uniVerse/UniData BASIC language, with nesting operators: .Value and .SubValue. In this section, the notation [.Nest-ingOp] is used to represent one of the following nesting operators:

[.NestingOp] = .Value(ValueIndex) |

.SubValue(ValueIndex, SubValueIndex) ]

Program Example

Set dyn = Server.CreateObject("RedBack.Redfield") ’ CreateObject’ Access the entire contents like a normal String (no NestingOp)dyn = "THIS" ’ default property is .StringValue’ This is how to access a ValueMsgbox dyn.Value(1) ’ result is "THIS"’ This is how to access the LAST Valuedyn.Value(-1).Ins "GREAT"’ dyn now contains "THIS<ValueMarker>GREAT"’ This is how to access a SubValuedyn.SubValue(1, 2) = "IS"’ dyn = "THIS<SubValueMarker>IS<ValueMarker>GREAT"

Default Property or MethodIf you access a RedField object without specifying a property or a method, the StringValue prop-erty is accessed as the default.

RedPages 55


RedField Properties

count Property

Description

Returns the number of values, or subvalues contained in the specified portion of the object.

Syntax

RedField[.NestingOp].count

This syntax has the following parameters:

Properties Access

count r

length r

StringValue r w

ValueMark r w

RedField Object Properties

Part Description

[.NestingOp] Can be:

• Value(ValueIndex)

ValueIndex Can be:

• between 1 and RedField.count to specify a value position.

• -1 to specify the last value position; equivalent to Red-Field.Value(RedField.count)

Parts of the Syntax

56 RedPages

RedField Object

Remarks

If .NestingOp is omitted, count returns the number of values in the object.

If .NestingOp is .Value(v), count returns the number of subvalues in value ‘v’.

If .NestingOp is .SubValue(v, s), count always returns 0.

length Property

Description

Returns the string length contained in the specified portion of the object.

Syntax

RedField[.NestingOp].length

This syntax has the following Parameters:

Part Description

[.NestingOp] Can be either:

• .Value(ValueIndex)

• .SubValue(ValueIndex,SubValueIndex)

ValueIndex Can be:

• between 1 and RedField.count to specify a value position.

• -1 to specify the last value position; equivalent to RedField.Value(RedField.count).length

SubValueIndex Can be:

• between 1 and RedField.Value(v).count to specify a sub-value position within value ‘v’.

• -1 to specify the last subvalue position; equivalent to RedField.SubValue(v,RedField.Value(v).count).length

Parts of the Syntax

RedPages 57


Remarks

If .NestingOp is omitted, length returns the total number of characters in the object, counting each ValueMarker, and SubValueMarker delimiter as 1.

If .NestingOp is .Value(v), length returns the number of characters in value ‘v’ including any SubValueMarker delimiters.

If .NestingOp is .SubValue(v,s), length returns the number of characters in subvalue ‘s’ of value ‘v’.

58 RedPages

RedField Object

StringValue Property

Description

This sets or returns in string format, the contents of the specified portion of a RedField object. If the portion already contains a string it is replaced.

Syntax

RedField[.NestingOp][.StringValue] [=String]

The syntax has the following parts:

If .NestingOp is omitted, the entire contents of the RedField object are set to String.

If .NestingOp is .Value(v), the String is set in the value ‘v’.

If .NestingOp is .SubValue(v,s), the String is set in the subvalue ‘s’ of value ‘v’.

Part Description




ValueIndex Can be:

• an integer that specifies a value position.

• -1 to specify the last value position; equivalent to RedField.Value(RedField.count+1).StringValuemeaning replace the last value.


• an integer that specifies a subvalue position within value ‘v’.

• -1 to specify the last subvalue position; equivalent to RedField.SubValue(v,RedField.Value(v).count).StringValuemeaning replace the last subvalue.

Parts of the Syntax

RedPages 59


Zero (0) values of ValueIndex and SubValueIndex are automatically translated to 1.

If ValueIndex or SubValueIndex are -1, the String will replace the last value or subvalue respectiv-iely.

Property ValueMark

Description

This property gets or sets the current integer value that is used to delimit values within a dynamic string by the RedField object. The SubValueMark is always automatically calculated as the value for ValueMark-1.

Syntax

Redfield.ValueMark = Integer

where:

Integer

is a number which represents the ASCII character.

60 RedPages

RedField Object

RedField Methods

Del Method

Description

This deletes an element (Value or SubValue) from the specified portion of the RedField object.

Syntax

RedField[.NestingOp].Del

This syntax has the following parts:

Methods

Del

Ins

Replace

SwapString

SubValue

Value

RedField Object Methods

Part Description




Parts of the Syntax

RedPages 61


Remarks

If .NestingOp is omitted, the entire contents of the RedField object are deleted.


ValueIndex Can be:

• between 1 and RedField.count to delete a nominated value position.

• -1 to delete the last value position; equivalent to RedField.Value(RedField.count).Del


• between 1 and RedField.Value(v).count to delete a nomi-nated subvalue position within value ‘v’.

• -1 to specify the last subvalue position; equivalent to RedField.SubValue(v,RedField.Value(v).count).Del

Part Description

Parts of the Syntax

62 RedPages

RedField Object

Ins Method

Description

This inserts an element (Value or SubValue) into the specified portion of the RedField object.

Syntax

RedField[.NestingOp].Ins [String]


Remarks

After insertion, all other elements after the position specified will be increased by 1.

Part Description




ValueIndex Can be:

• between 1 and RedField.count+1 to insert a nominated value position.

• -1 to append after the last value position; equivalent to RedField.Value(RedField.count).Ins


• between 1 and (RedField.Value(v).count+1) to insert a nominated subvalue position within value ‘v’.

• -1 to append after the last subvalue position; equivalent to RedField.SubValue(v,RedField.Value(v).count+1).Ins

String The contents of the element to be inserted.

Parts of the Syntax

RedPages 63


If .NestingOp is omitted, the entire contents of the RedField object are replaced with String.


If String is omitted, a NULL string (i.e. "") is inserted.

If an insertion is done into an empty or NULL string position the String simply replaces the null wihout inserting a new value or subvalue.

64 RedPages

RedField Object

Replace Method

Description

This replaces an element (Value or SubValue) from the specified portion of the RedField object.

Syntax

RedField[.NestingOp].Replace [String]


Remarks

If .NestingOp is omitted, the entire contents of the RedField object are replaced.

Part Description




ValueIndex Can be:

• between 1 and RedField.count to replace a nominated value position.

• -1 to delete the last value position; equivalent to RedField.Value(RedField.count).Replace


• between 1 and RedField.Value(v).count to replace a nomi-nated subvalue position within value ‘v’.

• -1 to specify the last subvalue position; equivalent to RedField.SubValue(v,RedField.Value(v).count).Replace

String The new contents of the element to be replaced.

Parts of the Syntax

RedPages 65


Zero (0) values ValueIndex and SubValueIndex are automatically translated to 1.

If String is omitted, a NULL string (i.e. "") is replaced.

66 RedPages

RedField Object

SwapString

Description

This method is used on an initial string to replace all occurrences of one substring with another substring.

Syntax

newstr = RedField.SwapString(oldstr,origseq,newseq)


Remarks

origseq and newseq are strings so if you wish to replace a single character they should still be passed as a string i.e. to replace all character ‘A’ with the character ‘B’ you would do a SwapString(mystring,"A","B").

NoteThe SwapString method has no effect on the current contents of the RedField object.

Part Description

oldstr The string that is to have its substrings swopped.

origseq The sequence of characters to be replaced.

newseq The sequence of characters to replace the origseq with.

Parts of the Syntax

RedPages 67


SubValue Method

Description

This is a nesting operator to access a specific subvalue, when combined with another property or method.

Syntax

RedField.SubValue(ValueIndex,SubValueIndex)


Remarks


Part Description

ValueIndex Can be:

• between 1 and RedField.count to specify an existing value position.

• -1 to specify the last value positioin; equivalent to RedField.Value(RedField.count)

• -1 or (RedField.count+1) to specify a new value position after the last one; used to insert new values with Insert or StringValue


• between 1 and RedField.Value(v).count to specify an existing subvalue position within value ‘v’.

• -1 to specify the last subvalue position; equivalent to RedField.SubValue(v,RedField.Value(v).count)

• -1 or (RedField.Value(v).count+1) to specify a new subvalue position after the last one; used to insert new subval-ues with Insert or StringValue

Parts of the Syntax

68 RedPages

RedField Object

SubValue must be combined with another property or method, otherwise it porduces an invalid object.

RedPages 69


Value Method

Description

This is a nesting operator which is used to access a specific value, when combined with another property or method.

Syntax

RedField.Value(ValueIndex)


Remarks

Zero (0) values of ValueIndex are automatically translated to 1.

Value must be combined with another property or method, otherwise it produces an invalid object.

Part Description

ValueIndex Can be:

• between 1 and RedField.count to specify an existing value position.

• -1 or (RedField.count+1) to specify the last value posi-tion; used to insert new fields with Insert or StringValue


• between 1 and RedField.Value(v).count to specify an existing value position.

• -1 to specify the last value position; equivalent to RedField.Value(RedField.count)

• -1 or (RedField.count+1) to specify a new value position after the last one; used to insert new values with Insert or StringValue

Parts of the Syntax

70 RedPages

Step-by-Step Instructions for Using RedField

Step-by-Step Instructions for Using RedField

These are the typical steps involved when using a RedField object.

1. Create an instance of a RedField object

2. Assign the RedField a string value

3. Manipulate the field

4. Extract the modified string

5. Destroy the object

Create an Instance of a RedField ObjectThis creates an empty RedField object.

Syntax

handle = Server.CreateObject("RedBack.RedField")

Assign the RedField a String ValueThis can be done in a variety of different was Using the Ins, Replace and Append methods.

Syntax

handle.StringValue = dynastring

or

handle.Replace dynastring

or

handle.Ins dynastring

or

handle.Append dynastring

RedPages 71


Manipulate the FieldThe RedField allows individual elements to be added, deleted or replaced from the string value.

Syntax

To insert element at Value position 2:

handle.Value(2).Ins StringValue

To delete SubValue 3 of Value 1:

handle.SubValue(1,3).Del

To add a new SubValue to the end of Value 2

handle.SubValue(2, -1).Append

Extract the Modified StringOnce the string has been manipulated using the RedField it can then be extracted again as a dynamic string.

Syntax

dynastring = handle

Destroy the ObjectWhen you have finished with any object it is important to close or reset the object to release any resources it may be consuming.

Syntax

handle.StringValue = ""

Set handle = Nothing

72 RedPages

RedField Code Example

RedField Code Example

Program Example

<HTML><HEAD><TITLE>RedPages RedField Example</TITLE></HEAD><BODY><%On error Resume Next

'1. Create a RedField object instance that will be used to manipulate'our string

'Set oFld = Server.CreateObject("RedBack.RedField")

'2. Create our initial string. A list of names and item counts and convert'the ':' and ',' separators into SubValue and Value Marks.

'mystring = "Colin:100,Jurgen:205,Tony:313,Mike:400"mystring = oFld.SwapString(mystring, ":", chr(252))mystring = oFld.SwapString(mystring, ",", chr(253))

'3. Assign the string to the RedField. Note: ASP has trouble making an'assignment to a default property so we have to specify StringValue'explicitly.

'oFld.StringValue = mystring

'4. Decrement the item count for each person by 10'count = 1While count <= oFld.Count

icount = oFld.SubValue(count, 2)oFld.SubValue(count, 2).StringValue = icount - 10

count = count + 1Wend

'5. Insert a new person between Jurgen and Tony. Note: ASP has trouble

RedPages 73


'making an assignment to a default property so we have to specify'StringValue explicitly.

'oFld.Value(3).Ins "Nghia"oFld.SubValue(3, 2).StringValue = "800"

'6. Remove Mike from the list'oFld.Value(-1).Del

'7. Extract the dynamic string and convert back to the original'format.

'mystring = oFld.SwapString(oFld, chr(253), ",")mystring = oFld.SwapString(mystring, chr(252), ":")Response.Write(mystring)

'8. Remove the RedField object when we are finished with it'oFld= ""Set oFld = Nothing%></BODY></HTML>

74 RedPages

ADO Object

ADO Object

ADO Object ModelThis can be found at the following location:

http://msdn.microsoft.com/library/techart/adosql_2.htm

NoteThis location is not maintained by Informix Software Corp and may be subject to change without notice.

ADO API ReferenceThis can be found at the following location:

http://msdn.microsoft.com/library/psdk/dasdk/mdao2of9.htm

NoteThis location is not maintained by Informix Software Corp and may be subject to change without notice.

RedPages 75


Step-by-Step Instructions for Using ADO

These are the typical steps you use to access RedBack Business Objects on the host computer via ADO.

The typical steps for using ADO are:

1. Create an ADO Connection object

2. Create an instance of the RedBack Business Object

3. Call RedBack methods

4. Access field values

5. Destroy objects

These steps are discussed in greater detail below.

Create ADO Connection objectRedObjects use ADO as the connection mechanism to the host provider where the RBO's reside.

Access to your RedBack Business Object is through a connection, the environment necessary for exchanging data. The Connection object is used to specify a particular provider.

NoteUsing collections, methods and properties of a Connection object, you can examine errors returned from the data source with the Errors collection.

The provider is the RedBack component (redpages.dll) which provides access to the uni-Verse/UniData backend. This is done in the following manner

Syntax

Set connectionobjectname = Server.CreateObject("ADODB.Connection")

connectionobjectname.Provider = "RedBack.RedPages"

connectionobjectname.Open Accountname

76 RedPages


where:

Accountname

Optional. Denotes the name of the uniVerse or UniData account.

This can have a number of formats:

1, Accountname

This is a name given to represent a U2 (i.e. uniVerse or UniData) account. This name corre-sponds to an entry in the rgw.ini file which maps the name to an IP address and port number (see “rgw.ini” on page 122 for more information about this ini file).

2, IPaddress:portnumber

This format specifies the IP number for the host machine and the port number to be used to communicate with the specific account.

Program Example

Set objconn = Server.CreateObject("ADODB.Connection")objconn.Provider = "RedBack.RedPages"objconn.Open "RBODemo"

Create an instance of the RedBack Business Object

Syntax

commandobjectname.CommandText = "ModuleName:RedBackBusinessObjectName.Create()"

RedPages 77


Program Example

Set rbo = Server.CreateObject("ADODB.Command")rbo.ActiveConnection = objconnrbo.CommandText = "OFFICE:Employee.Create()"rbo.ExecuteThe statement "rbo.Execute" is required to invoke "rbo.CommandText"

Call RedBack Methods

Syntax

commandobjectname.CommandText = String

where string can take a number of forms. These include:

"classname.methodname()"

"methodname()"

"handle.methodname()"

"methodname(parameters)" - this is the most common form used.

parameters

These can take one of the following forms:

("Inputfieldname1=Value1","Inputfieldname2=Value2",...)

("Inputfieldname1=Value1", "Outputfieldname1","Outputfieldname2"...)

methodname

The exact methods which can be called will depend on the design of the RedBack Business Object (RBO). The RBO is an object with a set of methods associated with it. These are created by the application programmer via the RedBack Explorer. Therefore the actual method names available will be determined by the application programmer.

78 RedPages


Program Example

rbo.CommandText = "OFFICE:Employee.Create()"rbo.CommandText = "ReadData(EmpId=" & Request.QueryString("EmpId")& ")"

NoteTo invoke rbo.CommandText it is necessary to invoke:

Set Employee = rbo.Execute

Access Field Values

Syntax

Set fields = RedBackObjectName.fields

Program Example

rbo.CommandText = "ReadData(EmpId=" & Request.QueryString("EmpId") & ")"Set record = rbo.ExecuteSet fields = record.fieldsname = fields("EmpName")

In general field values are a single data value i.e. Employee="Colin". A feature of the uni-Verse/UniData databases is that any data field can contain nested or multivalued data. Each field may be made up of 1 or more ‘values’ and each value may be made up of 1 or more ‘subvalues’.

The string returned from the ‘field value’ operation above will contain all of this nested data in what is referred to as a dynamic string.

To assist extraction, creation and manipulation of dynamic strings redpages.dll also registers an object titled RedField. The RedField object provides a simple mechanism for working with dynamic strings (see “RedField Object” on page 55).

RedPages 79


Destroy objects

Syntax

Set RedBackBusinessObjectName = Nothing

Program Example

Set rbo = Nothing

80 RedPages

ADO Code Examples

ADO Code Examples

Read ExampleThe following code is a typical example of a RedBack RedPage which performs a read action.

Program Example

<HTML><HEAD><TITLE>RedPages ADO Read Example</TITLE></HEAD><BODY>

<%On error Resume Next

'Note in VBScript there is no need to use the Dim statement for local'variables'Note RBO is used as an abbreviation to denote "RedBack Business Object"

''1. Create the ADO connection object, set the provider and Open the account'Set objconn = Server.CreateObject("ADODB.Connection")objconn.Provider = "RedBack.RedPages"objconn.Open "RBODemo"

'2. Now we need a command object for the RBO we are going to reference. It is'through this object that each RBO server request is made. The Command'object is passed the ADO Connection object so it knows where to connect'with each of its requests

'Set rbo = Server.CreateObject("ADODB.Command")rbo.ActiveConnection = objconn

'3. Now we can tell the command object to create an instance of a RBO on the'RBO server. We do this by assigning the required method call to the'command object's "command" string and then executing it.

'rbo.CommandText = "OFFICE:Employee.Create()"rbo.Execute

RedPages 81


'5. Now do a ReadData, passing in the EmpId value of "1010". Each name/value'that is to be sent back has to be placed as an argument to the method'call The "Set employee" statement will assign the resulting recordset'(from the execute) to the variable "employee"

'EmpId = Request.QueryString("EmpId")EmpId = 1010 ' hard coded for test purposesrbo.CommandText = "ReadData(EmpId=" & EmpId & ")"Set employee = rbo.Execute

'6. Now we can retrieve the required property values from the recordset.'FirstName = employee("FirstName")LastName = employee("LastName")Response.Write("FirstName=" & FirstName & " LastName=" & LastName)

'7. If we want to reuse the Connection and Command objects for reuse in'another ASP page then we can save them as follows:

'Set Session("connectionvariablename") = objconnSet Session("rbovariablename") = rbo

'Note to destroy an object the recommended way to do this is to:'Set rbo = NothingSet objconn = Nothing%></BODY></HTML>

Write ExampleThe following code is a typical example of a RedBack RedPage which performs a write action.

Program Example

<HTML><HEAD><TITLE>RedPages ADO Write Example</TITLE>

82 RedPages

ADO Code Examples

</HEAD><BODY>


'Note in VBScript there is no need to use the Dim statement for local'variables'Note RBO is used as an abbreviation to denote "RedBack Business Object"

''1. Create the ADO connection object, set the provider and Open the account

'If we want to reuse the Connection object from the Read example we would'insert the following code instead of the next 3 lines:'Set objconn = Session("connectionvariablename")

'Set objconn = Server.CreateObject("ADODB.Connection")objconn.Provider = "RedBack.RedPages"objconn.Open "RBODemo"

'2. Now we need a command object for the RBO we are going to reference. It is'through this object that each RBO server request is made. The Command'object is passed the ADO Connection object so it knows where to connect'with each of its requests

'Set rbo = Server.CreateObject("ADODB.Command")rbo.ActiveConnection = objconn

'3. Now we can tell the command object to create an instance of a RBO on the'RBO server. We do this by assigning the required method call to the'command object's "command" string and then executing it.

'rbo.CommandText = "OFFICE:Employee.Create()"rbo.Execute

'5. Now do a ReadData, passing in the EmpId value of "1010". Each name/value'that is to be sent back has to be placed as an argument to the method'call The "Set employee" statement will assign the resulting recordset'(from the execute) to the variable "employee"

'EmpId = Request.Form("EmpId")Name = Request.Form("FirstName")EmpId = 1010 ' hard coded for test purposesName = "Nghia La"rbo.CommandText = "WriteData(EmpId=" & EmpId & ",FirstName=" & Name & ")"Set employee = rbo.Execute

RedPages 83


'6. If we want to reuse the Connection and Command objects for reuse in'another ASP page then we can save them as follows:

'Set Session("connectionvariablename") = objconnSet Session("rbovariablename") = rbo

'Note to destroy an object the recommended way to do this is to:'Set rbo = NothingSet objconn = Nothing%></BODY></HTML>

RecordSet Code Example

Program Example

<HTML><HEAD><TITLE>RedPages Recordset Example</TITLE></HEAD><BODY>


'The RecordSet is used to scroll through the result of a uQuery,'where normally, more than one row of data is returned.

''First we need RedObject for the EmpLookup RBO

'Set oLookup = Server.CreateObject("RedBack.RedObject")oLookup.Open2 "rbodemo", "OFFICE:EmpLookup"

'Now we can do the actual selection. A recordset is returned from'a Select. This will return the first page

'Set rs = oLookup.CallMethod("Select")

84 RedPages

ADO Code Examples

'Now that we have the first page we can get and set values for that'page, that tell us how many items were selected and what the page'size is (determined by the RBO from the class definition).

'pageSize = oLookup("items_per_page")rs.PageSize = pageSizemax = oLookup("MaxRows")pageCount = Int(max/pageSize)If max Mod pageSize then pageCount = pageCount + 1End if

'As we will be returning to this page on the web server we need to'preserve the RecordSet handle so that we do not have to reselect'the data and recreate the RedObject for each subsequent page display.'Also, preserver the current page number

'Set Session("EmpRecSet") = rsSession("EmpPages") = pageCount

'This section of code, will loop through each item on a page,'displaying the details in the HTML page. The movement through each'row is done with rs.MoveNext. This will also return the next page'if the move extends beyond the current page.'When a page is at the end then rs.EOF will be set to true.

'For i = 1 to rs.PageSize If rs.EOF then Exit For End if%> <TR><TD WIDTH="25%" VALIGN="TOP"> <A HREF="EmpMaint.asp?action=ReadData&EmpId=<%=rs.Fields("EMP.ID")%>"> <%=rs.Fields("EMP.ID")%> </A> </TD> <TD WIDTH="25%" VALIGN="TOP"><%=rs.Fields("FIRST.NAME")%> </TD> <TD WIDTH="25%" VALIGN="TOP"> <%=rs.Fields("LAST.NAME")%> </TD> <TD WIDTH="25%" VALIGN="TOP" ALIGN="RIGHT"> <IMG SRC=<% ="images/" & rs.Fields("IMAGE")%> WIDTH=80 HEIGHT=98> </TD> </TR><% If i < rs.PageSize Then rs.MoveNext

RedPages 85


End ifNext

'Clean up all objects we no longer need'Set oLookup = Nothing%>

</BODY></HTML>

86 RedPages

Error Handling

Error Handling

When writing ASP applications that communicate via ADO to data sources such as the RedPages OLE DB provider, there is a need to handle various error conditions and messages that the provider may generate. The mechanism for determining the success or failure of any operation is by check-ing the ADO Errors collection associated with the Connection object.

The ADO Errors collection contains the provider-specific errors generated by a single operation. Each Error object constitutes one such error in the collection. To get information about an error, query the properties of an Error object from the Connection object. To get all the Error objects in the Errors collection, use code to loop through the collection.

ADO errors (for example, invalid use of ADO properties or methods), as opposed to provider

errors (those generated by the RedPages provider), do not appear in the Errors collection. ADO errors are captured by the exception handling mechanism of your run-time environment. For exam-ple, in Microsoft® Visual Basic® and Microsoft® Active Server Pages®, the occurrence of an ADO Error will trigger an On Error event and appear as a VB or ASP Err object.

If you want to trap both provider-specific errors (by querying the properties of an Error object) and ADO errors (by trapping ADO errors through the run-time exception handler) in your applica-tion, you have to write error-handling code for both. (See example code below)

Error numbers returned by ADO are 32-bit hexadecimal values that define the error. Each error code consists of a number of pieces with the lower 16-bit being the actual error identifier. A nega-tive number indicates a trappable error condition, 0 indicates success and a positive number indi-cates an informational type status.

Any provider-specific trappable error (negative number) generated by the provider is added to the ADO Errors collection and is also handled through the run-time exception handler.

Any provider-specific non-trappable error (positive number) generated by the provider is added to the ADO Errors collection but is not handled by the run-time exception handler.

This means that the On Error event generated in VB or ASP will only occur for negative error numbers. If you wish to check for non-trappable errors then you will need to examine the ADO Errors collection.

Non-trappable error numbers usually represent a successfully completed operation but indicate that some extra information was returned with regard to that operation.

RedPages 87


A common non-trappable error in RedBack is error number 0x50040023 (See “RedBack Error Codes” on page 127 for a list of all error codes). This error number represents an Alert generated by the RedBack Application Server. Alerts are messages sent from the RedBack Application Server to inform the user of something. An example of this is the Alert message generated when you log in to a RedBack Application Server that is running with a temporary license. The message shows how many days before the temporary license expires.

The following ASP code fragment demonstrates how to handle both trappable and non-trappable errors. The code creates an ADO connection object and opens a connection to the rbodemo account. It then creates a RedObject and attempts to Open a "OFFICE:Employee" object on the server. After the Open method call we test the returned error number and either write the error message to the page or add the Alert message to the StatusText variable.

Program Example

<HTML><HEAD><TITLE>RedPages Error handling example</TITLE></HEAD><BODY><%On Error Resume Next

'Create and Open the Employee RedObject'Set oEmp = Server.CreateObject("RedBack.RedObject")oEmp.Open2 "rbodemo", "OFFICE:Employee"errno = GetErrNumber(oEmp)If errno < 0 Then Response.Write("Error opening OFFICE:Employee. Error=" &GetErrDescription(oConn))End If

If errno > 0 Then StatusText = GetErrDescription(oEmp)Else StatusText = "Object opened successfully"End IfResponse.Write(StatusText)

'

88 RedPages

Error Handling

'Gets the error Number from either the On Error Err object or ADO'Errors collection'Note: Err.Number is only filled in for trappable errors (negative

numbers)'Passed: obj - The RedObject

'Function GetErrNumber(obj) GetErrNumber = 0 If Err.Number Then GetErrNumber = Err.Number Else If not IsEmpty(obj) and IsObject(obj) Then If obj.Errors.Count > 0 Then GetErrNumber = obj.Errors.Item(0).Number End If End If End IfEnd Function

''Gets the error Description from either the On Error Err object or'ADO Errors collection'Note: Err.Number is only filled in for trappable errors (negative

numbers)'Passed: obj - The RedObject

'Function GetErrDescription(obj) GetErrDescription = "" If Err.Number Then GetErrDescription = Err.Description Else If not IsEmpty(obj) and IsObject(obj) Then If obj.Errors.Count > 0 Then GetErrDescription = obj.Errors.Item(0).Description End If End If End IfEnd Function%></BODY></HTML>

RedPages 89


90 RedPages

Chapter 4 - RBODemo

RBODemo is a fictitious shoe store which demonstrates key features of the RedBack product. This chapter takes you through some of the code used in the RedPages version of RBODemo.

RedPages 91

Chapter 4 - RBODemo

RBODemo

RBODemo is a demonstration program. RBODemo was built to demonstrate some of the main features of RedBack which can be applied to the development of web-based transactional applica-tions. You can view the code in the RBODemo application to show how these RedBack concepts are applied.

NoteRBODemo is not a full commercial application and has purposely been kept simple to help iden-tify and clarify RedBack concepts.

The RBODemo application is bundled with RedBack and is installed during the RedBack installa-tion process.

RBODemo can be disabled from a live runtime system by deleting it from your system (refer to your database documentation for further information on how to do this) or by removing references to it in rgw.ini and rgwresp.ini (see the Administration manual for more details).

NoteRefer to the “Developing With RBOs” manual for more information about design methodology.

Design GoalsRBODemo is based on a fictional shoe store called “RedPage Shoes”. We have identified three types of potential users for this application, these being:

• external retail customers ordering directly form the RedPages shoe store,

• external trade customers wanting to purchase shoes,

• internal staff who maintain the shoe stock records in the application, and managers who maintain administrative records such as employee details.

The following sections provide more information about RBOdemo.

92 RedPages

RBODemo

Starting RBODemoType in the following URL in order to launch RBODemo:

http://web_server_name/rbodemo

where the web_server_name is either the domain name of the web server or the IP address of the web server machine.

The following web page will be presented:

From this screen it is possible to go to the RedPages version of the shoe store by clicking on the RedPage store link.

RedPages 93

Chapter 4 - RBODemo

Overview - Retail Part of RBODemoThe retail part of RBODemo would typically be used by individuals who would typically only buy one or two pairs of shoes. The steps of how individual customers would typically use the system are described below.

In describing this section of the shoe store we will also provide some suggestions for the web designers.

TipIt is always a good idea to design a static set of web pages to get an idea of how your application will look.

94 RedPages

RBODemo

Step 1: Entering the RedPages Shoe StoreIn order to cater for these multiple audiences, we designed three ways to enter the application, based on whether they are trade customers, retail customers or staff:

Retail customers click on the picture of the shoe store to gain access whereas trade customers and staff click on the menu links provided along the left hand side of the screen.

Trade customers will be taken to Step:2 Login Page, whereas retail customers will be taken to Step 3:Choose Shoe Category and Shoe Style.

RedPages 95

Chapter 4 - RBODemo

Step 2: Login PageProvide login details and then click on the Proceed button..

96 RedPages

RBODemo

Step 3: Choose Shoe Category and Shoe Style

RedPages 97

Chapter 4 - RBODemo

The dropdown combo box is dynamically created from data in the database..

98 RedPages

RBODemo

Step 4: Selecting ShoesUsers simply click on the Add to cart button to select a pair of shoes that they want to buy

RedPages 99

Chapter 4 - RBODemo

Step 5: Shopping CartThe Shopping cart page is used to show your selection. You also specify the shoe size and quan-tity from here:

100 RedPages

RBODemo

Step 6: CheckoutThis is the page where the customer provides delivery details and payment information.

RedPages 101

Chapter 4 - RBODemo

Step 7: Thank youThis page provides a confirmation of the order.

102 RedPages

RBODemo

Detail - Employee MaintenanceIn chapter 3 we gave you an overview of using RedPages, and earlier in this chapter we gave you an overview of design and navigation considerations. Now it is time to bring these principles together. We will do this by examining the employee maintenance section of RBOdemo in detail.

The Pages

TipIt is always a good idea to design a static set of web pages to get an idea of how your application will look. The following screens will take you through the employee maintenance section.

Step 1: Enter the RedPages Shoe Store

Select Staff Entry:

RedPages 103

Chapter 4 - RBODemo

Step 2: The BackOffice Page is Displayed

Select the Employees link from the menu list shown on the left hand side.

This screen has been built using frames.

The code, which can be found in BackOffice.asp for this is shown below for information purposes only:

Program Example

<HTML><HEAD><TITLE>RedPages</TITLE></HEAD><FRAMESET ROWS="120,*" BORDER=0> <FRAME SRC="BOHead.asp" NAME="TOP" NORESIZE> <FRAMESET COLS="18%,82%"> <FRAME SRC="BOMenu.asp" NAME="MENU" NORESIZE> <FRAME SRC="BOMain.asp" NAME="MAIN" NORESIZE> </FRAMESET>

104 RedPages

RBODemo

</FRAMESET> </HTML>

Step 3: The Employee Maintenance Screen

This screen is used to add employees, remove employees and change current employee’s details. Click on the Lookup button.

Step 4: Select Employee

In the following screen click on the link for the employee’s details that you want:

RedPages 105

Chapter 4 - RBODemo

Step 5: Editing Details

Details can be edited as required. When finished press the Accept button. The next time you view this record you will see the amended details.

106 RedPages

RBODemo

The Building Blocks

The following diagram shows the building blocks that comprise the employee maintenance module

RBOs Defined for RBODemo

The RBOs which were defined when designing RBODemo have been supplied with the RedBack product and will be created in the uniVerse/UniData backend when you install RBODemo. The following screens show that two modules were defined for RBODemo, these being:

• OFFICE

• STORE

ReadData()

WriteData()EmpMaint.asp

RBO

EmpLookup.asp

Employees

RBO

Lookup

EmpLookup

RedPages 107

Chapter 4 - RBODemo

Within the OFFICE module a number of RBOs are designed and viewed by using the RedBack Designer:.

108 RedPages

RBODemo

The Employee RBO is particularly relevant regarding the employee maintenance portion of RBOdemo.:

Refer to the documentation supplied with RedBack Designer for more information.

The Code

All of the user interface code is handled by the web server in RedBack aware Active Server Pages (ASP) called RedPages. RedPages are saved using the same .asp extension as ASP and support the same scripting languages as ASP.

The code for the user interface of the employee maintenance section of RBODemo is contained in the following three files:

• EmpMaint.asp

• EmpLookup.asp

• CommonSubs.inc

RedPages 109

Chapter 4 - RBODemo

The ASP code is contained within tags that have a percentage symbol, i.e.

<%%>

and is shown in bold in the code examples that follow.

The file CommonSubs.inc is simply a file that contains common routines, which are used by the other two files.

EmpMaint.asp handles the employee maintenance routines and EmpLookup.asp handles the lookup routines.

The code for these three files is shown below for reference purposes.

EmpMaint.asp

Program Example

<% Response.Buffer = true %><HTML><HEAD><TITLE>RedPages</TITLE></HEAD>

<%On error Resume NextConst VM = "ý"

firstTime = OpenObj("EmpObj", "OFFICE:Employee", 1, oEmp)

' Create two objects to hold multivalue Dept codes and descriptions Set oCodes = Server.CreateObject("RedBack.RedField") Set oDescs = Server.CreateObject("RedBack.RedField") If firstTime Then oCodes.StringValue = oEmp("DeptCodes") oDescs.StringValue = oEmp("DeptDescs") Else oCodes.StringValue = Request.Form("Codes") oDescs.StringValue = Request.Form("Descs") End If

' Generic field object for string operations

110 RedPages

RBODemo

Set oFld = Server.CreateObject("RedBack.RedField")

' Focus object If Request.Form("EmpId") = "" Then focusObj = "EmpId" Else focusObj = "" End If

' What is the action to take - passed in 'action' action = Request.QueryString("action")

Select Case action Case "ReadData" ReadData Case "WriteData" WriteData Case "ClearForm" ClearForm Case "Validate" Validate Case Else ' Just show form End Select %>



<%Sub ReadData() On error Resume Next ' First look if id passed in URL string (eg from lookup) else get from form post EmpId = Request.QueryString("EmpId") If IsEmpty(EmpId) Then EmpId = Request.Form("EmpId") ' Set the propery in the object to the new value oEmp("EmpId").Value = EmpId ' Now do the read by calling the ReadData method oEmp.CallMethod "ReadData" If Err.Number Then DisplayError focusObj = "FirstName"End Sub

RedPages 111

Chapter 4 - RBODemo

Sub WriteData() ' Update all property values in object then call WriteData method UpdateEmp oEmp.CallMethod "WriteData" If Err.Number Then DisplayError focusObj = "EmpId"End Sub Sub Validate() UpdateEmp fName = Request.QueryString("field") If oEmp(fName) <> "" Then If fName = "Salary" Then ' Validate Salary oEmp.CallMethod "ValidateSalary" Else ' Validate (Numeric/Date/Time) vType = Request.QueryString("type") oEmp("ServerValidate").Value = fName & VM & vType oEmp.CallMethod "Validate" End IF If Err.Number Then DisplayError If oEmp("ServerStatus") = 1 Then focusObj = fName End IfEnd Sub

Sub ClearForm() ' Clear form via Clear method oEmp.CallMethod("Clear") focusObj = "EmpId"End Sub

Sub UpdateEmp() ' Update all property values in Emp object oEmp("EmpId").Value = Request.Form("EmpId") oEmp("LastName").Value = Request.Form("LastName") oEmp("FirstName").Value = Request.Form("FirstName") oEmp("Salary").Value = Request.Form("Salary") oEmp("HireDate").Value = Request.Form("HireDate") oEmp("Dept").Value = Request.Form("Dept") oEmp("Interests").Value = oFld.SwapString(Request.Form("Interests"), vbCrLf, VM)End Sub %>

112 RedPages

RBODemo

<SCRIPT language="JavaScript">function SendToWebServer(action){ document.Form1.action = "EmpMaint.asp?action=" + action; document.Form1.submit();}</SCRIPT>

<BODY BGCOLOR="#FFFFFF"><% If oEmp("ServerStatus") = "1" Then Response.Write("<BR>Error: " & oEmp("ServerMessage")) End If oEmp("ServerStatus").Value = 0 oEmp("ServerMessage").Value = ""%> <FORM NAME="Form1" METHOD=POST><TABLE CELLSPACING=0 CELLPADDING=3 BORDER=0 WIDTH=450 STYLE="font-fam-ily:Arial;font-size:12"> <TR><TD COLSPAN=3 ALIGN="CENTER"><H3 STYLE="back-ground:#D29B9E;color:#633132;font-family:Arial">Employee Mainte-nance</H3></TD></TR> <TR> <TD vAlign=center NOWRAP><BR>Employee ID</TD> <TD vAlign=top> <INPUT name="EmpId" size=5 value="<%=oEmp("EmpId")%>" onchange=SendToWeb-Server("ReadData")>

<A HREF="EmpLookup.asp"><IMG height=30 src="images/btn_lookup.jpg" bor-der=0></A> </TD> <TD vAlign=top width="59%" ROWSPAN=4 ALIGN="RIGHT"> <% ImageFile = oEmp("ImageFile") If ImageFile = "" Then ImageFile = "onepixel.gif" %> <IMG height=121 src="images/<%=ImageFile%>" width=102> </TD> </TR> <TR> <TD vAlign=center>First Name</TD> <TD vAlign=top> <INPUT name="FirstName" size=25 value="<%=oEmp("FirstName")%>"></TD> </TR> <TR> <TD vAlign=center>Last Name</TD>

RedPages 113

Chapter 4 - RBODemo

<TD vAlign=top><INPUT name="LastName" size=25 value="<%=oEmp("LastName")%>"></TD>

</TR> <TR> <TD vAlign=center>Hire date</TD> <TD vAlign=top><INPUT name="HireDate" size=10 value="<%=oEmp("HireDate")%>" onchange=SendToWebServer("Validate&field=HireDate&type=D")></TD> </TR> <TR> <TD vAlign=center>Salary</TD> <TD vAlign=top><INPUT name="Salary" size=10 value="<%=oEmp("Salary")%>" onchange=SendToWebServer("Validate&field=Salary")></TD> <TD vAlign=top width="20%" ROWSPAN=3 ALIGN="RIGHT"> <A HREF="JavaScript:SendToWebServer('WriteData')"><IMG height=30 src="images/btn_accept.jpg" border=0><BR></A> <A HREF="JavaScript:SendToWebServer('ClearForm')"><IMG height=30 src="images/btn_clear.jpg" border=0><BR></A> <IMG height=30 src="images/btn_delete.jpg" border=0></TD> </TR> <TR> <TD vAlign=center>Department</TD> <TD vAlign=top> <SELECT name="Dept"><% ' Set dept codes and descriptions For i = 1 to oCodes.Count

If oEmp("Dept") = oCodes.Value(i) Then sel = "SELECTED " Else sel = ""%> <OPTION <%=sel%>VALUE=<%=oCodes.Value(i)%> > <%=oDescs.Value(i)%> <% Next %>

</SELECT></TD>

</TR> <TR> <TD vAlign=top>Interests</TD>

<TD WIDTH="59%" VALIGN="top"> <% Interests = oFld.SwapString(oEmp("Interests"), VM, vbCrLf) %> <TEXTAREA name="Interests" wrap=off rows=4 cols=24><%=Interests%></TEXTAREA>

</TD> </TR></TABLE>

<INPUT name="EmpObj" value="<%=oEmp.RBOHandle%>" type=HIDDEN><INPUT name="Codes" value="<%=oCodes%>" type=HIDDEN><INPUT name="Descs" value="<%=oDescs%>" type=HIDDEN>

114 RedPages

RBODemo

<% If focusObj <> "" Then %> <SCRIPT language="JavaScript"> var hFocusObj = document.Form1.<%=focusObj%>; hFocusObj.focus(); </SCRIPT><% End If %>

<%' Destroy objects (on Web Server)If isObject(oEmp) Then oEmp.Close Set oEmp = nothingEnd IfIf isObject(oCodes) Then oCodes.Close Set oCodes = nothingEnd IfIf isObject(oDescs) Then oDescs.Close Set oDescs = nothingEnd IfIf isObject(oFld) Then Set oFld = nothingEnd If%>

</FORM></BODY></HTML>

EmpLookup.asp

Program Example

<% Response.Buffer = true %><HTML>

RedPages 115

Chapter 4 - RBODemo

<HEAD><TITLE>RedPages</TITLE></HEAD>

<% On Error Resume Next firstTime = OpenObj("EmpRecSet", "OFFICE:EmpLookup", 1, oLookup)

page = Request.QueryString("page") If IsEmpty(page) then page = 1 Else page = Cint(page) End If

If firstTime Then ' Do selection Set rs = oLookup.CallMethod("Select") If Err.Number Then DisplayError

maxRows = oLookup("MaxRows") Else ' Selection already done and have recordset oLookup("page_no").Value = page Set rs = oLookup.CallMethod("PageDisp") If Err.Number Then DisplayError

' restore maximum rows maxRows = Request.Form("maxRows") End If

' Set the recordset page size to number of items specified in RBO pageSize = oLookup("items_per_page") rs.PageSize = pageSize pageCount = Int(maxRows/pageSize) If maxRows Mod pageSize then pageCount = pageCount + 1%>



<SCRIPT language="JavaScript">function SendToWebServer(page){

116 RedPages

RBODemo

document.Form1.action = "EmpLookup.asp?page=" + page; document.Form1.submit();}</SCRIPT>

<BODY BGCOLOR="#FFFFFF"><FORM NAME="Form1" METHOD=POST><CENTER><H3 STYLE="background:#D29B9E;color:#633132;font-family:Arial">Employee Lookup</H3></CENTER><TABLE CELLSPACING=0 BORDER=0 CELLPADDING=4 WIDTH=590 STYLE="font-fam-ily:Arial;font-size:12"><TR><TD VALIGN="TOP" COLSPAN=3><B>Click on an Employee ID to select it.</B></TD><TD ALIGN="RIGHT"><B>Page <%=page%> of <%=pageCount%></B></TD></TR><TR><TD WIDTH="10%" VALIGN="TOP" BGCOLOR="#000000"><FONT FACE="Arial" SIZE=2 COLOR="#ffffff"><P ALIGN="LEFT">Emp ID</FONT></TD><TD WIDTH="30%" VALIGN="TOP" BGCOLOR="#000000"><FONT FACE="Arial" SIZE=2 COLOR="#ffffff"><P ALIGN="LEFT">First Name</FONT></TD><TD WIDTH="30%" VALIGN="TOP" BGCOLOR="#000000"><FONT FACE="Arial" SIZE=2 COLOR="#ffffff"><P ALIGN="LEFT">Last Name</FONT></TD><TD WIDTH="30%" VALIGN="TOP" BGCOLOR="#000000"><FONT FACE="Arial" SIZE=2 COLOR="#ffffff"><P ALIGN="RIGHT">Photo</FONT></TD></TR>

<%' Now script for each employee rowFor i = 1 to rs.PageSize if rs.EOF then Exit For%> <TR> <TD WIDTH="25%" VALIGN="TOP"> <A HREF="EmpMaint.asp?action=ReadData&EmpId=<%=rs.Fields("EMP.ID")%>"> <%=rs.Fields("EMP.ID")%> </A> </TD> <TD WIDTH="25%" VALIGN="TOP"><%=rs.Fields("FIRST.NAME")%> </TD> <TD WIDTH="25%" VALIGN="TOP"> <%=rs.Fields("LAST.NAME")%> </TD> <TD WIDTH="25%" VALIGN="TOP" ALIGN="RIGHT"> <IMG SRC=<% ="images/" & rs.Fields("IMAGE")%> WIDTH=80 HEIGHT=98> </TD> </TR><% If i < rs.PageSize Then rs.MoveNextNext%>

RedPages 117

Chapter 4 - RBODemo

<TR><TD COLSPAN=6 VALIGN="BASELINE"><IMG height=4 src="images/totals.JPG" width=590></TD></TR></TABLE>

<BR><% If pageCount > 1 Then %> <FONT FACE="Arial" SIZE=2>Goto: <% If page > 1 Then %> <A HREF="JavaScript:SendToWebServer('<%=page-1%>')">Prev</A> <% End If %> <% For i = 1 to pageCount %> <% If i <> page Then %> <A HREF="JavaScript:SendToWebServer('<%=i%>')"> <%=i%> </A> <% End If %> <% Next %> <% If page < pageCount Then %> <A HREF="JavaScript:SendToWebServer('<%=page+1%>')">Next</A> <% End If %> </FONT><% End If %>

<INPUT name="EmpRecSet" value="<%=oLookup.RBOHandle%>" type=HIDDEN><INPUT name="maxRows" value="<%=maxRows%>" type=HIDDEN>

<%' Destroy object (on Web Server)If isObject(oLookup) Then oLookup.Close Set oLookup = nothingEnd If%>

</FORM></BODY></HTML>

CommonSubs.inc

<%

118 RedPages

RBODemo

CommonSubs.inc

Program Example

<Function OpenObj(objName, objClass, objSave, objHandle) On error Resume Next OpenObj = False

' Hardcode account, user id and password stdAccount = "rbodemo" stdUserid = "" stdPassword = ""

' Session id sessionId = Request.Cookies("RedBack")("SessionId")

' Previous object handle prevObjHandle = "" Select Case objSave Case 1 ' Object handle was saved (in form) prevObjHandle = Request.Form(objName) Case 2 ' Object handle was saved (in a cookie) prevObjHandle = Request.Cookies("RedBack")(objName) End Select

If prevObjHandle = "" Then ' Create object Set objHandle = Server.CreateObject("RedBack.RedObject") objHandle.Open2 stdAccount, objClass, stdUserid, stdPassword, sessionId

If Err.Number Then DisplayError Else OpenObj = True

' Save session id Response.Cookies("RedBack")("SessionId") = objHandle.SessionID

If objSave = 2 Then

RedPages 119

Chapter 4 - RBODemo

Response.Cookies("RedBack")(objName) = objHandle.RBOHandle End If End If Else ' Object already created - re-create object Set objHandle = Server.CreateObject("RedBack.RedObject") objHandle.Open2 stdAccount, prevObjHandle, stdUserid, stdPassword, ses-sionId If Err.Number Then DisplayError End IfEnd Function

Sub DisplayError() Response.Write("Error: " & Hex(Err.Number) & " " & Err.Description)End Sub%>

120 RedPages

Appendix A - RedPage Configuration Issues

This appendix details some RedPage configuration issues.

RedPages 121


rgw.ini

Configuration of RedPages is controlled via the file rgw.ini file which is located in the Web Server's 'document root' directory. If a Web Server is not present on the machine where RedPages is install then rgw.ini is placed in the Windows directory instead.

NoteAn example rgw.ini is automatically generated by the install procedure. You may use this file as is or edit it to suit your requirements.

Example rgw.ini File Settings# example rgw.ini file. this is a comment line.uvtest fred:8300udttest fred:8301

uvtest/udttest are the account names (a unique key used throughout RGW), fred is the host name of the RedBack Server Machine, and 8300/8301 are the ports used to connect to the Responder.

If the Web Server Machine and the RedBack Server Machine are the same machine, use 'localhost' instead of 'fred' above.

You can use the raw ip address instead of the hostname if you prefer. For example, for the account uvtest quoted in the above example, you could use:

uvtest 203.14.103.84:8300

instead of

uvtest fred:8300

You can further control RedPages behavior for rgw.dll only by setting the RGWLOADINI system environment variable as follows:

0 Default. Load rgw.ini contents at dll attach and use that cache thereafter unless rgw.ini changes - in which case reload rgw.ini for all subsequent requests.

1 Fastest. Load at dll attach and never check on rgw.ini thereafter. It will be necessary to restart IIS or other application using RedPages to pick up changes to rgw.ini.

122 RedPages

rgw.ini

2 This gets the location of rgw.ini at dll attach but unconditionally reload rgw.ini for every request but is not particularly useful.

3 Do not do anything at dll attach. This gets the location of rgw.ini for each request and unconditionally reloads rgw.ini for every request.

RedPages 123


Logging

Logging in RedPages is controlled through a set of rgw.ini settings that determine what level of logging is required.

Example rgw.ini File Settings; Logging is to the file RBLOG/redpages.log.[LogLevel]; Use 1 to switch a level on, 0 to switch it off (default on).; The names below match the names in include/mylog.h and; the headers in each log file entry.; (Default is to switch only PANIC, ERROR and INIT on).panic=1 ; panicerr=1 ; errorwrn=1 ; warninginf=0 ; informational (licensing)init=1 ; initialization/terminationtrace=0 ; reserved for function call stack traceverb=0 ; verbosebig=0 ; big

Noteredpages.log is located in the web server’s logging directory (“%SystemRoot%\System32\Log-Files” by default) or the system temp directory if the web server logging directory cannot be found.

Logging Levels

panic

Panic level entries are internal errors that are deemed serious and may not be recoverable. Often the only course of action is to terminate RedPages.

Examples of panic Entries

• Not being able to resolve a host name to an IP address.

124 RedPages

Logging

• Not being able to open a given IP address.

• Using a persistent connection that has expired.

• Not being able to open/close/read/write files.

err

Error level entries are internal errors that are classes as bad but not quite panic material.

Examples of err Entries

• Having to truncate data because it is too large for internal bufers.

• Encountering file names that are too long.

• Various problems creating Command or Recordset objects.

wrn

Warning level entries are things that aren't actually errors but weren't really expected.

Examples of wrn Entries

• Finding a persistent connection is busy.

• Trying to read a file that has a size of 0.

• The maximum number of fields has been exceeded.

inf

Informational level entries show the state of operation at various points in the code.

Examples of Inf Entries

• Notification that various operations happened successfully.

• What IP address and port are being used.

• The command being executed.

• What account and method are being called.

RedPages 125


• SessionID and UserID being used.

• Spider packet processing information.

init

Initialization/termination entries are Informational pieces specifically related to the Initializataion and Termination of RedPages.

Examples of init Entries

• Info about the rgw.ini file location and search path.

• Info about problems during startup.

trace

Trace entries show the entry and exit position of each function as they are called. Turning this on generates a large amount of data and is only really of use to engineering.

verb

Verbose entries are informational level entries but those that occur a lot more frequently than oth-ers or are sligthly larger in size.

Example of verb Entries

• Info about building up Recordset data.

big

Big entries and informational level entries again but are those that are generally big.

Examples of big Entries

• All the data sent to the host.

• All the data returned from the host.

126 RedPages

Appendix B - RedBack Error Codes

This appendix details the RedBack standard error values.

RedPages 127


Error Codes

Values are 32 bit values of the following syntax:

3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 +---+-+-+-----------------------+-------------------------------+ |Sev|C|R| Facility | Code | +---+-+-+-----------------------+-------------------------------+

where Sev - (bits 30-31) is the severity code 00 - Success 01 - Informational 10 - Warning 11 - Error C - (bit 29) is the Customer code flag R - (bit 28) is a reserved bit Facility - (bits 16-27) is the facility code Code - (bits 0-15) is the facility's status code

Defined facility codes

1 Spider protocol error codes2 Backend Responder error codes3 Backend Scheduler error codes4 RedPages ADO Interface error codes5 RedPages general error codes6 ISAPI, rgw.dll error codes7 CGI, rgw.exe, rgw error codes8 Generic Gateway error codes9 Apache module error codes

Spider protocol error codes

0xF0010001 Error found in spider protocol

A protocol error can be the result of a number of different errors. Usu-ally this is due to bad data being passed either to the backend or being received from the backend. It is also possible that the data being passed has been cor-rupted in transmission although the link between the Web Server and the backend

128 RedPages

Error Codes

is usually a pretty clean one. Other reasons for this error include: A filename that has been passed is greater than 1024 characters or less than 3 characters, The backend replied with an HTML form rather than XML.

0xF0010002 Error allocating memory

A memory allocation has failed. This can either be because the system has run out of virtual memory or the amount of memory requested is invalid. The Error description should show the amount of memory being requested.

0xF0010003 Error building data string

This is an internal error generated when trying to add the Spider version information to the data being sent to the backend.If this happens it is likely the internal stack has been corrupted. The Web Server should be restarted.

0xF0010004 Error message from responder detected

The RedBack responder returned an error. The Error description will con-tain the actual error message generated by the responder. These errors include, The responder was unable to allocate memory to hold the sent data, The account information sent was either invalid or unable to be located in the request data.

0xF0010005 Error creating event for named pipe operations

An error was generated while trying to create a Win32 event to use for named pipe operations. The error number returned in the Error description is the actual Win32 error code generated.

0xF0010010 Error attempting to get a file size

An error was generated when trying to get the size of a file while doing a document get or put. This is usually due to an incorrect filename or path being specified or the Web Server not having the correct permissions to access the file.

0xF0010011 Error attempting to open a file

An error was generated when trying to open a file while doing a document get or put. This is usually due to an incorrect filename or path being specified or the Web Server not having the correct permissions to access the file.

0xF0010012 Error trying to read from a file

RedPages 129


An error was generated trying to read from a file. The error description specifies which file the error occurred on. Generally if the file can be opened the read operations should succeed. Check that the file can be opened with other programs such as notepad.

0xF0010013 Error trying to write to a file

An error was generated trying to write to a file. Check that there is suf-ficient disk space to write the data.

0xF0010021 Error reading from socket to backend

An error was generated trying to read data from the backend. The most likely cause of this is that the socket connection to the backend has been lost. This could be due to some network disconnection or the backend responder exiting because of some error condition. Check the responder log files to see if and why it may have exited.

0xF0010022 Error writing to socket to backend

An error was generated trying to write data to the backend. The most likely cause of this is that the socket connection to the backend has been lost. This could be due to some network disconnection or the backend responder exiting because of some error condition. Check the responder log files to see if and why it may have exited.

Backend Responder error codes

Not supported yet

Backend Scheduler error codes

Not supported yet

RedPages ADO Interface error codes

0xF0040011 No Connection Object specified

An attempt to Open a RedObject object was made without first assigning an ADOConnection object. The ADOConnection object defines which account to log into and what user ID and password to use.

0xF0040012No RBOClass or RBOHandle specified

130 RedPages

Error Codes

An attempt to Open a RedObject object was made without first assigning a RBOClass or RBOHandle. In order to open the RedObject we need to know what to open. RBOClass tells us what type of RBO object to create while RBOHandle tells us which existing RBO object to connect to.

0xF0040013 Error Creating RedProperty

An Error was encountered while trying to create the internal RedProperty Object. RedProperty objects are created temporarily by RedObject to allow the setting and getting of values. Failure to create a RedProperty object is probably due to invalid or currupted register setting. Try un-registering RedPages with 'regsvr32 /u redpages.dll', remove everything in the registry that refers to RedPages then re-registering it with 'regsvr32 redpages.dll'.

0xF0040014 Object not open

An attempt to call a method on a RedObject was made but the object has not been successfully opened. Before any operation can be performed on a RedObject it must first be opened by calling the Open method.

0xF0040015 Couldn't set CommandText

An error occurred while trying to set the internal ADOCommand's Command-Text property. Check the Err.Number and Err.Description values for more informa-tion.

0xF0040016 Couldn't set ActiveConnection

An error occurred while trying to set the internal ADOCommand's ActiveCon-nection property. Check the Err.Number and Err.Description values for more infor-mation.

0xF0040017 ADOCommand Execute Failed

An error occurred while trying to Execute the internal ADOCommand's Exe-cute. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF0040018 Error Creating internal ADOCommand object

An Error was encountered while trying to create the internal ADOCommand Object. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

RedPages 131


0xF0040019 Error getting the ADORecordset's ADOFields collection

An Error was encountered while trying to get the internal ADORecordset object's ADOFields collection. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF004001A Error getting the ADOCommands's ADOProperties collection

An Error was encountered while trying to get the internal ADOCommand object's ADOProperties collection. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF004001B Error getting the ADOCommands's "Maximum Rows" property

An Error was encountered while trying to get the internal ADOCommand object's "Maximum Rows" property. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF004001C Error getting the ADOCommands's "Maximum Rows" value

An Error was encountered while trying to get the internal ADOCommand object's "Maximum Rows" property value. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF004001D Property not found

An attempt was made to access a property that the RedObject or RedSet object does not support. Check the name of the property you are trying to access again. The RedPages.log logfile will contain the name of the property that the error was reported for.

0xF004001E Error Creating internal ADOConnection object

An Error was encountered while trying to create the internal ADOConnection Object that RedSet uses. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF004001F Error Opening internal ADOConnection object

An Error was encountered while trying to open the internal ADOConnection Object that RedSet uses. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

132 RedPages

Error Codes

0xF0040020 Error setting ADOConnection Provider

An Error was encountered while trying to set the internal ADOConnection Object's Provider property. Check the Err.Number, Err.Description values and the RedPages.log logfile for more information and look in the.

0xF0040021 Error getting the ADOField

An Error was encountered while trying to get the specified field from internal ADORecordset Object used by RedSet. Check the Err.Number, Err.Descrip-tion values and the RedPages.log logfile for more information and look in the.

0xF0040022 Error setting the ADOField value

An Error was encountered while trying to set the specified field value of internal ADORecordset Object used by RedSet. Check the Err.Number, Err.Descrip-tion values and the RedPages.log logfile for more information and look in the.

0x50040023 RedBack Alert generated

RedBack alerts are informational messages generated by RedBackas a result of a request. They are not errors and can be safelyignored but contain information that may be useful to prompt orshow to the user. An example of this is the message indicatingthat you have logged in using the 30 day trial license

RedPages general error codes

0xF0050001 Invalid spider instance received

An invalid spider instance handle was passed to a RedPages internal func-tion. A spider instance is generated for each ADO Connection object. This error can occur because of either a corrupt program stack or there was not enough mem-ory to create a new spider instance.

0xF0050002 Persistent connection has timed out

This error occurs when a request is made over a persistent connection that has timed out and been closed. Persistent connections are established from the backend and are set up with a timeout period. If the connection has been inactive for more than the amount of time specified by the timeout the connection is closed.

0x50050003 Persistent connection is busy (Warning)

RedPages 133


This warning is generated if a request is made on a persistent connection and that connection is already busy performing some other request. In multi-threaded environments it is possible to have multiple requests to the backend at the same time. Each of these requests uses a different socket connection to the backend. When using persistent connections though each of these requests needs to be passed through the same socket connection. This warning just states that the socket is currently busy.


A memory allocation has failed. This can either be because the system has run out of virtual memory or the amount of memory requested is invalid. 0xF0050005 Error building up Values string

This is an internal error generated when trying to add Name Value pairs to the data being sent to the backend. If this happens it is likely the internal stack has been corrupted.

0xF0050010 Error opening socket to backend

An error was generated when trying to open a socket connection to the backend. This could be because an invalid host name, IP Address or port number has been specified or there is a problem with the network connections.

0xF0050011 Error setting blocking mode on for socket

An error was generated when trying to set a socket to use blocking mode. The Error description contains the actual error number returned from the winsock function call.

0xF0050012 Error closing socket to backend

An error was generated when trying to close a socket connection to the backend.

ISAPI, rgw.dll error codes

0xF0060001 PATH_INFO environment variable too long

The maximum length for the PATH_INFO environment variable has been exceeded. The PATH_INFO environment variable set up by the Web Server has a max-

134 RedPages

Error Codes

imum length of 8Kb within RGW. The PATH_INFO environment variable contains the Web Server URL, account details and persistent connection information.

0xF0060002 No rgw.ini configuration file could be found

RGW requires a configuration file rgw.ini to specify the RedBack account names, IP addresses and port numbers. This file normally resides in the Wed Server's WWWROOT directory. Without this file RGW cannot contact any RedBack backend.

0xF0060003 Invalid account name specified

The account name specified in the URL could not be found in the rgw.ini file. The only accounts available to RGW are those that have been defined in the rgw.ini configuration file.


A memory allocation has failed. This can either be because the system has run out of virtual memory or the amount of memory requested is invalid.





0xF0060007 Values string maximum length exceeded

The combined length of all environment variable values has exceeded 16Kb in length. This includes QUERY_STRING, PATH_INFO and the 18 other environment variables the Web Server provides.

RedPages 135


0xF0060008 Names string maximum length exceeded

The combined length of all environment variable names has exceeded 8Kb in length. This includes QUERY_STRING, PATH_INFO and the 18 other environment vari-ables the Web Server provides.

0xF0060009 Error writing to Web Server

An error was generated trying to write data back to the Web Server.

0xF006000A Error building environment variables

An error was generated while trying to build up the list of environment variables. This is most likely due to either the environment variable names being too long of the values being too long. 0xF0060010 Error opening socket to backend


0xF0060011 Error setting blocking mode on for socket

An error was generated when trying to set a socket to use blocking mode. The Error description contains the actual error number returned from the winsock function call.

0xF0060012 Error closing socket to backend


CGI, rgw.exe, rgw error codes

0xF0070001 Error setting signal

An error was generated trying to set signal handler for the Unix signals (Unix only)

0xF0070002 Maximum path length exceeded

136 RedPages

Error Codes

The maximum length for the PATH_INFO environment variable has been exceeded. The PATH_INFO environment variable set up by the Web Server has a max-imum length of 8Kb within RGW. The PATH_INFO environment variable contains the Web Server URL, account details and persistent connection information.

0xF0070003 PATH_TRANSLATED environment variable not set or incorrect

The PATH_TRANSLATED environment variable was not set or is invalid. RGW for CGI uses the PATH_TRANSLATED environment to find the default document root directory for the web server.



0xF0070005 Error updating environment variables

An error was generated while trying to update the host name and address in the rgw.ini file.



0xF0070007 Error opening socket to backend


0xF0070008 Error building environment variables

An error was generated while trying to build up the list of environment variables. This is most likely due to either the environment variable names being too long of the values being too long. (see next two errors)



RedPages 137


0xF007000A Names string maximum length exceeded


0xF007000B Error reading data from Web Server

An error was generated while trying to read data from the Web Server

Generic Gateway error codes



Apache module error codes





0xF0090003 Error building environment variablesAn error was generated while trying to build up the list of environment

variables. This is most likely due to either the environment variable names being too long of the values being too long. (see next two errors)



0xF0090005 Names string maximum length exceeded

138 RedPages

Error Codes


0xF0090006 Error creating an Apache client block

An error was generate while trying to create an Apache client block. An Apache client block is used to pass information to a from the Apache Web Server.

0xF0090007 Error reading an Apache client block

An error was generated while trying to read from an Apache client block.





0xF009000A Error opening socket to backendAn error was generated when trying to open a socket connection to the

backend. This could be because an invalid host name, IP Address or port number has been specified or there is a problem with the network connections.

0xF009000B Error closing socket to backend


RedPages 139


140 RedPages

Index

AAccount

name, 77Active Server Pages, 21, 21ADO, 19, 28, 30, 31

Errors collection, 32

Bbig, 126

CCommandText, 78Configuration, 122conventions, 10

DDemonstration programs, 91DLL

redpages, 20

Eerr, 125Error

codes, 128handling, 87

FFrontPage, 21

HHomeSite, 21HTML, 21

Iinf, 125init, 126IP address, 77

RedPages 141

Index

JJava, 21

LLimitations, 26Logging, 124Logging levels, 124

MMethod, RedField

Del, 61Ins, 63Replace, 65SubValue, 68SwapString, 67Value, 70

Method, RedObjectCallMethod, 36Close, 37Open, 35Open2, 35

Method, RedSetAddNew, 47Close, 48Delete, 48Move, 49MoveFirst, 50MoveLast, 50MoveNext, 50MovePrevious, 50Open, 50

Methodscalling Redback methods, 78

Ppanic, 124Property, RedField

count, 56length, 57StringValue, 59ValueMark, 60

Property, RedObjectAccount, 30ActiveConnection, 31Errors, 32Password, 32Property, 32RBOClass, 33RBOHandle, 33, 33UserID, 34

Property, RedSetAbsolutePosition, 43BOF, 44EOF, 44Property, 46RecordCount, 46

RRBO

creating an instance of, 77what are they, 21

RBOdemo, 91RBOs, 21RedBack Business Objects, 21RedBack Designer, 21RedField, 79

object, 55RedPages, 18

architecture, 18

142 RedPages

Index

configuration, 122RedSet

object, 43rgw.ini, 122

Ttrace, 126

Vverb, 126Visual Interdev, 21

Wwrn, 125

RedPages 143

Index

144 RedPages

RedPages DRB-3007

red pages

Documents