![]() |
![]() |
![]() |
![]() |
AXI Installation
ContentsThis chapter is organized as follows:
- Installation Requirements
- Distribution Media
- Directory Structure
- CD-ROM Installation
- Remote Installation
- Network Installation
- Installation Verification
Computer SystemsAXI software is available for many computer and operating system environments. The instructions in this chapter are relevant to the more common environments in use today. Specifically, the following systems supported by Apex are covered here:
- Compaq Alpha workstations running Tru64 UNIX (Digital UNIX)
- Hewlett-Packard HP9000 workstations running HP-UX
- IBM RS/6000 and PowerPC workstations running AIX
- Pentium-class workstations running Red Hat or SuSE Linux
- Silicon Graphics MIPS workstations running IRIX
- Sun SPARC workstations running Solaris
Installation RequirementsThe variable Rational_dir used throughout this document denotes the directory that contains the Rational Apex installation and all Rational and third-party layered product installations. This is the location of the directories base, config, and releases.
- 1 . The Apex Ada compiler must already be installed.
- 2 . The amount of disk space required for an installation is about 114 megabytes for the libraries and demonstration examples. Compiling all the demonstration examples requires an additional 427 megabytes or more. The installation script will check for adequate disk space before installing. The demonstration examples may be copied to another location if required. The demonstration examples are shipped as views; use the Apex copy_view command to copy them.
- 3 . The host you use for installation must have the same architecture and operating system as the AXI release.
- 4 . If you have AXI on CD-ROM, then the host must have a CD-ROM drive, and you (or your system administrator) must be able to mount the CD-ROM. Some operating systems (Solaris, IRIX) will automatically mount CD-ROMs for you.
- 5 . You must have read and write access to the directory Rational_dir.
- 6 . Do not log in as root; you should log in as the same user who installed Apex.
Distribution MediaAXI software is shipped on one of the following distribution media:
- ISO-9660 CD-ROM
- Anonymous FTP download
If you received AXI on CD-ROM, proceed to the section CD-ROM Installation. If you are downloading AXI from Rational's anonymous FTP server, proceed to the section Remote Installation. If you already have a copy of AXI that you received by anonymous FTP, proceed to the section Network Installation.
Directory StructureThe AXI distribution consists of the following subsystems, views, and other components:
- In the directory Rational_dir/base/ada:
- The subsystems xlibxt.ss, motif.ss, stars-xlibxt.ss, and stars-motif.ss.
- Model views in the subsystem model.ss. The model views available on a given host depend on the features supported by Apex on that host. All hosts support Ada 83 and Ada 95 models. The model views are listed in the chapter on Compiling and Linking and in the release notes accompanying each version of AXI.
- Demonstration subsystems xlibxt-test.ss, motif-test.ss, stars-xlibxt-test.ss, and stars-motif-test.ss.
- In the directory Rational_dir/base/cots:
- axi-version: AXI runtime libraries that form part of the interface between Ada and the X Window System.
- utrans-3.0.3:The UIL/Trans UIL to Ada conversion program. This program is described in the UIL/Trans User's Guide, which is furnished with Apex AXI.
- xpm-3.4k:The XPM pixmap manipulation library. This library is described in the XPM manual, which is furnished with Apex AXI.
- In the directory Rational_dir/releases/axi.version/bin:
- Scripts run to make AXI available when Apex is started.
- In the directory Rational_dir/releases/axi.version/install:
- Installation utilities.
CD-ROM InstallationIf you have AXI on CD-ROM, follow this procedure to install AXI.
- 1 . Prerequisites
- Mount the CD-ROM on the host where you are installing AXI. Typical commands for mounting a CD-ROM on various host architectures are given in Table 1.
- Depending on your host's security configuration, you may need to be root to mount a CD-ROM. If this is the case, log in as root to mount the CD-ROM, or get your system administrator to mount it for you.
Examples of CD-ROM mount commands for the different host architectures supported by AXI are given in Table 1.
- 2 . Log In
Log in to any host that meets the Installation Requirements given earlier.
- Even if you had to log in as root in the previous step to mount the CD-ROM, do not continue the installation as root. You should log in as the same user who installed Apex.
- 3 . Run the script rinstall on the CD-ROM
For example, if the CD-ROM is mounted as /cdrom/cdrom0, run rinstall as:
- 4 . Run installation script
Change directory to the AXI install directory:
$ cd releases/axi.version/install
During the installation script, you can select the AXI views that you want to install. For example, you can install only the Ada 95 views, or only the Threads views. The demonstration clients, which are in the views under the demonstraiton subsystems, are not installed by default. If you want to install the demonstration clients, you will need to "tailor" the AXI views that you are installing and select the demonstration clients.
- 5 . Obtain a license for AXI
Even if you have an existing license for AXI 4.1.9 or prior, you will need to get a new license code for later Apex AXI releases. You will need the following information to obtain an AXI license:
- The host name of your Apex license server.
- The host ID of your Apex license server.
- The number of licensed AXI users.
- The licensing version of your Apex release.
- The feature names and version of your AXI release (Table 2).
Most of this information is the same information you collected when you installed Apex, and it can be found in the file $APEX_HOME/install/LICENSE_INFORMATION. For further details, see the Rational Apex Installation Guide, Chapter 6, "Managing Apex/Summit Licenses". The feature name and version of your AXI release may be found in Table 2.
Contact Rational Technical Support to obtain your AXI licenses. You will receive one or more license file entries; for example,
FEATURE axi rational 4.200 01-jan-00 2 DC026087D08C76E48F6F ""
FEATURE axi.ada95 rational 4.200 01-jan-00 2 AC62A087840FC50805A5 ""
- 6 . Run post-install script
Run the post_install script; this will configure the AXI subsystems and views for your installation:
- 7 . Build demonstration clients (optional)
If you want to build the AXI demonstration clients now, you may do so. The command to build the demonstration clients is:
Alternatively, you can set up the AXI demonstration client views so that the clients can be built from the Apex Directory Viewer. The command to set up the demonstration client views without building the clients is:
Remote InstallationIf you are downloading AXI by anonymous FTP from Rational's FTP server, follow this procedure to install AXI.
- 1 . Prerequisites
- You must have a copy of the script rinstall.
- 2 . Log In
- Meets the Installation Requirements given earlier.
- Allows anonymous FTP access to Rational's FTP server.
- 3 . Run the script rinstall
- 4 . Continue installation as for the CD-ROM Installation at step 4 given earlier.
Network InstallationIf you received AXI by anonymous FTP, or you already have a copy of the AXI distribution on disk, follow this procedure to install AXI.
- 1 . Prerequisites
- You must have the AXI distribution and a copy of the script network_install.
- These files should be in the directory Rational_dir.
- 2 . Log In
Log in to any host that meets the Installation Requirements given earlier.
- 3 . Change working directory
In the example above, change directory to Rational_dir/distrib.
- 4 . Run the script network_install
- 5 . Continue installation as for the CD-ROM Installation at step 4 given earlier.
Installation VerificationTo verify that your installation of AXI has succeeded, build the demonstration clients using the script ./make_tests in the install directory. The demonstration clients will be built in the test views under Rational_dir/base/ada/{motif,stars-motif,stars-xlibxt,xlibxt}-test.ss. Depending on your host architecture, you may need 350 megabytes or more of free disk space to build all the demonstration clients.
To run any of the demonstration clients, you must have completed the installation of AXI, you must have the X Window System running, and the following environment variable must be set:
- DISPLAY must be the X Window System display name.
If you want to move the demonstration clients; for example, to move them to a disk with sufficient free space to build all of them, you can use the Apex copy_view command to move them. Before moving the demonstration clients to another directory, you must first run the script make_tests in place, without compiling and linking the demonstration clients. To prevent make_tests from compiling and linking the demonstration clients, run it as follows:
Once you have run the make_tests script, the demonstration views can be moved to any location using the Apex copy_view command. To build any or all of the demonstration clients in any of the demonstration views, see the chapter Compiling and Linking.
Compiling and Linking
ContentsThis chapter is organized as follows:
Creating an ApplicationCreating a Subsystem
The first step in creating a user application is to create a new subsystem. For example, the following command will create the new subsystem myprog.ss in the directory /home/apex_user.
$ apex create_subsystem /home/apex_user/myprog
Creating a Working View
The next step in creating a user application is to create a new view. AXI provides models for each of its APIs (AXI-Xlib/Xt, AXI-Motif, STARS-Xlib/Xt, STARS-Motif) that can be used for this purpose. Select a model that includes all the functionality your program needs: if you need only Xlib/Xt support, select an AXI-Xlib/Xt model; if you need Motif support as well, select an AXI-Motif model. If you need the STARS API, select a STARS-Xlib/Xt or STARS-Motif model. All hosts support both Ada 83 and Ada 95 models; select a model that uses the version of the Ada language that you will be using. A complete list of the AXI models is given in Table 3. As a convenience, the model view pathnames are set up as environment variables when Apex is running. For example, the following command will create the new working view myprog.wrk. It targets the AXI Motif Ada 95 interface: AXI Xlib, X Intrinsics (Xt) and Motif bindings will be visible to any Ada module compiled and linked in myprog.wrk.
$ cd /home/apex_user/myprog.ss
$apex create_working /home/apex_user/myprog.ss/myprog -model $AXI_XM_95_MDL
CompilingYou may now compile client programs in the same manner as compiling any other Apex Ada software. You can compile from either an Apex directory viewer or the command line . For example:
$ cd /home/apex_user/myprog.ss/myprog.wrk
To compile the demonstration clients, change directory to the appropriate view; for example,
$ cd Rational_dir/base/ada/motif-test.ss/arch_os.dialect.version.rel
To compile all the demonstration clients in the view, give the command:
To compile one or more demonstration clients, give a command of the form:
$ apex code client_a.2.ada [ client_b.2.ada ... ]
LinkingYou may now link your program from either the Apex directory viewer or the command line . For example, to link a program called hello_world:
To link all the clients in one of the AXI demonstration views, give the command:
To link one or more demonstration clients, give a command of the form:
$ apex link client_a.2.ada [ client_b.2.ada ... ]
DebuggingAn application using the AXI bindings may be debugged like any other program compiled and linked with Apex Ada. Consult your Apex documentation for details on how to do this.
In most circumstances, debugging must be performed while X is running. This is because most errors occur after a display is successfully opened, and a display cannot be successfully opened unless X is running. In cases where the debugger has to be run outside X, for example, due to memory constraints, you may set the DISPLAY environment variable to another workstation that is running X. If you have the X Window System man pages installed, see the man page X(1) for further information on the topic of displaying the output of a client program on a different display.
The normal techniques of debugging an Apex program that is an X client may be adhered to. In other words, elaboration, breakpoints, stepping and displaying variable values will all operate as expected.
Be particularly careful when debugging programs that grab the pointer, buttons, or the keyboard. If such a program reaches a breakpoint while a grab is in effect, the X server will deadlock. This is an inherent limitation of X, not a limitation of AXI or the Apex debugger. Motif programs that post system modal dialogs must also be debugged with the same care.
Demonstration Programs
ContentsThis chapter is organized as follows:
- Compilation
- AXI Xlib Demonstration Programs
- AXI Xt Demonstration Programs
- AXI Motif Demonstration Programs
- STARS Xlib Demonstration Programs
- STARS Xt Demonstration Programs
- STARS Motif Demonstration Programs
CompilationThe views in the subystems xlibxt-test.ss, motif-test.ss, stars-xlibxt-test.ss, and stars-motif-test.ss under Rational_dir/base/ada contain a number of packages and main programs that collectively demonstrate the AXI Xlib, Xt and Motif bindings. This chapter describes the features and means of operation of the demonstration programs. We assume some familiarity with the X Window System and a window manager, including basic operation such as moving windows, resizing windows, mouse motion and mouse presses.
These views may be compiled using the script make_tests in the directory Rational_dir/releases/axi.version/install, from the Apex Directory Viewer, or from the command line. Compilation and linking instructions are given in Chapter 2, "Compiling and Linking".
AXI Xlib Demonstration ProgramsThis section provides an overview of each Xlib-based client, how to invoke it, what its basic capabilities are, and any limitations on its use.
Programs 1 through 14 are located in
Rational_dir/base/ada/xlibxt-test.ss/arch_os.dialect.version.rel.
- 1 . color
A new window will be created with a random assortment of wide, filled lines of different colors. Pressing any mouse button will pseudo-randomly change the location of the lines. Upon a window resize, the "color sticks" will be made to fit the new window size. The program is terminated by entering the 'q' key.
- 2 . cursor
A new window will be created with the names of all predefined cursor shapes aligned in a matrix form. Initially, the cursor shape will be that of the "Dot". Positioning the cursor over any cursor name and then pressing any mouse button will change the cursor to the corresponding shape. The program is terminated by entering the `q' key.
- 3 . dashes
A new window will be created with four lines drawn with different dash patterns. This program is terminated by entering the `q' key. This program demonstrates the use of the Xlib SetDashes call.
- 4 . drag
This program will create a new window. Each time a mouse button is pressed and held down, a black rectangle will appear at the cursor position. Moving the mouse while continuing to hold the button down will cause the rectangle to follow the cursor (that is, be dragged) within the window. The rectangle will remain at the cursor position when the mouse button is released.
Multiple rectangles can be defined by simply pressing, holding, moving and then releasing the mouse. For each mouse press and release, the x,y coordinates will be printed on standard output.
Entering the 'c' key will clear the window. Entering the 'q' key will terminate the program.
- 5 . draw
A new window will be created. The cursor shape will be that of a pencil. Pressing and holding any mouse button and then moving the mouse will cause a pencil-thin line to be drawn.
Entering the 'c' key will clear the window. Entering the 'q' key will terminate the program.
- 6 . fill_rrect
A new window will be created. A series of colored ovals will be displayed. Pressing any mouse button will slightly alter the shape of the ovals. Resizing the window will cause the oval shapes to change to fit the new window size. The program is terminated by entering the 'q' key.
On a monochrome display, the ovals will be colored black and white.
- 7 . hello_r5
This program will link only if your X windows libraries are for X11 Release 5. A new window will be created with a green color bar illustrating X11R5 device-independent color specification. Pressing any mouse button will display the text "Hello R5!" at varying font sizes. Entering the 'q' key will terminate the program.
- 8 . hello_world
A new window will be created with the text "Hello World" in the center. Pressing any mouse button will display the text "Hello World!" at the point of the cursor. Entering any key will cause a confirmation line to be written in the parent window. Entering the 'q' key will terminate the program.
- 9 . output
A new window will be created. Pressing any mouse button will cause a series of patterns to appear. Continuing to press any mouse button will cause patterns to shift in a pseudo-random order. The program is terminated by entering the 'q' key.
- 10 . points
A new window will be created. The text Points will be displayed in the upper-left corner. Pressing any mouse button will cause the (x,y) coordinate values to be displayed at the position of the cursor (as well as on standard output). Entering the 'c' key will clear the contents of the window, including the text. By hiding the window, either by positioning another window in front of it or by iconifying the window and later repositioning/deiconifying the window, the text will reappear.
The program is terminated by entering the 'q' key.
- 11 . sketch_pad
A window will be created with a tiled background, a large work area and several square buttons underneath. Initially, the "Line" button will be highlighted in reverse video. Press and hold any mouse button and move the mouse, finally releasing the button. In the "Line" mode, a line will be drawn. Other modes may be selected by pressing a mouse button while the cursor is on one of the selections. Entering the 'q' key or selecting "QUIT" terminates the program.
- 12 . sxpm
This is a rewrite in Ada of the utility sxpm furnished with the XPM library. It takes command-line arguments; for a detailed listing of these arguments, run:
- 13 . winprops
This program works something like the X utility xwininfo, but it uses a GUI interface. A window will be created, with the legend "Click in any window to show properties of that window." Using the left mouse button, click in any window on the display. The first window will be redrawn, with a summary of the properties of the clicked-on window. The legend will change to "(To exit, click in this window or press any key.)" Click on another window to display its properties, or click on the first window to exit.
This program also takes command-line arguments, as follows:
- 14 . xdpyinfo
This program establishes a connection to the X server and displays information about the server. It is a rewrite of the X client xdpyinfo.
AXI Xt Demonstration ProgramsThis section provides an overview of each Xt-based client, how to invoke it, what its basic capabilities are, and any limitations on its use. In most demonstration programs, the position, width, height, foreground and background colors, border width, border color, and other such attributes of each widget can be changed by editing the ~/.Xdefaults file.
Xt demonstration programs are located in
Rational_dir/base/ada/xlibxt-test.ss/arch_os.dialect.version.rel.
- 1 . test_shell
The test_shell program simply creates an application shell in a window. The window is resizable, movable and so on. To exit the program, press the `q' key when the pointer is anywhere in the shell window.
- 2 . test_shell_cb1
The test_shell_cb1 program is a variant of test_shell. A "destroy" callback for the shell widget is registered with the toolkit. The callback routine actually only prints the string "Destroy invoked", the widget is not actually destroyed. When the window comes up, press a `q' key with the pointer anywhere in the shell window. The program prints "Yawn..." on standard output, waits a few seconds, invokes the destroy widget callback (and prints "Destroy invoked") with a call to
Xt.DestroyWidget
, waits a few more seconds and then exits.- 3 . test_shell_cb2
The test_shell_cb2 program is another variant of test_shell. A callback routine for the shell widget is registered with the toolkit. The callback routine prints the string "Callback invoked". During execution, the program displays a window (just like test_shell). When the window comes up, press a `q' key with the pointer anywhere in the shell window. The program prints "Yawn..." on standard output, waits a few seconds, invokes the callback (and prints "Callback invoked") with a call to
Xt.CallCallbacks
, waits a few more seconds and then exits. The program differs from test_shell_cb1 in that the former adds a destroy callback and invokes it with a call toXt.DestroyWidget
. This program adds a normal callback routine and invokes it with a call toXt.CallCallbacks
.
AXI Motif Demonstration ProgramsThis section provides an overview of each Motif-based client, how to invoke it, what its basic capabilities are, and any limitations on its use.
Programs 1 through 13 are located in
Rational_dir/base/ada/motif-test.ss/arch_os.dialect.version.rel.
- 1 . tasking
Three new windows will be created with the buttons "Accept Top", "Next", "Previous" and "Exit" on them. A dummy task, "Endless.DoLoop", is spawned for each window. Dummy callbacks are added to the first three buttons. Clicking on "Exit" will close the window and abort that window's task. When the last task has aborted, the program exits. Until that time Xt events are fielded and dispatched as expected in the multitasking program.
- 2 . form
This program demonstrates the use of a Form container widget. If you resize the window, the buttons in the form widget will move to keep the attachments that were set up in the program. Selecting the "Exit" button from the menu will terminate program.
- 3 . helloxma
This program creates a paned window to separate the drawing area from the control area. Initially the drawing area contains the string "Hello World". You may change this by typing a string into the Text Field and pressing Return. To exit, press the Quit button.
- 4 . quit
A new window will be created with the label "quit" on it. Clicking anywhere in this window will exit the program.
- 5 . periodic
Before running periodic, compile the UIL file periodic.uil with the command:
$ uil -o periodic.uid periodic.uil
This is the demonstration program of the same name in the Motif distribution rewritten in Ada. It displays a periodic table of widgets. You can operate each of the widgets displayed just as if they were invoked in a regular application. To exit, click the left mouse button over the File menu and choose Quit.
- 6 . motifburger
Before running motifburger, compile the UIL file motifbur.uil with the command:
$ uil -o motifbur.uid motifbur.uil
This is the demonstration program of the same name in the Motif distribution rewritten in Ada. The program employs Motif facilities to let you make up an order with Hamburgers, Fries and Drinks. To exit, click the left mouse button over the File menu and choose Quit.
- 7 . getmatch
This program demonstrates the use of a scrolled list widget from which you can select an item in the list and the appropriate callback routine prints this information out. To exit, close the window.
- 8 . scroll
This program is similar to the previous one. The only difference is that the Selection Policy is set to EXTENDED_SELECT. You can press and hold down mouse button 1 and drag it across a number of items to select them. To exit, close the window.
- 9 . selbox
This program displays XPM pixmaps in a Motif FileSelectionBox widget. There is a directory tree containing displayable pixmaps at:
Rational_dir/base/ada/motif-test.ss/arch_os.dialect.version.rel/pixmaps.
Select a pixmap to display by selecting a pixmap file and clicking the "OK" button. To exit the program, click the "Cancel" button.
- 10 . selposn
This program creates a text widget. Select any portion of the text in the window and hit any key. The callback prints out information. To exit, close the window.
- 11 . vamotifburger
This program is like the Motif demonstration program motifburger, but it has been rewritten to use the simple menu creation subprograms in the AXI varargs API.
- 12 . workproc
This program demonstrates the use of Xt work procedures. To exit, press the push button.
- 13 . xmstring
This program creates and displays a Motif compound text string. To exit, close the window.
STARS Xlib Demonstration ProgramsThis section provides an overview of each STARS Xlib-based client, how to invoke it, what its basic capabilities are, and any limitations on its use.
Programs 1 through 7 are located in
Rational_dir/base/ada/stars-xlibxt-test.ss/arch_os.dialect.version.rel.
- 1 . bitmap
A window will be created with a background bitmap that resembles the stock X client "xeyes". The program is terminated by entering the 'q' key.
- 2 . checkreg
This program tests the functions in
X_Lib.Regions
. For each test, the program prints two lines such as:Check X_Xor_Region: Should print TRUE FALSE TRUE
TRUE FALSE TRUEIf the two lines agree, then the subprogram being tested is functioning correctly.
- 3 . drag
This program will create a new window. Each time a mouse button is pressed and held down, a black rectangle will appear at the cursor position. Moving the mouse while continuing to hold the button down will cause the rectangle to follow the cursor (that is, be dragged) within the window. The rectangle will remain at the cursor position when the mouse button is released.
Multiple rectangles can be defined by simply pressing, holding, moving and then releasing the mouse. For each mouse press and release, the x,y coordinates will be printed on standard output.
Entering the 'c' key will clear the window. Entering the 'q' key will terminate the program.
- 4 . draw
A new window will be created. The cursor shape will be that of a pencil. Pressing and holding any mouse button and then moving the mouse will cause a pencil-thin line to be drawn.
Entering the 'c' key will clear the window. Entering the 'q' key will terminate the program.
- 5 . getvisinfo
This program establishes a connection to the X server and displays information about the X visuals available on that server.
- 6 . hello_world
A new window will be created with the text "Hello World" in the center. Pressing any mouse button will display the text "It works!" at the point of the cursor. Entering any key will cause a confirmation line to be written in the parent window. Entering the 'q' key will terminate the program.
- 7 . sketch_pad
A window will be created with a tiled background, a large work area and several square buttons underneath. Initially, the "Line" button will be highlighted in reverse video. Press and hold any mouse button and move the mouse, finally releasing the button. In the "Line" mode, a line will be drawn. Other modes may be selected by pressing a mouse button while the cursor is on one of the selections. Entering the 'q' key or selecting "QUIT" terminates the program.
STARS Xt Demonstration ProgramsThis section provides an overview of each STARS Xt-based client, how to invoke it, what its basic capabilities are, and any limitations on its use.
STARS Xt demonstration programs are located in
Rational_dir/base/ada/stars-xlibxt-test.ss/arch_os.dialect.version.rel.
- 1 . test_shell
The test_shell program simply creates an application shell in a window. The window is resizable, movable and so on. To exit the program, press the `q' key when the pointer is anywhere in the shell window.
STARS Motif Demonstration ProgramsThis section provides an overview of each STARS Motif-based client, how to invoke it, what its basic capabilities are, and any limitations on its use.
STARS Motif demonstration programs are located in
Rational_dir/base/ada/stars-motif-test.ss/arch_os.dialect.version.rel.
- 1 . test_label
This program simply creates a window containing a Label widget. To exit the program, select Close from the window manager menu.
- 2 . test_list
This program demonstrates the use of a scrolled list widget from which you can select an item in the list and the appropriate callback routine prints this information out. To exit, close the window.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2003, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |