ESP 7 (NGEN) on TCP/IPsupport.bull.com/ols/product/system/gcos7/gcos7-com/g7...ESP7 (NGEN) for Diane 2-2 47 A2 92US Rev01 2.2 The Installation Program After executing the installation

ESP 7 (NGEN)on TCP/IP

for DPS 7000/XTA DPS

7000/XTA

NO

VASC

ALE

7000

Distributed Computing

REFERENCE47 A2 92US 01

DPS7000/XTANOVASCALE 7000

ESP 7 (NGEN)on TCP/IPfor DPS 7000/XTA

Distributed Computing

December 2000

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

REFERENCE47 A2 92US 01

The following copyright notice protects this book under Copyright laws which prohibit such actions as, but notlimited to, copying, distributing, modifying, and making derivative works.

Copyright Bull SAS 2000

Printed in France

Suggestions and criticisms concerning the form, content, and presentation of thisbook are invited. A form is provided at the end of this book for this purpose.

To order additional copies of this book or other Bull Technical Publications, youare invited to use the Ordering Form also provided at the end of this book.

Trademarks and Acknowledgements

We acknowledge the right of proprietors of trademarks mentioned in this book.

Intel® and Itanium® are registered trademarks of Intel Corporation.

Windows® and Microsoft® software are registered trademarks of Microsoft Corporation.

UNIX® is a registered trademark in the United States of America and other countries licensed exclusively throughthe Open Group.

Linux® is a registered trademark of Linus Torvalds.

The information in this document is subject to change without notice. Bull will not be liable for errors containedherein, or for incidental or consequential damages in connection with the use of this material.

47 A2 92US Rev01 iii

Preface

This manual describes how to install, configure, and use the Enterprise ServerProcedures 7 (NGEN) for DPS 7000 XTA product. In this manual, theabbreviation ESP 7 (NGEN) is used to refer to this product. NGEN stands for“New Generation”.

This manual is intended for persons who need to install, configure, and/or use theESP 7 (NGEN) product.

None.

This manual contains 6 chapters and 2 appendices:

Chapter 1 gives an overview of ESP 7 (NGEN).

Chapter 2 describes the installation of ESP 7 (NGEN).

Chapter 3 describes the functions and architecture of ESP 7 (NGEN).

Chapter 4 describes the configuration of ESP 7 (NGEN).

Chapter 5 describes the configurability of ESP 7 (NGEN).

Chapter 6 describes the administration tool for ESP 7 (NGEN).

Appendix A gives advice on migrating from earlier versions of ESP 7.

Appendix B describes the translation table utility.

None.

The abbreviation ESP 7 (NGEN) is used for the name of the product EnterpriseServer Procedures 7 (NGEN) for DPS 7000 XTA.

None.

Scope andObjectives

IntendedReaders

Prerequisites

Structure

Bibliography

SyntaxNotation

DeliveryConditions

ESP7 (NGEN) for Diane

iv 47 A2 92US Rev01

47 A2 92US Rev01 1

Table of Contents

1. Overview

1.1 Purpose ........................................................................................................................... 1-1

1.2 Hardware and Software Requirements........................................................................... 1-2

1.2.1 Requirements on PC.......................................................................................... 1-2

1.2.2 Requirements on DPS 7000 XTA...................................................................... 1-2

1.3 Benefits of Enterprise Server Procedures 7.................................................................... 1-3

2. ESP7 Installation

2.1 Preconditions for Installation ........................................................................................... 2-1

2.2 The Installation Program ................................................................................................. 2-2

2.3 Installation Procedure ..................................................................................................... 2-3

2.3.1 Installation from Interop7 Web Site.................................................................... 2-3

2.3.2 Installation from Diskettes.................................................................................. 2-5


2 47 A2 92US Rev01

3. Enterprise Server Procedures 7

3.1 Product features 3-1

3.2 Functional Description..................................................................................................... 3-2

3.3 Using the TDS Object ..................................................................................................... 3-4

3.3.1 Using Early Binding............................................................................................ 3-5

3.3.2 Using Late Binding............................................................................................. 3-7

3.4 Using ESP7 ActiveX Control ........................................................................................... 3-8

3.5 ESP7 Interface 3-9

3.5.1 Properties........................................................................................................... 3-93.5.1.1 SessionID .......................................................................................... 3-93.5.1.2 Node .................................................................................................. 3-93.5.1.3 Host ................................................................................................. 3-103.5.1.4 Port .................................................................................................. 3-103.5.1.5 GCOS .............................................................................................. 3-113.5.1.6 Mailbox ............................................................................................ 3-113.5.1.7 User ................................................................................................. 3-113.5.1.8 Password......................................................................................... 3-113.5.1.9 Project ............................................................................................. 3-123.5.1.10 Billing ............................................................................................... 3-123.5.1.11 TermId ............................................................................................. 3-123.5.1.12 Trace3-133.5.1.13 TDSPrompt...................................................................................... 3-133.5.1.14 UseRemoteProcedureFile ............................................................... 3-13

3.5.2 Methods 3-143.5.2.1 Connect ........................................................................................... 3-143.5.2.2 Disconnect....................................................................................... 3-143.5.2.3 GetProcedureInfo ............................................................................ 3-153.5.2.4 ExecuteProcedure........................................................................... 3-163.5.2.5 NumberOfFields .............................................................................. 3-183.5.2.6 NumberOfRows............................................................................... 3-193.5.2.7 GetData ........................................................................................... 3-193.5.2.8 GetFieldInfo ..................................................................................... 3-20

3.5.3 Events 3-213.5.3.1 Message .......................................................................................... 3-21

3.6 Error Handling in the Client Application ........................................................................ 3-22

3.6.1 Error Constants................................................................................................ 3-23

3.6.2 Trace Facility.................................................................................................... 3-25

3.7 User Interface 3-26

3.7.1 User Profiles .................................................................................................... 3-26

3.7.2 User Interface Mechanics ................................................................................ 3-26

3.7.3 Accessing Stored Procedures from PowerBuilder........................................... 3-27

3.7.4 Accessing Stored Procedures from Visual Basic ............................................ 3-31

47 A2 92US Rev01 3

3.8 Dialog Descriptions ....................................................................................................... 3-36

3.8.1 Invoking ESP 7 TPRs ...................................................................................... 3-36

3.8.2 Returning Data................................................................................................. 3-36

3.9 File and Data Formats................................................................................................... 3-37

3.9.1 Data Types....................................................................................................... 3-373.9.1.1 Server Data Types........................................................................... 3-383.9.1.2 Conversion ...................................................................................... 3-40

4. Configuration of ESP 7

4.1 Configuring TCP/IP ......................................................................................................... 4-1

4.2 Configuring the Initialization File ..................................................................................... 4-2

4.3 Configuring Connection Parameters............................................................................... 4-4

4.4 Debugging Facilities........................................................................................................ 4-7

4.5 Security 4-7

4.5.1 Password Encryption ......................................................................................... 4-7

5. Configurability

5.1 ESP 7 Connections ......................................................................................................... 5-1

5.2 ESP 7 Procedures........................................................................................................... 5-1

6. Administration Tool for ESP 7

6.1 Overview 6-1

6.2 The Administration Tool (Espadmpc).............................................................................. 6-3

6.2.1 The Procedure Tree View.................................................................................. 6-4

6.2.2 The Parameter Form View................................................................................. 6-5

6.2.3 The main toolbar ................................................................................................ 6-5

6.2.4 The menus ......................................................................................................... 6-66.2.4.1 Menus commands ............................................................................. 6-6

A. Migration Advice

A.1 ESP 7 (ODBC) + DATA Control......................................................................................A-4

A.2 ESP 7 (NGEN) - Automation...........................................................................................A-5

A.3 execute_TPR: Example of Subroutine for ESP 7 (NGEN)..............................................A-7

A.4 Example for ESP 7 (NGEN) ............................................................................................A-9


4 47 A2 92US Rev01

B. Translation Table Utility

B.1 PC to GCOS 7 Translation Table....................................................................................B-1

B.2 Existing Tables B-2

B.2.1 Displaying ..........................................................................................................B-2

B.2.2 Modifying B-2

Glossary

Index

47 A2 92US Rev01 5

Table of Graphics

Figure 3-1. Connection between Client Application/TDS .................................. 3-2Figure 6-1. The Administration Tool in ESP 7 Architecture............................... 6-2

Table 3-1. Server Data Types........................................................................... 3-39Table 3-2. Automatic Data Conversions........................................................... 3-40

Figures

Tables


6 47 A2 92US Rev01

❑

47 A2 92US Rev01 1-1

1. Overview

1.1 Purpose

Distributed Computing Environments are more and more frequently deployed byenterprises. The role of Bull DPS 7000/GCOS 7 platforms is reinforced asEnterprise Servers provide the mainframe disciplines for hosting corporatedatabases and the server parts of business-critical applications, based on variousClient/Server technologies.

Enterprise Server Procedures for GCOS 7 (ESP 7) is part of Bull's offer aimedat developing two-tier and three-tier PC-DPS 7000 Client/Server applications,using the benefits of a wide range of Rapid Application Development (RAD) tools.

This document focuses on the installation, administration, and programming rulesfor the PC client side.

ESP7 (NGEN) for DPS 7000 XTA

1-2 47 A2 92US Rev01

1.2 Hardware and Software Requirements

1.2.1 Requirements on PC

The following table outlines the recommended PC configurations for installing andrunning ESP7:

2-tier version 3-tier version(up to 100 connections)

3-tier version(100 connections

and more)Processor Intel Pentium or faster

processorIntel Pentium II or fasterprocessor

Intel Pentium III or fasterprocessor

System Windows 95/98Windows NT 4.0 WorkstationWindows 2000 Professional

Windows NT 4.0 ServerWindows 2000 Server

Windows NT 4.0 ServerWindows 2000 Server

Memory 64 Mo 128 Mo 256 Mo

ESP 7 also requires the following hardware:

• A hard disk drive and approximately 2 Mbytes of hard disk space for thesoftware described above. Efficient execution requires 3 Mbytes of free space.

• A 3-1/2 inch floppy or CD-ROM drive (for installation).

• An Ethernet card.

1.2.2 Requirements on DPS 7000 XTA

ESP 7 requires the following mainframe software:

• the NT7 gateway NT7GW (release 1.5.0 or later),

• GCOS 7-V910 (minimum TS 9866).

Overview

47 A2 92US Rev01 1-3

1.3 Benefits of Enterprise Server Procedures 7

Enterprise Server Procedures 7 (ESP 7) is a middleware which enables the use ofopen, high productivity RAD tools for building PC-based Client applications andwhich benefits from the outstanding mainframe disciplines of GCOS 7 as aTP/DB Server.

Some of the key features that RAD tools provide for application developers are:

• easy development of Graphical User Interfaces (GUI's) which bring comfort,ease of use, and fast learning curve for the end-users of developed applications.

• iterative prototyping facilities for closer and more efficient cooperation withend-users, leading to applications that are more appropriate to the enterprisebusiness needs.

• easy integration of PC's with servers.

ESP 7 facilitates the building of application systems spanning PCs and BullDPS 7000 platforms (both in a two-tier and three-tier context), based on thestandard Microsoft Automation.

ESP 7 enables the independent evolution of Client and Server parts of theapplication, provided that both parts remain compliant with the applicationinterface they agreed on:

• application evolution is facilitated for easier and quicker response to economicchanges and constraints,

• there is no need for developers of the Client part of the application to be skilledin the GCOS environment, and vice-versa.

ESP 7 enables the integration of individual productivity tools with the EnterpriseClient/Server applications on the end-user's desktop within a standard Windowsenvironment.

ESP7 (NGEN) for DPS 7000 XTA

1-4 47 A2 92US Rev01

❑

47 A2 92US Rev01 2-1

2. ESP7 Installation

2.1 Preconditions for Installation

The ESP 7 (NGEN) diskettes contain the PC-side components for theESP 7 solution.

Other software requirements for its use are outlined below:

NT7GW must be installed and working correctly on the DPS 7000 XTA system.

Note that ESP7 (NGEN) may either be installed from the three 3.5” installationdiskettes or be downloaded using a browser to access Web7. The two methods areoutlined in Installation Procedure below.


2-2 47 A2 92US Rev01

2.2 The Installation Program

After executing the installation procedure (as described in the paragraph“Installation Procedure” below) to install ESP7 (NGEN), you should find thefollowing elements installed on your PC:

• in your chosen installation directory:

Espadmpc.exe Utility for procedure declaration handling.

Espini.exe Utility for configuration of op7gtw.ini.

Dsncnfg.exe Utility for configuration of connection parameters.

Pcclean.exe Utility used for connection cleaning on PC restart.

tblpcgc.exe Utility for generation of translation tables(between GCOS and PC).

System\ESP7SRV.exe TDS object server (ActiveX component).

System\ESP7.ocx ActiveX control

Samples Client application samples in Visual Basic andPowerBuilder

• in Windows system directory

The following Microsoft dlls will be installed or updated with a requiredversion:

− atl.dll

− mfc42.dll (on Win 9x system) or mfc42u.dll (on Windows NT 4.0 / Windows2000)

− msvcrt.dll

− oleaut32.dll

− olepro32.dll

• in Windows directory:

op7gtw.ini File common to several Interop7 products and used forconfiguration purposes.

In addition, 5 shortcuts will be available under the Start/Program/ESP7NGENmenu to activate the installed product utilities (see above).

The installation program lets you specify a directory other than the ESP7NGENdirectory.

ESP7 Installation

47 A2 92US Rev01 2-3

2.3 Installation Procedure

Note that this version of ESP7NGEN can be installed from a PC either using abrowser to access Interop7 Web site or with the two 3,5’’ disks.

Messages displayed during the installation procedure will be either in French orEnglish (default) language, according to the system configuration.

2.3.1 Installation from Interop7 Web Site

Note that the detail of the following Web pages may vary slightly from one versionto the next, but the underlying principle will remain unchanged.

To connect to the Interop7 Web site, enter the following URL in your browser:

http://<DPS 7000 XTA server>/Interop7

where <DPS 7000 XTA server> is the Windows 2000 server TCP/IP host namewhere Interop7 has been installed.

In the home page that appears, select the «Download Interop7 products on yourPC» link:


2-4 47 A2 92US Rev01

In the page that appears, click the «ESP7NGEN Info» link:

ESP7 Installation

47 A2 92US Rev01 2-5

Lastly, click the «ESP7NGEN (release V7.4.0) installation» link:

A self-extracting executable file (named ESP7NGEN.exe) is then downloaded tothe PC. Once launched (either by the browser, or by the user if he chose to save iton his PC), the installation begins.

2.3.2 Installation from Diskettes

Note : More than one diskette will be required by the installation program only ifthe versions of the system DLL libraries are older than the required ones.

Carry out the operations indicated below to install the ESP 7 components.

1) Start Windows.

2) If you have a previous version of ESP 7, you must first de-instal it.

3) Insert the first ESP 7 diskette in the floppy drive.

4) Run the installation program (install / remove software) or runSetUp.exe.

5) Advance from window to window until the following window appears.

At this stage you have to choose your installation directory.


2-6 47 A2 92US Rev01

Note that by default the directory C:\ESP7NGEN is proposed. You may enteranother directory if you wish. In the example, D:\ESP7NGEN has been used.

ESP7 Installation

47 A2 92US Rev01 2-7

Now click on Next to advance to the following screen:

Choose the type of installation required (Client for two-tier version Server forthree-tier version).


2-8 47 A2 92US Rev01


The ‘Custom installation’ option is no longer mandatory.

The ‘Typical’ option, if selected, leads to installation of Visual Basic/PowerBuilderprogram samples, while the ‘Compact’ option does not; this is the only differencebetween these two options.

The sample Visual Basic and PowerBuilder sources are found in the ESP7NGENinstallation directory in Samples/Visual Basic and Samples/PowerBuilder.

ESP7 Installation

47 A2 92US Rev01 2-9


Now you must choose your configuration parameters.

Note that the above utility is common to several products. For this reason, not allthe fields displayed are relevant in the ESP 7 context.

The following list outlines the fields to be filled for ESP 7:

PATH the path where the product is to be installed(C:\ESP7NGEN by default).

CRYPT yes / no (yes by default) for password encryption.

TIMEOUT1 timeout applied for connections(20 seconds by default).

TIMEOUT2 timeout applied for data recuperation(600 seconds by default).

VERSION the default value 1 MUST NOT BE MODIFIED.

To validate, click on OK.


2-10 47 A2 92US Rev01

8) Advance until the “Setup Complete” window appears.

If the installation process needed to install/update one or more system files, youwill have to reboot your computer in order to complete this installation. In thatcase, the following window will be displayed :

ESP7 Installation

47 A2 92US Rev01 2-11

If your system does not need to be rebooted, the following window will bedisplayed:

In either case, click on Finish to clear this final dialog box.

Note that, if you are re-installing the ESP 7 product, then you must copy yourprocedure definition file <DPS 7000 XTA system name>.pr1 to your choseninstallation directory (the utility Espadmpc.exe is already there). The mostconvenient way to do this is to use the Transfer facilities of Espadmpc (GetAllProcoption).


2-12 47 A2 92US Rev01

❑

47 A2 92US Rev01 3-1

3. Enterprise Server Procedures 7

3.1 Product features

The main goal of the ESP7 product is to provide a programmable softwarecomponent that enables Windows applications to execute GCOS7 TDS applicationservices (transactions).

As this component is built upon Microsoft ActiveX technology, it can be used by avariety of client applications. They can be existing programmable applications,such as Microsoft Word or Microsoft Excel (using the Visual Basic forApplications integrated development environment), or entirely new ones,developed with any ActiveX-supporting RAD tool (such as Microsoft Visual Basicor Sybase PowerBuilder).

An ESP7-based program can be a simple two-tier application that only displaysdata sent by a TDS transaction, or it can be a more complex three-tier Webapplication which retrieves data from GCOS7 files through TDS transactions andsends them to a Web browser running on a distant workstation.

Data conversion between the Windows and GCOS7 environments(ASCII/EBCDIC strings, memory data storage and numeric representation) is fullyhandled by the ESP7 software component, which only requires the description ofboth input and output data (that is, the TDS procedure arguments and the result setsreturned by the transaction) through a tool provided with the product.


3-2 47 A2 92US Rev01

3.2 Functional Description

Figure 3-1 shows the connection between a client application and a TDS, usingESP7:

Client application

Client application

Client application

ESP7 ActiveX control

TDS Object

TDS Object

TDS Object

Dim WithEvents tdsObj as ESP7SRV.TDS … Set tdsObj = CreateObject(“ESP7SRV.TDS.1”) … tdsObj.Connect() …

NT7GW

TCP/IP TCP/IP

VCAM VCAM

TDS TDS

Windows

GCOS7

ESP7 Object Server

Figure 3-1. Connection between Client Application/TDS

The client application triggers the GCOS 7 TDS transactions by means of a TDSobject (a combination of code and data treated as a unit), provided by an objectserver (ESP7srv.exe – “ActiveX component” in Microsoft terminology, formerlyknown as ActiveX or Automation “server”). This TDS object is built uponMicrosoft ActiveX/Automation technology, which means it provides itsfunctionality – in our case executing GCOS7 transactions – to the client applicationthrough a set of properties, methods and events which are described in theparagraph “ESP7 Interface” below.

Enterprise Server Procedures 7

47 A2 92US Rev01 3-3

As shown Figure 3-1, two client applications on the same PC can share the sameTDS connection (defined by TDS user name, password, mailbox, project, billingand terminal identifier) to execute their transactions.

Instead of using a TDS object directly, applications that were developed withprevious versions of ESP7NGEN can still use the ESP7 ActiveX control, whichforwards the client application calls to the TDS object.

Communications between the TDS object and the TDS rely on a protocol dialog:

• At a lower level, the TDS object sends and receives data through the TCP/IPsockets layer to the NT7 Gateway running on the DPS 7000 XTA server, whichforwards the data through the VCAM layer.

• At a higher level, the TDS object processes the transaction procedure parametersgiven by the client application to build a command line that it sends to the TDS.Then, the called transaction performs its job and returns data to the TDS objectfollowing specific rules, concerning mainly the data structures that are sent back.These rules are described in the ESP7 GCOS7-side documentation “EnterpriseServer Procedures for GCOS 7” (47 A2 35UT).

The PC side manages a file containing the definition of the procedures of the TDSapplication that PC client applications may trigger. This procedure definition filemay be located either on the PC or on the DPS 7000 XTA server.


3-4 47 A2 92US Rev01

3.3 Using the TDS Object

To use the TDS object in a client application, it is necessary to set up the propertyor method call to be made using a particular object variable: a process calledbinding (the variable to the object). There are two types of binding defined inMicrosoft Automation technology:

• Early binding, where the object variable type is known at compilation time (thatis, it is specified in the variable declaration).

• Late binding, where the determination of the actual object methods andproperties is made at run time.

Early binding is the preferable way of declaring a TDS object variable, as it willmake object calls faster by avoiding extra processing (property/method nameresolution). Furthermore, this is the only way to handle specific TDS object events(see section 3.5.3, Events). However, some development tools (such as SybasePowerBuilder 5.0) do not seem to support it, in which case the only options are touse either TDS object late binding or ESP7 ActiveX control.


47 A2 92US Rev01 3-5

3.3.1 Using Early Binding

Using early binding with the TDS object requires with the following steps:

• Addition of a reference to the ESP7 ActiveX Component LibraryIn Microsoft Visual Basic, this is done by choosing References in the Projectmenu, and selecting “BULL ESP7 ActiveX Component Library” in the dialogbox that appears:

• Declaration of an object variable of the TDS Object type. In Visual Basic, it willbe:

Dim WithEvents tdsObj as ESP7SRV.TDS

The TDS object type is composed of two parts: the name of the component thatsupplies the object (‘ESP7SRV’) and the name of the TDS Object class (‘TDS’).


3-6 47 A2 92US Rev01

After the variable has been declared with the ‘WithEvents’ keyword, the VisualBasic code window can use the variable to display event procedures for the TDSObject in the Procedure list box. In this case, the TDS Object exposes onespecific event called ‘Message’, so the displayed event procedure will beobjectvariable_Message:

• Assignation of an object reference to the object variableIn Visual Basic, it is done using CreateObject method:

Set tdsObj = CreateObject("ESP7SRV.TDS.1")

Here, ‘ESP7SRV.TDS.1’ is the programmatic interface (‘ProgID’) of the TDSobject, that is a string which uniquely identifies the object class. It is alsopossible to use the version-independent ProgID, which avoids recompilation ofthe application each time a new version of the object class is installed:

Set tdsObj = CreateObject("ESP7SRV.TDS")

Remark: A ‘WithEvent’ variable cannot be declared ‘as New’ to create a newinstance of the object class.

• When the object is no longer of use, any variable that references the objectshould be cleared, so that the object can be released from memory. This is doneby setting the object variable to ‘Nothing’:

Set tdsObj = Nothing


47 A2 92US Rev01 3-7

3.3.2 Using Late Binding

Using late binding with the TDS object can be made with the following steps:

• Declaration of an object variable of the generic object classIn Visual Basic, it will be as follows:

Dim tdsObj As Object

And in PowerBuilder:

OLEObject iole_tdsObj

• Assignation of an object reference to the object variableIn Visual Basic, it will be as follows:

Set tdsObj = CreateObject("ESP7SRV.TDS")

And in PowerBuilder:

iole_tdsObj = CREATE OLEObjectli_result = iole_TDSObj.ConnectToNewObject("ESPSRV.TDS.1")


3-8 47 A2 92US Rev01

3.4 Using ESP7 ActiveX Control

As previously stated, it is possible to use the ESP7 ActiveX control in a clientapplication rather than using the TDS object directly. Two reasons may lead to thischoice:

• The client application was developed with a previous version of ESP7 in whichthe TDS object was not available

• The client application is developed with a RAD tool that does not support earlybinding (see previous paragraph), and the client application needs to handle the‘Message’ event sent by the TDS object.

The TDS object and the ESP7 ActiveX control expose the same interface (in termsof properties, methods and events) to the client application (see section 3.5, ESP7Interface), except for the GetFieldInfo() method: In the TDS object, the outputarguments (Name, Type, Length) are variants, rather than strings in the ActiveXcontrol. This modification was implemented to enable a Web application to call thismethod from an ASP page, where output arguments of methods must be variants.

The same error constant names are defined for the TDS Object and the ActiveXcontrol (see section 3.6.1, Error Constants), with the same meaning, although theirvalues are different as result codes contain information about the error source:Error constant values range from 0x800403e9 to 0x800403fe for the TDS Objectand from 1001 to 1022 for the ActiveX control.

To be used, the ESP7 ActiveX control must be inserted in a container (a parentprogram that provides an environment for the control to run). A control containertypically takes the form of a dialog-like window.

In Visual Basic, the simplest way to insert the ESP7 ActiveX control is by adding itto the project’s toolbox (by choosing “Components” from the Project menu, thenselecting “BULL ESP7 ActiveX Control Module” in the Controls tab), then addingit to a Form like an intrinsic control (such as Label or Text Box).

In PowerBuilder, the ESP7 ActiveX control can be inserted choosing the “InsertControl” page of the “Insert Object” dialog box, the selecting “BULL ESP7ActiveX Control Module”.


47 A2 92US Rev01 3-9

3.5 ESP7 Interface

The user has at his disposal the following properties, methods, and events for theexecution of remote TDS transactions from his PC.

3.5.1 Properties

Except SessionID, all properties are used by the Connect method (see section 3.5.2,Methods):

3.5.1.1 SessionID

Description A read-only long-type property providing the sessionidentifier.

It is set to a positive value after a successfulconnection has been established.

Initial value –1 (no session)

3.5.1.2 Node

Description A character string (maximum 12 characters) providingthe name of a connection identifier defined through theConnection Handling utility (DSNCNFG: seesection 4.3, Configuring connection parameters).

If it is not empty, the connection parameters definingthis node will be used during the connection.

Each connection parameter value may be overriddenusing the matching connection property.

Default value Empty string


3-10 47 A2 92US Rev01

3.5.1.3 Host

Description A character string (maximum 8 characters) providingthe TCP/IP host name of the DPS 7000 XTA serverwhere the NT7 gateway is to be accessed.If the TCP/IP host name exceeds 8 characters, an aliasmust be declared in the system “hosts” file (see §4.1Configuring TCP/IP).

If not empty, it will override the “Host name” value ofthe virtual node if the latter is used.


3.5.1.4 Port

Description A long-type value providing the port number forcommunication with the NT7 gateway.

A positive value will override the “Port num” value ofthe virtual node if the latter is used (i.e. a negativevalue will not override the node parameter).

A valid port number must be between 1024 and 65535.

Default value -1


47 A2 92US Rev01 3-11

3.5.1.5 GCOS

Description A character string (maximum 4 characters) providingthe name of the GCOS 7 system to be accessed.

If not empty, it will override the “GCOS” value of thevirtual node if the latter is used.


3.5.1.6 Mailbox

Description A character string (maximum 8 characters) providingthe name of the TDS mailbox to be accessed.

If not empty, it will override the “Mailbox” value ofthe virtual node if the latter is used.


3.5.1.7 User

Description A character string (maximum 12 characters) providinga valid user name for the TDS mailbox connection. Ifnot empty, it will override the “UserName” value ofthe virtual node if the latter is used.


3.5.1.8 Password

Description A character string (maximum 12 characters) providinga valid password name for the TDS mailboxconnection.

If not empty, it will override the “Password” value ofthe virtual node if the latter is used.



3-12 47 A2 92US Rev01

3.5.1.9 Project

Description A character string (maximum 12 characters) providinga valid project name for the TDS mailbox connection.If not empty, it will override the “Project” value of thevirtual node if the latter is used.


3.5.1.10 Billing

Description A character string (maximum 12 characters) providinga valid billing name for the TDS mailbox connection.If not empty, it will override the “Billing” value of thevirtual node if the latter is used.


3.5.1.11 TermId

Description A character string (maximum 7 characters) providingthe Terminal Identifier. The value of this property willbe sent to executed TPRs through the SYMBOLICSOURCE field of the input CommunicationDescription (see the Communication Section in theappropriate TDS Programmer’s Guide). A dollarcharacter is automatically added at the beginning of thestring, so that the TDS may know that itscorrespondent is a PC.

If not empty, it will override the “TerminalId” value ofthe virtual node if the latter is used.



47 A2 92US Rev01 3-13

3.5.1.12 Trace

Description A boolean which, if set to TRUE, will activate thetrace facility.

Note: The Trace facility will be activated if either thisproperty is set to TRUE or the Trace field of the virtualnode is set to “YES” (see section 3.6.2, TraceFacility).

Default value FALSE

3.5.1.13 TDSPrompt

Description A character string (maximum 46 characters) providingthe currently applied TDS prompt.

If not empty, it will override the “-r” option in the“Other” field of the virtual node if the latter is used.

Default value “READY”

3.5.1.14 UseRemoteProcedureFile

Description A boolean which, if set to TRUE, will indicate that theProcedure definition file is to be retrieved from theDPS 7000 XTA server, rather than from the PC.

If not empty, it will override the “-c Open7” option inthe “Other” field of the virtual node if the latter isused.

Default value FALSE


3-14 47 A2 92US Rev01

3.5.2 Methods

Connect to connect to a TDS session.

Disconnect to disconnect from a TDS session.

GetProcedureInfo to obtain information on a given procedure (name, typeand length for each input and output parameter).

ExecuteProcedure to execute a TDS transaction.

NumberOfFields to obtain the number of fields of output parameterscorresponding to a given procedure call.

NumberOfRows to obtain the number of rows of output correspondingto a given procedure call.

GetData to obtain output field j of row i for a given procedurecall.

GetFieldInfo to obtain information (name, type, and length) foroutput field j for a given procedure call.

3.5.2.1 Connect

Function to connect to a TDS session.

Input parameters none (all connection parameters are set by the ActiveXcontrol properties: see section 3.5.1, Properties)

Output parameters none.

Returned value none.

NOTE:Successful completion of this method sets the SessionId attribute value.

3.5.2.2 Disconnect

Function to disconnect from a TDS session.

Input parameters none.




47 A2 92US Rev01 3-15

3.5.2.3 GetProcedureInfo

Function to obtain information on a given procedure (name,type, and length for each input and output parameter).

Input Parameter Type Comment

Procedure String Name of the TDS transaction for whichinformation is requestedMaximum length: 8


Returned value String containing the input procedure information:procedure name([in|out] parameter type parametername, …).


3-16 47 A2 92US Rev01

3.5.2.4 ExecuteProcedure

Function to execute a TDS transaction.


Procedure String Name of the TDS transaction to beexecutedMaximum length: 8

ParametersList String String containing the input parameters forthe TDS transactionMaximum length: 32K



The parameter values in the ParametersList string are separated by one or morespace characters.


47 A2 92US Rev01 3-17

Each parameter value must have a determined format according to its type:

Type Format Limits

SMALLINT [{+ | –}] [0 [{ x | X }]] [digits] Minimum decimal value:-32768Maximum decimal value:+32767

INT [{+ | –}] [0 [{ x | X }]] [digits] Minimum decimal value:-2147483648Maximum decimal value: +2147483647

FLOAT [{+ | –}] [digits] [.digits] [ {d | D| e | E}[{+ | –}]digits]

Minimum positive value: 1.175494351e-38Maximum positive value: 3.402823466e+38

CHAR ['][ascii_chars][']

DECIMALtypes(packed/unpacked,signed/unsigned)

[{+ | -}] [digits] [.digits] Maximum precision (total number of digits)is 29.Maximum scale (number of digits afterdecimal separator) is 28.With a scale of 0 (no decimal places), thelargest possible value is:+/-79,228,162,514,264,337,593,543,950,335.With a 28 decimal places, the largest value is:+/-7.9228162514264337593543950335 andthe smallest, non-zero value is:+/-.0000000000000000000000000001.

For SMALLINT-type and INT-type parameters, decimal and hexadecimal valuesmay be given following this convention:

• If the first (second if sign character is used) character is '0' and the second (thirdif sign character is used) character is 'x' or 'X', the string is interpreted as ahexadecimal integer.

EXAMPLES: 0xFFFF -0x1234

• If the first (second if sign character is used) character is '1' through '9', the stringis interpreted as a decimal integer.


3-18 47 A2 92US Rev01

A CHAR-type parameter value must begin and end with a quote character in thefollowing cases:

• when it is empty,

• when it contains at least one space character,

• when it contains at least one quote character, which must be followed by anotherone to protect it.

EXAMPLE: Valid CHAR-type parameter values

’’This_is_a_valid_string’This is another valid string’’another one with a quote character (’’)’

❑

NOTE:A CHAR-type input parameter value will be padded with space characters tomatch its definition length.

3.5.2.5 NumberOfFields

Function to obtain the number of output parameterscorresponding to a given procedure call.


Procedure String Name of the TDS transaction for whichinformation is requested. Maximum length: 8


Returned value the number of output parameters (long-type value)


47 A2 92US Rev01 3-19

3.5.2.6 NumberOfRows

Function to obtain the number of rows of output correspondingto a given procedure call.


Procedure String Name of the TDS transaction for whichinformation is requested. Maximum length: 8


Returned value the number of output rows (long-type value)

3.5.2.7 GetData

Function to obtain the output field j of row i for a givenprocedure call.


Procedure String Name of the TDS transaction for which data isrequested. Maximum length: 8

RowIndex Long Index of the row for which data is requested(starting from 0)

FieldIndex Long Index of the column for which data is requested(starting from 0)


Returned value requested data value (“Variant” type in Visual Basic,“Any” in PowerBuilder)


3-20 47 A2 92US Rev01

3.5.2.8 GetFieldInfo

Function to obtain information (name, type and length) foroutput field j for a given procedure call.


Procedure String Name of the TDS transaction for which data isrequested. Maximum length:8

Index Long Index of the column for which information isrequested (starting from 0)

OutputParameters

Type Comment

Name String (byreference)

Name of output parameter j

Type String (byreference)

Type of output parameter j

Length long (byreference)

Length of output parameter j



47 A2 92US Rev01 3-21

3.5.3 Events

3.5.3.1 Message

The TDS object uses a custom event named Message to notify the clientapplication of information and error messages sent by the TDS.

This event will be raised by the control when calling the ExecuteProcedure methodif the executed TPR sends a type-1 or type-2 message.

In this case, the following parameters will be available to the event-handlingprocedure of the client application:

Name Type Comment

MsgProcedure String Name of the TPR that sent the message

MsgType Short TPR output message type. A value of 1means an information message, a value of 2means an error message.

MsgStatus Long Status generated by the TDS transaction

MsgText String Message sent by the TPR


3-22 47 A2 92US Rev01

3.6 Error Handling in the Client Application

When the ESP7 TDS Object notifies the client application that an error hasoccurred, it sends it an error code and an error text description to identify theproblem. If the error is the abort of an executed TPR, then the Message event willalso be generated.

When an error occurs in a method of the TDS Object that returns a value throughits call (eg NumberOfFields) or through a reference parameter (GetFieldInfo), it ishighly advised not to check this value, as it will not be initialized by the TDSObject.

Error handling in a Visual Basic application

In Visual Basic, the client application developer may specify an error-handlingroutine using the OnError statement. In this routine, we will use the Number andDescription properties of the Err object, which will be filled with the error codeand text description sent by the TDS Object, to determine the cause of the error.

EXAMPLE: Valid error-handling in Visual Basic

Dim MsgOn Error GoTo errorLabeltdsOBJ.Disconnect()MsgBox "Successful Disconnect"Exit SuberrorLabel:Msg = "Disconnect : Error # " & Str(Err.Number) & Err.DescriptionMsgBox Msg, , "Error"End Sub

❑

Note that a complete example of a VisualBasic client application is given latter inthis chapter. Some migration tips are provided in Appendix A.

Error handling in a PowerBuilder application

In PowerBuilder, the client application developer may handle an error signaled bythe TDS Object using the ExternalException event.

In this event, the error code can be retrieved from the low word of the resultcodeargument (using the IntLow() function). The text description is contained in thedescription argument.


47 A2 92US Rev01 3-23

3.6.1 Error Constants

Error constants are supplied with the TDS Object to identify the Numberproperty value it will set. They are described below:

• esp7NoError : No error (code 0x800403e8).

• esp7AbortedProcedure (code 0x800403e9)The executed procedure has aborted.The Message event is sent to the client application.

• esp7ArgumentError (code 0x800403ea)An argument of the called method is erroneous (ex : negative value for the Portparameter of the Connect method).

• esp7BusyConnection (code 0x800403eb)This error code is left for compatibility with previous versions of ESP7. It is notsent anymore.

• esp7DataValueError (code 0x800403ec)This error code will be sent if the data sent by the NT7 gateway has erroneouscontents. Use the trace facility (see section 3.6.2, Trace Facility) to identify theproblem.

• esp7DSNFileAccessError (code 0x800403ed)An error occurred while accessing the DSN configuration file (maintained withthe dsncnfg utility).

• esp7InputParameterError (code 0x800403ee)An parameter value in the ParameterList parameter string of theExecuteProcedure method does not match its type defintionex: ‘ZZ’ for an INT type parameter, or 99999 for a SMALLINT type parameter).

• esp7InternalError (code 0x800403ef)An internal error occurred. Contact your support team.

• esp7NoConnection (code 0x800403f0)Called method requires that a successful connection be made before using it.

• esp7NoMoreSessions (code 0x800403f1)No more sessions are available.

• esp7NumberOfParametersError (code 0x800403f2)The number of parameters in the ParameterList parameter string of theExecuteProcedure method does not match the procedure definition.

• esp7Open7GatewayError (code 0x800403f3)An error occurred in the NT7 gateway. Contact your support team.


3-24 47 A2 92US Rev01

• esp7OutputParameterError (code 0x800403f4)An output parameter value does not match its type definition. This error codewill be sent if an output parameter value length exceeds its defined length, or ifone of the name/type/length fields in the SQLDA message structure does notmatch the procedure parameter definition.

• esp7ProcedureFileAccess (code 0x800403f5)An error occurred while accessing the Procedure definition file.

• esp7ProcedureFileContents (code 0x800403f6)An error occurred while analyzing the Procedure definition file contents.

• esp7ProcedureNotExecuted (code 0x800403f7)This error occurs when calling either the NumberOfRows or GetData method ifthe ExecuteProcedure method has not been successfully called first.

• esp7SyntaxError (code 0x800403f8)Syntax error in the ParameterList parameter string of the ExecuteProceduremethodex: a beginning-of-string quote character does not have a matching end-of-stringquote character

• esp7TBLFileAccessError (code 0x800403f9)An error occurred while accessing the Table Translation file (maintained withthe tblpcgc utility).

• esp7TDSDisconnection (code 0x800403fa)(Connect method only): Previous session to the TDS was abnormallydisconnected and last transaction may not have been successfully completedbefore the disconnection. The current connection attempt indicates thispossibility by the return of this property value. The next connection attempt withthe same parameters will not raise this error.

• esp7UnknownNode (code 0x800403fb)The node name (given in the Host parameter of the Connect method) does notmatch any virtual node in the DSN configuration file (maintained with thedsncnfg utility).

• esp7UnknownProcedure (code 0x800403fc)Current procedure name has not been found in the procedure information file, orGetProcedureInfo method has not been successfully called.

• esp7VCAMError (code 0x800403fd)An error occurred in the GCOS7 VCAM layer.

• esp7WinsockError (code 0x800403fe)An error occurred in the Windows Socket layer.


47 A2 92US Rev01 3-25

3.6.2 Trace Facility

Viewing the data exchanged by the ESP7 TDS Object and the TDS may be usefulfor the developer of the client application. For example, while it is possible tocatch a message sent by a TPR through the ESP7 TDS Object, a message sent bythe TDS itself cannot be directly accessed by the developer.

This facility can be activated by passing a True value for the Trace argument whencalling the Connect method of the control. Alternatively, tracing can be requestedby setting the Trace field to YES in the corresponding connection entry. In eachcase, a file containing all data exchanged between the control and the TDS will becreated if the connection is successful. The name of this file will be :

<ESP7 install dir>\trces_<sid>.log

where <ESP7 install dir> is the directory where ESP7 has been installed and <sid>is the session identifying the current connection (also given by the SessionIdattribute of the control).

Note that a trace file will also be produced for each ESP7 connection on the DPS7000 XTA server if NT7GW trace level has been set to three or greater. The tracefile name will be:

<NT7GW install dir>\NTGW_<server identifier>\<TermId> where:

• <NT7GW install dir> is the directory where NT7GW has been installed

• <server identifier> is the identifier of the running NT7GW server

• <TermId> is the TermId property string value (see section 3.5.1, Properties) if itis not empty, or the TCP/IP host name of the client PC if it can be computed, orthe TCP/IP address of the client PC

For further information about NT7GW trace, see the Interop7 User’s Guide(ref. 47A291US)


3-26 47 A2 92US Rev01

3.7 User Interface

3.7.1 User Profiles

Typical users of the ESP 7 facility are application developers who wish to takeadvantage of the user-friendly capabilities of the client/server environment, such asGraphical User Interfaces (GUIs), and at the same time recognize the value ofmaintaining their data repository enterprise systems such as IDS/II on GCOS 7.

Users of ESP 7 connectivity can develop application programs on PC workstations.A typical PC application program would be a Windows application generated by a4GL package such as PowerBuilder or Visual Basic.

In all cases, the user is accessing data and services located on a GCOS 7 system.

3.7.2 User Interface Mechanics

Clients may wish to develop new TDS transaction programs to access data residingon GCOS 7 systems. Alternatively, they may need to reference existing GCOS 7TDS transactions. Such TDS transactions require slight changes to be able tointerface via ESP 7 with PC applications developed with RAD tools.

The data stream to TDS TPRs is via the NT7 gateway. The input data is firsttreated, then the appropriate target TPR is called. When control is returned toESP7 from the target TPR, any data from the target TPR is converted to a formatexpected by the client. The ESP7 TDS Object performs all extendedASCII/EBCDIC converting operations.

There are several tools that the client can use to access procedures stored onGCOS 7 systems. The following examples show the use of some of the mostwidely used tools.


47 A2 92US Rev01 3-27

3.7.3 Accessing Stored Procedures from PowerBuilder

An example of a PowerBuilder application is provided in the fileSamples/PowerBuilder/esppbclient.pbl (under the installation directory).Some extracts are given below for reference:

SCRIPT FOR CONNECTION

Script – clicked for cb_open returns long

// Event triggered when the user opens a new connection (Openbutton)

long ll_port

// If a run-time error occurs while calling one of the ActiveXcontrol// methods, the ExternalException event will be triggered.

IF IsNumber(sle_port.Text) THEN IF sle_mailbox.Text = "" THEN gs_dest = ’TDS (using ’ + sle_node.Text + ’ node)’ ELSE gs_dest = sle_mailbox.Text END IF ole_esp.object.Node = sle_node.Text ole_esp.object.Host = sle_host.Text ole_esp.object.Port = Long(sle_port.Text) ole_esp.object.GCOS = sle_gcos.Text ole_esp.object.Mailbox = sle_mailbox.Text ole_esp.object.User = sle_user.Text ole_esp.object.Password = sle_password.Text ole_esp.object.Project = sle_project.Text ole_esp.object.Billing = sle_billing.Text ole_esp.object.TermId = sle_termid.Text ole_esp.object.Trace = cbx_trace.Checked ole_esp.object.Connect() ib_connected = True printtext(’Successful connection to ’ + gs_dest)

(...)ELSE MessageBox(’Error’, ’Port must be a number’, StopSign!)END IF


3-28 47 A2 92US Rev01

SCRIPT FOR DISCONNECTION

Script – clicked for cb_close returns long

// Event triggered when the user closes the active connection// (Close button)

// If a run-time error occurs while calling one of the ActiveXcontrol// method, the ExternalException event will be triggered.

ole_esp.object.Disconnect()

// At this point, the Disconnect() method of the ESP7 ActiveXcontrol// was successful.

ib_connected = Falseprinttext(’Successful disconnection from ’ + gs_dest)

(...)

SCRIPT FOR GETTING PROCEDURE INFO

Script – clicked for cb_procedureinformation returns long

// Procedure called when the user requests information about a TPR(Information// button)

String ls_info

ls_info = ole_esp.object.GetProcedureInfo(sle_procedurename.Text)printtext(ls_info)

SCRIPT FOR EXECUTING PROCEDURE

Script – clicked for cb_procedureexecute returns long

// Event triggered when the user executes a TPR (Execute button)

ole_esp.object.ExecuteProcedure(sle_procedurename.Text,sle_procedureparameters.Text)printtext("Completed " + sle_procedurename.Text)


47 A2 92US Rev01 3-29

SCRIPT FOR GETTING PROCEDURE DATA

Script – clicked for cb_proceduregetdata returns long

// Event triggered when the user wants to recover the data sent bythe// executed TPR (GetData button)

long ll_fieldindex, ll_fieldsnb, ll_rowindex, ll_rowsnbString ls_dataAny la_data

// Get the number of output parameters for current TPRll_fieldsnb =ole_esp.object.NumberOfFields(sle_procedurename.Text)

// Get the number of rows of output parameter valuesll_rowsnb = ole_esp.object.NumberOfRows(sle_procedurename.Text)

// For each row, get the value of each output parameterFOR ll_rowindex = 0 TO ll_rowsnb - 1 ls_data = ’’ FOR ll_fieldindex = 0 TO ll_fieldsnb - 1 la_data =ole_esp.object.GetData(sle_procedurename.Text, ll_rowindex, ll_fieldindex) ls_data = ls_data + ’ ’ + String(la_data) NEXT printtext(ls_data)NEXT

SCRIPTS FOR HANDLING ERRORS SIGNALLED BY THE ESP7 CONTROL

Script – externalexception for ole_esp returns [None]

// Event triggered when an error occurs in the ActiveX control// It may be an error signaled by the control to the application,or// an internal exception in the control.

IF exceptioncode = 0 THEN// If there was no internal exception in the ActiveX control gb_esperror = True// ... set boolean global variable that will be checked in// SystemError event, so that the application will not end.END IFprinttext(String(IntLow(resultcode)) + ": " + description)// The SystemError event will then be triggered


3-30 47 A2 92US Rev01

Script – systemerror for esppbclient returns [none]

IF gb_esperror <> True THEN // Error was not signaled by the ESP7 ActiveX control MessageBox('Fatal error', 'Error:' + String(error.text) +' at line ' +String(error.number) + & ' event:' + error.ObjectEvent +' object:' + error.object + ' text:' + error.text + & ' windowmenu:' + error.WindowMenu, StopSign!) HALT CLOSEEND IF

SCRIPT FOR HANDLING TPR MESSAGES

Script – message for ole_esp return [none]

IF msgtype = 1 THEN printtext(’--- ’ + msgprocedure + ’ : ’ + msgtext + ’ (status : ’ + String(msgstatus) + ’)’)ELSE printtext(’*** ’ + msgprocedure + ’ : ’ + msgtext + ’ (status : ’ + String(msgstatus) + ’)’)END IF


47 A2 92US Rev01 3-31

3.7.4 Accessing Stored Procedures from Visual Basic

Only procedures (TPRs) that return tuples and/or messages may be used from theVisual Basic application. Note that, when using Visual Basic, the maximumvolume of data which can be handled in a single request is 32000 bytes.

Messages returned may be of:

Type 1 informative

Type 2 error

An example of a VisualBasic client application (source and executable) iscontained in the Samples/Visual Basic directory created by the setup.exeinstallation program under the installation directory. Below is part of the sourcecode containing the calls to the ActiveX methods:

Option Explicit’ Declare a variable as TDS Object type’ (created by ESP7NGEN object server)Public WithEvents tdsObj As ESP7SRV.TDS’ The user may forget to close the connection before exiting’ the application, so we need to know if the connection is’ established in order to close it before leaving.Dim gbConnected As BooleanDim strDest As String

’ Print a string in the message text boxPublic Sub PrintText(strText As String)txtMessages.Text = txtMessages.Text & strTexttxtMessages.SelStart = Len(txtMessages.Text)End SubPublic Function Checked(Value As Integer) As BooleanIf Value = 1 Then Checked = TrueElse Checked = FalseEnd IfEnd Function


3-32 47 A2 92US Rev01

’ Procedure called when the user closes the active connection’ (Close button)Private Sub cmdClose_Click()’ If a run-time error occurs, branch to an error-handling’ routine.On Error GoTo DisconnectErrorHandlertdsObj.Disconnect’ At this point, the Disconnect() method of the TDS Object’ was successful.gbConnected = FalsePrintText "Successful Disconnection from " & txtGCOS.Text & vbCrLf’ Destroy object variableSet tdsObj = Nothing’ Enable user to modify the connection text boxes’ Enable the Open button’ Disable the Close button’ Disable all Procedure frame buttons’ (Information, Execute, GetData)txtHost.Locked = FalsetxtPort.Locked = FalsetxtGCOS.Locked = FalsetxtMailbox.Locked = FalsetxtUser.Locked = FalsetxtPassword.Locked = FalsetxtProject.Locked = FalsetxtBilling.Locked = FalsetxtTermId.Locked = FalsechkTrace.Enabled = TruecmdOpen.Enabled = TruecmdClose.Enabled = FalsecmdProcedureExecute.Enabled = FalsecmdProcedureInformation.Enabled = FalsecmdProcedureGetData.Enabled = FalseExit Sub’ Error-handling routine when closing the connection.’ Whether the error comes from the system or the TDS Object,’ the properties of the Err object will give information about it.DisconnectErrorHandler:PrintText "*** Aborted Disconnection from " & strDest & _" : " & Err.Number & " (" & Err.Description & ")" & vbCrLfEnd Sub


47 A2 92US Rev01 3-33

’ Procedure called when the user opens a new connection (Open’ button)Private Sub cmdOpen_Click()Dim dwPort As LongOn Error GoTo ConnectErrorHandlerIf txtMailbox.Text = "" Then strDest = "TDS (using " & txtNode.Text & " node)"Else strDest = txtMailbox.TextEnd If’ Create new instance of TDS Object class’ The ProgID (programmatic identifier) of this object is’ "ESP7SRV.TDS.1"Set tdsObj = CreateObject("ESP7SRV.TDS.1")’ Initialize each connection property of the TDS Object with the’ contents of the matching text fieldtdsObj.Node = txtNode.Text’ Note that when a virtual node is used, there is no need to’ initialize the other connection properties unless the node’ parameter values must be overriddentdsObj.Host = txtHost.TexttdsObj.Port = CLng(txtPort.Text)tdsObj.GCOS = txtGCOS.TexttdsObj.Mailbox = txtMailbox.TexttdsObj.User = txtUser.TexttdsObj.Password = txtPassword.TexttdsObj.Project = txtProject.TexttdsObj.Billing = txtBilling.TexttdsObj.TermId = txtTermId.TexttdsObj.Trace = Checked(chkTrace.Value)’ Call the Connect method. If it fails, the current error handler’ (ConnectErrorHandler) will be calledtdsObj.ConnectgbConnected = TruePrintText "Successful connection to " & txtGCOS.Text & vbCrLf’ Prevent user from modifying the connection text boxes, now’ that a connection has been established.’ Disable the Open button’ Enable the Close button’ Enable all Procedure frame buttons’ (Information,Execute,GetData)txtHost.Locked = TruetxtPort.Locked = TruetxtGCOS.Locked = TruetxtMailbox.Locked = TruetxtUser.Locked = TruetxtPassword.Locked = TruetxtProject.Locked = TruetxtBilling.Locked = TruetxtTermId.Locked = TruechkTrace.Enabled = False


3-34 47 A2 92US Rev01

cmdOpen.Enabled = FalsecmdClose.Enabled = TruecmdProcedureExecute.Enabled = TruecmdProcedureInformation.Enabled = TruecmdProcedureGetData.Enabled = TrueExit SubConnectErrorHandler:PrintText "*** Aborted connection to " & strDest & " : " & _Err.Number & " (" & Err.Description & ")" & vbCrLfEnd Sub

’ Procedure called when the user executes a TPR (Execute’ button)Private Sub cmdProcedureExecute_Click()On Error GoTo ProcedureExecuteErrorHandlertdsObj.ExecuteProcedure txtProcedureName.Text, _txtProcedureParameters.TextPrintText "Completed " & txtProcedureName.Text & vbCrLfExit SubProcedureExecuteErrorHandler:PrintText "*** Cannot execute " & txtProcedureName.Text & " : " _& Err.Number & " (" & Err.Description & ")" & vbCrLfEnd Sub

’ Procedure called when the user wants to recover the data’ sent by the executed TPR (GetData button)Private Sub cmdProcedureGetData_Click()Dim dwFieldIndex, dwFieldsNb, dwRowIndex, dwRowsNb As LongDim vData As VariantDim strData As StringOn Error GoTo ProcedureGetDataErrorHandler’ Get the number of output parameters for current TPRdwFieldsNb = tdsObj.NumberOfFields(txtProcedureName.Text)’ Get the number of rows of output parameter valuesdwRowsNb = tdsObj.NumberOfRows(txtProcedureName.Text)’ For each row, get the value of each output parameterFor dwRowIndex = 0 To dwRowsNb - 1 For dwFieldIndex = 0 To dwFieldsNb - 1 vData = tdsObj.GetData(txtProcedureName.Text, _ dwRowIndex, dwFieldIndex) strData = " " & vData PrintText strData Next dwFieldIndex PrintText vbCrLfNext dwRowIndexExit SubProcedureGetDataErrorHandler:PrintText "*** Cannot GetData " & txtProcedureName.Text & " : " &Err.Number & " (" & Err.Description & ")" & vbCrLfEnd Sub


47 A2 92US Rev01 3-35

’ Procedure called when the user requests information about a’ TPR (Information button)Private Sub cmdProcedureInformation_Click()Dim strInformation As StringOn Error GoTo GetProcedureInfoErrorHandlerstrInformation = tdsObj.GetProcedureInfo(txtProcedureName.Text)PrintText strInformation & vbCrLfExit SubGetProcedureInfoErrorHandler:PrintText "*** Cannot get information on " & txtProcedureName.Text& " : " & Err.Number & " (" & Err.Description & ")" & vbCrLfEnd Sub

’ Procedure called when the user quits the applicationPrivate Sub cmdQuit_Click()’ If connection is still active, close itIf gbConnected = True Then tdsObj.Disconnect Set tdsObj = NothingEnd IfUnload MeEnd Sub

’ Procedure called when a Message event is raised by the’ TDS ObjectPrivate Sub tdsObj_Message(ByVal msgProcedure As String, ByValmsgType As Integer, ByVal msgStatus As Long, ByVal msgText AsString)If msgType = 1 Then PrintText "--- " & msgProcedure & " : " & msgText & _" (status : " & msgStatus & ")" & vbCrLfElse PrintText "*** " & msgProcedure & " : " & msgText & _" (status : " & msgStatus & ")" & vbCrLfEnd IfEnd Sub

’Procedure called when the form is loadedPrivate Sub Form_Load()gbConnected = FalsecmdClose.Enabled = FalsecmdProcedureExecute.Enabled = FalsecmdProcedureInformation.Enabled = FalsecmdProcedureGetData.Enabled = FalseEnd Sub


3-36 47 A2 92US Rev01

3.8 Dialog Descriptions

3.8.1 Invoking ESP 7 TPRs

Procedures that are invoked through the ESP 7 product are called with thecommand name using the Execute Procedure.

The ESP 7 product converts the procedure call into the proper TDS format. Fordetails, see the ESP 7 on GCOS 7 User’s Guide.

3.8.2 Returning Data

ESP 7 TPRs return either data and/or a message (with a status):

• When a message is returned, it is in the form of a message buffer containingASCII data.

• Data is returned through the methods of the ActiveX control layer to theapplication program.


47 A2 92US Rev01 3-37

3.9 File and Data Formats

3.9.1 Data Types

Data exists on both the client and server sides of the network. Input data is sent bythe client to be used to form a TDS command line as input to TPRs and, in turn,output data can be sent back to the client as data rows. In both cases, the data cancontain internal data formats such as binary integers.

There are differences between the two sides, however, that must be addressed. Themost obvious of these is the GCOS 7 word size of 32 bits, byte size of 8 bits, anddecimal data types. The client side has a word size of 32 bits, byte size of 8 bits,and no decimal data types.

TPRs can process a variety of data types including:

• long integers• small integers• double precision floating point numbers• character strings• variable length character strings – varchar (on output only)• packed/unpacked signed/unsigned decimals

The client side, however, has a more limited input data type set containing:

• long integers• short integers• character strings• double precision floating point numbers• DECIMAL-type values

The ESP 7 product automatically converts the fields (see Table 3-2 for full details).

Before data can be sent from the server to the client, it must be described using astructure called an SQL Descriptor Area (SQLDA). An SQLDA is a relational database construct used to describe the data fields being returned as the result of aSELECT statement. Since the client side software is oriented towards SQL, theSQLDA suits the client's needs for returning data as well. The SQLDA must becontained in one message with an ESP 7 header indicating a message of type 3followed by the SQLDA. This complete message must be sent to the gateway withEMI.


3-38 47 A2 92US Rev01

3.9.1.1 Server Data Types

The valid server side data types are listed in the following table. The name, type,length and descriptions are presented.

The TYPE field is the value used in the datatype field of an SQLDA. For all butthe decimal data types, the LENGTH is the number of bytes the data type willoccupy. The LENGTH for the CHAR and VARCHAR types is the maximumnumber of characters. The LENGTH of a VARCHAR includes the two bytes whichgive the length of the message data. For a decimal data type, the four leftmost bitsof the LENGTH field contain the precision (total number of digits) and the fourrightmost bits contain the scale (number of digits after the decimal separator).

TDS TPRs using ESP 7 must be coded to allow for any alignment and padding(space filling) that may occur for input arguments. Output data may need to bealigned and space filled.

VARCHAR is not a standard data type. Therefore, any TPR that makes use of thisas an output data type must handle this special case.


47 A2 92US Rev01 3-39

Table 3-1. Server Data Types

Name Data Type Length Description

Integer 0 4 32-bit two’s-complement binary, e.g.COBOL COMP-2C int

Character 3 Len EBCDIC characters, fixed length, e.g.COBOL PIC X(n)C char[n]

Smallint 4 2 16-bit two’scomplement binary, e.g.COBOL COMP-1C short

Float double 6 8 Double precision binary floating point,e.g.COBOL COMP-10C double

UNPACKED 11 Combination ofprecision and

scale

Unpacked, signed decimal e.g.

COBOL PIC S9V99

UUNPACKED 12 Combination ofprecision and

scale

Unpacked, unsigned decimal e.g.

COBOL PIC 9V99

Varchar 13 Len Two part data type:1. 16 bit binary count of the number ofbytes to follow2. Character data

PACKED 14 Combination ofprecision and

scale

Packed, signed decimal e.g.

COBOL PIC S9V99 USAGE COMP

UPACKED 15 Combination ofprecision and

scale

Packed, unsigned decimal e.g.

COBOL PIC 9V99 USAGE COMP


3-40 47 A2 92US Rev01

3.9.1.2 Conversion

Table 3-2. Automatic Data Conversions

Server Data Type Client Data Type

COMP-2 integer (32 bit)<big-endian>

Integer (32 bit) <little-endian>

COMP-1 small integer (16 bit)<big-endian>

Short integer (16 bit) <little-endian>

COMP-10floating double precision<big-endian and IBM format>

Double precision<little-endian and IEEE format>

Character (8 bit) <EBCDIC byte> Character (8 bit) <char ASCII byte>

Varchar <EBCDIC byte> String (one byte per char)

Any decimal-type data DECIMAL

Big-endian byte 0 is the high order (left-most) byte.Little-endian byte 0 is the low order (right-most) byte.

47 A2 92US Rev01 4-1

4. Configuration of ESP 7

4.1 Configuring TCP/IP

• If the TCP/IP host name of the DPS 7000 XTA server exceeds 8 characters, analias must be declared in the “hosts” file of the PC (where ESP7NGEN productis installed).This file is located under the Systemroot\System (for Windows 9x) orSystemroot\System32\Drivers\Etc (for Windows NT/2000) and can becreated/modified using any text editor such as Notepad.Example: the TCP/IP host name of the DPS 7000 XTA is “frcls0506” (9characters), with IP address: 129.182.197.47. An alias of less than 8 charactersmust be created, such as “DPS7” by adding this line to the “hosts” file:129.182.197.47 frcls0506 DPS7

• With the ESP administration tool ESPADMPC, you may use symbolic namesinstead of port numbers for communication with the OPEN 7 Gateway. In orderto do this, an entry of the following type should be included in the services filein the windows directory:

<symbolic name> <port number>/tcp

where <symbolic name> is your chosen name and <port number> gives the portnumber to be used for communication with the OPEN 7 Gateway, for example:

ESP 7 9002/tcp

The use of symbolic names comes into effect when using the transfer facilities ofESPADMPC. Note that if a symbolic name is used which has not been registeredin the services file of your windows directory, the port number 9002 is used bydefault.

(If actual port numbers are used and an incorrect port number is supplied, aconnection error will result.)

Note that connections to a TDS mailbox are possible even without updating theservices file.


4-2 47 A2 92US Rev01

4.2 Configuring the Initialization File

The following fields should be entered using the MkgIni utility (see the followingdiagram):

Section: [ESPNGEN]

Path entry: II_SYSTEM= C:\ESP7NGENIndicates where the Espadmpc.exe utility is situated.This is also where the local procedure declaration fileis found.

Path entry: CRYPT= YES (default): Encrypted passwordNO: non-encrypted password

Path entry: TBLFILE= Indicates the name of the translation table that will beused in all following connections (see below).

Path entry: TIMEOUT1= timeout applied for connections (in seconds),default is 20 seconds

Path entry: TIMEOUT2= timeout applied for data recuperation (in seconds),default is 600 seconds

Path entry: VERSION= Reserved (DO NOT MODIFY)

Configuration of ESP 7

47 A2 92US Rev01 4-3

Note on TBLFILE field : If not empty, this field gives the name of the translationtable file that will be used in all following connections. If the full path is not given,it is assumed to be the esp7ngen installation directory. If the file type is not given,then «.tbx» is used. An example file, named d011.tbx, is available in the esp7ngeninstallation directory and should fit the character set of Western Europeancountries : the tables contained in this file perform translation between Windows(codepage 1252) and GCOS 7 (PLW) Western European character sets. It alsohandles translation of the euro character. Handling the euro character is not simple,as its representation is different in Windows and GCOS 7 systems :

• In Windows 95 / Windows NT 4.0 with euro patch (in some fonts and someapplications), or in Windows 98 / Windows 2000, the euro is a new characterwhich is at position ‘0x80 ‘ in all but cyrillic code pages (‘0x88’ in 1251 cyrilliccode page).

• In GCOS 7 V9 TA (TS 9662), the euro sign replaces the general currency signcharacter (‘¤’) with ‘0x9F’ code (in BULL D111 EBCDIC). This means there isno corresponding code in a GCOS7 character set for the general currency sign(‘0xA4’ ASCII code). One solution is to use ‘0x20’, as it was the correspondingEBCDIC code of ASCII code ‘0x80’ before the euro implementation. Thistranslation rule is applied in the d011.tbx translation sample file.


4-4 47 A2 92US Rev01

4.3 Configuring Connection Parameters

1. Click on the DSNCnfg icon.

NOTE:This tool is used by other products as well as ESP 7.

2. Choose Product type ESP7NGEN.

3. Create a new virtual node (connection parameters identifier).


47 A2 92US Rev01 4-5

4. Enter the parameters.

User name name used for the TDS connection.

Password Password used for the TDS connection.

Host name name of the Open 7.

Port num Port used by the Open 7 gateway.

GCOS GCOS name.

Mail box Name of the Mailbox where the TDS is connected.

Project name (optional) requested by your GCOS administrator.

Billing name (optional) requested by your GCOS administrator.


4-6 47 A2 92US Rev01

Terminal ID the PC name used at connection time

Trace YES (tracing) or NO (no tracing).The trace file name used by the NT7 gateway situatedon DPS 7000 XTA server (see section 4.4, DebuggingFacilities)

Other (reserved for specific application needs).

For ESP 7, 2 options are possible:

-c Open7 to specify the NT7 Gateway proceduredeclaration file (if omitted, the PC file is used)

-r <TDS prompt> to replace READY (see below)

5. Validate this grid (return to the previous grid).

6. Validate the virtual node grid (this second validate records of all modificationswhile cancel does not record modifications).

Note that the use of DSNCNFG is necessary only when “node = …” is supplied inthe Host field of the Connect method.

The –r option of the Other field is useful when a prompt other than the default(READY) is used by the TDS application. In all cases at connection time, the NT7Gateway passes the first 70 characters of the message(s) received from TDS toESP7NGEN. If the message(s) are less than 70 characters long, the NT7 Gatewaypads with binary zeroes. Thus ESP7NGEN always receives 70 characters inresponse to a connection request. If these 70 characters contain the specified TDSprompt (not necessarily at the start of the message(s)), then ESP7NGEN considersthat the connection is valid. Otherwise, ESP7NGEN considers that the connectionis invalid and returns an error to the client application program. Note that the clientapplication does not receive the 70 characters returned via TDS/NT7 Gateway.


47 A2 92US Rev01 4-7

4.4 Debugging Facilities

A trace file may be obtained on the DPS 7000 XTA server. Dynamic trace files arerequested at connection time using the trace parameter of ESP_connect. The tracefile is filled until disconnect time (ESP_disconnect). The trace file is found in thedirectory:

<NT7GW install dir>\NTGW_<server identifier>\<TermId> where:

• <NT7GW install dir> is the directory where NT7GW has been installed

• <server identifier> is the identifier of the running NT7GW server

• <TermId> is the Terminal ID parameter value (see §4.2 Configuring theInitialization File) if it is not empty, or the TCP/IP host name of the client PC ifit can be computed, or the TCP/IP address of the client PC

Note that this trace file is created only if NT7 Gateway is running with trace levelset to three or greater. For further information about running the NT7 Gateway andsetting trace level trace, see the Interop7 User’s Guide (ref. 47A291US)

In the event of any anomaly when using ESP 7, it is important to supply the contentof the trace file for analysis.

4.5 Security

4.5.1 Password Encryption

The password is encrypted in the ESP 7 gateway and decrypted in the NT7gateway on the GCOS 7 side.


4-8 47 A2 92US Rev01

❑

47 A2 92US Rev01 5-1

5. Configurability

5.1 ESP 7 Connections

A connection is defined by the following parameters:

• GCOS7 user name,• GCOS7 password,• TDS mailbox,• GCOS7 project,• GCOS7 billing,• terminal identifier.

Different applications can share the same connection at the same time to executetransactions.

The maximum number of simultaneous connections for an application on a givenPC is 10 for the two-tier version and 500 for the three-tier version, whetherconnected to one or more DPS 7000 systems.

5.2 ESP 7 Procedures

The maximum number of procedures registered for each host is 500.

The maximum number of parameters for each procedure (input + output) is 127.

The maximum length of a procedure name is 8.

The maximum length of a parameter name is 10.


5-2 47 A2 92US Rev01

❑

47 A2 92US Rev01 6-1

6. Administration Tool for ESP 7

6.1 Overview

All ESP 7 procedures that are triggered from a PC must first be registered in aprocedure declaration file. This file may be:

<hostname>.pr1: situated locally on the client PC (default configuration option).

<NT7GW inst dir>/espconf1.pr1: situated on the Diane server.

Note that the choice of where the procedure declaration file is situated should bemade only once for a given site (see Configuring Connection Parameters inChapter 4). Once the location is chosen, it should not be changed.

When a local procedure declaration file is chosen (more effective than a remotefile), no attempt is made by ESP 7 to search for a procedure declaration in theremote file if the declaration is not found in the local file.

ESPADMPC is the tool for managing the declarative procedures from the PC.

When a remote procedure is executed, a request for the procedure’s parameters issent to the ESP 7 gateway.

This gateway looks for the procedure name in the procedure declaration file.

• If the procedure is found, the gateway returns the parameters to the caller.

• Otherwise an error is signaled.

ESP 7 (NGEN) on TCP/IP for DPS 7000/XTA

6-2 47 A2 92US Rev01

Figure 6-1 shows the position of the administration tool in the ESP 7 architecture.

Local SiteFile

<hostname>.pr1ESPADMPCAdministration Tool

TDS Object

Application PC

TDSTransactions

NT7 Gateway

Host SiteFile

espconf1.pr1

Diane Server

VCAM

Figure 6-1. The Administration Tool in ESP 7 Architecture

Administration Tool for ESP 7

47 A2 92US Rev01 6-3

6.2 The Administration Tool (Espadmpc)

To run the Procedure Administration tool, On the Start menu, point to Programs,then to ESP7NGEN, and then click “Procedure definition (espadmpc)”.

The next figure shows a sample view of Espadmpc when an existing proceduredefinition file (“bc06-41” in this case) is opened:

To manage a procedure definition file, Espadmpc provides the following views andtools:

• (Left pane) A tree view of the procedures and the names of their parameters(input and output).

• (Right pane) A form view which displays and enables to change the definition ofthe parameters of a selected procedure.

• Main toolbar.

• Menu commands.


6-4 47 A2 92US Rev01

6.2.1 The Procedure Tree View

The procedure tree view lists all the procedures of the current procedure definitionfile. In this view, it is possible to create/delete/rename a procedure or parameter, aswell as creating a source file containing the COBOL structure declarations ofmessages exchanged between ESP7NGEN and an executed procedure.

The following table shows the actions needed to perform these operations:

Operation Action

Define a new procedure Select (left-click on) the root node (named“Procedures”), and then select the “Insert”command in the “Edit” menu.A new procedure will have the “PROCxxx”name by default (xxx being the first numberthat gives an unused procedure name).

Define a new parameter of a procedure Select the “Input Parameter” or “Outputparameter” node under the given Procedurenode, and then select the “Insert” commandin the “Edit” menu.

Rename a procedure or parameter Select the procedure or parameter namenode, and then select the “Rename”command in the “Edit” menu.

Display the definition of one (or all input, or alloutput) parameter(s) of a procedure in the rightpane

Select the parameter (or the “InputParameters” or “Output Parameters” node forall parameters).

Copy/cut/delete a procedure or parameter (alongwith its definition) to the Clipboard

Select the procedure or parameter namenode, and then select the “Cut”, “Copy” or“Delete” command in the “Edit” menu.(NOTE: the “Cut” operation is not availablefor procedures).


47 A2 92US Rev01 6-5

Operation Action

Paste a procedure Select the root node (named “Procedures”),and then select the “Paste” command in the“Edit” menu.NOTE: The pasted procedure will have thename of the copied procedure followed by anumeric suffix, as it is not possible to haveduplicate procedure names.

Paste a parameter Select the “Input Parameter” or “Outputparameter” node under the given targetProcedure node, and then select the “Paste”command in the “Edit” menu.

Send a procedure definition to the gateway toupdate the OPEN7 procedure definition file(available only when a connection has beenestablished – see “Connect” command ofTransfer menu).

Select the procedure node, and then select the“Send” command in the “Transfer” menu.

Create COBOL source file from proceduredefinition

Select the procedure node, and then select the“Make source” command in the “Edit” menu.

Most of these operations can also be performed by right-clicking on the node, andthen selecting the appropriate command from the context menu that appears. Forexample, to rename a procedure, right-click on it and then click “Rename” in thecontext menu.

6.2.2 The Parameter Form View

The parameter form view displays and enables to modify a parameter definition (itstype, size, …).

To modify a parameter definition, click on the grid row that displays its name anddescription, then use the other graphic elements (text fields, checkboxes, …) tochange its characteristics.

6.2.3 The main toolbar

The toolbar buttons can be used instead of selecting commands in menus. Forexample, clicking on the “New” button has the same effect than selecting the“New” command from the File menu.


6-6 47 A2 92US Rev01

6.2.4 The menus

The following menus are available:

File Manages local procedure files

Transfer Manages the procedure registered in the host site file.

Edit Manages the procedure and parameter nodes in theProcedure tree view.

View Hides/displays the main toolbar/status bar

Help Gives product information

6.2.4.1 Menus commands

File New Creates a new procedure definitiondocument

Open Opens an existing procedure definitionfile

Save Saves the active procedure definitiondocument

Save as… Saves the active procedure definitiondocument with a new name

Exit Quits the application

Transfer Connect To connect to the specified host.The first dialog box that appears will askfor the DPS 7000 XTA tcp/ip host name(or alias) and the port number of theGateway.Authentication will be performed on thebasis of current (interactive) Windowsuser name and domain: current user mustbe a member of “V7000Operators” groupof the DPS 7000 XTA system to beauthenticated.

Disconnect To disconnect from the previouslyconnected host

Get Procedure(s)… Transfers one specified procedure (or allprocedures) definition from the host

Send Procedure… Transfers (and possibly overwrites) thespecified procedure definition to the host

Delete Procedure… Deletes the specified procedure definitionon the host


47 A2 92US Rev01 6-7

Edit Cut Cuts the selected parameter definition inthe procedure view and sends it to theClipboard

Copy Copies the selected parameter orprocedure definition in the procedureview and sends it to the Clipboard

Paste Inserts a procedure (or parameter)definition from the Clipboard under the“Procedures” (or “Input parameter” or”Output parameter”) node in theprocedure view

Delete Deletes a procedure or parameterdefinition in the procedure view

Insert Inserts a new procedure or parameterdefinition in the procedure tree view

Rename Renames a procedure or parameter in thetree view

View Toolbar Shows/hides the main toolbarStatus bar Shows/hides the status bar

Help About Espadmpc… Displays program information, programnumber and copyright


6-8 47 A2 92US Rev01

❑

47 A2 92US Rev01 A-1

A. Migration Advice

This section is intended to provide help in migrating from previous versions ofESP7 (based on ODBC) to ESP7NGEN (based on Automation).

While no programming changes are required to the TDS transactions to beexecuted on GCOS7, it is difficult to describe the modifications of the PC clientapplication, as the code could have been written using various developmentenvironments (Visual Basic, PowerBuilder, ..). And even with one environment,e.g. Visual Basic, there are many ways to execute a transaction through the ODBClayer : with various object-oriented interfaces (DAO, RDO, ADO) or with theODBC API. However, whatever the environment used, the best way to upgrade theapplication code is to identify the code sequences which perform the logical stepsof the transaction execution processing, then rewrite these sequences using theESP7 control methods and event.

Here are the logical steps of the transaction execution processing :

• Connection to the databaseInput data : DSN name (ODBC version), node name (Automation version)Output data : none

• Execution of the transactionInput data : name of the TPR and values of its input parametersOutput data : result tuples (rows of output parameter values)

• Retrieve each output parameter value from each tupleInput data : result tuples from previous stepOutput data : all output parameter values

• Error handlingAn error code and a description text are available to the client application if anerror occurs in one of the previous steps. Retrieving these values depends on thedevelopment tool. For example :

− In Visual Basic (using either ODBC or Automation version), error detection isperformed by the On Error statement. The Number and Description propertiesof the Err object may then be accessed in an error-handling routine.


A-2 47 A2 92US Rev01

− In PowerBuilder, error handling depends on the ESP7 version :

. In the ODBC version, error detection is performed by checking theSQLCode property of the current Transaction object (which by default isSQLCA) after calling an SQL command : It is set to –1 if an error hasoccurred. The SQLDBCode and SQLErrText properties of this object thengive information about the error.

. In the Automation version, error detection is performed using theExternalException event. In this event, the error code can be retrieved fromthe low word of the resultcode argument (using the IntLow() function). Thetext description is contained in the description argument.

• Handling TPR type-1 and type-2 messagesThe detection of information (type-1) or error (type-2) message sent by the TPRvaries for the two versions of ESP7:

− In the ODBC version, receiving any of these messages leads to an error. Theerror code is 3146 in Visual Basic (in Err.Number), and 41300 inPowerBuilder (in SQLDBCode property of the transaction object).

− In the Automation version, only a type-2 message leads to an error (the errorcode is identified by the error constant esp7AbortedProcedure). The Messageevent of the ActiveX control is triggered in the client application when a type-1 or type-2 message is received.

Both TPR messages contain a status code and a text describing the TPRexecution. These values are not retrieved the same way in the two versions ofESP7:

− In the ODBC version, they are both contained at the end of the errordescription string (Err.Description in Visual Basic, SQLErrText property ofthe transaction object in PowerBuilder). The length of the message text mustnot exceed 60 characters, else the status code will not be included in the errordescription string.

− In the Automation version, they are contained in the msgStatus and msgTextarguments of the Message event.

Another change between the old and new versions of ESP7 is how to distinguisha type-1 from a type-2 message :

− In the ODBC version, the only way to distinguish them is through the value ofthe TPR status code (e.g. positive or negative).

− In the Automation version, the msgType argument of the Message event isinitialized to the message type number (i.e. 1 for information message, 2 forerror message).

• Disconnection from the databaseInput data : noneOutput data : none

Migration Advice

47 A2 92US Rev01 A-3

The following table contains a sample of code migration for each previous steps.The original application uses RDO access method to execute transactions.

ODBC AutomationPrivate moConnection As New rdoConnectionmoConnection.CursorDriver = rdUseOdbcmoConnection.Connect = "DSN=" +moAppSecurity.Databases("TCISTDS").NamemoConnection.EstablishConnectionWhile moConnection.StillConnectingDoEventsWend

Dim strHost as String‘ we suppose that a node with the same name that the ODBC DSN‘ has been defined, using the dsncnfg utilitystrHost = "node=" + rmoAppSecurity.Databases("TCISTDS").NameespCtl.Connect(strHost,9002, "","","","","","","",False)

Dim oResultSet As rdoResultset'oConnection is a reference to moConnection of the' previous example.Set oResultSet = oConnection.OpenResultset(asProcedure, rdOpenStatic,

rdConcurReadOnly, rdExecDirect)While oConnection.StillExecutingDoEventsWend

Dim strInfo as StringstrInfo = espCtl.GetProcedureInfo(asProcedureName)espCtl.ExecuteProcedure(asProcedureName, asProcedureParameters)

' once the result set has been retrieved, as in the above example,‘ code like the following two lines is used for the application to‘ access this data.aoConnection.SQLCode = oResultSet(0)aoConnection.SQLMessage = oResultSet(1)

aoConnection.SQLCode = espCtl.GetData(asProcedureName,0,0)aoConnection.SQLMessage = espCtl.GetData(asProcedureName,0,1)

On Error GoTo ErrorHandler….ErrorHandler :Select Case Err.Number Case 3146 ‘Type-1 or Type-2 message received ‘ Extract status from Err.Description : ‘ If type-1, print info message and resume execution ‘ If type-2, print error message and abort execution Case Else ‘ Handle other situations here…End Select

Private Sub espCtl_Message(ByVal msgProcedure As String, ByVal msgType As Integer, ByVal msgStatus As Long, ByVal msgText As String)If msgType = 1 Then ‘ print info messageElse ‘ print error messageEnd IfEnd Sub….On Error GoTo ErrorHandler….ErrorHandler :Select Case Err.Number Case espAbortedProcedure ‘Type-2 message received ‘ abort execution Case Else ‘ Handle other situations here…End Select

moConnection.Close espCtl.Disconnect

We now use an application program extract written in VisualBasic to illustrate thesteps required for migration. Note that this application uses the DATA controlfeatures of VisualBasic. As such, it illustrates ONE typical programmingmethod, but is in NO way intended to be the ONLY programming methodpossible.

Manipulation of databases can be effected without DATA controls, using themethods and properties associated with the database.


A-4 47 A2 92US Rev01

A.1 ESP 7 (ODBC) + DATA Control

Connection Sequence

‘### formname is the form that contains the DATA control named dcESP

..........

formname!dcESP.Connect = "ODBC;DSN=mydsn"

formname!dcESP.Options = DB_SQLPASSTHROUGH

formname!dcESP.Refresh

..........

Execution of a Procedure (TPR)

..........

dim scall as string

scall = "{call STYLEADD ( " param1, param2,...)} "

formname!dcESP.RecordSource = scall

formname!dcESP.Options = DB_SQLPASSTHROUGH

formname!dcESP.Refresh

..........

Handling of Output Tuples

..........

Do While Not formname!dcESP.Recordset.EOF

For i = 0 To NumberOfField-1 ‘here NumberOfField is

supposed to be known)

‘ below lst_tuple is a LISTBOX control

lst_tuple.AddItem "field_" & i + 1 & " = " &

formname!dcESP.Recordset.Fields(i).value

Next i

Me.Refresh

formname!dcESP.Recordset.MoveNext

Loop

..........

Migration Advice

47 A2 92US Rev01 A-5

A.2 ESP 7 (NGEN) - Automation

Connection Sequence

‘formname is the form that contains the ESP7 ActiveX control named ESP

..........

host = "NODE=mynode"

‘below all variables used must be declared but need not be set, except host

if NODE= is used

ESP.Connect host, port, system, tds, user, password, project, billing,

termid, trace

..........

Execution of a Procedure (TPR)

The following methods are available to execute a procedure (TPR) and obtain theoutput tuples in ESP 7 (NGEN):

procinfo=ESP.GetProcedureInfo(procname)

ESP.ExecuteProcedure procname, paramlist

ESP.NumberOfRows(procname)

ESP.NumberOfFields(procname)

And possibly:

ESP.GetFieldInfo procname, (i - 1), pname, ptype, plng

See the example of a typical sequence of methods in the function ‘execute_TPR’listed below.


A-6 47 A2 92US Rev01

Handling of Output Tuples

if number_of_lines > 0 then

For ilines = 1 To number_of_lines

For ifields = 0 To number_of_fields - 1

data=formname!ESP.GetData(procedure_name, (ilines - 1), ifields)

‘ #### for example display the output tuples in the list box

lst_tuple.AddItem "field_" & ifields + 1 & " = " & data

.............. any other treatment

Next ifields

Next ilines

End If

Migration Advice

47 A2 92US Rev01 A-7

A.3 execute_TPR: Example of Subroutine for ESP 7 (NGEN)

############################################################################

#############

Below we list the function execute_TPR (where we provide the sequence of

methods

to be executed)

############################################################################

#############

Public Function execute_TPR(index_ESP, procname As String, procinfo As

String, _

paramlist As String, with_row As Boolean, nbr_of_Field As Long, nbr_of_Row

As Long) As Long

Dim rc As Long

Dim method As String

Dim pname, ptype, plng As Variant

Dim i As Long

nbr_of_Row = 0

nbr_of_Field = 0

execute_TPR = 0

On Error GoTo procedureInfo_error

procinfo=formname.ESP.GetProcedureInfo(procname)

On Error GoTo executeprocedure_error

formname!ESP.ExecuteProcedure procname, paramlist

’#### test whether the TPR should return tuples or not (must be known by the

caller)

If with_row = False Then

Exit Function

End If

’##### request the number of rows and the number of fields

On Error GoTo numberrows_error

nbr_of_Row = formname!ESP.NumberOfRows(procname)

If nbr_of_Row = 0 Then

MsgBox "Warning : number of lines = 0, numberOfRows rc=0"

Exit Function ’ verify whether possible or whether a logic error

End If

On Error GoTo numberfields_error

nbr_of_Field = formname!ESP.NumberOfFields(procname)

If nbr_of_Field = 0 Then

MsgBox "Impossible branch, nbr fields=0 et nbr lines <> 0"

Exit Function ’ impossible if nbr_lines greater than zero

End If

’##### request information on each field


A-8 47 A2 92US Rev01

If formname.mnuShowFields.Checked = True Then

‘if mnushowfields is ticked, we display all the fields in the form

frmlistfield

On Error GoTo GetFieldInfo_error

frmlistfield.Show

frmlistfield.Caption = "list of fields returned by the function " &

procname

frmlistfield.lst_fields.Clear

frmlistfield.lbl_nbrfields.Caption = "the function " & procname & "

is composed of " _

& nbr_of_Field & " fieldss"

For i = 1 To nbr_of_Field

formname!ESP.GetFieldInfo procname, (i - 1), pname, ptype, plng

frmlistfield.lst_fields.AddItem "field_" & i & " name= " & pname &

_

", type= " & ptype & ", length= " & plng

Next i

End If

Exit Function

' ##### error handling ######

procedureInfo_error:

method = "getProcedureInfo"

GoTo all_error

executeprocedure_error:

method = "ExecuteProcedure"

GoTo all_error

numberfields_error:

method = "NumberOfFields"

GoTo all_error

numberrows_error:

method = "NumberOfRows"

GoTo all_error

GetFieldInfo_error:

method = "GetFieldInfo"

all_error:

save_Error = Error$

save_errnumber = Err.Number

execute_TPR = Err.Number

‘ ##### below we call a subroutine processerror which can centralize

actions and processing

‘##### in the event of an error

‘##### ie : display message box with error code saved in public

variables “ save_Error ”

‘##### and “ save_errnumber ”, “ method ”, WRITE a log of this error in

file etc.

processerror (procname & ".." & method)

End Function

Migration Advice

47 A2 92US Rev01 A-9

A.4 Example for ESP 7 (NGEN)

‘###########################################################################

###

'##### Use of the function to correctly sequence the methods:

'##### Executeproc, NumberOfRows, NumberOfFields

‘###########################################################################

####

............

............

............ code to declare and initialize variables used below

............

‘ from here, all the variables are supposed to be declared and (if

necessary) initialized

dim with_row as boolean

with_row= true

rc = execute_TPR(0, procedure_name, procinfo, parameter_list, with_row,

_

number_of_fields, number_of_lines)

If rc <> 0 Then

GoTo finish ' the error number and description are already displayed by

execute_TPR

End If

'##### extraction of each line, and associated treatment, e.g., add tuple to

listbox lst_tuple

On Error GoTo getData_Error

For ilines = 1 To number_of_lines

For ifields = 0 To number_of_fields - 1

data=formname!ESP.GetData(procedure_name, (ilines - 1), ifields)

lst_tuple.AddItem "field_" & ifields + 1 & " = " & data

‘##### writefile (below) is a subroutine to log each line received into a

file

writefile ("field_" & ifields + 1 & " = " & data)

Next ifields

Next ilines

finish:

Me.Refresh

Exit Sub

' ##### error handling ######

getData_Error:

Me.MousePointer = DEFAULT

save_Error = Error$

save_errnumber = Err.Number

processerror (procedure_name & "GetData")

End Sub


A-10 47 A2 92US Rev01

❑

47 A2 92US Rev01 B-1

B. Translation Table Utility

The tblpcgc utility (activated using the icon Tbl PC Gc) allows the user to createand/or modify the set of translation tables to be used by the ESP7NGEN productfor the conversion of characters:

1. From ASCII to EBCDIC (from PC to GCOS 7).

2. From EBCDIC to ASCII (from GCOS 7 to PC).

B.1 PC to GCOS 7 Translation Table

Some translation tables are already provided with the utility (File menu):

1. Tables for ASCII <-> EBCDIC conversion (7 bit): (sub-menu « Default »).

2. Tables for extended ASCII <-> EBCDIC conversion (sub-menu « D-011 »).


B-2 47 A2 92US Rev01

In addition, it is possible to entirely create your own conversion tables (File menuusing the sub-menu « New »).

A Tables menu is provided to allow us to display the existing tables and modifythem.

B.2 Existing Tables

B.2.1 Displaying

• PC to GCOS 7 (sub-menu « View PC table »)

• GCOS 7 to PC (sub-menu « View GCOS table »).

B.2.2 Modifying

• PC to GCOS 7 (sub-menu « Modify PC table »)

• GCOS 7 to PC (sub-menu « Modify GCOS table »).

The following procedure is required for translation table modification:

1. Select the table PC to GCOS

2. Select the index

3. Indicate the value for the selected index

4. Click on the « Set Value » button

5. At the end of all the modifications, click on « OK » to validate the table

6. Select the table GCOS to PC

7. Repeat operations 2 to 5 for this table

8. Save the entire set of modifications (File menu, option « Save » or » Save as »)

Note that the name of the file to be saved should have the suffix .tbx.

The tables are taken into account by ESP 7 (NGEN) via the DSNCNFG utility(specification of –f <filename> in the field « other » or « divers »).

47 A2 92US Rev01 g-1

Glossary

A

ActiveXActiveX is a set of technologies that uses the Component Object Model (COM) to enable softwarecomponents to interact with one another in a networked environment, regardless of the language inwhich they were created. ActiveX technologies can be used to create applications to run on thedesktop or the Internet.

ActiveX componentPhysical file that contains classes, which are definitions of (ActiveX) objects provided by thecomponent. For example, a .dll (ActiveX dll), .exe (ActiveX server) or .ocx (ActiveX control) file.

ActiveX controlAn ActiveX control is implemented as an in-process server (typically a small object) that can beused in any OLE container. Note that the full functionality of an ActiveX control is available onlywhen used within an OLE container designed to be aware of ActiveX controls. This container type,hereafter called a "control container," can operate an ActiveX control by using the control’sproperties and methods, and receives notifications from the ActiveX control in the form of events.The following figure demonstrates this interaction.Interaction between an ActiveX Control Container (client application) and a Windowed ActiveXControl:----------------- Get/Set properties, call methods -----------------| OLE control | ---------------------------------> | OLE control || container | <-------------------------------- ---------------------------------- Fire Events

AutomationA way to manipulate an application’s objects from outside the application. Automation is typicallyused to create applications that expose objects to programming tools and macro languages, createand manipulate one application’s objects from another applications, or to create tools for accessingand manipulating objects.


g-2 47 A2 92US Rev01

C

COMThe Component Object Model (COM) is a binary standard that defines how objects are created anddestroyed and, most importantly, how they interact with each other. As long as applications followthe COM standard, different applications from different sources can communicate with each otheracross process boundaries. People use COM to make communication with other applications easy.

D

DSNData Source Name, the name of the configuration file used for stocking connection information andhandled using the dsncnfg utility.

E

ESP 7Enterprise Server Procedures for GCOS 7, a middleware that enables the use of open, highproductivity RAD tools for building PC-based "client" applications using the benefits of aDPS 7000 as a TP/DB server

EventsActiveX controls use events to notify a container that something has happened to the control.Common examples of events include clicks on the control, data entered using the keyboard, andchanges in the control’s state. When these actions occur, the control fires an event to alert thecontainer.

G

GatewayA communication mechanism between different environments. Usually involves conversion of datastream entities from the form acceptable by one environment to the form accepted by a differentenvironment, as well as other operations.

GCOS 7General Comprehensive Operating System 7.

GUIGraphic User Interface. Term generally applied to windowing systems on PCs, Macs, and UNIXworkstations.

Glossary

47 A2 92US Rev01 g-3

I

IDS/IIAn interactive hierarchical data base system for the GCOS 7 operating system.

ISI 7Interoperability Software Installation on GCOS 7.

M

MethodsAn ActiveX control fires events to communicate with its control container. The container, in return,uses methods and properties to communicate with the control. Methods and properties are similarin use and purpose, respectively, to member functions and member variables of a C++ class.

P

PCPersonal Computer.Micro computers running DOS, and Microsoft Windows.

PowerBuilderThis is a Windows-based client application development environment. In an ESP 7 context, it is aRAD tool.

PropertiesProperties are data members of the ActiveX control that are exposed to any container. Propertiesprovide an interface for applications that contain ActiveX controls, such as Automation clients andActiveX control containers.

R

RPCRemote Procedure Call. This enables applications running on one system to call functions/services(procedures) executing on another system.

S

SQLStructured Query Language. The standard data base language for querying relational databases.

SQLDAStructured Query Language Descriptor Area. A structure that is used to describe data that is passedbetween a relational database and an application that references data in a database, and visa versa.This type of structure can also be used to describe data that is passed between any types ofprogram.


g-4 47 A2 92US Rev01

Stored ProcedureA stored procedure, in this document, is a TDS transaction that resides on a GCOS 7 system. Storedprocedures are referenced from the user application programs that are developed on PCs with4GLs, Visual Basic, or C programs that emulate an SQL Execute Procedure.

T

TCP/IPA suite of protocols for communication in interconnected LAN and WAN networks known asInternet.

TDS TransactionA TDS application may be comprised of one or more than TPR programs. A TPR may referenceother TPRs. When one or more TPRs are used in the running of a TDS application, they form aTDS transaction.

TPRTransaction Processing Routine. A GCOS 7 TDS application program. A TDS transaction consistsof executing one or more TPRs.

U

UFASUnified File Access System. Native classical file system on Bull DPS 7000 (GCOS 7).

Visual BasicThis is a client application development tool which can be used to facelift existing applications.In an ESP 7 context, it is a RAD tool.

V

VCAMVirtual Communications Access Method. This is the GCOS 7 session layer communicationsmodule.

X

XCP2Extended Communication Protocol Level 2. This enables transactional applications running underTDS on GCOS 7 to communicate with applications on other systems (which also run the XCP2protocol). XCP2 is often referred to as CPI-C/XCP2.

47 A2 92US Rev01 i-1

Index

A

data types 3-40automation A-5

C

connection parameters 4-4Initialization File 4-2

connection parametersconfiguring 4-4

connection sequence A-4, A-5

D

DATA control A-4Data Source Name g-2debugging facilities 4-7DSN

definition g-2

E

Enterprise Server Procedures 7description 1-3

ESP 7administration tool 6-1as transactional Client/Server 3-2automation A-5constraints 5-1definition g-2functional description 3-2ODBC A-4

procedures 5-1user interface 3-26

ESP 7 TPRsinvoking 3-36

ESP 7/DA 7 PC gateway 3-9ESPADMPC

tool 6-1execute_TPR subroutine A-7execution

TPR A-4, A-5, A-7

F

functional description 3-2

G

gatewaydefinition g-2

GCOS 7definition g-2

GUIdefinition g-2

H

hardwarerequirements 1-2


i-2 47 A2 92US Rev01

I

IDS/IIdefinition g-3

Initialization Fileconfiguring 4-2

installationpre-conditions 2-1procedure 2-5program 2-2

ISI 7definition g-3

O

ODBCDATA control A-4

data types 3-38output tuples

handling A-4, A-6

P

passwordencryption 4-7

PowerBuilderdefinition g-3

pre-conditionsinstallation 2-1

proceduresESP 7 5-1installation 2-5

R

RAD tools 1-3requirements

hardware 1-2software 1-2

RPCdefinition g-3

S

security 4-7sequence

connection A-4, A-5site files

overview 6-1software

requirements 1-2SQL

definition g-3SQLDA

definition g-3stored procedure

definition g-4

T

tablestranslation B-1

tblcgc utility B-1definition g-4

TDS application development 3-3TDS transaction

definition g-4tools

ESPADMPC 6-1TPR

definition g-4execution A-4, A-5, A-7

trace files 4-7translation tables B-1tuples

output A-4, A-6

U

UFASdefinition g-4

utilitiestblcgc B-1

Index

47 A2 92US Rev01 i-3

V

VCAMdefinition g-4

Visual Basicdefinition g-4processing stored procedures 3-31

X

XCP2definition g-4


i-4 47 A2 92US Rev01

Technical publication remarks form

Title : DPS7000/XTA NOVASCALE 7000 ESP 7 (NGEN)on TCP/IP for DPS 7000/XTA Distributed Computing

Reference Nº : 47 A2 92US 01 Date: December 2000

ERRORS IN PUBLICATION

SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION

Your comments will be promptly investigated by qualified technical personnel and action will be taken as required.If you require a written reply, please include your complete mailing address below.

NAME : Date :

COMPANY :

ADDRESS :

Please give this technical publication remarks form to your BULL representative or mail to:

Bull - Documentation Dept.

1 Rue de ProvenceBP 20838432 ECHIROLLES [email protected]

Technical publications ordering form

To order additional publications, please fill in a copy of this form and send it via mail to:

BULL CEDOC357 AVENUE PATTONB.P.2084549008 ANGERS CEDEX 01FRANCE

Phone: +33 (0) 2 41 73 72 66FAX: +33 (0) 2 41 73 70 66E-Mail: [email protected]

CEDOC Reference # Designation Qty

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

[ _ _ ] : The latest revision will be provided if no revision number is given.

NAME: Date:

COMPANY:

ADDRESS:

PHONE: FAX:

E-MAIL:

For Bull Subsidiaries:

Identification:

For Bull Affiliated Customers:

Customer Code:

For Bull Internal Customers:

Budgetary Section:

For Others: Please ask your Bull representative.

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

47 A2 92US 01REFERENCE

Documents

ESP 7 (NGEN) on TCP/IPsupport.bull.com/ols/product/system/gcos7/gcos7-com/g7...ESP7 (NGEN) for Diane 2-2 47 A2 92US Rev01 2.2 The Installation Program After executing the installation