This appendix is a guide to Sybase jConnect utility programs. It contains the following sections:

• Running IsqlApp

• Using jisql

• Using the Ribo Utility

• Running jConnect Sample Programs and Code

IsqlApp allows you to issue isql commands from the command line.

The syntax for IsqlApp is:

  
IsqlApp [-U username] [-P password]
	[-S servername]
	[-G gateway]
	[-p {http|https}]
	[-D debug-class-list]
	[-v verbose printing] 
	[-I input-command-file]
	[-c command_terminator]
	[-C charset] [-L language]
	[-T sessionID]
	[-V <version {2,3,4,5}>]

To obtain a full description of the command line options, enter:

  
java IsqlApp -help

The following example shows how to connect to a database on a host named "myserver" through port "3756" and run an isql script named "myscript":

  
java IsqlApp -U sa -P sapassword 
	-S jdbc:sybase:Tds:myserver:3756 
	-I $JDBC_HOME/sp/myscript -c run

jisql is an easy-to-use Transact-SQL (T-SQL) editor that helps you compose T-SQL command statements using a graphical user interface.You can then execute your T-SQL queries, and view the results either as text or within a table.

jisql can save your input or results data in common file formats that you can then import into other applications (for example, Microsoft Excel or bcp).

jisql is 100% Pure Java code and takes advantage of the Java Foundation Classes (JFC), which are a part of Swing. The Swing components are written in Java, without window-system-specific code, which allows you to use jisql in your favorite environment with the look and feel you are used to without having to rely on the native windowing system.

To install and start jisql,

• in UNIX, type:

  
	jisql

• in Windows, click Start, then click Run. When the Open dialog box displays, type the path to jisql.bat, which is located in the utils subdirectory of your jConnect directory, then click OK.

You can also start jisql using command line parameters and syntax:

  
jisql	[-d] [-v] [-L metal|system] [-U username] [-P password]
	[-Z <language>] [-C <LoginInformationFile>]
	[-S host:port[?propname=value[&propname=value]...]]

or

  
	[-S JDBC URL[?propname=value[&propname=value]...]]

or

  
	[-S JNDI URL[?propname=value[&propname=value]...]]

After you start jisql, a login window displays where you enter the necessary connection parameters:

• Username - The login ID.

• Password - The password for the Login ID specified.

• Hostname - The name of the machine on which the database server is running.

• Portnumber - The port to which the database server is listening.

• Properties - Optional. Any jConnect connection properties you want to specify. Refer to Table 2-2 for a list of connection properties.

• Language - The language in which jisql labels display. The currently supported values are English and Deutsch (German).

• Click Connect to make the connection.

After you log in successfully the first time, the connection parameters you specified (except the password), are stored in a property file. The next time you log in, you only need to enter the password. The property file is named [username].prp in the current directory. It always contains the data from the last successful connection.

This section contains examples of invoking jisql using various parameters.

To use the Java Software look and feel and open a connection window, you would enter:

  
jisql

To set the look and feel to Motif, Windows, or MacIntosh (depending on your operating system) and open a connection window, you would enter:

  
jisql -L system

To set the look and feel to Motif, Windows, or MacIntosh (depending on your operating system), open a connection to the host "serv," and set the user to sa with a password, you would enter:

  
jisql -L system -S serv:3312 -U sa -P pass

To use the Java Software look and feel, open a connection to the host "serv," and set the user to sa with no password, you would enter:

  
jisql -S serv:3312 -U sa

To use the Java Software look and feel, open a connection to the host "serv," set the user to sa with a password, and set the HOSTNAME and PACKETSIZE properties, you would enter:

  
jisql -L metal -U sa -P pass -S
	serv:3312?HOSTNAME=brillig&PACKETSIZE=4096

To use the Java Software look and feel, set the user to sa with a password, and use the complete JDBC URL to open a connection to the host "serv," you would enter:

  
jisql -U sa -P pass -S jdbc:sybase:Tds:serv:3312

To use the Java Software look and feel, set the user to sa with a password, and use Sun Microsystems, Inc.'s LDAP factory to provide a JNDI connection, you would enter:

  
jisql -U sa -P pass -S "jdbc:sybase:jndi:ldap://LDAP_hostname:LDAP_port/servername,o=MyComany,c=US?INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdatCtxFactory&PROVIDER_URL=ldap://LDAP_hostname:LDAP_port"

After you connect to a host server, the jisql program screen displays where you can:

• Type a query in the Input pane, click Go, then view the results in the Output pane

• Read in and execute a prepared batch file

• Click History to view a list of previously entered commands

• Save input, output, and history to a file

• View a list of system tables, user tables, stored procedures, and triggers for the specified database

• Select a different database from the pull-down list box

• Connect to a different server

Figure B-1 show the input and output of a simple query.

For more information, see the jisql online help. Using the Ribo Utility

The Ribo utility captures, displays, and translates the TDS protocol stream flowing between a Sybase client and server.

Ribo has three modes:

• Capture a TDS protocol stream to a file

• Translate a captured file to the TDS protocol's text representation

• Capture a TDS protocol's stream to a file and translate the protocol's text representation to the screen or a GUI window "on-the-fly"

To use Ribo to capture TDS protocol data and save that data to a file, enter the following from a UNIX or DOS command window:

  
Ribo <command_line_options>

Ribo uses the following syntax and command line options.

  
Ribo	[-l <listen_port>] [-s <server_host>] [-p <server_port>]
	[-c <capture_file_prefix>] [-t <trans_file_prefix] 
	[-gui] [-d] [-f <filter_file>] [-h]

Translating Data

---

To analyze captured TDS protocol data and save the text representation of that data to a file, enter:

  
Ribo <input_capture_file> <output_file>

where <input_capture_file> is the name of the file from which to analyze previously captured data and <output_file> is the file name under which to save the translated data. If you do not specify an output file, the translated data is sent to stdout.

The output file displays:

• SQL statements sent to the server

• Parameters sent to the server

• Results returned from the server

When you include the -gui parameter, you see the screen shown in Figure B-2.

If you specified the listen port, server host, and server port when you started Ribo, these parameters are filled in for you on the GUI screen.

To capture and translate data:

1. Select Settings from the File menu. You see the dialog box shown in Figure B-3.

1. Specify the options you want:

• Capture File Prefix
  Translate File Prefix
  Translation Filter File

correspond to the -c, -t, and -f command line parameters, respectively. See Table 2-1 for details.

• To translate the captured data to a text file and/or display the translated data in a window as it is being analyzed, check the appropriate option.

1. Click OK.

1. Click Start Capture.

1. To stop the capture process click Stop Capture. You must stop the capture process to change the host, ports, or settings.

1. When you finish, click End.

jConnect includes several sample programs to illustrate many of the topics covered in this chapter, and to help you understand how jConnect works with various JDBC classes and methods. In addition, this section includes a sample code fragment for your reference.

When you install jConnect, you can also the install sample programs. These samples include the source code so that you can review how jConnect implements various JDBC classes and methods. See the jConnect for JDBC Installation Guide and Release Bulletin for complete instructions for installing the sample programs.

The sample programs are installed in the sample subdirectory (jConnect 4.1) or sample2 subdirectory (jConnect 5.0) under your jConnect installation directory. The file index.html in the sample or sample2 subdirectory contains a complete list of the samples that are available along with a description of each sample. index.html also lets you view and run the sample programs as applets.

Using your Web browser, you can run some of the sample programs as applets. This enables you to view the source code while viewing the output results.

To run the samples as applets, you need to start the Cascade gateway. See "Using the Cascade Gateway".

Use your Web browser to open index.html:

For jConnect 4.1, enter:

http://localhost:8000/sample/index.html

For jConnect 5.0, enter:

http://localhost:8000/sample2/index.html

All of the sample programs are compatible with Adaptive Server, but only a limited number are compatible with Adaptive Server Anywhere. Refer to index.html in the sample or sample2 subdirectory for a current list of the sample programs that are compatible with Adaptive Server Anywhere.

To run the sample programs that are available for Adaptive Server Anywhere, you must install the pubs2_any.sql script on your Adaptive Server Anywhere server. This script is located in the sample (jConnect 4.1) or sample2 (jConnect 5.0) subdirectory.

For Windows, go to DOS command window and enter:

  
java IsqlApp -U dba -P password 
-S jdbc:sybase:Tds:[hostname]:[port] 
-I %JDBC_HOME%\sample\pubs2_any.sql -c go

For UNIX, enter:

  
java IsqlApp -U dba -P password 
-S jdbc:sybase:Tds:[hostname]:[port] 
-I $JDBC_HOME/sample/pubs2_any.sql -c go

The following sample code illustrates how to invoke the jConnect driver, make a connection, issue a SQL statement, and process results.

  
import java.io.*;
import java.sql.*;
 
  public class SampleCode
  {
      public static void main(String args[])
      {
          try
          {
          /*
           * Open the connection. May throw a SQLException.
           */
             Connection con = DriverManager.getConnection(
                 "jdbc:sybase:Tds:myserver:3767", "sa", "");
          /*
           * Create a statement object, the container for the SQL
           * statement. May throw a SQLException.
           */
             Statement stmt = con.createStatement();
          /*
           * Create a result set object by executing the query.
           * May throw a SQLException.
           */
             ResultSet rs = stmt.executeQuery("Select 1");
          /*
           * Process the result set.
           */

             if (rs.next())
             {
                int value = rs.getInt(1);
                System.out.println("Fetched value " + value);
             }
         }
     /*
      * Exception handling.
      */
         catch (SQLException sqe)
         {
             System.out.println("Unexpected exception : " +
                         sqe.toString() + ", sqlstate = " +
                             sqe.getSQLState());
             System.exit(1);
         }
         System.exit(0);
     }
 }