Informix Embedded SQLJ User’s Guide Version 1.0 March 1999 Part No. 000-5218 Published by INFORMIX Press Informix Corporation 4100 Bohannon Drive Menlo Park, CA 94025-1032 © 1999 Informix Corporation. All rights reserved. The following are trademarks of Informix Corporation or its affiliates: Answers OnLineTM; CBT StoreTM; C-ISAM ; Client SDKTM; ContentBaseTM; Cyber PlanetTM; DataBlade ; Data DirectorTM; Decision FrontierTM; Dynamic Scalable ArchitectureTM; Dynamic ServerTM; Dynamic ServerTM, Developer EditionTM; Dynamic ServerTM with Advanced Decision Support OptionTM; Dynamic ServerTM with Extended Parallel OptionTM; Dynamic ServerTM with MetaCube ROLAP Option; Dynamic ServerTM with Universal Data OptionTM; Dynamic ServerTM with Web Integration OptionTM; Dynamic ServerTM, Workgroup EditionTM; FastStartTM; 4GL for ToolBusTM; If you can imagine it, you can manage itSM; Illustra ; INFORMIX ; Informix Data Warehouse Solutions... Turning Data Into Business AdvantageTM; INFORMIX -Enterprise Gateway with DRDA ; Informix Enterprise MerchantTM; INFORMIX -4GL; Informix-JWorksTM; InformixLink ; Informix Session ProxyTM; InfoShelfTM; InterforumTM; I-SPYTM; MediazationTM; MetaCube ; NewEraTM; ON-BarTM; OnLine Dynamic ServerTM; OnLine for NetWare ; OnLine/Secure Dynamic ServerTM; OpenCase ; ORCATM; Regency Support ; Solution Design LabsSM; Solution Design ProgramSM; SuperView ; Universal Database ComponentsTM; Universal Web ConnectTM; ViewPoint ; VisionaryTM; Web Integration SuiteTM. The Informix logo is registered with the United States Patent and Trademark Office. The DataBlade logo is registered with the United States Patent and Trademark Office. Documentation Team: Joyce Simmonds, Juliet Shackell, Ju-Lung Tseng, Barb Van Dine, and the Oakland Editing and Production team GOVERNMENT LICENSE RIGHTS Software and documentation acquired by or for the US Government are provided with rights as follows: (1) if for civilian agency use, with rights as restricted by vendor’s standard license, as prescribed in FAR 12.212; (2) if for Dept. of Defense use, with rights as restricted by vendor’s standard license, unless superseded by a negotiated vendor license, as prescribed in DFARS 227.7202. Any whole or partial reproduction of software or documentation marked with this legend must reproduce this legend. ii Informix Embedded SQLJ User’s Guide Table of Contents Table of Contents Introduction In This Introduction ................. 3 About This Manual .................. 3 Organization of This Manual ............. 3 Types of Users .................. 4 Software Dependencies ............... 5 Global Language Support .............. 5 Documentation Conventions .............. 5 Typographical Conventions ............. 6 Icon Conventions ................. 6 Additional Documentation ............... 8 Related Manuals ................. 8 Documentation Notes and Release Notes ......... 8 Vendor-Specific Documentation ............ 9 Informix Welcomes Your Comments ............ 9 Chapter 1 Introducing Informix Embedded SQLJ In This Chapter ................... 1-3 What Is Embedded SQLJ? ............... 1-3 How Does Embedded SQLJ Work? ............ 1-3 Embedded SQLJ Versus JDBC .............. 1-5 Chapter 2 Preparing to Use Embedded SQLJ In This Chapter ................... 2-3 What Components Do You Need? ............. 2-3 Setting Up Your Software ............... 2-4 Installing the Java Development Kit .......... 2-4 Installing Embedded SQLJ and Informix JDBC Driver .... 2-4 Installing Your Informix Server ............ 2-5 Examples ..................... 2-5 Chapter 3 Building an Embedded SQLJ Program In This Chapter ................... 3-3 Fundamentals of Embedded SQLJ ............ 3-3 SQLJ Statement Identifier .............. 3-3 Connecting to a Database .............. 3-3 Embedding SQL Statements ............. 3-5 Handling Result Sets ............... 3-6 A Simple Embedded SQLJ Program ............ 3-8 Chapter 4 The Embedded SQLJ Language In This Chapter ................... 4-3 Embedded SQLJ Versus Traditional Embedded SQL ...... 4-3 Embedded SQLJ Source Files .............. 4-4 Identifying Embedded SQLJ Statements .......... 4-4 SQL Statements ................... 4-4 Host Variables ................... 4-5 SELECT Statements That Return a Single Row ........ 4-6 Handling Result Sets ................. 4-6 Positional Iterators ................ 4-7 Named Iterators ................. 4-8 Using Column Aliases ............... 4-10 Iterator Methods ................. 4-10 Positioned Updates and Deletes ........... 4-11 Monitoring the Execution of an SQL Query ......... 4-11 Calling SPL Routines and Functions ........... 4-12 SQL and Java Type Mappings .............. 4-13 Language Character Sets ............... 4-15 Importing Java Packages ............... 4-15 SQLJ Reserved Names ................ 4-16 Parameter, Field, and Variable Names ......... 4-16 Class Names and Filenames ............. 4-16 Handling Errors .................. 4-17 iv Informix Embedded SQLJ User’s Guide Chapter 5 Processing Embedded SQLJ Source Code In This Chapter .................. 5-3 Translating, Compiling, and Running Embedded SQLJ Programs . 5-3 The ifxsqlj Command ................ 5-4 Command Options ................. 5-5 Basic Options ................. 5-6 Advanced Options................ 5-8 Setting Options .................. 5-11 Setting Options on the Command Line......... 5-11 Supplying Options in Property Files ......... 5-12 On-Line Checking ................. 5-13 Setting the -user and -password Options ........ 5-14 Setting the -url and -driver Options .......... 5-15 The ifxprofp Tool ................. 5-15 Appendix A Connecting to Databases Appendix B Sample Programs Index Table of Contents v Introduction Introduction In This Introduction .................. 3 About This Manual................... 3 Organization of This Manual .............. 3 Types of Users ................... 4 Software Dependencies ................ 5 Global Language Support ............... 5 Documentation Conventions ............... 5 Typographical Conventions .............. 6 Icon Conventions .................. 6 Comment Icons ................. 7 Platform Icons .................. 7 Additional Documentation ................ 8 Related Manuals .................. 8 Documentation Notes and Release Notes .......... 8 Vendor-Specific Documentation ............. 9 Informix Welcomes Your Comments ............. 9 2 Informix Embedded SQLJ User’s Guide In This Introduction This introduction provides an overview of the information in this manual and describes the conventions it uses. Chapter 1, “Introducing Informix Embedded SQLJ,” provides an introduction to the Informix Embedded SQLJ product. About This Manual This manual contains information about using Informix Embedded SQLJ. This section discusses the organization of the manual, the intended audience, and the associated software products that you must have to use Informix Embedded SQLJ. Organization of This Manual This manual includes the following chapters: ■ Chapter 1, “Introducing Informix Embedded SQLJ,” introduces the Informix Embedded SQLJ product. ■ Chapter 2, “Preparing to Use Embedded SQLJ,” describes the software you need to develop and run Embedded SQLJ programs and how to set it up. ■ Chapter 3, “Building an Embedded SQLJ Program,” provides an overview of the Embedded SQLJ language and demonstrates its use with a simple program. ■ Chapter 4, “The Embedded SQLJ Language,” provides detailed information about the Embedded SQLJ language. Introduction 3 Types of Users ■ Chapter 5, “Processing Embedded SQLJ Source Code,” explains how to use the SQLJ translator and how to compile and run your Embedded SQLJ programs. ■ Appendix A, “Connecting to Databases,” provides background information and further details about how an Embedded SQLJ program connects to a database. ■ Appendix B, “Sample Programs,” provides a table describing the sample programs included with Embedded SQLJ. An index follows at the end of the manual. Types of Users This guide is for programmers who want to write Java programs that can: ■ connect to Informix databases. ■ issue SQL statements to manipulate data in the database. This manual is written with the assumption that you have the following background: ■ A working knowledge of your computer, your operating system, and the utilities that your operating system provides ■ Experience with the Java programming language ■ Experience working with relational databases or exposure to database concepts ■ Experience with the SQL query language If you have limited experience with relational databases, SQL, or your operating system, refer to the Getting Started manual for your database server for a list of supplementary titles. 4 Informix Embedded SQLJ User’s Guide Software Dependencies Software Dependencies To run Informix Embedded SQLJ programs, you must use one of the following database servers: ■ Informix Dynamic Server, Version 7.x ■ Informix Dynamic Server with Advanced Decision Support and Extended Parallel Options, Version 8.x ■ Informix Dynamic Server, Workgroup and Developer editions, Version 7.x ■ Informix Dynamic Server with Universal Data Option, Version 9.x ■ INFORMIX-OnLine Dynamic Server, Version 5.x ■ INFORMIX-SE, Versions 5.x to 7.2x To enable your programs to connect to the server, you must use Informix JDBC Driver, Version 2.0 or later. You must use the JavaSoft software Java Development Kit (JDK), Version 1.2 or later, or any Java software compatible with JDK 1.2, to create your programs. JDK 1.2 is also known as Java 2. Global Language