Sybase Business Intelligence Solutions - Database Management, Data Warehousing Software, Mobile Enterprise Applications and Messaging
Sybase Brand Color Bar
delete

Search for    in all of Sybase.com
view all search results right arrow
  blank
 
 
 
 
 
 
 
 
 
 
Support > Technical Documents > How To > Sybase(R) jConnect for JDBC(TM) Programmer's Refer...

Sybase(R) jConnect for JDBC(TM) Programmer's Reference: jConnect Utilities

jConnect Utilities
 
RSS Feed
 
 
 


B . jConnect Utilities

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

Running IsqlApp


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}>]

Parameter

Description

-U

The login ID with which you want to connect to a server.

-P

The password for the specified login ID.

-S

The name of the server to which you want to connect.

-G

Gateway address. For the HTTP protocol, the URL is: http://host:port.

To use the HTTPS protocol that supports encryption, the URL is https://host:port/servlet_alias.

-p

Specifies whether you want to use the HTTP protocol or the HTTPS protocol that supports encryption

-D

Turns on debugging for all classes or for just the ones you specify, separated by a comma. For example,

-D ALL

displays debugging output for all classes.

-D SybConnection, Tds

displays debugging output only for the SybConnection and Tds classes.

-v

Turns on verbose output for display or printing.

-I

Causes IsqlApp to take commands from a file instead of the keyboard.

After the parameter, you specify the name of the file to use for the IsqlApp input. The file must contain command terminators ("go" by default).

-c

Lets you specify a keyword (for example, "go") that, when entered on a line by itself, terminates the command. This lets you enter multiline commands before using the terminator keyword. If you do not specify a command terminator, each new line terminates a command.

-C

Specifies the character set for strings passed through TDS.

If you don't specify a character set, IsqlApp uses the server's default charset.

-L

The language in which to display error messages returned from the server and for jConnect messages.

-T

When this parameter is set, jConnect assumes that an application is trying to resume communication on an existing TDS session held open by the TDS-tunnelling gateway. jConnect skips the login negotiations and forwards all requests from the application to the specified session ID.

-V

Enables the use version-specific characteristics. See "JCONNECT_VERSION Connection Property".

Note

You must enter a space after each option flag.

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

Note


An applet that provides GUI access to isql commands is available as:

For jConnect 4.1:
$JDBC_HOME/sample/gateway.html
(UNIX)
%JDBC_HOME%\sample\gateway.html (Windows)

For jConnect 5.0:
$JDBC_HOME/sample2/gateway.html (UNIX)
%JDBC_HOME%\sample2\gateway.html (Windows)

Using jisql


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.

Note

If you use JDK 1.2.x, make sure that JAVA_HOME is set correctly and that your CLASSPATH includes dt.jar as follows:

$JAVA_HOME$/lib/dt.jar (for UNIX)

%JAVA_HOME%\lib\dt.jar (for Windows).
Starting jisql


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.

Note

If you are using Windows, you should have at least a 1024x768 screen resolution to run jisql.

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

Parameter

Description

-d

Switches to debug mode.

-v

Displays the version number.

-L

Sets the look and feel of jisql:

  • "metal" uses the Java Software look and feel.
  • "system" uses the Motif, Windows, or MacIntosh look and feel, depending on your operating system.

The default look and feel of jisql is "metal."

-U

The login ID with which you want to use to connect to the database.

Note:
If you specify -S, you must also specify -U.

-P

The password for the specified login ID.

-Z <language>

Sets the language of the labels in jisql. The currently supported values are "English|US_English" and "Deutsch|German."

-C <LoginInformationFile>

Sets the path and name of the file where the login information is stored. If you specify this value, the connection window will display this information. If you do not provide a file name, [username].prp is created in the current directory.

-S

Host:Port?Properties

or

JDBC URL

or

JNDI URL

where:

  • Host is the name of the machine on which the database server is running.
  • Port is the port to which the database server is listening.
  • Properties are connection properties as described in the "Setting Connection Properties".
  • JDBC URL is the complete JDBC URL.
  • JNDI URL is the JDNI connection string and its appropriate properties. See "Connecting to a Server Using JNDI" for more information.

To specify more than one property, connect them using an ampersand (the "&" character). Do not use blanks, and remember to put the string in quotes when you use "?" and "&."

Note:
If you specify -S, you must also specify -U.
Logging In To jisql


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.

Examples

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"
Using jisql


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"
Capturing Data


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>
Syntax and Parameters

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]

Table B-1:   Ribo command line parameters

Parameter

Description

-l

The port on which to listen.
The default is 5005.

-s

The host name of the database server.

-p

The port number of the database server.

-c

By default, Ribo captures TDS data to a file. This option lets you specify the prefix added to the generated file name of the captured data. If you do not specify a prefix, "cap" is used. This file can be used by technical support personnel to help you troubleshoot problems with your system.

-t

Translates captured data to the TDS protocol's text representation and saves it to a file. This option lets you specify the prefix added to the generated file name of the translated data. If you do not specify a prefix, "out" is used.

-gui

Invokes the Ribo GUI, which you can use to:

  • Start and stop the capturing process
  • View translated data "on the fly" as it is being analyzed

-d

Displays translated data while the data is being captured. If you are using the Ribo GUI, the data displays in a separate window. If you are not using the GUI, the data displays on the screen.

-h

Displays help on Ribo usage.

-f

Reserved for future use.

-q

Enter this option at the command line to stop data capture.

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
Using the Ribo GUI


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.

Running jConnect Sample Programs and Code


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.

Sample Applications

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.

Note

The jConnect sample programs are intended for demonstration purposes only.

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.

Running the Sample 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

Running the Sample Programs with Adaptive Server Anywhere

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
Sample Code

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);
     }
 }
 

Sybase(R) jConnect for JDBC(TM) Programmer's Reference - 29 Jan 1999

Copyright 1999 © Sybase, Inc. All Rights Reserved.

 

Related Links

 
 
 

© Copyright 2014, Sybase Inc. - v 7.6 Home / Contact Us / Help / Jobs / Legal / Privacy / Code of Ethics