HP NonStop SQL/MX Remote Conversational Interface (RMXCI) Guide

Transcription

1 HP NonStop SQL/MX Remote Conversational Interface (RMXCI) Guide HP Part Number: Published: August 2012 Edition: HP NonStop SQL/MX Release 3.2

2 Copyright 2012 Hewlett-Packard Development Company, L.P. Legal Notice Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor s standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Export of the information contained in this publication may require authorization from the U.S. Department of Commerce. Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. Intel, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks, and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. 1990, 1991, 1992, 1993 Open Software Foundation, Inc. The OSF documentation and the OSF software to which it relates are derived in part from materials supplied by the following: 1987, 1988, 1989 Carnegie-Mellon University. 1989, 1990, 1991 Digital Equipment Corporation. 1985, 1988, 1989, 1990 Encore Computer Corporation Free Software Foundation, Inc. 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. 1988, 1989 Massachusetts Institute of Technology. 1988, 1989, 1990 Mentat Inc Microsoft Corporation. 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. 1990, 1991 Siemens Nixdorf Informationssysteme AG. 1986, 1989, 1996, 1997 Sun Microsystems, Inc. 1989, 1990, 1991 Transarc Corporation. OSF software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California.

3 Contents About this document...10 Intended audience...10 Document organization...10 New and changed information in this edition...10 Notation conventions...10 General syntax notation...10 Related documentation...12 NonStop SQL/MX customer library...12 Publishing history...14 HP encourages your comments Introduction to RMXCI Installing RMXCI...16 Pre-installation procedures...16 Installing and verifying the Java Runtime Environment (JRE)...16 Installing and verifying the NonStop JDBC Type 4 Driver...19 (Optional) Installing Perl or Python...20 Installation procedures...20 Downloading the Installer...20 Verifying the installer file version...22 Installing RMXCI...22 Post-installation procedures...32 Verifying the installed software files...32 Verifying the installed version of RMXCI...32 Setting the Look-and-Feel of RMXCI...33 Testing the RMXCI launch Launching RMXCI...41 Launching RMXCI on Windows using graphic tools...41 Launching RMXCI on Linux...43 Setting the rmxci.sh PATH...43 Presetting the optional launch parameters...44 Logging in to the database platform...44 Default login...44 Login parameters...47 Using optional launch parameters...47 Exiting RMXCI Interactively running commands in RMXCI...54 Running commands...54 Product banner...54 Interface prompts...54 Breaking the command line...54 Case sensitivity...55 Using RMXCI commands...55 Showing the session attributes...55 Setting and showing the idletimeout value for the session...56 Customizing the standard prompt...56 Setting and showing the SQL terminator...57 Displaying the elapsed time...57 Setting and showing the current schema...58 Limiting the result set of a query...58 Contents 3

4 Showing information about SQL database objects...59 Displaying run commands...60 Editing and rerun a command...60 Clearing the interface window...60 Obtaining help...61 Running SQL statements...61 Executing an SQL Statement...61 Repeating an SQL Statement...61 Preparing and executing SQL Statements...62 Executing CREATE TRIGGER statements...65 Logging output...66 Starting the logging process...66 Stopping the logging process...67 Viewing the contents of a log file Running scripts in RMXCI...69 Creating a script file...69 Supported SQL statements in script files...69 Permitted RMXCI commands in script files...69 Comments...69 Section headers...69 Example of a script file...70 Running a script file...70 Logging output...71 Running scripts in parallel Running RMXCI from Perl or Python...72 Login environment variables...72 Setting the login environment variables...72 Perl and Python wrapper scripts...74 Launching RMXCI from the Perl or Python command-line...74 Example of a Perl Program (example.pl)...74 A RMXCI command...79 Syntax...79 Examples...79 / command...79 Syntax...79 Considerations...80 Example...80 ALIAS command...80 Syntax...80 Considerations...80 Examples...80 CLEAR command...81 Syntax...81 Considerations...81 Example...81 CONNECT command...81 Syntax...81 Considerations...82 Examples...82 DELAY command...82 Syntax...82 Considerations Contents

5 Examples...83 DISCONNECT command...83 Syntax...83 Considerations...83 Examples...83 ENV command...83 Syntax...83 Considerations...84 Examples...85 EXIT command...86 Syntax...86 Considerations...86 Examples...86 FC command...86 Syntax...87 Considerations...87 Examples...87 GET STATISTICS command...89 Syntax...89 Examples...89 GOTO command...90 Syntax...90 Considerations...90 Examples...90 HELP command...90 Syntax...90 Considerations...90 Examples...90 HISTORY command...91 Syntax...91 Considerations...91 Example...91 IF...THEN command...91 Syntax...91 Considerations...92 Examples...92 LABEL command...93 Syntax...93 Considerations...93 Examples...93 LOCALHOST command...93 Syntax...93 Considerations...93 Examples...93 LOG command...94 Syntax...94 Considerations...95 Examples...95 OBEY command...96 Syntax...96 Considerations...97 Examples...97 PRUN command...99 Syntax...99 Considerations Contents 5

6 Example QUIT command Syntax Considerations Examples RECONNECT command Syntax Considerations Examples REPEAT command Syntax Considerations Examples RESET LASTERROR command Syntax Considerations Examples RESET PARAM command Syntax Considerations Example RUN command Syntax Considerations Example SAVEHIST command Syntax Considerations Examples SET CATALOG command Syntax Considerations Examples SET COLSEP command Syntax Considerations Examples SET FETCHSIZE command Syntax Considerations Examples SET HISTOPT command Syntax Considerations Examples SET IDLETIMEOUT command Syntax Considerations Examples SET LIST_COUNT command Syntax Considerations Examples SET MARKUP command Syntax Contents

7 Considerations Examples SET PARAM command Syntax Considerations Examples SET PROMPT command Syntax Considerations Examples SET SQLPROMPT command Syntax Considerations Examples SET SQLTERMINATOR command Syntax Considerations Examples SET STATISTICS command Syntax Considerations Examples SET TIME command Syntax Considerations Examples SET TIMING command Syntax Considerations Examples SHOW ACTIVITYCOUNT command Syntax Examples SHOW ALIAS command Syntax Considerations Examples SHOW ALIASES command Syntax Considerations Examples SHOW CATALOG command Syntax Considerations Examples SHOW CATALOGS command Syntax Considerations Examples SHOW COLSEP command Syntax Considerations Examples SHOW ERRORCODE command Syntax Contents 7

8 Examples SHOW FETCHSIZE command Syntax Considerations Examples SHOW HISTOPT command Syntax Considerations Examples SHOW IDLETIMEOUT command Syntax Considerations Examples SHOW LASTERROR command Syntax Considerations Examples SHOW LIST_COUNT command Syntax Considerations Examples SHOW MARKUP command Syntax Considerations Examples SHOW PARAM command Syntax Considerations Example SHOW PREPARED command Syntax Considerations Examples SHOW PROCEDURES command Syntax Considerations Examples SHOW RECCOUNT command Syntax Considerations Examples SHOW SCHEMA command Syntax Considerations Example SHOW SCHEMAS command Syntax Considerations Examples SHOW SESSION command Syntax Considerations Examples SHOW SQLPROMPT command Syntax Contents

9 Considerations Example SHOW SQLTERMINATOR command Syntax Considerations Example SHOW STATISTICS command Syntax Considerations Example SHOW TABLES command Syntax Considerations Examples SHOW TIME command Syntax Considerations Example SHOW TIMING command Syntax Considerations Example SHOW VIEWS command Syntax Considerations Examples SPOOL command Syntax Considerations Examples VERSION command Syntax Considerations Example B Supported SQL statements C Error messages Index Contents 9

10 About this document This guide describes how to install and use the HP NonStop SQL/MX Remote Conversational Interface (RMXCI), installed on a client workstation, to manage SQL/MX 3.x database on a NonStop platform. RMXCI enables you to perform daily administrative tasks by running SQL statements interactively or from script files. In this release, RMXCI is supported on Linux and Windows platforms. Intended audience This guide is intended for users, administrators and support personnel who are maintaining and monitoring a NonStop SQL/MX 3.x database. Document organization Chapter 1: Introduction to RMXCI Chapter 2: Installing RMXCI Chapter 3: Launching RMXCI Chapter 4: Interactively running commands in RMXCI Chapter 5: Running scripts in RMXCI Chapter 6: Running RMXCI from Perl or Python Appendix A: RMXCI commands Appendix B: Supported SQL statements Appendix C: Error messages Introduces the RMXCI product and describes its capabilities. Describes how to install the RMXCI product on the client workstation. Describes how to launch, log in to, and exit the RMXCI session on a client workstation. Describes how to run commands interactively from RMXCI. Describes how to run script files from RMXCI. Describes how to run Perl or Python scripts from RMXCI. Provides syntax, considerations and examples for RMXCI commands. Lists the SQL statements supported by RMXCI. Lists the error messages returned by RMXCI. New and changed information in this edition This guide designates new and changed material by using change bars in the right margin. Chapter or Appendix All chapters New or Changed Information Added information and examples for RMXCI support on Windows. Notation conventions General syntax notation This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: SELECT Italic Letters Italic letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name 10

11 Computer Type Computer type letters within text indicate case-sensitive keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.sh Bold Text Bold text in an example indicates user input typed at the terminal. For example: ENTER RUN CODE?123 CODE RECEIVED: The user must press the Return key after typing the input. [ ] Brackets Brackets enclose optional syntax items. For example: DATETIME [start-field TO] end-field A group of items enclosed in brackets is a list from which you can select one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: DROP schema [CASCADE] [RESTRICT] DROP schema [ CASCADE RESTRICT ] { } Braces Braces enclose required syntax items. For example: FROM { grantee[, grantee]...} A group of items enclosed in braces is a list from which you are required to select one item. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: INTERVAL { start-field TO end-field } { single-field } INTERVAL { start-field TO end-field single-field } Vertical Line A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: {expression NULL} Ellipsis An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: ATTRIBUTE[S] attribute [, attribute]... {, sql-expression}... An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: Notation conventions 11

12 expression-n Punctuation Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: DAY Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "{" module-name [, module-name]... "}" Item Spacing Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: DAY (datetime-expression) DAY(datetime-expression) If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: myfile.sh Line Spacing If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: match-value [NOT] LIKE pattern Related documentation [ESCAPE esc-char-expression] This manual is part of the HP NonStop SQL/MX library of manuals. NonStop SQL/MX customer library The manuals in the SQL/MX customer library are listed here for your convenience. Introductory guides SQL/MX Comparison Guide for SQL/MP Users SQL/MX Quick Start Guide Describes differences between NonStop SQL/MP and NonStop SQL/MX databases. Describes basic techniques for using SQL in the SQL/MX conversational interface (MXCI). Includes information about installing the sample database. Installation guides SQL/MX Installation and Management Guide NSM/web Installation Guide Describes how to plan for, install, create, and manage an SQL/MX database. Explains how to use installation and management commands and utilities. Describes how to install NSM/web and troubleshoot NSM/web installations. 12

13 Reference manuals SQL/MX Reference Manual SQL/MX Messages Manual SQL/MX Glossary Describes the syntax of SQL/MX statements, MXCI commands, functions, and other SQL/MX language elements. Describes SQL/MX messages. Defines SQL/MX terminology. Connectivity manuals SQL/MX Connectivity Service Manual SQL/MX Connectivity Service Administrative Command Reference ODBC/MX Driver for Windows SQL/MX Remote Conversational Interface (RMXCI) Guide HP NonStop JDBC Type 4 Driver 3.0 Programmer's Reference Describes how to install and manage SQL/MX Connectivity Service (MXCS), which enables ODBC and other connectivity APIs to use NonStop SQL/MX. Describes the SQL/MX Administrative Command Library (MACL) available with the SQL/MX conversational interface (MXCI). Describes how to install and configure HP NonStop ODBC/MX for Microsoft Windows, which enables applications developed with ODBC API to use NonStop SQL/MX. Describes how to use SQL/MX Remote Conversational Interface to run the RMXCI commands, and SQL statements interactively or from script files. Describes the NonStop JDBC Type 4 Driver functionality, which allows Java programmers to remotely develop applications deployed on client workstations to access NonStop SQL/MX databases. Migration guides SQL/MX Database and Application Migration Guide NonStop NS-Series Database Migration Guide Describes how to migrate databases and applications to NonStop SQL/MX, and how to manage different versions of NonStop SQL/MX. Describes how to migrate NonStop SQL/MX, NonStop SQL/MP, Enscribe databases and applications to HP Integrity NonStop NS-series systems. Data management guides SQL/MX Data Mining Guide SQL/MX Report Writer Guide DataLoader/MX Reference Manual Describes the SQL/MX data structures and operations for data mining. Describes how to produce formatted reports using data from an SQL/MX database. Describes the features and functions of the DataLoader/MX product, a tool to load SQL/MX databases. Application development guides SQL/MX Programming Manual for C and COBOL SQL/MX Query Guide SQL/MX Queuing and Publish/Subscribe Services SQL/MX Guide to Stored Procedures in Java Describes how to embed SQL/MX statements in ANSI C and COBOL programs. Describes how to understand query execution plans and write optimal queries for an SQL/MX database. Describes how NonStop SQL/MX integrates transactional queuing and publish/subscribe services into its database infrastructure. Describes how to use stored procedures that are written in Java within NonStop SQL/MX. Related documentation 13

14 Online help Reference Help Messages Help Glossary Help NSM/web Help Visual Query Planner Help SQL/MX Database Manager Help Overview and reference entries from the SQL/MX Reference Manual. Individual messages grouped by source from the SQL/MX Messages Manual. Terms and definitions from the SQL/MX Glossary. Context-sensitive help topics that describe how to use the NSM/web management tool. Context-sensitive help topics that describe how to use the Visual Query Planner graphical user interface. Contents and reference entries from the SQL/MX Database Manager User Guide. The NSM/web, SQL/MX Database Manager, and Visual Query Planner help systems are accessible from their respective applications. You can download the Reference, Messages, and Glossary online help from the HP Software Depot at For more information about downloading the online help, see the SQL/MX Release 3.2 Installation and Upgrade Guide. Publishing history Part Number Product Version HP NonStop SQL/MX Release 3.1 HP NonStop SQL/MX Release 3.2 Publication Date Oct 2011 Aug 2012 HP encourages your comments HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to: Include the document title, part number, and any comment, error found, or suggestion for improvement you have concerning this document. 14

15 1 Introduction to RMXCI HP NonStop SQL/MX Remote Conversational Interface (RMXCI) is a command-line interface, which you can download and install on a client workstation that has a NonStop JDBC Type 4 Driver. The NonStop JDBC Type 4 Driver connects RMXCI on a Linux or Windows client workstation to an SQL/MX 3.x database on a NonStop platform. Figure 1 RMXCI connected to the NonStop environment NOTE: RMXCI interacts only with NonStop SQL/MX 3.x databases. RMXCI enables you to perform daily administrative and database management tasks by running SQL statements interactively or from script files. You can also run RMXCI from a Perl or Python command-line or programs. For a list of these SQL statements, see Appendix B (page 142). RMXCI does not support the following operations: Adding, modifying, and deleting users Changing user passwords Scheduling job Issuing MXCS commands 15

16 2 Installing RMXCI The hardware and software requirements for RMXCI are described in the softdoc file delivered with the product, through the Scout website for NonStop servers through HP NonStop eservices portal ( Read the softdoc file before installing the product. RMXCI installation requirements include: SQL/MX Release 3.x on the NonStop system The following softwares on the client workstation: Java 1.5 or later HP NonStop JDBC Type 4 Driver Release 3.1 or later NOTE: For the current set of software requirements, see the softdoc file. Softdoc also lists the earlier compatible versions of the software. To install RMXCI, complete the following steps: 1. Perform the pre-installation procedures. Before installing RMXCI, Java Runtime Environment (JRE) and NonStop JDBC Type 4 Driver must be installed on the client workstation. However, installing Perl and Python is optional. Installing and verifying the Java Runtime Environment (JRE) (page 16) Installing and verifying the NonStop JDBC Type 4 Driver (page 19) (Optional) Installing Perl or Python (page 20) 2. Perform the installation procedures. Installation procedures (page 20) 3. Perform the post-installation procedures. Verifying the installed software files (page 32) Verifying the installed version of RMXCI (page 32) Setting the Look-and-Feel of RMXCI (page 33) Testing the RMXCI launch (page 39) Pre-installation procedures Installing and verifying the Java Runtime Environment (JRE) (page 16) Installing and verifying the NonStop JDBC Type 4 Driver (page 19) (Optional) Installing Perl or Python (page 20) Installing and verifying the Java Runtime Environment (JRE) RMXCI and the NonStop JDBC Type 4 Driver require a compatible Java version to be installed on the client workstation. JRE 1.5 and later Java versions are supported. JRE and earlier versions are not supported. Installing a supported Java version To install one of the supported Java versions on the client workstation, follow the instructions on the Oracle website: After installing the Java version, proceed with Verifying the Java version (page 17). 16 Installing RMXCI

17 Verifying the Java version To display the Java version of the client workstation, enter the following command: java -version For example, On Windows, enter the following command: C:\java -version The following is a sample output: java version "1.5.0_10" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_10-b03) Java HotSpot(TM) Client VM (build 1.5.0_10-b03, mixed mode, sharing) On Linux, enter the following command: /usr/home:java -version The following is a sample output: java version "1.6.0_17" OpenJDK Runtime Environment (IcedTea ) (rhel-1.39.b17.el6_0-i386) OpenJDK Server VM (build 14.0-b16, mixed mode) If the returned version is not supported or is unavailable, see Setting the PATH for a supported Java version on Linux (page 19) for Linux or Setting the PATH for a supported Java version on Windows for Windows. Setting the PATH for a supported Java version on Windows 1. Right-click the My Computer icon on your desktop and select Properties. 2. Select the Advanced tab in the System Properties dialog box. 3. Click Environment Variables. Pre-installation procedures 17

18 4. Select the Path variable and then click Edit. 5. Place the cursor at the beginning of the Variable value: field. Enter the path of the Java bin directory, ending with a semicolon (;). 18 Installing RMXCI

19 NOTE: Ensure that there is no space after the semicolon (;) in the path. If there are spaces in the directory name, delimit the entire directory path in double quotes (") before the semicolon. For example, "C:\Program Files\Java\jdk1.5.0_10\bin";. 6. Click OK. 7. Verify that the updated Path appears in System variables, and click OK. 8. Click OK to accept the changes in the System Properties dialog box. Setting the PATH for a supported Java version on Linux 1. In the /home directory, open the user profile (.profile or.bash_profile). For example, using vi command, the following command opens the.profile file: /home:vi.profile 2. In the user profile, set the PATH environment variable to include the path of the Java bin directory. For example, export PATH=/opt/java1.5/jre/bin:$PATH NOTE: Place the path of the Java bin directory before $PATH, and ensure that no space is after the colon (:) in the path. In the C shell, use the setenv command instead of export. 3. To activate the changes, either log out and log in again or run the user profile command. For example: /home:..profile Installing and verifying the NonStop JDBC Type 4 Driver RMXCI requires a compatible NonStop JDBC Type 4 Driver Release 3.x to be installed on the client workstation. Installing the JDBC Driver To install the HP NonStop JDBC Type 4 Driver, complete the steps listed in Release 3.x of HP NonStop JDBC Type 4 Driver Programmer s Reference or the README file. Include the NonStop JDBC Type 4 Driver JAR file in the CLASSPATH. Verifying the JDBC Driver To display the version of the NonStop JDBC Type 4 Driver, which is already installed on the client workstation, complete the following steps: 1. Change to the lib directory, which contains the NonStop JDBC Type 4 Driver JAR file: On Windows, enter the following command: cd jdbc-installation-directory\lib On Linux, enter the following command: where: cd jdbc-installation-directory/lib jdbc-installation-directory is the NonStop JDBC Type 4 Driver installation directory. Pre-installation procedures 19

20 2. To view the version information, enter the following command: java -jar t4sqlmx.jar For example, On Linux, enter the following command: home:cd /usr/home/install/t4jdbc/lib/java -jar t4sqlmx.jar /usr/home/install/t4jdbc/lib/:java -jar t4sqlmx.jar The following is a sample output: T1249_V32_30AUG12_HP_NONSTOP(TM)_JDBCT4_2012_04_18 /usr/home/install/t4jdbc/lib/: On Windows, enter the following command: C:\>cd install\t4sqlmx\lib C:\install\t4sqlmx\lib>java -jar t4sqlmx.jar The following is a sample output: T1249_V32_30AUG12_HP_NONSTOP(TM)_JDBCT4_2012_04_18 C:\install\t4sqlmx\lib> If the JAR file is inaccessible or the returned version is not supported, see Installing the JDBC Driver (page 19). (Optional) Installing Perl or Python If you plan to use Perl or Python scripts with RMXCI, verify that you have Perl or Python installed on the client workstation. RMXCI supports the following versions of Perl and Python: Perl Python If you do not have Perl or Python, download it from any open source software provider website. You can perform this installation procedure anytime either before or after installing RMXCI. If you plan to run the sample scripts provided with RMXCI, verify that you have the Perl JavaServer and Jython (Java implementation of Python) installed on your client workstation. The RMXCI installation attempts to automatically download and install both the Perl JavaServer and Jython open source extensions. To download them manually, see the README file in the samples directory. Installation procedures Before following the installation procedures, you must install the NonStop SQLMX JDBC Type 4 Driver on the client workstation. For more information, see Pre-installation procedures (page 16). Downloading the Installer (page 20) Verifying the installer file version (page 22) Installing RMXCI (page 22) Downloading the Installer The RMXCI installer is available as rmxciinstaller.jar file. You can perform the following steps to download the installer: 1. On the NonStop system, logon to the TACL environment. 2. Navigate to the required volume to locate the RMXCI product by using the following command: TACL>VOLUME $SYSTEM.ZMXODBC 20 Installing RMXCI

21 3. Locate the file with the name T0774ZIP by using the following command: $SYSTEM.ZMXODBC> fileinfo T0774ZIP 4. To transfer the file to your client workstation by using a binary mode, use any of the available tool or use ftp command on the command prompt. 5. You must rename the file T0774ZIP to rmxci.zip. 6. The file rmxciinstaller.jar is available within the rmxci zip file. To extract the Installer on a Linux system, use the following command on a Linux command window: /usr/home/rmxci:unzip rmxci.zip On a Windows workstation, you can use the following steps to unzip the RMXCI installer. 1. The file rmxciinstaller.jar is available within the ZIP file rmxci.zip. 2. Unzip the rmxci.zip file to the download directory. Installation procedures 21

22 Verifying the installer file version To display the version of the installer file, complete the following steps: 1. Change to the directory, which contains the RMXCI installer file: cd installer-directory where, installer-directory is the directory where you downloaded the installer. 2. Enter the following command to get the version information: java -jar rmxciinstaller.jar v For example, C:\>cd RMXCI C:\RMXCI>java -jar rmxciinstaller.jar v The following is a sample output: T0774_V32_30AUG12_HP_NONSTOP(TM)_RMXCI_2011_12_12 C:\RMXCI> Installing RMXCI Before following the installation procedures, you must install the NonStop SQLMX JDBC Type 4 Driver on the client workstation. For more information, see Pre-installation procedures (page 16). You can run the installer from the Installer Wizard Graphical User Interface (GUI) or from the command line. Launching the Installer Wizard: NOTE: To run the Installer Wizard on Linux, the X Window system must be installed on the client workstation. If the client workstation does not have the X Window system, you can install from the command line. 1. Locate the rmxciinstaller.jar file in the folder where you downloaded the installer. 2. Verify that the rmxciinstaller.jar file appears as an Executable JAR file. If not, skip the next two steps. 3. Double-click the rmxciinstaller.jar file icon to launch the Installer Wizard. 4. Proceed to the steps listed in the procedure Running the Installer Wizard. 5. At the command prompt, change to the directory where you downloaded the installer: cd installer-directory where, installer-directory is the directory where you downloaded the installer. 22 Installing RMXCI

23 6. Launch the Installer Wizard with the following command: java -jar rmxciinstaller.jar Running the Installer Wizard When you run rmxciinstaller.jar, the Installer Wizard appears. 1. Select Standard Installation to start the Installer Wizard. The Installer Wizard guides you through installing both the core RMXCI components and the optional open source extensions. For a quick installation of the core RMXCI files, choose Core Components. If you have already installed the core RMXCI files, but want to install only the open source extensions, choose Optional Components. 2. After you select the install components, you must select the NonStop SQL/MX JDBC Type 4 Driver and RMXCI install directories. Installation procedures 23

24 3. To locate the NonStop SQL/MX JDBC Driver JAR file, click Browse. 4. Select t4sqlmx.jar and click Select. The Installer Wizard displays the path of the NonStop JDBC Type 4 Driver JAR file. 24 Installing RMXCI

25 5. To install in the default location, skip the next two steps. To install in a different location, proceed to the next step. 6. To find an installation location for RMXCI, click Browse. 7. Select the folder where you want to install RMXCI so that the directory path appears in the File Name box, and click Select. Installation procedures 25

26 The Installer Wizard displays the directory where RMXCI will be installed. 8. Click Next to review the open source disclaimer. 9. If you agree to the terms and conditions, select the check box and click Next. The Installer Wizard dialog box appears, showing which components are available for you to download and install. 10. Select the optional components to be downloaded and installed. 11. If you want to change the download URL for the extensions, click Edit URL and the following dialog box appears: 26 Installing RMXCI

27 NOTE: Perl and Python must be installed for the corresponding extensions to work. Select the proxy information as required to download the open source extensions. If you do not require a proxy server, skip the next two steps. 12. To configure the proxy settings, select Use the following proxy settings:. RMXCI installer attempts to auto-detect your proxy settings. 13. Click Detect Proxy Server(s) to list the available proxy servers. If RMXCI installer detects one or more proxy servers, they are displayed. 14. Click Install to start the installation. After the core RMXCI files are installed, the Installation Status dialog box appears indicating how many files got extracted to the installation directory. 15. After the core RMXCI files are installed, the installer attempts to download and install the components. The progress bar indicates the download progress of each file. In addition, an installation log provides details about the status of the download and installation of the components. Installation procedures 27

28 The following screen appears when the installation completes. 16. Click Exit. Command-line installation procedure The command-line installation steps are common to Linux and Windows platforms. 28 Installing RMXCI

29 1. At the command prompt, change to the directory where you downloaded the installer:cd installer-directory where, installer-directory is the directory where you have downloaded the installer. 2. Before launching the command-line installer, see the command options by using the -help option: java jar rmxciinstaller.jar help Usage: java jar <installer jar> [ help] <-cm -silent> [-jdbcfile <jdbc filename>] [-installdir <install Dir>] NOTE: The -silent option installs the client without prompting you for other options. The following is a sample install command on Windows: java -jar rmxciinstaller.jar -silent -jdbcfile C:\t4sqlmx.jar -installdir C:\ The -jdbcfile and -installdir are optional parameters, and the defaults are listed for them in the following table: Table 1 Installation Defaults OS Windows Linux jdbcfile C:\t4sqlmx.jar /usr/local/rmxci/t4sqlmx.jar installdir C:\Program Files\Hewlett-Packard\SQLMX Command Interface /usr/local 3. Launch the command-line installer: java -jar rmxciinstaller.jar cm The command-line installer starts and prompts you to enter the type of installation. Choose one of the following options: For a standard installation, type Y, and then click Enter. To install the optional components, type N, and then click Enter. NOTE: In the following steps, all items in square braces are default values. To accept the default value, click Enter. Installation procedures 29

30 4. Enter the full directory path and file name of the NonStop JDBC Type 4 Driver JAR file, t4sqlmx.jar which is located in the NonStop JDBC Type 4 Driver lib directory. The following is a sample display for Windows installation: NonStop(TM) SQLMX JDBC Type 4 Driver JAR File Enter the location and file name [C:\t4sqlmx.jar]: C:\install\t4sqlmx\lib\t4sqlmx.jar The following is a sample display for Linux installation:: NonStop(TM) SQLMX JDBC Type 4 Driver JAR File Enter the location and file name [/home/mydir/lib/t4sqlmx.jar]: /home/mydir/lib/t4sqlmx.jar 5. Enter the name of an existing directory where you want to install RMXCI. The following is a sample display for Windows installation: NonStop(TM) SQL/MX Remote Conversational Interface Enter the installation directory [C:\Program Files\Hewlett-Packard\SQLMX Command Interface]: The following is a sample display for Linux installation:: NonStop(TM) SQLMX JDBC Type 4 Driver JAR File Enter the location and file name [/home/mydir/install]: /home/mydir/install The installation status appears as follows on Windows: Extracted 16 files from the C:\RMXCI\rmxciInstaller.jar archive into the C:\Program Files\Hewlett-Packard\SQLMX Command Interface directory. Core RMXCI files installed. 6. If you do not want to download and install the optional components, type N at the prompt and your installation is complete. Otherwise, proceed through the remaining installation steps as follows: Do you want to install the optional components? [Y]: 7. Type Y, and then click Enter if you agree to the terms. If you are performing an optional install only, you are prompted to enter a valid RMXCI installation directory. Use a proxy server? [N]: 30 Installing RMXCI

31 If you do not require a proxy server, skip the step for detecting the proxy server, and proceed with the installation. 8. RMXCI can attempt to detect your proxy settings. If proxy servers are found, they are displayed as follows: Use a proxy server? [Y]: Y Attempt to auto-detect proxy server(s)? [Y]: N Enter the proxy server (do not include the port): myproxyserver.com Enter the proxy port: The install prompts you to indicate which optional components you want to download and install. It also allows you to change the download URL. Install Perl JavaServer extensions? [Y]: Perl JavaServer requires 3 files: Java.pm, JavaArray.pm, and JavaServer.jar URL of the folder which contains these files [ Install Perl XML SAX Module? [Y]: Perl SAX XML Module URL (PerlSAX.pm) [ Install Jython, a Java implementation of Python? [Y]: Jython URL (jython_installer-2.2.jar) [ The setup is now ready to attempt the download and installation of the optional open source components. As each component is retrieved, dots (...) appear to indicate the progress of the download as follows: Downloading Perl JavaServer [1 of 3] - Java.pm % Downloading Perl JavaServer [2 of 3] - JavaArray.pm % Downloading Perl JavaServer [3 of 3] - JavaServer.pm % Successfully added settings.pl Downloading Perl XML SAX Module [1 of 1] - PerlSAX.pm % Downloading Jython [1 of 1] - jython_installer-2.2.jar % Successfully Installed Jython. Successfully added settings.py. RMXCI Installation Complete. Installation procedures 31

32 Post-installation procedures This section describes the steps to verify the installation: Verifying the installed software files (page 32) Verifying the installed version of RMXCI (page 32) Testing the RMXCI launch (page 39) Verifying the installed software files After downloading and running the installer file, rmxciinstaller.jar, verify that the RMXCI software files are installed in the correct locations as described in Table 2 (page 32). Table 2 Locations of RMXCI Software Files Directory install-directory>rmxci>bin install-directory>rmxci>lib install-directory>rmxci>lib>perl install-directory>rmxci>lib>python install-directory>rmxci>samples Files rmxci.cmd rmxci.sh rmxci.pl rmxci.py rmxci.jar Session.pm Session.py arraydml.pl arrayiq.pl README sample.pl sample.sql sampletables.pl sampletables.py sampleddl.py sampledml.py Description Windows launch file Linux launch file Perl wrapper script Python wrapper script. (To run the script, see Perl and Python wrapper scripts (page 74).) Product JAR file Product file Product file Runs DML statements and returns results in an array format written in Perl Executes interface commands and returns results in array format written in Perl Readme file that describes how to use the sample scripts Sample Perl program Sample SQL script Sample perl file that lists all tables and respective rowcounts. (The file can accept a command-line wildcard parameter.) Sample python file that lists all tables and respective rowcounts. (The file accepts a command-line wildcard parameter.) Sample python file that uses Jython to run DDL statements Sample python file that uses Jython to run DML statements Verifying the installed version of RMXCI To display the installed version of RMXCI without launching the Remote Conversational Interface and connecting to the database, complete the following steps: 32 Installing RMXCI

33 1. Go to the lib directory, which contains the RMXCI JAR file: On Windows, enter the following command: C:\>cd rmxci-installation-directory\rmxci\lib On Linux, enter the following command: where, /home:cd rmxci-installation-directory/rmxci/lib rmxci-installation-directory is where you installed the RMXCI software files. 2. To obtain the version information, enter the following command: java -jar rmxci.jar For example, C:\>cd install/rmxci/lib C:\install\rmxci\lib>java -jar rmxci.jar The following is a sample output: T0774_V32_30AUG12_HP_NONSTOP(TM)_RMXCI_2011_12_12 C:\install\rmxci\lib> If the JAR file is inaccessible or the returned version is not supported, see Installation procedures (page 20). To display the installed versions of RMXCI and the NonStop JDBC Type 4 Driver in the Remote Conversational Interface: 1. Launch RMXCI. For details, see Chapter 3 (page 41). 2. To display information about the build versions, enter the following command: SQL>version The following is a sample output: NonStop SQLMX Version : 3.2 NonStop Connectivity Services : 3.2 NonStop JDBC Type 4 Driver : T1249_V32_30AUG12_HP_NONSTOP(TM)_JDBCT4_2012_04_18 RMXCI Version : T0774_V32_30AUG12_HP_NONSTOP(TM)_RMXCI_2011_12_12 If the RMXCI session is not connected to the database, RMXCI displays the following sample output: SQL>version NonStop JDBC Type 4 Driver : T1249_V32_30AUG12_HP_NONSTOP(TM)_JDBCT4_2012_04_18 RMXCI Version : T0774_V32_30AUG12_HP_NONSTOP(TM)_RMXCI_2011_12_12 Setting the Look-and-Feel of RMXCI You can use the -DrmxciLF property to configure the RMXCI display and the formatting of status messages. This property does not restrict the SQL statements, commands, or syntax that you can run in RMXCI. Each look-and-feel type accepts all the SQL statements, commands, and syntax that RMXCI currently supports. Before launching RMXCI, set the -DrmxciLF property to SQLPlus. On Windows, use the following command: set _JAVA_OPTIONS=-DrmxciLF=SQLPLUS Post-installation procedures 33

34 On Linux, use the following command: export _JAVA_OPTIONS=-DrmxciLF=SQLPLUS Supported Look-and-Feel Types In addition to the default look-and-feel of RMXCI, SQLPlus and Teradata types are also supported. The following is the default look-and-feel of RMXCI: 34 Installing RMXCI

35 Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. SQL>SET SCHEMA NONSTOP.RMXCI_SAMPLE; --- SQL operation complete. SQL> To display the SQL status messages in SQLPlus look-and-feel, set the -DrmxciLF property value to SQLPlus. The following are examples of SQLPlus look-and-feel status messages: Picked up _JAVA_OPTIONS: -DrmxciLF=SQLPLUS Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Connected to Data Source: TDM_Default_DataSource SQL>SET SCHEMA NONSTOP.RMXCI_SAMPLE; Schema set. SQL> The -DrmxciLF property value for setting the Teradata look-and-feel is BTEQ. Setting this property results in a Teradata personality for the status messages logged for all SQL operations within RMXCI. The following is the Teradata look-and-feel display: Picked up_java_options: -DrmxciLF=BTEQ Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Connected to DataSource: TDM_Default_DataSource SQL>set schema NONSTOP.RMXCI_SAMPLE; *** Total Query time was 1 second. *** Schema has been set. *** Total elapsed time was 1 second(s). SQL>select * from mgrlist; *** Total Query time was 1 second. FIRST_NAME LAST_NAME DEPARTMEMT JERRY HOWARD FINANCE ROBERT WHITE PERSONNEL THOMAS RUDOLF INVENTORY MARY MILLER SHIPPING JANE RAYMOND MARKETING PAUL WINTER CANADA SALES KLAUS SAFFERT GERMNY SALES GLENN THOMAS ENGLND SALES SHERRIE WONG ASIA SALES RACHAEL MCKAY RESEARCH ERIC BROWN PLANNING ROGER GREEN CORPORATE *** Query completed. 12 rows found. 4 columns returned. *** Total elapsed time was 1 second(s). SQL> Post-installation procedures 35

36 Setting the Look-and-Feel Type You can set the look-and-feel option either from a command-line prompt or in the user profile on Linux or in the system properties on Windows. NOTE: The images shown in this section vary depending on the specific Windows version. To set the _JAVA_OPTIONS environment variable for each session: On Windows, enter the following command: set _JAVA_OPTIONS=-DrmxciLF=look-and-feel-type On Linux, enter the following command: export _JAVA_OPTIONS=-DrmxciLF=look-and-feel-type where, look-and-feel-type is one of the Supported Look-and-Feel Types (page 34). For example: export _JAVA_OPTIONS=-DrmxciLF=SQLPlus set _JAVA_OPTIONS=-DrmxciLF=BTEQ To return to the default look-and-feel, set the -DrmxciLF property value to RMXCI. If you specify an invalid value, a warning message appears and the property value is set to RMXCI. To set the look-and-feel in the system properties on Windows, complete the following steps: 1. Right-click the My Computer icon and select Properties. 2. In the System Properties dialog box, select the Advanced tab and click Environment Variables. 36 Installing RMXCI

37 3. If you do not see _JAVA_OPTIONS in the environment variables, click New... If you see _JAVA_OPTIONS, click Edit... Post-installation procedures 37

38 4. Enter _JAVA_OPTIONS for the Variable name: and -DrmxciLF property value for the Variable value:, and click OK. The Variable value: must include -DrmxciLF=look-and-feel-type. where, look-and-feel-type is one of the Supported Look-and-Feel Types (page 34). For example, -DrmxciLF=SQLPlus 5. Verify that the new or updated _JAVA_OPTIONS is set and click OK. 6. In the System Properties dialog box, click OK to accept the changes. To return to the default look-and-feel, set the -DrmxciLF property value to RMXCI. To set the look-and-feel in the user profile on Linux, complete the following steps: 1. In the /home directory, open the user profile (.profile or.bash_profile for the Bash shell). For example: /home:vi.profile 2. Add this export command (or a setenv command for the C shell) to the user profile. export _JAVA_OPTIONS=-DrmxciLF=look-and-feel-type where: look-and-feel-type is one of the Supported Look-and-Feel Types (page 34). For example: export _JAVA_OPTIONS=-DrmxciLF=SQLPlus export _JAVA_OPTIONS=-DrmxciLF=BTEQ 38 Installing RMXCI

39 3. To activate the changes, either log out and log in again or run the user profile command. For example: /home:..profile To return to the default look-and-feel, set the -DrmxciLF property value to RMXCI. NOTE: If you do not set a look-and-feel type, the default is RMXCI. Setting the trace option You can set the _JAVA_OPTIONS environment variable -Drmxci.enableTrace to enable the display of stacktrace output on the console for exceptions. To set the _JAVA_OPTIONS environment variable for each session, run the following command at the command-line prompt: On Windows, enter the following command: set _JAVA_OPTIONS=-DrmxciLF.enableTrace On Linux, enter the following command: export _JAVA_OPTIONS=-DrmxciLF.enableTrace Testing the RMXCI launch To test the installation, launch RMXCI and verify that you can connect to the database. For instructions, see Chapter 3 (page 41). The following is a sample output on successfully connecting to the database: Post-installation procedures 39

40 Picked up _JAVA_OPTIONS: -DrmxciLF=BTEQ Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Host Name/IP Address: nsksys.ind.hp.com:18650 User Name: super.super Password: Data Source Name [TDM_Default_DataSource]: Connected to Data Source: TDM_Default_DataSource SQL> If you cannot connect to the database, verify whether: 1. The SQL/MX database is available and running, the port number is correct for the database platform, and you are authorized to log in to that database platform. 2. The version of the NonStop JDBC Type 4 Driver is compatible with the Java Runtime Environment (JRE) of the workstation. See Installing and verifying the Java Runtime Environment (JRE) (page 16). 3. You installed the RMXCI software files correctly. See Verifying the installed software files (page 32). 40 Installing RMXCI

41 3 Launching RMXCI This chapter describes how to launch RMXCI : Launching RMXCI on Windows using graphic tools (page 41) Launching RMXCI on Linux (page 43) Logging in to the database platform (page 44) Using optional launch parameters (page 47) Launching RMXCI without connecting to the database (page 52) Running RMXCI with -version (page 52) Running RMXCI with -help (page 53) Exiting RMXCI (page 53) For information about launching RMXCI from Perl or Python, see Chapter 6 (page 72). Launching RMXCI on Windows using graphic tools You can launch RMXCI on Windows from command prompt, using shortcut or directly from the RMXCI bin folder. Launching RMXCI from bin folder: 1. Find the Windows launch file, rmxci.cmd, in the RMXCI bin folder. 2. Double click the rmxci.cmd file. The RMXCI appears, prompting you to enter the host name or IP address and port number of the service you want to connect, the user name, password and a data source name. For details, see Logging in to the database platform (page 44). Launching RMXCI from a shortcut: NOTE: The images shown in this section may vary depending on the version of Windows. 1. Right-click the desktop and select New > Shortcut: 2. Enter the location of rmxci.cmd within double quotes ( ) or click Browse... to locate the file, and then click Next >. 3. Enter a name for the shortcut and click Finish. Launching RMXCI on Windows using graphic tools 41

42 4. If required, specify optional launch parameters for the shortcut: 1. Right-click the shortcut icon and select Properties. 2. Select the Shortcut tab. 3. In the Target:, insert a space after rmxci.cmd and add the optional launch parameters. For more information, see Using optional launch parameters (page 47). 4. Click OK. 42 Launching RMXCI

43 5. To launch RMXCI, double-click the shortcut icon. The RMXCI appears. If you have not set the optional launch parameters, RMXCI prompts you to enter the host name or IP address and port number of the service you want to connect, the user name, password and a data source name. For details, see Logging in to the database platform (page 44). Launching RMXCI on Windows from command prompt: You can specify the path to rmxci.cmd or go to that location as shown below to invoke rmxci.cmd: If you have not set the optional launch parameters, RMXCI prompts you to enter the host name or IP address and port number of the service you want to connect, the user name, password and a data source name. For details, see Logging in to the database platform (page 44). For information on adding optional launch parameters, see Using optional launch parameters (page 47). Launching RMXCI on Linux From the client terminal window, run the following command: /home:./rmxci-installation-directory/rmxci/bin/rmxci.sh where: rmxci-installation-directory is where you have installed the RMXCI software files. For more information, see Table 2 (page 32). Setting the rmxci.sh PATH To enable a user to launch RMXCI anywhere on the Linux workstation: 1. In the /home directory, open the user profile (.profile or.bash_profile for the Bash shell), for example: /home:vi.profile 2. In the user profile, set the PATH environment variable to include the path of the rmxci.sh file, for example: export PATH=rmxci-installation-directory/rmxci/bin:$PATH where: rmxci-installation-directory is where you have installed the RMXCI software files. For more information, see Table 2 (page 32). Ensure that there is no space after the colon (:) in the path. Launching RMXCI on Linux 43

44 3. To activate the changes, either log out and log in again or run the user profile command. For example: /home:..profile 4. To launch RMXCI, from the client terminal window, run rmxci.sh: /home:rmxci.sh Ensure that rmxci.sh has execute permissions with ls -l command. You can set the permissions with chmod command. RMXCI appears, prompting you to enter the host name or IP address of the NonStop database system, user name, password and a data source name. For more information, see Logging in to the database platform (page 44). NOTE: To enable all users to launch RMXCI anywhere on the system, create a symbolic link to the rmxci.sh file in the /usr/bin or /usr/local/bin directory: /home:ln -s./rmxci-installation-directory/rmxci/bin/rmxci.sh /usr/bin/rmxci.sh Creating this symbolic link is optional. Presetting the optional launch parameters To preset the optional launch parameters for each session, use an alias in the shell command, for example: alias rmxci='rmxci.sh -h nsksys.ind.hp.com: u dba1 -p xxxxxx -dsn DataSourceName' You can add the alias rmxci to the user profile, or you can enter it at a command prompt. For more information about the optional launch parameters, see Using optional launch parameters (page 47). Logging in to the database platform Default login This section describes how to log in to the NonStop SQL/MX database platform. Default login (page 44) Login parameters (page 47) NOTE: You must be authorized to log in to the NonStop system. 1. After you launch RMXCI, RMXCI shows the welcome banner and prompts you to enter the host name or IP address of the NonStop system: 44 Launching RMXCI

45 Host Name/IP Address: Enter a host name: host-name[:port-number] Enter a port-number: host-name[:port-number] If you do not specify a port number, RMXCI uses the default port number Ensure that a service has started on port Or enter an IP address: IP-address[:port-number] 2. Enter your user name. 3. Enter your password. 4. Enter the name of a data source that is available and started. If you do not enter a data source, by default, RMXCI connects to TDM_Default_DataSource. If TDM_Default_DataSource or any data source which you specify is not started, RMXCI returns an error and prompts you to close the session. If you specify a data source that does not exist, RMXCI returns a warning and connects to TDM_Default_DataSource. After you finish logging in to the SQL/MX database, the SQL prompt appears as shown: Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Host Name/IP Address: nsksys.ind.hp.com:18650 User Name: super.super Password: DataSource Name [TDM_Default_DataSource]: Connected to DataSource: TDM_Default_DataSource SQL> At the prompt, you can enter an SQL statement or a RMXCI command. For more information, see Chapter 4 (page 54). NOTE: RMXCI enables you to re-enter the login parameters with a maximum of three retries, before it exits from the session. The retry logic is applied as follows: If a connection fails due to an invalid host name, RMXCI prompts only for the host name parameter. If the login fails due to invalid user name or password, RMXCI prompts only for the user name and password. If the login fails with an error stating that the data source is not started, RMXCI does not prompt for the options again. If all the login parameters are invalid, RMXCI prompts only for the host name. When a valid host name is entered, RMXCI prompts for the user name and password. The retry logic applies to connect and reconnect commands. For the reconnect command, this applies only when no prior connection has been established (-noconnect). For more information, see RECONNECT command (page 102). If the -q parameter or -version is included on the command line, RMXCI does not prompt for retries. If the -s parameter is included on the command line, RMXCI prompts for retries. Logging in to the database platform 45

46 Any sessions using redirected or piped input are not prompted for retries. This example shows an invalid host name. RMXCI then prompts for the host name, followed by the user name and password, as shown: rmxci h dd Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Unknown Host: dd Host Name/IP Address: User Name: super.super Password: DataSource Name [TDM_Default_DataSource]: Connected to DataSource: TDM_Default_DataSource SQL> This example shows a valid user name and an invalid password. RMXCI prompts for the host name. With a valid host name, an error is returned for the invalid password. RMXCI then prompts for user name and password, as shown: rmxci u super.super p serv Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Host Name/IP Address: DataSource Name [TDM_Default_DataSource]: MyDataSource Invalid authorization specification User Name: super.super Password: Connected to DataSource: MyDataSource SQL> This example shows a valid host name, user name and data source. RMXCI prompts only for the user name and password. After three unsuccessful retries, the session is terminated as shown: rmxci h u super.super p x dsn TDM_Default_DataSource Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Invalid authorization specification User Name: super.super Password: Invalid authorization specification User Name: super.super Password: Invalid authorization specification This example shows the connect command with a valid user name, host name and data source. RMXCI prompts only for the user name and password because the password is invalid. SQL>connect TDM_Default_DataSource 46 Launching RMXCI

47 Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Invalid authorization specification User Name: super.super Password:abc Connected to DataSource: TDM_Default_DataSource SQL> After you finish logging in to the NonStop SQL/MX database, the SQL prompt appears, as shown: Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Host Name/IP Address: nsksys.ind.hp.com:18650 User Name: super.super Password: DataSource Name [TDM_Default_DataSource]: Connected to DataSource: TDM_Default_DataSource SQL> At the prompt, you can enter an SQL statement or a RMXCI command. For more information, see Chapter 4 (page 54). Login parameters Instead of the default method of logging in to the NonStop SQL/MX database platform, use the login parameters -h (or -host), -u (or -user), -p (or -password), -dsn, -q (or -sql), -s, (or -script), -noconnect, -version and -help when launching RMXCI. For more information, see Logging in when launching RMXCI (page 48). Using optional launch parameters To customize how to launch and log in to RMXCI, use these optional parameters: Launch Parameter {-h -host} host-name[:port-number]{-h -host} IP-address[:port-number] {-u -user} user-name {-p -password} password -dsn data-source-name Description Specifies the host name or IP address of the database platform to which you want to connect the client. If you do not specify a port number, RMXCI uses the default port number Ensure that there is a service started on port For more information, see Logging in when launching RMXCI (page 48). Specifies the user name to log in to the database platform. For more information, see Logging in when launching RMXCI (page 48). Specifies the password for the user name to log in to the database platform. For more information, see Logging in when launching RMXCI (page 48). Specifies the name of a data source. If TDM_Default_DataSource or any data source that you specify is not started, RMXCI returns an error and prompts you to close the session. If you specify a data source that does not exist, RMXCI returns a warning and connects to TDM_Default_DataSource instead. For more information, see Logging in when launching RMXCI (page 48). Logging in to the database platform 47

48 Launch Parameter {-q -sql} "command" {-s -script} script-file-name -noconnect -version -help Description Specifies that an SQL statement or a RMXCI command be run when launching the SQL/MX Remote Conversational Interface. You cannot specify this parameter at the same time as the -s or -script parameter. For more information, see Running a command when launching RMXCI (page 49). Specifies that a script file be run when launching RMXCI in interactive mode. You cannot specify this parameter at the same time as the -q or -sql parameter. For more information, see Running a script file when launching RMXCI (page 50). Launches a RMXCI session without connecting to the database platform. For more information, see Launching RMXCI without connecting to the database (page 52) Displays the build version of RMXCI and the NonStop JDBC Type 4 Driver. Upon completion of the display, the client exits. If any other parameters are included with the -version parameter, they are ignored. For more information, see Running RMXCI with -version (page 52). Displays a list of accepted parameters with descriptions and then exits. For more information, see Running RMXCI with -help (page 53). Logging in when launching RMXCI To avoid entering a host name, user name, password, or data source when RMXCI launches, use the -h (or -host), -u (or -user), -p (or -password), or -dsn command-line parameters. NOTE: You can include these parameters in a shortcut to the rmxci.cmd file or in a launch file for the rmxci.sh file. For more information, see Launching RMXCI on Windows using graphic tools (page 41) or Presetting the optional launch parameters (page 44)". On Linux, run the following commands: /home:cd rmxci-installation-directory/rmxci/bin /home/usr/rmxci/bin:./rmxci.sh -h nsksys.ind.hp.com: u dba1 -p xxxxxx -dsn DataSourceName On Windows, run the following commands: where, C:\cd rmxci-installation-directory\rmxci\bin c:\rmxci\bin>rmxci.cmd -h nsksys.ind.hp.com: u dba1 -p xxxxxx -dsn DataSourceName rmxci-installation-directory is where you have installed the RMXCI software files. For example, The Remote Conversational Interface launches and prompts you to enter an SQL statement or the RMXCI command as shown: 48 Launching RMXCI

49 Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Connected to DataSource: TDM_Default_DataSource SQL> Running a command when launching RMXCI To run an SQL statement or an RMXCI command when launching the SQL/MX Remote Conversational Interface, use the -q or -sql command line parameter. This parameter enables you to run a single command on the command-line without having to enter commands in RMXCI. NOTE: You cannot specify this parameter at the same time as the -s or -script parameter. When using -q or -sql, you must enclose the command in double quotes. The SQL terminator is not required at the end of an SQL statement and is not allowed after an RMXCI command. Although you can run any of the RMXCI commands with -q or -sql, obey, and prun commands are the most useful. For a list of supported SQL statements, see Appendix B (page 142). Example of running an SQL statement with -q or -sql When launching RMXCI, use -q or -sql with the create schema statement to create a schema. On Linux, run the following command: /home:cd rmxci-installation-directory/rmxci/bin On Windows, run the following command: c:\cd rmxci-installation-directory\rmxci\bin where, rmxci-installation-directory is the location where you have installed the RMXCI software files. For example, /home/usr/rmxci on Linux. On Linux, the following command creates the schema persnl in the default catalog NONSTOP_SYSTEM_NSK: NOTE: If the default catalog does not exist, login as super.super user and create the catalog. /home/usr/rmxci/bin:./rmxci.sh -q "create schema persnl" On Windows, the following command creates the schema persnl in the default catalog NONSTOP_SYSTEM_NSK: c:\rmxci\bin>rmxci.cmd -q "create schema persnl" After you enter the SQL statement, RMXCI launches and prompts you to log in by default (if you did not specify -h, -u, -p, and -dsn on the command line), runs the SQL statement, and then returns to the command prompt, as shown: Logging in to the database platform 49

50 Host Name/IP Address: nsksys.ind.hp.com:18650 User Name: super.super Password: DataSource Name [TDM_Default_DataSource]: --- SQL operation complete. Example of running an RMXCI command with -q or -sql To run multiple script files simultaneously from the command line, use -q or -sql options with the prun command. For more information, see PRUN command (page 99). On Linux, enter the following commands: /home:cd rmxci-installation-directory/rmxci/bin /home/usr/rmxci/bin:./rmxci.sh -q "prun" On Windows, enter the following commands: C:\cd rmxci-installation-directory\rmxci\bin C:\rmxci\bin>rmxci.cmd -q "prun" where, rmxci-installation-directory is the location where you have installed the RMXCI software files. After you enter the RMXCI command, the SQL/MX Remote Conversational interface launches and prompts you to log in by default (if you did not specify -h, -u, -p, and -dsn on the command line), and runs the command. The parallel run operation prompts you to enter the settings and then runs script files. At the end of the PRUN operation, RMXCI returns to the command prompt. For more information about the PRUN operation, see PRUN command (page 99). Running a script file when launching RMXCI To run a script file when launching RMXCI, use the -s or -script command-line parameter. NOTE: You cannot specify this parameter at the same time as the -q or -sql parameter. After you launch RMXCI with -s or -script, RMXCI runs the script file in an interactive mode. RMXCI remains open until you run an exit, quit, or disconnect command. To quit the interface immediately after executing a script file, include the exit, quit, or disconnect command at the end of the script file. Example of a script file You can create a script file that contains set commands, which customizes a session when you launch RMXCI as shown: For more information, see Creating a script file (page 69). Example of running a script file with -s or -script On Linux, enter the following commands: 50 Launching RMXCI

51 /home:cd rmxci-installation-directory/rmxci/bin /home/usr/rmxci/bin:./rmxci.sh -s settings.txt On Windows, enter the following commands: C:\cd rmxci-installation-directory\rmxci\bin C:\rmxci\bin>rmxci.cmd -s settings.txt where, rmxci-installation-directory is the location where you have installed the RMXCI software files. Specify the full path of the script file if it is outside the directory of rmxci.sh or rmxci.cmd. The RMXCI launches and prompts you to log in by default (if you did not specify -h, -u, -p, and -dsn on the command line), and runs the commands in the script file as shown: Logging in to the database platform 51

52 Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Host Name/IP Address: nsksys.ind.hp.com:18650 User Name: super.super Password: DataSource Name [TDM_Default_DataSource]: Connected to DataSource: TDM_Default_DataSource SQL>SET IDLETIMEOUT 0 SQL>SET SQLPROMPT * *SET TIME ON * 14:14:57 *SET TIMING ON 2:14:57 PM *SET SQLTERMINATOR. 2:14:57 PM * Launching RMXCI without connecting to the database To start RMXCI without connecting to the database, use the -noconnect option. Example of launching RMXCI with -noconnect On Linux, run these commands: /home:cd rmxci-installation-directory/rmxci/bin /home/usr/rmxci/bin:./rmxci.sh -noconnect On Windows, enter the following commands: C:\cd rmxci-installation-directory\rmxci\bin C:\rmxci\bin>rmxci.cmd -noconnect where, rmxci-installation-directory is the location where you have installed the RMXCI software files. Running RMXCI with -version To display the build versions of RMXCI and NonStop JDBC Type 4 Driver, use the -version option. If any other parameters are included with the -version parameter, they are ignored. Example of running RMXCI with -version On Linux, enter the following commands: /home:cd rmxci-installation-directory/rmxci/bin /home/usr/rmxci/bin:./rmxci.sh -version On Windows, enter the following commands: C:\cd rmxci-installation-directory\rmxci\bin C:\rmxci\bin>rmxci.cmd -version where, rmxci-installation-directory is where you have installed the RMXCI software files, for example, on Linux, /home/usr/rmxci. The following is a sample output: Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. 52 Launching RMXCI

53 NonStop JDBC Type 4 Driver : T1249_V32_30AUG12_HP_NONSTOP(TM)_JDBCT4_2012_04_18 RMXCI Version : T0774_V32_30AUG12_HP_NONSTOP(TM)_RMXCI_2011_12_12 Running RMXCI with -help To display a list of acceptable parameters, including proper usage information, use the -help option. After displaying this information, the application exits. Example of running RMXCI with -help On Linux, enter the following commands: /home:cd rmxci-installation-directory/rmxci/bin /home/usr/rmxci/bin:./rmxci.sh -help On Windows, enter the following commands: C:\cd rmxci-installation-directory\rmxci\bin C:\rmxci\bin>rmxci.cmd -help where, rmxci-installation-directory is the location where you have installed the RMXCI software files, for example: /home/usr/rmxci. Exiting RMXCI From the client terminal window, run one of these commands: exit quit For example, run: SQL>quit These commands are not case-sensitive and do not require a terminator before you press Enter. After you enter one of these commands, the RMXCI session is closed. Exiting RMXCI 53

54 4 Interactively running commands in RMXCI After launching the HP NonStop SQL/MX Remote Conversational Interface, you can run SQL statements and RMXCI commands in the interface. Running commands (page 54) Using RMXCI commands (page 55) Running SQL statements (page 61) Logging output (page 66) Running commands Product banner (page 54) Interface prompts (page 54) Breaking the command line (page 54) Case sensitivity (page 55) Product banner After you launch RMXCI and connect to the database, the product banner appears in the RMXCI interface. The product banner displays the data source to which you are connected, as shown: Welcome to the NonStop(TM) SQL/MX Remote Conversational Interface (c) Copyright Hewlett-Packard Development Company, LP. Connected to DataSource: TDM_Default_DataSource SQL> Interface prompts During a session, RMXCI prompts you to enter SQL statements and RMXCI commands: SQL> +> Standard prompt in SQL mode. You can change the standard prompt SQL> by using the setsqlprompt command. For more information, see Customizing the standard prompt (page 56). Continuation prompt. Continue the SQL statement from the previous line. Use the SQL terminator (a semicolon by default) to terminate an SQL statement. For more information, see Setting and showing the SQL terminator (page 57). NOTE: RMXCI commands must be entered in one line and do not require an SQL terminator. Breaking the command line You cannot break a RMXCI command over multiple lines. Each RMXCI command must be entered in one line. Enter the SQL terminator, and then re-enter the command in one line if you break a RMXCI command across more than one line. You can continue any SQL statement over multiple lines, breaking that statement at any point except within a word, a numeric literal or a multi-character operator (for example, <=). To break a string literal in a DML statement, use a concatenation operator. For example, you can use the concatenation operator as follows: SQL>select * from t where ch1 = 'abcdefg' +> 'jk'; where ch1 is a char(10) column of table t. 54 Interactively running commands in RMXCI

55 For more information, see the concatenation operator in the SQL/MX Release 3.x Reference Manual. To terminate an SQL statement that spans multiple lines, use the SQL terminator for the session. A syntax error is returned, if more than one SQL statement is included in the same line. For more information, see Setting and showing the SQL terminator (page 57). Case sensitivity In the RMXCI interface, you can enter SQL statements and RMXCI interface commands in uppercase, lowercase, or mixed-case characters. Command or statement parts, which you enclose in single quotes (') or double quotes ( ) are case sensitive. All other parts of statements and commands are case-insensitive. Using RMXCI commands The RMXCI commands enable you to customize the SQL/MX Remote Conversational Interface (for example, by using set commands) or return information about the interface settings or database objects (for example, by using show commands): Showing the session attributes (page 55) Setting and showing the idletimeout value for the session (page 56) Customizing the standard prompt (page 56) Setting and showing the SQL terminator (page 57) Displaying the elapsed time (page 57) Setting and showing the current schema (page 58) Limiting the result set of a query (page 58) Showing information about SQL database objects (page 59) Displaying run commands (page 60) Editing and rerun a command (page 60) Clearing the interface window (page 60) Obtaining help (page 61) For more information about the RMXCI commands, see Appendix A (page 76). NOTE: Each RMXCI command must be entered in one line. Enter the SQL terminator, and then re-enter the command in one line if you break a RMXCI command across more than one line. Showing the session attributes To display the attributes and settings of the current RMXCI session, use the env, show session or session command. For example, the following session command displays the session attributes: Using RMXCI commands 55

56 SQL>session COLSEP " " DATASOURCE TDM_Default_DataSource HISTOPT DEFAULT [No expansion of script files] IDLETIMEOUT 30 min(s) LIST_COUNT 0 [All Rows] LOG OFF LOOK AND FEEL RMXCI MARKUP RAW PROMPT SQL> CATALOG NONSTOP_SYSTEM_NSK SCHEMA PUBLIC_ACCESS_SCHEMA SERVER nsksys.ind.hp.com:18650 SQLTERMINATOR ; STATISTICS OFF TIME OFF TIMING OFF USER super.super SQL> For more information, see the ENV command (page 83) or SHOW SESSION command (page 132). Setting and showing the idletimeout value for the session The idle timeout value of a session determines when the session expires after a period of inactivity. To set the idle timeout value for a session, run the set idletimeout command. For example, the following command sets the idle timeout to an infinite amount of time so that the session never expires: SQL>set idletimeout 0 To show the idle timeout value which is in effect for the session, run the show idletimeout command. For example, this command displays an idle timeout of zero minutes, which means that the session never expires: SQL>show idletimeout IDLETIMEOUT 0 min(s) [Never Expires] For more information, see the SET IDLETIMEOUT command (page 110) and the SHOW IDLETIMEOUT command (page 125). Customizing the standard prompt To change the standard prompt in the RMXCI interface, use one or both of these commands: SET PROMPT command (page 116) SET TIME command (page 57) SET PROMPT command The set prompt command changes the default prompt to a specified character or string. For example, the following command changes the prompt to SQL ENTER>: SQL>set prompt "SQL ENTER>" 56 Interactively running commands in RMXCI

57 SQL ENTER> For more information, see the SET PROMPT command (page 116). SET TIME command The set time on command causes the current time of the client workstation to appear in the prompt: SQL ENTER>set time on 20:32:26 SQL ENTER> The set time off command removes the current time from the prompt: 20:32:26 SQL ENTER>set time off SQL ENTER> For more information, see the SET TIME command (page 120). Setting and showing the SQL terminator The SQL terminator symbolizes the end of an SQL statement. By default, the SQL terminator is a semicolon (;). To change the SQL terminator, run the set sqlterminator command. For example, the following command sets the SQL terminator to a period (.): SQL>set sqlterminator. SQL>insert into sales.custlist +> (select * from invent.supplier where suppnum=8) row(s) inserted. To show the SQL terminator which is in effect for the session, run the show sqlterminator command. For example, the following command displays SQLTERMINATOR., where the period (.) is the SQL terminator for the session: SQL>show sqlterminator SQLTERMINATOR. For more information, see the SET SQLTERMINATOR command (page 118) and the SHOW SQLTERMINATOR command (page 134). Displaying the elapsed time By default, RMXCI does not display the elapsed time of an SQL statement after the statement is run. To display the elapsed time after each SQL statement is run, run the following command: SQL>set timing on SQL>select suppname, street, city, state, postcode +> from invent.supplier +> where suppnum=3; SUPPNAME STREET CITY STATE POSTCODE HIGH DENSITY INC 7600 EMERSON NEW YORK NEW YORK row(s) selected. Elapsed :00:00: To prevent the elapsed time from being displayed after each SQL statement is run, run the set timing off command: SQL>set timing off For more information, see the SET TIMING command (page 120). Using RMXCI commands 57

58 Setting and showing the current schema By default, the schema of the session is PUBLIC_ACCESS_SCHEMA and catalog is NONSTOP_SYSTEM_NSK. The SQL statement set schema, allows you to set the schema for the RMXCI session. For example, the following set schema command changes the default schema to PERSNL for the session: SQL>set schema persnl; --- SQL operation complete. SQL>delete from employee where first_name='tim' and last_name='walker'; row(s) deleted. The schema, which you specify with set schema remains in effect until the end of the session or until you run another set schema statement. If you run this statement in a script file, it not only affects the SQL statements in the script file but also all the subsequent SQL statements that are run in the current session. If you set the schema in a script file, reset the default schema for the session at the end of the script file. For more information about the set schema command, see the SQL/MX Release 3.x Reference Manual. The show schema command displays the current schema for the session. For example, the following show schema command displays SCHEMA PERSNL, where PERSNL is the name of the current schema for the session: SQL>show schema SCHEMA PERSNL You can also specify the catalog where the schema resides. For example: SQL>set schema cat1.persnl; The show catalog command will show CAT1 and the show schema command shows PERSNL. If you do not specify the catalog in set schema statement, the catalog for the schema will be the catalog that appears with show catalog command. For more information, see the SHOW SCHEMA command (page 130). The set catalog command sets the current catalog. For more information about the set catalog statement, see the SQL/MX Release 3.x Reference Manual. NOTE: RMXCI uses NONSTOP_SYSTEM_NSK as the default catalog and PUBLIC_ACCESS_SCHEMA as the default schema. If you plan to use the defaults and they do not exist, then create the default catalog and schema by using super.super (255,255) id. HP recommends that you do not use the default catalog and schema. Instead, use set catalog and set schema commands to set the session defaults. Limiting the result set of a query To set the maximum number of rows to be returned by SELECT statements, which are run in the session, run the set list_count command. For example, the following command limits the result set of queries to twenty rows: SQL>set list_count 20 To show the limit, which is in effect for the session, run the show list_count command. For example, the following command shows that the number of rows returned by SELECT statements is unlimited: SQL>show list_count LISTCOUNT 0 [All Rows] 58 Interactively running commands in RMXCI

59 For more information, see the SET LIST_COUNT command (page 110) and the SHOW LIST_COUNT command (page 127). Showing information about SQL database objects Showing the schemas (page 59) Showing the tables in a schema (page 59) Showing the dependent objects of a table (page 59) Showing the views in a schema (page 59) Showing the schemas The show schemas command displays the schemas that exist in the current catalog. The following is a sample output: SQL>show schemas SCHEMA NAMES DBA001 DBA082 DBMGR DBSCRIPT_SALES DEFINITION_SCHEMA_VERSION_1200 DEMOSCH DEMOSCH1 DEMOSCH2 DEMO_SCH DEV DS_SCH D_SALES HMGR HPNVS HPNVSSCH HPNVS_SAMPLE HPNVS_SAMPLE INVENT ODBC_INVENT ODBC_PERSNL ODBC_SALES ODBC_SCHEMA ODBC_TEST PERSNL PUBLIC_ACCESS_SCHEMA ROLEDBA ROLEMGR ROLEUSER SALES SCH SERVICES T4JDBC_SCHEMA TEST1 USR SQL> For more information, see the SHOW SCHEMAS command (page 131). Showing the tables in a schema The show tables command displays the tables that exist in the current catalog and schema. For example, the following command displays all the tables in the catalog CAT1 and schema, PERSNL: SQL>show catalog CATALOG CAT1 SQL>show schema SCHEMA PERSNL SQL>show tables TABLE NAMES DEPT EMPLOYEE JOB PROJECT For more information, see the SHOW TABLES command (page 135). Showing the dependent objects of a table The showddl command displays information about the columns, indexes, and other objects such as triggers, for a specified table. For more information about the showddl command, see the SQL/MX Release 3.x Reference Manual. Showing the views in a schema The show views command displays the views that exist in the current catalog and schema. For example, the following command displays all the views in the current catalog CAT1, and schema INVENT: Using RMXCI commands 59

60 SQL>set catalog CAT1; -- SQL operation complete. SQL>set schema invent; --- SQL operation complete. SQL>show schema SCHEMA INVENT SQL>show views VIEW NAMES VIEW207 VIEW207N VIEWCS VIEWCUST For more information, see the SHOW VIEWS command (page 137). Displaying run commands To display commands that were recently run in the RMXCI session, run the history command. The history command associates each command with a number, which you can use to rerun or edit with the fc command. For more information, see Editing and rerun a command (page 60). For example, the following command displays three commands that were entered in the session: SQL>history 1> set idletimeout 0 2> set schema persnl; 3> select * from project; To save the session history in a user-specified file, run the savehist command. For example, this command saves the session history in a file named history.txt in the local directory where you are running RMXCI: SQL>savehist history.txt For more information, see the HISTORY command (page 91) and the SAVEHIST command (page 105). Editing and rerun a command To edit and rerun a command in the history buffer of an RMXCI session, run the fc command. For more information, see Displaying run commands (page 60). For example, the following fc command and the d (delete editing) command correct a SELECT statement that was entered incorrectly: SQL>fc SQL>selecct * from employee;... d SQL>select * from employee; Pressing Enter runs the corrected SELECT statement. For more information, see the FC command (page 86). Clearing the interface window After running commands in RMXCI, you can clear the interface window by using the clear command. For example, the following command clears the interface window so that only the prompt appears at the top of the window: SQL>clear For more information, see the CLEAR command (page 81). 60 Interactively running commands in RMXCI

61 Obtaining help To display help text for a command that is supported in RMXCI, run the help command. For example, the following command displays syntax and examples for the fc command: SQL>help fc For more information, see the HELP command (page 90). Running SQL statements In RMXCI, you can run SQL statements interactively. For a list of these statements, see Appendix B (page 142). This subsection shows examples of: Executing an SQL Statement (page 61) Repeating an SQL Statement (page 61) Preparing and executing SQL Statements (page 62) Executing CREATE TRIGGER statements (page 65) To run SQL statements from script files in RMXCI, see Chapter 5 (page 69). Executing an SQL Statement You can query the employee table, and return an employee s salary by executing the following SELECT statement in RMXCI: SQL>select salary from persnl.employee where jobcode=100; SALARY row(s) selected. If the SQL statement completes successfully, RMXCI returns a success message, followed by the standard prompt. If a problem occurs during the execution of the SQL statement, RMXCI returns an error message. For information about error messages, see the Error messages (page 144). Repeating an SQL Statement To run a previously run SQL statement, use the /,run or repeat command, for example: Running SQL statements 61

62 SQL>/ SALARY row(s) selected. For more information, see the / command (page 79), RUN command (page 105), or REPEAT command (page 102). Preparing and executing SQL Statements You can prepare or compile an SQL statement by using the prepare statement, and then you can run the prepared SQL statement later by using the execute statement. Preparing an SQL Statement (page 62) Setting parameters (page 63) Displaying the parameters for the session (page 63) Resetting the parameters (page 64) Executing a prepared SQL statement (page 64) Preparing an SQL Statement To compile an SQL statement for later execution, use the prepare statement. You can also use the prepare statement to check the syntax of an SQL statement without executing the statement. For example, the following statement compiles a SELECT statement named empsal and detects a syntax error: SQL>prepare empsal from +>select salary from employee +>where jobcode = 100; SQL>*** ERROR[4082] Object JAVCAT.JAVSCH.EMPLOYEE does not exist or is inaccessible. [ :39:43] *** ERROR[8822] The statement was not prepared. [ :39:43] You can then correct the syntax of the SQL statement and prepare it again: SQL>prepare empsal from +>select salary from persnl.employee +>where jobcode = 100; --- SQL command prepared. 62 Interactively running commands in RMXCI

63 To specify a parameter to be supplied later, either for a set param statement or for a using clause for an execute statement, use one of these types of parameters in the SQL statement: Named parameter, which is represented by?param-name Unnamed parameter, which is represented by a question mark (?) character For example, the following prepared SELECT statement specifies unnamed parameters for salary and job code: SQL>prepare findemp from +>select * from persnl.employee +>where salary >? and jobcode =?; --- SQL command prepared. This prepare statement prepares another SELECT statement named empcom, which has one named parameter,?dn, for the department number, which appears twice in the statement: SQL>prepare empcom from +> select first_name, last_name, deptnum from persnl.employee +> where deptnum <>?dn and salary <= (select avg(salary) from persnl.employee +>where deptnum =?dn); --- SQL command prepared. For the syntax of the prepare statement, see the SQL/MX Release 3.x Reference Manual. Setting parameters In a RMXCI session, you can set a parameter of an SQL statement (either prepared or not) by using the set param command. NOTE: The parameter name is case-sensitive. The same case used in set param command must be specified in other statements, such as DML statements or execute statement. For example, the following set param command sets a value for the parameter named?sal, which you can apply to one of the unnamed parameters in the prepared findemp statement or to a named parameter with an identical name in an SQL statement: SQL>set param?sal This SELECT statement uses sal as a named parameter: SQL>select last_name from persnl.employee +> where salary =?sal; For the syntax of the set param command, see the SET PARAM command (page 114). Displaying the parameters for the session To determine what parameters you have set in the current session, use the show param command. For example, the following command displays the recent parameter settings: SQL>show param dn 1500 sal For the syntax of the show param command, see the SHOW PARAM command (page 127). Running SQL statements 63

64 Resetting the parameters To change the value of a parameter, specify the name of the parameter in the reset param command, and then use the set param command to change the setting. For example, suppose that you want to change the salary parameter to : SQL>reset param?sal SQL>set param?sal Running the reset param command without specifying a parameter name clears all parameter settings in the session, for example: SQL>reset param SQL>show param *** ERROR[29428] No parameters found. SQL> To use the parameters, which you had set before, you must set them again in the session: SQL>set param?dn 1500 SQL>set param?sal SQL>show param dn 1500 sal SQL> For the syntax of the reset param command, see the RESET PARAM command (page 104). Executing a prepared SQL statement To run a prepared SQL statement, use the execute statement. For example, the following execute statement runs the prepared empsal statement, which does not have any parameters: SQL>execute empsal; SALARY row(s) selected. The following execute statement runs the prepared empcom statement, which has one named parameter,?dn, and was set by set param for the department number: 64 Interactively running commands in RMXCI

65 SQL>execute empcom; FIRST_NAME LAST_NAME DEPTNUM ALAN TERRY 3000 DAVID TERRY 2000 PETE WELLINGTON 3100 JOHN CHOU 3500 MANFRED CONRAD 4000 DINAH CLARK 9000 DAVE FISHER 3200 GEORGE FRENCHMAN 4000 KARL HELMSTED 4000 JOHN HUGHES 3200 WALTER LANCASTER 4000 MARLENE BONNY 4000 BILL WINN 2000 MIRIAM KING 2500 GINNY FOSTER 3300 MARIA JOSEF 4000 HERB ALBERT 3300 RICHARD BARTON 1000 XAVIER SEDLEMEYER 3300 DONALD TAYLOR 3100 LARRY CLARK 1000 JIM HERMAN 3000 GEORGE STRICKER 3100 OTTO SCHNABL 3200 TIM WALKER 3000 TED MCDONALD 2000 PETER SMITH 3300 MARK FOLEY 4000 HEIDI WEIGL 3200 ROCKY LEWIS 2000 SUE CRAMER 1000 MARTIN SCHAEFFER 3200 HERBERT KARAJAN 3200 JESSICA CRINER row(s) selected. The following statement runs the prepared findemp statement, which has two unnamed parameters. The values that are being passed to these parameters are?sal and 100. Parameter?sal had been previously set using set param command. SQL>execute findemp using?sal, 100; EMPNUM FIRST_NAME LAST_NAME DEPTNUM JOBCODE SALARY ROBERT WHITE JERRY HOWARD ROGER GREEN JANE RAYMOND THOMAS RUDLOFF PAUL WINTER RACHEL MCKAY row(s) selected. For the syntax of the execute statement, see the SQL/MX Release 3.x Reference Manual. Executing CREATE TRIGGER statements To run create trigger statements by using RMXCI, you must specify a / in the first column on a new line at the end of the create trigger statement, for example: Executing CREATE TRIGGER statements 65

66 SQL>create trigger handlecheckout +> after insert on checkout +> referencing new as newr +> for each row +> update member set dues = dues > where memberid = newr.memberid; +> / For the syntax of the create trigger statement, see the SQL/MX Release 3.x Reference Manual. Logging output To log a RMXCI session, use the spool or log command. These commands record into a log file the commands that you enter in the RMXCI interface and the output of those commands. Starting the logging process (page 66) Stopping the logging process (page 67) Viewing the contents of a log file (page 67) Starting the logging process Run one of the following commands: spool on or log on spool log-file or log log-file For more information, see the LOG command (page 94) and the SPOOL command (page 138). SPOOL ON or LOG ON command The spool on or log on command logs information about a session in the sqlspool.lst file, which RMXCI stores in the installation directory. On Linux platform, the sqlspool.lst file is created in directory, from which you are running rmxci.sh. On Windows platform, the sqlspool.lst file is created in the directory, from which you are running rmxci.cmd. For example, this spool on command starts logging the session in the sqlspool.lst file: SQL>spool on SPOOL log-file or LOG log-file command The spool log-file and log log-file commands record information about a session in a log file, which you specify. If you specify a directory for the log file, the directory must exist, else, an error is returned. If you do not specify a directory for the log file, the spool is written to the directory from where you are running rmxci.sh on Linux and the directory from where you are running rmxci.cmd on Windows. For example, on Linux, this command starts logging the session in the persnl_updates.log file in the /home/usr/log directory: SQL>spool /home/usr/log/persnl_updates.log On Windows, the following command starts logging the session in the persnl_updates.log file in the C:\log directory: SQL>spool C:\log\persnl_updates.log 66 Interactively running commands in RMXCI

67 Using the CLEAR option The clear option clears the contents of an existing log file before logging new information in the file. If you omit clear, RMXCI appends new information to existing information in the log file. For example, this command clears existing information from the specified log file and starts logging the session in the log file: SQL>spool /home/usr/log clear Logging concurrent RMXCI sessions If you plan to run two or more RMXCI sessions concurrently on the same workstation, use the spool log-file or log log-file command and specify a unique name for each log file. Otherwise, each session writes information to the same log file, making it difficult to determine which information belongs to which session. Stopping the logging process Run one of the following commands: spool off log off For example, the following command stops logging in a RMXCI session: SQL>spool off Viewing the contents of a log file The log file is an ASCII text file that contains all the lines in RMXCI from the time you start logging to the time you stop logging. The logged lines include prompts, entered commands, output from commands, and diagnostic messages. For example, the following shows a log file that contains information from when you started logging to when you stopped logging: Logging output 67

68 For information about error messages that might appear in the log file, see the Error messages (page 144). 68 Interactively running commands in RMXCI

69 5 Running scripts in RMXCI In RMXCI, you can perform the following tasks with script files: Creating a script file (page 69) Running a script file (page 70) Logging output (page 71) Running scripts in parallel (page 71) Creating a script file A script file which you run in RMXCI must be an ASCII text file, which contains only the following elements: Supported SQL statements in script files (page 69) Permitted RMXCI commands in script files (page 69) Comments (page 69) Section headers (page 69) For an example, see Example of a script file (page 70). NOTE: You cannot use shell commands in a script file that you run in RMXCI. To create shell scripts that can be run from RMXCI, see Chapter 6 (page 72). Supported SQL statements in script files For the details about the supported SQL statements in the script files, see Appendix B (page 142). Permitted RMXCI commands in script files Most of the RMXCI commands are supported in script file, with a few exceptions. For a list of interface commands, see Appendix A (page 76). Disallowed interface commands in script files Comments The fc command cannot be run in script files. You can include comments anywhere in a script file. SQL also supports comments. Comments are useful for documenting the functionality of the script file and for debugging. When debugging, use comments to disable specific statements or commands without removing them from the script file. To denote a comment in a script file, use two hyphens before the comment: -- comment The end of the line marks the end of the comment. Section headers To create sections of commands within a script file, put a section header at the beginning of each section:?section section-name The section-name cannot begin with a number or an underscore. Each section name in a script file must be unique because RMXCI runs the first section that it finds that matches the section name Creating a script file 69

70 in or obey command. For more information, see command (page 79) or the OBEY command (page 96). Example of a script file This script file creates tables in the inventory schema. Running a script file To run a script file in RMXCI, use or obey command. These commands run one script file at a time in the SQL/MX Remote Conversational Interface. To run a script file when launching RMXCI, see Running a script file when launching RMXCI (page 50). For example, on Linux, this command runs a script file, sch_invent.sql, that creates tables in the inventory schema: /home/usr/scripts/sch_invent.sql NOTE: If the script file is outside the directory for rmxci.sh file (by default, the RMXCI bin directory) on Linux and rmxci.cmd file on Windows, you must specify the full path of the script file in the command. For the install files in RMXCI bin directory, see Table 2 (page 32). SQL>@/home/usr/scripts/sch_invent.sql SQL>-- CREATE SCHEMA 70 Running scripts in RMXCI

71 SQL>CREATE SCHEMA INVENT; --- SQL operation complete. SQL>-- CREATE TABLES/VIEWS in SCHEMA INVENT SQL>SET SCHEMA INVENT; --- SQL operation complete. SQL>CREATE TABLE INVENT.supplier +> suppnum NUMERIC (4) UNSIGNED NO DEFAULT NOT NULL +>,suppname CHARACTER (18)NO DEFAULT NOT NULL +>,street CHARACTER (22) NO DEFAULT NOT NULL +>,city CHARACTER (14) NO DEFAULT NOT NULL +>,state CHARACTER (12) NO DEFAULT NOT NULL +>,postcode CHARACTER (10) NO DEFAULT NOT NULL +>,PRIMARY KEY (suppnum) ); --- SQL operation complete. For more information about and obey commands, see command (page 79) and the OBEY command (page 96). Logging output To log output of a RMXCI session while running one script file at a time, use the spool or log command. When you run an obey command, RMXCI displays each command in the script file, the output for each command, and diagnostic messages in the SQL/MX Remote Conversational Interface. The spool or log command captures this output as it appears in the SQL/MX Remote Conversational Interface and logs it in a log file. For more information, see Logging output (page 66). Running scripts in parallel In RMXCI, and obey commands enable you to run only one script file at a time. However, the prun command enables you to run multiple script files simultaneously. NOTE: The prun command can be run in noninteractive mode. The command allows options to be specified on the command-line, which enables prun to be run in script and/or obey files. The prun command is most useful for running sets of Data Definition Language (DDL) statements simultaneously, which speeds up the process of creating large databases. Put all dependent or related DDL statements in the same script file. For more information on running scripts in parallel using the prun command, see the PRUN command (page 99). Logging output 71

72 6 Running RMXCI from Perl or Python You can run SQL statements in Perl or Python by invoking the RMXCI Perl or Python wrapper script. To use the wrapper scripts, see: Login environment variables (page 72) Perl and Python wrapper scripts (page 74) Launching RMXCI from the Perl or Python command-line (page 74) These instructions assume that you have installed the RMXCI product. For more information, see Chapter 2 (page 16). Login environment variables Before launching RMXCI from Perl or Python, set these login environment variables: Environment variable RMXCI_PERL_JSERVER=JavaServer_jar_path RMXCI_PYTHON_JSERVER=Jython_jar_path RMXCI_PERL_JSERVER_PORT=port_number Description Specifies the Perl JavaServer JAR file location. Specifies the Jython JAR file location. Specifies the port on which the JavaServer listens. The RMXCI installer attempts to automatically download and install both the Perl JavaServer and Jython open source extensions. If you want to download and install them manually, refer to the instructions in the README file in the samples directory. To set the login environment variables, see the instructions for the operating system of the client workstation: Setting the login environment variables (page 72) Setting login environment variables in the system properties on Windows (page 72) Setting the login environment variables You can set the login environment variables for the session at command prompt, or you can set the login environment variables for the system or user by including them in the system properties. Setting login environment variables from the command-line on Windows At a command prompt, enter one of these commands: set RMXCI_PERL_JSERVER=absolute-path-of-JavaServer.jar set RMXCI_PYTHON_JSERVER=absolute-path-of-Jython.jar set RMXCI_PERL_JSERVER_PORT=portnumber Setting login environment variables in the system properties on Windows NOTE: The images shown in this section may vary depending on the version of Windows. 1. Go to Control Panel. Double-click the System icon. 2. Click the Advanced tab in the System Properties dialog box. 72 Running RMXCI from Perl or Python

73 3. Click Environment Variables. 4. Click New in system or user variables in the Environment Variables dialog box. 5. Enter the name of the login environment variable for the Variable Name: and the required value for the Variable value: in the New User Variable dialog box, and then click OK. 6. Verify that the environment variable appears in System or User variables. 7. Repeat the above steps for each login environment variable. 8. After adding all the environment variables, click OK in the Environment Variables and System Properties dialog boxes to accept the changes. Setting login environment variables on Linux 1. In the /home directory, open the user profile (.profile or.bash_profile for the Bash shell), for example: /home:vi.profile 2. Add the following export commands (or setenv commands for the C shell) to the user profile. export RMXCI_PERL_JSERVER=absolute-path-of-JavaServer.jar export RMXCI_PYTHON_JSERVER=absolute-path-of-Jython.jar export RMXCI_PERL_JSERVER_PORT=portnumber Login environment variables 73