gcos 7/jesp - atossupport.bull.com/ols/product/system/gcos7/gcos7-com/g7-dps7000/… · 4.4...

Distributed Computing

GCOS 7/JESP

JESP 7 for Java Platform

47 A2 93US Rev01

47 A2 93US Rev01

Distributed Computing

GCOS 7/JESP


Subject: This manual describes how to install, configure and use theproduct JESP 7 for Java Platform.

Special Instructions:

Software Supported: JESP 7 Version 4.0.0OPEN 7 >= Release 5.0, OP7GW >= Release 6.0NT7GW >= Release 1.2.0GCOS 7-V8 >= 8560,GCOS 7-V9 TS >= 9662

Software/Hardware required: Java - JDK version 1.1.8 or greater

Date: May 2002

Bull S.A.CEDOCAtelier de reprographie34, rue du Nid de Pie BP 42849004 ANGERS Cedex 01FRANCE

Bull HN Information Systems Inc.Publication Order EntryFAX: (978) 294-7411MA30/865ATechnology ParkBillerica, MA 01821U.S.A.

47 A2 93US Rev01

Copyright © Bull S.A., 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 93US Rev01 iii

Preface

This manual describes how to install, configure, and use the �� .In this manual, the abbreviation �� is used to refer to this product.

This manual is intended for persons who need to install, configure, and/or use theJESP 7 product.

None.

This manual contains 6 chapters and 2 appendices:

Chapter 1 gives an overview of JESP 7 .

Chapter 2 describes the installation of JESP 7 .

Chapter 3 describes the functions and architecture of JESP 7 .

Chapter 4 describes the configuration of JESP 7 .

Chapter 5 describes the configurability of JESP 7 .

Chapter 6 describes the administration tool for JESP 7 .

Appendix A gives advice on migrating from ESP 7 to JESP 7.

Appendix B describes the translation table utility.

None.

The abbreviation �� is used for the name of the product �� .The abbreviation �� is used for the name of the product �� for Java platforms for �� .

None.

��

��

��

��

��

� ��!"��

#�� $��


iv 47 A2 93US Rev01

❑

47 A2 93US Rev01 v

Table of Contents

1. Overview

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

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

1.2.1 Requirements on Java Platform ........................................................................ 1-2

1.2.2 Requirements on Bull Platform .......................................................................... 1-2

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

1.4 Related Documentation................................................................................................... 1-3

2. JESP 7 Installation

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

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

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

2.3.1 Installation from eWeb7 ..................................................................................... 2-3

3. Java Enterprise Server Procedures 7

3.1 Product features.............................................................................................................. 3-1

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


vi 47 A2 93US Rev01

3.3 JESP7 Class .................................................................................................................. 3-4

3.3.1 Fields .......................................................................................................... 3-43.3.1.1 public static final String Version ....................................................... 3-43.3.1.2 public JESP7 SessionId ................................................................... 3-53.3.1.3 public String Node............................................................................. 3-53.3.1.4 public String Host.............................................................................. 3-63.3.1.5 public String Port............................................................................... 3-63.3.1.6 public String GCOS ........................................................................... 3-63.3.1.7 public String Mailbox ........................................................................ 3-63.3.1.8 public String User.............................................................................. 3-63.3.1.9 public String Password..................................................................... 3-73.3.1.10 public String Project.......................................................................... 3-73.3.1.11 public String Billing........................................................................... 3-73.3.1.12 public String TermId.......................................................................... 3-73.3.1.13 static public boolean Trace ............................................................... 3-83.3.1.14 public String TDSPrompt .................................................................. 3-83.3.1.15 public boolean UseRemoteProcedureFile......................................... 3-83.3.1.16 public String Path .............................................................................. 3-83.3.1.17 public boolean CryptPassword........................................................ 3-93.3.1.18 public String TBLFile......................................................................... 3-93.3.1.19 public int ConnectTimeout................................................................. 3-93.3.1.20 public int DialogTimeout .................................................................... 3-93.3.1.21 public boolean AllowLossOfPrecision ............................................... 3-9

3.3.2 Constructor ...................................................................................................... 3-10

3.3.3 Methods ........................................................................................................ 3-103.3.3.1 Connect ........................................................................................... 3-123.3.3.2 Disconnect....................................................................................... 3-123.3.3.3 GetProcedureInfo ............................................................................ 3-133.3.3.4 ExecuteProcedure........................................................................... 3-143.3.3.5 NumberOfFields .............................................................................. 3-173.3.3.6 NumberOfRows............................................................................... 3-183.3.3.7 GetData ........................................................................................... 3-183.3.3.8 GetStringData.................................................................................. 3-193.3.3.9 GetIntegerData ................................................................................ 3-203.3.3.10 GetLongData ................................................................................... 3-213.3.3.11 GetShortData................................................................................... 3-213.3.3.12 GetFloatData ................................................................................... 3-223.3.3.13 GetDoubleData................................................................................ 3-233.3.3.14 GetBigDecimalData......................................................................... 3-233.3.3.15 GetFieldInfo ..................................................................................... 3-24

3.4 Exceptions ................................................................................................................ 3-26

3.4.1 JESP7_exception Class................................................................................... 3-263.4.1.1 Error Constants ............................................................................... 3-27

3.5 Trace Facility ................................................................................................................ 3-30

47 A2 93US Rev01 vii

3.6 User Interface................................................................................................................ 3-31

3.6.1 User Profiles .................................................................................................... 3-31

3.6.2 User Interface Mechanics ................................................................................ 3-31

3.6.3 JESP 7 Usage.................................................................................................. 3-313.6.3.1 Java pure......................................................................................... 3-313.6.3.2 Application Server ........................................................................... 3-32

3.6.4 Accessing Stored Procedures ......................................................................... 3-32

3.7 Dialog Descriptions ....................................................................................................... 3-56

3.7.1 Invoking JESP 7 TPRs..................................................................................... 3-56

3.7.2 Returning Data................................................................................................. 3-56

3.8 File and Data Formats................................................................................................... 3-57

3.8.1 Data Types....................................................................................................... 3-573.8.1.1 Server/TDS Data Types .................................................................. 3-583.8.1.2 Conversion ...................................................................................... 3-59

4. Configuration of JESP 7

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

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

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

4.4 Debugging Facilities........................................................................................................ 4-5

4.4.1 Trace Files on OPEN 7...................................................................................... 4-5

4.4.2 Trace Files on NT partition ................................................................................ 4-6

4.4.3 Execution of the OPEN7 Gateway Modules...................................................... 4-6

4.4.4 Execution of the NT 7 Gateway Modules .......................................................... 4-8

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

4.5.1 Password Encryption ......................................................................................... 4-9

5. Configurability

5.1 JESP 7 Connections ....................................................................................................... 5-1

5.2 JESP 7 Procedures......................................................................................................... 5-1


viii 47 A2 93US Rev01

6. Administration Tool for JESP 7

6.1 Overview .................................................................................................................. 6-1

6.2 Running the Administration Tool (Espadmpc) ................................................................ 6-4

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

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

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

6.2.4 The menus ......................................................................................................... 6-66.2.4.1 Menu commands............................................................................... 6-7

A. Migration Advice: ESP 7 � JESP 7

B. Translation Table Utility

B.1 Java platform to GCOS 7 Translation Table ...................................................................B-1

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

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

B.2.2 Modifying ..........................................................................................................B-2

B.3 Default translation tables.................................................................................................B-3

Glossary

Index

47 A2 93US Rev01 ix

Table of Graphics

Figures

Figure 3-1 Connection between a simple client application & TDS .......................................... 3-2Figure 3-2 Connection between client application, application server & TDS .......................... 3-3Figure 3-3 Methods Overview ................................................................................................. 3-11Figure 6-1 Position of the administration tool in the JESP 7 architecture ................................. 6-2Figure 6-2 Administration Tool in JESP 7 Architecture on DPS 7 & DPS 7 XTA...................... 6-3Figure A-1 Coexistence JESP 7 & ESP 7 for of the same TDS................................................A-1

47 A2 93US Rev01 1-1

�1.�Overview

1.1� Purpose

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

There are 2 versions of the product :

�� (JESP 7) is part of Bull's offeraimed at developing two-tier and three-tier Java Platform-DPS 7000Client/Server applications, using the benefits internet environment.

The �� is the �� interface (EnterpriseJava Bean)

This document focuses on the installation, administration, and programming rulesfor the Java Platform side.


1-2 47 A2 93US Rev01

1.2� Hardware and Software Requirements

1.2.1� Requirements on Java Platform

The following outlines the recommended Java Platform configurations for JESP 7.It can be used in native mode (Java pure) or through J2EE application server.JESP 7 also requires the following software :

For Java pure and J2EE application server usage :

• Java 1.1.8 or greater

• JTDS 4.0.0

• JESP 4.0.0

For J2EE application server usage :

• J2EE application server for the version of EJESP 7

• EJTDS 4.0.0

• EJESP 4.0.0

1.2.2� Requirements on Bull Platform

TDS is the application which is reached by the JESP 7 .This TDS application can be run on DPS 7000 or on DPS 7000 XTA.

On DPS 7000, JESP 7 requires the following software:

• OPEN 7 (release 5),

• the OPEN 7 gateway OP7GW (release 6.0),

• GCOS 7-V8 (minimum TS 8560) or GCOS 7-V9 (minimum TS 9662).

On DPS 7000 XTA, JESP 7 requires the following software:

• the NT7 gateway NT7GW (release 1.2.0),

• GCOS 7-V9 (minimum TS 9866).

Overview

47 A2 93US Rev01 1-3

1.3� Benefits of Java Enterprise Server Procedures 7

Java Enterprise Server Procedures 7 (JESP 7) is a middleware which enables theuse of open, internet environment applications and which benefits from theoutstanding mainframe disciplines of GCOS 7 as a TP/DB Server.

JESP 7 facilitates the building of application systems spanning Java and BullDPS 7000 platforms (both in a two-tier and three-tier context), based on thestandard Java language.

A Java platform is a machine which runs the Java Virtual Machine (JVM).

JESP 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 allowing easier and quicker response toeconomic changes and constraints,

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

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

1.4� Related Documentation

Enterprise Server Procedure for GCOS 7 47 A2 37 UT Rev 02How to code a Transaction to cooperate with ESP 7/JESP 7 application.

JAVA 7 User's Guide 47 A2 38 UT Rev 02Describes the JTDS class

INTEROP 7 User's Guide 47 A2 91 US Rev 00How to install and use Gateway on OPEN 7 (OP7Gw) or on DSP 7000 XTA(NT7gw)

47 A2 93US Rev01 1-4

�

47 A2 93US Rev01 2-1

�2.�JESP 7 Installation

2.1� Preconditions for Installation

JESP7 is downloaded using a browser to access eWeb7.This method is outlined in Installation Procedure below.

For DPS 7000 :The software requirements for its use are outlined below:OPEN 7, OP7GW, and TCP/IP must be installed and working correctly on theDPS 7000.

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

2.2� The Installation Program

After executing the installation procedure (as described in the paragraph“Installation Procedure” below) to install JESP7, you should find the followingelements installed on yours systems :

�� :

The following executables on PC allow you to configure your environment andto produce files that must be moved to the Java Platform.

Espadmpc.exe Utility for procedure declaration handling.

Espini.exe Utility for configuration of op7gtw.ini(used only in DPS 7000 XTA)

Dsncnfg.exe Utility for configuration of connectionparameters.

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


2-2 47 A2 93US Rev01

��

For a Java pure use :

Jtds.jar

Jesp7.jar

For an EJB running on WebLogic :

- JtdsEjbWL.jar

- Jesp7EjbWL.jar

For an EJB running on an unspecified Application Server :

- JtdsEjb.jar

- Jesp7Ejb.jar

��

- Monitor_JESP7.java : Java program which allows you to test the JESP7product only in Java pure.

JESP 7 Installation

47 A2 93US Rev01 2-3

2.3� Installation Procedure

You install the product from eWeb7.

2.3.1� Installation from eWeb7

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 your workstation» link:


2-4 47 A2 93US Rev01

In the next page that appears, click the «��» link to install first, theprerequisite software :

JESP 7 Installation

47 A2 93US Rev01 2-5

Then, on your Java platform install one of the three �� according to your use:

- Jtds.jar (for Java Pure use)

- JtdsEjbWL.jar (for EJB running on WebLogic)

- JtdsEjb.jar (For EJB running on an unspecified Application Server)


2-6 47 A2 93US Rev01

Then, go back to the initial page to �� !�then, click the «�"�� » link to install the software. :

JESP 7 Installation

47 A2 93US Rev01 2-7

Then, on your Java platform install one of the three �� that make the interface of aJava program and the JESP7 API, according to your use:

- Jesp7.jar (for Java Pure use)

- Jesp7EjbWL.jar (for EJB running on WebLogic)

- Jesp7Ejb.jar (For EJB running on an unspecified Application Server)

Install also on an "administrative PC" the Jesp7 PC tools through Jesp7.exe.These tools produce files which must be moved into the Java platform

Note : If you have already installed the ESP7 product on your PC, �� the JESP7 tools from Jesp7.exe because ESP7 tools are identicalthen JESP7 one, and you can destroyed the ESP7 parameters when youinstall the JESP7 tools.But �� the JESP7 tools if you have not installed ESP7.

47 A2 93US Rev01 2-8

�

47 A2 93US Rev01 3-1

�3.�Java Enterprise Server Procedures 7

3.1� Product features

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

A JESP7-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 Java platform and GCOS7 environments (ASCII /EBCDIC strings, memory data storage and numeric representation) is fully handledby the JESP7 software component, which only requires the description of bothinput and output data (that is, the TDS procedure arguments and the result setsreturned by the transaction) through a tool provided with the product.


3-2 47 A2 93US Rev01

3.2� Functional Description

Figure 3.1 & Figure 3-2 show the different connections between a clientapplication and two TDS (TDS(1) and TDS(2)), using JESP7:

��

Java Enterprise Server Procedures 7

47 A2 93US Rev01 3-3

��

The client application triggers the GCOS7 TDS transactions by means of a TDSobject (a combination of code and data treated as a unit), provided by an objectserver. This TDS object is built upon Java Platform technology, which means itprovides its functionality – in our case executing GCOS7 transactions – to theclient application through a set of fields, methods and exceptions which aredescribed in the paragraph “JESP7 Interface” below.

Note that, two client applications on the same Java Platform can access the sameTDS �� (defined by TDS user name, password,mailbox, project, billing and terminal identifier) to execute their transactions.


3-4 47 A2 93US Rev01

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 Gateway server (op7gw2 or nt7gw) 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 “�� ” (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 Java Platform or on the Gateway side.

3.3� JESP7 Class

Declaration : class JESP7This public class enables a to connect to TDS, put request to TDS then getstructured responses, information messages or error message from TDS. And thendisconnect from TDS. This class also gives a set of methods providing the structureof the request and the structure of the data returned by TDS.The user has at his disposal the following fields, methods, and exceptions for theexecution of remote TDS transactions from his Java Platform.

3.3.1� Fields

With the exception of SessionID, all properties are used by the Connect method(see §3.3.3 Methods):

3.3.1.1 public static final String Version

Contains the current version of JESP7 that you use.

Final Initial value : "1"


47 A2 93US Rev01 3-5

3.3.1.2 public JESP7 SessionId

An handling providing the session identifierIt is set to a non null value after a successful connection has been established.This value is also the JESP7 handling value.

Initial value : null (no session)

3.3.1.3 public String Node

A String (maximum 12 characters) providing the name of a connection identifierdefined through the Connection Handling utility (DSNCNFG: see §4.3 Configuringconnection parameters).If it is not null, the connection parameters defining this node will be used duringthe connection, then if one of the following parameters is not null then it overwritethe corresponding defining parameters in the Node.(except for the Trace optionwhich is an OR operation between the Trace value contained in the Node and theparameter one)The Node parameter is taken prior to each connection parameter which are filledby the corresponding value recorded in the dsncnf.cfg entry file.Note that this parameter stands in for the following one which their default value isnull except for Trace which is false:

- Host- Port- GCOS- Mailbox- User- Password- Project- Billing- TermId- Trace

Default value for Node : null


3-6 47 A2 93US Rev01

3.3.1.4 public String Host

A String (maximum 36 characters) providing the name of the OPEN 7 or NT7GWsubsystem where the gateway is to be accessed.

!�� : For NT7GW : if this name contains more then 8 characters, then you mustcreate an alias of this name with a maximum of 8 characters and use thealias name for this field.

Default value : null

3.3.1.5 public String Port

A String providing the port number for communication with the OPEN7 orNT7GW gateway. A valid port number must be between 1024 and 65535.

Default value : null (usual value is 9002)

3.3.1.6 public String GCOS

A String (maximum 4 characters) providing the name of the GCOS 7 system to beaccessed.


3.3.1.7 public String Mailbox

A String (maximum 8 characters) providing the name of the TDS mailbox to beaccessed.


3.3.1.8 public String User

A String (maximum 12 characters) providing a valid user name for the TDSmailbox connection.



47 A2 93US Rev01 3-7

3.3.1.9 public String Password

A String (maximum 12 characters) providing a valid password name for the TDSmailbox connection.


3.3.1.10 public String Project

A String (maximum 12 characters) providing a valid project name for the TDSmailbox connection.This parameter must be null if you want to use the default Project of the GCOS 7User.


3.3.1.11 public String Billing

A String (maximum 12 characters) providing a valid billing name for the TDSmailbox connection.This parameter must be null if you want to use the default Billing of the GCOS 7User.


3.3.1.12 public String TermId

A String (maximum 7 characters) providing the Terminal Identifier. The value ofthis property will be sent to executed TPRs through the SYMBOLIC SOURCEfield of the input Communication Description (see the Communication Section inthe appropriate �� ). A dollar character is automaticallyadded at the beginning of the string, so that the TDS may know that itscorrespondent is not a user terminal.If its value is null, then the login name is taken.



3-8 47 A2 93US Rev01

3.3.1.13 static public boolean Trace

A static boolean which, if set to TRUE, will activate the trace facility.

NOTE:The Trace facility will be activated if either this field is set to TRUE or theTrace field of the virtual node is set to “YES” (see §3.5 Trace Facility).

Default value : false

3.3.1.14 public String TDSPrompt

A String (maximum 46 characters) providing the currently applied TDS prompt.This field is used in the Connect method.

Default value “READY”

3.3.1.15 public boolean UseRemoteProcedureFile

A boolean which, if set to TRUE, will indicate that the Procedure definition file isto be retrieved from the OPEN7 site, rather than from the Java Platform.This boolean is useful only the first time when a new procedure is requested, afterit is retrieved from the memory.

Default value : FALSE

3.3.1.16 public String Path

Path where the parameter files produced on the administrative PC are found.These files have the following extension :

.pr1 for procedure declaration file,

.tbx for conversion ASCII��EBCDIC table

.cfg for the virtual node file which contains a set of host, user, password, mailbox,…

If its value is null then the default path is $HOME which is the value returned bythe method : System.getProperty("user.home")

Default value null


47 A2 93US Rev01 3-9

3.3.1.17 public boolean CryptPassword

Encrypted password option


3.3.1.18 public String TBLFile

Indicates the name of the translation table that will be used in all followingconnections.This file has the extension : .tbx


3.3.1.19 public int ConnectTimeout

Timeout applied for connections (in seconds)

Default value : 20 seconds

3.3.1.20 public int DialogTimeout

Timeout applied for dialog (Send/Receive).

Default value : 60 seconds

3.3.1.21 public boolean AllowLossOfPrecision

Allow Loss of Precision during conversion of the parameter in parameter-list ofExecuteProcedure for the Decimal.

true : Allow Loss of Precision

false : Prevent Loss of Precision

"#$%&'"(

If the required parameter has the 9V99 type then the data 6.55957 is truncated to6.55 if AllowLossOfPrecision is true, else a JESP7_exception exception is raisedwith the ESP_ERR_INPUTPARAMETER reason.



3-10 47 A2 93US Rev01

3.3.2� Constructor

There is no specific constructor for this class. The default constructor is then used :JESP7()

3.3.3� 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, as an object, the output field j of row i for agiven procedure call.

GetStringData to obtain, as a String, the output field j of row i for agiven procedure call.

GetIntegerData to obtain, as an Integer, the output field j of row i for agiven procedure call.

GetLongData to obtain, as a Long, the output field j of row i for agiven procedure call.

GetShortData to obtain, as a Short, the output field j of row i for agiven procedure call.

GetFloatData to obtain, as a Float, the output field j of row i for agiven procedure call.

GetDoubleData to obtain, as a Float, the output field j of row i for agiven procedure call.

GetBigDecimalData to obtain, as a BigDecimal, the output field j of row ifor a given procedure call.

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


47 A2 93US Rev01 3-11

��%��)��

First you must connect to TDS with the �� method : this method requests aconnection which asks TDS to allocate a session.

Then the *��&��+ �,&-�allows you to retrieve parameters info (2) for theprocedure P, from the file .pr1 through the Gateway (1) or your Java Platform (1).These informations are stored in a data structure "Info for Current Procedure P"attached to the JESP 7 instance.Note that the invocation of the GetProcedureInfo(P) method is not mandatorybefore the call to the ExecuteProcedure(P, param) method.


3-12 47 A2 93US Rev01

Then, using the parameters information, you can invoke the correspondingtransaction P using the method ".��&��,&��-. This methodrequests TDS to execute transaction with the specified parameters, then in case oft-uple, the data are stored in an array attached to the data structure "Info for CurrentProcedure P".

Now, you can retrieve t-uple data for the procedure P using the *��,&��/-method. The !��) 0��,&- and the !��) ��,&- provide theboundaries for the array where the data are stored.

The *��+ �,&��/- is useful to know the data type of the column j.Note that the GetData(P, i, j) method returns a data of OBJECT type.

To close the communication with TDS you must invoke the Disconnect method.

3.3.3.1 Connect

public void �� () throws DSAexception, JESP7_exception

Function to connect to a TDS session.

Parameters none (all connection parameters are set by the JESP7class field: see §3.3.1 Fields)

Throws JESP7_exception :- code : ESP_ERR_UNKNOWNNODE if the name ofthe virtual node is unknown.- code : ESP_ERR_NOCONNECTION if therequested connection is failed. SeeJESP7_error_message to known the detailed reasonDSAexception : see JTDS

3.3.3.2 Disconnect

public void �� () throws DSAexception

Function to disconnect from a TDS session.

Parameters none.

Throws JESP7_exception :- code : ESP_ERR_NOCONNECTION if the currentJESP7 instance has no connection established.DSAexception : see JTDS


47 A2 93US Rev01 3-13

3.3.3.3 GetProcedureInfo

public String *��&��+ �(String Procedure) throws JESP7_exception

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

+ ��&�� 1��

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

Returns String containing the input procedure information:�� .

Throws JESP7_exception :- code : ESP_ERR_GATEWAYCannot access remote file on GATEWAY side forProcedure name=�� , reason is : �� - code : ESP_ERR_UNKNOWNPROCEDUREProcedure name=�� is UNKNOWN !


3-14 47 A2 93US Rev01

3.3.3.4 ExecuteProcedure

public void ".��&��(String Procedure, String ParametersList)throws DSAexception, JESP7_exception

Function to execute a TDS transaction.

+ ��&�� 1��

Procedure String Name of the TDS transaction to be executedMaximum length: 8 characters

ParametersList String String containing the input parameters for theTDS transactionMaximum length: 32K

Returns none. To retrieve the data returned by the TPR, invokethe GetData method

Throws JESP7_exception :- code : ESP_ERR_TDS_DATA_MSG :

Type 1 message- code : ESP_ERR_ABORTEDPROCEDURE :

Type 2 message- code : ESP_ERR_DATAVALUE

* Erroneous or missing SQLDA message* Unknown m_msgtype=�� at offset= ��

- code : ESP_ERR_NOCONNECTION :A connection must be active duringExecuteProcedure.

- code : ESP_ERR_ARGUMENT :Procedure name=Procedure is toolong > 8 characters

- code : ESP_ERR_GATEWAY :Cannot access remote file onGATEWAY side for Procedurename=�� , reason is : ��

- code : ESP_ERR_UNKNOWNPROCEDURE :Procedure name=�� isUNKNOWN !

- code : ESP_ERR_INTERNALERROR :Feed message NOT DONE duringExecuteProcedure(The retrieval of the procedure from thegateway is failed)

DSAexception : see JTDS


47 A2 93US Rev01 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:

�1�� '��

SMALLINT [+ | –] [0 [ x | X ]] <��> Minimum decimal value:-32768Maximum decimal value:+32767

INT [+ | –] [0 [ x | X ]] <��> Minimum decimal value:-2147483648Maximum decimal value:+2147483647

FLOAT [+ | –] <��> <decimal point><��>[{d | D | e | E} [+ | –] <��]

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

DECIMAL [-]<��>[<decimal point> <digits>]

Maximum number of digits is31 (on GCOS7)

CHAR [‘][��][‘]

For �%$''+!�-�1�� and +!��1�� 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’


3-16 47 A2 93US Rev01

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

• For �"�+%$'��1�� the property AllowLossOfPrecision of the JESP7 classallows (if it is set to true) truncation of the decimal part if the number of digitsafter the decimal point exceeds the number of digits after the decimal point ofthe destination data.Example: the data 5.45972 is truncated to 5.45 if the parameter descriptionspecifies the type PIC 9V99 and AllowLossOfPrecision property is set to trueelse the ESP_ERR_INPUTPARAMETER exception is raised with the message"A loss of precision occurs during the conversion of the inputparameter=�� into Decimalbut if the parameter description specifies the type PIC 9V99 then the data 15.1leads to the exception : ESP_ERR_INPUTPARAMETER with the message "AnOverflow occurs during the conversion of the input parameter=�� intoDecimal."Refer to the java.math.2�� Class to obtain the format of the DECIMALtype.See also the java.text.�� Class for formatting decimal numbers.

A �3$0�1�� parameter value must begin and end with a quote character in thefollowing cases:

when it is empty,

when it contains at least one space character,

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

"#$%&'"��)��4$'+��3$0�5&"�&$0$%"�"0�4$'6"�(

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

�� :

To support special char from "00"x to "1F"x and from "80"x to "FF"x you mustspecified the file.encoding property.

The file.encoding property can be specified as follow :

• when you run your java application you can specified : java -Dfile.encoding=7789: ��!�� "��


47 A2 93US Rev01 3-17

• inside your application java you insert the following java code :

String w_previous_value;w_previous_value = System.setProperty("file.encoding","8859_1");

�� !"#

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

3.3.3.5 NumberOfFields

public long !��) ��(String Procedure) throws JESP7_exception

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

+ ��&�� 1��

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

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

Throws JESP7_exception :code : ESP_ERR_ARGUMENT :

Procedure name=Procedure is toolong > 8 characters


- code : ESP_ERR_UNKNOWNPROCEDURE :Procedure name=�� isUNKNOWN !


3-18 47 A2 93US Rev01

3.3.3.6 NumberOfRows

public long !��) 0��(String Procedure) throws JESP7_exception

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

+ ��&�� 1��

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

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



3.3.3.7 GetData

public Object *��(String Procedure, long RowIndex, long FieldIndex)throws JESP7_exception

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

+ ��&�� 1��

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

RowIndex Long Index of the row for which data is requested.Starting from 0 to NumberOfRows - 1

FieldIndex Long Index of the column for which data is requestedStarting from 0 to NumberOfFields - 1

Returns requested data value (Object type)Note that the type of the returned data is generic, thenyou can cast this data according to thegetClass().getName() method or with the GetFieldInfoof JESP 7 method.


47 A2 93US Rev01 3-19

Throws JESP7_exception :- code : ESP_ERR_ARGUMENT :

Procedure name=Procedure istoo long > 8 characters

- code : ESP_ERR_NOROWSETAVAILABLE :Procedure name=�� does notreturn a Row Set (T-uple) !

- code : ESP_ERR_PROCEDURENOTEXECUTED : Procedure name=�� has not beenexecuted !

- code : ESP_ERR_INPUTPARAMETER:Procedure name=�� returns#�$%&� !�� columns, then therequested column='��!�(��$ isinaccessible !

NOTE:You may invoke the NumberOfRows and NumberOfFields methods todetermine the bounds of the RowIndex and the FieldIndex parameters.

3.3.3.8 GetStringData

public String *�� (String Procedure, long RowIndex, long FieldIndex)throws JESP7_exception

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

+ ��&�� 1��




Returns requested data value (String type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not the Stringtype.


3-20 47 A2 93US Rev01

3.3.3.9 GetIntegerData

public String *��+ ��(String Procedure, long RowIndex, long FieldIndex)throws JESP7_exception

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

+ ��&�� 1��




Returns requested data value (Integer type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not the Integertype.


47 A2 93US Rev01 3-21

3.3.3.10 GetLongData

public String *��'� ��(String Procedure, long RowIndex, long FieldIndex)throws JESP7_exception

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

+ ��&�� 1��




Returns requested data value (String type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not the Longtype.

3.3.3.11 GetShortData

public String *��(String Procedure, long RowIndex, long FieldIndex)throws JESP7_exception

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

+ ��&�� 1��





3-22 47 A2 93US Rev01

Returns requested data value (Short type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not the Shorttype.

3.3.3.12 GetFloatData


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

+ ��&�� 1��




Returns requested data value (Float type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not the Floattype.


47 A2 93US Rev01 3-23

3.3.3.13 GetDoubleData


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

+ ��&�� 1��




Returns requested data value (Double type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not the Doubletype.

3.3.3.14 GetBigDecimalData

public String *��2��(String Procedure, long RowIndex, longFieldIndex)throws JESP7_exception

Function to obtain the output BigDecimal field j of row i for agiven procedure call.

+ ��&�� 1��





3-24 47 A2 93US Rev01

Returns requested data value (BigDecimal type)

Throws JESP7_exception :Same as GetData, plus :- code : ESP_ERR_TYPE_ERROR :The FieldIndex of this Procedure has not theBigDecimal type.

3.3.3.15 GetFieldInfo

public GetFieldInfo_out GetFieldInfo(String Procedure, long Index)throws JESP7_exception

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

+ ��&�� 1��

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

FieldIndex Long Index of the column for which information isrequested (starting from 0 to NumberOfFields - 1)

Returns Handle of the *��+ �:�� class which containsthe following members :

%��!�� *��+ �:��

��1��

Name String Name of output parameter j

Type String Type of output parameter j

Length String Length1 of output parameter j

1 For DECIMAL type, the Length returned is composed of:<number of digit of the integer part> "," < number of digits of the decimal part>


47 A2 93US Rev01 3-25

The class *��+ �:��contains only these members, there is no contructor,nor methods.

The values returned for the member Type are :

� LONG � DECIMAL_UNSIGNED_UNPACKED� CHAR � DECIMAL_UNSIGNED_PACKED� SHORT � DECIMAL_SIGNED_UNPACKED� FLOAT � DECIMAL_SIGNED_PACKED� DATE_TIME � Unknown_Type� VARCHAR

Exceptions throws by GetFieldInfo method :




- code : ESP_ERR_UNKNOWNPROCEDURE :Procedure name=�� is unknown !

- code : ESP_ERR_ARGUMENT :Procedure name=�� has only#�$%&�� parameters.


3-26 47 A2 93US Rev01

3.4� Exceptions

3.4.1� JESP7_exception Class

The JESP7_exception class has no method and its constructors are not accessible tothe user.

The JESP7 class raises an exception named JESP7_exception to notify:

the client application of information and error messages sent by the TDS.

that an error has occurred, it returns an error code and an error text description toidentify the problem

This exception will be raised by the JESP7 class when calling the JESP7 methods.

In this case, the following JESP7_exception's fields will be available on the catchclause of the client application:

��!�� ;"�&<:�.��

�1��

JESP7_Procedure 1 String Name of the TPR that sent the message

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

JESP7_MsgStatus 2 Long Status generated by the TDS transaction

JESP7_Message 2 String Message sent by the TDS transaction

JESP7_error 2 Int Error number

JESP7_error_message 2 String Message text corresponding to the errornumber.

1 Available only on a catch exception during the execution of ExecuteProcedure method if the executed TPR sends a type-1 or type-2 message.

2 Always meaningful


47 A2 93US Rev01 3-27

3.4.1.1 Error Constants

Error constants are supplied with the JESP7_exception class to identify theJESP7_error property value it will set.The following values can be retrieved from the JESP7_exception class:if jesp7_exception is an instance of the JESP7_exception class then thejesp7_exception. JESP7_error may be compared to thejesp7_exception.�!�� where �!�� can take the code described below :

ESP_ERR_TDS_DATA_MSG: (code 0) The TDS sent an information message.The following members are available:

- JESP7_Procedure- JESP7_MsgType- JESP7_MsgStatus- JESP7_Message

ESP_ERR_ABORTED&0)�"�60": (code 1) The executed procedure hasaborted, the TDS sent an error message.The following members are available:

- JESP7_Procedure- JESP7_MsgType- JESP7_MsgStatus- JESP7_Message

ESP_ERR_ARGUMENT: (code 2)An argument of the called method is erroneous (ex: negative value for the � ��parameter of the � �� method).

ESP_ERR_BUSY�)!!"��+)!: (code 3)A send to TDS is requested but the turn has not yet been received (internal error)

ESP_ERR_DATA4$'6": (code 4)This error code will be returned if the data sent by the Gateway has erroneouscontents. Use the trace facility (see §3.5 Trace Facility) to identify the problem.

ESP_ERR_DSN�+'": (code 5)An error occurred while accessing the DSN configuration file (maintained withthe dsncnfg utility).

ESP_ERR_INPUT&$0$%"�"0: (code 6)A parameter value in the ��)�� parameter string of the�$�� method does not match its type definitionex: ‘ZZ’ for an INT type parameter, or 99999 for a SMALLINT type parameter).

ESP_ERR_INTERNAL"00)0: (code 7)An internal error occurred. Contact your support team.

ESP_ERR_NO�)!!"��+)!: (code 8)Called method requires that a successful connection be made before using it orconnection failed.


3-28 47 A2 93US Rev01

ESP_ERR_NO%)0"SESSION: (code 9)No more sessions are available.

ESP_ERR_NUMBER)�PARAMETERS: (code 10)The number of parameters in the ��)�� parameter string of the�$�� method does not match the procedure definition.

ESP_ERR_GATEWAY: (code 11)An error occurred in the Gateway (Op7gw or Nt7gw).Contact your support team.

ESP_ERR_OUTPUT&$0$%"�"0: (code 12)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.

ESP_ERR_PROCEDURE�+'"ACCESS: (code 13)An error occurred while accessing the Procedure definition file.

ESP_ERR_PROCEDURE�+'"CONTENTS: (code 14)An error occurred while analyzing the Procedure definition file contents.

ESP_ERR_PROCEDURE!)�EXECUTED: (code 15)This error occurs when calling the �� method if the �$�� method has not been successfully called first for the same specified procedurename.

ESP_ERR_SYNTAX: (code 16)Syntax error in the ��)�� parameter string of the �$�� methodex: a beginning-of-string quote character does not have a matching end-of-stringquote character

ESP_ERR_TDS$2!DISCONNECT: (code 18)(� �� method only): The previous session to the TDS was abnormallydisconnected and the last transaction may not have been successfully completedbefore the disconnection.

ESP_ERR_UNKNOWN!)�": (code 19)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).

ESP_ERR_UNKNOWN&0)�"�60": (code 20)Current procedure name has not been found in the procedure information file.

ESP_ERR_VCAM: (code 21)An error occurred in the GCOS7 VCAM layer.


47 A2 93US Rev01 3-29

ESP_ERR_WINSOCK: (code 22)An error occurred in the Windows Socket layer.

ESP_ERR_MSG%$'FORMED: (code 23)The TDS message is not correctly structured (internal error)

ESP_ERR_NO0)=�"�AVAILABLE: (code 24)This error occurs when calling the �� method if the �$�� method does not return a Row Set.

ESP_ERR_BAD_VARCHAR_SIZE: (code 25)The size of the VARCHAR output parameter causes a boundary exception.

ESP_ERR_TBX�+'": (code 26)An error occurred during the read of the .tbx file built by the tblpcgc.exeutility on PC.

ESP_ERR_CNFG��!: (code 27)An error occurred while accessing the DSN configuration file (maintained withthe dsncnfg utility).

ESP_ERR_TYPE_ERROR (code 28)The requested TYPE in the method Get<Type>Data is not correct because thedata for the requested procedure and field index has not the right type


3-30 47 A2 93US Rev01

3.5� Trace Facility

Viewing the data exchanged by the JESP7 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 JESP7 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 �� argument whencalling the �� method of the JESP 7 class. Alternatively, tracing can berequested by setting the Trace field to YES in the corresponding connection entry.In each case, the trace writes on the standard output.

See Chapter 4 for the Debugging facilities.


47 A2 93US Rev01 3-31

3.6� User Interface

3.6.1� User Profiles

Typical users of the JESP 7 facility are application developers who wish to takeadvantage of the Java capabilities of the client/server environment, and at the sametime recognize the value of maintaining their data repository enterprise systemssuch as IDS/II on GCOS 7.

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

3.6.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 JESP 7 with Java applications.

The data stream to TDS TPRs is via the Gateway. The input data is first treated,then the appropriate target TPR is called. When control is returned to JESP7 fromthe target TPR, any data from the target TPR is converted to a format expected bythe client. The JESP7 methods perform all extended ASCII/EBCDIC conversionoperations.

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.6.3� JESP 7 Usage

The JESP 7 can be used in :- Java pure- an Application Server

3.6.3.1 Java pure

In ;��, the CLASSPATH variable must refer to the JESP7.jar and JTDS.jar


3-32 47 A2 93US Rev01

3.6.3.2 Application Server

For the =��'��$�� 8>, the EJB Jesp7EjbWL.jar andJTDSEjbWL.jar are already deployed. Then add the full path of the .jar in theweblogic.ejb.deploy= variable of the weblogic.properties file.

For ��$�� , deploy the Jesp7Ejb.jar and JTDSEjb.jar. Thenrefer to the specific documentation of your Application Server for the use of these.jar.

For an Application Server the following class are provided :

- public class JESP7 implements SessionBean

- public interface JESP7Home extends EJBHome

- public interface JESP7_I extends EJBObject, Remote

Note that the JESP7 class defined here contains the same fields, constructor,methods that the JESP7 class defined in the section §3.3 JESP7 Class

3.6.4� Accessing Stored Procedures

Only procedures (TPRs) that return t-uples and/or messages may be used from theJava application.

Messages returned may be of:

Type 1 informative

Type 2 error

An example of a Java client application (source and executable) is delivered withthe product. Below is the source code containing the calls to the JESP7 methods:

The following application is a "synthetic" application that allows you to test in Javaa TDS which is adapted/written for JESP 7 or ESP 7 interface.

This application prompts you to enter a command line which is the description ofthe JESP 7 interface.


47 A2 93US Rev01 3-33

The syntax is:

resnais:~/jesp/src% java MoniJESP

************************************

*** Welcome to the JESP7 Monitor ***

************************************

>>> Enter the command. Type ’help’ to list all available commands.

>> new : The JESP7 index is 0

>: ��

.. Commands are :

.. ------------

.. Comment :: To insert a comment in the input command flow of the JESP7 Monitor

.. (abbrev ’/*’ or ’//’)

.. Connect {Node=<Node> | Host=<Host> [Port=<Port>] Gcos=<Gcos> Mailbox=<Mailbox> User=<User>

.. Password=<Password> [Project=<Project>] [Billing=<Billing>] [TermId=<TermId>]

[Trace=<Trace>]}

.. :: To connect a specified user to TDS (abbrev: cn)

.. Disconnect :: To disconnect a specified user from TDS (abbrev: ds)

.. echo [on | off] :: To trace input comand line (default is on).

.. end :: To end the Monitor_JESP7 (abbrev quit or ’/’)

.. ExecuteProcedure <Procedure-Name> [<Parameter-List>]

.. :: To execute the transaction <Procedure-Name> with

.. the optional <Parameter-List> (abbrev: execute or ex)

.. GetData <Procedure-Name> [<RowIndex> [<FieldIndex>]]

.. :: To get the Data of the executed <Procedure-Name>

.. located on <RowIndex> and <FieldIndex>

.. If an Index is missing then get all the set of the missing Index

.. (abbrev: gd)

.. GetFieldInfo <Procedure-Name> [<Field-Index>]

.. :: To get the Name, Type, and Length of the specified field <Field-Index>

.. of the <Procedure-Name> (abbrev : gfi)

.. GetProcedureInfo <Procedure-Name>

.. :: To get the String of prototype call of the <Procedure-Name> (abbrev : gpi)

.. help [<command-name>] :: To get help about all command or a specific one. (abbrev ’?’)

.. keyboard :: To switch input command flow on keyboard.

.. new :: To create a new handle of JESP7.

The returned number is take as the current JESP7 index.

.. NumberOfFields <Procedure-Name>

.. :: To get the NumberOfFields of <Procedure-Name> (abbrev : nbf)

.. NumberOfRows <Procedure-Name>

.. :: To get the NumberOfRows of <Procedure-Name> (abbrev : nbr)

.. print [<JESP7_index>] :: To print the JESP7 class referenced by the <JESP7_index> integer.

.. If <JESP7_index> integer is missing then the current one is taken. (abbrev

p)

.. put [Node=<Node>] [Host=<Host> [Port=<Port>] [Gcos=<Gcos> [Mailbox=<Mailbox>] [User=<User>]

.. [Password=<Password>] [Project=<Project>] [Billing=<Billing>] [TermId=<TermId>] [Trace=<Trace>]

.. [AllowLossOfPrecision=<AllowLossOfPrecision>]

.. :: To put the specific value into a specified JESP7 class member

.. set <JESP7_index> :: To define the current JESP7 index as the <JESP7_index> integer.


3-34 47 A2 93US Rev01

You can enter the command of the MoniJESP7 �� ?�1�� with:java MoniJESP7

You can enter the command of the Monitor_JESP7 �� with :java MoniJESP7 file_nameThe file_name must be an ASCII file containing the commands.

A typical command flow is :

resnais:~/jesp/src% java MoniJESP

************************************

*** Welcome to the JESP7 Monitor ***

************************************

>>> Enter the command. Type ’help’ to list all available commands.

>> new : The JESP7 index is 0

>: connect Host=bc06-41 Port=9990 Gcos=BC06 Mailbox=RATP User=SCHA2 Password=SCHA

>>> Monitor_JESP7 : Connect returns : 0

>: GetProcedureInfo EINT

>>> Monitor_JESP7 : GetProcedureInfo Procedure_Name=EINT returns : EINT([in] CHAR(6) NO-CPTE,[out]

CHAR(80) MSG-INT)

>: ExecuteProcedure EINT 000001

>: NumberOfFields EINT

>>> Monitor_JESP7 : NumberOfFields Procedure_Name=EINT returns : 1

>: NumberOfRows EINT

>>> Monitor_JESP7 : NumberOfRows Procedure_Name=EINT returns : 4

>: GetData EINT 0 0

>>> Monitor_JESP7 : GetData Procedure=EINT, Row=0, Field=0, Value=

CLE=000001 21/09/00 NOM DU CLIENT : AVAKIANTZ D. SOLDE = 9990,00 (01)

>: GetData EINT

>>> Monitor_JESP7 : GetData/NumberOfRows Procedure_Name=EINT returns : 4

>>> Monitor_JESP7 : GetData/NumberOfFields Procedure_Name=EINT returns : 1

>>> Monitor_JESP7 : GetData Procedure=EINT, Row=0, Field=0, Value=

CLE=000001 21/09/00 NOM DU CLIENT : AVAKIANTZ D. SOLDE = 9990,00 (01)

>>> Monitor_JESP7 : GetData Procedure=EINT, Row=1, Field=0, Value=(00) 000001 21/09/00 VERSEMENT

10000,00+

>>> Monitor_JESP7 : GetData Procedure=EINT, Row=2, Field=0, Value=(01) 000001 21/09/00 Boisson

10,00-

>>> Monitor_JESP7 : GetData Procedure=EINT, Row=3, Field=0, Value=>>> EOD.

>: Disconnect

>>> Monitor_JESP7 : Disconnect returns : 0

>: quit

<<< JESP7 Monitor Terminated.

resnais:~/jesp/src%


47 A2 93US Rev01 3-35

The code of the MoniJESP is as follows :

import java.net.*;

import java.lang.*;

import java.util.*;

public class MoniJESP

{

static boolean St_echo=false; // echo of the command line

static boolean St_FromFile=false;

static Vector St_jesp7 = new Vector(); // to Store JESP7 handle

static int St_current_jesp7_index = 0; // to Store The current JESP7 index in St_jesp7

static BufferedReader St_System_In;

static JESP7_exception St_jesp7_exception;

/**************************/

public static void main (String args[])

/***************************------------------------------------------------------------------*/

/* This is the main entry point of the Monitor_JESP7 class : */

/*------------------------------------------------------------------*/

{

String S_Input_Message;

String S_FileName="";

boolean S_end;

try

{

System.out.println("************************************");

System.out.println("*** Welcome to the JESP7 Monitor ***");

System.out.println("************************************");

System.out.println(">>> Java/PURE - " + JESP7.Version());

if (args.length > 0)

{// Command from the file :

// ---------------------

S_FileName = args[0];

try

{

St_System_In = new BufferedReader(new FileReader(S_FileName));

System.out.println(">>> All command are taken from the file : " + S_FileName);

St_FromFile = true;

St_echo = true;

}

catch (FileNotFoundException e)

{

System.out.println("*** Exception in Monitor_JESP7 (main) : FileNotFoundException : " +

e.toString());

return;

}

}

else


3-36 47 A2 93US Rev01

{// Command from the System.in :

// --------------------------

St_System_In = new BufferedReader(new InputStreamReader(System.in));

System.out.println(">>> Enter the command. Type ’help’ to list all available commands.");

}

S_end = Input_Message_Processing("New");

do {

if (! St_FromFile) System.out.print(">: ");

S_Input_Message = St_System_In.readLine();

if (S_Input_Message == null) S_Input_Message = "quit";

S_Input_Message = S_Input_Message.trim();

if (St_echo) System.out.println("+: " + S_Input_Message);

S_end = Input_Message_Processing(S_Input_Message);

}

while (! S_end);

}

catch(Exception e)

{

System.out.println("*** Exception in Monitor_JESP7 (main) : " + e.toString());

e.printStackTrace();

}

System.out.println("<<< JESP7 Monitor Terminated.");

}


47 A2 93US Rev01 3-37

/**************************/

private static boolean Input_Message_Processing (String p_Input_Message)

/***************************-----------------------------------------------------------------------*/

/* This private method is called to process the Input message : */

/* Dispatch to the appropriate processing and call the specific JESP7 method : */

/* This function returns : */

/* - False : if another command line must be read from the flow of the command */

/* - True : if the command flow must be stopped */

/*-------------------------------------------------------------------------------*/

{

String w_command;

String w_param;

String w_keyword;

String w_keyvalue;

String w_Procedure_Name;

String w_Parameter_List;

String w_GetProcedureInfo;

int w_rc;

int w_idx;

int w_current_jesp7_index;

long w_NumberOfFields;

long w_NumberOfRows;

long w_RowIndex;

long w_FieldIndex;

long w_NbRow;

long w_NbField;

long w_CurRow;;

long w_CurField;

long w_FirstField;

long w_LastRow;

long w_LastField;

JESP7 w_jesp7;

GetFieldInfo_out w_GetFieldInfo_out;

Object w_Object;

w_idx = p_Input_Message.indexOf(" ");

if (w_idx == -1)

{

w_idx = p_Input_Message.length();

w_param = "";

}

else

{

w_param = p_Input_Message.substring(w_idx);

w_param = w_param.trim();

}

w_command = p_Input_Message.substring(0, w_idx);

w_command = w_command.toLowerCase();


3-38 47 A2 93US Rev01

/*-----------------------------------------------------------------------*/

/* COMMENT command : */

/*-----------------------------------------------------------------------*/

/* Syntax : {Comment | /* | //} */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("comment") == 0) ||

((w_command.length() > 1) && ((w_command.substring(0,2).compareTo("/*") == 0) ||

(w_command.substring(0,2).compareTo("//") == 0))))

{

return false;

}

/*-----------------------------------------------------------------------*/

/* END command : */

/*-----------------------------------------------------------------------*/

/* Syntax : {End | Quit | /} */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("end") == 0) ||

(w_command.compareTo("quit") == 0) ||

(w_command.compareTo("/") == 0))

{

return true;

}

/*-----------------------------------------------------------------------*/

/* HELP command : */

/*-----------------------------------------------------------------------*/

/* Syntax : Help [<Command-Name>] */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("help") == 0) || (w_command.compareTo("?") == 0))

{

w_param = w_param.toLowerCase();

if (w_param.compareTo("") == 0)

{

System.out.println(".. Commands are :");

System.out.println(".. ------------");

}

if ((w_param.compareTo("comment") == 0) ||

(w_param.compareTo("/*") == 0) ||

(w_param.compareTo("//") == 0) ||

(w_param.compareTo("") == 0))

{

System.out.println(".. Comment :: To insert a comment in the input command flow of the

JESP7 Monitor");

System.out.println(".. (abbrev ’/*’ or ’//’)");

}


47 A2 93US Rev01 3-39

if ((w_param.compareTo("connect") == 0) ||

(w_param.compareTo("cn") == 0) ||


{

System.out.println(".. Connect {Node=<Node> | Host=<Host> [Port=<Port>] Gcos=<Gcos> Mailbox=<Mailbox>

User=<User> ");

System.out.println(".. Password=<Password> [Project=<Project>] [Billing=<Billing>]

[TermId=<TermId>] [Trace=<Trace>]}");

System.out.println(".. :: To connect a specified user to TDS (abbrev : cn)");

}

if ((w_param.compareTo("disconnect") == 0) ||

(w_param.compareTo("ds") == 0) ||


{

System.out.println(".. Disconnect :: To disconnect a specified user from TDS (abbrev :

ds)");

}

if ((w_param.compareTo("echo") == 0) ||


{

System.out.println(".. echo [on | off] :: To trace input comand line (default is on).");

}

if ((w_param.compareTo("end") == 0) ||

(w_param.compareTo("quit") == 0) ||

(w_param.compareTo("/") == 0) ||


{

System.out.println(".. end :: To end the Monitor_JESP7 (abbrev quit or ’/’)");

}

if ((w_param.compareTo("executeprocedure") == 0) ||

(w_param.compareTo("execute") == 0) ||

(w_param.compareTo("ex") == 0) ||


{

System.out.println(".. ExecuteProcedure <Procedure-Name> [<Parameter-List>]");

System.out.println(".. :: To execute the transaction <Procedure-Name> with ");

System.out.println(".. the optional <Parameter-List> (abbrev : execute or

ex)");

}

if ((w_param.compareTo("getdata") == 0) ||

(w_param.compareTo("gd") == 0) ||


{

System.out.println(".. GetData <Procedure-Name> [<RowIndex> [<FieldIndex>]]");

System.out.println(".. :: To get the Data of the executed <Procedure-Name>");

System.out.println(".. located on <RowIndex> and <FieldIndex>");

System.out.println(".. If an Index is missing then get all the set of the

missing Index");


3-40 47 A2 93US Rev01

System.out.println(".. (abbrev : gd)");

}

if ((w_param.compareTo("getfieldinfo") == 0) ||

(w_param.compareTo("gfi") == 0) ||


{

System.out.println(".. GetFieldInfo <Procedure-Name> [<Field-Index>]");

System.out.println(".. :: To get the Name, Type, and Length of the specified field

<Field-Index>");

System.out.println(".. of the <Procedure-Name> (abbrev : gfi)");

}

if ((w_param.compareTo("getprocedureinfo") == 0) ||

(w_param.compareTo("gpi") == 0) ||


{

System.out.println(".. GetProcedureInfo <Procedure-Name>");

System.out.println(".. :: To get the String of prototype call of the <Procedure-

Name> (abbrev : gpi)");

}

if ((w_param.compareTo("help") == 0) ||

(w_param.compareTo("?") == 0) ||


{

System.out.println(".. help [<command-name>] :: To get help about all command or a specific one.

(abbrev ’?’)");

}

if ((w_param.compareTo("keyboard") == 0) ||


{

System.out.println(".. keyboard :: To switch input command flow on keyboard.");

}

if ((w_param.compareTo("new") == 0) ||


{

System.out.println(".. new :: To create a new handle of JESP7.");

System.out.println(" The returned number is take as the current JESP7

index.");

}

if ((w_param.compareTo("numberoffields") == 0) ||

(w_param.compareTo("nbf") == 0) ||


{

System.out.println(".. NumberOfFields <Procedure-Name>");

System.out.println(".. :: To get the NumberOfFields of <Procedure-Name> (abbrev :

nbf)");

}


47 A2 93US Rev01 3-41

if ((w_param.compareTo("numberofrows") == 0) ||

(w_param.compareTo("nbr") == 0) ||


{

System.out.println(".. NumberOfRows <Procedure-Name>");

System.out.println(".. :: To get the NumberOfRows of <Procedure-Name> (abbrev :

nbr)");

}

if ((w_param.compareTo("print") == 0) ||


{

System.out.println(".. print [<JESP7_index>] :: To print the JESP7 class referenced by the

<JESP7_index> integer.");

System.out.println(".. If <JESP7_index> integer is missing then the current

one is taken. (abbrev p)");

}

if ((w_param.compareTo("put") == 0) ||


{

System.out.println(".. put [Node=<Node>] [Host=<Host> [Port=<Port>] [Gcos=<Gcos> [Mailbox=<Mailbox>]

[User=<User>]");

System.out.println(".. [Password=<Password>] [Project=<Project>] [Billing=<Billing>]

[TermId=<TermId>] [Trace=<Trace>]");

System.out.println(".. [AllowLossOfPrecision=<AllowLossOfPrecision>]");

System.out.println(".. :: To put the specific value into a specified JESP7 class

member");

}

if ((w_param.compareTo("set") == 0) ||


{

System.out.println(".. set <JESP7_index> :: To define the current JESP7 index as the <JESP7_index>

integer.");

}

return false;

}

/*-----------------------------------------------------------------------*/

/* ECHO command : */

/*-----------------------------------------------------------------------*/

/* Syntax : Echo [on | off] */

/*-----------------------------------------------------------------------*/

if (w_command.compareTo("echo") == 0)

{

St_echo = (w_param.toLowerCase().compareTo("off") != 0);

return false;

}


3-42 47 A2 93US Rev01

/*-----------------------------------------------------------------------*/

/* NEW command : */

/*-----------------------------------------------------------------------*/

/* Syntax : New */

/*-----------------------------------------------------------------------*/

if (w_command.compareTo("new") == 0)

{

St_jesp7.addElement(new JESP7());

St_current_jesp7_index = St_jesp7.size() - 1;

System.out.println(">> new : The JESP7 index is " + St_current_jesp7_index);

return false;

}

/*-----------------------------------------------------------------------*/

/* SET command : */

/*-----------------------------------------------------------------------*/

/* Syntax : Set <JESP7 Index Integer> */

/*-----------------------------------------------------------------------*/

if (w_command.compareTo("set") == 0)

{

try

{

w_current_jesp7_index = Integer.parseInt(w_param);

if ((w_current_jesp7_index < 0) || (w_current_jesp7_index >= St_jesp7.size()))

{

System.out.println("--set : Invalid JESP7 index : " + w_current_jesp7_index +

" is Out Of Bound [0," + (St_jesp7.size()-1) + "] !");

}

else

{

St_current_jesp7_index = w_current_jesp7_index;

System.out.println(">> set : The current JESP7 index is " + St_current_jesp7_index);

}

}

catch (NumberFormatException e)

{

System.out.println("--set : Invalid JESP index : " + e.toString());

}

return false;

}


47 A2 93US Rev01 3-43

/*-----------------------------------------------------------------------*/

/* PRINT command : */

/*-----------------------------------------------------------------------*/

/* Syntax : Print [JESP7_index] */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("print") == 0) || (w_command.compareTo("p") == 0))

{

try

{


{

w_current_jesp7_index = St_current_jesp7_index;

}

else

{

w_current_jesp7_index = Integer.parseInt(w_param);

}

if ((w_current_jesp7_index < 0) || (w_current_jesp7_index >= St_jesp7.size()))

{

System.out.println("--print : Invalid JESP index : " + w_current_jesp7_index +

" is Out Of Bound [0," + (St_jesp7.size()-1) + "] !");

}

else

{

((JESP7) St_jesp7.elementAt(w_current_jesp7_index)).Print();

}

}


{

System.out.println("--print : Invalid JESP index : " + e.toString());

}

return false;

}

/*-------------------------------------------------------------------------------------------------*/

/* PUT command : To put specific values into a specified JESP7 class member */

/*-------------------------------------------------------------------------------------------------*/

/* Syntax : put [Node=<String>] [Host=<String> [Port=<int>] [Gcos=<String> [Mailbox=<String>] */

/* [User=<String>] [Password=<String>] [Project=<String>] [Billing=<String>] */

/* [TermId=<String>] [Trace=<boolean>] [AllowLossOfPrecision=<boolean>] */

/* [UseRemoteProcedureFile=<boolean>] [Path=<String>] */

/* [CryptPassword=<boolean>] [TBLFile=<String>] [ConnectTimeout=<int>] */

/* [DialogTimeout=<int>] [TDSPrompt=<String>] */

/*-------------------------------------------------------------------------------------------------*/

if (w_command.compareTo("put") == 0)

{

w_jesp7 = (JESP7) St_jesp7.elementAt(St_current_jesp7_index);

w_param = w_param + " ";


3-44 47 A2 93US Rev01

w_idx = w_param.indexOf("=");

while (w_idx > 0)

{

w_keyword = w_param.substring(0, w_idx);

w_keyword = w_keyword.toLowerCase();

w_param = w_param.substring(w_idx+1);

w_idx = w_param.indexOf(" ");

w_keyvalue = w_param.substring(0, w_idx);


w_param = w_param.trim() + " ";


// System.out.println(">> put : keyword=" + w_keyword + ", keyvalue=" + w_keyvalue);

if (w_keyword.compareTo("node") == 0) w_jesp7.Node = w_keyvalue;

else if (w_keyword.compareTo("host") == 0) w_jesp7.Host = w_keyvalue;

else if (w_keyword.compareTo("port") == 0) w_jesp7.Port = w_keyvalue;

else if (w_keyword.compareTo("gcos") == 0) w_jesp7.GCOS = w_keyvalue;

else if (w_keyword.compareTo("mailbox") == 0) w_jesp7.Mailbox = w_keyvalue;

else if (w_keyword.compareTo("user") == 0) w_jesp7.User = w_keyvalue;

else if (w_keyword.compareTo("password") == 0) w_jesp7.Password = w_keyvalue;

else if (w_keyword.compareTo("project") == 0) w_jesp7.Project = w_keyvalue;

else if (w_keyword.compareTo("billing") == 0) w_jesp7.Billing = w_keyvalue;

else if (w_keyword.compareTo("termid") == 0) w_jesp7.TermId = w_keyvalue;

else if (w_keyword.compareTo("trace") == 0) JESP7.Trace =

(new Boolean(w_keyvalue)).booleanValue();

else if (w_keyword.compareTo("tracepwd") == 0) JESP7.Trace_Pwd =


else if (w_keyword.compareTo("cryptpassword") == 0) w_jesp7.CryptPassword =


else if (w_keyword.compareTo("tblfile") == 0) w_jesp7.TBLFile = w_keyvalue;

else if (w_keyword.compareTo("connecttimeout") == 0) w_jesp7.ConnectTimeout =

(new Integer(w_keyvalue)).intValue();

else if (w_keyword.compareTo("dialogtimeout") == 0) w_jesp7.DialogTimeout =

(new Integer(w_keyvalue)).intValue();

else if (w_keyword.compareTo("tdsprompt") == 0) w_jesp7.TDSPrompt = w_keyvalue;

else if (w_keyword.compareTo("path") == 0) w_jesp7.Path = w_keyvalue;

else if (w_keyword.compareTo("allowlossofprecision") == 0) w_jesp7.AllowLossOfPrecision =


else if (w_keyword.compareTo("useremoteprocedurefile") == 0) w_jesp7.UseRemoteProcedureFile =


else System.out.println("--put : invalid keyword : " + w_keyword);

}

return false;

}


47 A2 93US Rev01 3-45

/*-----------------------------------------------------------------------*/

/* KEYBOARD command : */

/*-----------------------------------------------------------------------*/

/* Syntax : Keyboard */

/*-----------------------------------------------------------------------*/

if (w_command.compareTo("keyboard") == 0)

{

if (St_FromFile)

{

System.out.println(">> keyboard : return to the keyboard input.");

St_System_In = new BufferedReader(new InputStreamReader(System.in));

St_FromFile = false;

St_echo = false;

}

else

{

System.out.println(">> keyboard : you are already in keyboard input !");

}

return false;

}

/*--------------------------------------------------------------------------------------------*/

/* CONNECT command : */

/*--------------------------------------------------------------------------------------------*/

/* Syntax : connect {Node=<Node> | Host=<Host> [Port=<Port>] Gcos=<Gcos> Mailbox=<Mailbox> */

/* User=<User> Password=<Password> [Project=<Project>] [Billing=<Billing>] */

/* [TermId=<TermId>] [Trace=<Trace>]} */

/*--------------------------------------------------------------------------------------------*/

if ((w_command.compareTo("connect") == 0) || (w_command.compareTo("cn") == 0))

{


w_param = w_param + " ";


while (w_idx > 0)

{

w_keyword = w_param.substring(0, w_idx);

w_keyword = w_keyword.toLowerCase();



w_keyvalue = w_param.substring(0, w_idx);


w_param = w_param.trim() + " ";


// System.out.println(">> Connect : keyword=" + w_keyword + ", keyvalue=" + w_keyvalue);


3-46 47 A2 93US Rev01

if (w_keyword.compareTo("node") == 0) w_jesp7.Node = w_keyvalue;

else if (w_keyword.compareTo("host") == 0) w_jesp7.Host = w_keyvalue;

else if (w_keyword.compareTo("port") == 0) w_jesp7.Port = w_keyvalue;

else if (w_keyword.compareTo("gcos") == 0) w_jesp7.GCOS = w_keyvalue;

else if (w_keyword.compareTo("mailbox") == 0) w_jesp7.Mailbox = w_keyvalue;

else if (w_keyword.compareTo("user") == 0) w_jesp7.User = w_keyvalue;

else if (w_keyword.compareTo("password") == 0) w_jesp7.Password = w_keyvalue;

else if (w_keyword.compareTo("project") == 0) w_jesp7.Project = w_keyvalue;

else if (w_keyword.compareTo("billing") == 0) w_jesp7.Billing = w_keyvalue;

else if (w_keyword.compareTo("termid") == 0) w_jesp7.TermId = w_keyvalue;

else if (w_keyword.compareTo("trace") == 0) w_jesp7.Trace =


}

try

{

w_jesp7.Connect();

System.out.println(">>> Monitor_JESP7 : Connect returns : " + w_rc);

}

catch (DSAexception e)

{

System.out.println("*** Monitor_JESP7 : DSAexception : " + e.toString());


}

catch (JESP7_exception e)

{

System.out.println("*** Monitor_JESP7 : JESP7_exception : " + e.toString());


}

return false;

}

/*-----------------------------------------------------------------------*/

/* DISCONNECT command : */

/*-----------------------------------------------------------------------*/

/* Syntax : Disconnect */

/*-----------------------------------------------------------------------*

if ((w_command.compareTo("disconnect") == 0) || (w_command.compareTo("ds") == 0))

{


try

{

w_jesp7.Disconnect();

System.out.println(">>> Monitor_JESP7 : Disconnect OK");

}

catch (DSAexception e)

{

System.out.println("*** Monitor_JESP7 : DSAexception : " + e.toString());


}

return false;

}


47 A2 93US Rev01 3-47

/*-----------------------------------------------------------------------*/

/* ExecuteProcedure command : */

/*-----------------------------------------------------------------------*/

/* Syntax : ExecuteProcedure <Procedure-Name> [<Parameter-List>] */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("executeprocedure") == 0) ||

(w_command.compareTo("execute") == 0) ||

(w_command.compareTo("ex") == 0))

{



{System.out.println

("--ExecuteProcedure : <Procedure-Name> is missing ! (This parameter is mandatory)");

return false;

}


if (w_idx < 0)

{

w_idx = w_param.length();

}

w_Procedure_Name = w_param.substring(0, w_idx);



w_Parameter_List = w_param;

try

{

w_jesp7.ExecuteProcedure(w_Procedure_Name, w_Parameter_List);

}


{System.out.println("*** Monitor_JESP7 : JESP7_Exception in ExecuteProcedure : err=" +

e.JESP7_error + ", msg=" + e.JESP7_error_message);

if (e.JESP7_error == St_jesp7_exception.ESP_ERR_TDS_DATA_MSG)

{System.out.println("+++ Monitor_JESP7 : TDS MESSAGE : MsgType=" + e.JESP7_MsgType +

", MsgStatus=" + e.JESP7_MsgStatus +

", Procedure=" + e.JESP7_Procedure +

", Message=" + e.JESP7_Message);

}

if (e.JESP7_error == St_jesp7_exception.ESP_ERR_ABORTEDPROCEDURE)

{System.out.println("*** Monitor_JESP7 : TDS ERROR : MsgType=" + e.JESP7_MsgType +

", MsgStatus=" + e.JESP7_MsgStatus +

", Procedure=" + e.JESP7_Procedure +

", Message=" + e.JESP7_Message);

}

}

catch (DSAexception e1)

{

System.out.println("*** Monitor_JESP7 : DSAexception in ExecuteProcedure : " + e1.toString());

}

return false;

}


3-48 47 A2 93US Rev01

/*-----------------------------------------------------------------------*/

/* NumberOfFields command : */

/*-----------------------------------------------------------------------*/

/* Syntax : NumberOfFields <Procedure-Name> */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("numberoffields") == 0) ||

(w_command.compareTo("nbf") == 0))

{



{

System.out.println(

"--NumberOfFields : <Procedure-Name> is missing ! (This parameter is mandatory)");

return false;

}

w_Procedure_Name = w_param;

try

{

w_NumberOfFields = w_jesp7.NumberOfFields (w_Procedure_Name);

System.out.println(">>> Monitor_JESP7 : NumberOfFields Procedure_Name="+

w_Procedure_Name + " returns : " + w_NumberOfFields);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in NumberOfFields : err=" +


}

return false;

}


47 A2 93US Rev01 3-49

/*-----------------------------------------------------------------------*/

/* NumberOfRows command : */

/*-----------------------------------------------------------------------*/

/* Syntax : NumberOfRows <Procedure-Name> */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("numberofrows") == 0) ||

(w_command.compareTo("nbr") == 0))

{



{

System.out.println("--NumberOfRows : <Procedure-Name> is missing ! (This parameter is mandatory)");

return false;

}


try

{

w_NumberOfRows = w_jesp7.NumberOfRows(w_Procedure_Name);

System.out.println(">>> Monitor_JESP7 : NumberOfRows Procedure_Name="+ w_Procedure_Name +

" returns : " + w_NumberOfRows);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in NumberOfFields : err=" + e.JESP7_error +

", msg=" + e.JESP7_error_message);

}

return false;

}


3-50 47 A2 93US Rev01

/*-----------------------------------------------------------------------*/

/* GetFieldInfo command : */

/*-----------------------------------------------------------------------*/

/* Syntax : GetFieldInfo <Procedure-Name> [<Field-Index>] */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("getfieldinfo") == 0) ||

(w_command.compareTo("gfi") == 0))

{



{

System.out.println("--GetFieldInfo : <Procedure-Name> is missing ! (This parameter is mandatory)");

return false;

}


if (w_idx < 0)

{

/*------------------------------------------------------*/

/* <Field-Index> is missing : all fields are requested :*/

/*------------------------------------------------------*/


w_FieldIndex = -1;

w_CurField = 0;

try

{

w_NbField = w_jesp7.NumberOfFields (w_Procedure_Name);

System.out.println(">>> Monitor_JESP7 : GetFieldInfo/NumberOfFields Procedure_Name=" +

w_Procedure_Name + " returns : " + w_NbField);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in GetFieldInfo/NumberOfFields : err=" +


return false;

}

}

else

{

/*------------------------------------------------------*/

/* <Field-Index> is specified : */

/*------------------------------------------------------*/




try

{

w_FieldIndex = Long.parseLong(w_param);


47 A2 93US Rev01 3-51

w_NbField = 1;

w_CurField = w_FieldIndex;

}


{

System.out.println("--GetFieldInfo : Invalid Field Index : " + e.toString());

return false;

}

}

/*------------------------------------------------------*/

/* Retrieve FieldInfo for the specified FieldIndex : */

/*------------------------------------------------------*/

w_LastField = w_CurField + w_NbField;

for (; w_CurField < w_LastField; w_CurField++)

{

try

{

w_GetFieldInfo_out = w_jesp7.GetFieldInfo(w_Procedure_Name, w_CurField);

System.out.println(">>> Monitor_JESP7 : GetFieldInfo Procedure_Name="+ w_Procedure_Name +

", FieldIndex=" + w_CurField +

", returns : Name=" + w_GetFieldInfo_out.Name +

", Type=" + w_GetFieldInfo_out.Type +

", Length=" + w_GetFieldInfo_out.Length);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in GetFieldInfo : err=" + e.JESP7_error +


}

}

return false;

}


3-52 47 A2 93US Rev01

/*-----------------------------------------------------------------------*/

/* GetProcedureInfo command : */

/*-----------------------------------------------------------------------*/

/* Syntax : GetProcedureInfo <Procedure-Name> */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("getprocedureinfo") == 0) ||

(w_command.compareTo("gpi") == 0))

{



{

System.out.println(

"--GetProcedureInfo : <Procedure-Name> is missing ! (This parameter is mandatory)");

return false;

}


try

{

w_GetProcedureInfo = w_jesp7.GetProcedureInfo(w_Procedure_Name);

System.out.println(">>> Monitor_JESP7 : GetProcedureInfo Procedure_Name="+ w_Procedure_Name +

" returns : " + w_GetProcedureInfo);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in GetProcedureInfo : err=" +


}

return false;

}

/*-----------------------------------------------------------------------*/

/* GetData command : */

/*-----------------------------------------------------------------------*/

/* Syntax : GetData <Procedure-Name> [<RowIndex> [<FieldIndex>]] */

/*-----------------------------------------------------------------------*/

if ((w_command.compareTo("getdata") == 0) ||

(w_command.compareTo("gd") == 0))

{


w_RowIndex = 0;

w_FieldIndex = 0;

/*--------------------------------*/

/* Get <Procedure-Name> : */

/*--------------------------------*/



47 A2 93US Rev01 3-53

{

System.out.println("--GetData : <Procedure-Name> is missing ! (This parameter is mandatory)");

return false;

}


if (w_idx < 0)

{


w_RowIndex = -1; // Means all Rows

w_FieldIndex = -1; // Means all Fields

}


/*--------------------------------*/

/* Get <RowIndex> : */

/*--------------------------------*/

if (w_RowIndex == 0)

{




if (w_idx < 0)

{


w_FieldIndex = -1; // Means all Fields

}

try

{

w_RowIndex = Long.parseLong(w_param.substring(0, w_idx));

}


{

System.out.println("--GetData : Invalid Row Index : " + e.toString());

return false;

}

}

/*--------------------------------*/

/* Get <FieldIndex> : */

/*--------------------------------*/

if (w_FieldIndex == 0)

{



try

{

w_FieldIndex = Long.parseLong(w_param);


3-54 47 A2 93US Rev01

}


{

System.out.println("--GetData : Invalid Field Index : " + e.toString());

return false;

}

}

/*--------------------------------*/

/* Compute NbRow, CurRow : */

/*--------------------------------*/

if (w_RowIndex == -1) // Means all Rows

{

w_CurRow = 0;

try

{

w_NbRow = w_jesp7.NumberOfRows(w_Procedure_Name);

System.out.println(">>> Monitor_JESP7 : GetData/NumberOfRows Procedure_Name="+ w_Procedure_Name +

" returns : " + w_NbRow);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in GetData/NumberOfRows : err=" +


return false;

}

}

else

{

w_CurRow = w_RowIndex;

w_NbRow = 1;

}

/*--------------------------------*/

/* Compute NbField, CurField : */

/*--------------------------------*/

if (w_FieldIndex == -1) // Means all Fields

{

w_CurField = 0;

try

{

w_NbField = w_jesp7.NumberOfFields (w_Procedure_Name);

System.out.println(">>> Monitor_JESP7 : GetData/NumberOfFields Procedure_Name="+

w_Procedure_Name + " returns : " + w_NbField);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in GetData/NumberOfFields : err="

+ e.JESP7_error + ", msg=" + e.JESP7_error_message);


47 A2 93US Rev01 3-55

return false;

}

}

else

{

w_CurField = w_FieldIndex;

w_NbField = 1;

}

/*--------------------------------*/

/* Retrieve all Data requested : */

/*--------------------------------*/

w_LastRow = w_CurRow + w_NbRow;

w_LastField = w_CurField + w_NbField;

w_FirstField = w_CurField;

for (; w_CurRow < w_LastRow; w_CurRow++)

{

for (w_CurField = w_FirstField; w_CurField < w_LastField; w_CurField++)

{

try

{

w_Object = w_jesp7.GetData (w_Procedure_Name, w_CurRow, w_CurField);

System.out.println(">>> Monitor_JESP7 : GetData Procedure=" + w_Procedure_Name +

", Row=" + w_CurRow + ", Field=" + w_CurField + ", Value=" + w_Object);

}


{

System.out.println("*** Monitor_JESP7 : JESP7_Exception in GetData : err=" + e.JESP7_error +


}

}

}

return false;

}

/*-----------------------------------------------------------------------*/

/* OTHER : */

/*-----------------------------------------------------------------------*/

if (w_command.compareTo("") != 0) System.out.println("--Unknown Command : ’" + w_command + "’ !");

return false;

}

} //end of JESP7 Monitor class


3-56 47 A2 93US Rev01

3.7� Dialog Descriptions

3.7.1� Invoking JESP 7 TPRs

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

The JESP 7 product converts the procedure call into the proper TDS format. Fordetails, see the �� *��+��.

3.7.2� Returning Data

JESP 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 JESP7 class to the applicationprogram.


47 A2 93US Rev01 3-57

3.8� File and Data Formats

3.8.1� Data Types

Data exists on both the client and server sides of the network.

• Input data is sent by the client to be used to form a JESP7 command line (instring format) as input to the Execute Procedure method.Execute Procedure converts the string into the structure expected by the TPRswhich are define in COBOL language.The command line sent to TDS is formed by the name of the transactionfollowed by the structure (in binary mode) expected by the transaction.These parameters are converted according to the description of the parametersdefined in the parameters file.

In turn,

Output data can be sent back to the Execute Procedure which waiting the reply.Then, Execute Procedure convert the TPR 's data output structure into datarows.

TPRs can process a variety of data types including:

Integerssmall integersdecimal (signed or unsigned, packed or unpacked)double precision floating point numberscharactervariable length character – varchar (on output only)

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

long integersshort integerscharacterdouble precision floating pointBigDecimal

The Execute Procedure method defined in the JESP 7 class automatically convertsthe data (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 a result of aSELECT statement. Since the client side software is oriented towards SQL, theSQLDA suits the client's needs for returning data as well.


3-58 47 A2 93US Rev01

The SQLDA must be contained in one message with a JESP 7 header indicating amessage of type 3 followed by the SQLDA. This complete message must be sentto the gateway without EGI indicator : keep the turn to send the data.

3.8.1.1 Server/TDS Data Types

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

The TYPE field contains the datatype field of an SQLDA. The LENGTH is thenumber of bytes the data type will occupy. The LENGTH for the CHAR andVARCHAR types is the maximum number of characters. The LENGTH of aVARCHAR includes the two bytes which give the length of the message data.

TDS TPRs using JESP 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.

��> ��@��1��

!�� '� ��

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

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

Smallint 2 16-bit two's complement binary, e.g.COBOL COMP-1C short

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

Decimal Len COBOL PIC [S]9(n)[V9(m)] [USAGE COMP].

Varchar Len Two part data type:1. 16 bit binary count of the number of bytes tofollow2. Character data


47 A2 93US Rev01 3-59

3.8.1.2 Conversion

��> $��

��@��1�� ;��1��

COMP-2 integer (32 bit) Integer (32 bit)

COMP-1 small integer (16 bit) Short integer (16 bit)

COMP-10floating double precision

Double precision

Decimal: PIC [S]9(n)V9(m)[USAGE COMP]

BigDecimal

Character <EBCDIC byte> String <char ASCII byte>

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

47 A2 93US Rev01 3-60

�

47 A2 93US Rev01 4-1

�4.�Configuration of JESP 7

4.1� Configuring TCP/IP

Edit the hosts file in the Java platform and (if they are not already included) addthe address of your computer and the host address.

4.2� Configuring the Initialization File

Note concerning TBLFile member in the JESP7 class: if not empty, this field givesthe name of the translation table file that will be used in all following connections.If the full path is not given, it is assumed to be the $HOME directory.The $HOME directory is retrieve from the System.getProperty("user.home")method. If the file type is not given, then «.tbx» is used. An example file, namedd011.tbx, is provided with the product and should fit the character set of WesternEuropean countries: the tables contained in this file perform translation betweenWindows (codepage 1252) and GCOS7 (PLW) Western European character sets. Italso handles translation of the Euro character.

Handling the Euro character is not simple, as its representation is different in Javaplatform and GCOS7 systems :

• For the Euro support in Java see :http://java.sun.com/products/jdk/1.1/docs/guide/intl/euro.html

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

See Annex B : Translation Table Utility.


4-2 47 A2 93US Rev01

4.3� Configuring Connection Parameters

This file is produced on PC with the dsncnfg.exe utility. After its execution, the�� file produced must be moved into the Java platform in the directoryindicated by the field Path of the JESP7 class.

Click on the DSNCnfg icon.

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

Choose Product type ESP7NGEN.

Create a new virtual node (connection parameters identifier).

Configuration of JESP 7

47 A2 93US Rev01 4-3

Enter the parameters.

User name name used for the TDS connection.

Password Password used for the TDS connection.

Host name name of the Gateway.

Port num Port used by the Gateway.

GCOS GCOS name.

Mailbox Name of the Mailbox where the TDS is connected.

Project name (optional) Project name used for the TDS connection.The default Project is taken if it is empty.

Billing name (optional) Billing name used for the TDS connection.The default Billing is taken if it is empty.


4-4 47 A2 93US Rev01

Terminal ID Name given by the user.The default value is the Java Platform name used atconnection time.

Trace YES (tracing) or NO (no tracing).The trace file name used by the Gateway 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).

Two options are possible:

��Open7 to specify the Gateway procedure declarationfile (if omitted, the file located on the Java Platform isused)

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

Validate this grid (return to the previous grid).

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 TDSPrompt member in JESP7 class is useful when a prompt other than thedefault (READY) is used by the TDS application. In all cases at connection time,the Gateway passes the first 70 characters of the message(s) received from TDS toJESP 7. If the message(s) are less than 70 characters long, the Gateway pads withbinary zeroes. Thus JESP 7 always receives 70 characters in response to aconnection request. If these 70 characters contain the specified TDS prompt (notnecessarily at the start of the message(s)), then JESP 7 considers that theconnection is valid. Otherwise, JESP 7 considers that the connection is invalid andreturns an error to the client application program. Note that the client applicationdoes not receive the 70 characters returned via TDS/Gateway.


47 A2 93US Rev01 4-5

4.4� Debugging Facilities

In the event of any anomaly when using JESP7, it is important to supply thecontent of the trace file for analysis.

4.4.1� Trace Files on OPEN 7

A dynamic trace file may be obtained on OPEN 7. Dynamic trace files arerequested at connection time using the Trace parameter of JESP 7 Connect. Thetrace file is filled until disconnect time (JESP 7 Disconnect). The trace file is foundin the directory:

/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 JESP 7, it is important to supply thecontent of the trace file for analysis.


4-6 47 A2 93US Rev01

4.4.2� Trace Files on NT partition

A trace file may be obtained on the DPS 7000 XTA server. Dynamic trace files arerequested at connection time using the trace parameter of JESP7 Connect method.The trace file is filled until disconnect time (JESP7 Disconnect). The trace file isfound in the directory:

<�� >\NTGW_<��>\<��> where:

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

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

<TermId> is the Terminal ID parameter value if it is not empty,or the TCP/IP host name of the client of the Java Platform if it can be computed,or the TCP/IP address of the client of the Java Platform

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

4.4.3� 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 if at OPEN 7installation time this value has not been changed.

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

��

It may be re-started using the command:

�� (with or without parameters (see below)).


47 A2 93US Rev01 4-7

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

��

The optional parameters have the following significance:

�

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.

��

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)

��

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

��

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.


4-8 47 A2 93US Rev01

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.

4.4.4� Execution of the NT 7 Gateway Modules

The NT7GW gateway is automatically started when required by the SystemApplication Manager, based on the start information stored for the product atinstallation time (a set of default parameter values). These parameter values may bechanged at execution time.

The following options are available for execution of the NT7GW gateway:

-p <port number for NT7GW> (9002by default)

-d <global trace level> (0 by default)

0 no tracing

1 tracing of connections / disconnections

2 tracing of VCAM /ATMI error messages

3 tracing of all messages (up to 96 bytes per message)

4 internal tracing

(for further information about NT7GW trace, see paragraph 3.3.4)

-m <number of connections per thread> (default 10, maximum 30)

-s <number of server threads> (default 10, maximum 50)

-f <ASCII<->EBCDIC translation file> (D011 modified for Euro support bydefault)

-t <maximum size of all trace/log files> used to limit the log file size10,000 bytes (minimum and defaultsize)1,000,000 bytes (maximum size)


47 A2 93US Rev01 4-9

4.5� Security

4.5.1� Password Encryption

Following the option, the password is encrypted in JESP 7 and decrypted in theGateway on the GCOS 7 side.

If the password comes from cnfgdsn.cfg file (virtual node description), then thepassword is encrypted inside the file but the final encrypted password is not thesame one.

Note that the password is decrypted locally on the machine, but never set, throughthe network, in a readable state.

47 A2 93US Rev01 4-10

�

47 A2 93US Rev01 5-1

�5.�Configurability

5.1� JESP 7 Connections

A connection is defined by the following parameters:

GCOS7 user name,

GCOS7 password,

TDS mailbox,

GCOS7 project,

GCOS7 billing and

terminal identifier.

The same application or several applications �� the same connection atthe same time to execute transactions. This constraint about connections is set bythe JTDS ones.

5.2� JESP 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.

The maximum length of a decimal number is limited to 31 digits on GCOS 7.

47 A2 93US Rev01 5-2

�

47 A2 93US Rev01 6-1

�6.�Administration Tool for JESP 7

6.1� Overview

All JESP 7 procedures (or transaction names) that are triggered from a Javaplatform must first be registered in a procedure declaration file. This file may be:

<hostname>.pr1 situated locally on the Java platform (defaultconfiguration option).Note that, in this case, this file must be moved fromthe PC to the Java platform.

/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 Chapter 4 section 4.3 �� ).

When a local procedure declaration file is chosen (more performant than a remotefile), no attempt is made by JESP 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 JESP 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 signalled.


6-2 47 A2 93US Rev01

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

��

Administration Tool for JESP 7

47 A2 93US Rev01 6-3

�� !��

TDSTransactions

NT7 Gateway

Host SiteFile

espconf.pr1

DPS 7 XTA

VCAM


6-4 47 A2 93US Rev01

6.2� Running the Administration Tool (Espadmpc)

Under Windows click on the ESPADMPC icon:

or, 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:

• "��#�� : A tree view of the procedures and the names of their parameters(input and output).

• $��#�� : A form view which displays and enables us to change thedefinition of selected procedure parameters.

• %��&��.

• %�� .


47 A2 93US Rev01 6-5

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:

'#��

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” command inthe “Edit” menu.

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

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

Select the parameter (or the “Input Parameters”or “Output Parameters” node for allparameters).

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

Select the procedure or parameter name node,and then select the “Cut”, “Copy” or “Delete”command in the “Edit” menu. (NOTE: the“Cut” operation is not available forprocedures).

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.


6-6 47 A2 93US Rev01

'#��

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 select 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 us to modify a parameter definition(its type, 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 as selecting the “New”command from the File menu.

6.2.4� The menus

The following menus are available:

�� Manage local procedure files

�� Manage the procedure registered in the host site file.

�� Manage the procedure and parameter nodes in theProcedure tree view.

(��) Hide/display the main toolbar/status bar

*��# Give product information


47 A2 93US Rev01 6-7

6.2.4.1 Menu commands

�� +�) Create a new procedure definition document

'#�� Open an existing procedure definition file

��,� Save the active procedure definition document

��,�� - Save the active procedure definition document with anew name

�.�� Quit the application

�� /�� 000�!��1)��+��2��)�345Connect to the specified host.The first dialog box that appears will ask for the DPS7000 XTA tcp/ip host name (or alias) and the portnumber of the Gateway.Authentication will be performed on the basis ofcurrent (interactive) Windows user name and domain.��000�1)��'#��2��)�345Connect to the specified host.The first dialog box that appears will ask for theOpen7 tcp/ip host name and the port number of theGateway.If the given information is valid, a second dialog boxwill ask for an Open7 user name and password toensure authentication.

�� Disconnect from the host previously connected

2��1 4- Transfer one specified procedure (or all procedures)definition from the host

��- Transfer (and possibly overwrites) the specifiedprocedure definition to the host

��- Delete the specified procedure definition on the host

�� /�� Cut selected parameter definition in the procedureview and send it to the Clipboard

/�#3 Copy selected parameter or procedure definition inthe procedure view and send it to the Clipboard

�� Insert procedure (or parameter) definition from theClipboard under the “Procedures” (or “Inputparameter” or ”Output parameter”) node in theprocedure view.

�� Delete a procedure or parameter definition in theprocedure view

6� �� Insert new procedure or parameter definition in theprocedure tree view


6-8 47 A2 93US Rev01

$�� Rename a procedure or parameter in the tree view

(��) ��&�� Show/hide the main toolbar

�� &�� Show/hide the status bar

*��# �&�� #��#�- Display program information, program number andcopyright

47 A2 93US Rev01 A-1

�A.�Migration Advice: ESP 7 � JESP 7

This section is intended to provide help in migrating from ESP 7 to JESP 7.

�� are required to the TDS transactions to be executed onGCOS7 because it is the same interface:A TDS designed for ESP 7 is also designed for JESP 7

The administrative files (.pr1, .cfg, .tbx) generated on PC must be moved into theJava platform without modification.

On the client side, the application must (naturally) be coded in Java.

JESP 7 on JavaPlatform

ESP 7 on PC

TDS on GCOS 7

��


A-2 47 A2 93US Rev01

�

47 A2 93US Rev01 B-1

�B.�Translation Table Utility

The tblpcgc.exe utility, activated on PC, allows the user to create and/or modify theset of translation tables to be used by the ESP7NGEN and JESP7 products for theconversion of characters:

1. From ASCII to EBCDIC (from Java platform to GCOS 7).

2. From EBCDIC to ASCII (from GCOS 7 to Java platform).

Note that the produced file (.tbx) must be moved into the Java Platform in thedirectory referenced by the Path variable defined in the JESP7 class.This Path is user-defined.

B.1� Java platform to GCOS 7 Translation Table


B-2 47 A2 93US Rev01

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.

B.2� Existing Tables

Note that the terminology "��" must be replaced by the "��".This utility is also used for ESP 7 product.

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.

Translation Table Utility

47 A2 93US Rev01 B-3

The tables are taken into account by :

JESP 7, specifying the TBLFile member in the JESP 7 class, or via the DSNCNFGutility (specification of –f <filename> in the field « other » or « divers »)

B.3� Default translation tables

These tables are taken if TBLfile field is empty .

C101 (GCOS 7) to standard ASCII (Java Platform) :

+-------------------------------------------------------------------------------+ | 00 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 0A | 0B | 0C | 0D | 0E | 0F | +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+ | 00 | 00 | 01 | 02 | 03 | 1A | 09 | 1A | 7F | 1A | 1A | 1A | 0B | 0C | 0D | 0E | 0F | | 10 | 10 | 11 | 12 | 13 | 1A | 1A | 08 | 1A | 18 | 19 | 1A | 1A | 1C | 1D | 1E | 1F | | 20 | 1A | 1A | 1A | 1A | 1A | 0A | 17 | 1B | 1A | 1A | 1A | 1A | 1A | 05 | 06 | 07 | | 30 | 1A | 1A | 16 | 1A | 1A | 1A | 1A | 04 | 1A | 1A | 1A | 1A | 14 | 15 | 1A | 1A | | 40 | 20 | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 5B | 2E | 3C | 28 | 2B | 21 | | 50 | 26 | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 5D | 24 | 2A | 29 | 3B | 5E | | 60 | 2D | 2F | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 2C | 25 | 5F | 3E | 3F | | 70 | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 60 | 3A | 23 | 40 | 27 | 3D | 22 | | 80 | 1A | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 1A | 1A | 1A | 1A | 1A | 1A | | 90 | 1A | 6A | 6B | 6C | 6D | 6E | 6F | 70 | 71 | 72 | 1A | 1A | 1A | 1A | 1A | 1A | | A0 | 1A | 7E | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 7A | 1A | 1A | 1A | 1A | 1A | 1A | | B0 | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 1A | 7C | 1A | 1A | 1A | 1A | | C0 | 7B | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 1A | 1A | 1A | 1A | 1A | 1A | | D0 | 7D | 4A | 4B | 4C | 4D | 4E | 4F | 50 | 51 | 52 | 1A | 1A | 1A | 1A | 1A | 1A | | E0 | 5C | 1A | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 5A | 1A | 1A | 1A | 1A | 1A | 1A | | F0 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 1A | 1A | 1A | 1A | 1A | FF | +------------------------------------------------------------------------------------+


B-4 47 A2 93US Rev01

Standard ASCII (Java Platform) to C101 (GCOS 7) :

+-------------------------------------------------------------------------------+ | 00 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 0A | 0B | 0C | 0D | 0E | 0F | +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+ | 00 | 00 | 01 | 02 | 03 | 37 | 2D | 2E | 2F | 16 | 05 | 25 | 0B | 0C | 0D | 0E | 0F | | 10 | 10 | 11 | 12 | 13 | 3C | 3D | 32 | 26 | 18 | 19 | 3F | 27 | 1C | 1D | 1E | 1F | | 20 | 40 | 4F | 7F | 7B | 5B | 6C | 50 | 7D | 4D | 5D | 5C | 4E | 6B | 60 | 4B | 61 | | 30 | F0 | F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | 7A | 5E | 4C | 7E | 6E | 6F | | 40 | 7C | C1 | C2 | C3 | C4 | C5 | C6 | C7 | C8 | C9 | D1 | D2 | D3 | D4 | D5 | D6 | | 50 | D7 | D8 | D9 | E2 | E3 | E4 | E5 | E6 | E7 | E8 | E9 | 4A | E0 | 5A | 5F | 6D | | 60 | 79 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 91 | 92 | 93 | 94 | 95 | 96 | | 70 | 97 | 98 | 99 | A2 | A3 | A4 | A5 | A6 | A7 | A8 | A9 | C0 | BB | D0 | A1 | 07 | | 80 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | 90 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | A0 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | B0 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | C0 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | D0 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | E0 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | | F0 | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | 3F | FF | +------------------------------------------------------------------------------------+

Glossary

47 A2 93US Rev01 g-1

Glossary

D

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

E

��JESP 7 class uses events/exceptions to notify the method 's caller that something has happened.

G

�� A communication mechanism between different environments. Usually involves conversion ofdata stream entities from the form acceptable by one environment to the form accepted by adifferent environment, as well as other operations.

��General Comprehensive Operating System 7.

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

I

��An interactive hierarchical data base system for the GCOS 7 operating system.

��Interoperability Software Installation on GCOS 7.


g-2 47 A2 93US Rev01

��Java Platform is a machine which runs the Java Virtual Machine (JVM).

��Java Enterprise Server Procedures for GCOS 7, a middleware that enables the use of open, highproductivity of Java applications using the benefits of a DPS 7000 as a TP/DB server.

��Java TDS, a middleware that enables the use of a simple link between the Java platform andGCOS 7 mailbox (TDS, IOF…).

P

��Personal Computer.Micro computers running DOS, and Microsoft Windows.

��Properties (or member) are data members of the Java class that are exposed. Properties provide aninterface for applications that use Java class.

S

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

�� !Structured 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.

��"��#�"$��A 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 Javaplatform and that emulate a SQL Execute Procedure.

T

��A suite of protocols for communication in interconnected LAN and WAN networks known asInternet.

��#��A 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.

Glossary

47 A2 93US Rev01 g-3

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

U

�&!�Unified File Access System. Native classical file system on Bull DPS 7000 (GCOS 7).

V

'�!(Virtual Communications Access Method. This is the GCOS 7 session layer communicationsmodule.

X

)��*Extended 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.


g-4 47 A2 93US Rev01

❑

47 A2 93US Rev01 i-1

Index

�

data types 3-59

�

Enterprise Server Procedures 7description 1-3

ESP 7administration tool 6-1as transactional Client/Server 3-2constraints 5-1functional description 3-2procedures 5-1user interface 3-31

ESP 7 TPRsinvoking 3-56

ESP 7/DA 7 PC gateway 3-4ESPADMPC

icon 6-4running 6-4tool 6-1

�

functional description 3-2

�

installationpre-conditions 2-1program 2-1

�

pre-conditionsinstallation 2-1

proceduresESP 7 5-1

�

Requirementson Bull Platform 1-2on Java Platform 1-2

�

site filesoverview 6-1

�

tablestranslation B-1

tblcgc utility B-1TDS application development 3-4tools

ESPADMPC 6-1, 6-4translation tables B-1

utilitiestblcgc B-1


i-2 47 A2 93US Rev01

��

��

�� !" #��#��$� %�&��!!�

�� !�"#��$��

$%�#��$�� &&��&&�� '��%!��%� ��!�"#��$��

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:

"��($( "��) �� *�� (�� Publication Order EntryAtelier de reprographie FAX: (508) 294-741134 rue du Nid de Pie BP 428 MA02/423S49004 ANGERS Cedex 01 Technology ParkFRANCE Billerica, MA 01821

U.S.A.

gcos 7/jesp - atossupport.bull.com/ols/product/system/gcos7/gcos7-com/g7-dps7000/… · 4.4...

Documents