OS/2 Shareware BBS: InfoMgt/InfoMgt.zip/v20_eval.zip/XYQ.INF

OS/2 Help File | 1996-04-18 | 1MB | 8,092 lines

ΓòÉΓòÉΓòÉ 1. Special notices and trademarks information ΓòÉΓòÉΓòÉ

No part of this document may be reproduced or transmitted in any form or by any
means, electronic or mechanical, for any purpose, without the prior written
consent of Xyratex. The data used in all examples herein is fictitious unless
otherwise noted.

Copyright Havant International Ltd. 1995,1996. All rights reserved.

Xyratex is the trading name of Havant International Limited.

   Xyratex
   P.O. Box 6
   Havant
   Hampshire
   PO9 1SA
   United Kingdom

Telephone: [phone]

Fax:       [phone]

Xyratex, Xyratex Query for OS/2 and XY-Query are trademarks of Havant
International Limited.

The following are all trademarks of International Business Machines
Corporation:

AIX, AS/400, Database 2 OS/2, Database Manager, DB2, DB2/2, DB2/400, DB2/6000,
DDCS/2, DDCS/6000, DDQS/2, Distributed Relational Database Architecture, DRDA,
Extended Services, IBM, IBM SAA Distributed Database Connection Services/2,
OS/2, OS/2 Procedures Language 2/REXX, Presentation Manager, QMF, SQL/DS.

Microsoft, Windows and Excel are trademarks of Microsoft Corporation.

Intel and 80386 are trademarks of Intel Corporation.

Lotus 1-2-3 is a trademark of Lotus Corporation.

XDB is a trademark of XDB Systems Inc.


ΓòÉΓòÉΓòÉ 2. Version Notice ΓòÉΓòÉΓòÉ

First Edition April 1996

This edition applies to Release 2.0 of Xyratex Query for OS/2, and all
subsequent releases and modifications.

Printed in England.

Written by Brian Paine.


ΓòÉΓòÉΓòÉ 3. About XY-Query ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 3.1. Product overview ΓòÉΓòÉΓòÉ

Xyratex Query for OS/2 (XY-Query) is an interactive query development
application. It is a Presentation Manager application that runs on OS/2,
providing access to IBM and XDB local and remote relational databases.

XY-Query can be installed in standalone, database client-only and database
server configurations.  Remote data access to DB2 family locations is achieved
using the IBM SAA Distributed Database Connection Services /2 (DDCS/2) database
gateway product.

XY-Query offers the flexibility to accommodate users with varying degrees of
SQL proficiency.  It does not inhibit power users who are familiar with SQL,
but it also supports the less experienced user through its easy-to-use Query
Builder function.

Users with no knowledge of SQL can still benefit from the power and flexibility
of XY-Query by using pre-built objects that can request and display the
required data in a specific format.

The application is compact, offering key query management services in an easily
navigable environment without using excessive resources.

XY-Query offers the following advantages:

     Provides a single interface for queries and reporting on DB2, SQL/DS,
      DB2/400, DB2/6000, DB2/2 and XDB relational databases
     Supports Extended Services Database Manager databases
     Provides step-by-step assistance for query-building
     Allows dynamic table updates
     Provides comprehensive report formatting
     Displays data in various chart formats
     Offers REXX procedures interface
     Can save data as tables at local and remote locations
     Can directly import and run existing Query Manager queries and QMF
      queries from DB2 and SQL/DS
     Can directly import and run queries from XDB
     Can be invoked via DDE to enable data retrieval directly into spreadsheet
      applications
     Highly tailorable using its Settings facility

 Note:  This guide does not include instructions for writing SQL.


ΓòÉΓòÉΓòÉ 3.2. How to use this guide ΓòÉΓòÉΓòÉ

This guide is intended to provide a complete reference for XY-Query. It
explains how:

     To install XY-Query

      If you have not yet installed XY-Query,see chapter Installing XY-Query to
      find out how to install XY-Query.


     To start using XY-Query

      If you are new to XY-Query, you are recommended to start with chapter
      Getting started with XY-Query to chapter Opening and closing XY-Query.
      These chapters show you how to use XY-Query and to run queries.


     To use XY-Query's facilities

      Once you are familiar with the basic operations of XY-Query, refer to
      chapter XY-Query windows to chapter Using XY-Query with spreadsheets.
      These chapters tell you how to use the facilities provided by XY-Query.

 All users of XY-Query, irrespective of their previous experience, should find
 this book a valuable reference to help them use the product successfully and
 gain the most benefit from the advantages XY-Query gives.


ΓòÉΓòÉΓòÉ 4. Getting started with XY-Query ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4.1. Welcome ΓòÉΓòÉΓòÉ

Welcome to XY-Query. We have designed XY-Query to be as easy to use as we can,
yet it has many features and is as comprehensive as any database expert could
wish. Later chapters in this book will show you how to use the product in full.

This chapter is intended to get you going, and to show you how easy it is to
retrieve and display data and then plot a chart from information extracted by
running a query. You can use a sample database so that you can practice on test
data and learn how easy it is to use XY-Query.

If you haven't installed XY-Query yet, go to chapter Installing XY-Query.
Installation is very straightforward as XY-Query comes on only two diskettes
and only takes a matter of minutes.

We have to make some assumptions about your environment, primarily that you
have your data in a local database. If your data is not local to your PC, for
example, if it is on a mainframe you may not have access to it. If so, you may
have to seek help from your support personnel who should be able to provide
assistance in setting up the correct connections. See Connecting to remote DB2
databases. Even if you have a local database, then we suggest you use the
SAMPLE database that comes with DB2/2 or the TUTORIAL location for XDB users.
The samples that come with XY-Query use these two data sources.

The examples that will be described in this manual are based around the DB2/2
SAMPLE database.

Refer to Creating the DB2/2 sample database. to find out how to install this
database if necessary.

As you familiarise yourself with the product you will see that XY-Query aims to
do as many things as possible for you. For example, knowing just a location and
a table name is enough to allow you to construct a valid SQL query, run it and
display the data returned as both text and graphically as a chart.


ΓòÉΓòÉΓòÉ 4.2. Open the product folder ΓòÉΓòÉΓòÉ

To start, open the XY-Query desktop folder by double-clicking on the icon
labelled Xyratex Query for OS/2 (the full product name) that is on your OS/2
desktop:

Xyratex Query for OS/2 product icon

Within this folder you can see a number of other icons. The purpose of these
icons is explained in more detail in chapter What does XY-Query look like?.


ΓòÉΓòÉΓòÉ 4.3. Start the XY-Query program ΓòÉΓòÉΓòÉ

Start XY-Query by double clicking the XY-Query icon.

XY-Query program icon

You are presented with the SQL window which contains the Query Builder. You use
the Builder to make decisions about the data you want to retrieve. It builds
SQL statements for you but you need not see the SQL if you do not want to. As
soon as you have given the Builder enough information, it is able to run a
query when asked. You can see this because the Run button on the top toolbar
turns green when ready.


ΓòÉΓòÉΓòÉ 4.4. Work through the builder ΓòÉΓòÉΓòÉ

By working through the builder you can construct a query of your choice. The
Builder consists of a number of panels with which you can interact to specify
details of the query.

     Initially, you are presented with the Select SQL Statement panel. From
      here you can choose the type of query to build and run. This tutorial
      assumes that most queries you run will be SELECT and this option is
      already chosen from the list.
     Press the Location button on the lower toolbar to show the available
      locations. (You should see some Floating Help displayed for a short time
      each time you place the mouse pointer over a toolbar button).

      Double click the entry for SAMPLE to obtain a list of tables at the
      location. At this point, enter your userid and password if requested to
      gain access to the database.  If you have problems here, get help from
      your Database Administrator. Once access is obtained, the Builder
      progresses automatically to the Select Tables panel where the available
      tables are listed for you.
     Next choice is the table.  XY-Query has already displayed any tables
      owned by your current userid. Select the STAFF table from the list of
      table names and then press the ADD button. You have now specified enough
      information to make it possible to run a query.


ΓòÉΓòÉΓòÉ 4.5. View and run your query ΓòÉΓòÉΓòÉ

You can if you wish view the raw SQL that corresponds with what has been
specified in the Builder. Do this by pressing the Edit Sql button on the top
toolbar. To switch back into the Builder, press the Builder button on the same
toolbar.

To run the query that has been specified so far, press the Run button on the
top toolbar.

Tip-  You can obtain context sensitive help by moving the cursor to a specific
field and pressing the F1 key. Each XY-Query dialog has associated help which
you obtain by pressing the button labelled Help. In the Builder, you display
help by pressing the Help button on the bottom toolbar.


ΓòÉΓòÉΓòÉ 4.6. Display the Viewer ΓòÉΓòÉΓòÉ

As the data is retrieved from the database, XY-Query opens a window known as
the Viewer to display it. You can see the data displayed with the column
headings exactly as extracted from the database. This is the standard format of
the Viewer and the initial presentation is quite simple.

However, with a few modifications the report can be enhanced with various
colours and fonts and be provided with headings, footings, subtotals and
totals, making it suitable for direct presentation. The tool used for this is
the Settings Notebook called from the Settings button on the Viewer toolbar,
For now though, concentrate on refining your query.


ΓòÉΓòÉΓòÉ 4.7. Refining your query ΓòÉΓòÉΓòÉ

The query you just ran retrieved all the data in the STAFF table, that is all
the rows and all the columns. You can now refine this in a number of ways by:

     Reducing the number of columns
     Defining your own calculated columns
     Sorting the data that is returned
     Limiting the range of the data retrieved

 All these are managed from different panels of the Builder accessed from the
 buttons on the bottom toolbar.

 Refine your query as follows:

   1. Specify columns- by pressing the Select Columns... button

      You get a list of the columns in the table. All are selected because
      initially all the data was selected.

      Press the Deselect All button then select the columns you want from the
      list. For this example select the columns NAME, DEPT, SALARY  and COMM.
   2. Select specific rows- by pressing the Select Rows... button

      Choose the column you want to limit from the first list (SALARY), choose
      the limiting method (=,>,< etc) from the next list (<) and finally
      specify the limiting value in the right hand entry field (20000).

      Press the Add button to cause the statement SALARY < 20000 to appear in
      the box at the bottom of the panel.

      When the query is re-run this statement will have the effect of reducing
      the amount of data retrieved by the query to only that which matches this
      condition.
   3. Sort the data by pressing the Order rows... button

      You then select the columns to sort on and the relevant sequences
      (ascending or descending). In this example, firstly ensure the Ascending
      button is checked and then select the DEPT entry from the list.
   4. Run your amended query when the Builder activity has completed, by
      pressing the Run button and obtain another extract.

      You can now see that there are only the four columns, a reduced number of
      rows and that the data is in ascending department order.
 Tip- Accelerator keys are listed alongside many of the menu options in the
 XY-Query window menus.  You can use the accelerator keys instead of selecting
 items from the menus or toolbars.


ΓòÉΓòÉΓòÉ 4.8. Improving the appearance of the report ΓòÉΓòÉΓòÉ

To smarten up the report, press the Settings button on the Viewer toolbar.

Tip-  With the mouse pointer over the window, click the right-hand mouse button
to see the Settings Notebooks.

Once Settings is opened, you can change parameters.  For now, focus on the
column headings and add some totals.

The Viewer Settings Notebook has a page for each aspect of the report. It opens
at Columns. Start there by altering the usage of the SALARY and COMM columns.

Do the following:

   1. Rotate the Name field until SALARY appears.
   2. Drop the Usage list and select SUM.
   3. Press Apply and see the changes reflected immediately in the report.
   4. Move the Name field to read COMM.
   5. Select AVG from the Usage list.
   6. Press Apply and see the changes reflected immediately in the report.
   7. Rotate the Name field to read DEPT.
   8. Select Centre from the Alignment list.
    9.

 Now, to display the data in the SALARY and COMM columns as monetary values.

   1. Select the tab for the Country page.
   2. Rotate the Name field until it reads SALARY.
   3. Enter the currency symbol you want use for this column.
   4. Press either the Suffix: or Prefix button.
   5. Press Apply and see the changes reflected immediately in the report.
   6. Rotate the Name field until it reads COMM and repeat actions, possibly
      specifying a different currency symbol or position for this column.

 Now, to smarten the titles, do the following:

   1. Select the tab for the Titles page.
   2. Rotate the Name field until it reads SALARY.
   3. Alter the Data field to read Salary.
   4. Change the alignment field to read Centre.
   5. Press the Apply button and see the column title displayed in the Viewer
      change dynamically.
   6. Repeat steps 2 to 5 changing COMM to Commission, DEPT to Dep't and NAME
      to Employee_Name.

 You can change the colour of these titles later.

 Next however, complete the totalling by making the report break wherever the
 department number changes as follows:

   1. Select the Break tab to show the Break page.
   2. Select Dep't from the list.
   3. Press the Apply button and see the Report change immediately.

 The total effect of the changes made so far is that the report is now divided
 into department sections with each departmental salary bill sub-totalled and a
 grand total at the bottom.  The column titles have changed to be more
 understandable.

 To change the colour of the titles, do the following:

   1. Select the Presentation tab.
   2. Rotate the Region field until it reads Column Titles.
   3. Click the colour red in the palette.
   4. Press the Apply button to make the changes.

 Try making a few changes of your own. Explore the various regions that the
 Viewer comprises and give them different colours and fonts.  You can see the
 effect on the report as soon as you apply it. If you choose an effect you
 don't want then either change back or press the Default button to reset.


ΓòÉΓòÉΓòÉ 4.9. Display a Chart ΓòÉΓòÉΓòÉ

Make a chart from your data is just as easy. Once the data is extracted, press
the Chart button on the Viewer or SQL window toolbar to display a chart. The
default is a 3D bar chart, but as with everything else in XY-Query, you can
change it to match your own personal preferences.


ΓòÉΓòÉΓòÉ 4.10. Tailor the Chart ΓòÉΓòÉΓòÉ

You can tailor the Chart using a Settings Notebook specifically for the Chart
window. To display the window, press the Settings button on the toolbar, You
can change both the type of chart displayed and many display attributes and
styles. Try changing a few colours and fonts and you will see that, like the
Viewer, the Chart can be tailored extremely easily.


ΓòÉΓòÉΓòÉ 4.11. Where next ? ΓòÉΓòÉΓòÉ

The Samples folder is a good place to start. In there you will find two
distinct sets of examples, one for DB2/2 and one for XDB, that will show you
the many different ways you can use XY-Query  You will also find XY-Query
Procedures which let you use the XY-Query facilities in a REXX program.

As you will have discovered, XY-Query is truly easy to use. In this tutorial
you have experienced just a few of the features. Take your time to explore the
product and try a few experiments. There is comprehensive contextual help for
every window and control, and this book explains every functional area of the
product.

Happy querying.


ΓòÉΓòÉΓòÉ 5. What does XY-Query look like? ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1. The XY-Query desktop ΓòÉΓòÉΓòÉ

When XY-Query is installed, assuming you have requested that your desktop is
updated, the following product icon will be placed on your OS/2 desktop.

XY-Query desktop icon

This icon represents the folder in which XY-Query is stored. When the folder is
opened it will look as follows:

XY-Query desktop folder

The folder contains the following objects from left to right:

     A folder labelled Work you can use for storing XY-Query objects you
      create.
     A folder labelled Template containing templates for SQL, Viewer, Chart
      and Procedure objects.
     A folder labelled Samples which contains 2 further folders labelled DB2
      and XDB. These contain example XY-Query objects created to highlight some
      of the features offered by XY-Query. The folders indicate the database
      system against which the examples are targetted.
     An XY-Query program icon used to start a new untitled XY-Query session.
     An icon labelled Settings used to define defaults for your XY-Query
      system
     A book icon that you select to obtain the on-line version of this book.
     An icon labelled Remove used to remove XY-Query.

 As elsewhere in OS/2, folders can be renamed as required and objects can be
 stored within them in the way most convenient for you.  Each XY-Query object
 has a menu which you open in the normal way by pointing to the object and
 clicking the right-hand mouse button.


ΓòÉΓòÉΓòÉ 6. XY-Query Objects ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6.1. XY-Query objects ΓòÉΓòÉΓòÉ

There are four types of XY-Query object:

     SQL
     Viewer
     Chart
     Procedure

 The are represented on the desktop as icons as shown in XY-Query object icons.

 XY-Query object icons

 These four objects fall into two categories. The first covers the SQL, Viewer
 and Chart objects and the second, the Procedure object.

 A standard use of XY-Query is to write an SQL query, execute it and show the
 results both as data in the Viewer and graphically as a Chart. The query,
 together with all the presentation styles and settings for the SQL, Viewer and
 Chart windows form the content of the first object type. The creator of the
 object decides which object type is relevant depending upon how it will be
 used and by whom.

 The prime difference between SQL, Viewer and Chart objects is that they have a
 different Primary View on to the object. It is quite possible to store what
 are in effect identical objects as SQL, Viewer and Chart objects.  When these
 objects are selected at a later date it is the type of object that will
 determine how XY-Query is invoked.

 SQL objects are displayed with the SQL window as the Primary View.  Viewer
 objects have the Viewer as the Primary View and Chart objects have the Chart
 window as their Primary View.

 For an SQL object, the SQL window is displayed and you decide whether or not
 to run the query and show the Viewer and Chart. For a Viewer object, XY-Query
 runs the query automatically and displays the Viewer window. You can move from
 this window to the other windows to view the query or to plot a chart. In the
 final case for a Chart object, once again the query runs automatically and
 displays the Chart window. Again, from here you can display the SQL and Viewer
 windows.

 The object is closed only when the primary window is closed.

 Note that any data displayed is not retained when you close Viewer and Chart
 objects. Only the query in the SQL editor and the presentation styles and
 settings for the object's three available windows are saved with the object.

 Procedure objects cause the XY-Query Procedure window to be shown and it is
 from this window that XY-Query Procedures can be constructed and executed.
 There is however one exception to this. This is when a Procedure object has
 been saved with an Invocation mode of Background. When the object is opened
 the procedure starts automatically but the window is not shown.

 Procedures also do not retain any data when closed but do retain the content
 of the Procedure text together with all presentation styles and settings for
 the Procedure window.


ΓòÉΓòÉΓòÉ 6.2. Untitled Objects ΓòÉΓòÉΓòÉ

Untitled XY-Query objects are only temporary and do not exist once the instance
of XY-Query has been closed.

You instantiate an untitled Sql object whenever you open XY-Query from the
program icon in its desktop folder, or when you select the New option from the
File menu on an Sql window or if you start XY-Query from the command line
without naming an existing object.

Untitled Procedure objects can only be instantiated from either the command
line or from the New option fromt he File menu on the Procedure window.

The main purpose of untitled objects is to allow you to allow you to start an
XY-Query instance without first having to create an object from a template. It
allows you, for example to run ad-hoc queries or procedures which you do not
wish to keep after the instance has been closed. It is also one of the prime
ways in which you can develop your permanent objects. You can create the query
or procedure from an untitled object and once you are satisfied with it all you
have to do is Copy-To a permanent object.

As these objects are transient there is no associated object file and therefore
there is no concept of saving the object. You can of course create another
permanent object by using Copy-To as described above.


ΓòÉΓòÉΓòÉ 6.3. Object security ΓòÉΓòÉΓòÉ

There are two levels of security that can be applied to XY-Query objects that
you create. These are:

      Write Protection
      Read Protection

 Setting Write protection on an object will prevent changes made to the object
 from being saved back to the object file.

 Read protection will prevent unauthorised users from opening specific objects.
 Read protected objects are encrypted and will not open unless the correct
 password is given.

 Both levels of protection rely on the use of passwords. An object can have a
 read and a write protect password. It may be that they are both the same but
 they do not need to be. It is up to the creator of the object to determine
 what level of security it requires and what the passwords should be.

 Each security option requires a password to be set and made active. For Write
 protection once a password is set the protection is not automatically active
 (if it was you wouldn't be able to save the fact that it was set). Rather, the
 password is marked as set, but inactive until you save or close the object.
 Once you save the object the write protection password then becomes active for
 you and all other users of the object. This object can not then be saved again
 without de-activating the write protection password.

 In the case of read protection, once a password has been set it is
 automatically made active. Once the object has been saved it will be encrypted
 and all future users will be asked for the read password to when opening the
 object.

 There is an exception however for read protection when it is set for an object
 that already has active Write protection. The Write protection means that no
 information will be written to the object while it is active. This means that
 not even the fact that Read protection has been set can be written. To ensure
 that the Read protection is acknowledged it is necessary for you to
 de-activate the write protection on the object. Subsequently saving or closing
 the object will save the Read protection and also set write protection active
 again.

 Similarly, you cannot remove Read protection from a write protected object
 unless you first temorarily de-activate write protection and then save or
 close the object.

 The last Read password that you enter is remembered by XY-Query. If the next
 read-protected object you open has the same password then XY-Query will not
 prompt you to enter it and will carry on and open the object. If you wish to
 remove the last Read password you entered from XY-Query you should select the
 Logoff Object option from the Sessions utility sub-menu on an Sql, Viewer or
 Chart window.

 The setting of the security levels and associated passwords is done from the
 Security page of the Sql or Procedure window settings, see Security page.

 Note:  All passwords are case sensitive and retain any leading or trailing
 spaces.


ΓòÉΓòÉΓòÉ 7. Opening and closing XY-Query ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.1. Opening XY-Query ΓòÉΓòÉΓòÉ

XY-Query can be opened in a number of different ways. If you want to start a
new XY-Query SQL session then you start the application in one of two ways:

     Issue this command from an OS/2 command line:

                 XYQUERY

     Open the XY-Query program icon in the desktop folder.

 Both of these actions open a new untitled SQL object that inherits all of the
 defaults set in the XY-Query Settings facility.

 If you want a new XY-Query Procedure session, issue this command from an OS/2
 command line:

       XYQUERY /P
 to open a new untitled Procedure object that inherits all the relevant
 defaults set in the XY-Query Settings facility.

 Another way of starting an XY-Query session is to use the object templates
 provided at installation to start a new XY-Query session:

   1. Open the Work folder.
   2. Open the Template folder.
   3. Drag a copy of the relevant XY-Query object template from the Template
      folder to the Work folder.
   4. Rename the copied object as required.
   5. Open the new object and obtain a window corresponding to the type of
      object opened.

 Note:  For new Viewer or Chart objects, the initial window appears to be
 empty. This is because there has been no query defined which could be run to
 provide the data to fill the Viewer or against which to plot a chart. In these
 cases the SQL window will also be displayed from where you can define your
 query.

 You can also open XY-Query from an existing object. Do one of the following:

     Issue this command from an OS/2 command line:

                 XYQUERY obj_name
      where obj_name is the potentially fully qualified name of the object to
      be opened
     Open the object from within a folder on the OS/2 desktop.

 Note:  If your computer uses the File Allocation Table (FAT) system of storing
 files, only eight-character names are supported for objects. You can still
 give them names of more than eight characters, but OS/2 automatically
 truncates the name.


ΓòÉΓòÉΓòÉ 7.2. Closing XY-Query ΓòÉΓòÉΓòÉ

For SQL, Viewer or Chart objects, when you close the primary window of the
object you also close XY-Query, automatically closing any other windows open
for the object.  You can close XY-Query while a query is still executing but
XY-Query requests further confirmation from you before it shuts down.

For Procedure objects you need to close only the Procedure window to leave
XY-Query.


ΓòÉΓòÉΓòÉ 8. XY-Query windows ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.1. Introduction ΓòÉΓòÉΓòÉ

This chapter introduces the four XY-Query windows and details the facilities
available from each.


ΓòÉΓòÉΓòÉ 8.2. SQL window ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.2.1. Purpose ΓòÉΓòÉΓòÉ

The primary function of the SQL Window is to enable the definition, display and
execution of SQL queries.

Note:  For more detailed descriptions of SQL window facilities, see chapter
Working with the SQL window and section SQL window settings.


ΓòÉΓòÉΓòÉ 8.2.2. Appearance ΓòÉΓòÉΓòÉ

The SQL window is constructed of a number of elements:

 Element           Description
 Title Bar         Shows name of current object and the window type i.e. SQL.
 Menu Bar          Details all menus of facilities available from the SQL
                   window.
 Toolbar           Used to provide you with fast path access to commonly used
                   functions.
 SQL Query Area    Area which you can use to construct SQL queries. The
                   appearance of this area can change dependant upon the view
                   and mode you choose.
 Information Bar   Used to display status and information messages to you.


ΓòÉΓòÉΓòÉ 8.2.3. Views and modes ΓòÉΓòÉΓòÉ

There are two distinct views which determine the appearance of the query area
of the SQL window.

     Edit SQL View (XY-Query SQL window - Edit SQL view)
     Builder View (XY-Query SQL window - Builder view (Locations page))

 You can place the SQL window in either of two modes. These are Browse and
 Update.

 In Browse mode the Sql editor and location selector, or the Builder pages
 (depending on the current view) are made read only.

 You can set the default view in which the SQL window is displayed for any new
 XY-Query objects from the View page in the SQL section of the XY-Query
 Settings facility, see SQL Settings - View page.


ΓòÉΓòÉΓòÉ 8.2.3.1. Edit Sql View ΓòÉΓòÉΓòÉ

XY-Query SQL window - Edit SQL view

If the window is in its Edit SQL view, the query area is made up of two
elements.

     Location selector

     Sql editor

 The Location selector allows you to select the location which contains the
 table or tables against which a query can be executed.

 When a location is selected XY-Query automatically connects to it, prompting
 for logon information as appropriate. If you do not have have a suitably
 authorised userid and password for the location, consult your system
 administrator.

 By connecting to the database at this time, you remove the overhead of
 connection when the query is run.

 The main part of the window (the text area) is termed the Sql editor and is
 used for displaying and editing an SQL query.


ΓòÉΓòÉΓòÉ 8.2.3.2. Builder View ΓòÉΓòÉΓòÉ

XY-Query SQL window - Builder view (Locations page)

In Builder view you use a series of panels to define and build an SQL query
automatically which can then be run against tables you have selected. With this
view you can create a query, execute it and see the results without having to
have see any actual SQL statements. The Query Builder facility is explained
more fully later in this guide, see Using the Query Builder.


ΓòÉΓòÉΓòÉ 8.2.4. SQL window - File menu ΓòÉΓòÉΓòÉ

The File menu contains the following options.

 New            Use this to open a new 'Untitled' XY-Query SQL session. It has
                no link to the object from which it was spawned and is
                initialised with the relevant default attributes from the
                Settings facility.
 Save           Use this to save the current state of the object. It not only
                saves the SQL window attributes but also the attributes of the
                other windows associated with the object. If the object is
                'Untitled' then save can not be actioned directly but does
                invoke the 'Copy To' facility described below to create a new
                object with all of the attributes of the current object.
 Copy To        Use this to create a new object identical to the current state
                of the object.
 Print          Use this to print the contents of the Sql editor to a selected
                printer. If the window is currently in Builder view, the SQL
                query defined so far will be constructed and printed.
 Quit           Use this to close XY-Query without saving any of the current
                settings. This option is only available if the SQL window is
                the Primary View.


ΓòÉΓòÉΓòÉ 8.2.5. SQL window - Edit menu ΓòÉΓòÉΓòÉ

The Edit menu contains the following options.

 Select All     Use this to mark (highlight) all of the text in the Sql editor.
 Deselect All   Use this to de-highlight any marked text in the Sql editor.
 Cut            Use this to move any marked text to the clipboard. The marked
                text is deleted from the Sql editor.
 Copy           Use this to copy any marked text to the clipboard. The marked
                text is left unchanged.
 Paste          Use this to paste the contents of the clipboard into the Sql
                editor at the current cursor position.
 Clear          Use this to remove all text from the Sql editor.


ΓòÉΓòÉΓòÉ 8.2.6. SQL window - Query menu ΓòÉΓòÉΓòÉ

The Query menu contains the following options.

 Run            Use this to start the execution of an SQL query defined in the
                Builder or in the Sql editor.
 Stop           Use this to request that the currently executing SQL query is
                stopped.
 Models         Use this to show a list of popular SQL commands. Selecting one
                gives an example of the syntax for that command.
 History        Use these options to traverse through, add to, or remove
                queries from the History ring.
 Import         Use this to import a query from outside of the current XY-Query
                environment. This includes other file formats as well as Query
                Manager, QMF and XDB queries.
 Export         Use this to export the query to one of a number of other file
                formats.


ΓòÉΓòÉΓòÉ 8.2.7. SQL window - View menu ΓòÉΓòÉΓòÉ

The View menu contains the following options.

 Open Settings    Use this to open the SQL window settings notebook from where
                  SQL window settings can be changed.
 Edit SQL         Use this to switch the SQL window into its Edit SQL view.
 Builder          Use this to switch the SQL window into its Builder view.
 Builder Pages    Use the options under this menu to move sequentially, or
                  selectively through the pages of the builder.
 Browse           Use this option to set the Sql editor to read only mode.
 Update           Use this option to set the Sql editor to read / write mode.
 Toolbar          Use this option to show or suppress the toolbar on the SQL
                  window.
 Information Bar  Use this option to show or suppress the Information bar on
                  the SQL window.


ΓòÉΓòÉΓòÉ 8.2.8. SQL window - Window menu ΓòÉΓòÉΓòÉ

The Window menu contains the following options.

 Viewer         Use this to show the Viewer. If the query has not previously
                been run then it causes the query to execute.
 Chart          Use this to show the Chart window. If the query has not
                previously been run then it causes the query to execute.


ΓòÉΓòÉΓòÉ 8.2.9. SQL window - Utilities menu ΓòÉΓòÉΓòÉ

The Utilities menu has the following options:

 Database       Use this to create or erase DB2/2 databases.
 Table          Use this to define, alter the definition of, create, append to,
                or erase tables.
 Sessions       Use this to register logons to be used when XY-Query connects
                to various locations.


ΓòÉΓòÉΓòÉ 8.2.10. SQL window - Help menu ΓòÉΓòÉΓòÉ

The Help menu enables various types of help to be invoked for the application.

 General Help          Use this to display general help for the SQL window.
 Keys Help             Use this to display help explaining which key
                       combinations can be used to perform actions within the
                       SQL window.
 Builder Help          Use this to display help for the currently displayed
                       Builder page.
 Product Information   Use this to display the XY-Query about box.


ΓòÉΓòÉΓòÉ 8.2.11. SQL window - toolbar ΓòÉΓòÉΓòÉ

Underneath the menu bar is a toolbar.  Use the Toolbar item in the View menu to
suppress or restore the toolbar.  The toolbar provides a quick way of
performing commonly required actions.  Pressing the appropriate button invokes
the function required.

       Save current object
       Copy to a new object
       Print query
       Show SQL window settings
       Run query
       Halt execution of query
       Place the SQL window in its Builder view
       Place the SQL window in its Edit SQL view
       Move backwards through History Ring
       Move forwards through History Ring
       Switch to Viewer
       Switch to Chart window
       Get help

 Note:  The History Ring (forwards and backwards) buttons are visible only if
 the Ring has been initialised.


ΓòÉΓòÉΓòÉ 8.2.12. SQL window - information bar ΓòÉΓòÉΓòÉ

XY-Query uses the Information Bar at the bottom of the window to give status
and error messages. It can be shown or suppressed by selecting or de-selecting
the relevant option in the View menu.

When the Information Bar is not visible you will be unaware of normal status
messages but error messages will be displayed to you via message boxes.

For long messages the Information Bar must be expanded to see the full text. Do
this by pressing the button at the extreme right of the bar, or by using the
key combination of Ctrl and I.

Note:  Information Bars, identical functionally to the one described here,
appear on all of the main XY-Query windows.


ΓòÉΓòÉΓòÉ 8.3. Viewer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.3.1. Purpose ΓòÉΓòÉΓòÉ

The primary function of the Viewer is to display and format the data returned
from a database after a query has been executed.

For more detailed descriptions of the facilities available from the Viewer
window, see chapter Working with the Viewer window and section Viewer window
settings.


ΓòÉΓòÉΓòÉ 8.3.2. Appearance ΓòÉΓòÉΓòÉ

The Viewer is constructed of a number of elements:

 Element         Description
 Title Bar       Shows name of current object and the window type i.e. VIEWER.
 Menu Bar        Details all menus available from the Viewer.
 Toolbar         Used to provide fast path access to commonly used functions.
 Display Area    Area which is used to display the data returned by the query.
                 The content and appearance of this depends upon the view and
                 mode you have chosen and the formatting performed.
 Information Bar Used to display status and information messages to you.


ΓòÉΓòÉΓòÉ 8.3.3. Views and Modes ΓòÉΓòÉΓòÉ

There are two distinct views which determine the appearance of the display area
of the Viewer window.

     Report View
     Form View

 You can place the Viewer, in either view, in two modes, Browse and Update. The
 mode setting decides whether you can dynamically edit the text and data
 displayed in the Viewer.

 The default view and mode in which the Viewer is displayed for any new
 XY-Query objects is defined on the View page in the Viewer section of the
 XY-Query Settings facility, see Viewer Settings - View page.


ΓòÉΓòÉΓòÉ 8.3.4. Report View ΓòÉΓòÉΓòÉ

XY-Query Viewer window (Report view - Browse mode)

XY-Query Viewer window (Report view - Update mode)

The report view displays the data together with any heading and footing lines
that have been added in one continuous report. In browse mode the report view
is displayed as a plain paper report where any repeated data within a
summarised group is not shown. However, in update mode the report view is
displayed in a cellular form with each element (heading, column title, data
item and footing) selectable and, potentially, directly editable. The element
currently with the focus will be displayed with an edit box around it. Its
contents can be changed by manually overtyping.

Note:  The data can only be directly edited if the Data Update setting in the
Viewer settings notebook allows it.


ΓòÉΓòÉΓòÉ 8.3.5. Form View ΓòÉΓòÉΓòÉ

XY-Query Viewer window (Form View)

The Form view enables row-by-row analysis of the report displayed in the
Viewer. The data it displays will depend on the type of report defined in the
Report view. If it is a straightforward data only report then the data rows
will be displayed. If the report is enhanced with breaks and aggregation usages
to give total line these will NOT be displayed under Form view.

If a summary report is currently defined such as a Group report, an Across
report or a Totals Only report, then Form view will display the summary data
rows individually, again missing out any total rows that may shown in Report
view.

Essentially, only the rows in Report view that are displayed in data format
will be seen under Form view.

When Form view is in browse mode the data is not updateable, When it is in
update mode the data is editable only if the Data Update setting in the Viewers
settings notebook allows it and it is displaying non-summarised data.

Note:  Headings and footings are not visible in this view and column titles can
not be changed.

A data row is displayed as a set of fields which, providing the data is
editable, can be changed.

The data is displayed with the same settings as used in Report View.

Text fields will have a button to their right. When pressed this will expand
the entry field to multiple lines to allow free format text. Note that the
column in the table may not allow free format text so care should be taken when
using this feature.

The toolbar on the Form view provides a quick way of performing some of the
most popular actions required.  Pressing the appropriate button invokes the
function required.

The items available on the Form view toolbar are as follows:

       Display first data row
       Display previous data row
       Display next data row
       Display last data row
       Insert a new blank data row after the current row
       Duplicate the current data row after itself
       Delete the current data row
       Display general help for the Form View


ΓòÉΓòÉΓòÉ 8.3.6. Viewer window - regions ΓòÉΓòÉΓòÉ

The data display area is made up of different regions. These regions are
defined such that the presentation of the window can be tailored by setting
their individual style attributes. This tailoring is done via the Viewer window
settings notebook. The regions and the elements of the report they cover are
described below.

 Region          Description
 Data            The elements of data returned from the database
 Column Titles   The names of the columns
 Headings        Text added to provide headings for the report
 Footings        Text added to provide footings for the report
 Background      The background of the report
 Totals          Calculated totals.
 Selected        Any data that is temporarily marked (highlighted).
 Search Target   Data that matches a search request
 Lines           The grid lines and underlines that are drawn in the Viewer
                 when it is in Report view.
 Buttons         The selection buttons on the Viewer in Report view and update
                 mode.
 Update          The text in the cell with the edit focus and the focus box.


ΓòÉΓòÉΓòÉ 8.3.7. Viewer window - File menu ΓòÉΓòÉΓòÉ

The File menu contains the following options.

 Save      Use this to save the current state of the object. It not only saves
           the Viewer window attributes but also the attributes of the other
           windows associated with the object. If the object is 'Untitled' then
           save can not be actioned directly but does invoke the 'Copy To'
           facility described below to create a new object with all of the
           attributes of the current object.
 Copy To   Use this to create a new object identical to the current state of
           the object.
 Print     Use this to print to contents of the Viewer data area to a selected
           printer.
 Quit      Use this to close XY-Query without saving any of the current
           settings. This option is only available if the Viewer is the Primary
           View.


ΓòÉΓòÉΓòÉ 8.3.8. Viewer window - Edit menu ΓòÉΓòÉΓòÉ

The Edit menu contains the following options.

 Select All              Use this to mark (highlight) all of the data in the
                         Viewer in Report view.
 Deselect All            Use this to de-highlight all marked items in the
                         Viewer.
 Cut                     Use this to move any marked text to the clipboard. The
                         original text is deleted.
 Copy                    Use this to copy any marked text to the clipboard. The
                         marked text is left unchanged.
 Paste                   Use this to insert text from the clipboard into the
                         Viewer
 Find                    Use this to invoke the Find facility which can be used
                         to search for occurrences of certain characters in the
                         Viewer.
 Find Next               Use this to perform a repeat find operation.
 Apply Pending Changes   Issue all pending table update requests. Once this is
                         selected the changes cannot be undone, unless they are
                         rejected from the database.
 Undo                    Undo the current change (i.e. restore the text in the
                         current edit box to its original value before the edit
                         was started) or undo all unapplied (pending) data
                         changes.
 Insert Row              Add an empty row of the same type as the row with
                         focus, directly after this row. Heading, footing and
                         data rows can be inserted.
 Duplicate Row           Duplicate the row with focus directly after it in the
                         report. Headings, footings and data rows can be
                         duplicated.
 Delete Row              This will delete the current row from the report.
                         Heading, footing and data rows can be deleted.
 Insert Row Before       Add an empty row of the same type as the row with
                         focus, directly before this row. Heading, footing and
                         data rows can be inserted.
 Duplicate Row Before    Duplicate the row with focus directly before it in the
                         report. Headings, footings and data rows can be
                         duplicated.
 First                   Place Form View at first data row of report
 Backward                Move backward one row (in Form View)
 Forward                 Move forward one row (in Form View)
 Last                    Place Form View at last data row of report


ΓòÉΓòÉΓòÉ 8.3.9. Viewer window - Viewer menu ΓòÉΓòÉΓòÉ

The Viewer menu contains the following options.

 Autorefresh   Use this to run the query repeatedly. The delay between the
               query finishing and it being re-started is set in the Timings
               page of the XY-Query Settings facility. The query continues to
               re-run until auto-refresh is switched off.
 Refresh now   Use this to run the query again once, thus causing the data in
               the Viewer to be refreshed.
 Stop          Use this to stop the currently executing query.
 Export        Use this to export the data in the Viewer to a file in one of a
               number of industry standard and popular file formats.


ΓòÉΓòÉΓòÉ 8.3.10. Viewer window - Selected menu ΓòÉΓòÉΓòÉ

The Selected menu has one option, Plot To Chart, which, when invoked, causes a
chart to be plotted that takes into account only the data that is marked in the
data area of the Viewer.

Note:  This option is not available if only non-numeric data is marked.


ΓòÉΓòÉΓòÉ 8.3.11. Viewer Window - View menu ΓòÉΓòÉΓòÉ

The View menu contains the following options.

 Open Settings    Use this to open the Viewer window settings notebook from
                  where the appearance and contents of the Viewer can be
                  tailored.
 Subset Columns   Use this to open the Viewer window settings notebook at the
                  Subset columns page.
 Fix Columns      Use this to open the Viewer window settings notebook at the
                  Fix columns page.
 Break Columns    Use this to open the Viewer window settings notebook at the
                  Break columns page.
 Headings         Use this to open the Viewer window settings notebook at the
                  Headings page.
 Footings         Use this to open the Viewer window settings notebook at the
                  Footings page.
 Report           Use this option to display the Viewer in Report view.
 Form             Use this option to display the Viewer in Form view.
 Browse           Use this to set the Viewer to browse mode
 Update           Use this to set the Viewer to update mode
 Toolbar          Use this option to show or suppress the toolbar on the
                  Viewer.
 Information Bar  Use this option to show or suppress the Information bar on
                  the Viewer.


ΓòÉΓòÉΓòÉ 8.3.12. Viewer window - Window menu ΓòÉΓòÉΓòÉ

The Window menu contains the following options.

 Chart          Use this to show the Chart window.
 SQL            Use this to show the SQL window.


ΓòÉΓòÉΓòÉ 8.3.13. Viewer window - Utilities menu ΓòÉΓòÉΓòÉ

The Utilities menu has the following options:

 Database       Use this to create or erase DB2/2 databases.
 Table          Use this to define, alter the definition of, create, append to,
                or erase tables.
 Sessions       Use this to register logons to be used when XY-Query connects
                to various databases.


ΓòÉΓòÉΓòÉ 8.3.14. Viewer window - Help menu ΓòÉΓòÉΓòÉ

The Help menu enables various types of help to be invoked for the application.

 General Help          Use this to display general help for the Viewer.
 Keys Help             Use this to display help explaining which key
                       combinations can be used to perform actions within the
                       Viewer window.
 Form View Help        Use this to display specific help for Form View.
 Product Information   Use this to display the XY-Query about box.


ΓòÉΓòÉΓòÉ 8.3.15. Viewer window - toolbar ΓòÉΓòÉΓòÉ

The toolbar provides a quick way of performing commonly required actions.
Pressing the appropriate button invokes the function required.

The items available on the Viewer toolbar are as follows:

       Save current object
       Copy to a new object
       Print Viewer data
       Show Viewer window settings
       Select columns to display
       Search for text
       Find next occurrence of search string
       Apply pending table updates
       Set Viewer to its Report view
       Set Viewer to its Form view
       Set Viewer to its Browse mode
       Set Viewer to its Update mode
       Switch to Chart window
       Switch to SQL window
       Display general help for Viewer


ΓòÉΓòÉΓòÉ 8.4. Chart window ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.4.1. Purpose ΓòÉΓòÉΓòÉ

The primary function of the Chart Window is to display, graphically, the data
returned after a query has been executed.

For more detailed descriptions of the functions available from the Chart window
see Working with the Chart window and Chart window settings.


ΓòÉΓòÉΓòÉ 8.4.2. Appearance ΓòÉΓòÉΓòÉ

The Chart window is constructed of a number of elements:

 Element           Description
 Title Bar         Shows name of current object and the window type i.e. CHART.
 Menu Bar          Details all menus of facilities available from the Chart
                   window.
 Toolbar           Used to provide you with fast path access to commonly used
                   functions.
 Plot Area         Area which is used to display a chart.
 Information Bar   Used to provide status and information messages to you.


ΓòÉΓòÉΓòÉ 8.4.3. Views ΓòÉΓòÉΓòÉ

There are five different chart types that can be displayed in the Plot area of
the Chart window.

     Bar Chart
     Pie Chart
     Area Chart
     Line Chart
     High-Low-Close Chart

 XY-Query Chart window (3D bar chart)

 XY-Query Chart window (line chart)

 XY-Query Chart window (pie chart)

 You can tailor the appearance of the chart to suit your requirements.


ΓòÉΓòÉΓòÉ 8.4.4. Chart window - regions ΓòÉΓòÉΓòÉ

The plot area in which the chart is displayed is made up of different regions.
These regions are individually tailorable and have their own style settings to
enable the chart to be manipulated to your exact requirements. This tailoring
is done via the Chart window settings notebook.

The regions and the parts of the plot area they cover are described below.

 Region          Description
 Chart           The chart which is plotted according to the data specified
 Titles          Main chart and pie chart titles together with titles for all
                 axes.
 Data Labels     Labels attached to the chart giving details of the values
                 plotted
 Legend          Key to match values plotted in the chart to data items
 Axes            The X , Y and Y2 axes against which charts are plotted
 Background      The background of the plot area.


ΓòÉΓòÉΓòÉ 8.4.5. Chart window - File menu ΓòÉΓòÉΓòÉ

The File menu contains the following options.

 Save      Use this to save the current state of the object. It not only saves
           the Chart window attributes but also the attributes of the other
           windows associated with the object. If the object is 'Untitled' then
           save can not be actioned directly but does invoke the 'Copy To'
           facility described below to create a new object with all of the
           attributes of the current object.
 Copy To   Use this to create a new object identical to the current state of
           the object.
 Print     Use this to print the current chart to a selected printer.
 Quit      Use this to close XY-Query without saving any of the current
           settings. This option is only available if the Chart window is the
           Primary View.


ΓòÉΓòÉΓòÉ 8.4.6. Chart window - Edit menu ΓòÉΓòÉΓòÉ

The Edit menu has one option, Copy, which causes the current chart to be copied
to the OS/2 clipboard. It is copied to the clipboard in Metafile and Bitmap
formats.


ΓòÉΓòÉΓòÉ 8.4.7. Chart window - Chart menu ΓòÉΓòÉΓòÉ

The Chart menu contains the following options.

 Auto-refresh   Use this to run the query repeatedly. The delay between the
                query finishing and it being re-started is set in the Timings
                page of the XY-Query Settings facility. The query continues to
                re-run until auto-refresh is switched off. Every time the query
                is re-run the chart is re-plotted.
 Refresh now    Use this to run the query again once, thus causing the chart to
                be re-plotted.
 Stop           Use this to stop the currently executing query.
 Export         Use this to export the current chart as a bitmap file (.BMP) or
                as a metafile (.MET)


ΓòÉΓòÉΓòÉ 8.4.8. Chart window - View menu ΓòÉΓòÉΓòÉ

The View menu contains the following options.

 Open Settings            Use this to open the Chart window settings notebook
                          from where the appearance and contents of the Chart
                          window can be tailored.
 Subset Columns and Rows  Use this to open the Chart window settings notebook
                          at the Subset page. From there the data elements to
                          use for the X and Y axes can be specified together
                          with the subset of the rows of data returned from the
                          query which are to be plotted.
 Bar                      Use this to plot a Bar chart in the Chart window.
 Line                     Use this to plot a Line chart in the Chart window.
 HL Close                 Use this to plot a High-Low Close chart in the Chart
                          window.
 Area                     Use this to plot an area chart in the Chart window.
 Pie                      Use this to plot a Pie chart in the Chart window.
 2 Dimensions             Use this to show the current chart in 2 dimensions.
 3 Dimensions             Use this to show the current chart in 3 dimensions.
 Toolbar                  Use this option to show or suppress the toolbar on
                          the Chart window.
 Information Bar          Use this option to show or suppress the Information
                          bar on the Chart window.


ΓòÉΓòÉΓòÉ 8.4.9. Chart window - Window menu ΓòÉΓòÉΓòÉ

The Window menu contains the following options.

 Viewer         Use this to show the Viewer.
 SQL            Use this to show the SQL window.


ΓòÉΓòÉΓòÉ 8.4.10. Chart window - Utilities menu ΓòÉΓòÉΓòÉ

The Utilities menu has the following options:

 Database       Use this to create or erase DB2/2 databases.
 Table          Use this to define, alter the definition of, create, append to,
                or erase tables.
 Sessions       Use this to register logons to be used when XY-Query connects
                to various databases.


ΓòÉΓòÉΓòÉ 8.4.11. Chart window - Help menu ΓòÉΓòÉΓòÉ

The Help menu enables various types of help to be invoked for the application.

 General Help          Use this to display general help for the Chart window
 Keys Help             Use this to display help explaining which key
                       combinations can be used to perform actions within the
                       Chart window.
 Product Information   Use this to display the XY-Query about box.


ΓòÉΓòÉΓòÉ 8.4.12. Chart window - toolbar ΓòÉΓòÉΓòÉ

The items available on the Chart window toolbar are:

       Save current object
       Copy to a new object
       Print Chart
       Show Chart window settings
       Open Chart settings at Subset Page
       Show data as a bar chart
       Show data as a line chart
       Show data as a high-low close chart
       Show data as an area chart
       Show data as a pie chart
       Show chart in 2 dimensions
       Show chart in 3 dimensions
       Switch to Viewer window
       Switch to SQL window
       Get help

 For more detailed descriptions of the functions available from the Chart
 window see chapter Working with the Chart window and Chart window settings.


ΓòÉΓòÉΓòÉ 8.5. Procedure window ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.5.1. Purpose ΓòÉΓòÉΓòÉ

The Procedure Window is displayed when a Procedure object is opened. Its
primary functions of the are to display , construct and execute XY-Query REXX
procedures.

For more detailed descriptions of the functions available from the Procedure
window and the available REXX interface functions, see chapter XY-Query
Procedures.


ΓòÉΓòÉΓòÉ 8.5.2. Appearance ΓòÉΓòÉΓòÉ

The Procedure window is constructed of a number of elements:

 Element           Description
 Title Bar         Shows name of current object and the window type i.e. PROC.
 Menu Bar          Details all menus available from the Procedure window.
 Toolbar           Used to provide you with fast path access to commonly used
                   functions.
 Editor            Area you can use to build a procedure.
 Information Bar   Used to display status and information messages to you.

 XY-Query Procedure window


ΓòÉΓòÉΓòÉ 8.5.3. Procedure window - File menu ΓòÉΓòÉΓòÉ

The File menu contains the following options.

 New            Use this to open a new 'Untitled' XY-Query Procedure session.
                It will have no link to the object from which it was spawned
                and will be initialised with the relevant default attributes
                from the Settings facility.
 Save           Use this to save the current state of the procedure object. If
                the object is 'Untitled' then save can not be actioned directly
                but does invoke the 'Copy To' facility described below to
                create a new object with all of the attributes of the current
                object.
 Copy To        Use this to create a new object identical to the current state
                of the object.
 Quit           Use this to close the Procedure window (and hence the Procedure
                object) without saving any of the current settings
 Print          Use this to print to contents of the Procedure editor to a
                selected printer.


ΓòÉΓòÉΓòÉ 8.5.4. Procedure window - Edit menu ΓòÉΓòÉΓòÉ

The Edit menu contains the following options.

 Select All     Use this to mark (highlight) all of the text in the Procedure
                editor.
 Deselect All   Use this to de-highlight all marked text in the Procedure
                editor.
 Cut            Use this to move any marked text in the Procedure editor to the
                clipboard. The marked text is deleted from the editor.
 Copy           Use this to copy any marked text in the Procedure editor to the
                clipboard. The marked text is left unchanged.
 Paste          Use this to paste the contents of the clipboard into the
                Procedure editor at the current cursor position.
 Clear          Use this to remove all text from the Procedure editor.


ΓòÉΓòÉΓòÉ 8.5.5. Procedure window - Procedure menu ΓòÉΓòÉΓòÉ

The Procedure menu contains the following options.

 Run            Use this to start the execution of the XY-Query Procedure query
                currently in the Procedure editor.
 Stop           Use this to request that the currently executing Procedure is
                stopped. The Procedure will terminate when the current REXX
                statement has completed.
 Skeleton       Use this to insert skeleton code for a Procedure in the
                Procedure editor.
 Models         Use this to show a the list of available XY-Query procedure
                functions. Selecting one gives an example of the syntax of the
                command.
 Import         Use this to import a Procedure from another XY-Query Procedure
                object or from a REXX command (.CMD) file.
 Export         Use this to export the Procedure to a command file.


ΓòÉΓòÉΓòÉ 8.5.6. Procedure window - View menu ΓòÉΓòÉΓòÉ

The View menu contains the following options.

 Open Settings    Use this to open the Procedure window settings notebook.
 Browse           Use this option to set the Procedure editor to read only
                  mode.
 Update           Use this option to set the Procedure editor to read / write
                  mode.
 Toolbar          Use this option to show or suppress the toolbar on the
                  Procedure window.
 Information Bar  Use this option to show or suppress the Information bar on
                  the Procedure window.


ΓòÉΓòÉΓòÉ 8.5.7. Procedure window - Help menu ΓòÉΓòÉΓòÉ

The Help menu enables various types of help to be invoked for the application.

 General Help          Use this to display general help for the Chart window
 Keys Help             Use this to display help explaining which key
                       combinations can be used to perform actions within the
                       Procedure window.
 Product Information   Use this to display the XY-Query about box.


ΓòÉΓòÉΓòÉ 8.5.8. Procedure window - toolbar ΓòÉΓòÉΓòÉ

The items available on the Procedure window toolbar are as follows:

       Save current object
       Copy to a new object
       Print Procedure text
       Show Procedure window settings
       Run Procedure
       Halt execution of Procedure
       Procedure models
       Cut to OS/2 clipboard
       Copy to OS/2 clipboard
       Paste from OS/2 clipboard
       Set window to browse (Read Only) mode
       Set window to update (Read/Write) mode
       Get help


ΓòÉΓòÉΓòÉ 9. Working with the SQL window ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 9.1. Introduction ΓòÉΓòÉΓòÉ

This chapter explains how to use the XY-Query SQL window to create, maintain
and execute queries. It also describes the other facilities available from the
window and the Settings notebook.


ΓòÉΓòÉΓòÉ 9.2. Creating queries in the SQL editor ΓòÉΓòÉΓòÉ

Each XY-Query SQL, Viewer and Chart object relies on the existence of a query
in the editor of the SQL window to enable data to be retrieved from a table in
a database. This query can be produced in a number of different ways:

     By manually typing it into the SQL editor.
     By importing from the OS/2 clipboard.
     By inserting a pre-written `model' into the SQL editor and editing it as
      required.
     By importing a query that resides in an external database system.
     By importing from an external file.
     By using the automatic query building facility, Query Builder.


ΓòÉΓòÉΓòÉ 9.2.1. Using SQL models ΓòÉΓòÉΓòÉ

The Models option provides an aid to writing a query by giving examples of the
syntax of many SQL commands. A list of available Models is presented from which
you can choose. The chosen Model is then inserted into the SQL editor and you
can then amend it if required.

To use the Models option:

   1. Open the Query menu and select Models to display a dialog box.

      Sql Models


   2. Select the model required from the list.
   3. Press OK to insert the model to the SQL editor.
   4. Edit the model text as required.


ΓòÉΓòÉΓòÉ 9.2.2. Importing queries ΓòÉΓòÉΓòÉ

The Import facility allows you to import queries from outside the XY-Query
environment.  You can import queries developed by other XY-Query users or in
certain other query formats or database queries, held locally or remotely in
DB2/2, DB2, SQL/DS and XDB databases.

To import a query open the Query menu and select Import. You can import a query
held in a file or a database. Select From File to import a query from another
XY-Query object or other query format or select From Database to import a query
stored in a DB2/2, Database Manager, DB2, SQL/DS or XDB database.

     Importing a query from a file

      When the Import - From File option is selected a dialog box is displayed
      from where the type and directory path of the source query can be
      defined.

      Use the Format pulldown to specify the type of object from which the file
      is to be imported.

      There are four options:

        -  XYQuery
        -  IBM SQL statement
        -  DDQS/2 Query  (.QRY)
        -  Plain text

      Either type in a name of the file to be imported in the Name field, and
      its file path in the Directory field, or use the Names and Directories
      lists to specify the file.

      When the dialog has been completed, press Import to retrieve the
      targetted query and display it in the SQL editor.

     Importing a query from a database

      When the Import - From Database option is selected a dialog box is
      displayed from where the name of the source query and location can be
      defined.

      Import a query from a database

      Select the location at which the query resides from the pulldown. If the
      name of the query is known then it can be entered into the Name field
      directly. Otherwise, you can specify the query name by using the owner
      and name/comment lists. Press the Refresh button to fill the Owners list
      with all userids that own queries that are available to you. Double-click
      on an owner to see all available queries associated with that owner.

      When the correct Owner-Query combination has been selected, press OK to
      retrieve the named query from the database and display it in the SQL
      window.

 To successfully import queries from database systems you need authority to
 read the tables that hold the query definitions in the database.

 To import QMF queries from either DB2/MVS or SQL/DS you must have SELECT
 access to the following tables:

     Q.OBJECT_DIRECTORY

     Q.OBJECT_DATA

     Q.OBJECT_REMARKS

 To import Query Manager queries from DB2/2 databases requires you to have
 SELECT access to the table QRWSYS.QRWSYS_OBJECT.

 To import XDB queries you must have SELECT access to the table
 SYSXDB.SYSQUERY.


ΓòÉΓòÉΓòÉ 9.2.3. Running queries ΓòÉΓòÉΓòÉ

You can run a query defined in the SQL editor or the Query Builder, in the
following ways:

     Select the Run option  from the Query menu.
     Press the Run button on the main SQL window toolbar.
     Use the Shift and F1 key combination.
     Open an existing Viewer or Chart object with a query already defined.

 Note:  If you are using the Query Builder, the query defined so far is
 constructed and placed in the SQL editor and the location selected is
 reflected in the location selection pulldown.

 Each method of running reads the query from the SQL editor and then sends a
 request to the location selected to run the query.

 If there are any variables in the query (see Substitution variables), a dialog
 box is displayed requesting the values be specified. In this case, enter the
 run time values and press on Submit.

 If the query type was Select and ran successfully, the output is available
 from the Viewer and Chart windows.  If it failed, an error message is
 displayed in the Information Bar.

 After inspecting the output, the query in the SQL editor can be modified and
 then run again.  When this is done, the output in the Viewer and/or Chart
 Window is refreshed.

 Non-SELECT type queries such as INSERT, UPDATE and DELETE do not cause the
 Viewer or Chart to be shown. Such queries cause modifications to be made to
 tables. You are asked to confirm the modifications before the query completes
 and commits its changes. The Information Bar displays information on how many
 rows in the table have been modified by the query.

 Other administrative type queries such as GRANT do not cause the Viewer to be
 shown and notification of completion or otherwise is posted on the Information
 Bar.

 Every query that runs successfully can be added automatically to the History
 Ring (depending on the selections made on the History Page of the SQL window
 settings notebook see History page). A query that runs successfully is either
 one that retrieves or modifies data (SQL return code 0), or one that correctly
 interrogates the database without finding matching data (SQL return code 100).

 When the definition of the query is complete, it forms the basis of an SQL,
 Viewer or Chart object. The query is saved with the object as explained in
 Saving from the SQL window.

 You can use command line arguments to XY-Query (XY-Query command line
 interface) to run a query defined to an object automatically.

 Note:

   1. For a query to run, XY-Query must be connected to the chosen database.
      This connection is retained after the query finishes so that subsequent
      queries against that same database will not incur the overhead of
      connection. However, if no query is run for 30 minutes, XY-Query
      automatically breaks the connection with the database.
   2. Each XY-Query session is connected only to one database at any time.
   3. An SQL object can execute any valid SQL query. Viewer and Chart objects
      however permit only SELECT queries to be executed.


ΓòÉΓòÉΓòÉ 9.2.4. Substitution variables ΓòÉΓòÉΓòÉ

When building a query, it is often a requirement to specify variables for which
you can substitute a value at run-time.  For example, you might need to enter
today's date, or the query might require a minimum and maximum value for a
field, leaving you to specify them as required.

To create a substitution variable, precede its name by an ampersand in the
query, thus:

SELECT ID, NAME, DEPT, JOB, YEARS, SALARY, COMM
FROM  USERID.STAFF
WHERE  DEPT  =  &DEPT

XY-Query takes the string of letters after the ampersand to be the name of the
substitution variable.  For character columns within the database, you are
advised to enclose the variable name in inverted commas, thus:

SELECT ID, NAME, DEPT, JOB, YEARS, SALARY, COMM
FROM  USERID.STAFF
WHERE  JOB  =  '&JOB'

In this case, you do not need to know the data type required when entering
values for the variable.

Alternatively, you can omit the inverted commas when defining a character
string variable, but you must enter the inverted commas as well as the value.

When the query is run, a dialog box is displayed, asking for values for the
variables. See Specify values for substitution variables.

Specify values for substitution variables

This dialog has a number of built in facilities which are aimed at aiding you
in your variable value specification.

XY-Query remembers the last value you specified for a particular variable name.
When the dialog is displayed XY-Query primes the entry areas for any variables
it recognises with the values it has retained. These values can be accepted or
changed. A list of all variables being maintained by XY-Query can be viewed in
the Variables page of the General section of the XY-Query Settings facility,
see General Settings - Variables page. Unwanted variables can also be removed
from XY-Query from this page.

Each variable is associated with its own entry area. To the right of these
areas is a button which, when pressed, causes the entry area to expand. You can
use this when specifying data into a character field which can can cope with
free format text.

Some key words have been defined which are recognised by XY-Query and can be
used in place of specifying an actual value for a date or time related
variable. These generally match up with similar key words defined to the SQL
language

 Keyword             Description
 USER                currently logged on userid
 CURRENT TIME        The current system time
 NOW                 The current system time (an alternative to CURRENT TIME)
 CURRENT DATE        The current system date
 TODAY               The current system date (an alternative to CURRENT DATE)
 TOMORROW            The current system date plus one day
 YESTERDAY           The current system date less one day
 CURRENT TIMESTAMP   The current system timestamp

 If you wish to reset all entry area in the dialog to be empty press the Clear
 All button. To reset a specific field,  place the cursor on the field in
 question and press the Clear Line button or use the Ctrl+Delete key
 combination.

 If you decide not to run the query then press the Cancel button. Any values
 specified before the dialog was cancelled are not retained.

 When you have specified all the variable, press the Submit button to cause the
 values to be substituted into the query. The query will then run using these
 values.

 Note:

   1. To specify a value to be null type null in the entry area for the
      variable. This applies to all SQL types.
   2. Substitution variables may be case-sensitive. depending on the Case
      attribute of the object as defined in the SQL window settings notebook
      Case page.
   3. This dialog will be displayed whenever a query is run that requires run
      time variables specified. It will appear without the SQL window if a
      Viewer or chart object is opened that runs a query requiring user data.
      It will also be displayed from within a Procedure if a query being
      executed within the procedure requires run time data.


ΓòÉΓòÉΓòÉ 9.2.5. Terminating queries ΓòÉΓòÉΓòÉ

You can terminate a running query and show the output generated so far by
opening the Query menu and selecting Stop or by pressing the Stop button on the
toolbar. Query execution terminates when the current block of data has been
returned from the database.

Note:  Running queries can also be stopped by using the relevant menu options
from the Viewer or Chart windows.


ΓòÉΓòÉΓòÉ 9.3. Using the Query Builder ΓòÉΓòÉΓòÉ

You invoke the Query Builder by selecting the Builder option from the View menu
or by pressing the Builder button on the toolbar of the SQL window.

You can exit the Query Builder at any time by selecting the Edit Sql option
from the View menu or pressing the Edit SQL toolbar button.  The SQL window
reverts to its Edit SQL view and will display a query constructed automatically
by the Query Builder depending upon the information you entered while in the
Builder,

The Builder consists of a number of panels with which you interact to produce
an SQL query. This query can then be run directly against a location or shown
in the SQL editor when the Builder is exited.

In total there are eight panels although the availability of certain panels
depends upon the type of query being constructed. The panels that are available
are as follows:

           Select SQL Statement  (All query types)

           Select Location       (All query types)

           Select Tables         (All query types)

           Table Connections     (SELECT only)

           Calculated Columns    (SELECT only)

           Select Columns        (SELECT and UPDATE only)

           Select Rows           (SELECT, UPDATE and DELETE only)

           Order Rows            (SELECT only)

 The first time the Query Builder is invoked, it displays the Select Locations
 panel from where you choose the location against which to run a query. (The
 statement type of SELECT has been pre-selected on the first panel although
 this can be changed by moving back to it to choose one of the other statement
 types.)


ΓòÉΓòÉΓòÉ 9.3.1. Query Builder - toolbar ΓòÉΓòÉΓòÉ

The panels can be selected via the toolbar under the panels when the window is
switched into its Builder view. The toolbar changes dynamically to reflect the
panels that are available. The toolbar consists of buttons for each panel
together with buttons to move forward and backwards through the panels and a
Help button.

       Display Previous Panel
       Display Next Panel
       Select SQL Statement Panel
       Select Location Panel
       Select Tables Panel
       Table Connections Panel
       Calculated Columns Panel
       Select Columns Panel
       Select Rows Panel
       Order Rows Panel
       Display help for currently displayed panel


ΓòÉΓòÉΓòÉ 9.3.2. Query Builder - Select SQL Statement panel ΓòÉΓòÉΓòÉ

Query Builder - Select SQL Statement panel

This panel enables you to select the type of SQL query statement that you want
to construct. There are four options available:

     SELECT Query
     INSERT Query
     UPDATE Query
     DELETE Query

 You select the statement type you want by pressing the appropriate button.

 The type of query selected affects the other panels that are available. For
 example, a SELECT query enables interaction with all eight Builder panels, but
 an INSERT query requires interaction with only three. When a query type is
 selected, the Builder toolbar changes to show the panels that can be accessed.

 Also on this panel you can view and edit comments for the query. If the
 Builder has been set up following a parse of a query written in the sql editor
 all comments detected in the query will be placed in the comments area.

 When a query is built and displayed in the sql editor any comments defined on
 this page will be placed at the top of the query, each line preceded with two
 dashes to indicate a comment.


ΓòÉΓòÉΓòÉ 9.3.3. Query Builder - Select Location panel ΓòÉΓòÉΓòÉ

Query Builder - Select Location panel

This panel enables you to select the location against which the query will be
run.

Choose the target location by selecting one from the displayed list of all
known locations.

To connect XY-Query to the selected location, double click on the required
location in the list, or select the entry and press the Enter key.
Alternatively, XY-Query automatically connects to the selected location when
the Select Tables panel is brought forward.


ΓòÉΓòÉΓòÉ 9.3.4. Query Builder - Select Tables panel ΓòÉΓòÉΓòÉ

The Select Tables panel enables you to select the tables which contain the data
you want to retrieve.

Query Builder - Select Tables panel

Choose the target tables by selecting from the list of tables presented in the
lists at the top of the panel.

The panel has two lists at the top which can be used in conjunction to select
those tables that contain the data. A table name is made up of two parts, the
table creator and the table name. The left hand list contains all Table
Creators in the database. When one of these is selected it populates the right
hand list with the names of all tables associated with it together with any
available table description.

When the correct Creator - Table Name combination has been found (that is both
parts are highlighted in their respective lists), then select it by double
clicking the mouse on the table name or by pressing the Add button. This adds
the full table name into the list at the bottom of the panel. The new entry
will be added directly after the currently highlighted entry.

There are restrictions as to the selection of tables inasmuch as INSERT, UPDATE
and DELETE queries can only operate on a single table but SELECT statements can
be written against multiple tables. To this end this panel only allows a single
table to be selected for all but SELECT statements and limits the number of
tables for a SELECT to twenty-six.

To change a selected table to another, firstly select the correct table name
and creator combination. Then highlight the incorrect table name in the bottom
list and press the Replace button. This will then replace the old table name
entry with the new selection.

To remove a table from the list of selected tables, select it in the list and
then press the Remove button.

If the tables selected are changed after other elements of the query have been
defined on other panels, then by implication it means that the other
information is redundant. This information will be automatically removed from
the other panels and information such as table connections and column
selections will have to be redefined.

Note:

   1. The creator and table name lists may be limited by setting filters in the
      Wildcards page of the Sql window settings.

   2. For the creator and table name lists to be filled, you must have access
      to read certain tables which contain the catalogue information. By
      default, XY-Query will try to use the system catalogue tables for a
      location. There are two tables which will be used to return the creator
      and table information, depending upon whether the lists are restricted to
      those to which you have authority or not. The catalogue tables XY-Query
      will use are named in the Table Names page of the SQL section of the
      settings facility, see SQL Settings - Table Names page.


ΓòÉΓòÉΓòÉ 9.3.5. Query Builder - Table Connections panel ΓòÉΓòÉΓòÉ

This panel is available only when a SELECT statement against multiple tables is
being built. It enables the conditions by which the tables are connected, or
joined, to be defined. It is important for multi-table SELECT statements that
all tables are joined correctly or the query could give unpredictable results.

Query Builder - Table Connections panel

At the top of the panel there are two lists containing table column details
separated by a list of connectors. To define a connection between two tables,
you select one item from each list.

The left hand list contains entries for every column in every table selected in
the previous panel. When a column is selected from this list it automatically
populates the right hand list. The content of this list is determined by the
item that was selected from the left hand list. The table that the column
selected exists in and its type are the critical factors here. The right hand
list is populated with columns from all tables other than the one in which the
left hand column exists that are of a similar type.

For example, if three tables A, B and C have been selected and a numeric column
from table A has been chosen in the left hand list, then the right hand list is
filled with all numeric columns from tables B and C. This is because tables can
be connected only via like columns.

When a choice is made from the right hand list and from the list of connectors,
the table connection condition can be entered into the list at the bottom of
the panel by pressing the Add button.

All tables that are included in a multi-table SELECT statement must be included
in at least one join condition. As a rule of thumb, the number of join
conditions that must be defined is one less than the number of tables selected.
If these conditions are not defined, then the final query will produce
unpredictable results.

To change a connection condition, define the new condition, highlight the
incorrect condition in the bottom list and then press the Replace button.

To remove a connection condition from the list of those defined, simply
highlight it in the list and then press the Remove button.

If a connection condition showing in the bottom list is double-clicked then the
top three selection lists will be set to match the selected predicate.


ΓòÉΓòÉΓòÉ 9.3.6. Query Builder - Calculated Columns panel ΓòÉΓòÉΓòÉ

This panel is available only when a SELECT statement is being constructed. It
allows the definition of user-defined calculations and expressions which can be
included in the list of columns that is returned by the query when it has run.

Query Builder - Calculated Columns panel

To create an expression you can either use information provided by XY-Query,
type it manually or use a combination of both.

In the centre of the page is an entry field in which the expression is
constructed. It is free format for you to enter what you like. No edit checking
will be performed on the expressions you create, apart from preventing you
entering blank or duplicate expressions.

At the top of the page there are two list boxes. The left hand list, titled
Operand & Operator Types, contains a list of operand and operator types. When
one of these items is selected is causes the right hand list, titled Operands &
Operators, to be populated. This second list provides you with assistance by
detailing for example, all of the column names in the selected tables.

A double-click on an entry in this list will cause the selected text to be
appended to the expression in the expression entry field.

To erase the expression currently being built you can press the button marked
C.

When the expression has be written you must press the Add button to add it to
the list of expressions at the bottom of the page.

To replace an expression, simply highlight the expression to be changed in the
bottom list and then press the Replace button.

To remove an expression from the list of those defined simply highlight it in
the bottom list and then press the Remove button.

If an expression in the bottom list is double-clicked, then the text of the
expression will be placed in the expression entry field. This will cause
anything currently in the entry field to be over-written.


ΓòÉΓòÉΓòÉ 9.3.7. Query Builder - Select Columns panel ΓòÉΓòÉΓòÉ

This panel is available only for SELECT and UPDATE statements. It enables you
to define the columns that are to be selected in the case of a SELECT query or
updated in the case of an UPDATE query.

Query Builder - Select Columns panel

The panel consists of a list containing all the columns from all the selected
tables plus any calculated columns for a SELECT query, together with some
buttons to aid the selection of columns from the list.

In its initial state, all items (columns) in the list are selected for
inclusion into the final query. You can  de-select those columns you do not
want and also specify the order in which the columns are included into the
query. This ordering is important only for SELECT queries as it defines the
sequence in which the data is presented in the Viewer when it is returned from
the database. The number visible on the extreme left hand side of the listed
items denotes its position in the final query.

When a column is de-selected from the list the positions of all other selected
columns are automatically updated to take account of the removal. When a column
is selected then the next available position is associated with this item. This
means that columns can be selected in the order in which, for SELECT queries,
the data will be presented.

As well as column name entries in the list there are entries relating to the
tables that have been selected. These appear directly before the list of
columns within that table. Although these items cannot be included as a
selected and positioned column they can be used to aid the selection and
de-selection of columns within them.  De-selecting a table name item
automatically de-selects all columns within it and causes the re-numbering of
other selected columns as appropriate.  Selecting a table name item selects all
currently un-selected columns within it with the appropriate numbering.

To de-select all columns that have been selected, press the Deselect All
button. To select all columns in the list press the Select All button.  This
selects every column that is not currently selected and allocates the newly
selected columns ascending position numbers from the top to the bottom of the
list.


ΓòÉΓòÉΓòÉ 9.3.8. Query Builder - Select Rows panel ΓòÉΓòÉΓòÉ

This panel is available only for SELECT, UPDATE and DELETE statements. You
define conditions that determine which rows in the tables are to be retrieved.

Query Builder - Select Rows panel

Each condition consists in general of a left hand operand which is a column
name from one of the selected tables, a connector which defines the type of
comparison to be performed and a right hand operand which can be user defined
text or another column. Each of these conditions is called a predicate.

At the top of the panel are three drop down lists from where the left hand
operand, connector and right hand operand can be defined. In certain cases, the
drop down list for the right hand operand can be removed in favour or one or
two entry fields for user defined text. The decision over which controls to
display to enable the right hand operand to be entered depends on the connector
that has been chosen. For example, if an IN connector is selected then a single
entry field is shown from where you must enter the list of values. If a BETWEEN
connector is selected then two entry fields are shown in which you must specify
the upper and lower bounds for the predicate. If the IS NULL or IS NOT NULL
connector is selected however, there is no requirement for a right hand operand
as the predicate is already complete.

Note:  You can specify XY-Query run time variables in the cases where the right
hand operand consists of user defined text. These take the form of a user
defined name preceded by an ampersand. For example, &DEPT.  This means that you
can substitute a value for this variable at run time.

The selection of the column from the left hand operand list determines the
content of the connector list and the right hand operand column list. There are
certain connectors that can only be used in conjunction with character fields
and these will only be available in the connector list if a character column
has been selected as the left hand operand. Similarly, the right hand operand
column list is only populated with columns of a similar type to that selected
as the left hand operand. For example, if the left hand operand is a numeric
column then the list for the right hand operand is populated only with numeric
columns.

When the predicate definition is complete then it can be added to the list of
predicates at the bottom of the panel by pressing the Add button. For all but
the first predicate defined it is necessary to decide whether the predicate
will be prefixed with AND or OR thus dictating the way in which the selection,
and elimination, of rows in the tables will be carried out. By selecting the
NOT option it is possible to negate the predicate by making it  AND NOT or OR
NOT. The predicate will be added into the list directly after the last
highlighted entry. If none is highlighted then it will be added to the bottom
of the list.

To replace a defined predicate with another, highlight the incorrect predicate
in the list and then press the Replace button.

To remove a predicate from the list of those defined simply highlight it in the
list and then press the Remove button.

The predicates list allows multiple selections to be made. This is required in
order to use the bracket and unbracket options.

When one or more rows in the predicates list are highlighted it is possible to
place brackets around the group of predicates bounded by the first and last
highlighted lines. Note that it is not necessary to highlight all predicates in
a block in order to bracket them. Simply highlighting the first and the last is
enough to delimit the block to be bracketed. When the block has been defined
press the Bracket button.

The Unbracket button is only available when the block of predicates delimited
by the first and last highlighted items have a matching set of brackets.
Pressing this button will remove an open bracket from the first highlighted
predicate and a close bracket from the last highlighted predicate.

For SELECT statements there will be a box marked Remove Duplicate Rows. To
cause all duplicate rows to be omitted from the returned data, when the query
is run, select this option.


ΓòÉΓòÉΓòÉ 9.3.9. Query Builder - Order Rows panel ΓòÉΓòÉΓòÉ

This panel is only available for SELECT statements. You use it to determine the
order in which the data is to be returned from the database.

Query Builder - Order Rows panel

It is necessary to decide which columns, of those previously selected, the data
should be sorted on and in which priority order multiple column ordering should
be done.

In its initial state no columns in the list will be selected. When a column is
selected its row in the list will display a number indicating its sort priority
and a button indicating the sort direction. By default, newly selected rows are
always set to ascending order. If it is required to change the sort direction
to you can just click on the button which will invert the arrow indicating the
sort direction.

Clicking anywhere else on a selected row will cause it to be de-selected from
the list.

Ensuring that the columns have been selected in the correct sequence and have
the correct sort direction is the only way to guarantee that the data is
displayed in the sequence required. If the sorting information is incorrect
then, although the data itself will not be affected, its presentation may well
not be what is required.

As well as column name entries in the list there are entries relating to the
tables that have been selected. These appear directly before the list of
selected columns within that table. Although these items cannot be included as
a selected and positioned column they can be used to aid the selection and
de-selection of columns within them. De-selecting a table name item has the
effect of automatically de-selecting all columns within it and causing the
re-numbering of other selected columns as appropriate. Selecting a table name
item has the effect of selecting all columns that are not currently selected
within it with the appropriate numbering in an ascending direction.

To de-select all columns that have been selected click on the Deselect All
button. To select all columns in the list click on the Select All button. This
will have the effect of selecting every column that is not currently selected
and allocate the newly selected columns ascending position numbers from the top
to the bottom of the list.


ΓòÉΓòÉΓòÉ 9.3.10. Switching views in the SQL window ΓòÉΓòÉΓòÉ

You can switch the view of the SQL window by selecting the relevant menu item
or toolbar button. Depending upon the view selected different actions are
invoked:


ΓòÉΓòÉΓòÉ 9.3.11. From builder view to edit SQL view ΓòÉΓòÉΓòÉ

If the SQL window is displayed in its Builder view and the Edit SQL menu option
is selected, or the Edit SQL toolbar button is pressed, then the Edit SQL view
is displayed.

In doing this, XY-Query will attempt to construct a query based upon the
information that has been entered so far into the various panels in the Query
Builder. If enough information has been entered then a query will be
constructed according to the selections made in the Query Builder panels and
displayed in the SQL editor.

If insufficient information has been entered into the Builder then no query is
displayed in the SQL editor.


ΓòÉΓòÉΓòÉ 9.3.12. From edit SQL view to builder view ΓòÉΓòÉΓòÉ

If the SQL window is in its Edit SQL view and the Builder menu option is
selected, or the Builder toolbar button is pressed, then the Builder view is
displayed.

As the switch is made into the Builder view, XY-Query will attempt to read any
query that is currently displayed in the SQL editor and break it down into its
constituent parts. When this has been done, the various panels of the builder
are then primed with the information extracted from the query in the SQL
editor.

Note:  If the SQL editor contains a query other than the standard data
manipulation queries of SELECT, INSERT, UPDATE and DELETE then it will not be
possible to enter the builder as it only constructs queries of these four
types.

As a result of this parsing you can change the current query from within the
Builder environment rather than by editing the raw SQL. This is useful where,
for example, a query has been imported into XY-Query from another source.

The Query Builder has limitations as regards the complexity of the queries it
is able to build. Therefore, it is only able to cope with syntax in parsed
queries that it would itself have been able to construct. If the XY-Query
parser comes across query syntax that it does not understand it displays a
panel in the Builder that contains details of the errors it has detected as
described in Query Builder - parsing errors notification panel. You can then
decide to either switch back to the SQL window and manually edit the query or
continue into the Builder and let it make its best attempt at priming the
panels.

Query Builder - parsing errors notification panel

To help with tracking down the source of an error, each message details the
line of the query at which it was detected. If you double click on an error
message line the Sql window will revert to Edit Sql view and the line
containing the error you selected will be marked in the window.

Alternatively, you can select the Edit Sql button on either the Builder or main
toolbar to switch back to Edit Sql view. In this case the currently selected
error in the list will be marked in the Edit Sql window.

Note:

   1. If you choose to continue into the builder, parts of the original query
      can be lost as the builder has no means of displaying them.
   2. The XY-Query Query Builder constructs queries which have distinct blocks
      of Join and Row conditions. To parse a set of join conditions into the
      Builder, a similar syntactical notation must be adopted. All joins should
      be bracketed together in the predicate list.  Not doing this can cause
      the Builder to treat the Join conditions as standard row conditions.

 When the error notification page is displayed the Builder toolbar contains
 only the following buttons.

       Switch back to the Edit SQL view
       Continue into the Builder
       Display help for Errors panel


ΓòÉΓòÉΓòÉ 9.4. SQL window functions ΓòÉΓòÉΓòÉ

This section details the other functions available from the SQL window:

     Save the current object (Saving from the SQL window)
     Copying to an XY-Query object (Copying to an XY-Query object from the SQL
      window.)
     Export query outside XY-Query (Exporting queries)
     Traverse and maintain the History Ring (Using the History Ring)
     Print the contents of the SQL editor (Printing queries)
     Place data in the clipboard (Copying, cutting and pasting text)
     Utilities (Utilities from the SQL window)


ΓòÉΓòÉΓòÉ 9.4.1. Saving from the SQL window ΓòÉΓòÉΓòÉ

To save, open the File menu and select Save.  This saves all information about
all three windows associated with the current object, namely the SQL , Viewer
and Chart windows. It will not affect the object type. It is quite valid to
request a save from the SQL window even if the current object is a Viewer or
Chart object.


ΓòÉΓòÉΓòÉ 9.4.2. Copying to an XY-Query object from the SQL window. ΓòÉΓòÉΓòÉ

To create a copy of the current XY-Query object, open the File menu of the SQL
window and select Copy to... to obtain the Copy-To dialog box.

Copy-To dialog box

Use the dialog box to specify the name and type of the new XY-Query object.

Complete the fields as follows:

 Format     Select one from:
                XYQuery
                XYChart
                XYViewer.
 Name       Type a name, including file extension if any, for the file in the
            field.  Alternatively, use Names to select a file to overwrite.
 Directory  Type a file path for the file in the field.  Alternatively, you can
            use Directories to select a path.
 Names/Directories Use these fields to display the names and file paths of
            existing XY-Query objects.  If necessary, select one of these and
            overwrite it.

 Press Copy to complete the operation.

 A new XY-Query object of the type specified is created which is identical, in
 all but name, to the current state of the active object.


ΓòÉΓòÉΓòÉ 9.4.3. Exporting queries ΓòÉΓòÉΓòÉ

You can to export queries from the SQL editor to non XY-Query objects enabling
them to be accessed by other applications.

To export a query:

   1. Open the Query menu and select Export...

      The dialog box displayed is similar to the one used for copying to an
      XY-Query object (Copy-To dialog box), except that the Format pulldown
      contains different choices.  The formats available are:
          IBM SQL Statement
          DDQS/2 Query (.QRY)
          Plain Text  (.TXT).
   2. Complete the fields and press Export to write the query to a named file
      of the selected type.


ΓòÉΓòÉΓòÉ 9.4.4. Using the History Ring ΓòÉΓòÉΓòÉ

The History Ring is a device that enables multiple queries to be maintained
within an individual XY-Query SQL, Viewer or Chart object. The queries
associated with the object are held in a notional `ring'. The SQL window
displays the `current' query from the ring at any particular time. The query
can be displayed in either the SQL or Build view depending upon the current
state of the window.

The mode of operation of the History ring is determined by the History page of
the SQL window settings notebook as described in History page. You can decide
that all queries that run successfully be added automatically to the ring or
you can populate the ring by adding elements into it manually. It is quite
valid to add manually a query into a ring set up to be populated automatically.

The ring does not allow duplicates so that, in the case of automatic addition,
repeatedly running the same query, for example when using the auto-refresh
option, does not cause it to be stored multiple times. The ring also does not
allow blank entries.

In order to preserve an environment in which several different queries are used
in close association, all queries in the ring can be saved with the object.
This option is again set from the History page of the SQL window settings
notebook. The query that is displayed in the SQL window at the time of the save
action is treated as the `primary' query for the object. When the object is
subsequently activated the whole ring is re-loaded.

You can have queries that have not yet been run in the ring. XY-Query
automatically takes the query in the SQL window and places it in the ring
whenever new queries are introduced by the Query Builder or Query Import.

In the case of an Import from another XY-Query SQL, Viewer or Chart object, if
the object has multiple queries itself then they will all be imported into the
ring (minus duplicates) with the primary query from the source object becoming
the current query in the SQL editor.

To assist with the management of the ring there are five menu items. These
options are displayed in the History submenu of the Query menu on the SQL
window. Some of the options only become available when at least one item is in
the ring.

 Add         This enables the manual addition of the current query into the
             History Ring, subject to the standard check for duplication.
 Backwards / Forwards These options are only available if at least one query
             has been placed in the ring. They enable the traversal of the
             ring. When one of these options is selected the next, or previous,
             query in the ring is displayed in the SQL window and the previous
             contents of the SQL editor is moved on around the ring. These two
             actions can also be invoked directly from the toolbar.
 Remove      This option is only available if at least one query has been
             placed in the ring. If this option is selected the current query
             displayed in the SQL window is removed from the ring. If there are
             other queries in the ring then the query that was notionally
             behind it is displayed in the SQL editor. If there were no other
             queries then the SQL editor is emptied and the ring rotation and
             removal facilities become unavailable.
 Remove All  This option is only available if at least one query has been
             placed in the ring. It serves to remove all queries from the ring.
             The ring rotation and removal facilities become unavailable.

 The toolbar buttons allowing traversal of the ring are only visible when the
 first query is placed in it. If all queries in the ring are subsequently
 removed then the toolbar buttons will be removed.


ΓòÉΓòÉΓòÉ 9.4.5. Printing queries ΓòÉΓòÉΓòÉ

To print the query currently displayed in the SQL editor open the File menu and
select Print, or press the printer button on the toolbar.

A dialog box displays a list of all available printers:

     Select a printer from the list.
     Press the Job button to display and change the job properties for this
      printer as required.
     Press the Print button to confirm the printing request. to print your
      query.

 XY-Query uses the OS/2 formatted print drivers installed on your system to
 produce hardcopy output.

 If you have a problem printing on a LAN connected printer where the printer
 starts up when the job is submitted but no text appears, try the following:

   1. Open the Settings for your desktop printer object.
   2. Turn to the Queue options page.
   3. Select the Printer-specific format option.


ΓòÉΓòÉΓòÉ 9.4.6. Copying, cutting and pasting text ΓòÉΓòÉΓòÉ

You can copy and cut text from, and paste text into, the SQL editor using the
OS/2 Clipboard. Before copying or cutting text, select it, either by holding
the left mouse button and dragging the pointer over it, or by holding down the
Shift key and using the arrow keys to move through the text. If all text in the
SQL editor is required use the Select all option from the Edit menu. This will
highlight all of the text in the SQL editor ready for Cut or Copy.

To copy selected text, open the Edit menu and select Copy.  The text is copied
to the Clipboard.

To cut and copy selected text, open the Edit menu and select Cut. The text is
deleted from the text area and copied to the Clipboard.

To paste an item from the clipboard into the SQL editor, position the cursor at
the point where you want the item to be inserted, open the Edit menu and select
Paste. The item is pasted into the text area.


ΓòÉΓòÉΓòÉ 9.4.7. Utilities from the SQL window ΓòÉΓòÉΓòÉ

The standard set of XY-Query utility functions are available from the SQL
window.

Some utilities are limited only to DB2/2 but others are open to all DB2
databases and XDB.

     Create a DB2/2 database (Create Database)
     Erase a DB2/2 database (Erase Database)
     Create, or append to, a DB2 or XDB table (Creating, or appending to a
      table using Viewer data)
     Define a new DB2 or XDB table (Defining a new table)
     Erase a DB2 or XDB table (Erasing a table)
     Create a DB2/2 table by importing a file (Importing a table)
     Register and de-register logons and passwords (Managing sessions)


ΓòÉΓòÉΓòÉ 9.4.8. SQL window functions whilst in builder view ΓòÉΓòÉΓòÉ

With the exception of the clipboard operations, all SQL window functions can be
performed as normal when the SQL window is in its Builder view. However, for
the functions concerned with extracting the current query from the SQL editor
such as Save, Copy-To and Export, XY-Query will firstly construct a query as
defined by the current state of the Builder panels and place it in the SQL
editor. The operations can then continue as normal.


ΓòÉΓòÉΓòÉ 9.5. SQL window settings ΓòÉΓòÉΓòÉ

Each SQL window has a Settings Notebook from where you can set the attributes
and presentation styles for the window. You use the SQL window Settings
Notebook to override the default settings for the appearance of the SQL window
and those that affect query execution.

You can display the notebook in three different ways:

     Select the Open Settings option of the View menu
     Press the Settings icon on the toolbar
     Press the right hand mouse button when the pointer is over the SQL editor
      or the location selector.

 The SQL window Settings Notebook consists of six pages:

     Presentation page
     History page
     Case page
     Limits page
     Wildcards page
     Security page

 Note:  In general all pages in a Settings notebook have Apply, Undo and
 Default buttons as standard. The Apply button takes the current settings for
 the page and applies them to the object. The Undo button sets the page
 settings back to the state they were in at the time of the last apply. The
 Default button causes the default settings to be reflected on the page. The
 defaults can be application supplied or can be supplied by the XY-Query
 Settings facility. These defaults will only be reflected in the object itself
 if they are explicitly applied.


ΓòÉΓòÉΓòÉ 9.5.1. Presentation page ΓòÉΓòÉΓòÉ

You use the Presentation Page to set the background and text colours for the
SQL editor and the location selector. You can also set the font in which any
text is displayed in the editor.

SQL Settings - Presentation page

To set the colours, press the button for the relevant area, then select a
colour from the colour matrix. The small colour sample square to the right of
the button changes to reflect the selection.

To set the font for the text in the SQL editor, select a font name from the
list of those available and then use the spin button to select the font size.

The defaults for this page are retrieved from the SQL section of the XY-Query
Settings facility as described in SQL Settings - Presentation page.


ΓòÉΓòÉΓòÉ 9.5.2. History page ΓòÉΓòÉΓòÉ

You use the SQL History Page to determine the way in which the History Ring
operates.

SQL Settings - History page

To save the History Ring with the object you must select the History Save
option. Then you can decide upon the maximum number of queries that can be
saved as the History for the object.

To get XY-Query to automatically add a query into the History Ring when it has
executed successfully, select the Add to History On Run option. If you have not
selected this queries can only be added to the ring manually.

The defaults for this page are retrieved from the SQL section of the XY-Query
Settings facility as described in SQL Settings - History page.


ΓòÉΓòÉΓòÉ 9.5.3. Case page ΓòÉΓòÉΓòÉ

You use the Case Page to select the case in which queries are submitted to the
database.

SQL Settings - Case page

To set the Case attribute, press a button to specify whether:

     The query text remains as typed
     The query text is translated to lower case
     The query text is translated to upper case

 Setting this attribute has no effect on the visual display of the query in the
 SQL editor. It only affects the internal representation of the query text as
 it passed for execution.

 The defaults for this page are retrieved from the SQL section of the XY-Query
 Settings facility as described in SQL Settings - Defaults page.


ΓòÉΓòÉΓòÉ 9.5.4. Limits page ΓòÉΓòÉΓòÉ

You use the Limits Page to set the character display limit and the row fetch
limit for the object.

SQL Settings - Limits page

 Character limit Use this field to specify the maximum number of characters
                 that are displayed in the Viewer when a column of any
                 Character type is returned from a query issued by this object.
 Fetch Limit     Use this field to specify the maximum number of rows which
                 will be fetched by a query run from the object. The value can
                 not be greater than the value set for Maximum Fetch Limit in
                 the Limits page of the General section of XY-Query Settings
                 facility. If there are more rows than this maximum, XY-Query
                 displays a message explaining that the query has stopped as
                 the fetch limit has been reached. If the extra data is
                 required then the Maximum Fetch Limit must be increased before
                 increasing the Fetch limit for the individual object. The
                 query must then be re-run to retrieve the additional data.

 The defaults for this page are retrieved from the General section of the
 XY-Query Settings facility as described in General Settings - Limits page.


ΓòÉΓòÉΓòÉ 9.5.5. Wildcards page ΓòÉΓòÉΓòÉ

SQL Settings - Wildcards page

The Wildcards page allows you to specify values for table creators and table
names that will act as wildcards to limit the amount of data retrieved into the
Select Tables page of the Builder.

The wildcards can be specified in various forms. If an exact match is required
then the exact text should be entered, for example USERID. If a fuzzy match is
required then the wildcard can be specified as for example U* or *SER*.

Note:  The wildcard indicator can be either an asterisk ,* , or a percentage
sign, %.

When multiple wildcards are specified then creators or table names will be
returned that match any of the wildcards.

In addition to the wildcards it is possible to request that tables owned by you
are returned. In order to reduce the list still further it is possible to
request that only tables to which you have the correct authority, depending
upon the type of query being built, be returned.

When Apply is pressed the Select Tables page in the Builder will be
automatically refreshed to take account of the selections.

 Creators List       Use this to specify up to 40 wildcards to use to limit the
                     number of entries returned into the Creators list of the
                     Select Tables page in the builder.
 Tables List         Use this to specify up to 40 wildcards to use to limit the
                     number of entries returned into the Table names list of
                     the Select Tables page in the builder.
 List "My Tables"    Select this to ensure that tables owned by you are
                     retrieved
 List Granted Tables Only Select this to limit the list of tables returned to
                     those for which you have the correct authority granted.

 The defaults for this page are retrieved from the SQL section of the XY-Query
 Settings facility as described in SQL Settings - Wildcards page.


ΓòÉΓòÉΓòÉ 9.5.6. Security page ΓòÉΓòÉΓòÉ

SQL Settings - Security page

The Security page allows you to apply security measures to your XY-Query Sql,
Viewer and Chart objects. You can specify an individual object to be Write
Protected, Read Protected or both.

By making an object write protected you can prevent users of the object from
saving changes they may have made, either accidentally or deliberately.

Setting read protection prevents unauthorised users from opening or executing
an object.

Both levels of protection rely on the use of passwords. An object can have a
read and a write protect password. It may be that they are both the same but
they do not need to be. It is up to the creator of the object to determine what
level of security it requires and what the passwords should be.

To set a password perform the following activities:

   1. Select the required security option from the list

   2. Enter the required password

   3. Repeat the password in the verification field

   4. Press the Set button.

   5. Press the Apply button (if all activity on the page is complete)

 When you set write protection on it is initially in its de-activated state.
 This is to allow you to continue changing the object. When all changes are
 complete you may either explicitly save or close the object. Once these
 actions are complete full write protection for the object is activated. This
 would mean that no further changes can be written to the object file.

 If you have a write protected object you can still change it if you know the
 correct password. The way to do this is as follows:

   1. Select the Write Protection security option from the list

   2. Enter the write protect password

   3. Press the De-Activate button.

   4. Press the Apply button (if all activity on the page is complete)

 This will temporarily de-activate write protection. This means that you can
 make changes to the object and save them. The act of saving will re-activate
 full write protection.

 Setting read protection on will cause the object file to be encrypted as it is
 stored thus making the file unreadable using normal text editors.

 You can only open a read protected object if you know the correct password.
 When you attempt to open a read protected object a dialog box will be
 displayed prompting you for the read protect password.

 Opening a read protected object

 Entering the correct password here will then open the XY-Query object as
 normal. If the password is incorrect then a warning is given and the object is
 not opened. You have three attempts to enter the correct password before the
 dialog will dismiss itself.

 Note:  All passwords are case sensitive and retain any leading or trailing
 spaces.


ΓòÉΓòÉΓòÉ 10. Working with the Viewer window ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 10.1. Introduction ΓòÉΓòÉΓòÉ

This chapter explains the functions available from the Viewer window and
describes the Viewer settings notebook.

For instructions on using charts to display your output, see chapter Working
with the Chart window.


ΓòÉΓòÉΓòÉ 10.2. Using the Viewer ΓòÉΓòÉΓòÉ

From the Viewer, the following facilities are available:

     Direct Editing (Direct Editing)
     Dynamic Table Updates (Table Update)
     Save the current object (Saving from the Viewer)
     Copy to an XY-Query object (Copying to an XY-Query object)
     Data export (Exporting Viewer data to a file)
     Find data (Finding data)
     Place data in the OS/2 clipboard (Selecting items and clipboard support)
     Plot a selected portion of the data to a chart (Plotting selected items
      of data)
     Print the contents of the display area (Printing the data in the Viewer)
     Refresh the data displayed re-running the query (Refreshing the data in
      the Viewer)
     Utilities (Utilities from the Viewer)
     Tailor the appearance of the Viewer using the Viewer settings (Viewer
      window settings)


ΓòÉΓòÉΓòÉ 10.2.1. Direct Editing ΓòÉΓòÉΓòÉ

Direct Editing is the term associated with the ability to directly manipulate
elements of the report displayed in the Viewer without using the settings
notebook.

Updates are possible in both the Report and Form views but only when they are
in update mode.

The elements that can be updated are as follows:

     Headings
     Column Titles
     Data
     Footings

 Note:  All in this list are directly editable from the Report view in update
 mode, however the Form view only allows the direct edit of data.

 Editing in Report view is achieved by means of an edit box which appears
 around the cell in the report which has focus. When the edit box is over the
 cell you would like to change, you can then manually edit its contents to what
 you required.

 Editing in Form view is achieved by enabling the fields displaying the data to
 be updated.

 When data is being updated edit checking is performed to ensure that the
 edited value conforms to the definition of the column to which the data
 relates. For example, it will not allow non-numeric characters in a numeric
 column or values that breach the bounds of the column type.

 Headings, footings and column titles can be updated directly within the Report
 view in update mode at all times. However, data can only be directly edited,
 in either view, depending upon the setting of the Data Update Page in the
 Viewer settings notebook. It is possible from within here to disallow the
 direct edit of data even if the Viewer is in update mode.

 This page also controls whether or not any updates made to the data should be
 reflected in the table from which the data was originally retrieved. The
 ability to do this is termed Table Update (see Table Update) and is governed
 by a number of conditions which must be met before it will be allowed. These
 include that the query must only be selecting data from a single table and the
 selected columns must not include expressions, constants or duplicates.

 If you make a mistake when editing, or inadvertently change the wrong data,
 you can restore the current cell to its original state before the edit was
 initiated by selecting the Undo - Current Change menu item under the Edit
 menu.

 You can add or delete heading, footing and data rows directly in the Viewer.
 These functions are all controlled from under the Edit menu of the Viewer.

 To delete a row of any kind from the Report view the focus must be placed on
 the line to be removed. In Form view the currently displayed data row will be
 deleted.

 To add a row within the Report view the focus must be placed upon another row
 of the same type. It is then possible to add the new row immediately before or
 after the row with focus. In Form view a new data row will be inserted after
 or before the currently displayed row. It is important to note that if you are
 employing Table Update, although you may enter a data row at a certain place
 in the report it does not imply that this would be where it would appear next
 time you run the query. The query must be written to ensure data is presented
 to you in the sequence you require.


ΓòÉΓòÉΓòÉ 10.2.2. Table Update ΓòÉΓòÉΓòÉ

Table Update is the term associated with the ability to reflect changes made to
the data by Direct Editing, in the underlying table.

A number of conditions must be met before Table Update is allowed. These
include that the query must only be selecting data from a single table and the
selected columns must not include expressions, constants or duplicates.

There are four methods of Table Update that can be used. The choice is made
from the Data Update Page of the Viewer settings notebook, see Data Update
page.

If the choice is Update Table By Cell, By Row or By Block then the updates
requests will be sent automatically by XY-Query

Alternatively, the changes can be grouped and pended until the user is ready to
issue them to the table. This is termed Update Table On Request.

The automatic sending of update requests is triggered when XY-Query detects
that focus has moved and the issue threshold has been reached. This may be one
cell, one row or a number of rows.

It is still possible to send updates through on request even if one of the
automatic options has been selected. This is achieved by using the Apply
Pending Changes option of the Edit menu or the associated toolbar button.

When changes have been made to the data in the Viewer, but the table update
requests have not yet been issued, the changed data will be displayed in the
foreground colour of the update region as specified in the Presentation page of
the Viewer settings notebook. As the updates are processed and confirmation is
received from the database, the colour is changed back to the normal data
region colour.

If you have a number of pending changes you can cancel them and restore the
data to its original state by selecting the Undo - Pending Changes menu item
under the Edit menu.


ΓòÉΓòÉΓòÉ 10.2.3. Saving from the Viewer ΓòÉΓòÉΓòÉ

To perform a save, open the File menu and select Save. This saves all
information about the three windows associated with the current object, namely
the Viewer, SQL and Chart windows. It does not affect the type of object. You
can validly request a save from the Viewer even if the current object is an SQL
or Chart object.


ΓòÉΓòÉΓòÉ 10.2.4. Copying to an XY-Query object ΓòÉΓòÉΓòÉ

To create a copy of the current XY-Query object, open the File menu of the
Viewer and select Copy to....

The dialog box displayed has the same appearance as the one used for copying or
exporting from the SQL window (Copy-To dialog box).

The formats available for copying are:

     XYViewer
     XYQuery
     XYChart

 Select a format, then specify a file name and path.  A new XY-Query object of
 the type specified is created, identical, in all but name, to the current
 state of the active object.


ΓòÉΓòÉΓòÉ 10.2.5. Exporting Viewer data to a file ΓòÉΓòÉΓòÉ

To export the data shown in the Viewer, open the Viewer menu of the Viewer and
select Export....

The dialog box displayed has the same appearance as the one used for copying or
exporting from the SQL window as shown in Copy-To dialog box.

The file formats available for exporting are:

           Import Export Format       (.IXF)

           Plain Text                 (.TXT)

           Comma Separated Variable   (.CSV)

           ASCII Delimited Files      (.DEL)

           DIF Standard               (.DIF)

           Standard DIF with headings (.DIF)

           DIF Extended               (.DIF)

           Lotus 1-2-3 spreadsheet    (.WSF)

 You select a format and then specify a file name and path.

 For export operations to text (.TXT), the resultant file contains the data
 from the Viewer together with any changes made using the Settings option (see
 Viewer window settings).

 Export operations to Data Interchange Format (.DIF) , Import Export Format
 (.IXF), Delimited ASCII Format (.DEL or .CSV) or Worksheet Format (.WSF) do
 not reflect headings, footings or column usage settings (see Viewer window
 settings).

 Note:  You can change the ASCII delimiters for .DEL and .CSV files using the
 Export page of the Viewer section of the XY-Query Settings facility (see
 Viewer Settings - Export page).


ΓòÉΓòÉΓòÉ 10.2.6. Finding data ΓòÉΓòÉΓòÉ

To search for a string of characters, open the Edit menu and select Find, or
press the appropriate button on the toolbar to display the Find dialog box.

Viewer Search dialog

Type the search string in the Search field, select any required options and
press the Find button.  The options available are:

 Column          Select the column to search from the pulldown.
 Ignore case     Find the required characters irrespective of case, for example
                 Sales  or SALES.
 Search wrap     If a forward search reaches the end of the report, continue
                 the search by wrapping round to the beginning.  Similarly, if
                 a reverse search reaches the beginning of the report, wrap
                 round to the end.
 Reverse search  Search the report backwards, from the cursor position towards
                 the beginning of the report.

 Note:  The next cell containing the data is found.  If there is another
 instance of the search string in the same cell, a subsequent Find ignores it
 and goes on to the next cell containing the string.

 To search for the next occurrence of the string, press the Find button again.
 Alternatively, open the Edit menu and select Find next, or press the
 appropriate button on the toolbar.

 Note:

   1. The search starts at the current position of the cursor in the Viewer
      display and stops at the beginning or end unless the Search Wrap option
      is selected. To search the whole report, select this option or start from
      the beginning or end. Once search parameters have been established, the
      Find Next option can be used to find the next occurrence of the string.
   2. To set the search start position simply click in the Viewer at the
      required position. If the Viewer did not previously have the focus,
      double-click the mouse button.


ΓòÉΓòÉΓòÉ 10.2.7. Selecting items and clipboard support ΓòÉΓòÉΓòÉ

When the Viewer is in Report view and update mode, rows of data can be selected
by clicking with the left mouse-button on the graphic buttons to the left of
them, and columns by clicking on the buttons above them. To select a cell,
click on the small button to its left.

By holding the shift key while selecting data, a range of data can be selected.
By holding the control key while selecting data, more data can be selected
without de-selecting the previously selected data - in this way, several
separate areas can be marked.

The Select All option under the Edit menu marks all data in the Viewer.

The availability of the clipboard operations in the Viewer depend upon which
mode it is in.

When the Viewer is in browse mode, irrespective of view, only the Copy function
may be used.

Full clipboard support can be used when the Viewer is in update mode.

To copy any marked text to the clipboard, open the Edit menu of the Viewer and
select Copy or use the CTRL+INSERT key combination.

To move any marked text to the clipboard, open the Edit menu of the Viewer and
select Cut or use the Shift+Delete key combination.

To paste text into the Viewer from the clipboard, open the Edit menu of the
Viewer and select Paste or use the Shift+Insert key combination.


ΓòÉΓòÉΓòÉ 10.2.8. Plotting selected items of data ΓòÉΓòÉΓòÉ

To plot specific items of data to a chart:

   1. Place the Viewer in Report view and Update mode.
   2. Mark the data to be plotted in the Viewer.
   3. Open the Selected menu and select Plot to Chart.

 Note:  The Plot To Chart option is only available if the marked areas of the
 Viewer data are suitable for plotting.


ΓòÉΓòÉΓòÉ 10.2.9. Printing the data in the Viewer ΓòÉΓòÉΓòÉ

To print the data displayed in the Viewer, open the File menu and select Print,
or press the printer button on the toolbar.

A dialog box is displayed showing a list of all available printers:

The dialog box is used to specify the printer on which to print the report. The
dialog should be used as follows.

     Select a printer from the list.
     Press the Job button to display and change the job properties for this
      printer as required..
     Press the Print button to confirm the printing request.

 Note:  The Viewer only prints the Report view, in either mode. Print requests
 made from Form view will cause the report view to be printed.

 XY-Query uses the OS/2 formatted print drivers installed on your system to
 produce hardcopy output.

 If you have a problem printing on a LAN connected printer where the printer
 starts up when the job is submitted but no text appears, try the following:

   1. Open the Settings for your printer object.
   2. Turn to the Queue options page.
   3. Select the Printer-specific format option.


ΓòÉΓòÉΓòÉ 10.2.10. Refreshing the data in the Viewer ΓòÉΓòÉΓòÉ

If you want to refresh the data in the Viewer, you must re-run the query. You
do this from the SQL window or by selecting the Refresh now option from the
Viewer menu.

You can stop a query that is running by selecting the Stop option from the
Viewer menu. The data retrieved so far is shown in the Viewer.

You can request that the data in the Viewer is continually refreshed thus
reflecting dynamically any changes to the database. The query is re-run after a
pre-defined delay.

To specify that the data is automatically refreshed, open the Viewer menu and
select AutoRefresh. To terminate auto-refreshing, repeat this action.

You can define the auto-refresh interval in the Timings page in the XY-Query
Settings facility. See Using the XY-Query settings facility.

Note:  The Viewer is subject to auto-refresh even if the request was issued
from the Chart window.  When the query is re-run XY-Query, refreshes all data
display windows that are visible.


ΓòÉΓòÉΓòÉ 10.2.11. Utilities from the Viewer ΓòÉΓòÉΓòÉ

The standard set of XY-Query utility functions are available from the Viewer.

Some utilities are limited only to DB2/2 but others are open to all DB2
databases and XDB.

     Create a DB2/2 database (Create Database)
     Erase a DB2/2 database (Erase Database)
     Create, or append to, a DB2 or XDB table (Creating, or appending to a
      table using Viewer data)
     Define a new DB2 or XDB table (Defining a new table)
     Erase a DB2 or XDB table (Erasing a table)
     Create a DB2/2 table by importing a file (Importing a table)
     Register and de-register logons and passwords (Managing sessions)


ΓòÉΓòÉΓòÉ 10.3. Viewer window settings ΓòÉΓòÉΓòÉ

Each Viewer window has a Settings Notebook from where you can set the
attributes and presentation styles for the window. The Viewer window settings
notebook enables you to override the default settings for the appearance of the
Viewer window as well as giving great scope for tailoring the report currently
being displayed.

You can open the Viewer settings notebook in several ways. It can be requested
by selecting the Open Settings option of the View menu, or by pressing the
Settings button on the toolbar. Both of these methods display the notebook in
its default state with the first page at the top.

You can however, open the notebook at a specific page with certain fields
pre-selected. This can be achieved by pressing the right hand mouse button
either on its own or in conjunction with the CTRL key whilst the mouse pointer
is over certain regions in the Viewer window.

A right hand mouse click over data, total, button and line regions causes the
columns page of the notebook to be pre-selected with the name field set to the
name of the column (or closest column) in which the mouse was clicked. A right
hand mouse click over a heading or footing opens the notebook at either the
Headings or Footings page with the details of the line over which the mouse was
clicked, pre-filled. If the mouse click is performed over a column title then
the Titles page is pre-selected and the details of the selected column title
pre-filled.

If the CTRL button is held down at the same time as the right hand mouse button
is pressed then the presentation page of the notebook is pre-selected. The
presentation details of the region over which the mouse was clicked are
pre-filled.

The Viewer window Settings Notebook consists of eleven pages as follows:

     Columns page
     Titles page
     Country page
     Date/Time page
     Subset page
     Fix page
     Break page
     Headings page
     Footings page
     Presentation page
     Data Update page

 Note:  In general all pages in a Settings notebook have Apply, Undo and
 Default buttons as standard. The Apply button takes the current settings for
 the page and applies them to the object. The Undo button sets the page
 settings back to the state they were in at the time of the last apply. The
 Default button causes the default settings to be reflected on the page. The
 defaults can be application supplied or can be supplied by the XY-Query
 Settings facility. These defaults will only be reflected in the object itself
 if they are explicitly applied.


ΓòÉΓòÉΓòÉ 10.3.1. Columns page ΓòÉΓòÉΓòÉ

You use the Columns page to view and set the attributes for the data columns
displayed in the Viewer.

Viewer Settings - Columns page

You can display the Columns page by positioning the mouse pointer over a
specific data column and then pressing the right hand button.  The columns page
is presented with the Name field set to the column pointed to and the attribute
fields showing the current settings for that column.

Use the Columns Page as follows:

 Name       Select a column to format from this pulldown, or use the spin
            button to select a column. The entries made in the Usage, Width,
            Alignment and Position fields are applied to the selected column
            when the Apply button is pressed.  Another column can then be
            selected and changed in the same way.
 Usage      Select the arithmetic or report function to be performed on the
            data in the column. The possible functions are:
            SUM           Total value
            AVG           Average value
            MIN           Minimum value
            MAX           Maximum value
            COUNT         Count of non-null entries
            GROUP         Group rows of report on the column
            ACROSS        Base an Across report on this column. Only one column
                          can have this usage. Selecting it for a second column
                          will automatically remove it from the original.
 Alignment  Use this field to specify the alignment (Right, Left or Centre) of
            the data in the column when it is displayed.
 Width      Use this field to specify the maximum number of characters that the
            column can display. Reducing this number beyond the original value
            can cause  the display of the data to be truncated.
 Position   Use this field to specify the position of the column in the
            display, where 1 represents the column on the extreme left, 2
            represents the column immediately to the right of it, and so on.
            Any new positions are automatically reflected in the sequence
            numbers in the Subset page.


ΓòÉΓòÉΓòÉ 10.3.2. Titles page ΓòÉΓòÉΓòÉ

You use the Titles page to view and set the names of the data columns displayed
in the Viewer.

Viewer Settings - Titles page

You can display the Titles Page by positioning the mouse pointer over a
specific column title and then pressing the right hand button.  The page is
presented with the Name field set to the column pointed to and the attribute
fields showing the current settings for that column title.

Use the Titles Page as follows:

 Name       Select a column title to format from this pulldown or use the spin
            button to select a column title. The entries made in the Data and
            Alignment fields are applied to the selected column title when the
            Apply button is pressed.  Another column can then be selected and
            changed in the same way.
 Data       Use this field to specify the new text for the column title. This
            field is limited to 18 characters. If you want the title to be on
            multiple lines, then separate the text using the Underscore
            character. For example, enter DATE_OF_BIRTH to split the title over
            three lines.

            Note:  Underneath this field is an information field showing the
            actual name of the column as defined in the database.
 Alignment  Use this field to specify the alignment (Right, Left or Centre) of
            the column title in the column when it is displayed.

 You can also change the title of a column by directly editing it on the
 Viewer. Any changes you make in this fashion will be dynamically reflected in
 this page.


ΓòÉΓòÉΓòÉ 10.3.3. Country page ΓòÉΓòÉΓòÉ

You use the Country page to specify Country specific formatting details for
columns containing numeric data in the Viewer.

Viewer Settings - Country page

In its default state it reflects the settings defined in the XY-Query Settings
facility.  Any changes made in this notebook are limited to the current object
and do not affect the global settings.

Complete the Country page as follows:

 Name            Select a column to format from this pulldown, or use the spin
                 button to select.
 Currency        Enter the symbol to be used to show monetary values in the
                 column. Use the Prefix, Suffix and None radio buttons to
                 determine if the value is to be displayed in monetary terms
                 and if so should the symbol precede or follow the value.
 1000's separator Use the pulldown to select a thousands separator for the
                 column. Use a comma to display the number one thousand as
                 1,000, or a period for 1.000.
 Decimal separator Use the pulldown to select a separator for decimals in the
                 column. Use a period to show one and a half as 1.5 or a comma
                 for 1,5.
 Decimal Places  Use this field to specify the maximum number of digits that
                 are displayed after the separator for decimal values in the
                 column. If this is, for example, set to 2 then the value
                 15.2948 is displayed as 15.29. Data displayed in the column is
                 rounded when the decimal places are reduced.
 Display Scientific Select this option to display Exponential numbers in
                 Scientific notation. If it is not selected they will be
                 displayed as decimal values.
 Override database settings Use this field to decide whether to show the data
                 in the column in its raw form as returned from the table or
                 tailored according to the settings on this page. If this field
                 is not selected then the settings are NOT used.

 The defaults for this page are retrieved from the General section of the
 XY-Query Settings facility. See General Settings - Language page for more
 information.


ΓòÉΓòÉΓòÉ 10.3.4. Date/Time page ΓòÉΓòÉΓòÉ

You use the Date/Time page to specify Country specific date and time formatting
details to be used for columns containing dates or times in the Viewer.

In its default state, this page reflects the settings defined in the XY-Query
Settings facility.

Any changes made in this notebook are limited to the current object and do not
affect the global settings.

Complete the Date / Time page as follows:

 Name                Select a column to format from this pulldown, or use the
                     spin button to select.
 Date format - format Use the pulldown to choose a date format for the column.
                     The available options are Day Month Year , Month Day Year
                     or Year Month Day.
 Date separator      Use the field and spin button to choose a date separator
                     for the column. Use a hyphen if dates are to be displayed
                     like 17-06-95.
 Time format - format Use the pulldown to choose a time format for the column.
                     The available options are 12- or 24-hour clock , am and pm
                     etc..
 Time separator      Use the field and spin button to choose a time separator
                     for the column. For example, a colon if times are to be
                     displayed like 07:30.
 Override database settings Use this field to decide whether to show the data
                     in the column in its raw form as returned from the table
                     or tailored according to the settings on this page. If
                     this field is not selected then the settings are NOT used.

 The defaults for this page are retrieved from the General section of the
 XY-Query Settings facility. See General Settings - Date / Time page for more
 information.


ΓòÉΓòÉΓòÉ 10.3.5. Subset page ΓòÉΓòÉΓòÉ

You use the Subset Page to determine which columns are displayed in the Viewer.

Viewer Settings - Subset page

The Subset page can also be displayed by opening the View menu of the Viewer
and selecting Subset columns....

Use the Subset page as follows:

 Column list   This lists all the columns available to be displayed. In its
               default state, all are selected. Columns that are currently
               selected to appear in the Viewer are highlighted.  Select and
               de-select columns by clicking on the columns in the list. Each
               selected column has a number indicating its position from left
               to right across the report.  Each new column selected is
               assigned the next available number in ascending order.

               To change the sequence numbers, de-select the columns and
               reselect them in the required order. Any new sequencing is
               automatically reflected in the Position field of the Columns
               page.
 Select All    Select all columns in the list.  Sequence numbers of columns not
               already selected are assigned from top to bottom of the list.
 Deselect All  De-select all columns in the list.

 Changes made in this page affect several other pages. For example, if a column
 is de-selected from this page it will no longer be available in the Columns,
 Titles, Country, Date/Time, Fix or Break pages.


ΓòÉΓòÉΓòÉ 10.3.6. Fix page ΓòÉΓòÉΓòÉ

You can display the Fix page by opening the View menu of the Viewer and
selecting Fix columns.... The Fix page has the same general appearance as the
Subset page.

You use the Fix Page to anchor columns to the left of the Viewer display area.
These columns are then non-scrollable horizontally. Only any remaining
non-anchored columns can be scrolled.

Complete the Fix page as follows:

 Column list   This lists all of the columns currently displayed. Only those
               columns that have been selected in the Subset page are
               available.  Columns that are currently fixed are highlighted.

               Select and de-select columns by clicking on the columns in the
               list.  Each selected column is allocated a number indicating the
               columns position from left to right across the fixed portion of
               the Viewer.  Each new column selected is assigned the next
               available number. To change the sequence, de-select the columns
               and select them in the required order.
 Select All    Select all columns in the list. Sequence numbers of columns not
               already selected are assigned from top to bottom of the list.
 Deselect All  Deselect all columns in the list.


ΓòÉΓòÉΓòÉ 10.3.7. Break page ΓòÉΓòÉΓòÉ

You can display the Break page by opening the View menu of the Viewer and
selecting Break columns....

Viewer Settings - Break page

You use the Break Page to specify the columns on which the report will break
after a change in value.

Complete the Break page as follows:

 Column list   This lists all the columns currently displayed.  Only those
               columns that have been selected in the Subset page are
               available. The columns used to break the report are highlighted.

               Select and de-select columns by clicking on the columns in the
               list.  Each selected column is allocated a number indicating the
               order in which the breaks are actioned. Each new column selected
               is assigned the next available number.  To change the sequence
               numbers, de-select the columns and select them in the required
               order.
 Select All    Select all columns in the list.  Sequence numbers of columns not
               already selected are assigned from top to bottom of the list.
 Deselect All  De-select all columns in the list.
 Break data on totals If this is selected and the report includes breaks, then
               the data values on which the report breaks will be dropped onto
               the totals line.
 Totals only   If this is selected then the report will only show total lines.

 The break data on totals and totals only options have the effect of altering
 the displayed report to make it more concise and/or more informative.

 For example, a fragment of a report giving salary totals by department may
 display data as follows:

  10       Mgr     22,959.20
           Mgr     20,010.00
           Mgr     19,260.25
           Mgr     21,234.00
                   83,463.45
  15       Clerk   12,508.20
           Clerk   12,258.50
           Mgr     20,659.80
           Sales   16,502.83
                   61,929.33

 When the data is viewed in Report view/read only mode the break data is not
 repeated. This means that it may not be very easy to see which break values
 relate to which sub-total.

 If the option to show Break data on totals is selected then the above report
 fragment would change as follows:

  DEPT     JOB     SALARY
  10       Mgr     22,959.20
           Mgr     20,010.00
           Mgr     19,260.25
           Mgr     21,234.00
  10               83,463.45
  15       Clerk   12,508.20
           Clerk   12,258.50
           Mgr     20,659.80
           Sales   16,502.83
  15               61,929.33

 If you select Totals only the report described above could be condensed to
 only show the total lines (sub- totals and grand totals) as follows:

  DEPT    SALARY
          83,463.45
          61,929.33
          64,286.10
          77,285.55
          58,369.05
          86,090.80
          86,076.20
          66,147.00
          583,647.48

 This in itself may not be exactly what you required, but when it is used in
 conjunction with the Break data on totals option a more useful report may be
 displayed, as follows:

  DEPT    SALARY
  10      83,463.45
  15      61,929.33
  20      64,286.10
  38      77,285.55
  42      58,369.05
  51      86,090.80
  66      86,076.20
  84      66,147.00
          583,647.48


ΓòÉΓòÉΓòÉ 10.3.8. Headings page ΓòÉΓòÉΓòÉ

You use the Headings Page to specify up to twenty lines of heading text which
are displayed above the data at the top of the report.

Viewer Settings - Headings page

You can display the Headings Page by positioning the mouse pointer over a
heading and then clicking the right hand button.  The Headings page is
displayed with the fields pre-filled with the attributes of the heading line
clicked.

Complete the Headings page as follows:

 Heading    Use this field to view the current lines of heading text. In
            conjunction with the Text and Position fields you can amend an
            existing heading or add a new one.  All headings can be viewed by
            pulling down the list. Select the heading line from this field and
            then write the text of the heading in the Text field below.
 Text       Use this field to enter or update the text of the heading line.
 Alignment  Use this to Right, Left or Centre align the heading line.
 Position   Use the spin button to change the position of the heading line.
            For example, changing the number from 3 to 1 makes the heading
            currently on line 3, the top heading line. The headings originally
            on lines 1 and 2 are automatically moved to lines 2 and 3
            respectively.

 Note:

   1. You must press Apply after entering each heading line in order to
      register it.
   2. .You can also change the the text of a heading line by directly editing
      it on the Viewer. Any changes you make in this fashion will be
      dynamically reflected in this page.
   3. Within a line of heading text, you can specify variables for which a
      value will be substituted at run time. If the current date is required in
      the heading enter &date in the text area.  Similarly, enter &time to show
      the time at which the data was produced. Also, any other substitution
      variables known to XY-Query can be specified. These can be variables
      specified in the query that has run or one set by a previous query.  See
      General Settings - Variables page for more information.


ΓòÉΓòÉΓòÉ 10.3.9. Footings page ΓòÉΓòÉΓòÉ

You use the Footings Page to specify up to twenty lines of footing text which
are displayed below the data at the bottom of the report.

Viewer Settings - Footings page

You can display the Footings Page by positioning the mouse pointer over a
heading and then pressing the right hand button.  The Footings page appears
with the fields pre-filled with the attributes of the footing line clicked.

Complete the Footings page as follows:

 Footing    Use this field to view the current lines of footing text. In
            conjunction with the Text and Position fields, you can amend an
            existing footing or add a new one.  All footings can be displayed
            by pulling down the list.  Select the footing line in this field
            and then write the text of the footing in the Text field below.
 Text       Use this field to enter or update the text of the footing line.
 Alignment  Use this to Right, Left or Centre align the footing line.
 Position   Use the spin button to change the position of the footing line.
            For example, changing the number from 3 to 1 makes the footing
            currently on line 3, the first footing line. The footings
            originally on lines 1 and 2 are automatically moved to lines 2 and
            3 respectively.

 Note:

   1. You must press Apply after entering each footing line in order to
      register it.
   2. .You can also change the the text of a footing line by directly editing
      it on the Viewer. Any changes you make in this fashion will be
      dynamically reflected in this page.
   3. Within a line of footing text, you can specify variables for which a
      value will be substituted at run time. If the current date is required in
      the footing enter &date in the text area.  Similarly, enter &time to show
      the time at which the data was produced. Also, any other substitution
      variables known to XY-Query can be specified. These can be variables
      specified in the query that has run or one set by a previous query. See
      General Settings - Variables page for more information.
   4. The Footings page has the same general appearance as the Headings  page.


ΓòÉΓòÉΓòÉ 10.3.10. Presentation page ΓòÉΓòÉΓòÉ

You use the Presentation page to specify fonts and colours for the various
regions of the Viewer display area.

Viewer Settings - Presentation page

You can display the Presentation Page by positioning the mouse pointer over a
specific region in the Viewer, and then pressing the right hand button while
holding down the Ctrl key. The Presentation page is displayed with the fields
pre-filled with the attributes of the region over which the mouse was clicked.

The defaults for this page are retrieved from the Viewer section of the
XY-Query Settings facility. In its default state it reflects the settings
defined in the XY-Query Settings facility. Any changes made in this notebook
are limited to the current object and do not affect the global settings. See
Viewer Settings - Presentation page for more information.

Note:  You can also use the OS/2 fonts and colours facilities for this. Drag
the font or colour to the required part of the report.  If the control key is
held while dragging a colour, the foreground is coloured.  If it is not, the
background is coloured.

To set the presentation attributes for a region firstly select it from the
pulldown and then set the attributes as shown below:

 Font name / size Select a font name from the pulldown and use the spin button
                to select a font size.  (You can only set a font for regions
                that show text i.e. headings, column titles, data, totals and
                footings.)
 Radio buttons  Select a radio button for the section of the region to be
                tailored, then select a colour from the colour matrix. The
                small colour sample square to the right of the button changes
                to reflect the selection. Different regions have different
                attributes that can be tailored.
                     Region         Attributes
                Headings            Font, font size and text colour
                Column Titles       Font, font size and text colour
                Data                Font, font size and text colour
                Totals              Font, font size and text colour
                Footings            Font, font size and text colour
                Selected            Text and background colours
                Search Target       Text and background colours
                Background          Background and window frame colours
                Lines               Vertical and horizontal line colours
                Buttons             Row, column and cell selection button
                                    colours
                Update              The colour of the  edit box and updated and
                                    unapplied data changes

 When the tailoring is complete for a region, you must press the Apply button
 to register the settings for that region before the next region is selected.


ΓòÉΓòÉΓòÉ 10.3.11. Data Update page ΓòÉΓòÉΓòÉ

You use the Data Update page to specify the mode you wish to use for the update
of the data displayed in the Viewer.

Viewer Settings - Data Update page

You select on option from the following:

 No Update            Select this if no updates are to be allowed to the Viewer
                      data.
 Update report Only   Select this to allow updates to be made to the data
                      without issuing any update requests to the underlying
                      table.
 Update Table On Request Select this to allow updates made to the data to be
                      issued to the underlying table. The update requests are
                      pended until you specifically request their issue.
 Update Table By Cell Select this to automatically issue a table update request
                      when a single data cell is changed.
 Update Table By Row  Select this to automatically issue a table update request
                      when updates to a single row have been completed.
 Update Table By Block Select this to automatically issue table update requests
                      when a pre-determined number of rows have been changed.
                      This value is set using the Block Size spin button.

 Note:  In certain circumstances, some options will not be available. For
 example, if the data displayed in the Viewer is the result of a query across
 two or more tables then the four Table Update options will not be available.

 The defaults for this page are retrieved from the Viewer section of the
 XY-Query Settings facility. See Viewer Settings - Data Update page for more
 information.


ΓòÉΓòÉΓòÉ 10.4. Report styles ΓòÉΓòÉΓòÉ

After a query has run and returned data there are a large number of formatting
options, available from the Viewer window settings notebook, you can use to
make your report more informative and useful.

Applying headings, footings, arithmetic functions and breaks amongst others
enables you to change a data only report into one that is clearer and more
useful.

For example, it is possible to turn a report containing a large number of
totals and sub-totals into a more concise report showing only the total data.
XY-Query calls this report style Totals Only.

There are some more advanced reporting styles and features available that give
you more flexibility in your reporting. XY-Query calls these advanced report
styles GROUP and ACROSS.


ΓòÉΓòÉΓòÉ 10.4.1. Creating a Totals Only report ΓòÉΓòÉΓòÉ

If you have a report on which you have specified breaks and arithmetic usages
you get a report with a mixture of data and total rows. The following fragment
is an example of the report layout you may see.

DEPT     JOB   YEARS   SALARY
--------------------------------
10       Mgr     7     22,959.20
                 10    20,010.00
                 5     19,260.25
                 12    21,234.00
                 9     83,463.45
                 9     83,463.45
15       Clerk   5     12,508.20
                 4     12,258.50
                 5     24,766.70
         Mgr     10    20,659.80
                 10    20,659.80
         Sales   7     16,502.83
                 7     16,502.83
                 7     61,929.33

When the data is viewed in Report view/read only mode the repeated break data
is not displayed. This means that in large reports it may not be very easy to
see which break values relate to which sub-total.

By selecting the Break data on totals option on the Break page of the Viewer
settings notebook, you can drop the break data relating to the total onto the
total line.

Doing this would change this report fragment as follows:

DEPT     JOB   YEARS   SALARY
--------------------------------
10       Mgr     7     22,959.20
                 10    20,010.00
                 5     19,260.25
                 12    21,234.00
10       Mgr     9     83,463.45
10               9     83,463.45
15       Clerk   5     12,508.20
                 4     12,258.50
15       Clerk   5     24,766.70
         Mgr     10    20,659.80
15       Mgr     10    20,659.80
         Sales   7     16,502.83
15       Sales   7     16,502.83
15               7     61,929.33

The next stage on from this would be to only display the total lines. You can
specify this by selecting the Totals only option on the Break page of the
Viewer settings notebook.

If both options are set you can generate a summary totals report which displays
only the calculations and totals you are interested in. The following figure
gives an example XY-Query report in which the first two columns have been given
break levels and the latter two arithmetic usages. The options to drop the
break data onto the total lines and to show only the total lines have both been
selected.


Viewer - Totals Only Report

When the Viewer, whilst displaying a Totals only report, is switched into Form
view a row by row analysis of the total data can be performed. Each totals row
will be presented individually in the Form view.


ΓòÉΓòÉΓòÉ 10.4.2. Creating a GROUP report ΓòÉΓòÉΓòÉ

Group reports have been enabled by the provision of the usage GROUP in the
usage field of the Columns page of the Viewer settings notebook.

In essence a Group report is a summary report. It summarises values, in one or
more columns which have arithmetic usages defined, against distinct values or
combinations in one or more columns to which GROUP usages have been defined.

The description of a Group report is best served by means of an example.
Suppose the following data was returned to XY-Query from a database.

DEPT     YEARS   SALARY
--------------------------
10       7       22,959.20
10       10      20,010.00
10       5       19,260.25
10       12      21,234.00
15       10      20,659.80
15       7       16,502.83
15       5       12,508.20
15       4       12,258.50
20       7       18,357.50
20       8       18,171.25
20       -       13,504.60
20       8       14,252.75

If usages are applied to the data columns as follows the data report can be
transformed into a Group summary report.

 DEPT      GROUP
 YEARS     AVG
 SALARY    SUM


 The following report fragment shows how the data has been summarised according
 to the usages set.

           AVG     SUM
  DEPT     YEARS   SALARY
  --------------------------
  10       9       83,463.45
  15       7       61,929.33
  20       8       64,286.10

 When XY-Query produces the summary data for the Group report it processes the
 rows of data returned from the database in the order they are returned. When
 the value in the selected Group column changes it is considered to be the end
 of the current group and summary data is produced at that point. This means
 that in order to guarantee the most concise and useful Group report, the query
 executed must request the data to be returned in the order of the GROUPed
 columns.

 As soon as one column is given the GROUP usage XY-Query will convert the
 current report into a Group report. All columns that have being given an
 aggregation usage (SUM/AVG/MIN/MAX/COUNT) will immediately be summarised
 according to their usage. Any columns that do not have an aggregation usage
 will be left empty.

 Group reports in XY-Query can still benefit from the large number of other
 formatting options available. For example the following figure shows a report
 which has two GROUP columns, headings, footings and a break level specified.

 Viewer - Group report

 When the Viewer, whilst displaying a Group report, is switched into Form view
 a row by row analysis of the summarised data can be performed. Each summarised
 row will be presented individually in the Form view. Note that only the
 summary data rows will be displayed in the Form view. Any total rows caused by
 break levels or the grand total row will not be displayed.


ΓòÉΓòÉΓòÉ 10.4.3. Creating an ACROSS report ΓòÉΓòÉΓòÉ

When you have produced your summary Group report it is then possible to take it
a step further and convert it into an Across report. This type of report hinges
on the selection of one column in the report to have a usage code of ACROSS.
This is set from the Columns page of the Viewer settings notebook. Note that
only one column can have this usage code. Setting it to a second will
automatically remove it from the original.

In an Across report additional columns of data are created in the report that
summarise the column chosen as the ACROSS column. For each distinct value in
this column a group of columns will be produced that display the summarised
values for the columns with aggregation usages applied to them.

The description of an Across report is best served by means of an example.
Suppose the following data was returned to XY-Query from a database.

DEPT     JOB     YEARS   SALARY
----------------------------------
10       Mgr     7       22,959.20
10       Mgr     10      20,010.00
10       Mgr     5       19,260.25
10       Mgr     12      21,234.00
15       Clerk   5       12,508.20
15       Clerk   4       12,258.50
15       Mgr     10      20,659.80
15       Sales   7       16,502.83
20       Clerk   -       13,504.60
20       Clerk   8       14,252.75
20       Mgr     7       18,357.50
20       Sales   8       18,171.25
38       Clerk   -       12,954.75
38       Clerk   3       12,009.75
38       Mgr     5       17,506.75
38       Sales   6       18,006.00
38       Sales   -       16,808.30

Firstly, apply the following usages to the data columns to produce a Group
report.

 DEPT      GROUP
 JOB       GROUP
 YEARS     AVG
 SALARY    SUM

 The following report fragment shows how the data will be summarised according
 to the usages set.

                   AVG     SUM
  DEPT     JOB     YEARS   SALARY
  ----------------------------------
  10       Mgr     9       83,463.45
  15       Clerk   5       24,766.70
  15       Mgr     10      20,659.80
  15       Sales   7       16,502.83
  20       Clerk   8       27,757.35
  20       Mgr     7       18,357.50
  20       Sales   8       18,171.25
  38       Clerk   3       24,964.50
  38       Mgr     5       17,506.75
  38       Sales   6       34,814.30

 Now change the usage of the JOB column to be ACROSS. This has a marked effect
 on the data that is displayed.

           <--------------------------------- JOB ------------------------------->
           <----- Mgr ----->  <---- Clerk --->  <---- Sales --->  <---- TOTAL --->
           AVG     SUM        AVG    SUM        AVG    SUM        AVG    SUM
  DEPT     YEARS   SALARY     YEARS  SALARY     YEARS  SALARY     YEARS  SALARY
  10       9       83,463.45                                      9      83,463.45
  15       10      20,659.80  5      24,766.70  7      16,502.83  7      61,929.33
  20       7       18,357.50  8      27,757.35  8      18,171.25  8      64,286.10
  38       5       17,506.75  3      24,964.50  6      34,814.30  5      77,285.55

 You will notice that the JOB column has been removed from the report and in
 its place a number of extra column groupings have been created. The distinct
 values in the JOB column (Mgr/Clerk/Sales) are each given their own column
 grouping which present the calculated totals for the columns with aggregation
 usages.

 The column titles region will expand to show on which column the report is
 based, in this instance JOB, and the distinct values found in the column which
 now have individual summary column groupings.

 If you want to re-order the columns in the Viewer by using the Subset page of
 the settings, all of the across groupings will be treated as one column and
 positioned en-masse wherever the ACROSS column is placed. The total columns in
 the report are the real aggregated columns and can positioned as you wish,
 together as shown above or separated as required. Only GROUP columns can be
 fixed in an Across report.

 Across reports in XY-Query can still benefit from the large number of other
 formatting options available. For example the following figure shows an Across
 report with headings, footings and the GROUP column fixed.

 Viewer - Across report

 When the Viewer, whilst displaying an Across report, is switched into Form
 view a row by row analysis of the summarised data can be performed. Each
 summarised row will be presented individually in the Form view. Note that only
 the summary data rows will be displayed in the Form view. Any total rows
 caused by break levels or the grand total row will not be displayed.


ΓòÉΓòÉΓòÉ 11. Working with the Chart window ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 11.1. Introduction ΓòÉΓòÉΓòÉ

This chapter explains the functions available from the Chart window and the
Chart window settings notebook.

For instructions on using the Viewer to display your output, see chapter
Working with the Viewer window.


ΓòÉΓòÉΓòÉ 11.2. Using the Chart window ΓòÉΓòÉΓòÉ

From the Chart window, the following facilities are available:

     Save the current object (Saving from the Chart window)
     Copy to an XY-Query object (Copying to an XY-Query object)
     Export the Chart data (Exporting Chart data to a file)
     Place data in the OS/2 clipboard (Copying a Chart to the clipboard)
     Print the chart (Printing a chart)
     Refresh the chart displayed by re-running the query (Refreshing the
      Chart)
     Utilities (Utilities from the Chart window)
     Tailor the appearance of the Chart using the Chart settings (Chart window
      settings)


ΓòÉΓòÉΓòÉ 11.2.1. Saving from the Chart window ΓòÉΓòÉΓòÉ

To perform a save, open the File menu and select Save. This saves all
information about the three windows associated with the current object, namely
the SQL , Viewer and Chart windows. It does not affect the type of object. You
can validly request a save from the Chart window even if the current object is
an SQL or Viewer object.


ΓòÉΓòÉΓòÉ 11.2.2. Copying to an XY-Query object ΓòÉΓòÉΓòÉ

To create a copy of the current XY-Query object, open the File menu of the
Chart window and select Copy to... to obtain a dialog box. This has the same
appearance as the one used for copying or exporting from the SQL window
(Copy-To dialog box).

The formats available for copying are:

     XYChart
     XYViewer
     XYQuery

 You select a format, then specify a file name and directory path.  A new
 XY-Query object of the type specified is created, identical, in all but name,
 to the current state of the active object. The format you select determines
 the primary view of the newly created object.


ΓòÉΓòÉΓòÉ 11.2.3. Exporting Chart data to a file ΓòÉΓòÉΓòÉ

To export the Chart, open the Chart menu of the Chart window and select
Export.... The dialog box displayed the same appearance as the one used for
copying or exporting Copy-to activities (see Copy-To dialog box).

The file formats available for exporting are:

           Bitmap     (.BMP)

           Metafile   (.MET)

 Select a format, then specify a file name and directory path for the exported
 chart.


ΓòÉΓòÉΓòÉ 11.2.4. Copying a Chart to the clipboard ΓòÉΓòÉΓòÉ

You can copy the whole chart to the OS/2 clipboard by selecting the Copy option
of the Edit menu. The chart is placed in the clipboard in Bitmap and Metafile
formats.

You can paste the chart only into applications that can accept the Bitmap and
Metafile formats.


ΓòÉΓòÉΓòÉ 11.2.5. Printing a chart ΓòÉΓòÉΓòÉ

To print the Chart:

   1. Open the File menu and select Print, or press the printer icon on the
      toolbar to display a dialog box listing all available printers.
   2. Select a printer.
   3. Press the Job button to display and change the job properties for this
      printer.
   4. Press the Print button to confirm the printing request.

 The image of the Chart display area is then printed on the specified printer.

 XY-Query uses the OS/2 formatted print drivers installed on your system to
 produce hardcopy output.

 If you have a problem printing on a LAN connected printer where the printer
 starts up when the job is submitted but no text appears, try the following:

   1. Open the Settings for your printer object.
   2. Turn to the Queue options page.
   3. Select the Printer-specific format option.


ΓòÉΓòÉΓòÉ 11.2.6. Refreshing the Chart ΓòÉΓòÉΓòÉ

To refresh the Chart, the query has to be re-run. You do this either from the
SQL window itself or by selecting the Refresh now option from the Chart menu.

You can stop a running query by selecting the Stop option from the Chart menu.
The data retrieved so far is plotted in the Chart window.

You can request that the Chart is continually refreshed and re-plotted thus
reflecting dynamically any changes to the database. The query is re-run after a
pre-defined delay.

To specify that the data is automatically refreshed, open the Chart menu and
select AutoRefresh. To terminate the auto-refreshing repeat this action.

You can define the auto-refresh interval in the Timings page in the XY-Query
Settings facility. See Using the XY-Query settings facility.

Note:  A Chart is subject to auto-refresh even if the request was issued from
the Viewer. When the query is re-run XY-Query refreshes all data display
windows that are visible.


ΓòÉΓòÉΓòÉ 11.2.7. Utilities from the Chart window ΓòÉΓòÉΓòÉ

The standard set of XY-Query utility functions are available from the Chart
window.

Some utilities are limited only to DB2/2 but others are open to all DB2
databases and XDB.

     Create a DB2/2 database (Create Database)
     Erase a DB2/2 database (Erase Database)
     Create, or append to, a DB2 or XDB table (Creating, or appending to a
      table using Viewer data)
     Define a new DB2 or XDB table (Defining a new table)
     Erase a DB2 or XDB table (Erasing a table)
     Create a DB2/2 table by importing a file (Importing a table)
     Register and de-register logons and passwords (Managing sessions)


ΓòÉΓòÉΓòÉ 11.3. Chart window settings ΓòÉΓòÉΓòÉ

Each Chart window has a Settings Notebook from where you can set the attributes
and presentation styles for the window. You can use the Chart window settings
notebook to override the default settings for the appearance of the Chart
window and apply your own individual tailoring.

There are number of ways to open the Chart settings notebook. It can be
requested by selecting the Open Settings option of the View menu, or by
pressing the Settings button on the toolbar. Both of these methods display the
notebook in its default state with the first page at the top.

You can also open the notebook at a specific page with certain fields
pre-selected. This can be achieved by pressing the right hand mouse button
either on its own or in conjunction with the CTRL key whilst the mouse pointer
is over certain regions in the Chart window.

The Chart window settings notebook consists of eight pages as follows:

     Types page
     Titles page
     Axes page
     Labels page
     Legend page
     Elements page
     Background page
     Subset page

 Note:  In general all pages in a Settings notebook have Apply, Undo and
 Default buttons as standard. The Apply button takes the current settings for
 the page and applies them to the object. The Undo button sets the page
 settings back to the state they were in at the time of the last apply. The
 Default button causes the default settings to be reflected on the page. The
 defaults can be application supplied or can be supplied by the XY-Query
 Settings facility. These defaults will only be reflected in the object itself
 if they are explicitly applied.


ΓòÉΓòÉΓòÉ 11.3.1. Types page ΓòÉΓòÉΓòÉ

You use the Types page to set the presentation attributes for the types of
chart which can be displayed. Although the data can only be represented by one
chart at a time you can set up style attributes for all available chart types.
The examples show the settings for a bar chart and a pie chart.

Chart Settings - Types page (for bar charts)

Chart Settings - Types page (for pie charts)

In its default state this page reflects the settings defined for the chart
types in the Chart section of the XY-Query settings facility.  See Chart
Settings - Types page for more information.

Any changes made in this page are limited to the current object and do not
affect the global settings.

Complete the Types page as follows:

 Chart   Use the pulldown to choose the type of chart for which to set the
         style attributes and to display.
 Styles  Each individual chart type has its own unique set of style attributes
         that can be tailored. The displayed attributes change dynamically
         whenever a new type is selected from the chart pulldown. You should
         set the options as desired for each chart type.

 You must press the Apply button on the page to retain the tailored settings
 for each chart type. This re-plots the chart taking account of the latest
 presentation settings.

 Note:  You can also switch the chart displayed between different types by
 using the relevant buttons on the toolbar. (The presentation of the displayed
 chart is determined by the style attributes for the chart type as detailed on
 this page.)  If the notebook is displayed whenever the toolbar method is used
 then this page is brought to the front with the newly selected chart type and
 its style settings pre-filled in the page.


ΓòÉΓòÉΓòÉ 11.3.2. Titles page ΓòÉΓòÉΓòÉ

You use the Titles page to set the text to be displayed for the various titles
that appear on a chart.  You can also set the colour for the title and the
attributes of the box in which the title appears.

Chart Settings - Titles page

In its default state this page reflects the settings defined for the chart
titles in the Chart section of the XY-Query settings facility. See Chart
Settings - Titles page for more information.

Any changes made in this page are limited to the current object and do not
affect the global settings.

Complete the Titles page as follows:

 Title      Use the pulldown to choose the titles for which to set the text and
            presentation attributes. There are five titles for which attributes
            can be set, namely:
                The main title of the chart
                Title along X-Axis
                Title along Y-Axis
                Title along Y2-Axis
                Pie chart title (colour attributes only)
 Data       Use this field to enter the actual text to appear in the title area
            on the chart.  This field is not available for the Pie Title option
            as the titles that appear over this type of chart is determined by
            the column name on which it is based. For the Main Title only it is
            possible to split the title over multiple lines by adding the
            characters /n at the point of a line break. For example, entering
            Salary Report/nBy Department would put the title on two lines.
 Font Name / Font Size Use these fields to specify the font used to display the
            title text on the chart.
 Foreground Use this field to set the foreground colour for the title text.
            Select the foreground radio button and then select the required
            colour from the colour matrix. The small colour sample square to
            the left of the button changes to show your selection.
 Background Use this field to set the background colour for the box containing
            the title text. Select the background radio button and then select
            the required colour from the colour matrix.  The small colour
            sample square to the left of the button changes to reflect the
            selection.
 Outline    Use this field to set the outline colour for the box containing the
            title text. Select the Outline radio button and then select the
            required colour from the colour matrix. The small colour sample
            square to the left of the button changes to reflect the selection.
 Shadow     Use this field to determine whether or not the box containing the
            title text is displayed with a shadow.

 You must select the Apply button on the page to retain the tailored settings
 for each chart type.  This re-plots the chart to take account of the latest
 set of presentation attributes.

 Note:  Only the titles relevant to the currently displayed chart type are
 available. For example, you cannot set Pie Title attributes when the currently
 displayed chart is a bar chart.


ΓòÉΓòÉΓòÉ 11.3.3. Axes page ΓòÉΓòÉΓòÉ

Use the Axes page to set the display attributes for the various axes that
appear on a chart.

Chart Settings - Axes page

In its default state this page reflects the settings defined for the chart axes
in the Chart section of the XY-Query settings facility, See Chart Settings -
Axes page for more information. Any changes made in this page are limited to
the current object and do not affect the global settings.

Complete the Axes page as follows:

 Axis       Use the pulldown to choose the axis for which to set the
            presentation attributes.  There are three axes for which attributes
            can be set, namely:
                X-Axis
                Y-Axis
                Y2-Axis
 Font Name / Font Size Use these fields to specify the font in which the axis
            values should be displayed on the chart.
 Foreground Use this field to set the foreground colour for the axis value
            text. Select the foreground radio button and then select the
            required colour from the colour matrix. The small colour sample
            square to the left of the button changes to reflect the selection.
 Background Use this field to set the background colour for the box containing
            the axis value text. Select the background radio button and then
            select the required colour from the colour matrix. The small colour
            sample square to the left of the button changes to reflect the
            selection.
 Gridlines  Select this option if guide lines are required from the relevant
            axis through the chart display.
 Data Angle This option is available only for the X-axis and can be used to set
            the orientation of the text written along the X-axis.
 Tickmarks  This option is available only for the Y axes and can be used to set
            the position, if required, of tickmarks to be shown on a Y axis.

 You must select the Apply button on the page to retain the tailored settings
 for each axis.  This re-plots the chart to take account of the latest set of
 presentation attributes.

 Note:  Only the axes relevant to the currently displayed chart type are
 available. For example, this page is totally disabled if a Pie Chart is
 currently being displayed.


ΓòÉΓòÉΓòÉ 11.3.4. Labels page ΓòÉΓòÉΓòÉ

You Use the Labels page to set the presentation attributes for any data labels
that are to be displayed on the chart.

Chart Settings - Labels page

In its default state this page reflects the settings defined for the data
labels in the Chart section of the XY-Query settings facility. See Chart
Settings - Labels page for more information. Any changes made in this page are
limited to the current object and do not affect the global settings.

Complete the Labels page as follows:

 Font Name / Font Size Use these fields to decide the font and font size to be
                used for the label's text.
 Foreground     Use this field to set the foreground colour for the label value
                text. Select the foreground radio button and then select the
                required colour from the colour matrix. The small colour sample
                square to the left of the button changes to reflect the
                selection.
 Background     Use this field to set the background colour for the box
                containing the label value text. Select the background radio
                button and then select the required colour from the colour
                matrix. The small colour sample square to the left of the
                button changes to reflect the selection.
 Percent Format This field is only relevant for Pie Charts and when set shows
                the label values as percentages of the whole as opposed to
                simple numeric values.
 Position       Select a radio button to choose where on the chart to write the
                data labels. If no labels are required then select None.


ΓòÉΓòÉΓòÉ 11.3.5. Legend page ΓòÉΓòÉΓòÉ

Chart Settings - Legend page

Use the Legend page to set the presentation attributes for the legend that is
to be displayed on the chart. The legend is the descriptor that explains the
colours used for each series plotted in the chart. The colours shown in the
legend can be tailored for each series by using the Elements page as described
in Elements page.

In its default state this page reflects the settings defined for a legend in
the Chart section of the XY-Query settings facility. See Chart Settings -
Legend page for more information.

Any changes made in this page are limited to the current object and do not
affect the global settings.

Complete the Legend page as follows:

 Font Name / Font Size Use these fields to decide the font and font size used
            to write any legend text.
 Foreground Use this field to set the foreground colour for the legend text.
            Select the foreground radio button and then select the required
            colour from the colour matrix. The small colour sample square to
            the left of the button changes to reflect the selection.
 Background Use this field to set the background colour for the box containing
            the legend. Select the background radio button and then select the
            required colour from the colour matrix. The small colour sample
            square to the left of the button changes to reflect the selection.
 Outline    To set the outline colour for the box containing the legend. Select
            the Outline radio button and then select the required colour from
            the colour matrix. The small colour sample square to the left of
            the button changes to reflect the selection.
 Shadow     Use this field to determine whether or not the box containing the
            legend is displayed with a shadow.
 Position   Select a radio button to choose where on the chart the legend is to
            appear.  If no legend is required then select None.


ΓòÉΓòÉΓòÉ 11.3.6. Elements page ΓòÉΓòÉΓòÉ

You use the Elements page to change the name and colour by which a series is
represented on a chart. The changes to the name of the series and its colour
are visible on the chart itself and in the legend if it is displayed.

Chart Settings - Elements page

Complete the Elements page as follows:

 Name       Select the series name as shown on the chart from this pulldown.
            The temporary name and colour representation of this series can
            then be set. The real name (as returned by the query) is shown in
            static text below the Data field.
 Data       Use this field to change the name of the series element selected in
            the Name field.
 Foreground Use the Foreground button to determine the foreground colour of the
            items in the pattern matrix.
 Background Use the Background button to determine the background colour of the
            items in the pattern matrix.
 Pattern    Select a pattern from the pattern matrix to be used to represent
            the series on the chart.

 You must select the Apply button on the page to retain the tailored settings
 for each series.


ΓòÉΓòÉΓòÉ 11.3.7. Background page ΓòÉΓòÉΓòÉ

Chart Settings - Background page

Use the Background page to set the overall background colour of the chart
window.

Complete the Background page as follows:

 Colour         Select a colour from the colour matrix. The small colour sample
                square changes to reflect the selection. Select the Apply
                button to change the chart background to the selected colour.

 The default for this page is retrieved from the Chart section of the XY-Query
 Settings facility. See Chart Settings - Background page for more information.


ΓòÉΓòÉΓòÉ 11.3.8. Subset page ΓòÉΓòÉΓòÉ

You use the Subset page to specify series data for the X and Y axes. The X axis
can have only one series specified but multiple numeric series can be plotted
against the Y axis.

You also use this page to determine which subset of rows of data returned from
the query are to be plotted.

Chart Settings - Subset page

Complete the Subset page as follows:

 X-Axis Data    Select a series from the pulldown to be show against the X
                axis.
 Starting Row / Ending Row Use these fields to specify which subset of rows
                returned by the query are to be plotted on the chart. By
                default the first 10 rows are displayed.
 Y-Axis Data    Select the series from the pulldown to be plotted against the Y
                axis.
 Select All / Deselect All Use these buttons to select or de-select all of the
                series entries in the Y-axis data list.


ΓòÉΓòÉΓòÉ 12. XY-Query utilities ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 12.1. Utility functions ΓòÉΓòÉΓòÉ

This chapter describes the standard set of utility functions that are available
from the SQL, Viewer and Chart windows. Each window has a menu item named
Utilities under which the following general facilities are found:

     Create a DB2/2 database (Create Database)
     Erase a DB2/2 database (Erase Database)
     Create, or append to, a DB2 or XDB table (Creating, or appending to a
      table using Viewer data)
     Define a new DB2 or XDB table (Defining a new table)
     Alter definition of a DB2 or XDB table (Altering the definition of a
      table)
     Erase a DB2 or XDB table (Erasing a table)
     Create a DB2/2 table by importing a file (Importing a table)
     Register and de-register logons and passwords (Managing sessions)

 As can be seen from this list, some utilities are limited to DB2/2 whereas
 others are open to any DB2 or XDB database.


ΓòÉΓòÉΓòÉ 12.2. Create Database ΓòÉΓòÉΓòÉ

To create a DB2/2 database, open the Utilities menu and select Database
followed by Create....

This displays a dialog box which should be used to specify the name and
physical location of the new database. The fields should be completed as
follows:

 Name      Enter the name of the new database (up to eight alpha-numeric
           characters)
 Comment   Enter an optional comment for the database
 Drive     Enter the letter of the hard disk drive where the database will
           reside.
 Name/Comments List A reference list showing all currently catalogued DB2/2
           databases

 Press OK to create the database.


ΓòÉΓòÉΓòÉ 12.3. Erase Database ΓòÉΓòÉΓòÉ

To erase a DB2/2 database, open the Utilities menu and select Database followed
by Erase....

This displays a dialog box. used to identify the database to be removed.

The fields should be completed as follows:

 Name      Enter the name of the database to be deleted.
 Comment   Read only reference field. This is filled when an entry is selected
           from the Name/Comment list.
 Drive     Read only reference field. This is filled when an entry is selected
           from the Name/Comment list. This shows on which drive the database
           to be erased is situated.
 Name/Comments List Select the database to delete from this list. When one is
           selected the Name, Comment and Drive fields are updated to reflect
           the selection.

 Press OK to remove the database.


ΓòÉΓòÉΓòÉ 12.4. Creating, or appending to a table using Viewer data ΓòÉΓòÉΓòÉ

To save the data in the Viewer as a table locally or remotely , open the
Utilities menu and select Table followed by Create and then finally From Viewer
Data....

Create Table From Viewer Data

A dialog box is displayed. which you use to specify the name of the table to be
created or appended to, the location and potentially the database and
tablespace combination, in which the table is to reside. The fields should be
completed as follows:

 Location       Select the location at which the table is to be created
 Name           Enter the name of the table to be created
 Comment        Enter a comment to be associated with the table
 Convert Table Name to Upper Case Select this option to ensure the table name
                is converted to upper case.
 Owner List     Press the Refresh button to populate this list with all table
                owners at the selected location.
 Name/Comments List Populate this list by selecting an owner from the owner
                list. Selecting a table from this list will cause the Name and
                Comment fields to be changed to the selected table.
 Database       Use this field to specify in which database at the named
                location the table will be created.
 Tablespace     Use this field to specify in which tablespace in the named
                database the table will be created.

 Press Create to create a new table, or press Append to add the data to an
 existing table.

 Note:

   1. The database and tablespace fields are required only for locations such
      as DB2/MVS and XDB that use these concepts. If they are not specified
      then the table will be created in the default database and tablespace at
      the named location.
   2. The table will reflect the column titles and sequence as displayed in the
      Viewer. These may have been tailored from the Viewer settings notebook
      (see Viewer window settings). It will not reflect headings and footings,
      column widths or usages.


ΓòÉΓòÉΓòÉ 12.5. Defining a new table ΓòÉΓòÉΓòÉ

To define a new table, open the Utilities menu then select Table followed by
Create and finally From Definition....

A dialog box is displayed.

Define Table

The dialog box is used to specify the details of the the table being defined.

 Location     Select the Location at which the table will reside
 Name         Enter the name of the new table
 Comment      Enter a comment to associate with the new table
 Convert all names to upper case Select this to ensure that the table name
              together with all column names are treated as upper case when the
              table is created.
 Columns List This displays the columns that have been defined for the new
              table.
 Add          Press this to display the dialog from where the columns are
              defined

              Define Table - Add Column


 Remove       Press this to delete the currently highlighted entry from the
              columns list.
 Index        Press this to display the dialog from where the columns to be
              used in the index are selected.

              Define Table - Define Index


 Database     Use this field to specify in which database at the named location
              the table will be created.
 Tablespace   Use this field to specify in which tablespace in the named
              database the table will be created.

 Press OK to create the newly defined table.

 Note:  The database and tablespace fields are required only for locations such
 as DB2/MVS and XDB that use these concepts. If they are not specified then the
 table will be created in the default database and tablespace at the named
 location.


ΓòÉΓòÉΓòÉ 12.6. Altering the definition of a table ΓòÉΓòÉΓòÉ

This utility allows the user to examine the column definition for an existing
table or view. It also offers the capability to add new columns to existing
tables (not views).

To invoke this facility, open the Utilities menu and select Table followed by
Alter Definition....

A dialog box is displayed which is used to identify the table or view.

Complete the dialog box as follows.

 Location       Select the location at which the table/view resides
 Name           Enter the name of the table/view to be examined or altered, or
                select a name from the Name/Comment list into the field.
 Comment        This is reference field showing any associated comment from a
                table/view selected from the Name/Comment List.
 Owner List     Press the Refresh button to populate this list with all table
                owners at the selected location.
 Name/Comments List Populate this list by selecting an owner from the owner
                list. Selecting an entry from this list will cause the Name and
                Comment fields to be changed to those of the selected entry.
 Convert Table Name to Upper Case Select this option to ensure the table/view
                name is treated as upper case.

 Press OK to display another dialog showing the column definition for the
 selected table or view. The dialog that is displayed depends upon whether a
 table or a view was selected.

 Alter Table Definition #2 (Tables)

 For tables, this secondary dialog consists of the following fields.

 Columns list   List showing definition of all columns in table
 Convert column names to upper case Select this to treat all newly defined
                column names as upper case.
 Add            Press this to display a dialog from where a new column can be
                defined

                Alter Table Definition - Add Column


 Delete         Use this to remove a newly defined column from the column list.
                The column in question must first be selected in the list.

 When all new columns have been defined press Alter to update the column
 definition.

 For views, the secondary dialog is displayed thus:

 Alter Table Definition #2 (Views)

 Complete the dialog as follows.

 Columns list   List showing definition of all columns in the view
 View Definition This field shows the query that defines the view

 When the definitions have been examined press OK to close the dialog.


ΓòÉΓòÉΓòÉ 12.7. Erasing a table ΓòÉΓòÉΓòÉ

To erase a local or remote table, open the Utilities menu and select Table
followed by Erase....

A dialog box is displayed.

The dialog box is used to specify the name of the table to be erased The fields
should be completed as follows:

 Location       Select the location at which the table resides
 Name           Enter the name of the table to be erased or select a table from
                the Name/Comment list into the field.
 Comment        This is reference field showing any associated comment from a
                table selected from the Name/Comment List.
 Owner List     Press the Refresh button to populate this list with all table
                owners at the selected location.
 Name/Comments List Populate this list by selecting an owner from the owner
                list. Selecting a table from this list will cause the Name and
                Comment fields to be changed to the selected table.
 Convert Table Name to Upper Case Select this option to ensure the table name
                is converted to upper case.

 Press OK to erase the named table.

 Confirmation will be requested from you before the deletion is carried out.


ΓòÉΓòÉΓòÉ 12.8. Importing a table ΓòÉΓòÉΓòÉ

To import an OS/2 file into a DB2/2 table, open the Utilities menu then select
Table followed by Create and finally From Import File....

A dialog box is displayed from where you can specify the location and type of
the file containing the data to import.

Complete the dialog as follows.

 Format         Select the format of the file to import. The following formats
                are available
                    Non-Delimited ASCII    (.ASC)
                    Import Export Format   (.IXF)
                    Comma Separated Variable (.CSV)
                    ASCII Delimited      (.DEL)
                    Lotus 123 spreadsheet   (.WSF)
 Name           Enter the name of the file, or select an item into it from the
                Names list.
 Directory      Enter the path of the file to be imported, or select a path
                from the Directories list.

 Press the Import button to display another dialog

 Table Import #2

 This dialog enables the target table and location to be specified. Various
 options are available dependant on the type of input file. Only IXF files
 contain enough information to enable a new table to be created so the Create A
 New Table option and the options to ignore codepage errors and recreate
 indexes are only available for these files. For all other file types the data
 can only be used against existing tables.

 Descriptions of the available import methods follow:

 Insert             Append the new data to an existing table without affecting
                    the existing data.
 Update             Add new rows for data with primary keys that are not
                    already in the table. If the primary keys match then the
                    existing row is updated.
 Create A New Table Only available for IXF files. A new table will be created
                    according to the definition held in the IXF file.
 Replace All        All existing data in the table is removed and replaced with
                    the data in the input file.

 Note:  During the import of certain IXF files information, warning and error
 messages are written out ot a file called MSGFILE.LOG which will be created in
 the working directory. To view this file to check the outcome of the import
 press the View Msg File button.


ΓòÉΓòÉΓòÉ 12.9. Managing sessions ΓòÉΓòÉΓòÉ

The Sessions utilities are used to register userids and passwords which will be
used by XY-Query when it connects to locations containing databases and tables.

To log on locally, open the Utilities menu and select Sessions followed by
Logon and then finally Local. This presents a dialog into which the local
userid and password should be entered. XY-Query will use this information when
it runs queries against local DB2/2 tables.

To log on to a LAN node, open the Utilities menu and select Sessions followed
by Logon and then finally Node. This presents a dialog into which the userid,
password and node name should be entered. The Node name is the remote
workstation where a remote database resides or the name of the DDCS/2 gateway
workstation. XY-Query will use the userid and password when it tries to run a
query against a table in a remote location catalogued at that node.

To register your XDB userid and password to XY-Query, open the Utilities menu
and select Sessions followed by Logon and then finally XDB. This presents a
dialog into which the userid and password to be used when XY-Query connects to
XDB.

XDB Logon

To log off a local or remote userid:

   1. Open the Utilities menu and select Sessions followed by Logoff and then
      Logoff again.
   2. Select the session to log off from.
   3. Press the Logoff button.

 XY-Query remembers the last read-protect password you entered such that it can
 use it when you subsequently open other read-protected objects, if they have
 the same password then it will not prompt for a password when it is opened. To
 remove this remembered password from XY-Query, open the Utilities menu and
 select Sessions followed by Logoff and then Logoff Object.


ΓòÉΓòÉΓòÉ 13. XY-Query Procedures ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.1. Introduction ΓòÉΓòÉΓòÉ

This chapter explains how to use the Procedures Window to create and maintain
XY-Query Procedure objects.

XY-Query Procedures are written using the REXX Procedures Language giving the
benefits of rapid data access harnessed with the flexibility and power of the
REXX language.

You can invoke XY-Query functions from any REXX program providing that it is
executing in a Presentation Manager environment. Normal REXX command (.CMD)
files can access the XY-Query functions as described in Running XY-Query
remotely from REXX.  Other generic REXX application builders such as PMREXX and
DrDialog can also utilise the XY-Query interface.

To enable both XY-Query Procedures and external applications to use its
functions, XY-Query provides a Dynamic Link Library (XYQREXFN) containing the
entry points allowing functions to be invoked from a REXX program. For a REXX
program to call XY-Query functions, you must temporarily extend REXX by
defining them as external functions.

A list of the functions provided to perform XY-Query tasks can be found in
XY-Query Procedure functions.

Note:  Full help on REXX is available within OS/2.


ΓòÉΓòÉΓòÉ 13.2. Working with the procedures window ΓòÉΓòÉΓòÉ

The Procedure window is displayed whenever an XY-Query Procedure object is
opened or XY-Query is invoked from the command line with the /P parameter.

From this window, REXX commands are written to perform a series of tasks
including calls to XY-Query functions.

Among the functions available from the Procedure window are the following:

     Procedure Creation (Creating XY-Query Procedures)
     Running a Procedure  (Starting a Procedure)
     Stopping a Procedure  (Stopping a Procedure)
     Save the Procedure object (Saving from the Procedure window)
     Copy to a new Procedure object (Copying to a new Procedure object)
     Export a procedure (Exporting Procedures)
     Import a new procedure (Importing Procedures)
     Print the procedure (Printing Procedures)
     Clipboard operations (Copying, cutting and pasting procedure text)
     Setting Procedure characteristics (Procedure window settings)


ΓòÉΓòÉΓòÉ 13.3. Creating XY-Query Procedures ΓòÉΓòÉΓòÉ

You can build procedures manually or with the help of some specific functions.
Although the Procedure window can be used to run REXX programs with no XY-Query
function calls, this section concentrates on how to create Procedures that use
the functions on offer.

When a new Procedures window is shown, it is pre-filled with the following code
fragment:

/* XY-Query Procedure.                               */
call RxFuncAdd 'XYQRegisterFunctions' ,,
               'XYQREXFN' ,,
               'XYQRegisterFunctions'

call XYQRegisterFunctions


/* Enter the body of your XY-Query Procedure here */


call XYQDeregisterFunctions
return

This code forms the skeleton of the procedure. It includes the functions needed
to start and finish calling XY-Query.  See XY-Query Procedure functions for a
full list of the XY-Query functions that can be invoked.

This skeleton can be reproduced at any time by selecting the Skeleton option
from the Procedure menu.

All other calls to XY-Query functions must be made between the
XYQRegisterFunctions and XYQDeregisterFunctions. The Models option (Using
Procedure models)  helps to ensure that the XY-Query function calls are
syntactically correct.


ΓòÉΓòÉΓòÉ 13.3.1. Using Procedure models ΓòÉΓòÉΓòÉ

Procedure models dialog

The Models option aids the building of a procedure by presenting a list of
available functions which, when selected, are inserted at the current cursor
position, into the Procedure editor. Each 'Model' may optionally contain
pre-written comments explaining the function and basic error-checking code
together with the actual function call with example parameters where required.

To use the Models option:

   1. Open the Procedure menu and select Models to display a dialog box.
   2. Select the function to insert into the procedure editor. For a
      description of the functions available, see XY-Query Procedure functions.
   3. To add an explanatory comment in front of the function call, select
      Comment.
   4. To add an error check after the function call, select Error Check. This
      inserts an unfinished conditional statement whose condition is the error
      return code of the function.  By completing the statement, you can
      specify the action the procedure takes in the event of an error.
   5. Press Add to insert the Model text into the Procedure editor at the
      current cursor position.


ΓòÉΓòÉΓòÉ 13.4. Starting a Procedure ΓòÉΓòÉΓòÉ

You start a Procedure defined in the Procedure editor in one of the following
ways:

     Select the Run option  from the Procedure menu.
     Press the Run button on the toolbar.
     Use the Shift and F1 key combination.

 Each of these reads the Procedure text from the editor and then sends it to
 the REXX interpreter for execution.

 Each XY-Query function that is called in the Procedure sends status messages
 to be displayed on the Information Bar. Notification of completion, or
 otherwise, is also posted on the Information Bar. If the REXX interpreter
 detects an error, a description of the error is displayed there.

 Note:  You can make a procedure return a message by using the exit or return
 statement followed by a REXX variable or your message text.  For example, the
 statement:

  exit 'Query 1 failed'
 displays the following message in the Information Bar:

  Query 1 failed

 Variables can also be attached to the completion message via the exit or
 return statements; the procedure displays the contents of the variable. For
 example:

  exit 'Query 1 failed, sqlcode =' XYQSqlCode

 This returns the message plus the contents of the REXX variable XYQSqlCode,
 which contains the sqlcode returned when the query was run.  The resulting
 error message might be:

  exit Query 1 failed, sqlcode= -204

 You can use any combination of text with the REXX variables to give meaningful
 return or error messages on the status line when the procedure ends. For more
 details about the REXX variables see REXX variables used by XY-Query.


ΓòÉΓòÉΓòÉ 13.5. Stopping a Procedure ΓòÉΓòÉΓòÉ

If you want to stop the execution of a Procedure prematurely, select the Stop
option of the Procedure menu or press the Stop button on the toolbar. The
procedure ends when the current REXX statement has completed.


ΓòÉΓòÉΓòÉ 13.6. Saving from the Procedure window ΓòÉΓòÉΓòÉ

To perform a save, open the File menu and select Save. This saves all
information about the Procedure window together with the text of the procedure
and the invocation setting.


ΓòÉΓòÉΓòÉ 13.7. Copying to a new Procedure object ΓòÉΓòÉΓòÉ

To create a copy of the current XY-Query procedure object, open the File menu
and select Copy to....

From the resulting dialog box, specify the name of the new XY-Query Procedure
object.  Complete the fields as follows:

 Format     Only format XYPROC is available
 Name       Type a name for the new procedure.  Alternatively, use Names to
            select a file to overwrite.
 Directory  Type a file path for the object in the field.  Alternatively, you
            can use Directories to select a path.
 Names/Directories Use these fields to display the names and file paths of
            existing XY-Query procedure objects.  If necessary, select one of
            these and overwrite it.

 Press Copy to complete the operation.

 A new XY-Query procedure object is created which is identical, in all but
 name, to the current state of the active procedure.


ΓòÉΓòÉΓòÉ 13.8. Exporting Procedures ΓòÉΓòÉΓòÉ

You can export procedure text from the Procedure editor to command (.CMD)
files.

To export the procedure open the Procedure menu and select Export.... Complete
the resulting dialog box by specifying the path and name of the file to receive
the export. Only one export format, Command File (.CMD) is available.

Complete the fields and press Export to write the procedure to the named file.


ΓòÉΓòÉΓòÉ 13.9. Importing Procedures ΓòÉΓòÉΓòÉ

Procedures can be imported into the Procedure editor from either XY-Query
Procedure objects or REXX command (.CMD) files.

To import a procedure, open the Procedure menu and select Import. Complete the
resulting dialog box by specifying the path and name of the import file. The
correct format, either XYPROC or Command File (.CMD) must be specified.

Complete the fields and press Import to retrieve the procedure from the named
source and display it in the Procedure editor.


ΓòÉΓòÉΓòÉ 13.10. Printing Procedures ΓòÉΓòÉΓòÉ

To print the procedure currently displayed in the Procedure editor open the
File menu and select Print, or press the printer icon on the toolbar.

A dialog box is displayed containing a list of all available printers:

     Select a printer from the list.
     Press the Job button to display and change the job properties for this
      printer as required..
     Press the Print button to print the procedure text on the selected
      printer.


ΓòÉΓòÉΓòÉ 13.11. Copying, cutting and pasting procedure text ΓòÉΓòÉΓòÉ

You can copy and cut text from, and paste text into, the Procedure editor using
the clipboard. Before copying or cutting text, select it, either by holding the
left mouse button and dragging the pointer over it, or by holding down the
Shift key and using the arrow keys to move through the text. If all text in the
editor is required use the Select all option from the Edit menu. This
highlights all of the text in the Procedure editor ready for Cut or Copy.

To copy selected text, open the Edit menu and select Copy.  The text is copied
to the clipboard.

To cut and copy selected text, open the Edit menu and select Cut. The text is
deleted from the text area and copied to the Clipboard.

To paste text from the clipboard into the Procedure editor, position the cursor
at the point where you want the item to be inserted, open the Edit menu and
select Paste. The item is pasted into the text area.

Note:  The Cut, Copy and Paste functions can all be invoked by using their
respective toolbar buttons.


ΓòÉΓòÉΓòÉ 13.12. Procedure window settings ΓòÉΓòÉΓòÉ

Each Procedure window has a Settings Notebook from where you can set the
attributes and presentation styles for the window. You use the Procedure window
settings notebook to override the default settings for the appearance of the
Procedure window and also to decide how the Procedure object will behave in
future.

You can display the notebook in three different ways:

     Select the Open Settings option of the View menu
     Press the Settings icon on the toolbar
     Press the right hand mouse button when the pointer is over the Procedure
      editor.

 The Procedure window settings notebook consists of three pages as follows:

     Presentation page
     Invocation page
     Security page

 Note:  In general all pages in a Settings notebook have Apply, Undo and
 Default buttons as standard. The Apply button takes the current settings for
 the page and applies them to the object. The Undo button sets the page
 settings back to the state they were in at the time of the last apply. The
 Default button causes the default settings to be reflected on the page. The
 defaults can be application supplied or can be supplied by the XY-Query
 Settings facility. These defaults will only be reflected in the object itself
 if they are explicitly applied.


ΓòÉΓòÉΓòÉ 13.12.1. Presentation page ΓòÉΓòÉΓòÉ

Procedure Settings - Presentation page

You use the Presentation Page to set the background and text colours for the
Procedure editor. You can also set the font in which text will be displayed in
the editor.

The defaults for this page are retrieved from the Procedure section of the
XY-Query Settings facility. See Procedure Settings - Presentation page for more
information.


ΓòÉΓòÉΓòÉ 13.12.2. Invocation page ΓòÉΓòÉΓòÉ

You use the Invocation page to set the mode in which the Procedure is activated
when the object is subsequently invoked.

Procedure Settings - Invocation page

There are three modes from which to choose:

     Select Manual Run to obtain the Procedure window and run the Procedure
      manually. This is the default state for this attribute.
     Select Automatic Run to obtain the Procedure window and run the Procedure
      automatically.
     Select Background Run to run the Procedure automatically as the object is
      invoked without showing the Procedure window.

 Note:  You can access the procedure window from the task list while a
 procedure is running in the background.  If the window is visible when the
 procedure ends, then it stays available until closed by you.  If it is not
 visible, then the procedure shuts down automatically when the procedure has
 completed.  If the procedure fails for some reason while running in background
 mode, the window is made visible so that you can investigate and the procedure
 will not be closed automatically.

 There is no immediate effect on the Procedure object by setting a mode on this
 page.  It determines only how the Procedure will be invoked in the future.


ΓòÉΓòÉΓòÉ 13.12.3. Security page ΓòÉΓòÉΓòÉ

Procedure Settings - Security page

The Security page allows you to apply security measures to your XY-Query
Procedure objects. You can specify an individual object to be Write Protected,
Read Protected or both.

By making an object write protected you can prevent users of the object from
saving changes they may have made, either accidentally or deliberately.

Setting read protection prevents unauthorised users from opening or executing
an object.

Both levels of protection rely on the use of passwords. An object can have a
read and a write protect password. It may be that they are both the same but
they do not need to be. It is up to the creator of the object to determine what
level of security it requires and what the passwords should be.

To set a password perform the following activities:

   1. Select the required security option from the list

   2. Enter the required password

   3. Repeat the password in the verification field

   4. Press the Set button.

   5. Press the Apply button (if all activity on the page is complete)

 When you set write protection on it is initially in its de-activated state.
 This is to allow you to continue changing the object. When all changes are
 complete you may either explicitly save or close the object. Once these
 actions are complete full write protection for the object is activated. This
 would mean that no further changes can be written to the object file.

 If you have a write protected object you can still change it if you know the
 correct password. The way to do this is as follows:

   1. Select the Write Protection security option from the list

   2. Enter the write protect password

   3. Press the De-Activate button.

   4. Press the Apply button (if all activity on the page is complete)

 This will temporarily de-activate write protection. This means that you can
 make changes to the object and save them. The act of saving will re-activate
 full write protection.

 Setting read protection on will cause the object file to be encrypted as it is
 stored thus making the file unreadable using normal text editors.

 You can only open a read protected object if you know the correct password.
 When you attempt to open a read protected object a dialog box will be
 displayed prompting you for the read protect password.

 Opening a read protected procedure object

 Entering the correct password here will then open the XY-Query object as
 normal. If the password is incorrect then a warning is given and the object is
 not opened. You have three attempts to enter the correct password before the
 dialog will dismiss itself.

 Note:  All passwords are case sensitive and retain any leading or trailing
 spaces.


ΓòÉΓòÉΓòÉ 13.13. Running XY-Query remotely from REXX ΓòÉΓòÉΓòÉ

This section explains how to run XY-Query procedures from a REXX command file
instead of from the XY-Query Procedure Window.  To do this, you need two
command files. The first starts the other in a Presentation Manager (PM)
session.  This is required as XY-Query is a PM application.

The following files, INVOKE.CMD and RXXYQ.CMD, are examples. To start XY-Query
using these files, type INVOKE on a command line.  The functions used in the
files are explained in XY-Query Procedure functions.

The INVOKE.CMD file contains these statements:

/* Invoke REXX XY-Query Procedure.                   */

/* This command file can be used to invoke another   */
/* in a Presentation Manager session. This is        */
/* required to allow XY-Query procedure functions    */
/* to be executed.                                   */

/* Retrieve the path of the XY-Query installation    */
/* directory and use it to construct the fully       */
/* qualified name of the command file to execute.    */

/* The command file that is invoked can be           */
/* found in your XY-Query installation directory.    */

env = 'OS2ENVIRONMENT'
xyqpath = value('XYQPATH',,env)
rxfile = xyqpath'\rxxyq.cmd'

'@start /pm CMD /c 'rxfile
return

The RXXYQ.CMD file contains these statements:

/* Example XY-Query Procedure                        */

/* This REXX command file MUST be initiated in a     */
/* Presentation Manager Session. The relevant code   */
/* to do this can be found in file INVOKE.CMD in     */
/* your XY-Query Samples directory.                  */

/* It will not run correctly if it is not invoked    */
/* in this manner.                                   */

/* Extend REXX to enable use of the XY-Query         */
/* Procedure functions.                              */

call RxFuncAdd 'XYQRegisterFunctions' ,,
               'XYQREXFN' ,,
               'XYQRegisterFunctions'
call XYQRegisterFunctions

/* Retrieve the XY-Query Install directory path.     */
/* The XY-Query object containing the query to       */
/* run is referred to in the variable XYQOBJ. This   */
/* is the SERVICE object in the SAMPLES directory.   */

env = 'OS2ENVIRONMENT'
xyqpath = value('XYQPATH',,env)
XYQOBJ  = xyqpath'\SAMPLES\SERVICE'

/* Set a value which will be used as a parameter to  */
/* the query held in the object to be run.           */

rx_years=5

/*****************************************************/

/*****************************************************/
/* Execute the query held in the object SERVICE and  */
/* automatically substitute the value 5 for the      */
/* variable called years.                            */
/*****************************************************/

call XYQRunQuery XYQOBJ , 'years='rx_years
if (XYQRc <> 0)
then
 XYQMsg = RxMessageBox('Error 'XYQRc ,
                       'SQLCODE = 'XYQSQLCode ,,
                       'Run SERVICE Query' ,,
                       'OK')
else
 XYQMsg = RxMessageBox('SERVICE Completed OK.' ,
                       'Rows='XYQRows 'Cols='XYQCols,,
                       'Run SERVICE Query' ,,
                       'OK')

/*****************************************************/
/* Display the XY-Query Viewer to show the data.     */
/*****************************************************/

call XYQShowViewer XYQOBJ
if (XYQRc <> 0)
then
 XYQMsg = RxMessageBox('Error 'XYQRc ,,
                       'Show Viewer' ,,
                       'OK')
else
 XYQMsg = RxMessageBox('Viewer Displayed OK' ,,
                       'Show Viewer' ,,
                       'OK')

/*****************************************************/

/*****************************************************/
/* Show the data in a chart using display attributes */
/* defined in the SERVICE object.                    */
/*****************************************************/

call XYQShowChart XYQOBJ
if (XYQRc <> 0)
then
 XYQMsg = RxMessageBox('Error 'XYQRc ,,
                       'Show Chart' ,,
                       'OK')
else
 XYQMsg = RxMessageBox('Chart Displayed OK' ,,
                       'Show Chart' ,,
                       'OK')

/*****************************************************/
/* Clean up and de-register functions from REXX      */
/*****************************************************/

call XYQTerminate
call XYQDeregisterFunctions

XYQMsg = RxMessageBox('Procedure Completed' ,,
                      'XY-Query Procedure'  ,,
                      'OK')
return

Note:  The XYQTerminate call is required when XY-Query functions are called
from outside of the XY-Query Procedure window.


ΓòÉΓòÉΓòÉ 13.13.1. Tracing XY-Query Procedures ΓòÉΓòÉΓòÉ

If you have to perform a trace on an executing REXX procedure, then change the
INVOKE.CMD file as follows:

/* Invoke REXX XY-Query Procedure.                   */
/* Write trace messages to a named file.             */

/* This command file can be used to invoke another   */
/* in a Presentation Manager session. This is        */
/* required to allow XY-Query procedure functions to */
/* be executed.                                      */

/* The command file that is invoked can be           */
/* found in your XY-Query installation directory.    */

/* Retrieve the path of the XY-Query installation    */
/* directory and use it construct the name of the    */
/* command file to execute.                          */

env = 'OS2ENVIRONMENT'
xyqpath = value('XYQPATH',,env)
rxfile  = xyqpath'\rxxyqtrc.cmd'

/* Construct trace file name to be written into      */
/* install directory.                                */

trcfile = xyqpath'\xyq.trc'

/* Invoke procedure with trace messages being        */
/* written to a file.                                */

'@start /pm CMD /c 'rxfile ' 2>'trcfile
return

Include the statement trace r in the invoked command file (rxxyqtrc.cmd) to get
the trace messages written.


ΓòÉΓòÉΓòÉ 13.14. XY-Query Procedure functions ΓòÉΓòÉΓòÉ

The full list of available XY-Query Procedure functions follows
(alphabetically):

     XYQCreateTable
     XYQDeregisterFunctions
     XYQEraseTable
     XYQFileData
     XYQFirstColName
     XYQFirstHeading
     XYQGetAllAttributes
     XYQGetAllHeadings
     XYQGetAllColNames
     XYQGetColHeading
     XYQGetColName
     XYQGetDataItem
     XYQGetDataRow
     XYQPrintChart
     XYQPrintViewer
     XYQRegisterFunctions
     XYQRunChart
     XYQRunQuery
     XYQRunSQL
     XYQRunViewer
     XYQShowChart
     XYQShowViewer
     XYQTerminate
     XYQTopOfData

 The REXX variable XYQRc returned by each function contains the value 0 if the
 function completed successfully.  If not, it contains a textual description of
 the error. This and other REXX variables used by XY-Query are detailed in REXX
 variables used by XY-Query.

 Detailed descriptions of these functions follow.


ΓòÉΓòÉΓòÉ 13.14.1. XYQCreateTable ΓòÉΓòÉΓòÉ

This function saves the data returned from the last query run to a named table.
Using this function, you can create new tables or append data onto existing
tables.


ΓòÉΓòÉΓòÉ 13.14.1.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of the location at which to create the table
 Parameter #2  Name of the table to create
 Parameter #3  Comment on the table
 Parameter #4  'A' - append to existing table 'R' - replace if exists
 Parameter #5 (optional) Name of the database at the named location in which
               the table will be created.
 Parameter #6 (optional) Name of the tablespace in the named database in which
               the table will be created.


ΓòÉΓòÉΓòÉ 13.14.1.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Table has been created successfully.
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to save        There is no data currently held which can be used
                             to create a table.
      Unknown Action         Action flag (Parameter #4) is not blank or 'A' or
                             'R'.
      Invalid location       Location specified (Parameter #1) is not known.
      Create failed          The Create request has failed.
     REXX variable XYQSqlCode containing the sqlcode value for the cases where
      a create request fails.
     REXX variable XYQSqlMsg containing the textual description of the error
      sqlcode.


ΓòÉΓòÉΓòÉ 13.14.1.3. Example ΓòÉΓòÉΓòÉ

/* Create a table called TEMPTAB at the              */
/* location called SAMPLE                            */
call XYQCreateTable 'SAMPLE' ,,
                    'TEMPTAB' ,,
                    'A Temporary table' ,,
                    'R'

Note:  oompact.

   1. The table name parameter is case sensitive. The table is created exactly
      as stated in the parameter. This means that, for example, table TEMPTAB
      can be created as well as table temptab

   2. If Append is requested and the table does not already exist, the request
      is treated as a normal create.


ΓòÉΓòÉΓòÉ 13.14.2. XYQDeregisterFunctions ΓòÉΓòÉΓòÉ

This function de-registers all XY-Query functions. You can include it after the
XYQTerminate request in the command file. It de-registers the functions across
the WHOLE OS/2 system. For this reason, you must use it carefully, or other
procedures running concurrently will be affected by the de-registering of
functions they need to use.


ΓòÉΓòÉΓòÉ 13.14.2.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.2.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value         Description
      0                  Functions deregistered successfully


ΓòÉΓòÉΓòÉ 13.14.2.3. Example ΓòÉΓòÉΓòÉ

call XYQDeregisterFunctions


ΓòÉΓòÉΓòÉ 13.14.3. XYQEraseTable ΓòÉΓòÉΓòÉ

This function erases a table or view from a named location.


ΓòÉΓòÉΓòÉ 13.14.3.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of the location at which the table exists.
 Parameter #2  Name of the table to erase.


ΓòÉΓòÉΓòÉ 13.14.3.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Table erased successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      Erase failed           The erase request failed to complete successfully
      Erase cancelled        The erase request was cancelled at time of
                             confirmation
     REXX variable XYQSqlCode containing the sqlcode value for the cases where
      an erase request fails.
     REXX variable XYQSqlMsg containing the textual description of the error
      sqlcode.


ΓòÉΓòÉΓòÉ 13.14.3.3. Example ΓòÉΓòÉΓòÉ

/* Erase table TEMPTAB from the sample location      */

call XYQEraseTable 'SAMPLE' , 'TEMPTAB'

Note:  The table name parameter is case sensitive. The table erased will be
exactly as stated in the parameter. This allows differentiation between tables
called for example, TEMPTAB and temptab


ΓòÉΓòÉΓòÉ 13.14.4. XYQFileData ΓòÉΓòÉΓòÉ

This function files the data returned from the last query run. The type of
filing is determined by the file extension, but you can override this by
including a second parameter. You can file data to the following types of file:

     .TXT  (plain text)
     .CSV  (comma separated variable)
     .DEL  (delimited ASCII)
     .DIF  (standard, extended and with headings in data)
     .WSF  (Lotus 1-2-3 format)
     .MET  (Metafile format)
 By default, data is filed to a .TXT file.


ΓòÉΓòÉΓòÉ 13.14.4.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of the file to create
 Parameter #2  Type of file - override of file extension (optional).
                   TXT
                   CSV
                   DEL
                   DIF
                   DIFS
                   DIFE
                   DIFD
                   WSF
                   MET


ΓòÉΓòÉΓòÉ 13.14.4.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Data written to file successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to file        There is no data currently held which can be
                             written to file.
      File failed            The file request failed to complete successfully


ΓòÉΓòÉΓòÉ 13.14.4.3. Example ΓòÉΓòÉΓòÉ

/* Use extended DIF as default */
Call XYQFileData 'C:\XYQUERY\WORK\DATA.DIF'
/* Request that DIF with headings format be used */
Call XYQFileData 'C:\XYQUERY\WORK\DATA.DIF' , 'DIFD'
/* Create file in default TXT format */
Call XYQFileData 'C:\XYQUERY\WORK\DATA.XXX'
/* Create file in CSV format */
Call XYQFileData 'C:\XYQUERY\WORK\DATA.XXX' , 'CSV'


ΓòÉΓòÉΓòÉ 13.14.5. XYQFirstColName ΓòÉΓòÉΓòÉ

This function resets the real column name fetching process so that when
XYQGetColName is called again, it starts at the first column name.


ΓòÉΓòÉΓòÉ 13.14.5.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.5.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value          Description
      0                   Fetching process reset to first column name
      No data to show     There is no data currently held.


ΓòÉΓòÉΓòÉ 13.14.5.3. Example ΓòÉΓòÉΓòÉ

call XYQFirstColName


ΓòÉΓòÉΓòÉ 13.14.6. XYQFirstHeading ΓòÉΓòÉΓòÉ

This function resets the user-tailored column heading fetching process so that
when XYQGetColHeading is called again it starts at the first column heading.


ΓòÉΓòÉΓòÉ 13.14.6.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.6.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value         Description
      0                  Fetching process reset to first column heading
      No data to show    There is no data currently held.


ΓòÉΓòÉΓòÉ 13.14.6.3. Example ΓòÉΓòÉΓòÉ

call XYQFirstHeading


ΓòÉΓòÉΓòÉ 13.14.7. XYQGetAllAttributes ΓòÉΓòÉΓòÉ

This function retrieves the attributes of the columns retrieved by the last
query run. The attributes are put into a two dimensional REXX array called by
default XYQAttributes although you can override this.

The returned array is referenced thus, XYQAttributes.x.y and contains
information as follows:

     Column Type
     Column Size (maximum)
     Whether or not the column can contain null values

 The array elements referenced by XYQAttributes.0.y contain the number of
 columns for which information is being returned. The column attributes start
 at element XYQAttributes.1.y.

 The Column Type information can include data such as CHAR or INTEGER and can
 be accessed as follows, XYQAttributes.x.0.

 The Column Size information gives the maximum size of data in the column. The
 information can be accessed as follows, XYQAttributes.x.1.

 The Nulls information is either NULL or NOT NULL to indicate whether the
 column can contain null data. The information can be accessed as follows,
 XYQAttributes.x.2.


ΓòÉΓòÉΓòÉ 13.14.7.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of REXX array to populate with attributes (optional).

               If a parameter is not specified, data is returned in the array
               XYQAttributes.


ΓòÉΓòÉΓòÉ 13.14.7.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      All attributes have been retrieved successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to show        There is no data currently held which can be
                             retrieved.
     REXX array variable XYQAttributes or supplied array name

      Contains all column attributes.


ΓòÉΓòÉΓòÉ 13.14.7.3. Example ΓòÉΓòÉΓòÉ

Call XYQGetAllAttributes

if (XYQRc <> 0)
then
do
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                  'Error from XYQGetAllAttributes' ,,
                  'OK')
  exit
end
else
  XYQMsg = RxMessageBox('Column attributes retrieved',,
                        'XYQGetAllAttributes' ,,
                        'OK')

do i= 1 to XYQAttributes.0.0
   XYQMsg = RxMessageBox('Type of column 'i ' = ',
                          XYQAttributes.i.0  ,,
                         'Column Type Attribute' ,,
                         'OK')
   XYQMsg = RxMessageBox('Size of column 'i ' = ',
                          XYQAttributes.i.1  ,,
                         'Column Size Attribute' ,,
                         'OK')
   XYQMsg = RxMessageBox('Nulls for column 'i ' = ',
                          XYQAttributes.i.2 ,,
                         'Nulls Attribute' ,,
                         'OK')
end


ΓòÉΓòÉΓòÉ 13.14.8. XYQGetAllColNames ΓòÉΓòÉΓòÉ

This function retrieves the real column names, as stated in the table
definition, from the last query run. The headings are put into a REXX array
called by default XYQColNames although you can override this.  The zero element
of the array contains the number of names it contains.

To retrieve any user-defined column titles after executing a query held in an
XY-Query object, use the function XYQGetAllHeadings.


ΓòÉΓòÉΓòÉ 13.14.8.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1      Name of REXX array to populate with column names (optional).

                   If a parameter is not specified, data is returned in the
                   array XYQColNames.


ΓòÉΓòÉΓòÉ 13.14.8.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      All column names have been retrieved successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to show        There is no data currently held which can be
                             retrieved.
     REXX variable XYQColNames or supplied array name

      Contains all column names.


ΓòÉΓòÉΓòÉ 13.14.8.3. Example ΓòÉΓòÉΓòÉ

call XYQGetAllColNames

if (XYQRc <> 0)
then
do
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                   'Error from XYQGetAllColNames' ,,
                   'OK')
  exit
end
else
  XYQMsg = RxMessageBox('All column names retrieved',,
                        'XYQGetAllColNames' ,,
                        'OK')

do i= 1 to XYQColNames.0
   XYQMsg = RxMessageBox('Name of column 'i ' = ',
                          XYQColNames.i  ,,
                         'Column Name' ,,
                         'OK')
   end
end


ΓòÉΓòÉΓòÉ 13.14.9. XYQGetAllHeadings ΓòÉΓòÉΓòÉ

This function retrieves all column headings from the last query run. It
retrieves the column titles that you have defined and stored in an object, and
not the column names as held in the table definition. The headings are put into
a REXX array called by default XYQHeadings although you can override this. The
zero element of the array contains the number of headings it contains.

To obtain the real column names as held in the table definition, use the
function XYQGetAllColNames.


ΓòÉΓòÉΓòÉ 13.14.9.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of REXX array to populate with headings (optional).

               If a parameter is not specified, the data is returned in the
               array XYQHeadings.


ΓòÉΓòÉΓòÉ 13.14.9.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      All column headings have been retrieved
                             successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to show        There is no data currently held which can be
                             retrieved.
     REXX variable XYQHeadings or supplied array name

      Contains all column headings.


ΓòÉΓòÉΓòÉ 13.14.9.3. Example ΓòÉΓòÉΓòÉ

call XYQGetAllHeadings

if (XYQRc <> 0)
then
do
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                   'Error from XYQGetAllHeadings',,
                   'OK')
  exit
end
else
  XYQMsg = RxMessageBox('Column headings retrieved' ,,
                        'XYQGetAllHeadings' ,,
                        'OK')

/* Get heading details from array                    /

do i= 1 to XYQHeadings.0
   XYQMsg = RxMessageBox('Column heading 'i ' = ',
                          XYQHeadings.i  ,,
                         'Column Heading' ,
                         , 'OK')
end


ΓòÉΓòÉΓòÉ 13.14.10. XYQGetColHeading ΓòÉΓòÉΓòÉ

This function retrieves a column heading from the last query run. Any
user-defined column titles are retrieved using this function.

To obtain the real column name as held in the table definition, use the
function XYQGetColName.


ΓòÉΓòÉΓòÉ 13.14.10.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.10.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value            Description
      0                     The column heading has been retrieved successfully
      No data to show       There is no data currently held which can be
                            retrieved.
      End of data reached   All column headings have already been individually
                            retrieved. Reset the fetching pointer by issuing a
                            XYQFirstHeading request.
     REXX variable XYQColHead

      Contains a column heading.


ΓòÉΓòÉΓòÉ 13.14.10.3. Example ΓòÉΓòÉΓòÉ

call XYQGetColHeading

if (XYQRc <> 0)
then
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                   'Error from XYQGetColHeading' ,,
                   'OK')
else
  XYQMsg = RxMessageBox('Column heading = ',
                         XYQColHead ,,
                        'XYQGetColHeading' ,,
                        'OK')


ΓòÉΓòÉΓòÉ 13.14.11. XYQGetColName ΓòÉΓòÉΓòÉ

This function retrieves a column name from the last query run. It returns the
real column name as held in the table definition and not any user-tailored
column title.

To obtain the user-tailored column titles, use the function XYQGetColHeading.


ΓòÉΓòÉΓòÉ 13.14.11.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.11.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value            Description
      0                     The column heading has been retrieved successfully
      No data to show       There is no data currently held which can be
                            retrieved.
      End of data reached   All column names have already been individually
                            retrieved. Reset the fetching pointer by issuing a
                            XYQFirstColName request.
     REXX variable XYQColName

      Contains a column name.


ΓòÉΓòÉΓòÉ 13.14.11.3. Example ΓòÉΓòÉΓòÉ

call XYQGetColName

if (XYQRc <> 0)
then
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                        'Error from XYQGetColName' ,,
                        'OK')
else
  XYQMsg = RxMessageBox('Column name = ',
                         XYQColName ,,
                        'XYQGetColName' ,,
                        'OK')


ΓòÉΓòÉΓòÉ 13.14.12. XYQGetDataItem ΓòÉΓòÉΓòÉ

This function retrieves an element of data from the last query run. Data is
retrieved row by row, a column at a time.


ΓòÉΓòÉΓòÉ 13.14.12.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.12.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value            Description
      0                     The data item has been retrieved successfully
      No data to show       There is no data currently held which can be
                            retrieved.
      End of data reached   All data items have already been individually
                            retrieved. Reset the fetching pointer by issuing a
                            XYQTopOfData request.
     REXX variable XYQDataItem

      Contains the column data.


ΓòÉΓòÉΓòÉ 13.14.12.3. Example ΓòÉΓòÉΓòÉ

call XYQGetDataItem

if (XYQRc <> 0)
then
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                        'Error from XYQGetDataItem',,
                        'OK')
else
  XYQMsg = RxMessageBox('Data item = ' XYQDataItem ,,
                        'XYQGetDataItem' ,,
                        'OK')

Note:  The user defined REXX variable XYQFormat is interrogated by this
function to determine whether or not to perform any formatting on the data
elements returned. If it is set to NO (the default value), the raw data as held
in the table is returned. If this value is set to YES, the data returned is
subject to the formatting options as defined in the Language and Date/Time
pages of the General section of the XY-Query settings facility.

For example, with XYQFormat set to YES, then the data 18,230.32 can be returned
from a decimal field. If the formatting was off, then the data returned would
be 18230.32 This difference is important if the data is to be subsequently used
as variables in another SQL query. SQL syntax does not allow the data 18,230.32
to be used because of the formatting information.


ΓòÉΓòÉΓòÉ 13.14.13. XYQGetDataRow ΓòÉΓòÉΓòÉ

This function retrieves a whole row of data from the last query run. An
XYQGetDataItem call following it retrieves the first element of the next row.

The data items are put into a REXX array called by default XYQDataRow although
you can override this. The zero element of the array contains the number of
data items retrieved.


ΓòÉΓòÉΓòÉ 13.14.13.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of REXX array to populate with data (optional).

               If a parameter is not specified, data is returned in the default
               array XYQDataRow. The array is referenced in the procedure by
               XYQDataRow.0, XYQDataRow.1 etc..


ΓòÉΓòÉΓòÉ 13.14.13.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      The data item has been retrieved successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to show        There is no data currently held which can be
                             retrieved.
      End of data reached    All data items have already been individually
                             retrieved. Reset the fetching pointer by issuing a
                             XYQTopOfData request.
     REXX variable XYQDataRow or supplied array name

      Contains the row data.


ΓòÉΓòÉΓòÉ 13.14.13.3. Example ΓòÉΓòÉΓòÉ

Call XYQGetDataRow

if (XYQRc <> 0)
then
do
  XYQMsg = RxMessageBox('Error ' XYQRc ,,
                        'Error from XYQGetDataRow' ,,
                        'OK')
  exit
end
else
  XYQMsg = RxMessageBox('Row of data retrieved' ,,
                        'XYQGetDataRow' ,,
                        'OK')

do i= 1 to XYQDataRow.0
   XYQMsg = RxMessageBox('Data item 'i ' = ' ,
                          XYQDataRow.i ,,
                         'Data Item' ,,
                         'OK')
end

Note:  The user defined REXX variable XYQFormat is interrogated by this
function to determine whether or not to perform any formatting on the data
elements returned. If it is set to NO (the default value), the raw data as held
in the database is returned. If this value is set to YES, the data returned is
subject to the formatting options as defined in the Language and Date/Time
pages of the General section of the XY-Query settings facility.

For example, with XYQFormat set to YES then the data 18,230.32 can be returned
from a decimal field. If the formatting was off, the data returned would be
18230.32 This difference is important if the data is to be subsequently used as
as variables in another SQL query. SQL syntax does not allow the data 18,230.32
to be used because of the formatting information.


ΓòÉΓòÉΓòÉ 13.14.14. XYQPrintChart ΓòÉΓòÉΓòÉ

This function prints a chart, constructed from the data from the last query
run, to a specified printer, with, optionally, chart style settings from a
named XY-Query object.


ΓòÉΓòÉΓòÉ 13.14.14.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Printer physical name (optional).
 Parameter #2  XY-Query object for chart style settings (optional).

 If Parameter #1 is not specified, the default printer as defined on the
 requesting machine is used. If parameter #2 is not specified then a chart
 conforming to the default specified in the Chart section of the Settings
 Facility will be printed.


ΓòÉΓòÉΓòÉ 13.14.14.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      The print request has completed successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to print       There is no data currently held which can be
                             printed
      Print request failed   The print request has failed to complete
                             successfully


ΓòÉΓòÉΓòÉ 13.14.14.3. Example ΓòÉΓòÉΓòÉ

/* Print on the default printer using the default    */
/* chart style settings.                             */

call XYQPrintChart

/* Print on printer PRT1 using style settings        */
/* contained in a named object.                      */

call XYQPrintChart 'PRT1' ,,
                   'C:\XYQUERY\WORK\STAFFCHT'


ΓòÉΓòÉΓòÉ 13.14.15. XYQPrintViewer ΓòÉΓòÉΓòÉ

This function prints the data from the last query run, to a specified printer,
with, optionally, presentation settings from a named XY-Query object. The
Viewer can only be printed in its Report View in either mode.


ΓòÉΓòÉΓòÉ 13.14.15.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Printer physical name (optional).
 Parameter #2  XY-Query object for presentation settings (optional). This can
               also be specified as 'U' or 'B' to specify the print the Viewer
               Update or Browse modes.

 If Parameter #1 is not specified, the default printer as defined on the
 requesting machine is used. If parameter #2 is not specified then a report
 conforming to the defaults specified in the Viewer section of the Settings
 Facility will be printed.


ΓòÉΓòÉΓòÉ 13.14.15.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      The print request has completed successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to print       There is no data currently held which can be
                             printed
      Print request failed   The print request has failed to complete
                             successfully


ΓòÉΓòÉΓòÉ 13.14.15.3. Example ΓòÉΓòÉΓòÉ

/* Print on default printer using default Viewer     */
/* presentation settings.                            */

call XYQPrintViewer

/* Print on printer PRT1 using specific presentation */
/* settings contained in a named object.             */
call XYQPrintViewer 'PRT1' ,,
                    'C:\XYQUERY\WORK\STAFFVWR'

/* Print on printer PRT1 in browse mode.             */
call XYQPrintViewer 'PRT1' , 'B'


ΓòÉΓòÉΓòÉ 13.14.15.4. Note ΓòÉΓòÉΓòÉ

For Version 1.0 compatibility specifying 'T' as the second parameter will be
treated the same as 'U' and specifying 'R' will be considered the same as 'B'.


ΓòÉΓòÉΓòÉ 13.14.16. XYQRegisterFunctions ΓòÉΓòÉΓòÉ

This function registers all other XY-Query functions to REXX. This removes the
need for you to register each individual function separately. This function
must be called to enable the procedure to call any other.


ΓòÉΓòÉΓòÉ 13.14.16.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.16.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value         Description
      0                  Functions registered successfully
      Function registration failed The XY-Query functions have not registered
                         to REXX correctly.


ΓòÉΓòÉΓòÉ 13.14.16.3. Example ΓòÉΓòÉΓòÉ

call XYQRegisterFunctions


ΓòÉΓòÉΓòÉ 13.14.17. XYQRunChart ΓòÉΓòÉΓòÉ

This function works in the same way as XYQRunQuery except that it shows the
Chart Window immediately the data is returned from the query.  It is equivalent
to running XYQRunQuery followed by XYQShowChart.


ΓòÉΓòÉΓòÉ 13.14.17.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  File containing the query to be run and the presentation styles
               for the Chart window to be shown.
 Others        Detail any variable values that are to be passed to the query
               (optional).

 REXX limits the number of parameters to a function to twenty. If you wish to
 pass a number of variables to your query that would cause this limit to be
 exceeded you can construct a REXX array containing the variable specifications
 and pass this array as parameter 2. The array you construct will be called
 XYQVarList.

 The first (zero) element will contain the number of variables being passed in
 the array. The subsequent elements will contain text assigning values into
 host variable names in the same fashion as if they were entered as individual
 parameters to the API call.


ΓòÉΓòÉΓòÉ 13.14.17.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Query run and chart displayed successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      Query not found        The object specified in parameter #1 can not be
                             found
      Unable to run query    The query specified failed to execute.
      Query run failed       The query specified failed to run successfully.
                             The sqlcode gives an indication of the cause of
                             the error.
     REXX variable XYQRows

      Set to the number of rows retrieved by the query.
     REXX variable XYQCols

      Set to the number of columns retrieved by the query.
     REXX variable XYQSQLCode

      Contains the SQLCODE resulting from the query run.
     REXX variable XYQSqlMsg

      Contains the textual description of an error sqlcode.


ΓòÉΓòÉΓòÉ 13.14.17.3. Examples ΓòÉΓòÉΓòÉ

/* Run the query held in the named object and        */
/* automatically chart the output.                   */

call XYQRunChart 'C:\XYQUERY\WORK\STAFFQRY1'

/* Specify a value for one variable required by the  */
/* named query and a REXX variable for another.      */

rx_years=5
call XYQRunChart 'C:\XYQUERY\WORK\STAFFQRY2' ,,
                 'dept=10' ,,
                 'years='rx_years

/* Specify the variables in the array XYQVarList     */
/* and pass as Parameter #2.                         */

XYQVarList.0=5
XYQVarList.1='upper_comm=3000'
XYQVarList.2='lower_comm=1000'
XYQVarList.3='upper_salary=9000'
XYQVarList.4='lower_salary=4000'
XYQVarList.5='dept=10'

call XYQRunChart 'C:\XYQUERY\WORK\STAFFQRY3' ,,
                 XYQVarList


ΓòÉΓòÉΓòÉ 13.14.17.4. Notes ΓòÉΓòÉΓòÉ

If the query to be run contains substitution variables that are not passed as
parameters to the function, you are asked to enter the values in the normal
XY-Query fashion.

You cannot use both methods of specifying variables in the same call. If
parameter 2 is set to XYQVarList then any subsequent parameters are ignored.


ΓòÉΓòÉΓòÉ 13.14.18. XYQRunQuery ΓòÉΓòÉΓòÉ

This function loads and runs a named query. Specify a fully-qualified file path
if the query is not in the directory identified by the XYQWORK environment
variable. If the query requires run time variables, you can pass values into
them. The query must already exist having been previously saved as an XY-Query
Query, Viewer or Chart object.


ΓòÉΓòÉΓòÉ 13.14.18.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  File containing the query to be run
 Others        Detail any variable values that are to be passed to the query
               (optional).

 REXX limits the number of parameters to a function to twenty. If you wish to
 pass a number of variables to your query that would cause this limit to be
 exceeded you can construct a REXX array containing the variable specifications
 and pass this array as parameter 2. The array you construct will be called
 XYQVarList.

 The first (zero) element will contain the number of variables being passed in
 the array. The subsequent elements will contain text assigning values into
 host variable names in the same fashion as if they were entered as individual
 parameters to the API call.


ΓòÉΓòÉΓòÉ 13.14.18.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Query run successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      Query not found        The object specified in parameter #1 can not be
                             found
      Unable to run query    The query specified failed to execute.
      Query run failed       The query specified failed to run successfully.
                             The sqlcode gives an indication of the cause of
                             the error.
     REXX variable XYQRows

      Set to the number of rows retrieved by the query.
     REXX variable XYQCols

      Set to the number of columns retrieved by the query.
     REXX variable XYQSQLCode

      Contains the SQLCODE resulting from the query run.
     REXX variable XYQSqlMsg

      Contains the textual description of an error sqlcode.


ΓòÉΓòÉΓòÉ 13.14.18.3. Examples ΓòÉΓòÉΓòÉ

/* Run the query held in the named object            */

call XYQRunQuery 'C:\XYQUERY\WORK\STAFFQRY1'

/* Specify a value for one variable required by the  */
/* named query and a REXX variable for another.      */

rx_years=5
call XYQRunQuery 'C:\XYQUERY\WORK\STAFFQRY2' ,,
                 'id=10' ,,
                 'years='rx_years

/* Specify the variables in the array XYQVarList     */
/* and pass as Parameter #2.                         */

XYQVarList.0=5
XYQVarList.1='upper_comm=3000'
XYQVarList.2='lower_comm=1000'
XYQVarList.3='upper_salary=9000'
XYQVarList.4='lower_salary=4000'
XYQVarList.5='dept=10'

call XYQRunQuery 'C:\XYQUERY\WORK\STAFFQRY3' ,,
                 XYQVarList


ΓòÉΓòÉΓòÉ 13.14.18.4. Notes ΓòÉΓòÉΓòÉ

If the query to be run contains substitution variables that are not passed as
parameters to the function, you are asked to enter the values in the normal
XY-Query fashion.

You cannot use both methods of specifying variables in the same call. If
parameter 2 is set to XYQVarList then any subsequent parameters are ignored.


ΓòÉΓòÉΓòÉ 13.14.19. XYQRunSQL ΓòÉΓòÉΓòÉ

This function runs a query passed as a parameter against a named location.


ΓòÉΓòÉΓòÉ 13.14.19.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  Name of the location against which to run the query
 Parameter #2  Text of the query to run
 Others        Detail any variable values that are to be passed to the query
               (optional).

 REXX limits the number of parameters to a function to twenty. If you wish to
 pass a number of variables to your query that would cause this limit to be
 exceeded you can construct a REXX array containing the variable specifications
 and pass this array as parameter 3. The array you construct will be called
 XYQVarList.

 The first (zero) element will contain the number of variables being passed in
 the array. The subsequent elements will contain text assigning values into
 host variable names in the same fashion as if they were entered as individual
 parameters to the API call.


ΓòÉΓòÉΓòÉ 13.14.19.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Query run successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      Unable to run query    The query specified failed to start to execute.
      Query run failed       The query specified failed to run successfully.
                             The sqlcode gives an indication of the cause of
                             the error.
     REXX variable XYQRows

      Set to the number of rows retrieved by the query.
     REXX variable XYQCols

      Set to the number of columns retrieved by the query.
     REXX variable XYQSQLCode

      Contains the SQLCODE resulting from the query run.
     REXX variable XYQSqlMsg

      Contains the textual description of an error sqlcode.


ΓòÉΓòÉΓòÉ 13.14.19.3. Examples ΓòÉΓòÉΓòÉ

/* Run a specific query against a named database     */

call XYQRunSQL 'SAMPLE' ,,
               'SELECT ID , JOB FROM USERID.STAFF'

/* Pass a REXX variable as a value for a             */
/* substitution variable required by the query.      */

rx_years=5
call XYQRunSQL 'SAMPLE' ,
               'SELECT ID , JOB FROM USERID.STAFF ' ,
               'WHERE YEARS > &yrs' ,,
               'yrs='rx_years

/* Specify the variables in the array XYQVarList     */
/* and pass as Parameter #3.                         */

XYQVarList.0=3
XYQVarList.1='upper_salary=9000'
XYQVarList.2='lower_salary=4000'
XYQVarList.3='dept=10'

call XYQRunSQL 'SAMPLE' ,
               'SELECT ID , JOB FROM USERID.STAFF ' ,
               'WHERE DEPT = &dept AND SALARY BETWEEN' ,,
               '&lower_salary AND &upper_salary' ,,
               XYQVarList


ΓòÉΓòÉΓòÉ 13.14.19.4. Notes ΓòÉΓòÉΓòÉ

If the query to be run contains substitution variables that are not passed as
parameters to the function, you are asked to enter the values in the normal
XY-Query fashion.

You cannot use both methods of specifying variables in the same call. If
parameter 3 is set to XYQVarList then any subsequent parameters are ignored.


ΓòÉΓòÉΓòÉ 13.14.20. XYQRunViewer ΓòÉΓòÉΓòÉ

This function works in the same way as XYQRunQuery except that it shows the
Viewer immediately the data is returned from the query.  It is equivalent to
running XYQRunQuery followed by XYQShowViewer.


ΓòÉΓòÉΓòÉ 13.14.20.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  File containing the query to be run and the presentation styles
               for the Viewer window to be shown.
 Others        Detail any variable values that are to be passed to the query
               (optional).

 REXX limits the number of parameters to a function to twenty. If you wish to
 pass a number of variables to your query that would cause this limit to be
 exceeded you can construct a REXX array containing the variable specifications
 and pass this array as parameter 2. The array you construct will be called
 XYQVarList.

 The first (zero) element will contain the number of variables being passed in
 the array. The subsequent elements will contain text assigning values into
 host variable names in the same fashion as if they were entered as individual
 parameters to the API call.


ΓòÉΓòÉΓòÉ 13.14.20.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Query run and Viewer displayed successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      Query not found        The object specified in parameter #1 can not be
                             found
      Unable to run query    The query specified failed to execute.
      Query run failed       The query specified failed to run successfully.
                             The sqlcode gives an indication of the cause of
                             the error.
     REXX variable XYQRows

      Set to the number of rows retrieved by the query.
     REXX variable XYQCols

      Set to the number of columns retrieved by the query.
     REXX variable XYQSQLCode

      Contains the SQLCODE resulting from the query run.
     REXX variable XYQSqlMsg

      Contains the textual description of an error sqlcode.


ΓòÉΓòÉΓòÉ 13.14.20.3. Examples ΓòÉΓòÉΓòÉ

/* Run the query held in the named object and        */
/* automatically display the data in the Viewer      */

call XYQRunViewer 'C:\XYQUERY\WORK\STAFFQRY1'

/* Specify a value for one variable required by the  */
/* named query and a REXX variable for another.      */

rx_years=5
call XYQRunViewer 'C:\XYQUERY\WORK\STAFFQRY2' ,,
                  'id=10' ,,
                  'years='rx_years

/* Specify the variables in the array XYQVarList     */
/* and pass as Parameter #2.                         */

XYQVarList.0=5
XYQVarList.1='upper_comm=3000'
XYQVarList.2='lower_comm=1000'
XYQVarList.3='upper_salary=9000'
XYQVarList.4='lower_salary=4000'
XYQVarList.5='dept=10'

call XYQRunViewer 'C:\XYQUERY\WORK\STAFFQRY3' ,,
                   XYQVarList


ΓòÉΓòÉΓòÉ 13.14.20.4. Notes ΓòÉΓòÉΓòÉ

If the query to be run contains substitution variables that are not passed as
parameters to the function, you are asked to enter the values in the normal
XY-Query fashion.

You cannot use both methods of specifying variables in the same call. If
parameter 3 is set to XYQVarList then any subsequent parameters are ignored.


ΓòÉΓòÉΓòÉ 13.14.21. XYQShowChart ΓòÉΓòÉΓòÉ

This function displays the chart showing the data returned from the last query
run. If no parameter is passed indicating from which XY-Query object the Chart
presentation attributes should be retrieved, then the chart will be shown using
the defaults as specified in the Chart section of the Settings Facility.


ΓòÉΓòÉΓòÉ 13.14.21.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  XY-Query object from which to get Chart Window presentation
               settings (optional).


ΓòÉΓòÉΓòÉ 13.14.21.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Chart displayed successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to show        There is no data currently held which can be
                             plotted.


ΓòÉΓòÉΓòÉ 13.14.21.3. Example ΓòÉΓòÉΓòÉ

/* Show a chart using default display attributes.    */

call XYQShowChart

/* Show a chart using attributes from named object.  */

call XYQShowChart 'C:\XYQUERY\WORK\STAFFQRY'


ΓòÉΓòÉΓòÉ 13.14.22. XYQShowViewer ΓòÉΓòÉΓòÉ

This function displays the Viewer to show the data returned from the last query
run. If no parameter is passed indicating from which XY-Query object the Viewer
presentation attributes should be retrieved, then it will be shown using the
defaults as specified in the Viewer section of the Settings Facility.


ΓòÉΓòÉΓòÉ 13.14.22.1. Input Parameters ΓòÉΓòÉΓòÉ

 Parameter #1  XY-Query object from which to get Viewer presentation settings
               (optional).


ΓòÉΓòÉΓòÉ 13.14.22.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value             Description
      0                      Viewer displayed successfully
      Invalid number of arguments An incorrect number of parameters have been
                             specified
      Invalid argument       At least one parameter is invalid
      No data to show        There is no data currently held which can be
                             displayed.


ΓòÉΓòÉΓòÉ 13.14.22.3. Example ΓòÉΓòÉΓòÉ

/* Show the Viewer using default attributes          */

call XYQShowViewer

/* Show Viewer using attributes from named object    */

call XYQShowViewer 'C:\XYQUERY\WORK\STAFFQRY'


ΓòÉΓòÉΓòÉ 13.14.23. XYQTerminate ΓòÉΓòÉΓòÉ

This function terminates and tidies up an XY-Query session.  This function is
not necessary in procedures run in the Procedure Window although it has no
adverse effects if it is called. In command files and other REXX programs
however, this function MUST always be called after the last XY-Query function
is processed and before the functions are de-registered.


ΓòÉΓòÉΓòÉ 13.14.23.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.23.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value         Description
      0                  Termination completed successfully


ΓòÉΓòÉΓòÉ 13.14.23.3. Example ΓòÉΓòÉΓòÉ

/* Call clean up routine. For use in command files   */
/* and other REXX programs. Use after last function  */
/* call has been made and before de-registering      */

call XYQTerminate


ΓòÉΓòÉΓòÉ 13.14.24. XYQTopOfData ΓòÉΓòÉΓòÉ

This function resets the data-fetching process such that when either
XYQGetDataItem or XYQGetDataRow is next called, it starts at the top of the
data.


ΓòÉΓòÉΓòÉ 13.14.24.1. Input Parameters ΓòÉΓòÉΓòÉ

NONE.


ΓòÉΓòÉΓòÉ 13.14.24.2. Returns ΓòÉΓòÉΓòÉ

     REXX variable XYQRc
           Value         Description
      0                  Fetch pointer reset to the top of the data
                         successfully
      No data to show    The reset could not be done as there is no data
                         currently held.


ΓòÉΓòÉΓòÉ 13.14.24.3. Example ΓòÉΓòÉΓòÉ

/* Re-position the data fetching pointer to the      */
/* first element of data again.                      */

call XYQTopOfData


ΓòÉΓòÉΓòÉ 13.15. REXX variables used by XY-Query ΓòÉΓòÉΓòÉ

The following REXX variables are set and used by XY-Query procedures:

 XYQRc          This is set when each XY-Query function completes. If the
                function has completed successfully it contains zero, otherwise
                it contains a textual description of the error. Check this in
                the REXX program after each XY-Query call.

 XYQSqlCode     This is set whenever an XY-Query function that runs a query is
                called. It contains the SQLCODE resulting from the query
                execution. Check this after every XY-Query query function
                request.

 XYQSqlMsg      This is set in conjunction with XYQSqlCode. It contains the
                textual description of an error sqlcode. If a query completes
                successfully (sqlcode = 0) then XYQSqlMsg will be empty. It is
                used by the functions that run queries and those that create
                and erase tables.

 XYQRows        This is set to the number of rows retrieved by a query. If a
                query fails it is set to zero.

 XYQCols        This is set to the number of columns retrieved by a query. If a
                query fails it is set to zero.

 XYQAttributes  This is the default array name for the XYQGetAllAttributes
                function. It is be two dimensional and contain the type, size
                and null details for each column retrieved by the last query
                run. The XYQAttributes.0.0 element contains the number of
                columns for which details are included. The column type
                information is stored in elements XYQAttributes.x.0, where x is
                between 1 and the number of columns. The column size
                information is stored in elements XYQAttributes.x.1 and the
                nulls information is stored in elements XYQAttributes.x.2.

 XYQColNames    This is the default array name for the XYQGetAllColNames
                function. It contains the real column names as defined in the
                database, for the last query run. The zero element contains the
                number of names included. The names themselves start at element
                1.

 XYQHeadings    This is the default array name for the XYQGetAllHeadings
                function. It contains the column titles, including those that
                have been user-defined, for the last query run. The zero
                element contains the number of headings included. The headings
                themselves start at element 1.

 XYQColHead     This variable is used to hold a single column title. It
                contains user-defined column titles where they have been set.
                The variable is set when the XYQGetColHead function is
                requested.

 XYQColName     This variable is used to hold a single column name. It contains
                column names as defined in the database, ignoring any
                user-defined overrides. The variable is set when the
                XYQGetColName function is requested.

 XYQDataRow     This is the default array name for the XYQGetDataRow function.
                It contains a whole row of data from the last query run in its
                elements. The zero element contains the number of data items
                retrieved. The data items themselves start at element 1.

 XYQDataItem    This variable is used to hold a single item of data when the
                XYQGetDataItem function is called.

 XYQConfirm     Set this variable from within the REXX program. It is
                interrogated by XY-Query. If it is set to NO, XY-Query does not
                ask for confirmation of updates resulting from INSERT, UPDATE
                or DELETE queries before they are made. Also, the confirmation,
                or not, of a request to delete a table (XYQEraseTable) depends
                on the state of this variable.  If this variable is not set,
                XY-Query assumes confirmation is required.

 XYQFormat      Set this variable from within the REXX program.  It is
                interrogated by XY-Query. If it is set to NO, XY-Query does not
                attempt to format the data returned from the XYQGetDataItem and
                XYQGetDataRow function calls. If it is set to YES, data
                returned by these function calls is subject to formatting as
                defined in the Language and Date/Time pages in the General
                section of the XY-Query settings facility or overridden with
                settings from the Country and Date/Time pages in the Viewer
                settings for an individual object. This formatting includes the
                insertion of thousands separators into numeric data and the
                truncation of decimal data after a number of decimal places.

                The default value for this variable is NO which means no
                formatting is done.

 XYQVarList     This is the REXX array name that you can use to pass run time
                variables to queries run from the XYQRunSql, XYQRunQuery,
                XYQRunViewer and XYQRunChart functions. This is particularly
                useful when you have a large number of run time variables that,
                when specified individually, would cause the function to exceed
                twenty parameters which is the REXX maximum.


ΓòÉΓòÉΓòÉ 14. Using the XY-Query settings facility ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 14.1. Introduction ΓòÉΓòÉΓòÉ

This chapter describes the use of the XY-Query Settings facility.  This allows
you to change the defaults and current attributes used by XY-Query. It allows
you to tailor your XY-Query installation to your own personal preferences. The
XY-Query Settings facility consists of five sections. If the Settings object in
the XY-Query folder on the desktop is opened a further folder will appear that
contains five objects relating to the sections of the Settings facility.

XY-Query Settings folder

The sections in the Settings facility are as follows.

     General settings
     SQL settings
     Viewer settings
     Chart settings
     Procedure settings

 When any of the individual settings objects are opened a notebook is displayed
 from where you can update the defaults for the specific area of the XY-Query
 installation.

 For all pages in each notebook complete the fields as explained in the
 appropriate sections of this chapter. Press Apply to apply the changes,
 Default to use the default XY-Query values, or Undo to cancel the changes and
 return to the previously applied settings.

 When you have finished tailoring defaults, close the relevant Settings
 notebook.  Many settings have an immediate effect on any currently open
 XY-Query objects but others provide the defaults whenever a new object is
 created.


ΓòÉΓòÉΓòÉ 14.2. General settings ΓòÉΓòÉΓòÉ

You use the General Settings notebook to tailor attributes that are relevant
across the whole application.

You can tailor these attributes:

     General Settings - Language page
     General Settings - Date / Time page
     General Settings - Timings page
     General Settings - Variables page
     General Settings - Window page
     General Settings - Limits page


ΓòÉΓòÉΓòÉ 14.2.1. General Settings - Language page ΓòÉΓòÉΓòÉ

XY-Query General Settings - Language page

      Language

      Use the pulldown to select a language to be used by XY-Query for messages
      and prompts.  The choice depends on the languages available in the
      version of XY-Query you have installed.
      Currency

      Enter a symbol to be used as the default for for showing currency data in
      XY-Query reports. Click on the Prefix or Suffix radio button to choose
      whether this symbol is to be used by default as a prefix or suffix.
      1000's separator

      Use the pulldown to select the default separator for thousands Select
      either a comma to display the number one thousand as 1,000, or a period
      to display the number one thousand as 1.000.
      Decimal separator

      Use the pulldown to select the default separator for decimal values (use
      a period  to show one and a half as 1.5, or a comma for 1,5).
      Decimal Places

      Use this field to specify the default maximum number of digits to display
      after the separator for decimal values.
      Override database settings

      Use this field to decide whether to show the data returned from a query
      in its raw form, or tailored according to the settings on this page.


ΓòÉΓòÉΓòÉ 14.2.2. General Settings - Date / Time page ΓòÉΓòÉΓòÉ

XY-Query General Settings - Date/Time page

      Date format - format

      Use the pulldown to choose an order to be used for dates in XY-Query
      messages, reports and charts (Day Month Year, Month Day Year or Year
      Month Day).
      Date separator

      Use the field and spin button to choose a date separator, for example, a
      hyphen if you want dates to appear like 17-06-95.
      Time format - format

      Use the pulldown to choose a format for showing times in XY-Query
      messages, reports and charts. For example, 12 or 24 hour clock.
      Time separator

      Use the field and spin button to choose a time separator, for example, a
      colon if you want times to appear like 07:30.
      Override database settings

      Use this field to decide whether to show the data returned from a query
      in its raw form, or tailored according to the settings on this page.


ΓòÉΓòÉΓòÉ 14.2.3. General Settings - Timings page ΓòÉΓòÉΓòÉ

XY-Query General Settings - Timings page

      Chart / Viewer Refresh Interval

      Use the spin buttons to choose the interval used for auto-refreshing the
      Chart and Viewer windows. This interval is used when Auto-Refresh is
      turned on in either of these windows. It is only necessary to select
      auto-refresh from one of the Viewer or Chart windows. If both are showing
      they are refreshed simultaneously.
      System Library Retain Interval

      When XY-Query is started, there may be a delay while the System Library
      is loaded. If you use XY-Query regularly, you can retain the System
      Library in memory to avoid this delay.  Use these controls to choose
      whether or not the System Library is retained in memory and the interval
      for which it is retained.

      You choose one of these options: tize=12.
      Indefinite     Select the Indefinite radio button to retain the System
                     Library in memory until the computer is switched off or
                     re-booted.
      None           Select the None radio button if you do not want the System
                     Library to be retained.  It will be reloaded the next time
                     you open an XY-Query object.
      Timed          Select the Timed radio button to retain the System Library
                     for a fixed interval which you define using the Minutes
                     spin button. The 'countdown' to the release of the System
                     Library starts as soon as the last instance of XY-Query is
                     closed. Starting another XY-Query session before the
                     System Library has been released stops this 'countdown'


ΓòÉΓòÉΓòÉ 14.2.4. General Settings - Variables page ΓòÉΓòÉΓòÉ

XY-Query General Settings - Variables page

Use the Variables Page to review and, if required, delete variables previously
used in queries and held by XY-Query.

To delete unwanted variables, select the variable or variables from the list,
then press Erase to erase them from the list.  You can use the check boxes to
select or de-select all variables in the list.  The variables are not deleted
from XY-Query until you press the Apply button.


ΓòÉΓòÉΓòÉ 14.2.5. General Settings - Window page ΓòÉΓòÉΓòÉ

XY-Query General Settings - Window page

Use the Window page to set the Save option for all instances of XY-Query and to
also set the defaults for the appearance, or not, of certain features on
XY-Query windows for all new objects created.

For the Save option there are three potential choices. If you select Save On
Close then all attributes of the XY-Query windows are saved automatically when
the primary window of the object is closed. If you select Prompt On Close then
XY-Query prompts for a save decision when the object is closed and it detects
that the object attributes have changed since it was opened or it was last
explicitly saved. If neither is selected then the XY-Query instance does not
perform any save activity when the object closes. In this case the only way to
cause the object to be saved with its latest attributes would be to request an
explicit Save from one of the object windows.

The XY-Query features that can be defaulted from this page are the appearance,
or not, by default of Tool and Information bars on any new XY-Query objects,
and the availability of the toolbar tips facility. If this latter feature is
enabled then any current XY-Query instances pick it up and causes descriptions
to be displayed about the function of buttons on the toolbar as the mouse
passes over them.


ΓòÉΓòÉΓòÉ 14.2.6. General Settings - Limits page ΓòÉΓòÉΓòÉ

XY-Query General Settings - Limits page

Use the Limits Page to set certain limiting defaults for new XY-Query objects.
Complete the page as shown below:

      Character limit

      Use this field to specify the maximum number of characters to display in
      the Viewer when columns of all character types are returned from a query.
      Fetch Limit

      Use this field to specify the default value for the maximum number of
      rows which will be fetched by a query for any new XY-Query object.
      Maximum Fetch Limit

      Use this field to specify the maximum value to which the default Fetch
      Limit can be set. It also set the upper bound to which an individual
      XY-Query object can set its own Fetch Limit.
      Low Memory Limit

      Use this field to specify the minimum amount of memory, in megabytes,
      that the computer must have available for XY-Query to continue. If
      XY-Query detects that the limit has been breached, it terminates all
      running queries immediately.

 Note:

   1. The check on the amount of memory available is made automatically by
      XY-Query every second. The value specified in the Low Memory Limit
      setting should take into account the power and speed of the processor
      with respect to the amount of data it can return in one second. The
      faster and more powerful the processor then the larger this value may
      need to be.
   2. The purpose of having this setting is to provide protection from the
      undefined behaviour of the operating system in extreme low memory
      situations.


ΓòÉΓòÉΓòÉ 14.3. SQL settings ΓòÉΓòÉΓòÉ

You use the SQL Settings notebook to tailor attributes that are relevant
primarily for the SQL window. See the following sections to find out how to
tailor these attributes:

     SQL Settings - Presentation page
     SQL Settings - View page
     SQL Settings - History page
     SQL Settings - Defaults page
     SQL Settings - Table Names page
     SQL Settings - Wildcards page


ΓòÉΓòÉΓòÉ 14.3.1. SQL Settings - Presentation page ΓòÉΓòÉΓòÉ

Use the SQL Presentation Page to choose the background colours, text colours
and the font for the SQL editor to be used by default in any new XY-Query
objects that can show the SQL window.


ΓòÉΓòÉΓòÉ 14.3.2. SQL Settings - View page ΓòÉΓòÉΓòÉ

SQL Settings - View page

Use the SQL View Page to determine the default view in which the SQL window
appears when a new XY-Query object is created.

Make the selection from either of these views:

     Builder view
     Edit SQL view


ΓòÉΓòÉΓòÉ 14.3.3. SQL Settings - History page ΓòÉΓòÉΓòÉ

Use the SQL History Page to determine the default method in which the History
Ring operates in new XY-Query objects.

If you want to save the History Ring with an object, select the History Save
option. If you choose this then you can specify the maximum number of queries
that can be saved as the History Ring for the object.

If you want XY-Query to add queries automatically into the History Ring when a
query has executed successfully, select the Add to History On Run option.
Otherwise items can only be added to the History Ring manually.


ΓòÉΓòÉΓòÉ 14.3.4. SQL Settings - Defaults page ΓòÉΓòÉΓòÉ

SQL Settings - Defaults page

Use the SQL Defaults Page to select the case in which queries are submitted and
the choice of default location.

You select the default location from the Default Location pulldown. The
location you choose appears pre-selected in the Location selector in the SQL
window for any new XY-Query objects.

To set the Case attribute, press a radio button to specify whether:

     The query text remains as typed
     The query text is translated to lower case when submitted.
     The query text is translated to upper case when submitted.


ΓòÉΓòÉΓòÉ 14.3.5. SQL Settings - Table Names page ΓòÉΓòÉΓòÉ

SQL Settings - Table Names page

You can use the SQL Table Names Page to enter the names of the tables to be
used when enquiries are made in order to present the list of available creators
and tables on the Select Tables page of the Query Builder. By default the
system catalogue tables are specified. However, this allows you to specify your
own copy if required.

For each particular type of location you can enter the table to use to retrieve
details of all tables and the table to use to only retrieve details of tables
to which you have the correct level of authority.

Firstly, select the location type from the top selection list. This will cause
the All Tables List and Authorised Tables List fields to be populated with the
current setting for this location type. You can then change these entries as
appropriate. When changes have been made for a location you must apply them
before selecting another location type.

The location types available for selection are as follows:

     DB2 - OS/2 & AIX
     DB2 - MVS
     DB2 - SQL/DS
     DB2 - AS400
     XDB


ΓòÉΓòÉΓòÉ 14.3.6. SQL Settings - Wildcards page ΓòÉΓòÉΓòÉ

The Wildcards page allows you to specify the default values for table creators
and table names that will be passed to every new XY-Query object when it is
created. The wildcards are used to limit the amount of data retrieved into the
Select Tables page of the Builder.

The wildcards can be specified in various forms. If an exact match is required
then the exact text should be entered, for example USERID. If a fuzzy match is
required then the wildcard can be specified as for example U* or *SER*.

Note:  The wildcard indicator can be either an asterisk ,* , or a percentage
sign, %.

When multiple wildcards are specified then creators or table names will be
returned that match any of the wildcards.

In addition to the wildcards it is possible to request that tables owned by you
are returned. In order to reduce the list still further it is possible to
request that only tables to which you have the correct authority, depending
upon the type of query being built, be returned.

 Creators List     Use this to specify up to 40 wildcards to use to limit the
                   number of entries returned into the Creators list of the
                   Select Tables page in the builder.
 Tables List       Use this to specify up to 40 wildcards to use to limit the
                   number of entries returned into the Table names list of the
                   Select Tables page in the builder.
 List "My Tables"  Select this to ensure that tables owned by you are retrieved
 List Granted Tables Only Select this to limit the list of tables returned to
                   those for which you have the correct authority granted.


ΓòÉΓòÉΓòÉ 14.4. Viewer settings ΓòÉΓòÉΓòÉ

You use the Viewer Settings notebook to tailor attributes that are relevant
primarily for the Viewer.

See the following sections for explanations of its pages:

     Viewer Settings - Presentation page
     Viewer Settings - View page
     Viewer Settings - Data Update page
     Viewer Settings - Export page


ΓòÉΓòÉΓòÉ 14.4.1. Viewer Settings - Presentation page ΓòÉΓòÉΓòÉ

Use the Presentation page to specify the default fonts and colours for the
various regions of the XY-Query Viewer.

The following list details the regions of the Viewer for which defaults can be
specified from this page:

     Headings
     Column titles
     The data
     Totals
     Footings
     The selected (highlighted) area
     The data found in a search
     Background
     The horizontal and vertical lines
     The buttons on the Viewer when in table view

 Select the Region for which to set defaults and then use the font
 specification fields and the radio buttons in conjunction with the colour
 matrix to set the attributes for the region.

 The changes that can be made depend on the region.  For example, the Viewer
 background does not require a font setting, only colours.  The number of
 different parts of a region for which colours are set varies. For example, the
 headings, column titles, data, totals and footings regions need only a
 foreground colour, whereas the buttons region needs four colours:

     Top
     Middle
     Lower
     Cell Tag.

 The top, middle and lower colours apply to these parts of the buttons used to
 select rows and columns.  The cell tag colours apply to the small buttons used
 to select individual cells.

 When you have completed the default specification for each region, press the
 Apply button to register the new settings for the specific region.


ΓòÉΓòÉΓòÉ 14.4.2. Viewer Settings - View page ΓòÉΓòÉΓòÉ

Viewer Settings - View page

Use the Viewer View Page to determine the default View and Mode in which the
Viewer will be displayed when a new XY-Query object is created.

Make your selection for the default View from the following:

     Report
     Form

 Make your selection for the default Mode from the following:

     Browse
     Update


ΓòÉΓòÉΓòÉ 14.4.3. Viewer Settings - Data Update page ΓòÉΓòÉΓòÉ

You use the Data Update page to specify the default mode you wish to use for
the update of the data displayed in the Viewer.

Viewer Settings - Data Update page

You select an option from the following:

      No Update

      Select this if no updates are to be allowed to the Viewer data.
      Update report Only

      Select this to allow updates to be made to the data without issuing any
      update requests to the underlying table.
      Update Table On Request

      Select this to allow updates made to the data to be issued to the
      underlying table. The update requests are pended unitl you specifically
      request their issue.
      Update Table By Cell

      Select this to automatically issue a table update request when a single
      data cell is changed.
      Update Table By Row

      Select this to automatically issue a table update request when updates to
      a single row have been completed.
      Update Table By Block

      Select this to automatically issue table update requests when a
      pre-determined number of rows have been changed. This value is set using
      the Block Size spin button.


ΓòÉΓòÉΓòÉ 14.4.4. Viewer Settings - Export page ΓòÉΓòÉΓòÉ

Viewer Settings - Export page

Use the Export Page to specify how XY-Query data is exported in the form of
ASCII delimited (.DEL) or Comma Separated Variable (.CSV) files.

You can change these details:

      Column delimiter

      Use this field to specify the column delimiter that is used to separate
      columns of data in the files.
      Character string delimiter

      Use this field to specify the character to be used to delimit strings in
      the files.
      Decimal separator character

      Use this field to specify the character to be used as the decimal
      separator in decimal numbers exported in the files.


ΓòÉΓòÉΓòÉ 14.5. Chart settings ΓòÉΓòÉΓòÉ

You use the Chart Settings notebook to tailor attributes that are relevant
primarily for the Chart Window. See the following sections for explanations of
its pages:

     Chart Settings - Types page
     Chart Settings - Titles page
     Chart Settings - Axes page
     Chart Settings - Labels page
     Chart Settings - Legend page
     Chart Settings - Background page


ΓòÉΓòÉΓòÉ 14.5.1. Chart Settings - Types page ΓòÉΓòÉΓòÉ

Chart Settings - Types page (for Bar charts)

Use the Chart Types page to specify the default settings for the types of chart
available within XY-Query. Each type of chart has its own distinct set of
attributes, termed 'Chart Styles' that you can tailor.

By selecting the chart type for which defaults are to be set, the correct set
of styles for that type of chart is shown. When the styles have been set for a
particular type, press the Apply button. This action saves the settings before
the next chart type is selected and a different set of styles is displayed.

For each chart type an option to set Default Type is available. When this is
set it means that for any new XY-Query object created, the default chart type
is the type specified. Only one chart type can have the Default Type box
checked.


ΓòÉΓòÉΓòÉ 14.5.2. Chart Settings - Titles page ΓòÉΓòÉΓòÉ

Chart Settings - Titles page

Use the Chart Titles page to define the default properties for all titles used
in a chart. These defaults are passed to any new XY-Query object created.

After selecting the Title, the default attributes for that Title can be set.
For the Main Title and the Axes Titles you can set the default text of the
title, the font to display the text, the foreground, background and outline
colours of the box containing the title. You can also request that this box is
displayed in the chart window with a shadow.

For Pie titles, you can only set the font for the title text and the foreground
and background colours for the text box.

When the attributes have been set for a particular Title, you press the Apply
button to save the settings before the next title is selected and the
attributes for this title are displayed and modified.

Note:  For the Main Title only it is possible to split the title over multiple
lines by adding the characters /n at the point of a line break. For example,
entering Salary Report/nBy Department would put the title on two lines.


ΓòÉΓòÉΓòÉ 14.5.3. Chart Settings - Axes page ΓòÉΓòÉΓòÉ

Chart Settings - Axes page

You use the Chart Axes page to define the default properties for all axes
plotted on a chart. These defaults are passed to any new XY-Query object
created.

After selecting an axis, you can set the default attributes for that axis. For
all axes, you can specify the font to display the axis text and the foreground
and background colours of the boxes containing the text. You can also request
gridlines be drawn for each axis.

For the X-Axis only, you can specify the angle at which the axis text is
written. For both Y axes, you can specify only the appearance and position of
tickmarks on the axes.

When the attributes have been set for a particular axis, press the Apply button
to save the settings before the next axis is selected.


ΓòÉΓòÉΓòÉ 14.5.4. Chart Settings - Labels page ΓòÉΓòÉΓòÉ

Chart Settings - Labels page

You Use the Chart Labels page to define the default properties for Labels
plotted on a chart. These defaults are passed to any new XY-Query object
created.

You can set the default font, foreground and background colours for the data
labels and also the position on the chart that the labels should be drawn, if
at all, relative to the series elements.


ΓòÉΓòÉΓòÉ 14.5.5. Chart Settings - Legend page ΓòÉΓòÉΓòÉ

Chart Settings - Legend page

You use the Chart Legend page to define the default properties for the Legend
shown on a chart. These defaults are passed to any new XY-Query object created.

You can select the default font, foreground, background  and outline colours
for the legend box, and whether or not this box should be drawn with a shadow
around it. You can also specify the default position of the legend relative to
a chart, or suppress it altogether.


ΓòÉΓòÉΓòÉ 14.5.6. Chart Settings - Background page ΓòÉΓòÉΓòÉ

You use the Chart Background page to define the default background colour for
any chart.  This default is passed to any new XY-Query object created.


ΓòÉΓòÉΓòÉ 14.6. Procedure settings ΓòÉΓòÉΓòÉ

You use the Procedure Settings notebook to tailor attributes that are relevant
for the Procedure window.


ΓòÉΓòÉΓòÉ 14.6.1. Procedure Settings - Presentation page ΓòÉΓòÉΓòÉ

You use the Presentation Page to determine the background and text colours and
the font for the Procedure editor to be used by default in any new Procedure
object.


ΓòÉΓòÉΓòÉ 15. XY-Query command line interface ΓòÉΓòÉΓòÉ

You can invoke XY-Query and its settings facility from an OS/2 command line. To
invoke XY-Query see Running XY-Query from the command line. To invoke the
XY-Query settings facility see Invoking the XY-Query settings facility from the
command line.


ΓòÉΓòÉΓòÉ 15.1. Running XY-Query from the command line ΓòÉΓòÉΓòÉ

You can run XY-Query from an OS/2 command line to take advantage of the
parameters available.

The command to run XY-Query has the following syntax:

XYQUERY <object-name> <optional parameters>

where:

<object-name> is the name of the XY-Query object you want to run. If this name
is not specified then an untitled XY-Query object is created.

Where a parameter introduces further information, it is followed by a colon,
and the string of information follows without a space.  You can use the
following parameters:

 /P            You should only use this option when a new XY-Query Procedure
               object is required. It is not required if a Procedure object is
               specified by name and is ignored if one is named. This parameter
               is incompatible with the others in this list. It should only be
               used as follows:

                              XYQUERY /P

               Note:  If the /P option is inadvertently used in conjunction
               with other parameters then XY-Query ignores the other parameters
               with the exception of the object name.
 /B            Use this to specify XY-Query to run in background mode, that is,
               without displaying windows.
 /O            Use this to specify an output file for the data produced by the
               query.  For example:

                              /O:C:\XYQUERY\DATA\OUTPUT.TXT

 /S            You can use this to specify an SQL query to run. You must place
               the query in inverted commas. For example:

                              /S:"SELECT * FROM USERID.STAFF"

               Note:  If the /S option is used XY-Query ignores any existing
               object that has been specified either with or without the /Q
               option. It always causes a new object to be created containing
               the query specified.
 /D            Use this to specify a database for the query.  You need this
               when you specify a string with the /S parameter.  For example:

                              /D:SAMPLE

 /Q            Use this to specify the XY-Query object to be invoked.
               (Alternatively, this can be specified by <object-name>, as shown
               in the syntax above.)  For example:

                              /Q:C:\XYQUERY\WORK\ALLSTAFF

 File extensions Use this to specify the format of the output file. XY-Query
               writes to the output file specified by the /O parameter, and
               uses the appropriate format as indicated by the file extension
               of the file you name in that parameter.  If you do not use a
               file extension recognised by XY-Query, it writes the output
               file, by default, in text format (.TXT).  You can use file
               extension parameters to override this default format.  For
               example, if you use these parameters:

                              /O:OUTPUT.XXX /DIF
               XY-Query writes the output to a file called OUTPUT.XXX in
               standard DIF format.

               You can use the following file extension parameters:
                   /DIF (standard Data Interchange Format)
                   /DIFE (extended DIF),
                   /DIFD (standard DIF with headings in data)
                   /TXT  (Plain text)
                   /CSV  (Comma Separated Variable)
                   /DEL  (Delimited ASCII)
                   /WSF  (Lotus 1-2-3 Worksheet format)
 When you run XY-Query with a specified query, it prompts for any substitution
 variables in the usual way.


ΓòÉΓòÉΓòÉ 15.2. Invoking the XY-Query settings facility from the command line ΓòÉΓòÉΓòÉ

You can invoke any of the sections of the XY-Query Settings facility from an
OS/2 command line by entering the command:

XYQPRO <optional parameter>
The optional parameter determines which section of the Settings facility is
required.

The parameters you can specify are as follows:

 /G            Specify XYQPRO /G to invoke the General Settings section of the
               XY-Query Settings facility.
 /S            Specify XYQPRO /S to invoke the SQL Settings section of the
               XY-Query Settings facility.
 /V            Specify XYQPRO /V to invoke the Viewer Settings section of the
               XY-Query Settings facility.
 /C            Specify XYQPRO /C to invoke the Chart Settings section of the
               XY-Query Settings facility.
 /P            Specify XYQPRO /P to invoke the Procedure Settings section of
               the XY-Query Settings facility.

 If no parameter is entered or an unrecognised parameter is specified the
 default action is to show the General Settings notebook of the Settings
 facility.


ΓòÉΓòÉΓòÉ 16. Using XY-Query with spreadsheets ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 16.1. Introduction ΓòÉΓòÉΓòÉ

XY-Query allows users of spreadsheets such as Microsoft EXCEL to access data
from databases and display that data in their spreadsheets. As a spreadsheet
user, you need have no interaction with or knowledge of XY-Query.

XY-Query can be called from spreadsheets running in OS/2 or in Windows under
OS/2. This data interchange facility is achieved via Dynamic Data Exchange
(DDE).

The spreadsheet application is started as normal. To cause XY-Query to retrieve
data, you run a macro that contains details of the query to be executed by
XY-Query as well as commands for initiating the DDE link between the
spreadsheet application and XY-Query.


ΓòÉΓòÉΓòÉ 16.2. Calling XY-Query from within a spreadsheet ΓòÉΓòÉΓòÉ

To invoke XY-Query from within a spreadsheet, you can run a macro in the normal
way.

EXCEL macrosheet used to retrieve data from a database

EXCEL macrosheet used to retrieve data from a database illustrates a sample
Microsoft EXCEL macrosheet used to retrieve data from the database SAMPLE, and
then display this data on a new Microsoft EXCEL worksheet.

Note:  For invocation from Microsoft EXCEL under WIN-OS/2, you must ensure that
certain pre-requisite set-up activities have been performed.

     Ensure the Dynamic Data Exchange option in the WIN-OS/2 Setup settings is
      set to Public.
     Ensure XYQDDE.EXE and XYQDDEL.DLL are referenced off the PATH setting in
      the AUTOEXEC.BAT file on the boot drive.

 The commands used in the Microsoft EXCEL macrosheet shown in EXCEL macrosheet
 used to retrieve data from a database. The numbers in the list refer to the
 numbers shown in the figure as follows:

   1. The INITIATE macro must be called before attempting to access data from
      the database. This macro establishes a communications mechanism between
      the spreadsheet product and XY-Query. The form of the INITIATE macro must
      be as shown in EXCEL macrosheet used to retrieve data from a database.
   2. The POKE macro sends an XY-Query command string to XY-Query. The general
      form of this POKE macro is as follows

            POKE( ChannelId , Reference , XY-Query command string )

      where:
      ChannelId          is the channel identifier returned from the INITIATE
                         macro
      Reference          is a unique user-defined reference tag for the
                         XY-Query command to be run
      XY-Query command string is the command string to be submitted to
                         XY-Query, to generate the data from a remote database.
                         It can use all the parameters available when you run
                         XY-Query from the command line.  See XY-Query command
                         line interface for details.

      In EXCEL macrosheet used to retrieve data from a database, the XY-Query
      command string to be executed is stored in the macro sheet cell A48. Cell
      A48 is pointed to by the line labelled 10 in the example, and this
      command string executes the SQL literal string "SELECT * FROM USERID.ORG"
      against the database named SAMPLE and stores the data retrieved in the
      file C:\XYQUERY\WORK\EXAMPLE.DIF. This data file is written in a format
      compatible with a Microsoft EXCEL worksheet.
   3. Any error generated by this POKE statement is reported back to the macro
      sheet as a function return value of #REF!, and the macro ISERR() returns
      TRUE if this is the case. The most likely cause of an error occurring on
      a POKE statement is that XY-Query was not properly installed.
   4. The POKE command to XY-Query causes XY-Query to run in the background,
      and so the REQUEST macro must be used to determine when XY-Query has
      completed running its command string to generate the data.

      The general form of this REQUEST macro is as follows

            REQUEST( ChannelId , Reference )

      where
      ChannelId          is the channel identifier returned from the INITIATE
                         macro
      Reference          is the unique user-defined reference tag from the
                         previous POKE macro.

      At any given time, there may be many XY-Query commands waiting to be run,
      each generated by a user-issued POKE macro.  Each POKE macro is uniquely
      identified by the user-defined reference name. The REQUEST macro
      determines the status of any of these outstanding XY-Query commands by
      supplying the correct user-defined reference name.

      The return code from the REQUEST macro is one of the following:
          32766 - this means that this REQUEST macro has been previously
           issued for the same reference name, which is not valid.
          32765 - this means XY-Query has not yet completed retrieval of the
           data requested from the matching POKE macro.
          The return code from XY-Query, resulting from running the query.
   5. If the REQUEST macro returns 32766, this example displays a message box
      to warn you that this request has been previously issued for this
      reference name.
   6. If the REQUEST macro returns 32765, this example displays a message box
      to warn you that XY-Query is still busy satisfying the data retrieval.
   7. This is cell A34. The XY-Query instance has completed, and a message box
      displays the XY-Query return code to you.
   8. The worksheet generated by XY-Query is then loaded via the OPEN() macro.
   9. When all required data has been retrieved from the database, the
      TERMINATE() macro is called to close the channel linking the macrosheet
      and XY-Query. The Channel identifier returned from the INITIATE macro is
      supplied to the TERMINATE macro.
  10. This is the XY-Query command to be executed.


ΓòÉΓòÉΓòÉ 17. Installing XY-Query ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 17.1. Requirements for installing XY-Query ΓòÉΓòÉΓòÉ

Make sure you have the Xyratex Query for OS/2 installation diskettes before
attempting to install XY-Query.


ΓòÉΓòÉΓòÉ 17.1.1. Suggested hardware requirements ΓòÉΓòÉΓòÉ

The minimum hardware configuration consists of:

     Intel 80386 DX processor
     8 MB Random Access Memory
     3.5 MB free disk space

 Note:  It is recommended that where possible XY-Query is installed on an HPFS
 drive and that the swapper is on an HPFS drive.

 XY-Query can be used in a standalone configuration to access locally stored
 databases or a client configuration to access both local databases and remote
 databases.


ΓòÉΓòÉΓòÉ 17.2. Accessing local DB2/2 databases ΓòÉΓòÉΓòÉ

To access locally stored databases only, you need:

     Operating system
        -  OS/2 2.0 with Servicepak XR06055 or higher, or any higher level of
           OS/2.
     Database Management System
 One of the following:
        -  Extended Services 1.0 for OS/2
        -  Database 2 OS/2 (Single User).


ΓòÉΓòÉΓòÉ 17.3. Accessing XDB databases ΓòÉΓòÉΓòÉ

To access XDB databases, you need:

     Operating system
        -  OS/2 2.0 with Servicepak XR06055 or higher, or any higher level of
           OS/2.
     Database Management System
        -  XDB 3.x or later client

 XY-Query will connect to any XDB database server that is accessible using the
 XDB client. This includes local, non network-aware XDB servers (as supplied
 with XDB Workbench), XDB servers on another machine, or DB2/MVS hosts accessed
 via XDB-Link.

 The server that XY-Query connects to is determined by the "XDBSERVE"
 environment variable. Upon a successful connect, XY-Query interrogates the
 table SYSTEM.SYSXDB.SYSLOCALS to retrieve a list of locations known to that
 server, which is added to the XY-Query "locations" list. This means that you
 must have SELECT authority against this table in order for the location list
 to be retrieved. If you do not have this authority then see your XDB database
 administrator.

 Note that it is possible to have both a DB2/2 client and an XDB client
 installed on the same workstation. In this case, the XY-Query "locations" list
 will consist of the DB2/2 catalog contents, in addition the XDB locations
 stored in SYSTEM.SYSXDB.SYSLOCALS on the XDB server.

 If problems are encountered accessing an XDB server using XY-Query, it is
 worth trying to use the character-mode "XDB" interface to access the server
 first. If this connects successfully, then XY-Query should also be able to
 connect.


ΓòÉΓòÉΓòÉ 17.4. Accessing remote DB2/2 databases ΓòÉΓòÉΓòÉ

A typical configuration involves a "Client/Server" setup, in which the client
communicates database requests to a Database Server. Components of DB2/2 must
be configured on both the client and server.


ΓòÉΓòÉΓòÉ 17.4.1. Software required on the XY-Query Client workstation ΓòÉΓòÉΓòÉ

On the Client workstation, you need:

     Operating system
        -  OS/2 2.0 with Servicepak XR06055 or higher, or any higher level of
           OS/2.
     Database client software
  One of the following:
        -  Extended Services 1.0 for OS/2 installed with Remote Data Services
        -  Extended Services Client Enabler for OS/2
        -  Database 2 OS/2 (Single User) installed as client or client with
           local databases
        -  DB2/2 V1 Client-Enabling Distributed Feature for OS/2
        -  Client Application Enabler/2.

 Note:

   1. The OS/2 Distributed Client Feature allows access only to remote
      databases stored on a database server.  Local databases are not
      supported.  The directory tool is not installed on the client, so the
      remote databases must be catalogued using the command line.

   2. For a NETBIOS client configuration, Communications Manager/2 is not
      required.  Communications Manager/2 is required only to support an APPC
      connection.

   3. Lan Adapter and Protocol Support is contained in several products:

          For LAN Server 3.0, use the NTS/2 disk to run LAPS.EXE (NTS/2 is
           also available separately).
          Lan Server 2.0 also contains Lan Adapter and Protocol Support (LAPS)
           as part of the requestor component.

      Note:  Lan Server 4.0 has Multi-Protocol Transport Services (MPTS)
      instead of LAPS.


ΓòÉΓòÉΓòÉ 17.4.2. Software required on the XY-Query Server workstation ΓòÉΓòÉΓòÉ

To access OS/2 databases, you need:

     Operating system
        -  OS/2 2.0 with Servicepak XR06055 or higher, or any higher level of
           OS/2.
     Database software
 One of the following:
        -  Extended Services 1.0 with Database Server for OS/2,
        -  Database 2 OS/2 Client Server.


ΓòÉΓòÉΓòÉ 17.5. Accessing Remote DB2 family databases ΓòÉΓòÉΓòÉ

In order for XY-Query Clients to access host databases that are DRDA
Application Servers (e.g. SQL/DS, DB2/400 and DB2/MVS), DDCS/2 must be
installed on the database server in addition to the above database server
software.

The version of DDCS/2 must match the version of the database server software,
as shown below:

 Extended Services 1.0    DDCS/2 1.0
 DB2/2 1.0                DDCS/2 2.0
 DB2/2 1.2                DDCS/2 2.2
 DB2/2 2.1                DDCS/2 2.3


ΓòÉΓòÉΓòÉ 17.5.1. Software required on the host ΓòÉΓòÉΓòÉ

On the host you need:

     A level of DB2 that supports Distributed Relational Database Architecture
      (DRDA).

 Note:  A configuration that uses Distributed Database Connection Services/2
 Single User (DDCS/2 Single User) to access host databases is also possible.
 In this case, each client would require the appropriate level of database
 management software as well as a version of Communications Manager to support
 the APPC connection to the host.  Each client would have to be individually
 defined to the host system.


ΓòÉΓòÉΓòÉ 17.6. How to install XY-Query ΓòÉΓòÉΓòÉ

To install XY-Query, load the XY-Query installation diskette, change your
directory to A: and enter:

XYQINST
and follow the instructions on the panel.

The installation program copies the XY-Query product files to a directory of
your choice.  Overtype the input fields as necessary.

XY-Query Installation panel

You have three options:

     Standard installation, that is installing XY-Query, automatic updating of
      CONFIG.SYS and the OS/2 desktop.
     Installing XY-Query product files only followed by a manual update of
      CONFIG.SYS
     Refreshing of XY-Query's OS/2 desktop folder

 Each option is described below.


ΓòÉΓòÉΓòÉ 17.6.1. Standard installation of XY-Query ΓòÉΓòÉΓòÉ

To install XY-Query, update CONFIG.SYS automatically and create the XY-Query
OS/2 desktop folder, make sure that you select both the Install Product Files
and Update Desktop and Configuration boxes and then press the OK button.

XY-Query takes a back-up copy of CONFIG.SYS automatically and gives you the
name of the back-up file when installation is complete. If the installation
process cannot update the CONFIG.SYS file, you must update it manually as
described below before you can run XY-Query.

Your OS/2 desktop is updated as soon as the installation process is completed
successfully. You must re-boot your machine before trying to use XY-Query so
that the changes made to CONFIG.SYS take effect.


ΓòÉΓòÉΓòÉ 17.6.2. Installing XY-Query product files only ΓòÉΓòÉΓòÉ

To install XY-Query product files only make sure that you select only the
Install Product Files box and then press the OK button.

You must then update the CONFIG.SYS file manually by adding or changing
environment variables and updating the LIBPATH statement to reference the
destination directory used in the installation process. The default destination
directory is C:\XYQUERY.

Make the changes shown below changing the default destination directory if
necessary:

 LIBPATH          Add reference to C:\XYQUERY
 SET PATH         Add reference to C:\XYQUERY
 SET DPATH        Add reference to C:\XYQUERY
 SET HELP         Add reference to C:\XYQUERY
 SET BOOKSHELF    Add reference to C:\XYQUERY
 SET XYQPATH      Add this environment variable to refer to C:\XYQUERY
 SET XYQWORK      Add this environment variable to refer to C:\XYQUERY\WORK
 SET XYQTEMP      Add this environment variable to refer to C:\XYQUERY\TEMP

 After updating CONFIG.SYS, re-boot your machine to make the updates effective.
 You can then use XY-Query.


ΓòÉΓòÉΓòÉ 17.6.3. Refreshing your OS/2 desktop only ΓòÉΓòÉΓòÉ

If the the XY-Query folder has been lost from your OS/2 desktop, you can
re-instate the folder on your desktop without having to re-install XY-Query.
You do this by selecting only the Update Desktop and Configuration box and
pressing the OK push button.

You can use this option provided that XY-Query has been installed previously.
You do not need to re-boot your machine for the refresh to take effect.

It is possible to re-install the same or later versions of XY-Query over an
existing version. If you choose to do this the current desktop folder will be
destroyed and re-created. The contents of the Work folder will not be affected.
However, if you have placed any other folders or objects in the XY-Query
desktop folder these will be lost when the desktop is destroyed. Therefore, it
is advised that if you wish to re-create the desktop when you are installing
over an existing version, any objects not originally created by XY-Query
installation are moved from the desktop folder for safe-keeping prior to
re-installation.


ΓòÉΓòÉΓòÉ 17.7. Connecting to databases ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 17.7.1. Connecting to a local database ΓòÉΓòÉΓòÉ

Local databases are managed by DB2/2, Database Manager, or XDB, and need no
additional configuration.  XY-Query automatically binds itself to the database
if required when you run the first query against that database.

(XY-Query will access local XDB locations without any requirement to bind).


ΓòÉΓòÉΓòÉ 17.7.2. Connecting to remote DB2 databases ΓòÉΓòÉΓòÉ

XY-Query accesses remote DB2/2 databases using NETBIOS or APPC connections
directly to the database server, and remote host DRDA compliant databases
through DDCS/2.

There are two versions of DDCS/2:

     Single-user
     Multi-user

 In the single-user configuration, each workstation has a separate DDCS/2
 program connected to the DBMS.

 In the multi-user configuration, each workstation is connected to a single
 DDCS/2 which is connected to the DBMS.

 Note:  Note that each single-user configuration requires an LU6.2 connection
        while the multi-user configuration requires only one.  In the
        multi-user configuration, however, each workstation is simply connected
        to the DDCS/2 server via Remote Data Services (RDS).

 In a multi-user configuration, if a user wishes to access remote databases on
 the host (DB2) as well as those catalogued as local to the server, the user
 must have the same userid and password on the server as on the host.

 If access is required to DB2/400 databases, create a new collection called XYQ
 before trying to run XY-Query against it.

 See the Guide to SAA Distributed Database Connection Services/2 for more
 information on setting up these facilities.


ΓòÉΓòÉΓòÉ 17.8. Binding to remote databases ΓòÉΓòÉΓòÉ

XY-Query attempts to bind automatically to remote databases. If you do not have
the correct authority then a database administrator will need to bind XY-Query
to each remote database.  To do this, use the SQLBIND command and one of the
three bind files supplied with XY-Query (XYQSQL16.BND, XYQSQL32.BND or
XYQSQL21.BND).

Issue only one of these commands depending on your local client Database
Management system where <RemoteDB> represents the database name (fully qualify
the path name of the bind file SQLBIND command if necessary:

     For Database Manager, use the command:

              SQLBIND XYQSQL16.BND <RemoteDB>  /* Database Mgr.  */

     For DB2 for OS/2 Version 1.x, use the command:

              SQLBIND XYQSQL32.BND <RemoteDB>  /* DB2/2 Vers 1.x */

     For DB2 for OS/2 Version 2.x, use the command:

              SQLBIND XYQSQL21.BND <RemoteDB>  /* DB2/2 Vers 2.x */

 Note:  The SQLBIND only needs to be performed once to each DB2 system per
 install of XY-Query so long as the GRANT EXECUTE has been issued.  The SQLBIND
 uses a collection ID of XYQ and package names of XYQ1620E, XYQ3220E and
 XYQ2120E  You must have the appropriate authority to perform each SQLBIND
 (PACKADM or CREATE on collection XYQ).

 The package name matches the bind file as follows

      XYQSQL16.BND XYQ1620E
      XYQSQL32.BND XYQ3220E
      XYQSQL21.BND XYQ2120E


ΓòÉΓòÉΓòÉ 17.8.1. Granting access to a database ΓòÉΓòÉΓòÉ

Each user must be given access to each database as follows:

   1. Catalogue the database in the local DBMS.

      To catalogue the database in the local DBMS, use the Directory Tool
      feature of Database Manager or DB2/2 and follow the instructions in the
      IBM Extended Services for OS/2 Guide to Database Manager, or the DB2/2
      manual IBM Database 2 OS/2 Guide.
   2. Grant the user authority to execute the XY-Query package

      To let a user run XY-Query, you must grant execute access to the package.
      For example, use the following command to grant access to a user to run
      XY-Query against a DB2 system.

               GRANT EXECUTE
               ON PACKAGE XYQ.XYQ2120E
               TO <userid>
      where <userid> represents the userid of the user to whom you want to give
      access.

      Note:  For simplicity it is advisable that you grant access to all three
      package names when the access is for a central database and you have
      users using different levels of database software.

      Depending on whether you choose PUBLIC or an individual userid, this
      command allows all users or a specified user possessing the necessary
      authority to run queries against the database.
   3. Give each user the necessary authority (SELECT, UPDATE etc.) for each
      database.


ΓòÉΓòÉΓòÉ 17.8.2. Connecting to a remote XDB database. ΓòÉΓòÉΓòÉ

The file XDBSQLXD.DBR (the DBRM file for XY-Query) has been provided if it is
necessary to bind XY-Query to a remote DB2 database accessed via XDB-Link.


ΓòÉΓòÉΓòÉ 17.9. Upgrading your level of DB2/2 ΓòÉΓòÉΓòÉ

When you start XY-Query for the first time, it will examine your system to
determine what type of DB2/2 database requestor is installed. This information
is stored as the DatabaseType entry in the file XYQ.CFG in your installation
directory..

It can have one of the following values:

     DBM (for Extended Services 1.0)

     DB2 (for DB2/2 1.x or CAE/2 1.x)

     V21 (for DB2/2 2.x or CAE/2 2.x)

 An example of the line in the XYQ.CFG file containing this information
 follows:

  DatabaseType = DB2

 If you subsequently upgrade the database requestor software after running
 XY-Query, the value stored in the XYQ.CFG file will be incorrect.

 Deleting the DatabaseType line from the XYQ.CFG file will force XY-Query to
 re-examine your system and determine the correct type of database requestor
 next time it is started.

 Note:  It is recommended that if you run XY-Query on a DB2/2 2.x system,
 either the command DB2START should be added to STARTUP.CMD, or the Start DB2
 object should be shadowed into the Startup folder.


ΓòÉΓòÉΓòÉ 17.10. Creating the DB2/2 sample database. ΓòÉΓòÉΓòÉ

The figures and examples in this document are based on the database, called
SAMPLE, supplied with DB2/2. If this database has not been installed, you can
install it provided that you have a local administrator's account.

You create this database by issuing a single command from an OS/2 command line.
If you have DB2/2 V1.x installed, issue the command:

              SQLSAMPL
or if you have DB2/2 V2.x installed, issue the command:

              DB2SAMPL


ΓòÉΓòÉΓòÉ 17.11. Removing XY-Query ΓòÉΓòÉΓòÉ

To remove XY-Query, choose one of the following:

     Double-click on the icon labelled Remove in the desktop folder
     Issue the following command from an OS/2 command line:

            XYQINST /remove

 XY-Query is then removed completely. Both the directory structure set up at
 installation and the updates to CONFIG.SYS are removed.

 Note:  After removal of XY-Query re-boot your machine to make the removal
 effective.


ΓòÉΓòÉΓòÉ 17.12. Advanced installation and removal options ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 17.12.1. Installation Parameters ΓòÉΓòÉΓòÉ

The XYQINST program has a number of parameters which can be set from the
command line, or from icon settings, or can be set up by any other program
which wishes to run XYQINST.EXE.

A complete list of these parameters is as follows.

 -tTargetDir              Directory to install into Default is the value of the
                          XYQPATH variable else its c:\xyquery

 -sSourceDir              Directory to install from Default is the directory
                          XYQINST.EXE is executing from

 -p[Y|N]                  Install program files Default is -pY

 -d[Y|N]                  Install desktop icons Default is -dY

 -c[Y|N]                  Modify config.sys Default is -cY

 -i[N|Y]                  Autostarted, invisible install, do not show dialog if
                          -iY, show it if -iN Default is -iN

 -a[N|Y]                  Autostarted visible install, dialog is visible, but
                          install button is auto pressed and started. Recommend
                          use with -fY. -aY is mutually exclusive with -iY. If
                          you use both -iY takes precedence.

 -f[N|Y]                  Freeze panel. This is only ever effective if -aN is
                          used. -fY prevents the user from modifying the
                          installation options on the panel. The only available
                          options will be the Install, Cancel and Help buttons.
                          Default is -fN

 -vwWorkDir               Specify the work directory. If the directory name
                          starts with a \ or a drive: then this directory is
                          used as specified. If it does not start this way it
                          is taken as a subdirectory of the target directory
                          Default is -vwWork.

 -vmTempDir               Specify the temp directory. If the directory name
                          starts with a \ or a drive: then this directory is
                          used as specified. If it does not start this way it
                          is taken as a subdirectory of the target directory
                          Default is -vmTemp.

 -vtTemplatesDir          Specify the templates directory. If the directory
                          name starts with a \ or a drive: then this directory
                          is used as specified. If it does not start this way
                          it is taken as a subdirectory of the target directory
                          Default is -vtTemplates, (or -vtTemplate for FAT
                          drives).

 -vsSamplesDir            Specify the samples directory. If the directory name
                          starts with a \ or a drive: then this directory is
                          used as specified. If it does not start this way it
                          is taken as a subdirectory of the target directory
                          Default is -vsSamples.

 -remove                  This will cause a full deletion of &XY-Query. Only
                          the following options will work with -remove
                          -vwWorkDir   -vmTempDir  -vtTemplatesDir
                          -vsSamplesDir -tTargetDir  -a[N|Y]      -f[N|Y]

 Each parameter above is shown with its options in square brackets, e.g.
 -a[N|Y]. What this means is that the -a paramater can be written as -a, -an or
 -ay. Because the N is the first item in the brackets it means that -a actually
 means -aN, hence -aN is the default. This default is also used if the
 parameter is not specified at all. So, for instance, if you just use the -pY
 parameter then the default value for all other parameter is used so the -a
 parameter is taken as -aN.

 Where dirctories are specified in parameters you can give them in two ways.
 For instance, suppose XY-Query was installed in a target directory of C:\XYQ.
 You could specify that the samples appear in a subdirectory of this called
 SAMPS\NEW by specifying -vssamps\new. This will put the samples in
 C:\XYQ\SAMPS\NEW, i.e. underneath the target directory. Alternatively, if you
 do not wish to use the target directory you could specify -vsd:\mysamps for
 install xyquery in C:\XYQ, and the samples in D:\MYSAMPS. The use of the drive
 letter (e.g. D:) is crucial for XYQINST to determine what you actually want to
 do.

 Note:  These parameters are not case sensitive which means you can mix capital
 and small letters where you please without affecting their meaning. In
 addition the parameters may start with either a '-' character or a '/'
 character.


ΓòÉΓòÉΓòÉ 17.12.2. LAN, Remote or CID installation ΓòÉΓòÉΓòÉ

It is possible to start the XYQINST program as part of another program to
execute either from a LAN or from diskettes.

To install from a LAN first install the program files only with the appropriate
LAN directory as the target directory. Then any user can go into that directory
and execute XYQINST to install on to their own machine.

If you wish to execute XYQINST from another program that is also possible. Be
warned that XYQINST.EXE and its help file XYQINST.HLP must be together in the
same directory. Simply execute the XYQINST.EXE program as desired specifying
the appropriate command line parameters to get the result you want.

The program can be made to run invisibly by using the -iY parameter. This can
be used to make &XY-Query installation appear to be a part of your own
installation.

Note:  If installation is from diskette then even if the -iY parameter is used
a dialog box prompting for the next diskette will still appear.