JTDS. DSA Acess from Java (JTDS) 47 A2 98US Rev00

JTDS DSA Acess from Java (JTDS) 47 A2 98US Rev00

JTDS DSA Acess from Java (JTDS) Subject: Special Instructions: Software Supported: Software/Hardware required: Date: June 2002 Bull S.A. CEDOC Atelier de reprographie 357, Avenue Patton BP 20845 49008 ANGERS Cedex 01 FRANCE Bull HN Information Systems Inc. Publication Order Entry FAX: (800) 611-6030 MA30/415 300 Concord Rd. Billerica, MA 01821 U.S.A. 47 A2 98US Rev00

Copyright Bull S.A., 2002 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 any means, 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 no express warranties except as may be stated in its written agreement with and for its customer. In no event is Bull liable 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 98US Rev00

Table of Contents 1. Introduction 2. Constructors Supplied with the Class 2.1 For an 8-parameter Call... 2-1 2.2 For a 7-parameter Call... 2-1 2.3 For a 6-parameter Call... 2-1 2.4 For a 5-parameter Call (Missing Password)... 2-3 2.5 For a 4-parameter Call (Missing User and Password)... 2-3 2.6 For a 3-parameter Call (Missing Mailbox, User and Password)... 2-3 2.7 For a 2-parameter Call (Missing System, Mailbox, User and Password)... 2-3 2.8 For a 1-parameter Call (Missing Port, System, Mailbox, User and Password)... 2-3 2.9 For a 0-parameter Call (Missing HOST Name, Port, System, Mailbox, User and Password)... 2-4 3. PUBLIC Methods Supplied 3.1 read... 3-2 3.2 write... 3-3 3.3 Break... 3-4 3.4 return_error_msg...3-4 3.5 is_open... 3-5 3.6 is_turn... 3-5 3.7 is_alive... 3-6 3.8 disconnect... 3-6 47 A2 98US Rev00 iii

DSA Access from Java 4. Example of Java Access to a DSA Mailbox Index iv 47 A2 98US Rev00

Table of Graphics Tables 2-1. Positional Parameters - DSAconnect... 2-2 2-2. Error Handling Facilities - DSAconnect... 2-4 3-1. Error Handling Facilities - read... 3-2 3-2. Positional Parameter - write... 3-3 3-3. Error Handling Facilities - write... 3-3 3-4. Error Handling Facilities - Break... 3-4 3-5. Error Handling Facilities - return_error_msg... 3-4 3-6. Error Handling Facilities - is_open... 3-5 3-7. Error Handling Facilities - is_turn... 3-5 3-8. Error Handling Facilities - disconnect... 3-6 47 A2 98US Rev00 v

DSA Access from Java vi 47 A2 98US Rev00

1. Introduction This document describes the JTDS product which offers a DSA access to IOF or TDS from Java. The access is based on the Java class DSAconnect, which makes use of the sockethandling facilities of Java to connect to the NTGW7 gateway module. We then use the gateway to connect to any mailbox (IOF or TDS) using the ATMI or VCAM mechanisms. Once connection has been made to the mailbox, data can be sent to or read from the mailbox using specific methods supplied in the DSAconnect class. This class handles the notion of turn. We can only send data to the required mailbox when we have the turn. These methods, together with the other public methods of the class are described in the following sub-sections. Some exception and error recuperation mechanisms have been incorporated in the class. In all cases of error detection or exception recuperation, an exception (belonging to the class DSAexception) is thrown. These exceptions may all be intercepted by the caller under the general class DSAexception. An example of use of the DSAconnect class is provided in Appendix A. The test programme DSAtest provided makes use of the Threads facility of Java in order to handle the passage of break signals to the DSA mailbox. Restriction No encryption is provided for the password to be supplied in the DSA test program provided. 47 A2 98US Rev00 1-1

DSA Access from Java 1-2 47 A2 98US Rev00

2. Constructors Supplied with the Class The following valid constructors are supplied with the DSAconnect class: 2.1 For an 8-parameter Call public DSAconnect (home, port, system, mailbox, user, password, project, billing) throws DSAexception, DSAexcep_inparm 2.2 For a 7-parameter Call public DSAconnect (home, port, system, mailbox, user, password, project) throws DSAexception, DSAexcep_inparm 2.3 For a 6-parameter Call public DSAconnect (home, port, system, mailbox, user, password) throws DSAexception, DSAexcep_inparm Note that the above positional parameters are outlined in Table 1 below. The first six parameters are obligatory, while the seventh (project) and eighth (billing) are optional. This method is used to effect a DSA connection from Java to an IOF or TDS mailbox. 47 A2 98US Rev00 2-1

DSA Access from Java Table 2-1. Positional Parameters - DSAconnect Name Type Length Comment Home String 36 The name of HOST on which the gateway is to be accessed. Port String 4 The port number on which the gateway is listening. System String 4 The GCOS 7 system for which DSA access is to be effected. Mailbox String 8 The Mailbox on which the connection is to be made. User String 12 The name of the user for whom the connection is to be made. Password String 12 The Password for the given user. Project String 12 The (optional) project for which the connection is to be made. If omitted, the default project for the user is assumed. Billing String 12 The (optional) billing for which the connection is to be made. If omitted, the default billing for the user is assumed. The first two parameters are required for access to the HOST gateway on the target DPS 7. The others are used to effect the DSA connection to the required mailbox. The connection is made by the constructor for the DSAconnect class. Several constructors are defined to allow for connection with a variable number of parameters (project and billing being optional). Since connection is carried out by the constructor (which returns void), an additional method (is_open) is supplied. This method (described later) allows us to test whether the connection is valid. In addition, constructors with from 0 to 5 parameters are defined. These constructors do not result in connection, but edit an appropriate error message (or set of error messages) indicating that an insufficient number of parameters has been supplied. These special constructors are defined below. 2-2 47 A2 98US Rev00

Constructors Supplied with the Class 2.4 For a 5-parameter Call (Missing Password) public DSAconnect (home, port, system, mailbox, user) throws DSAexception, DSAexcep_nopwd 2.5 For a 4-parameter Call (Missing User and Password) public DSAconnect (home, port, system, mailbox) throws DSAexception, DSAexcep_nousr 2.6 For a 3-parameter Call (Missing Mailbox, User and Password) public DSAconnect (home, port, system) throws DSAexception, DSAexcep_nombx 2.7 For a 2-parameter Call (Missing System, Mailbox, User and Password) public DSAconnect (home, port) throws DSAexception, DSAexcep_nosys 2.8 For a 1-parameter Call (Missing Port, System, Mailbox, User and Password) public DSAconnect (home) throws DSAexception, DSAexcep_noport 47 A2 98US Rev00 2-3

DSA Access from Java 2.9 For a 0-parameter Call (Missing HOST Name, Port, System, Mailbox, User and Password) public DSAconnect () throws DSAexception, DSAexcep_nohome Whenever one of these constructors is executed, one or more error messages is edited to indicate which obligatory parameters are missing. For example, execution of DSAconnect () leads to the edition of the following set of error messages: The 1st parameter (HOST Host name of up to 36 characters) is required The 2nd parameter (port number of up to 4 characters) is required The 3rd parameter (system of up to 4 characters) is required The 4th parameter (mailbox of up to 8 characters) is required The 5th parameter (username of up to 12 characters) is required The 6th parameter (password of up to 12 characters) is required Too few parameters ************************************************* Anomaly detected in DSAconnect ************************************************* See the following Table for more details on the error handling facilities supplied with this method. Table 2-2. Error Handling Facilities - DSAconnect Exception Cause Action Taken DSAexception Exception occurred during execution of the constructor prints the current stack if available DSAexcep_inparm DSAexcep_nbpar DSAexcep_nopwd an input parameter is too long (more than the specified length) the number of parameters supplied is insufficient the password has been omitted from the parameter list edits an error message to indicate which parameter value is too long (see Example 1 below) edits the following message : Too few parameters edits the following message : The 6th parameter (password of up to 12 characters) is required throws DSAexcep_nbpar 2-4 47 A2 98US Rev00

Constructors Supplied with the Class Exception Cause Action Taken DSAexcep_nousr the user has been omitted from the parameter list edits the following message : The 5th parameter (username of up to 12 characters) is required DSAexcep_nombx DSAexcep_nosys DSAexcep_noport DSAexcep_nohome the mailbox has been omitted from the parameter list the system has been omitted from the parameter list the port number has been omitted from the parameter list the target HOST has been omitted from the parameter list throws DSAexcep_nopwd edits the following message : The 4th parameter (mailbox of up to 8 characters) is required throws DSAexcep_nousr edits the following message : The 3rd parameter (system of up to 4 characters) is required throws DSAexcep_nombx edits the following message : The 2nd parameter (port number of up to 4 characters) is required throws DSAexcep_nosys edits the following message : The 1st parameter (HOST name of up to 12 characters) is required throws DSAexcep_noport 47 A2 98US Rev00 2-5

DSA Access from Java EXAMPLE: Host Name Too Long DSAconnect (more_than_36_characters, 9003, bc06, iof, user1, password1) results in edition of the following text : Parameter 1 (Host name) is limited to 12 characters Exception caught during parameter controls Exception : DSAexcep_inparm DSAexcep_inparm at DSAconnect.control_parm(DSAconnect.java:461) at DSAconnect.<init>(DSAconnect.java:107) at DSAtest.main(DSAtest.java:99) **************** Connection error **************** End of processing 2-6 47 A2 98US Rev00

3. PUBLIC Methods Supplied The following public methods are available with the DSAconnect class: read write Break return_error_msg is_open is_turn is_alive disconnect to read from a DSA mailbox to write to a DSA mailbox to effect a break to obtain details on an error code to test whether or not a connection is open to test whether or not we have the turn to write to test whether the mailbox connection is still alive to terminate a DSA connection (for error treatment) These methods are outlined in detail below. In addition, a sample client source program to illustrate the use of the DSAconnect class is provided below. Note that this program may be modified by the user and no guarantee is provided that it will function on all types of client machine. 47 A2 98US Rev00 3-1

DSA Access from Java 3.1 read This method is used to read from a DSA mailbox. The read method has no parameters, but returns a String (the data read) to the caller. It is the caller s responsability to loop on reading until he is given the turn, indicating that there is nothing left to read. Read in a Multi-Thread Context In a multi-thread context, if the read is performed while you have the turn, then the thread that performs the read remains blocked until another thread unblocks it by performing a write. Read in a Mono-Thread Context In a mono-thread context, if the read is performed while you have the turn, then the thread that performs the read remains blocked. In this case, you must test the turn before performing a read. public String read () throws DSAexception, DSAexcep_read, DSAexcep_endsession, DSAexcep_abnormalend See the Table 3-1 for details of the error handling facilities supplied with this method. Table 3-1. Error Handling Facilities - read Exception Cause Action Taken DSAexception Exception occurred during execution of this method prints the current stack, together with an error message DSAexcep_read DSAexcep_endsession DSAexcep_abnormalend error detected during attempt to read from mailbox the end of the DSA session has been detected an abnormal end of the DSA session has been detected edits the error message: Error during read from mailbox : user disconnected edits the error message: Normal end of session edits the error message: Abnormal end of session 3-2 47 A2 98US Rev00

PUBLIC Methods Supplied 3.2 write This method is used to write to a DSA mailbox. The write method has a single input parameter, a string giving the data to be sent to the mailbox. public void write (String strin) throws DSAexception, DSAexcep_write The input parameter is described in the following Table. Table 3-2. Positional Parameter - write Name Type Length Comment strin String Variable the data to be sent to the mailbox See the Table 3-3 for details of the error handling facilities supplied with this method. Table 3-3. Error Handling Facilities - write Exception Cause Action Taken DSAexception Exception occurred during prints the current stack execution of this method DSAexcep_write error detected during attempt to write to mailbox edits the error message: Error during write to mailbox : user disconnected 47 A2 98US Rev00 3-3

DSA Access from Java 3.3 Break This method is used to send a break signal to a DSA mailbox. The Break method has no parameters. public void Break () throws DSAexception, DSAexcep_break See the following Table for details of the error handling facilities supplied with this method. Table 3-4. Error Handling Facilities - Break Exception Cause Action Taken DSAexception Exception occurred during Prints the current stack execution of this method DSAexcep_ break Error detected during attempt to send break signal to mailbox Edits the error message: Error during break handling : user disconnected 3.4 return_error_msg This method is used to obtain information on an error condition. public String return_error_msg () throws DSAexception See the Table 3-5 for details of the error handling facilities supplied with this method. Table 3-5. Error Handling Facilities - return_error_msg Exception Cause Action Taken DSAexception Exception occurred during Prints the current stack execution of this method 3-4 47 A2 98US Rev00

PUBLIC Methods Supplied 3.5 is_open This method is used to test whether a connection has been successfully made. It has no parameters, but returns a boolean whose value is : true false if the connection is open if the connection could not be made public boolean is_open () throws DSAexception See the following Table for details of the error handling facilities supplied with this method. Table 3-6. Error Handling Facilities - is_open Exception Cause Action Taken DSAexception exception occurred during prints the current stack execution of this method 3.6 is_turn This method is used to test whether it is your turn (to write). It has no parameters, but returns a boolean whose value is: true false if it is your turn to write if it is not your turn to write public boolean is_turn () throws DSAexception See the Table 3-7 for details of the error handling facilities supplied with this method. Table 3-7. Error Handling Facilities - is_turn Exception Cause Action Taken DSAexception exception occurred during prints the current stack execution of this method 47 A2 98US Rev00 3-5

DSA Access from Java 3.7 is_alive The is_open method described above returns true at the the creation of a DSAconnect object but doesn t allow real time looking after connection state (The connection state is known only after a following read method and so is_open doesn t allow a good scanning for connection pooling). The is_alive method is used to test whether the mailbox connection is alive in real time, and so it allows real time connection state scanning for efficient pooling by the application. is_alive() has no parameters and returns a boolean whose value is : true if the mailbox connection is alive false if the mailbox connection is dead public boolean is_alive() throws DSAexception 3.8 disconnect This method is used to disconnect from a DSA mailbox. It has no parameters and returns void. It is not always necessary for the user to effect the disconnection. If a read is effected after disconnection, the exception DSAendsession is thrown. The user should therefore provide a catch clause for this condition. Note that the HOST gateway acts merely as a tube for the passage of data to and from the mailbox. No interpretation of the data is carried out by the gateway module. public void disconnect () throws DSAexception See the following Table for details of the error handling facilities supplied with this method. Table 3-8. Error Handling Facilities - disconnect Exception Cause Action Taken DSAexception exception occurred during prints the current stack execution of this method 3-6 47 A2 98US Rev00

4. Example of Java Access to a DSA Mailbox Note that this extract indicates how to use the DSAconnect class with a 6- parameter constructor (project and billing take the default values for the given user). The DSAtest program provided uses the Threads facility of Java to allow simultaneous reading from and writing to a DSA mailbox. In this way we can handle the passage of break signals to the mailbox. In DSAtest, the string $*$BRK is used to indicate a break, but this may of course be modified by the user for his own specific needs. We do NOT guarantee that this sample program will run on any platform.import java.io.*; import java.net.*; import java.util.*; import java.lang.*; // =========================================================== class DSAtest extends Thread static Thread t; static DSAconnect cnx; // main entry point public static void main(string args[]) throws InterruptedException try String Strin = ; String arg_home = ; String arg_port = ; String arg_site = ; String arg_mbx = ; String arg_user = ; String arg_pw = ; char C; boolean online = true; // boolean online = false; Exception exc = new Exception(); if (! online) 47 A2 98US Rev00 4-1

DSA Access from Java System.out.println( *************** DSAtest execution *************** ); System.out.println( ); // ************* HOST name ****************** String Prompt1 = HOST name : ; System.out.print(Prompt1); while ((C = (char)system.in.read())!= '\n') arg_home = arg_home + C; // ************* Port number ****************** String Prompt2 = Port number : ; System.out.print(Prompt2); while ((C = (char)system.in.read())!= '\n') arg_port = arg_port + C; // ************* GCOS7 site ****************** String Prompt3 = GCOS7 site : ; System.out.print(Prompt3); while ((C = (char)system.in.read())!= '\n') arg_site = arg_site + C; // ************* Mailbox ****************** String Prompt4 = Mailbox : ; System.out.print(Prompt4); while ((C = (char)system.in.read())!= '\n') arg_mbx = arg_mbx + C; // ************* User ****************** String Prompt5 = User : ; System.out.print(Prompt5); while ((C = (char)system.in.read())!= '\n') arg_user = arg_user + C; // ************* Password ****************** String Prompt6 = Password : ; System.out.print(Prompt6); while ((C = (char)system.in.read())!= '\n') arg_pw = arg_pw + C; // ***************************************** else // ************* HOST name ****************** arg_home = args[0]; System.out.println( HOST name : + arg_home); // ************* Port number ****************** arg_port = args[1]; System.out.println( Port number : + arg_port); // ************* GCOS7 site ****************** arg_site = args[2]; System.out.println( GCOS7 name : + arg_site); 4-2 47 A2 98US Rev00

Example of Java Access to a DSA Mailbox // ************* Mailbox ****************** arg_mbx = args[3]; System.out.println( Mailbox name: + arg_mbx); // ************* User ****************** arg_user = args[4]; System.out.println( User name : + arg_user); // ************* Password ****************** arg_pw = args[5]; System.out.println( Password : + arg_pw); System.out.println( ); boolean end_of_test = false; cnx = new DSAconnect(arg_home,arg_port,arg_site,arg_mbx,arg_user, arg_pw); if (cnx.is_open()) t = new Thread(new readmbx(cnx)); t.setpriority(thread.currentthread().getpriority() + 1); t.start(); else String errstr = cnx.return_error_msg(); System.out.println( **************** Connection error **************** ); System.out.println(errStr); while (cnx.is_open()) Strin = ; while ((C = (char)system.in.read())!= '\n') Strin = Strin + C; if (Strin.compareTo( $*$BRK ) == 0) cnx.break(); else if (cnx.is_turn()) cnx.write(strin); catch (DSAexcep_endsession e) System.out.println( End of session ); System.out.println( ************************************************* ); System.out.flush(); catch (DSAexception e) 47 A2 98US Rev00 4-3

DSA Access from Java System.out.println( ); System.out.println( ************************************************* ); System.out.println( ); System.out.println( Anomalie detected in DSAconnect ); System.out.println( ************************************************* ); System.out.flush(); catch (Exception e) System.out.println( ); System.out.println( ************************************************* ); System.out.println( ); System.out.println( Exception recovered in DSAtest ); System.out.println( Exception : + e.tostring()); e.printstacktrace(); System.out.println( ); System.out.println( ************************************************* ); System.out.flush(); class readmbx implements Runnable private DSAconnect cnx; public readmbx(dsaconnect cnt) throws DSAexception, DSAexcep_endsession, DSAexcep_read cnx = cnt; public void run() try while (cnx.is_open()) Thread.currentThread().yield(); String Strout = cnx.read(); System.out.print(Strout); System.out.flush(); cnx.disconnect(); System.exit(0); catch (DSAexcep_endsession e) System.out.println( End of session detected ); catch (DSAexception e) System.out.println( Exception in readmbx ); 4-4 47 A2 98US Rev00

Index B Break method 3-4 C classes DSAconnect 1-1 D disconnect method 3-6 I is_open method 3-5, 3-6 is_turn method 3-5 M methods Break 3-4 disconnect 3-6 is_open 3-5, 3-6 is_turn 3-5 read 3-2 return_error_msg 3-4 write 3-3 P public methods Break 3-4 disconnect 3-6 is_open 3-5, 3-6 is_turn 3-5 read 3-2 retun_error_msg 3-4 write 3-3 R read method 3-2 return_error_msg method 3-4 W write method 3-3 47 A2 98US Rev00 i-1

DSA Access from Java i-2 47 A2 98US Rev00

Vos remarques sur ce document / Technical publications remarks form Titre / Title : DSA Acess from Java (JTDS) N Référence / Reference No. : 47 A2 98US Rev00 Date / Dated : June 2002 ERREURS DETECTEES / ERRORS IN PUBLICATION AMELIORATIONS SUGGEREES / SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION Vos remarques et suggestions seront attentivement examinées. Si vous désirez une réponse écrite, veuillez indiquer ci-après votre adresse postale complète. Your comments will be promptly investigated by qualified personnel and action will be taken as required. If you require a written reply, furnish your complete mailing address below. NOM / NAME : DATE : SOCIETE / COMPANY : ADRESSE / ADDRESS : Remettez cet imprimé à un responsable Bull S.A. ou envoyez-le directement à : Please give this technical publications remarks form to your Bull S.A. representative or mail to: Bull S.A. CEDOC Atelier de reprographie 357, Avenue Patton BP 20845 49008 ANGERS Cedex 01 FRANCE Bull HN Information Systems Inc. Publication Order Entry FAX: (800) 611-6030 MA30/415 300 Concord Rd. Billerica, MA 01821 U.S.A.