ESP 7 (NGEN) on TCP/IPsupport.bull.com/ols/product/system/gcos7/gcos7-com/g7...DPS7000/XTA NOVASCALE 7000 ESP 7 (NGEN) on TCP/IP for DPS 7000/XTA Distributed Computing December 2000

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:///Interop7

where 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 .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 :

\trces_.log

where is the directory where ESP7 has been installed and 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:

\NTGW_\ where:

• is the directory where NT7GW has been installed

• is the identifier of the running NT7GW server

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

Integer (32 bit)

COMP-1 small integer (16 bit)

Short integer (16 bit)

COMP-10floating double precision

Double precision

Character (8 bit) Character (8 bit)

Varchar 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:

/tcp

where is your chosen name and 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 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:

\NTGW_\ where:

• is the directory where NT7GW has been installed

• is the identifier of the running NT7GW server

• 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:

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

/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

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

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

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

Administration Tool for ESP 7

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

Documents

ESP 7 (NGEN) on TCP/IPsupport.bull.com/ols/product/system/gcos7/gcos7-com/g7...DPS7000/XTA NOVASCALE 7000 ESP 7 (NGEN) on TCP/IP for DPS 7000/XTA Distributed Computing December 2000