GCOS 7/ESP - Bull On-line Support...

Distributed Computing

GCOS 7/ESP

ESP 7 (NGEN) on TCP/IP for PC

47 A2 87US Rev03

47 A2 87US Rev03

Distributed Computing

GCOS 7/ESP


Subject: This manual describes how to install and configure the productESP 7 (NGEN) on TCP/IP for PC.

Special Instructions:

Software Supported: ESP 7 (NGEN) Version 7OPEN 7 >= Release 5.0, OP7GW >= Release 6.0GCOS 7-V7 TS >= 7560, GCOS 7-V8 >= 8560,GCOS 7-V9 TS >= 9662

Software/Hardware required: PC with either Windows 95/98/NT 4.0/2000.DPS 7000 with GCOS 7, OPEN 7, and ESP 7.

Date: September 2001

Bull S.A.CEDOCAtelier de reprographie357, Avenue Patton BP 2084549008 ANGERS Cedex 01FRANCE

Bull HN Information Systems Inc.Publication Order EntryFAX: (800) 611-6030MA30/415300 Concord Rd.Billerica, MA 01821U.S.A.

47 A2 87US Rev03

Copyright © Bull S.A., 2000, 2001

Bull acknowledges the rights of proprietors of trademarks mentioned herein.

Your suggestions and criticisms concerning the form, contents and presentation of this manual are invited.A form is provided at the end of this manual for this purpose.

No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by anymeans, electronic, mechanical or otherwise without the prior written permission of the publisher.

Bull disclaims the implied warranties of merchantability and fitness for a particular purpose and makes noexpress warranties except as may be stated in its written agreement with and for its customer. In no event is Bullliable to anyone for any indirect, special, or consequential damages.The information and specifications in this document are subject to change without notice.Consult your Bull Marketing Representative for product or service availability.

47 A2 87US Rev03 iii

Preface

This manual describes how to install, configure, and use the Enterprise ServerProcedures 7 (NGEN) on TCP/IP for PC 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) on TCP/IP for PC.

None.

Scope andObjectives

IntendedReaders

Prerequisites

Structure

Bibliography

SyntaxNotation

DeliveryConditions


iv 47 A2 87US Rev03

47 A2 87US Rev03 v

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 DPS7000 ............................................................................... 1-2

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

2. ESP 7 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 Web7 ....................................................................................... 2-3

2.3.2 Installation from Diskettes.................................................................................. 2-6

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


vi 47 A2 87US Rev03

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-93.5.1.4 Port .................................................................................................. 3-103.5.1.5 GCOS .............................................................................................. 3-103.5.1.6 Mailbox ............................................................................................ 3-103.5.1.7 User ................................................................................................. 3-103.5.1.8 Password......................................................................................... 3-113.5.1.9 Project ............................................................................................. 3-113.5.1.10 Billing ............................................................................................... 3-113.5.1.11 TermId ............................................................................................. 3-113.5.1.12 Trace ............................................................................................... 3-123.5.1.13 TDSPrompt...................................................................................... 3-123.5.1.14 UseRemoteProcedureFile ............................................................... 3-12

3.5.2 Methods ........................................................................................................... 3-133.5.2.1 Connect ........................................................................................... 3-133.5.2.2 Disconnect....................................................................................... 3-133.5.2.3 GetProcedureInfo ............................................................................ 3-143.5.2.4 ExecuteProcedure........................................................................... 3-143.5.2.5 NumberOfFields .............................................................................. 3-163.5.2.6 NumberOfRows............................................................................... 3-163.5.2.7 GetData ........................................................................................... 3-173.5.2.8 GetFieldInfo ..................................................................................... 3-17

3.5.3 Events .............................................................................................................. 3-183.5.3.1 Message .......................................................................................... 3-18

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

3.6.1 Error Constants................................................................................................ 3-20

3.6.2 Trace Facility.................................................................................................... 3-22

3.7 User Interface................................................................................................................ 3-23

3.7.1 User Profiles .................................................................................................... 3-23

3.7.2 User Interface Mechanics ................................................................................ 3-23

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

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

3.8 Dialog Descriptions ....................................................................................................... 3-33

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

3.8.2 Returning Data................................................................................................. 3-33

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

3.9.1 Data Types....................................................................................................... 3-343.9.1.1 Server Data Types........................................................................... 3-353.9.1.2 Conversion ...................................................................................... 3-37

47 A2 87US Rev03 vii

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.4.1 Trace Files ......................................................................................................... 4-7

4.4.2 Execution of the OPEN7 Gateway Modules...................................................... 4-7

4.5 Security ........................................................................................................................... 4-9

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


viii 47 A2 87US Rev03

A. Migration Advice

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

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

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

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

B. Translation Table Utility

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

B.2 Existing Tables ................................................................................................................B-3

B.2.1 Displaying ..........................................................................................................B-3

B.2.2 Modifying............................................................................................................B-3

Glossary

Index

47 A2 87US Rev03 ix

Table of Graphics

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

3-1. Server Data Types ........................................................................................................ 3-363-2. Automatic Data Conversions......................................................................................... 3-37

Figures

Tables


x 47 A2 87US Rev03

47 A2 87US Rev03 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.


1-2 47 A2 87US Rev03

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

3-tier version (100connections and more)

Processor Intel Pentium or fasterprocessor

Intel Pentium II or fasterprocessor

Intel Pentium III orfaster processor

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 DPS7000

ESP 7 requires the following mainframe software:

• OPEN 7 (release 5),

• the OPEN 7 gateway OP7GW (release 7.1.0 or later),

• GCOS 7-V7 (minimum TS 7560), GCOS 7-V8 (minimum TS 8560), orGCOS 7-V9 (minimum TS 9662).

Overview

47 A2 87US Rev03 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 a TP/DBServer.

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.


1-4 47 A2 87US Rev03

❑

47 A2 87US Rev03 2-1

2. ESP 7 Installation

2.1 Preconditions for Installation

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

Other software requirements for its use are outlined below:

OPEN 7, OP7GW, and TCP/IP must be installed and working correctly on theDPS 7000.

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 87US Rev03

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

Pcclean.exe Utility used for connection cleaning on PCrestart.

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 Basicand PowerBuilder

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

Windows 2000)− msvcrt.dll− oleaut32.dll− olepro32.dll

• in Windows directory:

op7gtw.ini File common to several Interop7 productsand used for configuration 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.

ESP 7 Installation

47 A2 87US Rev03 2-3

2.3 Installation Procedure

Note that this version of ESP7NGEN can be installed from a PC either using abrowser to access Web7 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 Web7

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

In the home page, select the «Download Interop7 products on yourworkstation» link:


2-4 47 A2 87US Rev03

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

ESP 7 Installation

47 A2 87US Rev03 2-5

Lastly, click the «ESP7NGEN (release V7.0.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-6 47 A2 87US Rev03

2.3.2 Installation from Diskettes

NOTE:The installation program will require more than one diskette only if the versionsof 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-install it.

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

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

5) MOVE FORWARD FROM WINDOW TO WINDOW UNTIL THE FOLLOWINGWINDOW APPEARS.

At this stage you have to choose your installation directory.

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.

ESP 7 Installation

47 A2 87US Rev03 2-7

Now click on Next to move to the following screen:

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


2-8 47 A2 87US Rev03

6) Move forward from window to window until the following windowappears.

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 VisualBasic and PowerBuilder sources are found in the ESP7NGENinstallation directory in Samples/Visual Basic and Samples/PowerBuilder.

ESP 7 Installation

47 A2 87US Rev03 2-9

7) Move forward from window to window until the following windowappears.

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 87US Rev03

8) Move forward 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:

ESP 7 Installation

47 A2 87US Rev03 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 <Open7 name>.pr1 to your chosen installationdirectory (the utility Espadmpc.exe is already there). The most convenient wayto do this is to use the Transfer facilities of Espadmpc (GetAllProc option).

Note that if your previous version of ESP 7 supported only up to 63 parameters fora given procedure call, you should first run the conf_util utility (available withOP7GW on OPEN 7). This utility converts the OPEN 7 procedure definition file/etc/espconf to the version /etc/espconf1, which supports up to 127parameters.


2-12 47 A2 87US Rev03

❑

47 A2 87US Rev03 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 TDSapplication services (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 fully handledby the ESP7 software component, which only requires the description of both inputand output data (that is, the TDS procedure arguments and the result sets returnedby the transaction) through a tool provided with the product.


3-2 47 A2 87US Rev03

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

OP7GW

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 GCOS7 TDS transactions by means of aTDS object (a combination of code and data treated as a unit), provided by anobject server (ESP7srv.exe – “ActiveX component” in Microsoft terminology,formerly known 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 87US Rev03 3-3

As shown in 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 OPEN7 Gateway server (op7gw2) on GCOS7, 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 OPEN7.


3-4 47 A2 87US Rev03

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 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 87US Rev03 3-5

3.3.1 Using Early Binding

Using early binding with the TDS object requires 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:


3-6 47 A2 87US Rev03

• 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’).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 87US Rev03 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 87US Rev03

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, EPS7Interface), 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 87US Rev03 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.5.1.3 Host

Description A character string (maximum 8 characters) providingthe name of the OPEN 7 subsystem where the OPEN7gateway is to be accessed.If not empty, it will override the “Host name” value ofthe virtual node if the latter is used.



3-10 47 A2 87US Rev03

3.5.1.4 Port

Description A long-type value providing the port number forcommunication with the OPEN7 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.

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.



47 A2 87US Rev03 3-11

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



3-12 47 A2 87US Rev03

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, Trace Facility).

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 theOPEN7 site, 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.


47 A2 87US Rev03 3-13

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.




3-14 47 A2 87US Rev03

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




47 A2 87US Rev03 3-15

The parameter values in the ParametersList string are separated by one or morespace characters. Each parameter value must have a determined format accordingto 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][‘]

DECIMAL types(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 of hexadecimal strings:

‘0xFFFF’, ‘-0x1234’

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

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

another one to protect it.


3-16 47 A2 87US Rev03

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

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


47 A2 87US Rev03 3-17

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

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

Input Parameter Type CommentProcedure String Name of the TDS transaction for which data is

requested. Maximum length:8Index Long Index of the column for which information is

requested (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



3-18 47 A2 87US Rev03

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 CommentMsgProcedure String Name of the TPR that sent the messageMsgType Short TPR output message type. A value of 1

means an information message, a value of 2means an error message.

MsgStatus Long Status generated by the TDS transactionMsgText String Message sent by the TPR


47 A2 87US Rev03 3-19

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 (e.g. 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 of 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 later 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.


3-20 47 A2 87US Rev03

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 Open 7 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)A parameter value in the ParameterList parameter string of theExecuteProcedure method does not match its type definitionex: ‘ZZ’ for an INT type parameter, or 99999 for an SMALLINT typeparameter).

• 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 Open 7 gateway. Contact your support team.


47 A2 87US Rev03 3-21

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


3-22 47 A2 87US Rev03

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, if tracing is requested, a trace file is also produced on OPEN7 under thename:

/usr/tmp/OPGW<ppp>/<iii>/<Pcname>.<session-identifier>

where <ppp> is the port number associated with the Open7 Gateway and <iii> isthe identifier for the Open7 gateway process involved.

While an OPEN7 trace file is always produced if tracing is requested, the contentvaries according to the trace option (-d value) specified at the time of execution ofthe Open7 Gateway (the file will be empty if the Open7 gateway was executedwithout the –d option or with –d 0). See Chapter 4 for details on activation of theOpen7 Gateway.

Even if the Open7 gateway has been executed with –d 0 (or without –d), it is stillpossible to dynamically change the –d value by using the Open7 Gatewayadministration tool (op7gw2adm).


47 A2 87US Rev03 3-23

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 bya 4GL 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 OPEN 7 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.


3-24 47 A2 87US Rev03

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 (Open button)long ll_port// If a run-time error occurs while calling one of the ActiveX control// 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


47 A2 87US Rev03 3-25

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 ActiveX control// method, the ExternalException event will be triggered.

ole_esp.object.Disconnect()

// At this point, the Disconnect() method of the ESP7 ActiveX control// 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 EXECUTINGPROCEDURE

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)


3-26 47 A2 87US Rev03

SCRIPT FOR GETTING PROCEDURE DATA

Script – clicked for cb_proceduregetdata returns long// Event triggered when the user wants to recover the data sent by the// 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 BYTHE 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


47 A2 87US Rev03 3-27

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


3-28 47 A2 87US Rev03

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

’ 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 DisconnectErrorHandler


47 A2 87US Rev03 3-29

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

’ 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"


3-30 47 A2 87US Rev03

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 = FalsecmdOpen.Enabled = FalsecmdClose.Enabled = TruecmdProcedureExecute.Enabled = TruecmdProcedureInformation.Enabled = TruecmdProcedureGetData.Enabled = TrueExit SubConnectErrorHandler:PrintText "*** Aborted connection to " & strDest & " : " & _Err.Number & " (" & Err.Description & ")" & vbCrLfEnd Sub


47 A2 87US Rev03 3-31

’ 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

’ 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


3-32 47 A2 87US Rev03

’ 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


47 A2 87US Rev03 3-33

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.


3-34 47 A2 87US Rev03

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.


47 A2 87US Rev03 3-35

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 byteswhich give the length of the message data. For a decimal data type, the fourleftmost bits of the LENGTH field contain the precision (total number of digits)and the four rightmost bits contain the scale (number of digits after the decimalseparator).

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.


3-36 47 A2 87US Rev03

Table 3-1. Server Data Types

Name DataType

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’s complement 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


47 A2 87US Rev03 3-37

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.


3-38 47 A2 87US Rev03

❑

47 A2 87US Rev03 4-1

4. Configuration of ESP 7

4.1 Configuring TCP/IP

With the ESP administration tool ESPADMPC, you may use symbolic namesinstead of port numbers for communication with the OPEN 7 Gateway. In order todo this, an entry of the following type should be included in the services file in thewindows 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 87US Rev03

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 87US Rev03 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 GCOS7 (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 GCOS7 systems:

• In Windows 95 / Windows NT 4.0 with euro patch (in some fonts andsome applications), or in Windows 98 / Windows 2000, the euro is a newcharacter which is at position ‘0x80 ‘ in all but cyrillic code pages (‘0x88’ in1251 cyrillic code page).

• In GCOS7 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 87US Rev03

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 87US Rev03 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.

Terminal ID the PC name used at connection time


4-6 47 A2 87US Rev03

Trace YES (tracing) or NO (no tracing).The trace file name used by the Open 7 gatewaysituated on Open 7 is:

/usr/tmp/OPGW<ppp>/<iii>/<PCname>.<session-identifier>

where <ppp> is the port number, and <iii> is theprocessId.

Other (reserved for specific application needs).

For ESP 7, 2 options are possible:

-c Open7 to specify the OPEN 7 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, theOpen7 Gateway passes the first 70 characters of the message(s) received from TDSto ESP7NGEN. If the message(s) are less than 70 characters long, the Open7Gateway pads with binary zeroes. Thus ESP7NGEN always receives 70 charactersin response to a connection request. If these 70 characters contain the specifiedTDS prompt (not necessarily at the start of the message(s)), then ESP7NGENconsiders that the connection is valid. Otherwise, ESP7NGEN considers that theconnection is invalid and returns an error to the client application program. Notethat the client application does not receive the 70 characters returned viaTDS/Open7 Gateway.


47 A2 87US Rev03 4-7

4.4 Debugging Facilities

4.4.1 Trace Files

A dynamic trace file may be obtained on OPEN 7. 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:

/usr/tmp/OPGW<port number>/<process identifier>

where:

<port number> is the port number associated with the OPEN 7gateway.

<process identifier> is the OPEN 7 process identifier for the OPEN 7gateway connection.

The trace file is named: <PCname>.<session identifier>.

Note that the trace file is filled ONLY if the OPEN7 Gateway module op7gw2 isexecuting with the –d option set to a non-zero value. See below for details ofexecution of op7gw2.

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

4.4.2 Execution of the OPEN7 Gateway Modules

The executables op7gw2adm and op7gw2Stp may be executed with an optionalport number. If no port number is provided, 9002 is taken by default.

Note that the op7gw2 module is executed at OPEN7 startup. It may be stoppedusing the command:

/users/op7gtw/op7gw2Stp <port number>

It may be re-started using the command:

/users/op7gtw/op7gw2 (with or without parameters (see below)).


4-8 47 A2 87US Rev03

Note that op7gw2 (which now supports up to 1500 connections) may be executedwith the following parameters:

# op7gw2 [-p <port number>] [-d <trace level>] [-s <number of processes>] [-m <number of connections per process>]

The optional parameters have the following significance:

-p:

the port number on which the Open7 Gateway will listen for incoming requestsfrom the TCP/IP network. By default, the port number given in the file/etc/services is used. If there is no entry in the /etc/services file for the Open7Gateway, then the port number 9002 is used.

-d:

the trace level, with the following significance:

-d 0 (or no -d) no trace

-d 1 tracing of connection/disconnection

-d 2 tracing level 1 + VCAM messages

-d >=3 tracing level 2 + other messages (full trace)

-s:

the number of OPEN7 processes to be used for the OP7GW (10 by default)

-m:

the number of connections per process (NCPP). By default, NCPP is 20 and themaximum value is 59.

Note that the following controls are carried out to determine the effective numberof connections per process:

The maximum number of connections per process (MAXCPP) is calculated usingthe value NOFILES in the OPEN7 file /makeopen7/cf/config.h.

MAXCPP = (NOFILES-5) / 4.

If NCPP is greater than or equal to MAXCPP, an error message is obtained.

If MAXCPP is less than 11, an error message is printed. This message indicateshow to increase the MAXCPP value.

The NCPP value is accepted only if it is in the range: 2 < NCPP < MAXCPP.


47 A2 87US Rev03 4-9

4.5 Security

Password Encryption:

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


4-10 47 A2 87US Rev03

❑

47 A2 87US Rev03 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 87US Rev03

❑

47 A2 87US Rev03 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 PC (default configurationoption).

/etc/espconf1 situated on OPEN 7.

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


6-2 47 A2 87US Rev03

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

Application

ESP 7 ActiveX Control

ESP 7 DLL

PC

Local Site File

<hostname>.prlESPADMPC

Administration Tool

DPS 7000 HOST

Host SiteFile

/etc/espconf1

OPEN 7 Gateway VCAM

TDSTransactions

OPEN 7 GCOS 7

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

Administration Tool for ESP 7

47 A2 87US Rev03 6-3

6.2 The Administration Tool (Espadmpc)

To run the Procedure Administration tool, proceed as follows.

On the Start menu, point to Programs, point 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 enable to change the definition ofa selected procedure parameters.

• Main toolbar.

• Menu commands.


6-4 47 A2 87US Rev03

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 87US Rev03 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 87US Rev03

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 Open7 tcp/ip host name and theport number of the Gateway.If the given information is valid, a seconddialog box will ask for an Open7 username and password to ensureauthentication (NOTE: only Open7 “root”user can be authenticated).

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 87US Rev03 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 toolbar.Status bar Shows/hides the status bar.

Help About Espadmpc… Displays program information, programnumber and copyright.


6-8 47 A2 87US Rev03

❑

47 A2 87US Rev03 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 87US Rev03

− 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).The text 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 87US Rev03 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 Automation

Private 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 previousexample.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 accessthis‘ 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


A-4 47 A2 87US Rev03

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.

Migration Advice

47 A2 87US Rev03 A-5

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

..........


A-6 47 A2 87US Rev03

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.

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 87US Rev03 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

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


A-8 47 A2 87US Rev03

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 87US Rev03 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 87US Rev03

❑

47 A2 87US Rev03 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-2 47 A2 87US Rev03

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

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.

Translation Table Utility

47 A2 87US Rev03 B-3

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


B-4 47 A2 87US Rev03

❑

47 A2 87US Rev03 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 WindowedActiveX Control:----------------- 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 87US Rev03

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 87US Rev03 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 87US Rev03

Stored ProcedureA stored procedure, in this document, is a TDS transaction that resides on a GCOS 7 system.Stored procedures are referenced from the user application programs that are developed on PCswith 4GLs, 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 87US Rev03 i-1

Index

A

ActiveXcomponent g-1control g-1definition g-1

automation A-6

C

COMdefinition g-2

Component Object Model g-2configuring

connection parameters 4-4Initialization File 4-2

connection parametersconfiguring 4-4

connection sequence A-5, A-6

D

DATA control A-5Data Source Name g-2data types

automatic conversion 3-37debugging facilities 4-7DSN

definition g-2

E

Enterprise Server Procedures 7description 1-3

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

ESP 7 TPRsinvoking 3-33

ESP 7/DA 7 PC gateway 3-9ESPADMPC

tool 6-1execute_TPR subroutine A-7execution

TPR A-5, A-6, A-7

F

functional description 3-2


i-2 47 A2 87US Rev03

G

Gatewaydefinition g-2

GCOS 7definition g-2

GUIdefinition g-2

H

hardware requirements 1-2

I

IDS/IIdefinition g-3

Initialization Fileconfiguring 4-2

installationpre-conditions 2-1procedure 2-6program 2-2

ISI 7definition g-3

O

ODBCDATA control A-5

data types 3-35output tuples

handling A-5, A-6

P

passwordencryption 4-9

PowerBuilderdefinition g-3

pre-conditionsinstallation 2-1

proceduresESP 7 5-1installation 2-6

R

RAD tools 1-3requirements

on DPS7000 1-2on PC 1-2

RPCdefinition g-3

S

security 4-9sequence

connection A-5, A-6site files

overview 6-1software requirements 1-2SQL

definition g-3SQLDA

definition g-3Stored procedure

definition g-4

T

tablestranslation B-1

tblcgc utility B-1TCP/IP

definition g-4TDS application development 3-3TDS transaction

definition g-4tools

ESPADMPC 6-1TPR

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

trace files 4-7translation tables B-1tuples

output A-5, A-6

Index

47 A2 87US Rev03 i-3

U

UFASdefinition g-4

utilitiestblcgc B-1

V

VCAMdefinition g-4

Visual Basicdefinition g-4processing stored procedures 3-28

X

XCP2definition g-4


i-4 47 A2 87US Rev03

Vos remarques sur ce document / Technical publications remarks form

Titre / Title : ESP 7 (NGEN) on TCP/IP for PC

N° Référence / Reference No. : 47 A2 87US Rev03 Date / Dated : September 2001

ERREURS DETECTEES / ERRORS IN PUBLICATION

AMELIORATIONS SUGGEREES / SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION

Vos remarques et suggestions seront attentivement examinées. Si vous désirez une réponse écrite,veuillez indiquer ci-après votre adresse postale complète.Your comments will be promptly investigated by qualified personnel and action will be taken asrequired. If you require a written reply, furnish your complete mailing address below.

NOM / NAME : DATE :

SOCIETE / COMPANY :

ADRESSE / ADDRESS :

Remettez cet imprimé à un responsable Bull S.A. ou envoyez-le directement à :Please give this technical publications remarks form to your Bull S.A. representative or mail to:

Bull S.A.CEDOCAtelier de reprographie357, Avenue Patton BP 2084549008 ANGERS Cedex 01FRANCE

Bull HN Information Systems Inc.Publication Order EntryFAX: (800) 611-6030MA30/415300 Concord Rd.Billerica, MA 01821U.S.A.

Date post:	04-Nov-2019
Category:	Documents
Upload:	others
View:	7 times
Download:	0 times

GCOS 7/ESP - Bull On-line Support...

Documents