jade install config

Installation and Configuration Guide V E R S I O N 6.3

Copyright © 2009 Jade Software Corporation Limited

All rights reserved

Jade Software Corporation Limited cannot accept any financial or other responsibilities that may be the result of your use of this information or software material, including direct, indirect, special or consequential damages, or loss of profits. There are no warranties extended or granted by this document or software material.

You should be very careful to ensure that the use of this software material and/or information complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. 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 express written permission of Jade Software Corporation Limited.

The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions.

Copyright © 2009 Jade Software Corporation Limited. All rights reserved.

JADE is a trademark of Jade Software Corporation Limited. All trade names referenced are the service mark, trademark, or registered trademark of the respective manufacturer.

For details about other licensing agreements for third party products, you must read the JADE ReadMe.txt file.

____________________________________

JADEICG-6.3

Contents

Before You Begin xi Who Should Read this Guide................................................................................................................ xi What's Included in this Guide .............................................................................................................. xi Conventions ........................................................................................................................................... xii Related Documentation ........................................................................................................................ xiii

Chapter 1 Installing JADE under Windows 14 Operational Requirements ................................................................................................................... 15

Hardware Requirements................................................................................................................ 15 Minimum Hardware Requirements for a JADE Database Server........................................ 15 Minimum Hardware Requirements for an Application Server ........................................... 16 Minimum Hardware Requirements for Standard Clients ................................................... 16 Minimum Hardware Requirements for Running Presentation Clients.............................. 17

Software Requirements.................................................................................................................. 18 Database Server ...................................................................................................................... 18 Application Server.................................................................................................................. 18 Standard Clients ..................................................................................................................... 18 Presentation (Thin) Clients................................................................................................... 19 Additional Software Requirements for Deploying JADE Web Applications....................... 19 ODBC Requirements for External Database Coexistence or JADE ODBC Driver Usage . 19 Portable Graphical User Interface (Portable GUI) Requirements ..................................... 20 Java Framework Requirements .............................................................................................. 20 .NET Requirements................................................................................................................ 20 Requirements for Exporting JADE Objects through ActiveX Exposure ............................ 20 Requirement for Postscript Printing..................................................................................... 21 Requirements for RPS Nodes ................................................................................................ 21 Virtual Environments ............................................................................................................. 21

Installing Your JADE Software .............................................................................................................. 21 Initiating the Installation from the JADE Setup Program........................................................... 22 JADE Software Installation Process ............................................................................................... 23

Displaying the Welcome Dialog ............................................................................................ 23 Accepting the Terms of the JADE License Agreement........................................................ 23 Selecting the Type of Installation.......................................................................................... 23 Selecting the Type of Set Up ................................................................................................. 23 Selecting the Components to Install ..................................................................................... 24 Specifying Your User Information ........................................................................................ 24 Selecting the Destination Directory ...................................................................................... 25 Selecting the Program Folder for the JADE Icons ............................................................... 25

JADE Installation and Configuration Guide

Contents iv

JADEICG-6.3

Chapter 1 Installing JADE under Windows, continued Selecting the Installation of the JADE Just-In-Time (JIT) Debugger.................................. 25 Running the Installation Program ........................................................................................ 26 Informing You When the Installation is Complete .............................................................. 26

JADE Configurations under Windows.................................................................................................. 26 Multiuser Configuration................................................................................................................ 27

Running a JADE Server in Multiuser Mode.......................................................................... 27 Running a JADE Client in Multiuser Mode.......................................................................... 27 Running a JADE User Application in Multiuser Mode........................................................ 28 Running an Application Server in JADE Thin Client Mode ............................................... 28 Running a Presentation Client in JADE Thin Client Mode ................................................ 28

Single User Configuration............................................................................................................. 29 Running JADE in Single User Mode..................................................................................... 29 Running a JADE User Application in Single User Mode..................................................... 29

Installing Multiple JADE Initialization Files................................................................................. 29 Reregistering JADE with a New Licence .............................................................................................. 30 Configuring the JADE JIT Debugger ................................................................................................... 32

Chapter 2 Compact JADE under Windows CE 33 Overview ................................................................................................................................................. 33 Operational Requirements ................................................................................................................... 34

Microsoft Windows Mobile Operating Systems............................................................................ 34 Writing DLLs that Support External Methods and External Functions............................. 35

Specifying a Pre-Load Library List for Compact JADE................................................. 35 Hardware Specifications ................................................................................................................ 35 Other Considerations .................................................................................................................... 36

Installing Compact JADE on a Desktop Machine................................................................................ 36 Initiating the Installation from the JADE Setup Program........................................................... 37 JADE Software Installation Process ............................................................................................... 37

Displaying the Welcome Dialog ............................................................................................ 37 Accepting the Terms of the JADE License Agreement........................................................ 37 Selecting the Type of Installation.......................................................................................... 37 Selecting the Type of Set Up ................................................................................................. 38 Specifying Your User Information ........................................................................................ 38 Selecting the Destination Directory ...................................................................................... 38 Selecting the Installation of the JADE Just-In-Time (JIT) Debugger.................................. 38 Running the Installation Program ........................................................................................ 39 Informing You When the Installation is Complete .............................................................. 39

Installing Compact JADE on a Windows Mobile Device ..................................................................... 39 Thin Client Installation ................................................................................................................. 39 Single User Installation.................................................................................................................. 40

Configuring Compact JADE.................................................................................................................. 41 Running Compact JADE in JADE Thin Client or Single User Mode ......................................... 43

Automatically Upgrading the Compact JADE Thin Client ................................................................. 43

Chapter 3 JADE under SUSE Linux Enterprise Server on Intel 44 Overview ................................................................................................................................................. 45 SUSE Linux Enterprise Server Installation on Intel Servers............................................................... 46


Contents v

JADEICG-6.3

Chapter 3 JADE under SUSE Linux Enterprise Server on Intel, continued Overview of Installing JADE on Linux.......................................................................................... 46 JADE Operational Requirements on Linux on Intel................................................................... 47

SUSE Linux Enterprise Server Hardware Requirements for Intel...................................... 47 Minimum Hardware Requirements for a JADE Database Server ................................ 47 Minimum Hardware Requirements for an Application Server ................................... 48 Minimum Hardware Requirements for Standard Clients............................................ 48 Minimum Hardware Requirements for Running JADE Presentation Clients ............ 49

SUSE Linux Enterprise Server Software Requirements for Intel........................................ 50 JADE Product and RPM Names for SUSE Linux on Intel........................................................... 51

Port Numbers for Linux on Intel .......................................................................................... 52 Installing JADE............................................................................................................................... 53

Parameters for the jadeinstall Command ............................................................................. 55 [--help]............................................................................................................................. 55 -i | --installDir= ................................................................................................................. 55 -v | --version=.................................................................................................................... 55 [-u | --usercode=]............................................................................................................. 55 [-g | --group=] .................................................................................................................. 55 [-s | --serviceName=]........................................................................................................ 55 [-n]................................................................................................................................... 55 [-k] ................................................................................................................................... 55 [-f | --force] ...................................................................................................................... 56 [-t | --targetType=]........................................................................................................... 56 [-q | --quiet] ..................................................................................................................... 56 [-j | --jadeHome=]............................................................................................................ 56 [-U | --Upgrade] .............................................................................................................. 56 [--all] ................................................................................................................................ 56 [--rte] ............................................................................................................................... 56 [--devdata] ....................................................................................................................... 56 [--devel] ........................................................................................................................... 56 [--docs]............................................................................................................................. 56 [--examples] .................................................................................................................... 56 [--thinclient].................................................................................................................... 56 [--w32thinclient] ............................................................................................................. 57

Starting and Stopping the JADE System ............................................................................... 57 Registering the Database for SUSE Linux on Intel.............................................................. 57 Setting Up the Windows Client ............................................................................................. 58

Upgrading a JADE Release............................................................................................................ 58 Deinstalling JADE .......................................................................................................................... 59

Displaying the Packages Associated with a Specific JADE Version...................................... 59 Obtaining a Core Dump................................................................................................................ 60

Detailed Command Information for SUSE Linux on Intel ................................................................ 60 Environment Variables .................................................................................................................. 60

Required Environment Variables .......................................................................................... 60 JADEHOME .................................................................................................................... 60 LANG............................................................................................................................... 61 LD_LIBRARY_PATH...................................................................................................... 61 NLSPATH........................................................................................................................ 61 PATH............................................................................................................................... 61


Contents vi

JADEICG-6.3

Chapter 3 JADE under SUSE Linux Enterprise Server on Intel, continued Optional Environment Variables for SUSE Linux on Intel................................................. 62

JADELANGDIR............................................................................................................... 62 LC_CTYPE....................................................................................................................... 62 TMPDIR .......................................................................................................................... 62

JADE Daemon (jaded)................................................................................................................... 62 Starting JADE Daemon from the Command Line on Intel................................................. 62

JADE Portable GUI (jadepg)......................................................................................................... 63 Starting the JADE Portable GUI from the Command Line................................................. 63

Running an Application Server..................................................................................................... 63 Invoking an Application Server............................................................................................. 64

Running a Non-GUI Client Application....................................................................................... 65 Invoking a Non-GUI Client Application ............................................................................... 65

Initiating Non-GUI Applications when the Application Server is Initiated ................ 66 Initiating Non-GUI Applications at a Specific Time .................................................... 67

Java Framework .............................................................................................................................. 67 Locales and Translatable Messages............................................................................................... 67

Locales .................................................................................................................................... 68

Chapter 4 JADE under a Red Hat Distribution of Linux on Intel 72 Overview ................................................................................................................................................. 73 Red Hat Linux Installation on Intel Servers ........................................................................................ 74

Overview of Installing JADE on Linux under Red Hat................................................................ 74 JADE Operational Requirements on Linux under Red Hat ....................................................... 75

Red Hat Linux Hardware Requirements .............................................................................. 75 Minimum Hardware Requirements for a JADE Database Server ................................ 75 Minimum Hardware Requirements for an Application Server ................................... 76 Minimum Hardware Requirements for Standard Clients............................................ 76 Minimum Hardware Requirements for Running JADE Presentation Clients ............ 77

Red Hat Linux Software Requirements ................................................................................ 77 JADE Product and RPM Names for Red Hat Linux on Intel ...................................................... 79

Port Numbers for Red Hat Linux.......................................................................................... 80 Installing JADE............................................................................................................................... 81

Parameters for the jadeinstall Command ............................................................................. 83 [--help]............................................................................................................................. 83 -i | --installDir= ................................................................................................................. 83 -v | --version=.................................................................................................................... 83 [-u | --usercode=]............................................................................................................. 83 [-g | --group=] .................................................................................................................. 83 [-s | --serviceName=]........................................................................................................ 83 [-n]................................................................................................................................... 83 [-k] ................................................................................................................................... 83 [-f | --force] ...................................................................................................................... 84 [-t | --targetType=]........................................................................................................... 84 [-q | --quiet] ..................................................................................................................... 84 [-j | --jadeHome=]............................................................................................................ 84 [-U | --Upgrade] .............................................................................................................. 84 [--all] ................................................................................................................................ 84 [--rte] ............................................................................................................................... 84


Contents vii

JADEICG-6.3

Chapter 4 JADE under a Red Hat Distribution of Linux on Intel, continued [--devdata] ....................................................................................................................... 84 [--devel] ........................................................................................................................... 84 [--docs]............................................................................................................................. 84 [--examples] .................................................................................................................... 84 [--thinclient].................................................................................................................... 85 [--w32thinclient] ............................................................................................................. 85

Starting and Stopping the JADE System ............................................................................... 85 Registering the Database ....................................................................................................... 85 Setting Up the Windows Client ............................................................................................. 86

Upgrading a JADE Release............................................................................................................ 86 Deinstalling JADE .......................................................................................................................... 87

Displaying the Packages Associated with a Specific JADE Version...................................... 87 Obtaining a Core Dump................................................................................................................ 87

Detailed Command Information for Red Hat Linux on Intel............................................................ 88 Environment Variables .................................................................................................................. 88

Required Environment Variables .......................................................................................... 88 JADEHOME .................................................................................................................... 88 LANG............................................................................................................................... 89 LD_LIBRARY_PATH...................................................................................................... 89 NLSPATH........................................................................................................................ 89 PATH............................................................................................................................... 89

Optional Environment Variables .......................................................................................... 90 JADELANGDIR............................................................................................................... 90 LC_CTYPE....................................................................................................................... 90 TMPDIR .......................................................................................................................... 90

JADE Daemon (jaded)................................................................................................................... 90 Starting JADE Daemon from the Command Line ............................................................... 90

JADE Portable GUI (jadepg)......................................................................................................... 91 Starting the JADE Portable GUI from the Command Line................................................. 91

Running an Application Server..................................................................................................... 91 Invoking an Application Server............................................................................................. 92

Running a Non-GUI Client Application....................................................................................... 93 Invoking a Non-GUI Client Application ............................................................................... 93

Initiating Non-GUI Applications when the Application Server is Initiated ................ 94 Initiating Non-GUI Applications at a Specific Time .................................................... 95

Java Framework .............................................................................................................................. 95 Locales and Translatable Messages............................................................................................... 95

Locales .................................................................................................................................... 95

Chapter 5 Configuring JADE 100 Example Production System Configurations ....................................................................................... 101 Directory Locations ............................................................................................................................... 102

Installation Directory Location ..................................................................................................... 103 Home Directory Location.............................................................................................................. 103 Program Data Directory Location................................................................................................. 103 User Data Directory Location ....................................................................................................... 104 Work File Directory Location........................................................................................................ 105


Contents viii

JADEICG-6.3

Chapter 5 Configuring JADE, continued Configuring Your Network Protocol .................................................................................................... 106

Selecting Network Addresses......................................................................................................... 106 Local Intra-Machine Transport..................................................................................................... 107

Connecting to JADE Applications from Internet Information Server (IIS) ...................................... 108 Application Requirements for a Jade61 Application Type.......................................................... 110

Connecting to JADE Applications from an Apache HTTP Server ..................................................... 110 Using the mod_ jadehttp Module................................................................................................. 111

Configuring Your JADE Software ......................................................................................................... 112 Portable GUI Configuration.......................................................................................................... 114

Portable GUI Environment Variables ................................................................................... 115 CLASSPATH ................................................................................................................... 115 JAVA_HOME .................................................................................................................. 116 JRE_HOME ..................................................................................................................... 116 JMFHOME ...................................................................................................................... 116 LD_LIBRARY_PATH...................................................................................................... 116

Running a Headless Portable GUI Program ........................................................................ 117 Configuring JadeHttp for Remote Connections.......................................................................... 117

Firewall for the JADE Internet Environment ....................................................................... 118 Image Files Created by the JADE Application .............................................................. 118 Files Transferred from the Web Browser ...................................................................... 120 Internal Housekeeping of the Virtual Directory .......................................................... 121

Controlling the Location of Files Uploaded via a Web Application ................................... 121 [application-name] Section ................................................................................................... 122

ApplicationType ............................................................................................................. 122 CloseDelay[n] ................................................................................................................. 123 ConnectionGroup[n]..................................................................................................... 123 FirstTcpPort[n]............................................................................................................... 123 GroupSharesConnections .............................................................................................. 124 JadeHost .......................................................................................................................... 125 LastTcpPort[n] ............................................................................................................... 125 MaximumPipes ............................................................................................................... 125 MaxInUse[n]................................................................................................................... 126 MaxMessageSize.............................................................................................................. 126 MaxQueueDepth ............................................................................................................ 126 MessageTimeout ............................................................................................................. 127 MinInUse[n] ................................................................................................................... 127 MinMessageSize .............................................................................................................. 128 TcpConnection[n] ......................................................................................................... 128 TcpPort[n] ...................................................................................................................... 128 VirtualDirectory .............................................................................................................. 128 Sample [application-name] Section ................................................................................. 129

[Jadehttp Files] Section ......................................................................................................... 130 FileTransferDirectory ..................................................................................................... 131 Firewall ............................................................................................................................ 131 Sample [Jadehttp Files] Section .................................................................................... 131

[Jadehttp Logging] Section................................................................................................... 132 Trace................................................................................................................................ 132 TraceFile.......................................................................................................................... 132 Sample [Jadehttp Logging] Section.............................................................................. 132


Contents ix

JADEICG-6.3

Chapter 5 Configuring JADE, continued Configuring Apache for Remote Connections ............................................................................ 132

Apache Configuration Directives .......................................................................................... 133 SetHandler ...................................................................................................................... 134 ApplicationType ............................................................................................................. 135 Application...................................................................................................................... 135 FaultDocument ............................................................................................................... 136 FileTransferDirectory ..................................................................................................... 136 Firewall ............................................................................................................................ 137 GroupSharesConnection ............................................................................................... 137 JadeHttp_Trace............................................................................................................... 138 JadeServer ....................................................................................................................... 139 JadeTimeout.................................................................................................................... 140 LocalInterface................................................................................................................. 141 MaxMessageSize.............................................................................................................. 141 MaxQueueDepth ............................................................................................................ 142 MinMessageSize .............................................................................................................. 142 PhysicalDirectory ............................................................................................................ 143 PurgeDirectoryFrequency .............................................................................................. 143 PurgeFileAge................................................................................................................... 144 TcpConnection[n] ......................................................................................................... 144

MinInUse................................................................................................................. 145 MaxInUse ................................................................................................................ 145 CloseDelay ............................................................................................................... 146 ConnectionGroup................................................................................................... 146

VirtualDirectory .............................................................................................................. 146 Apache Configuration Examples .......................................................................................... 147

Minimal Configuration Example................................................................................... 147 Extended Configuration Example................................................................................. 148 Extended Configuration Example with Additional Apache Directives....................... 148

Apache Considerations .......................................................................................................... 150 Tuning Your Systems ..................................................................................................................... 150

Specifying Parameters in the JADE Command Line ........................................................................... 151 Placing Initialization File Parameters on the Command Line.................................................... 154 Handling Multiple Copies of the JADE Program......................................................................... 156

Specifying Your Administration Options ............................................................................................. 156 Using the File Menu ...................................................................................................................... 157

Saving Your Options and Logging Off.................................................................................. 157 Logging Off from the Installation Preferences Dialog ........................................................ 158 Saving Options and Exiting from the Installation Preferences Dialog............................... 158 Exiting from the Installation Preferences Dialog................................................................. 158

Using the Admin Menu ................................................................................................................. 158 Resetting JADE Default Preferences ..................................................................................... 159 Removing Source Code.......................................................................................................... 159 Backing Up Your Development Database from a Client Workstation ................................ 159

Using the Patch Menu ................................................................................................................... 160 Using the Help Menu .................................................................................................................... 160 Specifying Your JADE Installation Preferences............................................................................ 160

Maintaining Painter Options................................................................................................. 162


Contents x

JADEICG-6.3

Chapter 5 Configuring JADE, continued Reregistering a JADE System in Batch Mode ............................................................................... 163

path ......................................................................................................................................... 163 ini............................................................................................................................................. 163 name........................................................................................................................................ 164 key ........................................................................................................................................... 164 online ...................................................................................................................................... 164 minStandard ........................................................................................................................... 164 minJade ................................................................................................................................... 164 report ...................................................................................................................................... 165 help ......................................................................................................................................... 165

Using the JADE Version Information Utility ....................................................................................... 165 Checking which Hot Fixes are Applied ........................................................................................ 167 Obtaining the Version Number of User Database Files .............................................................. 167

Appendix A Exit Values 169 Overview ................................................................................................................................................. 169 Enabling the Use of Generic Exit Values for Windows ....................................................................... 170 General Exit Values Unique to Each Program .................................................................................... 170

Index 173

____________________________________

JADEICG-6.3

Before You Begin

____________________________________

The JADE Installation and Configuration Guide is intended as the main source of information when you are installing and configuring JADE.

Who Should Read this Guide The main audience for the JADE Installation and Configuration Guide is expected to be system administrators.

What's Included in this Guide The JADE Installation and Configuration Guide has five chapters and one appendix.

Chapter 1 Covers installing JADE under Windows

Chapter 2 Covers installing Compact JADE under Windows CE

Chapter 3 Covers installing JADE under SUSE Linux Enterprise Server on Intel

Chapter 4 Covers installing JADE under a Red Hat distribution of Linux on Intel

Chapter 5 Covers configuring JADE

Appendix A Covers the JADE program and warning exit values


Before You Begin xii

JADEICG-6.3

Conventions The JADE Installation and Configuration Guide uses consistent typographic conventions throughout.

Convention Description

Arrow bullet ( ) Step-by-step procedures. You can complete procedural instructions by using either the mouse or the keyboard.

Bold Items that must be typed exactly as shown. For example, if instructed to type foreach, type all the bold characters exactly as they are printed.

File, class, primitive type, method, and property names, menu commands, and dialog controls are also shown in bold type, as well as literal values stored, tested for, and sent by JADE instructions.

Italic Parameter values or placeholders for information that must be provided; for example, if instructed to enter class-name, type the actual name of the class instead of the word or words shown in italic type.

Italic type also signals a new term. An explanation accompanies the italicized type.

Document titles and status and error messages are also shown in italic type.

Blue text Enables you to click anywhere on the cross-reference text (the cursor symbol changes from an open hand to a hand with the index finger extended) to take you straight to that topic. For example, click on the “Work File Directory Location” cross-reference to display that topic.

Bracket symbols ( [ ] ) Indicate optional items.

Vertical bar ( | ) Separates alternative items.

Monospaced font Syntax, code examples, and error and status message text.

ALL CAPITALS Directory names, commands, and acronyms.

SMALL CAPITALS Keyboard keys.

Key combinations and key sequences appear as follows.

Convention Description

KEY1+KEY2 Press and hold down the first key and then press the second key. For example, “press SHIFT+F2” means to press and hold down the SHIFT key and press the F2 key. Then release both keys.

KEY1,KEY2 Press and release the first key, then press and release the second key. For example, “press ALT+F,X” means to hold down the ALT key, press the F key, and then release both keys before pressing and releasing the X key.

In this document, the term Microsoft Windows refers to Windows 2003 Server, Windows Vista, Windows XP, Windows 2000, or Windows CE. (For details about the differences when running JADE applications under Microsoft Windows Vista, see Chapter 6, “Windows Vista Support”, in the JADE Platform Differences Guide.)

When there are differences between the versions of Microsoft Windows, the specific version of Microsoft Windows is stated. This also applies to Linux, which is a specific version of UNIX developed by SUSE or Red Hat. The term UNIX is used when an issue is generic to all versions of UNIX and the term Linux is used if the issue is specific to the SUSE or Red Hat implementation of UNIX.


Before You Begin xiii

JADEICG-6.3

With the exception of the jade.exe program, when referring to Windows program executables in this document, the .exe file suffix is omitted; for example, jadclient refers to jadclient.exe on Windows and jadclient.sh on UNIX. Similarly, the Windows .dll (Dynamic Link Library) and UNIX .so (shared object library) file suffixes are omitted. For example, jomos refers to jomos.dll (Windows) and libjomos.so (Linux).

Related Documentation Other documents that are referred to in this guide, or that may be helpful, are listed in the following table, with an indication of the JADE operation or tasks to which they relate.

Title Related to…

JADE Database Administration Guide Administering JADE databases

JADE Development Environment Administration Guide Administering JADE development environments

JADE Development Environment User’s Guide Using the JADE development environment

JADE Developer’s Reference Developing or maintaining JADE applications

JADE Encyclopaedia of Classes System classes (Volumes 1 and 2), Window classes (Volume 3)

JADE Encyclopaedia of Primitive Types Primitive types and global constants

JADE Initialization File Reference Maintaining JADE initialization file parameter values

JADE Java Developer’s Reference Developing or maintaining JADE applications from a Java integrated development environment

JADE Synchronized Database Service (SDS) Administration Guide Administering JADE Synchronized Database Services (SDS), including Relational Population Services (RPS)

JADE Object Manager Guide JADE Object Manager administration

JADE Platform Differences Guide Platform differences when running JADE applications

JADE Replication Framework User’s Guide Replicating selective activity between physically different but logically similar JADE systems

JADE Report Writer User’s Guide Using the JADE Report Writer to develop and run reports

JADE Runtime Application Guide Administering deployed JADE runtime applications

JADE Thin Client Guide Administering JADE thin client environments

JADE Web Application Guide Implementing, monitoring, and configuring Web applications

____________________________________

JADEICG-6.3

Chapter 1 Installing JADE under Windows

____________________________________

This chapter covers the following topics.

Operational Requirements

Hardware Requirements

– Minimum Hardware Requirements for Running JADE Thin Client Software Only

– Minimum Hardware Requirements for Machines not Hosting a JADE Database

– Minimum Hardware Requirements for Machines Hosting a JADE Database

Software Requirements

– Additional Software Requirements for Deploying JADE Web Applications

– ODBC Requirements for External Database Coexistence or JADE ODBC Driver Usage

– Portable Graphical User Interface (Portable GUI) Requirements

– Java Framework Requirements

– .NET Requirements

– Requirements for Exporting JADE Objects through ActiveX Exposure

– Requirement for Postscript Printing

– Requirements for RPS Nodes

– Virtual Environments

Installing Your JADE Software

Initiating the Installation from the JADE Setup Program

JADE Software Installation Process

JADE Configurations under Windows

Multiuser Configuration

Single User Configuration

Installing Multiple JADE Initialization Files

Reregistering JADE with a New Licence

Configuring the JADE JIT Debugger


Chapter 1 Installing JADE under Windows 15

JADEICG-6.3

Operational Requirements This section describes the JADE operational requirements and contains the following subsections.

Hardware Requirements

Software Requirements

Hardware Requirements This section describes the hardware required for JADE development and JADE applications running under a Windows operating system.

Further requirements that must be met to satisfactorily provide for data recoverability are described in the Environmental Considerations for Deploying JADE white paper on the JADE Web site at http://www.jadeworld.com/jade/whitepapers.htm.

Notes These specifications represent minimum configurations. Configurations that are more powerful may be advisable, depending on the scale of your JADE applications and the performance requirements of your system.

JADE handles only the first nine monitors running on one workstation. Additional monitors are ignored.

For examples of some business-critical production system hardware considerations, see “Example Production System Configurations”, in Chapter 5.

Minimum Hardware Requirements for a JADE Database Server The following subsections contain the recommended minimum hardware required to deploy JADE on a machine that hosts a JADE database server node.

Processors

For a database server with:

Up to 10 concurrent users, you require an Intel Single Core CPU (Pentium, AMD, or compatible), 1 GHz or faster

More than 10 concurrent users, you require an Intel Dual Core CPU (Pentium, AMD, or compatible), 1 GHz or faster

Memory

For database servers, you require 2G bytes Error Checking and Correcting (ECC) RAM.

Add 128M bytes for each JADE node.

Storage

For database servers, you require:

Disk subsystem that guarantees that acknowledged writes are non-volatile (for details, see the Environmental Considerations for Deploying JADE white paper on the JADE Web site at http://www.jadeworld.com/jade/whitepapers.htm)

Available disk space of four times the expected database size, allowing for growth

http://www.jadeworld.com/jade/whitepapers.htm




JADEICG-6.3

RAID 1+0 configuration (for details, see the Environmental Considerations for Deploying JADE white paper on the JADE Web site at http://www.jadeworld.com/jade/whitepapers.htm)

Other

For database servers:

Server class hardware is essential

TCP/IP network environment is required

Data backup components (for example, a backup disk drive, tape drive, or an optical read-write drive)

Minimum Hardware Requirements for an Application Server The following subsections contain the recommended minimum hardware required to deploy JADE on machines hosting an application server.

Processors

For an application server with:



Memory

For application servers, you require 2G bytes Error Checking and Correcting (ECC) RAM.


Storage

When computing disk space requirements for application servers, allow for software installation size, transient object storage, and application external file requirements.

Other

For application servers:

Server class hardware is recommended

Transmission Control Protocol/Internet Protocol (TCP/IP) network environment is required

Data backup components (for example, a backup disk drive, tape drive, or an optical read--write drive) if not provided by another server (for example, by the database server)

Minimum Hardware Requirements for Standard Clients The following subsections contain the recommended minimum hardware required to deploy JADE on a machine that hosts a JADE standard client.

Processors

For a standard client, you require an Intel CPU (Pentium, AMD, or compatible), 1 GHz or faster.




JADEICG-6.3

Memory

For standard clients, you require 512M bytes Error Checking and Correcting (ECC) RAM.


Storage

When computing disk space requirements for standard clients, allow for software installation size, transient object storage, and application external file requirements.

Other

For standard clients:

Screen resolution of 800x600 or higher is required


Minimum Hardware Requirements for Running Presentation Clients The following subsections contain the recommended minimum hardware required to deploy JADE on a presentation (or thin) client node.

Processors

For a presentation client, you require an Intel CPU (Pentium, AMD, or compatible), 1 GHz or faster.

Memory

For presentation clients, you require 512M bytes RAM (recommended) or 256M bytes (minimum, depending on the operating system).

Storage

When computing disk space requirements for presentation clients, allow for software installation size, presentation client forms cache, and application external file requirements.

Other

For presentation clients:


Network Interface Card (NIC) or a dial-up adaptor and modem




JADEICG-6.3

Software Requirements This section describes the software required for JADE development and JADE applications.

Notes JADE encodes Unicode characters using the wide-character encoding routines provided by Windows 2003 Server, Windows Vista, Windows XP, Windows 2000, Windows CE, or UNIX.

JADE 6.3 has been compiled on Windows environments using the:

Microsoft Visual C++ 2005 SP1 compiler for 32-bit binaries. Because JADE 6.3 is compiled against Visual Studio 2005 on Windows, it requires the Microsoft C++ 2005 SP1 Redistributable Package (x86) called vcredist_x86.exe to be installed. (This executable is supplied on the JADE distribution media.)

Microsoft Windows C++ 2008 SP1 compiler for 64-bit binaries. Because JADE 6.3 is compiled against Visual Studio 2008 on Windows, it requires the Microsoft C++ 2008 SP1 Redistributable Package (x64) called vc_x64Runtime.exe to be installed. (This executable is supplied on the JADE distribution media.)

This will be done as part of the normal JADE installation or upgrade process. Installing this Microsoft redistributable package requires administration privileges. If possible, deploy this package to all workstations before installing or upgrading to JADE 6.3, using the appropriate techniques that allow for privileged installations.

Although minimum Service Pack (SP) levels are specified, we recommend that you keep up-to-date with Service Packs and security updates for the operating system that you are running.

Database Server A JADE database server requires one of the following:

Microsoft Windows 2008 Server (recommended) with the latest security updates

Microsoft Windows 2003 Server (recommended) with SP1 and the latest security updates

Microsoft Windows 2000 Server (minimum) with SP4 and the latest security updates

Application Server A JADE application server requires one of the following:

Microsoft Windows 2008 Server (recommended) with the latest security updates

Microsoft Windows 2003 Server (recommended) with SP1 and the latest security updates

Microsoft Windows 2000 Server (minimum) with SP4 and the latest security updates

Standard Clients JADE standard clients require one of:

Microsoft Windows XP Professional (recommended) with SP2

Microsoft Windows Vista Business (recommended) or better

Microsoft Windows 2000 Professional (minimum) with SP4 and Update Rollup 1

Any database server or application server operating system



JADEICG-6.3

Presentation (Thin) Clients Presentation clients require one of:

Windows XP Professional (recommended) with SP2

Windows Vista Home Premium (recommended) or better

Windows 2000 Professional (minimum) with SP4 and Update Rollup 1

Any database server or application server operating system

Additional Software Requirements for Deploying JADE Web Applications The additional software required to deploy JADE Web applications is the minimum of one of the following.

Microsoft Internet Information Server (IIS) 6.0

Apache 2.2.3 for Microsoft Windows

In addition, JADE Web services support SOAP version 1.1 and version 1.2.

Notes Unicode Web applications are not supported.

To provide greater security with firewalls, the machine hosting the Web server can be different from the machine that is running the JADE application.

ODBC Requirements for External Database Coexistence or JADE ODBC Driver Usage The Microsoft Data Access Components (MDAC) installed with the Windows operating system are sufficient for running an external relational database or using the JADE ODBC standard or thin client driver.

Note The JADE ODBC drivers are available in 32-bit and 64-bit versions. If running on a 64-bit machine, the driver used must match the third-party tool being used; for example, it may be necessary to install 32-bit JADE ODBC drivers for use with 32-bit tools.

If you are running JADE on a 64-bit machine under Windows in 64-bit mode and you are configuring a 32-bit tool, run the following program:

<\windows-directory>\SysWOW64\odbcad32.exe

This runs the 32-bit version of the Microsoft Data Source Administrator program rather than the 64-bit version.

For more details, see “Configuring a JADE ODBC Driver”, in Chapter 6 of the JADE Developer's Reference.



JADEICG-6.3

Portable Graphical User Interface (Portable GUI) Requirements To deploy a JADE thin client or standard (fat) client on any compatible Java-capable desktop, you require the:

Sun or IBM Virtual Machine Java 2 Runtime Environment ( JRE), Standard Edition ( J2SE) Version 6. In addition, the JADE initialization file on the presentation client or standard (fat) client must have a [ JadeJava] section that indicates the directory in which the J2SE software resides; for example:

[JadeJava] JavaHome=C:\Program Files\Java\jre1.6.0_12

Sun Java Media Framework ( JMF) 2.1.1e.

For 32-bit JADE clients, the native or the cross-platform version of JMF can be used. For the 64-bit version of JADE, the Java Media Framework ( JMF) library must be the portable version (that is, all Java code and no .dll files), not the i386 version.

Note Download the Java installation (the software package) from the Sun Microsystems Java Web site http://java.sun.com/ or the IBM Web site http://www.ibm.com/developerworks/java/.

Download the Java Media Framework ( JMF) 2.1.1e software package from the Sun Microsystems Java Web site http://java.sun.com/. Although you can download the Windows Intel or All Java version of these software packages, the Windows Intel version provides improved performance.

For details about configuring your portable GUI software, see “Portable GUI Configuration”, “Portable GUI Environment Variables”, and “Running a Headless Portable GUI Program”, under “Configuring Your JADE Software”, in Chapter 5.

Java Framework Requirements To deploy a Java framework, you require the:

Sun or IBM Virtual Machine Java 2 Runtime Environment ( JRE), Standard Edition ( J2SE) Version 6.

Note Download the Java installation (the software package) from the Sun Microsystems Java Web site http://java.sun.com/ or the IBM Web site http://www.ibm.com/developerworks/java/.

.NET Requirements To develop and compile .NET applications, you must have Microsoft Visual Studio 2008, Microsoft Visual Studio 2008, or Microsoft Visual Studio 2008 Express, the free but limited edition of Visual Studio 2008.

Machines that are used to generate and use the .NET library must have .NET Framework 3.0 or higher installed.

Requirements for Exporting JADE Objects through ActiveX Exposure To support the JADE object interface through an ActiveX Exposure Dynamic Link Library (DLL), the following software must be installed on any machine that is accessing JADE objects as ActiveX objects.

Visual C++ 6

http://java.sun.com/

http://www.ibm.com/developerworks/java/






JADEICG-6.3

ActiveX Template Library (ATL)

The ActiveX Exposure Wizard (a Visual Studio add-in) is installed with the Development and Custom installation types. (For details, see “Selecting the Components to Install”, later in this chapter.)

The software must be installed on the:

Application server, if running in thin client mode

Client node, if running in fat (standard) client mode

Server node, if running server execution”

Requirement for Postscript Printing If using Postscript printing, your printer must support Postscript level 2 or greater.

Requirements for RPS Nodes With the Relational Population Service (RPS) that provides automatic replication of objects from a JADE database to one or more relational databases when running an RPS node, the following SQL Server ODBC drivers must be used for the SQL Server versions.

Microsoft SQL Server 2008 requires SQL Server Native Client 10.0 or later

Microsoft SQL Server 2005 requires SQL Native Client or later

Microsoft SQL Server 2000 requires SQL Native Client or later (recommended) or SQL Server

The edition must match the JADE server edition (32-bit or 64-bit) running on the RPS node.

The sqlcmd SQL Server utility must be installed on the RPS node to use the default (recommended) sqlcmd to execute SQL scripts. (For details, see step 6.e under “Configuring your RPS Node”, in Chapter 2 of the JADE Synchronized Database Service (SDS) Administration Guide.)

Virtual Environments JADE can be run in a virtual environment on all supported operating systems listed in the previous sections on Intel-compatible hardware.

Support is provided as per the published release policy for faults found in a virtual environment; however, a problem that is suspected to be related to an issue in the virtualization layer may result in requests for additional customer diagnostic actions. In some rare cases, fixes for issues that are specific to the virtualization layer may need to be negotiated with the customer.

Installing Your JADE Software The JADE software is supplied on the JADE release medium (for example, the ANSI CD-ROM, the Unicode CD-ROM, or from the JADE Web site). Install your JADE software from the setup executable program file contained on the release medium.



JADEICG-6.3

Notes You should exit from all Windows programs before you install your JADE software.

For users wishing to develop their own installation process for Windows, the JADE install and upgrade steps are documented in the ReadmeInstallSteps.txt file in the \documentation directory.

Because of the changes to the security model in Windows Vista, if you are installing JADE under Vista, ensure that you have the appropriate privileges or capabilities to install applications. The configuration of Vista’s User Account Control (UAC) and your current user account privileges may affect the behavior of the installation. For details about Windows Vista UACs, standard user accounts, and administrator accounts, see:

http://technet2.microsoft.com/WindowsVista/en/library/00d04415-2b2f-422c-b70e-b18ff918c2811033.mspx?mfr=true

The 32-bit Microsoft Windows C++ 2005 SP1 Redistributable Package (x86) or 64-bit Microsoft C++ 2008 SP1 Redistributable Package (x64) is required on all Windows systems that run JADE 6.3. Installing this Microsoft redistributable package requires administration privileges. If possible, deploy this package to all workstations before installing JADE 6.3, using the appropriate techniques that allow for privileged installations.

Click the Next > button when you have specified the required information in each JADE set-up folder. The folder for the next phase of the installation process is then displayed, if applicable. Use the < Back button to return to earlier set-up folders. To abandon the JADE installation, click the Cancel button in the current set-up folder.

For details about the customization mechanism that enables you to customize the installation of JADE presentation client software, see “Customizing the Presentation Client Installer” under “Installing Application Servers and Presentation Clients”, in Chapter 3 of your JADE Thin Client Guide. For details about customizing the upgrading of deployed JADE systems, see Appendix A of your JADE Runtime Application Guide, “Customizing the Deployment Upgrade Process”.

For details about upgrading JADE release 6.2 databases, see “Upgrading to JADE 6.3 from a Windows JADE 6.2.12 Release or Higher”, in the ReleaseInfo.pdf file on your JADE release medium. (You can upgrade to JADE release 6.3 only from a JADE 6.2 release.)

Initiating the Installation from the JADE Setup Program Before installing JADE, make sure that there are no conflicting applications running. The following instruction is an example of the installation of JADE on Windows from a CD-ROM. Alternatively, you can execute the executable program downloaded from the JADE Web site (that is, www.jadeworld.com).

To initiate the installation of your JADE software, for example

1. Place the JADE release CD-ROM in the CD-ROM drive

2. In Explorer, select the Windows folder on the CD-ROM drive

3. Double-click the setup program

The Microsoft Windows C++ 2005 SP1 Redistributable Package (x86) is installed.

Note This package is required on all systems that run JADE 6.3.



http://www.jadeworld.com/



JADEICG-6.3

The installation of your JADE software is then started and the initialization progress is displayed in the Setup progress dialog.

JADE Software Installation Process During the installation process, the JADE set-up program performs the events described in the following subsections.

Displaying the Welcome Dialog The JADE set-up program first displays the Welcome dialog.

Accepting the Terms of the JADE License Agreement The Software License Agreement folder is then displayed. Use the scroll bar or the PAGE DOWN key to scroll through and read the entire software license agreement.

When you have read the entire software license agreement and you accept the specified terms, click the Yes button to continue the installation. (You cannot install JADE until you accept these license agreement terms.) Alternatively, click the No button to close the JADE set-up process.

Selecting the Type of Installation The Installation Type folder is then displayed, to enable you to select the type of installation that you require. The types of installation that you can select are:

Fresh Copy, which is selected by default, and installs a brand new copy of JADE.

Feature Upgrade, which you can select if you want to upgrade an existing JADE database and binary files. For details, see the ReleaseInfo.pdf file on your JADE release medium.

Selecting the Type of Set Up The Setup Type folder is then displayed, to enable you to select the type of set up that you require. The types of set up that you can select are listed in the following table.

Type Installs…

Development Binary, database, JADE Report Writer, documentation, and general support files required to run single user and multiuser mode of the development and application runtime environments and JADE application server and presentation client files

Application Runtime Only the binary, documentation, and general support files required to run the JADE application server

Presentation Client Only the binary and general support files required to run the presentation client in JADE thin client mode

Jade Client Only the binary and documentation files required to run a JADE client (including the JADE ODBC driver)

Custom User-selected JADE components (for the Fresh Copy installation type only)

SDS development Binary and database files for the JADE environment on SDS (Feature Upgrade installation type only)

By default, the Development option is selected.



JADEICG-6.3

Note If you are not installing or upgrading JADE from a CD-ROM or you are installing the Presentation Client installation type, the documentation files are not included and must be downloaded from the JADE Web site separately, if required.

Selecting the Components to Install When you specify a Custom installation, the Select Components folder is then displayed. to enable you to select the file components that you want to install. You can select the installation of the following components.

ActiveX Exposure Files

Binary Files

Debug Symbol Files

Documentation

Example Files

Include Files

Library Files

Presentation Client Files

ReadMe File

Report Writer Files ( JADE Report Writer)

Rose JADE Add-in Files

System Files ( JADE development database)

White Paper Files

Windows System Files

WSDL Files

No components are selected for installation, by default.

To select or deselect a component for installation

Click the appropriate component.

The disk space required for each component is displayed at the right of the component in the Components list box.

The available disk space and the required disk space for all currently selected components are displayed at the bottom of the folder.

Specifying Your User Information If you are installing a JADE database, the User Information folder enables you to specify the Licence Name (that is, your organization name, which is not to be confused with your company name that is displayed in large letters above the licence name and key) and your Licence Key specified on your licence for your JADE database.

An entry is required in both the Licence Name and Licence Key text boxes.



JADEICG-6.3

Notes To obtain your licence key, contact your local JADE authorized reseller.

The licence key has four text boxes. Enter the licence key exactly as it is specified on your Certificate of Authorisation (which may be an e-mail message providing you with your licence name and key). Enter the first eight characters in the first text box, the next eight characters in the second text box, the next eight characters in the third text box, and the last eight characters in the fourth text box. (Ignore the “-” printed on the licence.)

Ensure that you type the licence name of your organization (which is case-sensitive) correctly, as this is validated against your licence key.

Selecting the Destination Directory The Select Installation Folders folder enables you to specify the locations of the JADE files that are to be installed. The installation process defaults to the Jade63 directory on your c: drive, and displays these values in the Install Directory, Executable Directory, and Database Directory text boxes.

To select a destination directory

Click the Browse button.

The common File dialog is then displayed, to enable you to specify the destination directory for your JADE files.

The Database Directory text box enables you to explicitly specify the location in which the database (system) files are installed. When installing on a non-Vista operating system or on Vista when the destination folder is not \Program Files, the database destination defaults to system under the install folder (for example, if you specify c:\ Jade63 in the Install Directory text box, the database directory defaults to c:\ Jade63\system).

If the installation directory is a subdirectory of the programmatically determined location of \Program Files on Vista, the \Program Files portion of the install directory is replaced with programmatically discovered location for the common application data directory (for example, if you specify c:\Program Files\ Jade63 in the Install Directory text box, the default database location is c:\ProgramData\ Jade63\system).

Selecting the Program Folder for the JADE Icons The Select Program Folder folder is then displayed, to enable you to select the program folder in which the JADE icons are installed.

By default, the JADE icons are installed in the JADE program folder. If the program folder specified in the Program Folder text box does not exist, the installation process creates it.

The Existing Folders list box enables you to select an existing program folder, if required.

Selecting the Installation of the JADE Just-In-Time (JIT) Debugger The JADE JIT Debugger folder is then displayed, to enable you to specify whether you want the JADE JIT ( Just-In-Time) Debugger installed. By default, the JADE JIT Debugger is installed; that is, the Install JADE JIT Debugger check box is checked.

The JIT Debugger enables you to reliably acquire a dump and crash log when an exception occurs in a system running with the Microsoft Visual C++ 8 (MSVC8) run time.



JADEICG-6.3

Installing and un-installing Dr Danyo as the JIT debugger (the -i and -u command line switches) requires execution at an elevated privilege; for example, using an administrator command prompt.

Notes It is recommended that you install this on all non-presentation client-only nodes running JADE.

If User Account Control (UAC) is enabled, you must be running as an administrator.

Running the Installation Program The Start Copying Files folder is then displayed. This dialog displays the installation options that you have selected.

Review your selections and then click the Next > button, to start copying files.

Informing You When the Installation is Complete When the installation is complete, the JADE set-up program informs you that the JADE set-up program was successfully completed and the ReadMe.txt file can now be viewed.

To view the ReadMe.txt file

Ensure that the check box is checked (the default).

The ReadMe.txt file, which refers you to the document covering migrating to JADE release 6.3, the changes and new features in this release, and to other documents relating to JADE release 6.3, is then displayed in a text editor (for example, Notepad).

The ReadMe.txt file is a read-only text file installed in your JADE documentation directory that you can print or delete, if required.

Click the Finish button to end the JADE installation process. Alternatively, if a system file could not be updated, the JADE set-up program prompts you to reboot your workstation so that it can complete the installation. In this case, you can view the ReadMe.txt file by using the shortcut in your specified folder.

JADE Configurations under Windows The JADE database can be run in one of the following configurations.

Multiuser (the default)

The multiuser configuration allows access to the database from multiple processes across multiple workstations. One workstation must perform the role of server, or remote, node. For more details, see “Multiuser Configuration”, in the following subsection.

Single user

The single user configuration allows access to the database from one process only (for example, only one copy of jade.exe). For more details, see “Single User Configuration”, later in this chapter.

For details about accessing JADE applications from IIS or the Apache HTTP Server, see “Connecting to JADE Applications from Internet Information Server (IIS)” and “Configuring JadeHttp for Remote Connections” or see “Connecting to JADE Applications from an Apache HTTP Server” and “Configuring Apache for Remote Connections”, in Chapter 5.



JADEICG-6.3

Multiuser Configuration Before running JADE in multiuser mode (the default), ensure that TCP/IP has been loaded on both your client workstations and the server (remote node) workstation.

For details, see “Selecting Network Addresses”, in Chapter 5, or “Using the JADE Remote Node Access Utility”, in Chapter 1 of your JADE Remote Node Access Utility User’s Guide.

In the standard initial installation, the following parameters are set in the jade.ini file in the database directory.

[Jade] server=multiUser // Default [JadeServer] NodeName=LocalHost NetworkSpecification1=TcpIp,Enabled,6005 [JadeClient] ServerNodeSpecifications=TcpIp,LocalHost,6005

This sets up the server and clients to run on the same installation node.

For more details about the parameters in the JADE initialization file required to run JADE in a multiuser environment, see Chapter 1 of your JADE Initialization File Reference, particularly the “JADE Object Manager Client Module Section [ JadeClient]” and “JADE Object Manager Server Section [ JadeServer]” sections.

Running a JADE Server in Multiuser Mode The default multiuser installation sets up the JADE MultiUser \ JADE Database Server shortcut for the JADE server.

The following table lists examples of the properties required to run a JADE server.

Property Example

Command line jadrap.exe path=s:\jade\system ini=s:\jade\system\jade.ini app=Jade

Working directory s:\jade\bin

Running a JADE Client in Multiuser Mode The default multiuser installation sets up the JADE MultiUser \ JADE Client shortcut for the JADE multiuser client.

Hint When running JADE in multiuser mode as a standard (fat) client, the JADE initialization file is usually specified on the command line. If a JADE initialization file is not specified, JADE attempts to use the jade.ini file in the server node system directory.

If this directory is not visible to the client node, the default values used may not be sufficient for your application to run.



JADEICG-6.3

The following table lists examples of the properties required to run the JADE development environment in a JADE client.

Property Example

Command line jade.exe path=s:\jade\system ini=c:\jade\system\jade.ini app=Jade


Ensure that you specify the same path in the path parameter of both the JADE Remote Node Access utility ( jadrap) and JADE ( jade.exe).

Running a JADE User Application in Multiuser Mode The following table lists examples of the properties required to run a user application written in JADE on a client node.

Property Example

Command line jade.exe path=s:\jade\system schema=AccountsApp app=Accounts ini=c:\jade\system\jade.ini


Ensure that you specify the same path in the path parameter of both the JADE Remote Node Access utility ( jadrap) and JADE ( jade.exe or jadepg).

Running an Application Server in JADE Thin Client Mode The default multiuser installation sets up the JADE MultiUser \ JADE Application Server shortcut for the JADE application server.

The following table lists examples of the properties required to run an application server in JADE thin client mode.

Property Example

Command line jadapp.exe appServerPort=1500 server=multiUser path=s:\jade\system ini=s:\jade\system\jade.ini


For more details, see “Invoking an Application Server”, in Chapter 2 of your JADE Thin Client Guide.

Running a Presentation Client in JADE Thin Client Mode The default multiuser installation sets up the JADE MultiUser \ JADE Presentation Client shortcut for the JADE presentation client.

The following table lists examples of the properties required to run a presentation client in JADE thin client mode.

Property Example

Command line D:\JADE\bin\jade.exe app=SortApp schema=SortTest appServer=JadeServer appServerPort=1500

Working directory D:\jade\bin



JADEICG-6.3

If a JADE initialization file is not specified on the command line when you are running an application in thin client mode, JADE attempts to use the jade.ini file in the installation directory of jade.exe (that is, the bin directory) on the presentation client node.

For more details, see “Invoking a JADE Presentation Client”, in Chapter 2 of your JADE Thin Client Guide.

Single User Configuration Before you run JADE in single user mode, ensure that the Server parameter in the [ Jade] section of the JADE initialization file is set to singleUser. Alternatively, you can specify server=SingleUser in the command line.

Running JADE in Single User Mode The default installation sets up the JADE shortcut for a single user mode client. The following table lists examples of the properties required to run the JADE development environment in single user mode.

Property Example

Command line jade.exe path=c:\jade\system ini=c:\jade\system\jade.ini app=Jade server=singleUser

Working directory c:\jade\bin

Running a JADE User Application in Single User Mode The following table lists examples of the properties required to run a user application written in JADE in single user mode.

Property Example

Command line jade.exe path=c:\jade\system ini=c:\jade\system\jade.ini schema=TPC_A app=BenchmarkApp server=SingleUser

Working directory c:\jade\bin

Installing Multiple JADE Initialization Files If you want multiple users to share binary files on your Local Area Network (LAN), install multiple copies of the JADE initialization file. For example, you can install multiple initialization files so that each user has his or her own initialization file.

To install multiple JADE initialization files

1. Copy the JADE initialization file ( jade.ini) into the appropriate user directory.

2. Create a JADE shortcut to meet your requirements, with the ini parameter in the command line specifying the JADE initialization file of the user; for example:

c:\jade\bin\jade.exe ini=c:\current\myjade.ini path=c:\jade\system schema=Faults server=singleUser app=Jade

The working-directory-name is usually the directory in which the JADE executable file ( jade.exe or jadepg) is located but you can specify another start-in directory when you install JADE, if required. The parameters can be in any order but must be specified once only.



JADEICG-6.3

For details about multiple JADE programs on the same host sharing a JADE initialization file, see “Sharing JADE Initialization Files”, in your JADE Initialization File Reference.

Reregistering JADE with a New Licence The JadReg program installed with your JADE software enables you to reregister JADE with new licence information.

For details about automating the registration of a JADE system by running the registration program in batch mode, see “Reregistering a JADE System in Batch Mode”, in Chapter 5.

To reregister JADE

1. In Explorer or File Manager, access the directory in which your JADE binary files are located (for example, c:\ jade\bin) and then double-click the jadreg program.

The Jade Registration Update dialog, shown in the following diagram, is then displayed.

2. In the Database Directory combo box, specify your JADE database directory or select it from the drop-down list. The last system directory that was accessed is displayed by default.

3. If you want to update your licence without stopping the JADE server, enter the name and absolute path of the JADE initialization file in the Ini File text box and then check the Online check box. This enables the jadreg program to obtain multiuser initialization file settings that will allow it to sign on to the JADE Remote Node Access utility ( jadrap).

Wait until the jadreg program has signed on successfully before proceeding to the next step.

Note You must specify the absolute path and name of the JADE initialization file before you check the Online check box.



JADEICG-6.3

You must close down the JADE server before you can update your licence key if you do not specify that you want online registration update.

4. In the Licence Name text box, specify your organization’s licence name (displayed on your Certificate of Authorisation, which may be an e-mail message providing you with your licence name and key).

Note This must be typed correctly (it is case-sensitive), as it is validated against your licence key.

5. In the Licence Key text boxes, specify your licence key for your JADE database.

Enter the licence key exactly as specified on your Certificate of Authorisation. Enter the first eight characters in the first text box, the next eight characters in the second text box, the third eight characters in the third text box, and the last eight characters in the fourth text box. (Ignore the “-” printed on the Certificate of Authorisation.)

6. Server licences are split over the two types of run time operation; that is, standard (fat client) and JADE thin client. You can optionally specify the minimum number of licences reserved for both types of run time operation, if required, by performing the following step.

In the Minimum Usage text boxes, specify the minimum number of runtime licences you want reserved for:

Standard Jade (that is, standard fat client runtime licences)

Thin Jade (that is, JADE thin client runtime licences)

Specify minimum values for both types of runtime licence so that when you run your JADE applications, you can ensure that a specific number of licences are available (reserved) for that type of operation at any time.

Note You cannot specify a minimum number of licences greater than the number of your registered server (run time) licences.

The default value of zero (0) indicates that there is no minimum number of licences for each run time type. (For details about viewing the minimum number of JADE licences that you specify in this dialog and monitoring the number of licences that are available and currently in use, see “Displaying the Licence Information View”, in Chapter 2 of your JADE Monitor User’s Guide.)

7. Click the Update button.

The dialog then displays the following information.

The type of licence is displayed at the bottom of the JADE development environment sign-on screen; that is, an unrestricted primary (Production) licence or a Compact, Enterprise, or Free restricted licence.

A user application developed using an Enterprise or Free restricted licence that is invoked from outside of the JADE development environment displays a splash screen that states that the application is not for production use. The only action that the user can perform is to click anywhere on the splash screen or to press any key to remove the splash screen. A Compact restricted licence can be used only on Windows Mobile devices or the Compact desktop version of JADE.



JADEICG-6.3

The number of developer, process, and secondary database licences for which you are registered at run time.

If your licence is not perpetual, the expiry date of the licence.

If you specified an invalid licence name or licence key, a message box is displayed, advising you of the invalid entry.

8. Click the Close button.

Configuring the JADE JIT Debugger The Just-In-Time ( JIT) debugger enables you reliably acquire a dump and crash log when an exception is raised in a system running with the Microsoft Visual C++ 2005 run time.

For details about installing the JIT debugger, see “Selecting the Installation of the JADE Just-In-Time (JIT) Debugger”, earlier in this chapter.

Note We recommend that you install this on all Windows non-presentation client-only nodes running JADE.

By default, the installation or upgrade process registers and configures the drdanyo.exe program as the just-in-time debugger on your system.

If the installation process detects that Dr. Danyo is installed, Dr. Danyo is first uninstalled. Alternatively, you can use the command line to specify drdanyo –i (to install) or drdanyo –u (to uninstall).

The drdanyo.exe program is a stand-alone Windows console program that has no run time dependencies on other JADE software.

The process dump and crash log are the same as they would have been if they had been performed by the JADE unhandled exception filter. (For details about specifying the directory of crash logs and the process dumps, see the CrashLogDirectory and ProcessDumpDirectory parameters the [FaultHandling] section of the JADE initialization file.)

A drdanyo.log is written to the folder containing the drdanyo.exe program. It records every initiation of Dr Danyo.

____________________________________

JADEICG-6.3

Chapter 2 Compact JADE under Windows CE

____________________________________

This chapter covers the following topics.

Overview

Operational Requirements

Installing Compact JADE on a Desktop Machine

Installing Compact JADE on a Windows Mobile Device

Thin Client Installation

Single User Installation

Configuring Compact JADE

Automatically Upgrading Compact JADE on a Presentation Client

Overview Compact JADE provides the ability to:

Run a JADE thin client on Windows Mobile devices, including Windows-based Personal Digital Assistants (PDAs)

Run a single-user JADE node (including the JADE Object Manager and the database) on Windows Mobile devices

Embed a deployed JADE server-side application in a hardware device (for example, Windows Mobile 6.0 devices) and have this interoperate with other systems via Web services

Compact JADE delivers a specialized JADE node and specialized RootSchema class library that can run on Windows Mobile devices, including PDAs and selected Windows CE devices. The Compact JADE node can host multiple JADE processes. You can build JADE applications for deployment in hardware devices, with those applications being able to store persistent data and interoperate with other systems via Web services.

Note You can run only a deployed JADE application on Compact JADE. The JADE development environment is not supported.

A thin client running on Windows Mobile 5.0 or 6.0 (or in the desktop emulator) can connect to an application server using Secure Sockets Layer (SSL) encryption. HTTPS-based proxy servers, including basic and digest-based authentication to the proxy server, are supported. (The TCP/IP address and port number must be specified in the JADE initialization file. There is no automatic detection of the proxy configuration from the registry.)


Chapter 2 Compact JADE under Windows CE 34

JADEICG-6.3

For a summary of the differences between a standard JADE implementation and a Compact JADE implementation on a PDA device or an emulated version on the desktop, see “Difference between Compact JADE and Standard JADE” and “GUI Differences when Running Compact JADE”, in the JADE Platform Differences Guide.

Operational Requirements The following table lists the operational requirements for a device hosting a Compact JADE node.

Microsoft Windows Mobile Operating Systems To run Compact JADE, your require one of the following Microsoft operating systems.

Windows Mobile 6.0 Professional

Windows Mobile 6.0 Classic

Windows Mobile 5.0 for Pocket PC Phone Edition

Windows Mobile 5.0 for Pocket PC

For details, see the following table.

Windows Mobile Version Underlying Windows CE Version Compact JADE Features

Windows Mobile 6.0 Professional and Classic Windows CE 5.0 Thin client

Single user node

GUI controls

Web service consumer

Serial port access

TCP/IP connectivity

Database recovery

Windows Mobile 5.0 for Pocket PC Phone Edition Windows CE 5.0 Thin client

GUI controls

Serial port access

TCP/IP connectivity

Windows Mobile 5.0 for Pocket PC Windows CE 5.0 Thin client

GUI controls

Serial port access

TCP/IP connectivity



JADEICG-6.3

Writing DLLs that Support External Methods and External Functions If you want to develop external methods or external functions for Compact JADE, you require the following software.

Microsoft Visual Studio 2005 + SP1

To build support DLLs for Windows Mobile 6.0, download Windows Mobile 6 Professional and Standard Software Development Kit refresh (version 6, published 5/1/2007) from http://www.microsoft.com/downloads.

To build support DLLs for Windows Mobile 5.0, download Windows Mobile 5.0 Pocket PC SDK.msi (version 5.0.14343, published October 5, 2005) from http://msdn.microsoft.com.

Specifying a Pre-Load Library List for Compact JADE

The [ JadeEnvironment] section of the JADE initialization file, which is read from the registry at start up of a presentation client or a single user Compact JADE installation, can contain the PreLoadLibraryList parameter; for example:

[JadeEnvironment] PreLoadLibraryList=cmmobile,library2

Use this parameter to specify a comma-separated list of DLLs to be loaded early while jade.exe is loading. This ensures that the DLL is present in memory when your external function call or external method is invoked.

The default value is a blank string. The maximum length of the parameter value is 1,024 characters. Note that the .dll extension is not required.

Hardware Specifications The following subsections summarize the Compact JADE hardware requirements.

Processors For a device hosting Compact JADE:

Thin client, ARM v4 400 MHz (minimum), 600 MHz (recommended), or better

Single user node, ARM v4 600 MHz (minimum), or better

Memory For a device hosting a Compact JADE node, you require 32M bytes (minimum) of memory available to user applications (which usually requires a minimum 64M bytes-capable device).

For a device running JADE thin client only, you require 16M bytes (minimum) of memory available to user applications.

Storage For Compact JADE storage:

This section refers to additional storage space to the memory requirements in the previous section. Typically, this will be a separate Secure Digital (SD) memory card or Compact Flash (CF) card of 256M bytes minimum size.

http://www.microsoft.com/downloads

http://msdn.microsoft.com/



JADEICG-6.3

For JADE thin client applications that have been designed to suit the small device and limit the use of highly complex forms and large graphics, we expect 256M bytes to be sufficient. Additional storage requirements will depend on the size of the presentation client form cache, which is dependent largely on the size and complexity of application forms.

For single user node applications, the additional storage space must allow for the database size, software installation size, transient object storage, and any application external file requirements.

For the best performance, selecting a fast memory card is important (for example, the SanDisk 1 GB Extreme III CF Card), especially for Compact JADE single user node applications.

Other Considerations For Compact JADE:

320 x 240 minimum display resolution is recommended

TCP/IP network environment is required (802.11 b/g protocols are recommended)

Depending on the performance of the cradle that comes with your device (some provide only slow transfer speeds), the use of an external Secure Digital (SD) memory card or Compact Flash (CF) card reader/writer may be desirable for faster file transfers to and from your device

On Windows Mobile devices, JADE is installed into the following for both thin client and single user installations.

\storage-medium\Program Files\Jade\bin

Installing Compact JADE on a Desktop Machine Install the Compact JADE software ( JADEwin32Compact) from the JADE release medium (for example, the ANSI CD-ROM or from the JADE Web site).

The JADE setup executable program contained on the release medium installs the Windows version of Compact JADE and includes files needed for PDA deployment.

Note You should exit from all Windows programs before you install your Compact JADE software.

Click the Next > button when you have specified the required information in each Compact JADE set-up folder.

The folder for the next phase of the installation process is then displayed, if applicable. Use the < Back button to return to earlier set-up folders. To abandon the Compact JADE installation, click the Cancel button in the current set-up folder.

The Windows Compact JADE files include bin (Windows executable and DLL files) and system (database files) subdirectories. A separate subdirectory includes the cab and bin files required for deployment to the Windows Mobile device; that is, armv4i-msoft-wce50 for Windows Mobile 5.0 or armv4i-msoft-wm60 for Windows Mobile 6.0 Professional.



JADEICG-6.3

For single user JADE, the Windows Compact installation is used to load the required schemas into the database system and to test the execution of the user schemas in the Compact JADE environment. You can then deploy the system directory containing the user schemas and the appropriate mobile binary files to the Windows Mobile device.

Initiating the Installation from the JADE Setup Program Before installing Compact JADE, make sure that there are no conflicting applications running. The following instruction is an example of the installation of Compact JADE on Windows from a CD-ROM. Alternatively, you can execute the executable program downloaded from the JADE Web site (that is, www.jadeworld.com).

To initiate the installation of your JADE software

Double-click the JADEwin32Compact.exe program downloaded from the JADE Web site or the CompactCD CD-ROM.

The Microsoft Windows C++ 2005 SP1 Redistributable Package (x86) is installed.

Note This package is required on all Windows systems that run JADE 6.3.

The installation of your Compact JADE software is then started and the initialization progress is displayed in the Setup progress dialog.

JADE Software Installation Process During the installation process, the Compact JADE set-up program performs the events described in the following subsections.

Displaying the Welcome Dialog The Compact JADE set-up program first displays the Welcome folder.

Accepting the Terms of the JADE License Agreement The Software License Agreement folder is then displayed. Use the scroll bar or the PAGE DOWN key to scroll through and read the entire software license agreement.

When you have read the entire software license agreement and you accept the specified terms, click the Yes button to continue the installation. (You cannot install Compact JADE until you accept these license agreement terms.) Alternatively, click the No button to close the Compact JADE set-up process.

Selecting the Type of Installation The Installation Type folder is then displayed, to enable you to select the type of installation that you require. The types of installation that you can select are:

Fresh Copy, which is selected by default, and installs a brand new copy of Compact JADE.

Feature Upgrade, which you can select if you want to upgrade an existing Compact JADE database and binary files. For details, see the ReleaseInfo.pdf file on your Compact JADE release medium.

http://www.jadeworld.com/



JADEICG-6.3

Selecting the Type of Set Up The Setup Type folder is then displayed, to enable you to select the type of set up that you require.

The types of set up that you can select are listed in the following table.

Type Installs…

Single User Binary, database, documentation, and general support files required to run single user Compact JADE on a Windows desktop and Windows Mobile devices

Presentation Client Binary and general support files required to run the presentation client on a Windows Mobile device

By default, the Single User option is selected.

Specifying Your User Information If you are installing single user Compact JADE, the User Information folder enables you to specify the Licence Name (that is, your organization name, which is not to be confused with your company name that is displayed in large letters above the licence name and key) and your Licence Key specified on your licence for your Compact JADE database.

An entry is required in both the Licence Name and Licence Key text boxes.

Notes To obtain your licence key, contact your authorized reseller or send an e-mail message to [email protected].

The licence key has four text boxes. Enter the licence key exactly as it is specified on your Certificate of Authorisation (which may be an e-mail message providing you with your licence name and key). Enter the first eight characters in the first text box, the next eight characters in the second text box, the next eight characters in the third text box, and the last eight characters in the fourth text box. (Ignore the “-” printed on the licence.)

Ensure that you type the licence name of your organization (which is case-sensitive) correctly, as this is validated against your licence key.

Selecting the Destination Directory The Select Destination Directory folder is then displayed, to enable you to select the path and directory in which your Compact JADE files are installed on the desktop machine. By default, the selected files are installed in subdirectories in the Jade63 directory on your c: drive.

To select a destination directory

Click the Browse button.

The common File dialog is then displayed, to enable you to specify the destination directory for your Compact JADE files.

Selecting the Installation of the JADE Just-In-Time (JIT) Debugger If you are installing single user Compact JADE, the JADE JIT Debugger folder is then displayed, to enable you to uncheck the Install JADE JIT Debugger check box if you do not want the JADE JIT ( Just-In-Time) Debugger installed on the desktop machine. (This debugger remains on the desktop machine, and is not copied to the Windows Mobile device as part of that phase of the installation.)



JADEICG-6.3

The JIT Debugger enables you to reliably acquire a dump and crash log when an exception occurs in a system running with the Microsoft Visual C++ 2005 run time.

By default, the JIT Debugger is installed on the desktop machine (that is, the Install JADE JIT Debugger check box is checked).

Note We recommend that you install this on all Windows machines running JADE.

Running the Installation Program The Start Copying Files folder is then displayed. This dialog displays the installation options that you have selected. Review your selections and then click the Next > button, to start copying files.

Informing You When the Installation is Complete When the installation is complete, the Compact JADE set-up program informs you that the Compact JADE set-up program was successfully completed and you can now view the ReadMe.txt file. To view the ReadMe.txt file, ensure that the check box is checked (the default).

The ReadMe.txt file, which refers you to the document covering migrating to JADE release 6.3, the changes and new features in this release, and to other documents relating to JADE release 6.3, is then displayed in a text editor (for example, Notepad).

The ReadMe.txt file is a read-only text file installed in your JADE documentation directory that you can print or delete, if required.

Click the Finish button to end the Compact JADE installation process.

Installing Compact JADE on a Windows Mobile Device Compact JADE on Windows Mobile devices does not use JADE initialization files. For details about configuring JADE on a Windows Mobile device, see “Configuring Compact JADE”, later in this chapter.

Thin Client Installation The included jadethinclient.cab file contains the necessary files to run JADE in thin client mode on a Windows Mobile device.

To install Compact JADE for thin client mode

1. Copy the appropriate version of the jadethinclient.cab file to the Windows Mobile device.

2. Click on the cab file to install the thin client.

3. Enter the required start-up information in the Startup sheet of the Configure Compact Jade dialog. (For details, see “Configuring Compact JADE”, later in this chapter.)

For details about the Compact JADE thin client download Control Panel applet (cpl) files that are included in the files downloaded from the application server by the thin client automatic download process and copied into the Windows Mobile device \Windows directory, see “Download File Types”, in Appendix B of the JADE Thin Client Guide.

The icon defined for a file of type .cpl in the \Windows directory appears in the System folder of the Settings menu of a Windows Mobile device.



JADEICG-6.3

Compact JADE includes the file jadeconfig.cpl, which enables the Compact JADE thin client and single user execution configurations to be established.

Single User Installation You cannot override the default SplashScreenFile configuration parameter in single user mode; that is, the default splash screen is always displayed when you run a Compact JADE application in this mode.

To install single user Compact JADE on a Windows Mobile device

1. Install the files manually.

2. On the Windows Mobile device memory card, create a JADE directory with bin and system subdirectories.

Caution We advise that you should not copy the JADE binary and database files to the main memory of the Windows Mobile device because there will be insufficient memory left to run Compact JADE.

3. Copy into the bin directory that you created in the previous step all of the bin\*.bin files from the desktop machine.

4. Copy into the bin directory that you created in step 2 of this instruction all of the mobile\armv4i-msoft-wce50\bin\*.* or mobile\armv4i-msoft-wm60\bin\*.* files from the desktop machine.

5. Copy into the system directory that you created in step 2 of this instruction all of the system\*.dat files from the desktop machine.

6. Copy the jadeconfig.cpl file to the to the \Windows directory on the Windows Mobile device.

To install single user Compact JADE on a Windows Mobile

1. Copy the single user jadesingleuser.cab file to the Windows Mobile device.

2. Click on the cab file to install single user Compact JADE.

3. Enter the required start-up information in the Startup sheet of the Configure Compact Jade dialog. (For details, see “Configuring Compact JADE”, later in this chapter.)

Caution We advise that you should not copy the JADE binary and database files to the main memory of the Windows Mobile device because there will be insufficient memory left to run Compact JADE.

4. Copy into the system directory that you created in step 3 of this instruction all of the system\*.dat files from the desktop machine.

5. Copy the jadeconfig.cpl file to the to the \Windows directory on the Windows Mobile 5.0 or Windows Mobile 6.0 device.



JADEICG-6.3

Configuring Compact JADE Compact JADE can be run in one of the following configurations.

Thin client on Windows Mobile devices.

Single user JADE node (including the JADE Object Manager and the database) on Windows Mobile devices.

For details about accessing JADE applications from IIS or the Apache HTTP Server, see “Connecting to JADE Applications from Internet Information Server (IIS)” or “Connecting to JADE Applications from an Apache HTTP Server”, in Chapter 5.

The Compact JADE control panel configuration program jadeconfig.cpl enables you to:

Configure the initiation settings for the JADE application to be run on a Windows Mobile device (for example, a PDA).

Modify JADE initialization settings for the Windows Mobile device.

The Compact JADE installation process automatically installs this file in the \Windows directory.

When the file is located in the \Windows directory of the Windows Mobile device, the JADE icon is displayed with a caption of Compact Jade in the System folder of the Settings menu of the Windows Mobile device.

Notes The thin client download install program automatically copies any downloaded .cpl files into the \Windows directory.

Click the Compact Jade icon in the System folder, to display the Startup sheet of the Configure Compact Jade dialog, shown in the following diagram.

To define your Compact JADE start-up options

1. If you want to initiate a JADE in single user application rather than a default JADE thin client application, click the Single User option button.

2. In the Schema text box, specify the name of the schema that you want to invoke.



JADEICG-6.3

3. In the App text box, specify the name of the application that you want to initiate.

4. If you clicked the Single User option button in step 1 of this instruction, in the DB Path text box, specify the absolute path of the database.

5. In the default thin client initiation mode, in the A/S Host text box, specify the application server host address.

6. In the default thin client initiation mode, in the A/S Port text box, specify the application server port number.

7. Click the Ini File Options tab at the lower left of the dialog, to display the Ini File Options sheet, shown in the following diagram.

The Ini File Options sheet enables you to view and modify JADE initialization options stored in the Windows registry.

The Named combo box currently contains only the name of the CompactJade registry entry that holds all of the JADE initialization sections, and this value cannot be changed. (It is included for possible future enhancement.)

8. In the Section combo box, select the section name that you require from the list of all defined sections in the JADE initialization CompactJade registry section.

If the selected section has no defined parameters (keys), the Delete Key button is displayed as the Delete Section button, enabling you to delete the selected JADE initialization section.

9. In the Key combo box, select the parameter that you require from the list of all of the parameters defined within the JADE initialization section selected in the previous step.

10. In the Value text box, modify the displayed value of the selected parameter to meet your requirements.

11. To add a new JADE initialization section, click the Add Section button. This button is enabled only if the name displayed in the Section combo box in step 8 of this instruction has been modified so that it does not match the name of an existing JADE initialization section.



JADEICG-6.3

12. Click the Update Value button to set the value of the selected parameter to the contents of the Value text box or to create a new parameter with the value specified in the Value text box if the value displayed in the Key combo box has also been modified so that it does not match the names of an existing parameter in the JADE initialization section displayed in the Section combo box.

13. Click the Delete Key, to delete the parameter currently selected in the Key combo box.

14. Click OK button at the top right of the dialog to save any changes made to these controls and to close the program.

Note The changes made using this dialog are immediate, and are saved independent of clicking the OK button.

Running Compact JADE in JADE Thin Client or Single User Mode Execute jade.exe from the installed directory.

The command line and JADE initialization file settings are read from the registry on a presentation client or a single user JADE node. For more details, see “Invoking a JADE Presentation Client”, in Chapter 2 of your JADE Thin Client Guide.

As you cannot override the default SplashScreenFile configuration parameter in single user mode, the default splash screen is always displayed when you run a Compact JADE application in that mode. (You can change the splash screen when the application is run in JADE thin client mode.)

Automatically Upgrading the Compact JADE Thin Client In addition to the download directory file names and corresponding JADE initialization file sections documented under “Upgrading Software on Presentation Clients”, in Appendix B of your JADE Thin Client Guide (for example, the existing [i686-msoft-win32-unicode]), the following directory file and section names are required for Compact JADE.

[armv4-msoft-wm60-unicode]

[armv4i-msoft-wince50-unicode]

____________________________________

JADEICG-6.3

Chapter 3 JADE under SUSE Linux Enterprise Server on Intel

____________________________________ This chapter covers the following tops.

Overview

SUSE Linux Enterprise Server Installation on Intel Servers

Overview of Installing JADE on Linux

JADE Operational Requirements on Linux on Intel

– SUSE Linux Enterprise Server Hardware Requirements for Intel

– SUSE Linux Enterprise Server Software Requirements for Intel

JADE Product and RPM Names for SUSE Linux on Intel

– Port Numbers for Linux on Intel

Installing JADE

– Parameters for the jadeinstall Command

– Starting and Stopping the JADE System

– Registering the Database

– Setting Up the Windows Client

Upgrading a JADE Release

Deinstalling JADE

Obtaining a Core Dump

Detailed Command Information for SUSE Linux on Intel

Environment Variables

JADE Daemon (jaded)

JADE Portable GUI (jadepg)

Running an Application Server

Running a Non-GUI Client Application

Java Framework

Locales and Translatable Messages


Chapter 3 JADE under SUSE Linux Enterprise Server on Intel 45

JADEICG-6.3

Overview This chapter gives an overview of JADE under SUSE Linux Enterprise Server on Intel, including:

Installing JADE for the first time

Performing upgrades

Running the supplied commands

JADE server nodes, JADE thin client mode application servers, and JADE client nodes can be run on SUSE Linux Enterprise Server (SLES) on Intel hardware.

In this chapter, the term:

UNIX generally refers to Linux.

The usage of Linux differentiates features that are available only on Linux, whereas UNIX is used where the feature is generally available to most versions of UNIX.

RPM relates to the Linux installable file package (that is, Red Hat Package Manager).

subsystem is equivalent to the following terms.

Server, JADE database, or application

UNIX daemon

Windows 2003 Server, Windows Vista, Windows XP, or Windows 2000 service

Notes On Linux, use the command line versions of administrative programs (for example, the JADE Database or the JADE Remote Node Access utility).

The size of a Unicode character used by JADE is 4 bytes on Linux. Unicode characters in strings are stored as logical lengths rather than physical lengths.

When running a JADE command on UNIX (for example, jadappb or jaded), you can run the corresponding supplied shell script (for example, jadappb.sh or jaded.sh) so that your environment variables are set up for you.

Your JADE applications are developed independently of the targeted server operating environment. You are therefore sheltered to a significant degree from many platform-specific details like operating system services, data representations, character sets, and error messages.

For details about the differences when running JADE applications on a server under UNIX and the Microsoft Windows operating systems, see “Differences When Running JADE Applications on a Server under UNIX”, in Chapter 1 of your JADE Platform Differences Guide.

The portation to UNIX consists of JADE server code only, as follows.

The JADE kernel

External methods

Compiler methods and functions

The compiler

The interpreter



JADEICG-6.3

The database server

The application server

The non-GUI client

The portable GUI client

The command line utility tools

For details about other terms, see “Glossary”, in Appendix A of your JADE Development Environment User’s Guide.

SUSE Linux Enterprise Server Installation on Intel Servers This section provides you with the steps required to install and configure JADE under SUSE Linux Enterprise Server on an Intel server. If you want more information about commands and their parameters, see “Detailed Command Information for SUSE Linux on Intel”, later in this chapter.

Notes For users wishing to develop their own installation process, the steps are as executed in the pre_i and post_i scripts in the bin directory in the /opt/jade subdirectory for the release.

For details about the location of directories, see “Directory Locations”, in Chapter 5.

Overview of Installing JADE on Linux JADE uses the underlying Linux installation tools to install JADE software. From the JADE perspective, the RPM install mechanism has a serious limitation, which is that a specific UNIX product can be installed only in a fixed location (which is decided by the product developer; that is, by the JADE Development Centre) and that multiple versions cannot be installed (because of the fixed location issue).

To overcome this limitation, the JADE install process has been enhanced as follows.

The JADE product is made up of several Linux RPMs, which are the smallest installable units.

The initial RPM install copies the files from the release medium into the /opt/jade directory.

The RPM stores details about installed files and data.

The jadeinstall program uses command line options to control where it installs a working copy of JADE.

The general sequence of actions for installing JADE on Linux is as follows.

Install the required JADE Red Hat Package Manager (RPM) file directly by using the standard Linux RPM install tools. This puts the files in the /opt/jade directory.

To install one or more copies of JADE, perform the following action.

Execute the jadeinstall program, indicating where you want the software to be installed and other customizations that you require.

The install process automatically selects port numbers and configures subsystems, so that the database and an application server are ready to be started.



JADEICG-6.3

JADE Operational Requirements on Linux on Intel This section covers the hardware and software required to run JADE on an Intel server under SUSE Linux Enterprise Server.

Notes These specifications represent minimum configurations. Configurations that are more powerful may be advisable, depending on the size of the development being undertaken, the scale of your JADE applications, and the performance requirements of your system. Although minimum Service Pack (SP) levels are specified, we recommend that you keep up-to-date with Service Packs and security updates for the operating system that you are running.

Where an operating system provides both 32-bit and 64-bit editions, both are supported.


SUSE Linux Enterprise Server Hardware Requirements for Intel Depending on the size and configuration of your SUSE Linux Enterprise Server installation, JADE server nodes can be configured on one or many Intel servers.

Different JADE applications can run on separate Intel servers, accessed by JADE clients.

Caution Each device on which JADE runs should have error-correcting memory.

Minimum Hardware Requirements for a JADE Database Server

The following subsections contain the recommended minimum hardware required to deploy JADE on a machine that hosts a JADE database server.

Processors




Memory



Storage






JADEICG-6.3



Other





Minimum Hardware Requirements for an Application Server

The following subsections contain the recommended minimum hardware required to deploy JADE on machines hosting an application server.

Processors




Memory



Storage


Other





Minimum Hardware Requirements for Standard Clients

The following subsections contain the recommended minimum hardware required to deploy JADE on standard clients.




JADEICG-6.3

Processors

For a standard clients, you require an Intel CPU (Pentium, AMD, or compatible), 1 GHz or faster.

Memory



Storage


Other




Minimum Hardware Requirements for Running JADE Presentation Clients

The following subsections contain the recommended minimum hardware required to deploy JADE on a presentation (or thin) client node.

Processors


Memory


Storage


Other







JADEICG-6.3

SUSE Linux Enterprise Server Software Requirements for Intel JADE 6.3 has been compiled on SUSE Linux Enterprise Server environments using the GNU Compiler Collection 4.1.2 (shipped with SUSE Linux Enterprise Desktop 10).

The minimum level of software required for SUSE Linux Enterprise Server 10 (SLES 10) on an Intel server is as follows.

kernel-2.6.16 or later.

glibc-2.4.31 or later.

openssl-0.9.8a.

libacl-2.2.41.

libattr-2.4.34.

libgcc-4.1.2.

libstdc++-4.1.2.

zlib-1.2.3.

cups-1.1.23.

Optional Apache2 HTTP Server version 2.2.3 for SUSE Linux. (For details, see “Connecting to JADE Applications from an Apache HTTP Server” and “Configuring Apache for Remote Connections”, in Chapter 5.)

Apache 2.2.3 is the default 32-bit and 64-bit version installed on SLES10.


Optional unixODBC version 2.2.11 (if you are using external databases or the JADE ODBC driver). For details, see “Configuring a JADE ODBC Driver”, in Chapter 6 of the JADE Developer's Reference.

Optional gcc-4.1.2 or gcc-c++-4.1.2 (if you are developing user libraries for use with JADE).

Optional expat-2.0 (if you are using external databases or the JADE XML parser).

Optionally, to allow the built-in JADE development environment help to work, you must install one of the following packages.

xpdf (the default)

acroread

evince version 0.4.0, which displays PDF hyperlinks but does nothing with them

For details, see “JADE Online Help”, in Chapter 2 of your JADE Development Environment User's Guide.

To deploy a JADE thin client or standard (fat) client on any compatible Java-capable desktop, you require the:




JADEICG-6.3

For details about specifying the Java home directory in which this software is installed on each standard (fat) client or presentation client node in a JADE portable GUI environment, see “JADE Portable GUI Java Section [ JadeJava]”, in your JADE Initialization File Reference.


For 32-bit JADE clients, the native or the cross-platform version of JMF can be used. For the 64-bit version of JADE, the Java Media Framework ( JMF) library must be the portable version (that is, all Java code and no .so files), not the i386 version.

Although you can download the Linux Intel or All Java version of these software packages, the Linux Intel version provides improved performance.


To deploy a Java framework, you require the:


Notes If the Java Virtual machine is not available on the Linux distribution release medium, you can download the Java installation (software package) from the Sun Microsystems Java Web site http://java.sun.com/ or the IBM Web site http://www.ibm.com/developerworks/java/. Download the Java Media Framework ( JMF) 2.1.1e software package from the Sun Microsystems Java Web site http://java.sun.com/.

JADE encodes Unicode characters using the wide-character encoding routines provided by UNIX.

When accessing a JADE application from the Internet (World Wide Web), your JADE application and Microsoft Internet Information Server (IIS) or Apache HyperText Transfer Protocol (HTTP) Server must reside on the same workstation if you are using a named pipe connection. (When using a TCP/IP connection, the machine hosting IIS or Apache HTTP Server can be different from the machine that is running the JADE application, to provide greater security via firewalls.)

If using Postscript printing, your printer must support Postscript level 2 or greater.

JADE Product and RPM Names for SUSE Linux on Intel The following is the JADE software required for Linux multiuser LAN-based development or applications usage when running 32-bit JADE on Intel.

JADE-6.3.nn.nnn-suse-linux-ansi.i686-1.rpm (must be installed)

JADE-6.3.nn.nnn- suse-linux-ansi-rte.i686-1.rpm (must be installed)

JADE-6.3.nn.nnn-suse-linux-ansi-devdata.i686-1.rpm (must be installed)

JADE-6.3.nn.nnn-suse-linux-ansi-devel.i686-1.rpm (installed for C++ development)

JADE-6.3.nn.nnn-suse-linux-ansi-docs.i686-1.rpm (optional)

JADE-6.3.nn.nnn-suse-linux-ansi-examples.i686-1.rpm (optional)

JADE-6.3.nn.nnn-microsoft-win32-ansi.noarch-1.rpm (optionally installed if Windows thin client downloads are required)






JADEICG-6.3

JADE-6.3.nn.nnn-microsoft-win32-ansi-thinclient.noarch-1.rpm (optionally installed if Windows thin client downloads are required)

JADE-6.3.nn.nnn-suse-linux-ansi-thinclient.i686-1.rpm (optionally installed if SUSE Linux ANSI thin client downloads are required)

Notes The nn.nnn values in the JADE-6.3.nn.nnn version require leading zeros (for example, 6.3.12.001).

For the 64-bit version of JADE, the i686 portion of the above 32-bit JADE software is replaced by x86-64 (for example, JADE-6.3.nn.nnn-suse-linux-ansi.x86-64-1.rpm).

The JADE package contains the Red Hat Package Manager (RPM) units (individually installable groups of files) listed in the following table.

RPM Description Dependent on…

<linuxansi> JADE install tools Requirement level of operating system

rte JADE binaries (run time) base and all operating system software listed earlier in this section

devdata JADE database rte

docs JADE messages and documentation rte

devel JADE application development tool kit rte

examples JADE example schemas rte

<win32ansi> Parent RPM of "JADE Windows thin client"

thinclient JADE Windows thin client binaries rte

In addition to the ANSI software listed under “SUSE Linux Enterprise Server Software Requirements for Intel”, in the previous section, there is also a Unicode version of these RPMs; for example:

JADE-6.3.12.001-suse-linux-unicode-docs.i686-1.rpm

The –ansi– portion of the RPM name is changed to –unicode–.

Port Numbers for Linux on Intel Each JADE database and application server running on a host must have a unique TCP/IP port number. The installation process automatically searches for the two available TCP/IP port numbers greater than 50,000, assigning the first to the database server and the second to the application server.

If you want to assign a specific port number, edit the /etc/services file and create the entries that you require before installing JADE; for example:

"jade 6005/tcp jade-db" "jade-app1 6006/tcp jade-6006"

The installation process uses any value that already exists. You can change the port number or local port number in the /etc/services file after the installation. If you change it, you must make the corresponding change in your JADE initialization files on the JADE client nodes.

The installation process automatically updates the ServerNodeSpecifications parameter in the [ JadeClient] section and the NetworkSpecification parameter in the [ JadeServer] section of the JADE initialization file ( jade.ini) for each database.



JADEICG-6.3

Installing JADE

To install JADE on an Intel server running under SUSE Linux Enterprise Server

1. As root, install the rpm files using rpm commands to meet your requirements, as shown in the following example.

mount /mnt/cdrom cd /mnt/cdrom/RPMS rpm -ivh *.rpm-file-name cd / eject cdrom

Files are installed into the following directories.

/opt/jade/sbin /opt/jade/images/6.3.version-number.patch-number/bin : install scripts /opt/jade/images/6.3.version-number.patch-number/i686-suse-linux/ansi /opt/jade/images/6.3.version-number.patch-number/ i686-microsoft-win32/ansi

Each JADE version installed using rpm is put into a separate /opt/jade/images subdirectory. For example, the next release of JADE 6.3 version 12 patch 044 (that is, 6.3.12.044 may be as follows.

/opt/jade/images/6.3.12.044/i686-suse-linux/ansi

No updates are done using rpm.

When you install JADE, a user jade and group jade are created if they do not exist.

Caution If you are installing JADE on an Intel server that uses a centrally managed user management system, you should create the jade user and jade group on the master node and then propagate out the details to the installation node before the installation takes place.

2. To install the JADE executables, library files, and database into the appropriate directories, run the jadeinstall command as root, as follows.

/opt/jade/sbin jadeinstall [--help] -i | --installDir= -v | --version= [-u | --usercode=] [-g | --group=] [-s | --serviceName=] [-n] [-k] [-f] [-t | --targetType] [-q | --quiet] [-j | --jadeHome=] [-U | --Upgrade] [--all] [--rte] [--devdata] [--devel] [--docs] [--examples] [--thinclient] [--w32thinclient]



JADEICG-6.3

The parameters for the jadeinstall command, described under “Parameters for the jadeinstall Command” in the following section, are listed in the following table.

Short Format Long Format Description

[--help] Displays help information

-i --installDir= Target installation directory for the JADE system (mandatory)

-v --version= JADE version to be installed (mandatory)

[-u] [--usercode=] User code for JADE files (which defaults to jade)

[-g] [--group=] Group for JADE files (which defaults to jade)

[-s] [--serviceName=] Service name defined in /etc/services (which defaults to JADE)

[-n] JADE registration name (if defined, the database is registered)

[-k] JADE registration key (if defined, the database is registered)

[-f] [--force] Forces the overwrite of existing files (which defaults to no overwriting)

[-t] [--targetType=] Specifies a non-default target type

[-q] [--quiet] Quiet mode (which defaults to status/error messages output)

[-j] [--jadeHome=] Location of rte installation for executables (if not the same as the –i | --installDir= value)

[-U] [--Upgrade] Upgrades the currently installed version

[--all] Installs all available components

[--rte] Installs JADE Runtime files

[--devdata] Installs the JADE database

[--devel] Installs JADE devel files

[--docs] Installs JADE documentation

[--examples] Installs JADE example files

[--thinclient] Installs JADE SUSE Linux Enterprise Server thinclient files

[--w32thinclient] Installs JADE Windows thinclient files

The short format parameter, indicated by a single dash, is separated from its value by a space. The long format parameter, indicated by a double dash, is separated by its value only by the equals sign (=), and no space separation is permitted between the parameter and its value. In addition, nn.nnn values in the JADE version require leading zeros. For example, run the following command to install the rte, devdata, and thinclient packages into the /home/myjade directory.

/opt/jade/sbin jadeinstall --installDir=/home/myjade --version=6.3.12.001 -n "My Company Ltd." -k 98765432-10123456-78909876-54321012 --rte --devdata --targetType=i686-suse-linux-ansi --thinclient

For each selected package, the jadeinstall command performs the following actions.

1. Runs the pre-installation script, if it is present

2. Copies the required files from the /opt/jade/images directory to your specified target installation directory

3. Sets the ownership and permissions that you specified

4. Runs the post-installation script, if it is present



JADEICG-6.3

Parameters for the jadeinstall Command This section contains the parameters for the jadeinstall command that installs the JADE executables, library files, and database as root into the appropriate directories. For details, see “Installing JADE”, in the previous section.

[--help]

The optional --help parameter enables you to specify that help information about the jadeinstall command is displayed.

-i | --installDir=

The –i or --installDir= parameter specifies the target installation directory for the JADE system running under Linux. You must specify this parameter, which must be a valid directory path.

-v | --version=

The –v or --version= parameter specifies the JADE version to be installed.

You must specify this parameter, which must be a valid installed JADE version (that is, /opt/jade/images/version-number).

[-u | --usercode=]

The optional –u or --usercode= parameter specifies the user code for JADE files. This value defaults to jade.

[-g | --group=]

The optional –g or --group= parameter specifies the group for JADE files. This value defaults to jade.

[-s | --serviceName=]

The optional –s or --serviceName= parameter specifies the service name defined in /etc/services.

This value defaults to JADE.

[-n]

The optional –n parameter specifies your registered licence name (displayed on your Certificate of Authorisation, which may be an e-mail message providing you with your licence name and key), if the database is to be registered.

You must specify your licence name (enclosed in double quote characters if spaces are included) if it has changed. This name must be typed correctly (it is case-sensitive), as it is validated against your licence key. If you do not specify the licence name, the program assumes that the name is unchanged and uses the existing licence name or it leaves the database unlicensed.

[-k]

The optional –k parameter specifies the JADE licence key, if the database is registered. Enter the licence key exactly as it is specified on your Certificate of Authorisation, but without spaces. (You can enter or omit the quotation marks ('') printed on the Certificate of Authorisation.)



JADEICG-6.3

[-f | --force]

The optional –f or --force parameter forces the overwriting of existing files. By default, existing files are not overwritten.

[-t | --targetType=]

The optional –t or --targetType= parameter specifies the non-default target type to use. For example, specify the non-default target type as follows.

--targetType=i686-suse-linux-ansi

This value defaults to i686-suse-linux-ansi for SUSE.

[-q | --quiet]

The optional –q or --quiet parameter specifies quiet mode (that is, status and error messages are not output. By default, status and error messages are output.

[-j | --jadeHome=]

The optional –j or --jadeHome= parameter specifies the location of the run time executable files (specified in the optional --rte parameter) for installation if it is not the same as the value of the -i or --installDir= parameter.

[-U | --Upgrade]

The optional –U or --Upgrade parameter specifies that the currently installed JADE version is upgraded. For more details, see “Upgrading a JADE Release”, later in this chapter.

[--all]

The optional --all parameter installs all available JADE components (that is, JADE Runtime, JADE DEVELOPMENT, JADE devel, JADE thinclient, and JADE documentation databases and files).

[--rte]

The optional --rte parameter installs the JADE Runtime files.

[--devdata]

The optional --devdata parameter installs the JADE DEVELOPMENT database.

[--devel]

The optional --devel parameter installs the JADE devel files (that is, the JADE application development tool kit, which contains examples and C++ header files).

[--docs]

The optional --docs parameter installs the JADE documentation files.

[--examples]

The optional –examples parameter installs the JADE examples files.

[--thinclient]

The optional --thinclient parameter installs the JADE SUSE Linux Enterprise Server thinclient files, for the JADE thin client automatic download.



JADEICG-6.3

[--w32thinclient]

The optional –w32thinclient parameter installs the JADE Windows thinclient files, for the JADE thin client automatic download.

Starting and Stopping the JADE System You can set the RunAsService parameter in the [ JadeServer], [ JadeAppServer], or [NonGuiClient] section of the JADE initialization file to true if you want the node automatically placed in the background and detached from the controlling terminal.

Although this parameter is set to false by default, it is normally set to true when running JADE nodes as services on Linux.

To start a JADE Linux server, perform one of the following actions

Ensure that the environment variables are set up correctly (for details, see “Required Environment Variables”, later in this chapter) and then start the default JADE server by typing the following.

jaded ini=/home/initialization-file-path path=database-path

Run the supplied jaded.sh shell script, which sets up all required environment variables for you, by typing the following.

jaded.sh ini=/home/initialization-file-path path=database-path

Path names with no leading slash character are pre-pended by the JADE HOME directory. In the following examples, the JADE HOME directory is assumed to be /jade.

Path Specified in the Command Line Actual Path

path=/jade63/system /jade63/system

path=system /jade/system

To stop a JADE Linux server

1. Change the directory to the JADE install directory.

2. Type the following, to stop the default JADE server.

kill –TERM -$(< tmp/node-name.pid)

Registering the Database for SUSE Linux on Intel Before you can run JADE on the Linux server, you must register the database (if you do not do so during the installation process). See also “Reregistering a JADE System in Batch Mode”, in Chapter 5.

To register the JADE database




JADEICG-6.3

2. Type the following.

export LD_LIBRARY_PATH=`pwd`/lib:$ LD_LIBRARY_PATH:/usr/lib

export NLSPATH=`pwd`/lib/nls/msg/%L/%N.cat:$NLSPATH

bin/jadregb ini=jade.ini path=system name='licence-name' key=00000000000000000000000000000000

Alternatively, if you define the JADE_REGNAME and JADE_REGKEY environment variables before you install JADE, the database is automatically registered as part of the installation process.

Setting Up the Windows Client After you have installed JADE on a server node running under Linux, you must then set up the client node with the appropriate information, as follows.

1. Enter the host name or IP number in the second part of the ServerNodeSpecifications parameter in the [ JadeClient] section of the JADE initialization file ( jade.ini) on the Windows client node. Alternatively, you can specify the server host name or IP number in the host parameter in the command line on the client node running under Windows.

2. Specify your port number in the third part of the ServerNodeSpecifications parameter in the [ JadeClient] section of the JADE initialization file ( jade.ini) on the Windows client node. For example:

ServerNodeSpecifications=tcpip,RH9node,devjade-sds

Alternatively, you can specify the port number in the port parameter in the command line on the client node running under Windows.


To upgrade from an existing JADE release to a new JADE release

1. Ensure that your JADE systems and data have been fully backed up.

Caution As with any upgrade, the database should not be in recovery state and you should perform a full and verified backup of the binaries and database before you upgrade.

2. Read any specific upgrade documentation before you proceed.

3. To upgrade your JADE installation to the new JADE release, use the jadeinstall –U or --Upgrade parameter, as shown in the following example.

/opt/jade/sbin/jadeinstall -i /home/jade -U -v 6.3.14.000 --all

The parameter values are as follows.

-i <dir> is the previously installed JADE directory

-v <version> is the new JADE version to be installed

--all indicates that all components previously installed into the directory specified in the -i parameter will be upgraded

The upgrade process copies over the new binaries and required system map files, resets timestamps, and performs any other steps necessary to complete the upgrade.



JADEICG-6.3

Caution As with any major JADE release, you must recompile any external method libraries with the new JADE release \include and \lib files before you attempt to run your upgraded JADE systems.

For more details, see “Installing JADE” and “Parameters for the jadeinstall Command”, earlier in this chapter. See also “Upgrading to JADE 6.3 from a Linux JADE 6.2.12 Release or Higher”, in the ReleaseInfo.pdf file on your JADE release medium.

Deinstalling JADE

To remove a JADE system installed using the jadeinstall program by deleting the files

Use the rm (remove) command, as follows.

rm –rf installation–directory

For example, the following command removes the myJade63 directory.

rm –rf myJade63

To remove a specific version of JADE that you installed using the rpm command

Use the rpm –e (that is, erase) short format, as follows.

rpm –e JADE-package-name

For details, see “Displaying the Packages Associated with a Specific JADE Version”, in the following subsection.

Alternatively, use the rpm –uninstall long format, as follows.

rpm --uninstall JADE-package-name

For example, the following command removes the rte JADE binaries for run time.

rpm --uninstall JADE-6.3.14.011--suse-linux-ansi-rte.i686-1.rpm

For more details, see “JADE Product and RPM Names for SUSE Linux on Intel”, earlier in this chapter.

Displaying the Packages Associated with a Specific JADE Version

To display the list of packages associated with a specific JADE version

Use the rpm query command to get a list of the package names associated with the JADE version, as follows.

rpm –qa --queryformat '%{name}\n'|grep JADE-version

For example, the following command displays the packages for JADE 6.3.14.008.

rpm –qa --queryformat '%{name}\n'|grep JADE-6.3.14.008



JADEICG-6.3


To obtain a core dump on Linux

1. For the user from which the process was initiated, check that the core file size ulimit setting is set to unlimited. (ulimit -a displays the current settings.)

To set ulimit for the core file size:

ulimit -c unlimited

2. Obtain the pid for the process that is to be dumped (see jadehome/tmp/program.pid).

3. From the jadehome directory, attach gdb to the process, dump the core file, and then detach the following from the process.

gdb --pid=pid (gdb) generate-core-file (gdb) detach (gdb) quit

The core file will be named core.pid.

Detailed Command Information for SUSE Linux on Intel This section provides you with details about the commands and parameters that enable you to tailor the installation and configuration of JADE on UNIX.

Note You can use supplied shell scripts for JADE commands (for example, jadappb.sh or jaded.sh) so that your environment variables are set up for you.

If you want you want to install and configure JADE using the default values or you require information about the operational requirements, see “Installing JADE”, earlier in this chapter.

Environment Variables The environment variables in the following subsections apply to all JADE executable programs; for example, when running a non-GUI client using jadclient or when loading a schema and forms using jadloadb.

Required Environment Variables JADE executable programs (for example, jaded) expect and use the UNIX environment variables described in the following sections. The standard JADE installation process sets these variables automatically, under the control of the RPM.

JADEHOME

The JADEHOME environment variable is the directory in which JADE has been installed. As a minimum below this directory, there are the bin and lib subdirectories and often the system directory. This variable defaults to /opt/jade if it is not set. (See also “Directory Locations”, in Chapter 5.)



JADEICG-6.3

To set this variable in the Korn and Bourne shells:

JADEHOME=/home/wilbur1/jade; export JADEHOME

To set this variable in the csh:

setenv JADEHOME /home/wilbur1/jade

LANG

The LANG environment variable indicates the language and locale conventions that you want to use.

Note This variable, if set, cannot have .UTF-8 appended to the language.

Setting this variable affects all programs started by this process, including standard UNIX utilities. For details about JADE locales and translatable messages, see Chapter 12, “Internationalization”, in your JADE Development Environment User’s Guide.

See also the optional LC_CTYPE environment variable, later in this chapter.

LD_LIBRARY_PATH

The LD_LIBRARY_PATH environment variable is the standard UNIX environment variable that indicates the location of shared objects and libraries. This variable, which applies only to Linux, must include the lib directory of this JADE installation. (See also “Directory Locations”, in Chapter 5.)

To set this variable in the Bourne Again Shells (bash):

LD_LIBRARY_PATH=$JADEHOME/lib:$LD_LIBRARY_PATH:/usr/lib; export LD_LIBRARY_PATH


setenv LD_LIBRARY_PATH $JADEHOME/lib:$LD_LIBRARY_PATH:/usr/lib

NLSPATH

The NLSPATH environment variable is the standard UNIX environment variable that indicates the location of message catalogs and translatable messages.

Update this variable to include the message catalog directory.


NLSPATH=$JADEHOME/lib/nls/msg/%L/%N.cat:$NLSPATH; export NLSPATH


setenv NLSPATH $JADEHOME/lib/nls/msg/%L/%N.cat:$NLSPATH

PATH

The PATH environment variable is the standard UNIX environment variable that indicates the location of executable programs. (See also “Directory Locations”, in Chapter 5.)


PATH=$JADEHOME/bin:$PATH; export PATH



JADEICG-6.3


setenv PATH $JADEHOME/bin:$PATH

Optional Environment Variables for SUSE Linux on Intel The following UNIX environment variables are used by JADE executable programs. You do not have to change them, but the following examples make JADE easier to use if you do set them.

JADELANGDIR

The JADELANGDIR environment variable is used by JADE if it cannot find the message catalogs that it requires by using the standard UNIX NLSPATH environment variable.

The JADELANGDIR variable points directly to the directory that contains the messages catalogs, and ignores the value of the LANG environment variable.


JADELANGDIR=$JADEHOME/lib/nls/msg; export JADELANGDIR


setenv JADELANGDIR $JADEHOME/lib/nls/msg

LC_CTYPE

The LC_CTYPE environment variable indicates the character classification, case conversion, and other character attributes that you want to use.

Note This variable, if set, cannot have .UTF-8 appended to the character classification.

TMPDIR

The TMPDIR environment variable is a standard UNIX environment variable that indicates where temporary files are created.

JADE Daemon (jaded) The jaded program (the JADE daemon) is the JADE server implemented on UNIX, which can be run directly from the command line.

Starting JADE Daemon from the Command Line on Intel The following is the command line syntax required to start the JADE daemon.

jaded path=/database-path ini=JADE-initialization-file

The mandatory path parameter specifies the full location of the JADE database. The optional ini parameter specifies the JADE initialization file.

The following is an example of the jaded command line.

jaded path=/usr/jade/system ini=/usr/jade/jade.ini

To stop it from the command line, press ^C or issue a kill command against the jaded process id from a different shell.



JADEICG-6.3

JADE Portable GUI (jadepg) The jadepg program is the standard fat client or JADE presentation client implementation of the JADE portable GUI implemented on UNIX, which can be run directly from the command line.

The jadepg program expects and uses the UNIX environment variables described in “Portable GUI Environment Variables” under “Portable GUI Configuration”, in Chapter 5. The sample shell script (that is, jadepg.sh in your bin directory) performs the required environment setup.

Note If you want the portable GUI program to run as a service, specify the RunAsService parameter in the [ Jade] section of the JADE initialization file with a value of true.

Starting the JADE Portable GUI from the Command Line The following is the command line syntax required to start the JADE portable GUI program.

jadepg path=/database-path schema=schema-name app=application-name ini=JADE-initialization-file


The following is an example of the jadepg command line.

jadepg path=/usr/jade/system schema=TestSchema app=TestSchemaApp ini=/usr/jade/jade.ini

To stop it from the command line, press ^C or issue a kill command against the jadepg process id from a different shell.

Running an Application Server Your JADE schemas and applications can be run in thin client mode from a UNIX application server simply by specifying the appropriate command line parameters and then invoking the application server on your UNIX host.

When this is running, you just specify the appropriate presentation client command line parameters on the Windows 2003 Server, Windows Vista, Windows XP, or Windows 2000 workstation that you want to run in thin client mode and then invoke the thin client executable program.

Notes JADE does not currently supply a facility to control the order in which services are started or stopped when the host computer is booted. If the application server is started before the database, a message is recorded in the JADE log file indicating that it cannot connect to the database.

If you want to install multiple application servers as services on the same host, you must have a separate JADE initialization file for each application server service because the service installation process must update a unique NodeName, NodeNameDescription, and RunAsService parameter in the [ JadeAppServer] section of the JADE initialization file. Alternatively, you can prefix a section name with a unique identifier that is supported when a JADE program detects the optional name=unique-identifier command line parameter. For details, see “Sharing JADE Initialization Files” and “Two-Level Section Names”, in your JADE Initialization File Reference.



JADEICG-6.3

When you install JADE on a UNIX host, two subsystems are automatically created for you. For example, if your repackaged copy of JADE is called devdb, there will be a service called devdb that controls the database and a second service called devdb-app1 that controls the application server. The port numbers and database path details are listed at the end of the install process.

Invoking an Application Server The jadappb program is the JADE application server implemented on UNIX.

The following is the command line syntax required to run an application server on UNIX.

jadappb appServerPort=TCP/IP-communications-port-number path=/database-path ini=JADE-initialization-file-path [server=multiUser|singleUser|readOnlyUser] [host=host-server-node-name or host-IP-address] [port=host-port-name or host-port-number] [interface=client-TCP/IP-name or client-IP-address] [localport=client-port-name or client-port-number] [endJade] optional-user-defined-parameters

The command parameters are summarized in the following table.

Parameter Description Example

appServerPort TCP/IP communications port number (mandatory) AppServerPort=1500

path Database path name (mandatory) path=r:/jade_development/jade63/system

ini JADE initialization file path ini=r:/jade63/system/test/myjade.ini

[server] Server type server=multiUser (default value)

[host] Host server node name or host IP address host=cnwchcs38

[port] Port name or number of the host (server) node port=6015

[interface] TCP/IP name or the IP address of the client (local) node interface=cnwme1c

[localport] Port name or number of the client (local) node localport=6099

[endJade] Indicates the end of JADE-specific parameters endJade

For details about these parameter values, see “Running an Application Server in Batch Mode”, in Chapter 2 of your JADE Thin Client Guide. (Note, however, that the virgule, or forward slash, separator ( /) is used in file and directory paths in the UNIX operating system, in contrast to the backslash character ( \) used as a separator in file and directory path names on a workstation running under a Microsoft Windows operating system.)

The program treats processing arguments enclosed in double ("") or single ('') quotation marks after the endJade parameter as single-string entries in the huge string array. The handling of strings in this huge string array is application-specific. For example, dir= "program files" is treated as a two-string entry and "dir= program files" is treated as a one-string entry. How these entries are handled is determined by your application.

Specify the server parameter only if you want to run the application server in single user mode. (If you do not specify the server parameter, the application server runs in multiuser mode.) The jadappb program uses the parameters in the [ JadeAppServer] section of the JADE initialization file. When you have invoked your application server, you can then initiate your JADE presentation clients. If the jadappb program fails, a non-zero exit code is returned and an error message is displayed; for example, if the database directory was invalid.



JADEICG-6.3

Running a Non-GUI Client Application You can run a non-GUI client JADE application (defined as application type Non-GUI in the Define Application dialog) on UNIX simply by specifying the appropriate command line parameters to invoke the non-GUI client application on a UNIX host, to add processing nodes to your JADE network.

A non-GUI client application runs on the node on which the Application class startApplication method is executed (that is, if the startApplication method is executed on a server node, the application is started on that server node).

Notes JADE does not currently supply a facility to control the order in which services are started or stopped when the host computer is booted. If the application server is started before the database, a message is recorded in the JADE log file.

If you want to install multiple non-GUI client applications as services on the same host, you must have a separate JADE initialization file for each non-GUI application service, because the service installation process must update a unique NodeName, NodeNameDescription, and RunAsService parameter in the [NonGuiClient] section of the initialization file. Alternatively, you can prefix a section name with a unique identifier that is supported when a JADE program detects the optional name=unique-identifier command line parameter. For details, see “Sharing JADE Initialization Files” and “Two-Level Section Names”, in your JADE Initialization File Reference.

For details about increasing the time JADE waits for an application to initiate on another thread before raising an exception when your system has a large number of applications to start, see the MaxWaitAppStart parameter in the JADE initialization file [ JadeServer] section, in your JADE Initialization File Reference.

The jadclient executable program that enables you to automate the running of non-GUI client applications on UNIX is installed with your JADE software. (For details about using non-GUI client applications to automate the extraction of schemas, see “Extracting Schemas as a Non-GUI Client Application”, in Chapter 11 of your JADE Development Environment User’s Guide.)

Invoking a Non-GUI Client Application The following is the command line syntax required to run the jadclient program on UNIX.

jadclient schema=schema-name app=application-name path=/database-path ini=JADE-initialization-file-path [causeEventOnSystem=[cause-event-number]] [server=multiUser|singleUser|readOnlyUser] [host=host-server-node-name or host-IP-address] [port=host-port-name or host-port-number] [interface=client-TCP/IP-name or client-IP-address] [localport=client-port-name or client-port-number] [endJade]



JADEICG-6.3



schema Schema name (mandatory) ASchema

app Application name (mandatory application of type Non_GUI) NonGUIApp or Non_GUI_Web)



[causeEventOnSystem] External user event caused on the JADE System object, 12345 and if specified, can optionally contain a numeric value

[server] Server type (that is, mode in which the application runs) server=multiUser (default value)






For details about these parameter values, see “Running a Non-GUI Client Application using jadclient”, in Chapter 1 of your JADE Runtime Application Guide. Note, however, that the service, nodeName, and nodeNameDescription parameters do not apply when running a non-GUI client application on UNIX, as a non-GUI client application is installed on UNIX as a subsystem, which is itself a service.

In addition, the virgule, or forward slash, separator ( /) is used in file and directory paths in the UNIX operating system, in contrast to the backslash character ( \) used as a separator in file and directory path names on a workstation running under a Microsoft Windows operating system.

Note The jadclient program treats processing arguments enclosed in double (" ") or single (' ') quotation marks after the endJade parameter as single-string entries in the huge string array. The handling of strings in this huge string array is application-specific. For example, path= "program files" is treated as a two-string entry and "path= program files" is treated as a one-string entry. How these entries are handled is determined by your application.

The non-GUI client application program displays a progress report as the application initializes. Standard initialization information is output to stdout and error information is output to stderr. If the jadclient program fails, a non-zero exit code is returned and an error message is displayed; for example, if the schema is invalid or you attempt to remove a service that is not installed.

The jadclient program uses the parameters in the [NonGuiClient] section of the JADE initialization file.

Initiating Non-GUI Applications when the Application Server is Initiated

Use the ServerApplication parameter in the [NonGuiClient] section of the JADE initialization file to specify a non-GUI client application that is executed when the server or application server node initializes.

Note Non-GUI client applications initiated in JADE thin client mode are run wholly on the application server, with no presentation client interaction.



JADEICG-6.3

For details, see “JADE Non-GUI Client Section [NonGuiClient]” under “JADE Thin Client Sections”, in your JADE Initialization File Reference.

Initiating Non-GUI Applications at a Specific Time

Specify the optional time variable in the [NonGuiClient] section of the JADE initialization file to specify a non-GUI client application that is executed at a specified time.



Java Framework You must set up the JADE environment to run Java applications that interact with JADE. The eclipse.sh and java.sh linked sample scripts are provided to set up the JADE environment and run Eclipse or Java. These scripts assume that the eclipse and java commands will execute the required executables. You can set up a similar script for other required Java development environments.

Before running java.sh, you must set up the Java CLASSPATH environment variable to specify the location of the Java user classes.

Locales and Translatable Messages The Microsoft Windows implementations of JADE supplies the jadmsgs.eng file that maps error numbers to error messages. This enables you to translate and extend error messages for users of runtime JADE applications.

The UNIX implementation of JADE uses the jadmsgs message catalog instead of the jadmsgs.eng file. (The jadmsgs.eng file is supplied but is not used.)

The selection of which jadmsgs message catalog to use is determined by a combination of the LANG, NLSPATH, and JADELANGDIR environment variables.

If messages need to be translated, the following command generates a standard text file that can be edited as required.

dspcat –g ./jadmsgs.cat > jadmsgs.msg

Set 1 is used for error numbers that are positive and set 2 is used for negative error numbers. As message catalog message numbers can only be positive, the message number in set 2 is the absolute value of the error number.

To generate a new message catalog from the edited jadmsgs.msg file, use the following command.

gencat jadmsgs.cat jadmsgs.msg

When you have generated your new message catalog, place the new jadmsgs.cat catalog in the $JADEHOME/lib/nls/msg/$LANG/ directory to which the translated file belongs.



JADEICG-6.3

Locales The internal translation table lists the LANG variables and their LCID descriptive names. This table is used if the [LANG2LCID] section in the JADE initialization file does not contain a value that matches the LANG environment variable.

JADE internally performs the following actions to map the LANG variable to a Microsoft LCID number.

If the language and country portions of the LANG variable match, the matching LCID number is used.

If only the language matches, the primary LCID language is used with the sublanguage of SUBLANG_NEUTRAL.

If neither the language nor the country portion matches, the LCID number is set to 1033 English (USA).

The first letter of the LANG environment variable is changed to a lowercase character and then looked up in the following internal translation table.

LANG LCID LCID Descriptive Name

af 54 Afrikaans

ar 1 Arabic (Saudi Arabia)

ar_AE 20481 Arabic (United Arab Emirates)

ar_BH 21505 Arabic (Bahrain)

ar_DZ 5121 Arabic (Algeria)

ar_EG 3073 Arabic (Egypt)

ar_IQ 2049 Arabic (Iraq)

ar_JO 17409 Arabic (Jordan)

ar_KW 19457 Arabic (Kuwait)

ar_LB 18433 Arabic (Lebanon)

ar_LY 4097 Arabic (Libya)

ar_MA 6145 Arabic (Morocco)

ar_OM 8193 Arabic (Oman)

ar_QA 22529 Arabic (Qatar)

ar_SY 16385 Arabic (Syria)

ar_TN 7169 Arabic (Tunisia)

ar_YE 9217 Arabic (Yemen)

be 35 Byelorussian

bg_BG 2 Bulgarian

c 2048 LANG_NEUTRAL/SUBLANG_SYS_DEFAULT

ca_ES 3 Catalan

cs_CZ 5 Czech

da_DK 6 Denmark

de 7 German

de_AT 3079 German (Austrian)

de_CH 2055 German (Swiss)

de_DE 1031 German (Germany)



JADEICG-6.3


de_LI 5127 German (Liechtenstein)

de_LU 4103 German (Luxembourg)

el_GR 8 Greek

en 9 English

en_AU 3081 English (Australian)

en_CA 4105 English (Canadian)

en_GB 2057 English (UK)

en_IE 6153 English (Irish)

en_JM 8201 English (Jamaica)

en_NZ 5129 English (New Zealand)

en_US 1033 English (USA)

en_ZA 7177 English (South Africa)

es 10 Spanish

es_AR 17418 Spanish (Argentina)

es_BO 22538 Spanish (Bolivia)

es_CL 19466 Spanish (Chile)

es_CO 9226 Spanish (Colombia)

es_CR 5130 Spanish (Costa Rica)

es_DO 7178 Spanish (Dominican Republic)

es_EC 18442 Spanish (Ecuador)

es_ES 1034 Spanish (Castilian)

es_GT 4106 Spanish (Guatemala)

es_MX 2058 Spanish (Mexican)

es_PA 6154 Spanish (Panama)

es_PE 16394 Spanish (Peru)

es_PY 21514 Spanish (Paraguay)

es_UY 20490 Spanish (Uruguay)

es_VE 8202 Spanish (Venezuela)

et_EE 37 Estonian

eu 45 Basque

fa_FA 41 Farsi / Persia

fi_FI 11 Finnish

fo_FO 56 Faroese

fr 1036 French

fr_BE 2060 French (Belgian)

fr_CA 3084 French (Canadian)

fr_CH 4108 French (Swiss)

fr_FR 12 French (France)

fr_LU 5132 French (Luxembourg)

he 13 Hebrew (formerly iw)

hr_HR 26 Croatian

hu_HU 14 Hungarian

id_ID 33 Indonesian



JADEICG-6.3


is_IS 15 Icelandic

it 1040 Italian

it_CH 2064 Italian (Swiss)

it_IT 16 Italian (Italy)

ja_JP 17 Japanese

ko 18 Korean

ko_KP 2066 Korean (Johab)

ko_KR 1047 Korean (Korea)

lt_LT 39 Lithuanian

lv_LV 38 Latvian, Lettish

nl 19 Dutch

nl_BE 2067 Dutch (Belgian)

nl_NL 1043 Dutch (Holland)

no 20 Norwegian

no_NO 20 Norwegian (Norway)

pl_PL 21 Polish

pt 22 Portuguese

pt_BR 1046 Portuguese (Brazilian)

pt_PT 2070 Portuguese (Portugal)

ro_RO 24 Romanian

ru_RU 25 Russian

sk_SK 27 Slovak

sl_SI 36 Slovenian

sq_AL 28 Albanian

sr_SR 46 Serbian

sv_CH 29 Swedish

th_TH 30 Thai

tr_TR 31 Turkish

uk_UA 34 Ukrainian

zh 4 Chinese

zh_CH 4 Chinese (China)

zh_CN 2052 Chinese (PR China)

zh_HK 3076 Chinese (Hong Kong)

zh_SG 4100 Chinese (Singapore)

zh_TW 1028 Chinese (Taiwan)

To allow consistent locale handling behavior between Microsoft Windows and UNIX, the supplied locbuild program (both in source code and the Windows executable) was used to step through all installed locales on a development machine to create the locales.msg file. (For details about the locbuild program, see /opt/jade/tools on the JADE CD-ROM.)

Each set number corresponds to an LCID value, and the message number corresponds to each LCTYPE value.



JADEICG-6.3

In simplified terms, the reimplementation of the Microsoft Windows GetLocaleInfo(LCID, LCTYPE, LPTSTR, int) API call uses the LCID as the set number and LCTYPE as the message number, and performs a UNIX catgets (locales_cat, LCID, LCTYPE, default) API call.

If you want to add additional locale support or alter the current information, you can use the supplied locbuild program to create a new locales.msg file on a Windows host that has your required locale installed, as follows.

locbuild > locales.msg

Alternatively, on a UNIX host you can:

1. Convert the locales.cat catalog to a text file, as follows.

dspcat –g ./locales.cat > locales.msg

2. Edit the contents to meet your requirements.

3. Recreate the locales.cat file, as follows.

gencat locales.cat locales.msg

Note When copying the generated locales.msg file from a Microsoft Windows host to UNIX, you must change the CR/LF (carriage return/linefeed) line terminators to LF (linefeed).

____________________________________

JADEICG-6.3

Chapter 4 JADE under a Red Hat Distribution of Linux on Intel

____________________________________ This chapter covers the following topics.

Overview

Red Hat Linux Installation on Intel Servers

Overview of Installing JADE on Linux under Red Hat

JADE Operational Requirements on Linux under Red Hat

– Red Hat Linux Hardware Requirements

– Red Hat Linux Software Requirements

JADE Product and RPM Names for Red Hat Linux on Intel

– Port Numbers for Red Hat Linux

Installing JADE

– Parameters for the jadeinstall Command

– Starting and Stopping the JADE System

– Registering the Database

– Setting Up the Windows Client


Deinstalling JADE


Detailed Command Information for Red Hat Linux on Intel

Environment Variables

JADE Daemon (jaded)

JADE Portable GUI (jadepg)

Running an Application Server

Running a Non-GUI Client Application

Java Framework

Locales and Translatable Messages


Chapter 4 JADE under a Red Hat Distribution of Linux on Intel 73

JADEICG-6.3

Overview This chapter gives an overview of JADE under a Red Hat distribution of Linux on Intel, including:

Installing JADE for the first time

Performing upgrades

Running the supplied commands

JADE server nodes, JADE thin client mode application servers, and JADE client nodes can be run on 32-bit versions of the Red Hat Linux, a UNIX-like operating system, on Intel hardware.

In this chapter, the term:

UNIX generally refers to Linux.

The usage of Linux differentiates features that are available only on Linux, whereas UNIX is used where the feature is generally available to most versions of UNIX.

RPM relates to the Linux installable file package (that is, Red Hat Package Manager).

subsystem is equivalent to the following terms.

Server, JADE database, or application

UNIX daemon

Windows 2003 Server, Windows Vista, Windows XP, or Windows 2000 service

Notes On Linux, use the command line versions of administrative programs (for example, the JADE Database or the JADE Remote Node Access utility).

The size of a Unicode character used by JADE is 4 bytes on Linux. Unicode characters in strings are stored as logical lengths rather than physical lengths.

When running a JADE command on UNIX (for example, jadappb or jaded), you can run the corresponding supplied shell script (for example, jadappb.sh or jaded.sh) so that your environment variables are set up for you.

Your JADE applications are developed independently of the targeted server operating environment. You are therefore sheltered to a significant degree from many platform-specific details like operating system services, data representations, character sets, and error messages. For details about the differences when running JADE applications on a server under UNIX and the Microsoft Windows operating systems, see “Differences When Running JADE Applications on a Server under UNIX”, in Chapter 1 of your JADE Platform Differences Guide

The portation to UNIX consists of JADE server code only, as follows.

The JADE kernel

External methods

Compiler methods and functions

The compiler

The interpreter



JADEICG-6.3

The database server

The application server

The portable GUI client

The non-GUI client

The command line utility tools

For details about other terms, see “Glossary”, in Appendix A of your JADE Development Environment User’s Guide.

Red Hat Linux Installation on Intel Servers This section provides you with the steps required to install and configure JADE on a Red Hat distribution of Linux. If you want more information about commands and their parameters, see “Detailed Command Information for Red Hat Linux on Intel”, later in this chapter.

Notes For users wishing to develop their own installation process, the steps are as executed in the pre_i and post_i scripts in the bin directory in the /opt/jade subdirectory for the release.

For details about the location of directories, see “Directory Locations”, in Chapter 5.

Overview of Installing JADE on Linux under Red Hat JADE uses the underlying Linux installation tools to install JADE software. From the JADE perspective, the RPM install mechanism has a serious limitation, which is that a specific UNIX product can be installed only in a fixed location (which is decided by the product developer; that is, by the JADE Development Centre) and that multiple versions cannot be installed (because of the fixed location issue).

To overcome this limitation, the JADE install process has been enhanced as follows.

The JADE product is made up of several Linux RPMs, which are the smallest installable units.

The initial RPM install copies the files from the release medium into the /opt/jade directory.

The RPM stores details about installed files and data.

The jadeinstall program uses command line options to control where it installs a working copy of JADE.

The general sequence of actions for installing JADE on Linux is as follows.

Install the required JADE Red Hat Package Manager (RPM) file directly by using the standard Linux RPM install tools. This puts the files in the /opt/jade directory.

To install one or more copies of JADE, perform the following action.

Execute the jadeinstall program, indicating where you want the software to be installed and other customizations that you require.

The install process automatically selects port numbers and configures subsystems, so that the database and an application server are ready to be started.



JADEICG-6.3

JADE Operational Requirements on Linux under Red Hat This section covers the hardware and software required to run JADE on a UNIX server under a Red Hat distribution of Linux.

Notes These specifications represent minimum configurations. Configurations that are more powerful may be advisable, depending on the size of the development being undertaken, the scale of your JADE applications, and the performance requirements of your system. Although minimum Service Pack (SP) levels are specified, we recommend that you keep up-to-date with Service Packs and security updates for the operating system that you are running.

Where an operating system provides both 32-bit and 64-bit editions, both are supported.


Red Hat Linux Hardware Requirements Depending on the size and configuration of your Linux Red Hat installation, JADE server nodes can be configured on one or many Intel servers. Different JADE applications can run on separate Intel servers, accessed by JADE clients.

Caution Each device on which JADE runs should have error-correcting memory.

Minimum Hardware Requirements for a JADE Database Server

The following subsections contain the recommended minimum hardware required to deploy JADE on a machine that hosts a JADE database server.

Processors




Memory



Storage







JADEICG-6.3


Other





Minimum Hardware Requirements for an Application Server

The following subsections contain the recommended minimum hardware required to deploy JADE on machines hosting an application server.

Processors




Memory



Storage


Other





Minimum Hardware Requirements for Standard Clients

The following subsections contain the recommended minimum hardware required to deploy JADE on a standard client.




JADEICG-6.3

Processors

For a standard client, you require an Intel CPU (Pentium, AMD, or compatible), 1 GHz or faster.

Memory



Storage


Other




Minimum Hardware Requirements for Running JADE Presentation Clients

The following subsections contain the recommended minimum hardware required to deploy JADE on a presentation (or thin) client node.

Processors


Memory


Storage


Other





Red Hat Linux Software Requirements JADE 6.3 has been compiled on Red Hat Linux environments using the GNU Compiler Collection 4.1.2 (shipped with Red Hat Enterprise Linux 5 Desktop).



JADEICG-6.3

The following software is the minimum level of Red Hat Linux software when running JADE on an Intel server. Red Hat Enterprise Linux 5 (RHEL 5) Update 5 meets these requirements.

kernel-2.6.18 or later.

glibc-2.5-24 or later.

openssl-0.9.8b.

libacl-2.2.39.

libattr-2.4.32.

libgcc-4.1.2.

libstdc++-4.1.2.

zlib-1.2.3.

cups-1.2.4.

Optional Apache2 HTTP Server httpd-2.2.3 for Red Hat Linux (RHEL 5). (For details, see “Connecting to JADE Applications from an Apache HTTP Server” and “Configuring Apache for Remote Connections”, in Chapter 5.)

Apache 2.2.3 is the default 32-bit and 64-bit version installed on RHEL5.


Optional unixODBC-2.2.11(if you are using external databases or the JADE ODBC driver). For details, see “Configuring a JADE ODBC Driver”, in Chapter 6 of the JADE Developer's Reference.

Optional gcc-4.1.2 or gcc-c++-4.1.2 (if you are developing user libraries for use with JADE).

Optional expat-1.95.8 (if you are using external databases or the JADE XML parser).

To allow the built-in JADE development environment help to work, you must install one of the following packages.

xpdf (the default)

acroread

evince version 0.6.0, which supports following hyperlinks within a document and between other documents in the JADE product information library

For details, see “JADE Online Help”, in Chapter 2 of your JADE Development Environment User's Guide.

To deploy a JADE thin client or standard (fat) client on any compatible Java-capable desktop, you require the:

Sun or IBM Virtual Machine Java 2 Runtime Environment ( JRE), Standard Edition ( J2SE) Version 6. For details about specifying the Java home directory in which this software is installed on each standard (fat) client or presentation client node in a JADE portable GUI environment, see “JADE Portable GUI Java Section [ JadeJava]”, in your JADE Initialization File Reference.



JADEICG-6.3


For 32-bit JADE clients, the native or the cross-platform version of JMF can be used. For the 64-bit version of JADE, the Java Media Framework ( JMF) library must be the portable version (that is, all Java code and no .so files), not the i386 version.

Although you can download the Linux Intel or All Java version of these software packages, the Linux Intel version provides improved performance.


To deploy a Java framework, you require the:

Sun or IBM Virtual Machine Java 2 Runtime Environment ( JRE), Standard Edition ( J2SE) Version 6

Notes If the Java Virtual machine is not available on the Linux distribution release medium, you can download the Java installation (software package) from the Sun Microsystems Java Web site http://java.sun.com/ or the IBM Web site http://www.ibm.com/developerworks/java/. Download the Java Media Framework ( JMF) 2.1.1e software package from the Sun Microsystems Java Web site http://java.sun.com/.

JADE encodes Unicode characters using the wide-character encoding routines provided by UNIX.

When accessing a JADE application from the Internet, your JADE application and Microsoft Internet Information Server (IIS) or Apache HyperText Transfer Protocol (HTTP) must reside on the same workstation if you are using a named pipe connection. When using a TCP/IP connection, the machine hosting IIS or Apache HTTP Server can be different from the machine that is running the JADE application, to provide greater security via firewalls.

If using Postscript printing, your printer must support Postscript level 2 or greater.

JADE Product and RPM Names for Red Hat Linux on Intel The following is the JADE software required for Linux multiuser LAN-based development or applications usage when running 32-bit JADE on Intel.

JADE-6.3.nn.nnn-redhat-linux-ansi.i686-1.rpm (must be installed)

JADE-6.3.nn.nnn-redhat-linux-ansi-rte.i686-1.rpm (must be installed)

JADE-6.3.nn.nnn-redhat-linux-ansi-devdata.i686-1.rpm (must be installed)

JADE-6.3.nn.nnn-redhat-linux-ansi-devel.i686-1.rpm (installed for C++ development)

JADE-6.3.nn.nnn-redhat-linux-ansi-docs.i686-1.rpm (optional)

JADE-6.3.nn.nnn-redhat-linux-ansi-examples.i686-1.rpm (optional)

JADE-6.3.nn.nnn-microsoft-win32-ansi.noarch-1.rpm (optionally installed if Windows thin client downloads are required)

JADE-6.3.nn.nnn-microsoft-win32-ansi-thinclient.noarch-1.rpm (optionally installed if Windows thin client downloads are required)






JADEICG-6.3

JADE-6.3.nn.nnn-redhat-linux-ansi-thinclient.i686-1.rpm (optionally installed if Red Hat Linux ANSI thin client downloads are required)

Notes The nn.nnn values in the JADE-6.3.nn.nnn version require leading zeros (for example, 6.3.12.001).

For the 64-bit version of JADE, the i686 portion of the above 32-bit JADE software is replaced by x86-64 (for example, JADE-6.3.nn.nnn- redhat-linux-ansi.x86-64-1.rpm).

The JADE package contains the Red Hat Package Manager (RPM) units (individually installable groups of files) listed in the following table.

RPM Description Dependent on…

<linuxansi> JADE install tools Requirement level of operating system

rte JADE binaries (run time) base and all operating system software listed earlier in this section

devdata JADE database rte

docs JADE messages and documentation rte

devel JADE application development tool kit rte

examples JADE example schemas rte

<win32ansi> Parent RPM of "JADE Windows thin client"

thinclient JADE Windows thin client binaries rte

In addition to the ANSI software listed under “Red Hat Linux Software Requirements”, in the previous section, there is also a Unicode version of these RPMs; for example:

JADE-6.3.12.001-redhat-linux-unicode-docs.i686-1.rpm

The –ansi– portion of the RPM name is changed to –unicode–.

Port Numbers for Red Hat Linux Each JADE database and application server running on a host must have a unique TCP/IP port number.

The installation process automatically searches for the two available TCP/IP port numbers greater than 50,000, assigning the first to the database server and the second to the application server.

If you want to assign a specific port number, edit the /etc/services file and create the entries that you require before installing JADE; for example:

"jade 6005/tcp jade-db" "jade-app1 6006/tcp jade-6006"

The installation process uses any value that already exists.

You can change the port number or local port number in the /etc/services file after the installation. If you change it, you must make the corresponding change in your JADE initialization files on the JADE client nodes.

The installation process automatically updates the ServerNodeSpecifications parameter in the [ JadeClient] section and the NetworkSpecification parameter in the [ JadeServer] section of the JADE initialization file ( jade.ini) for each database.



JADEICG-6.3

Installing JADE

To install JADE on a UNIX server running under a Red Hat distribution of Linux

1. As root, install the rpm files using rpm commands to meet your requirements, as shown in the following example.

mount /mnt/cdrom cd /mnt/cdrom/RPMS rpm -ivh *.rpm-file-name cd / eject cdrom

Files are installed into the following directories.

/opt/jade/sbin /opt/jade/images/6.3.version-number.patch-number/bin : install scripts /opt/jade/images/6.3.version-number.patch-number/i686-redhat-linux/ansi /opt/jade/images/6.3.version-number.patch-number/ i686-microsoft-win32/ansi

Each JADE version installed using rpm is put into a separate /opt/jade/images subdirectory. For example, the next release of JADE 6.3 version 12 patch 044 (that is, 6.3.12.044 may be as follows.

/opt/jade/images/6.3.12.044/i686-redhat-linux/ansi

No updates are done using rpm.

When you install JADE, a user jade and group jade are created if they do not exist.

Caution If you are installing JADE on an Intel server that uses a centrally managed user management system, you should create the jade user and jade group on the master node and then propagate out the details to the installation node before the installation takes place.

2. To install the JADE executables, library files, and database into the appropriate directories, run the jadeinstall command as root, as follows.

/opt/jade/sbin jadeinstall [--help] -i | --installDir= -v | --version= [-u | --usercode=] [-g | --group=] [-s | --serviceName=] [-n] [-k] [-f] [-t | --targetType] [-q | --quiet] [-j | --jadeHome=] [-U | --Upgrade] [--all] [--rte] [--devdata] [--devel] [--docs] [--examples] [--thinclient] [--w32thinclient]



JADEICG-6.3

The parameters for the jadeinstall command, described under “Parameters for the jadeinstall Command” in the following section, are listed in the following table.

Short Format Long Format Description

[--help] Displays help information

-i --installDir= Target installation directory for the JADE system (mandatory)

-v --version= JADE version to be installed (mandatory)

[-u] [--usercode=] User code for JADE files (which defaults to jade)

[-g] [--group=] Group for JADE files (which defaults to jade)

[-s] [--serviceName=] Service name defined in /etc/services (which defaults to JADE)

[-n] JADE registration name (if defined, the database is registered)

[-k] JADE registration key (if defined, the database is registered)

[-f] [--force] Forces the overwrite of existing files (which defaults to no overwriting)

[-t] [--targetType=] Specifies a non-default target type

[-q] [--quiet] Quiet mode (which defaults to status/error messages output)

[-j] [--jadeHome=] Location of rte installation for executables (if not the same as the –i | --installDir= value)

[-U] [--Upgrade] Upgrades the currently installed version

[--all] Installs all available components

[--rte] Installs JADE Runtime files

[--devdata] Installs the JADE database

[--devel] Installs JADE devel files

[--docs] Installs JADE documentation

[--examples] Installs JADE example files

[--thinclient] Installs JADE Red Hat thinclient files

[--w32thinclient] Installs JADE Windows thinclient files

The short format parameter, indicated by a single dash, is separated from its value by a space.

The long format parameter, indicated by a double dash, is separated by its value only by the equals sign (=), and no space separation is permitted between the parameter and its value. In addition, nn.nnn values in the JADE version require leading zeros. For example, run the following command to install the rte, devdata, and thinclient packages into the /home/myjade directory.

/opt/jade/sbin jadeinstall --installDir=/home/myjade --version=6.3.12.001 -n "My Company Ltd." -k 98765432-10123456-78909876-54321012 --rte --devdata --targetType=i686-redhat-linux-ansi --thinclient

For each selected package, the jadeinstall command performs the following actions.

1. Runs the pre-installation script, if it is present

2. Copies the required files from the /opt/jade/images directory to your specified target installation directory

3. Sets the ownership and permissions that you specified



JADEICG-6.3

4. Runs the post-installation script, if it is present

Parameters for the jadeinstall Command This section contains the parameters for the jadeinstall command that installs the JADE executables, library files, and database as root into the appropriate directories. For details, see “Installing JADE”, in the previous section.

[--help]

The optional --help parameter enables you to specify that help information about the jadeinstall command is displayed.

-i | --installDir=

The –i or --installDir= parameter specifies the target installation directory for the JADE system running under Linux. You must specify this parameter, which must be a valid directory path.

-v | --version=

The –v or --version= parameter specifies the JADE version to be installed.

You must specify this parameter, which must be a valid installed JADE version (that is, /opt/jade/images/version-number).

[-u | --usercode=]

The optional –u or --usercode= parameter specifies the user code for JADE files. This value defaults to jade.

[-g | --group=]

The optional –g or --group= parameter specifies the group for JADE files. This value defaults to jade.

[-s | --serviceName=]

The optional –s or --serviceName= parameter specifies the service name defined in /etc/services. This value defaults to JADE.

[-n]

The optional –n parameter specifies your registered licence name (displayed on your Certificate of Authorisation, which may be an e-mail message providing you with your licence name and key), if the database is to be registered.

You must specify your licence name (enclosed in double quote characters if spaces are included) if it has changed. This name must be typed correctly (it is case-sensitive), as it is validated against your licence key. If you do not specify the licence name, the program assumes that the name is unchanged and uses the existing licence name or it leaves the database unlicensed.

[-k]

The optional –k parameter specifies the JADE licence key, if the database is registered. Enter the licence key exactly as it is specified on your Certificate of Authorisation, but without spaces. (You can enter or omit the quotation marks ('') printed on the Certificate of Authorisation.)



JADEICG-6.3

[-f | --force]

The optional –f or --force parameter forces the overwriting of existing files.

By default, existing files are not overwritten.

[-t | --targetType=]

The optional –t or --targetType= parameter specifies the non-default target type to use. For example, specify the non-default target type as follows.

--targetType=i686-redhat-linux-ansi

This value defaults to i686-redhat-linux-ansi.

[-q | --quiet]

The optional –q or --quiet parameter specifies quiet mode (that is, status and error messages are not output. By default, status and error messages are output.

[-j | --jadeHome=]

The optional –j or --jadeHome= parameter specifies the location of the run time executable files (specified in the optional --rte parameter) for installation if it is not the same as the value of the -i or --installDir= parameter.

[-U | --Upgrade]

The optional –U or --Upgrade parameter specifies that the currently installed JADE version is upgraded. For more details, see “Upgrading a JADE Release”, later in this chapter.

[--all]

The optional --all parameter installs all available JADE components (that is, JADE Runtime, JADE DEVELOPMENT, JADE devel, JADE thinclient, and JADE documentation databases and files).

[--rte]

The optional --rte parameter installs the JADE Runtime files.

[--devdata]

The optional --devdata parameter installs the JADE DEVELOPMENT database.

[--devel]

The optional --devel parameter installs the JADE devel files (that is, the JADE application development tool kit, which contains examples and C++ header files).

[--docs]

The optional --docs parameter installs the JADE documentation files.

[--examples]

The optional –examples parameter installs the JADE examples files.



JADEICG-6.3

[--thinclient]

The optional --thinclient parameter installs the JADE Red Hat thinclient files, for the JADE thin client automatic download.

[--w32thinclient]

The optional –w32thinclient parameter installs the JADE Windows thinclient files, for the JADE thin client automatic download.

Starting and Stopping the JADE System You can set the RunAsService parameter in the [ JadeServer], [ JadeAppServer], or [NonGuiClient] section of the JADE initialization file to true if you want the node automatically placed in the background and detached from the controlling terminal.

Although this parameter is set to false by default, it is normally set to true when running JADE nodes as services on Linux.

To start a JADE Linux server, perform one of the following actions

Ensure that the environment variables are set up correctly (for details, see “Required Environment Variables”, later in this chapter) and then start the default JADE server by typing the following.

jaded ini=/home/initialization-file-path path=database-path

Run the supplied jaded.sh shell script, which sets up all required environment variables for you, by typing the following.

jaded.sh ini=/home/initialization-file-path path=database-path

Path names with no leading slash character are pre-pended by the JADE HOME directory. In the following examples, the JADE HOME directory is assumed to be /jade.




To stop a JADE Linux server


2. Type the following, to stop the default JADE server.

kill –TERM -$(< tmp/node-name.pid)

Registering the Database Before you can run JADE on the Linux server, you must register the database (if you do not do so during the installation process). See also “Reregistering a JADE System in Batch Mode”, in Chapter 5.

To register the JADE database




JADEICG-6.3

2. Type the following.

export LD_LIBRARY_PATH=`pwd`/lib:$ LD_LIBRARY_PATH:/usr/lib

export NLSPATH=`pwd`/lib/nls/msg/%L/%N.cat:$NLSPATH

bin/jadregb ini=jade.ini path=system name='licence-name' key=00000000000000000000000000000000

Alternatively, if you define the JADE_REGNAME and JADE_REGKEY environment variables before you install JADE, the database is automatically registered as part of the installation process.

Setting Up the Windows Client After you have installed JADE on a server node running under Linux, you must then set up the client node with the appropriate information, as follows.

1. Enter the host name or IP number in the second part of the ServerNodeSpecifications parameter in the [ JadeClient] section of the JADE initialization file ( jade.ini) on the Windows client node. Alternatively, you can specify the server host name or IP number in the host parameter in the command line on the client node running under Windows.

2. Specify your port number in the third part of the ServerNodeSpecifications parameter in the [ JadeClient] section of the JADE initialization file ( jade.ini) on the Windows client node. For example:

ServerNodeSpecifications=tcpip,RH9node,devjade-sds

Alternatively, you can specify the port number in the port parameter in the command line on the client node running under Windows.


To upgrade from an existing JADE release to a new JADE release

1. Ensure that your JADE systems and data have been fully backed up.

Caution As with any upgrade, the database should not be in recovery state and you should perform a full and verified backup of the binaries and database before you upgrade.

2. Read any specific upgrade documentation before you proceed.

3. To upgrade your JADE installation to the new JADE release, use the jadeinstall –U or --Upgrade parameter, as shown in the following example.

/opt/jade/sbin/jadeinstall -i /home/jade -U -v 6.3.14.000 --all

The parameter values are as follows.

-i <dir> is the previously installed JADE directory

-v <version> is the new JADE version to be installed

--all indicates that all components previously installed into the directory specified in the -i parameter will be upgraded

The upgrade process copies over the new binaries and required system map files, resets timestamps, and performs any other steps necessary to complete the upgrade.



JADEICG-6.3

Caution As with any major JADE release, you must recompile any external method libraries with the new JADE release \include and \lib files before you attempt to run your upgraded JADE systems.

For more details, see “Installing JADE” and “Parameters for the jadeinstall Command”, earlier in this chapter. See also “Upgrading to JADE 6.3 from a Linux JADE 6.2.12 Release or Higher”, in the ReleaseInfo.pdf file on your JADE release medium.

Deinstalling JADE

To remove a JADE system installed using the jadeinstall program by deleting the files

Use the rm (remove) command, as follows.

rm –rf installation–directory

For example, the following command removes the myJade63 directory.

rm –rf myJade63

To remove a specific version of JADE that you installed using the rpm command

Use the rpm –e (that is, erase) short format, as follows.

rpm –e JADE-package-name

For details, see “Displaying the Packages Associated with a Specific JADE Version”, in the following subsection.

Alternatively, use the rpm –uninstall long format, as follows.

rpm --uninstall JADE-package-name

For example, the following command removes the rte JADE binaries for run time.

rpm --uninstall JADE-6.3.14.011--redhat-linux-ansi-rte.i686-1.rpm

For more details, see “JADE Product and RPM Names for Red Hat Linux”, earlier in this chapter.

Displaying the Packages Associated with a Specific JADE Version

To display the list of packages associated with a specific JADE version

Use the rpm query command to get a list of the package names associated with the JADE version, as follows.

rpm –qa --queryformat '%{name}\n'|grep JADE-version

For example, the following command displays the packages for JADE 6.3.14.008.

rpm –qa --queryformat '%{name}\n'|grep JADE-6.3.14.008


To obtain a core dump on Linux

1. For the user from which the process was initiated, check that the core file size ulimit setting is set to unlimited. (ulimit -a displays the current settings.)



JADEICG-6.3

To set ulimit for the core file size:

ulimit -c unlimited

2. Obtain the pid for the process that is to be dumped (see jadehome/tmp/program.pid).

3. From the jadehome directory, attach gdb to the process, dump the core file, and then detach the following from the process.

gdb --pid=pid (gdb) generate-core-file (gdb) detach (gdb) quit

The core file will be named core.pid.

Detailed Command Information for Red Hat Linux on Intel This section provides you with details about the commands and parameters that enable you to tailor the installation and configuration of JADE on UNIX.

Note You can use supplied shell scripts for JADE commands (for example, jadappb.sh or jaded.sh) so that your environment variables are set up for you.

If you want you want to install and configure JADE using the default values or you require information about the operational requirements, see “Installing JADE”, earlier in this chapter.

Environment Variables The environment variables in the following subsections apply to all JADE executable programs; for example, when running a non-GUI client using jadclient or when loading a schema and forms using jadloadb.

Required Environment Variables JADE executable programs (for example, jaded) expect and use the UNIX environment variables described in the following sections. The standard JADE installation process sets these variables automatically, under the control of the RPM.

JADEHOME

The JADEHOME environment variable is the directory in which JADE has been installed. As a minimum below this directory, there are the bin and lib subdirectories and often the system directory. This variable defaults to /opt/jade if it is not set. (See also “Directory Locations”, in Chapter 5.)


JADEHOME=/home/wilbur1/jade; export JADEHOME


setenv JADEHOME /home/wilbur1/jade



JADEICG-6.3

LANG

The LANG environment variable indicates the language and locale conventions that you want to use.

Note This variable, if set, cannot have .UTF-8 appended to the language.

Setting this variable affects all programs started by this process, including standard UNIX utilities. For details about JADE locales and translatable messages, see Chapter 12, “Internationalization”, in your JADE Development Environment User’s Guide.

See also the optional LC_CTYPE environment variable, later in this chapter.

LD_LIBRARY_PATH

The LD_LIBRARY_PATH environment variable is the standard UNIX environment variable that indicates the location of shared objects and libraries. This variable, which applies only to Linux, must include the lib directory of this JADE installation. (See also “Directory Locations”, in Chapter 5.)

To set this variable in the Bourne Again Shells (bash):

LD_LIBRARY_PATH=$JADEHOME/lib:$LD_LIBRARY_PATH:/usr/lib; export LD_LIBRARY_PATH


setenv LD_LIBRARY_PATH $JADEHOME/lib:$LD_LIBRARY_PATH:/usr/lib

NLSPATH

The NLSPATH environment variable is the standard UNIX environment variable that indicates the location of message catalogs and translatable messages.

Update this variable to include the message catalog directory.


NLSPATH=$JADEHOME/lib/nls/msg/%L/%N.cat:$NLSPATH; export NLSPATH


setenv NLSPATH $JADEHOME/lib/nls/msg/%L/%N.cat:$NLSPATH

PATH

The PATH environment variable is the standard UNIX environment variable that indicates the location of executable programs. (See also “Directory Locations”, in Chapter 5.)


PATH=$JADEHOME/bin:$PATH; export PATH


setenv PATH $JADEHOME/bin:$PATH



JADEICG-6.3

Optional Environment Variables The following UNIX environment variables are used by JADE executable programs. You do not have to change them, but the following examples make JADE easier to use if you do set them.

JADELANGDIR

The JADELANGDIR environment variable is used by JADE if it cannot find the message catalogs that it requires by using the standard UNIX NLSPATH environment variable.

The JADELANGDIR variable points directly to the directory that contains the messages catalogs, and ignores the value of the LANG environment variable.


JADELANGDIR=$JADEHOME/lib/nls/msg; export JADELANGDIR


setenv JADELANGDIR $JADEHOME/lib/nls/msg

LC_CTYPE

The LC_CTYPE environment variable indicates the character classification, case conversion, and other character attributes that you want to use.

Note This variable, if set, cannot have .UTF-8 appended to the character classification.

TMPDIR

The TMPDIR environment variable is a standard UNIX environment variable that indicates where temporary files are created.

JADE Daemon (jaded) The jaded program (the JADE daemon) is the JADE server implemented on UNIX, which can be run directly from the command line.

Starting JADE Daemon from the Command Line The following is the command line syntax required to start the JADE daemon.

jaded path=/database-path ini=JADE-initialization-file


The following is an example of the jaded command line.

jaded path=/usr/jade/system ini=/usr/jade/jade.ini

To stop it from the command line, press ^C or issue a kill command against the jaded process id from a different shell.



JADEICG-6.3

JADE Portable GUI (jadepg) The jadepg program is the standard fat client or JADE presentation client implementation of the JADE portable GUI implemented on UNIX, which can be run directly from the command line.


The jadepg program expects and uses the UNIX environment variables described in “Portable GUI Environment Variables” under “Portable GUI Configuration”, in Chapter 5. The sample shell script (that is, jadepg.sh in your bin directory) performs the required environment setup.

Starting the JADE Portable GUI from the Command Line The following is the command line syntax required to start the JADE portable GUI program.

jadepg path=/database-path schema=schema-name app=application-name ini=JADE-initialization-file


The following is an example of the jadepg command line.

jadepg path=/usr/jade/system schema=TestSchema app=TestSchemaApp ini=/usr/jade/jade.ini

To stop it from the command line, press ^C or issue a kill command against the jadepg process id from a different shell.

Running an Application Server Your JADE schemas and applications can be run in thin client mode from a UNIX application server simply by specifying the appropriate command line parameters and then invoking the application server on your UNIX host.

When this is running, you just specify the appropriate presentation client command line parameters on the Windows 2003 Server, Windows Vista, Windows XP, or Windows 2000 workstation that you want to run in thin client mode and then invoke the thin client executable program.

Notes JADE does not currently supply a facility to control the order in which services are started or stopped when the host computer is booted. If the application server is started before the database, a message is recorded in the JADE log file indicating that it cannot connect to the database.

If you want to install multiple application servers as services on the same host, you must have a separate JADE initialization file for each application server service because the service installation process must update a unique NodeName, NodeNameDescription, and RunAsService parameter in the [ JadeAppServer] section of the initialization file. Alternatively, you can prefix a section name with a unique identifier that is supported when a JADE program detects the optional name=unique-identifier command line parameter. For details, see “Sharing JADE Initialization Files” and “Two-Level Section Names”, in your JADE Initialization File Reference.



JADEICG-6.3

When you install JADE on a UNIX host, two subsystems are automatically created for you. For example, if your repackaged copy of JADE is called devdb, there will be a service called devdb that controls the database and a second service called devdb-app1 that controls the application server. The port numbers and database path details are listed at the end of the install process.

Invoking an Application Server The jadappb program is the JADE application server implemented on UNIX.

The following is the command line syntax required to run an application server on UNIX.

jadappb appServerPort=TCP/IP-communications-port-number path=/database-path ini=JADE-initialization-file-path [server=multiUser|singleUser|readOnlyUser] [host=host-server-node-name or host-IP-address] [port=host-port-name or host-port-number] [interface=client-TCP/IP-name or client-IP-address] [localport=client-port-name or client-port-number] [endJade] optional-user-defined-parameters


appServerPort TCP/IP communications port number (mandatory) AppServerPort=1500



[server] Server type server=multiUser (default value)






For details about these parameter values, see “Running an Application Server in Batch Mode”, in Chapter 2 of your JADE Thin Client Guide. (Note, however, that the virgule, or forward slash, separator ( /) is used in file and directory paths in the UNIX operating system, in contrast to the backslash character ( \) used as a separator in file and directory path names on a workstation running under a Microsoft Windows operating system.)


Specify the server parameter only if you want to run the application server in single user mode. (If you do not specify the server parameter, the application server runs in multiuser mode.) The jadappb program uses the parameters in the [ JadeAppServer] section of the JADE initialization file. When you have invoked your application server, you can then initiate your JADE presentation clients. If the jadappb program fails, a non-zero exit code is returned and an error message is displayed; for example, if the database directory was invalid.



JADEICG-6.3

Running a Non-GUI Client Application You can run a non-GUI client JADE application (defined as application type Non-GUI in the Define Application dialog) on UNIX simply by specifying the appropriate command line parameters to invoke the non-GUI client application on a UNIX host, to add processing nodes to your JADE network.

A non-GUI client application runs on the node on which the Application class startApplication method is executed (that is, if the startApplication method is executed on a server node, the application is started on that server node).

Notes JADE does not currently supply a facility to control the order in which services are started or stopped when the host computer is booted. If the application server is started before the database, a message is recorded in the JADE log file.

If you want to install multiple non-GUI client applications as services on the same host, you must have a separate JADE initialization file for each non-GUI application service, because the service installation process must update a unique NodeName, NodeNameDescription, and RunAsService parameter in the [NonGuiClient] section of the initialization file. Alternatively, you can prefix a section name with a unique identifier that is supported when a JADE program detects the optional name=unique-identifier command line parameter. For details, see “Sharing JADE Initialization Files” and “Two-Level Section Names”, in your JADE Initialization File Reference.

For details about increasing the time JADE waits for an application to initiate on another thread before raising an exception when your system has a large number of applications to start, see the MaxWaitAppStart parameter in the JADE initialization file [ JadeServer] section, in your JADE Initialization File Reference. The jadclient executable program that enables you to automate the running of non-GUI client applications on UNIX is installed with your JADE software. (For details about using non-GUI client applications to automate the extraction of schemas, see “Extracting Schemas as a Non-GUI Client Application”, in Chapter 11 of your JADE Development Environment User’s Guide.)

Invoking a Non-GUI Client Application The following is the command line syntax required to run the jadclient program on UNIX.

jadclient schema=schema-name app=application-name path=/database-path ini=JADE-initialization-file-path [causeEventOnSystem=[cause-event-number]] [server=multiUser|singleUser|readOnlyUser] [host=host-server-node-name or host-IP-address] [port=host-port-name or host-port-number] [interface=client-TCP/IP-name or client-IP-address] [localport=client-port-name or client-port-number] [endJade]



schema Schema name (mandatory) ASchema

app Application name (mandatory application of type Non_GUI) NonGUIApp or Non_GUI_Web)



JADEICG-6.3




[causeEventOnSystem] External user event caused on the JADE System object, 12345 and if specified, can optionally contain a numeric value

[server] Server type (that is, mode in which the application runs) server=multiUser (default value)






For details about these parameter values, see “Running a Non-GUI Client Application using jadclient”, in Chapter 1 of your JADE Runtime Application Guide. Note, however, that the service, nodeName, and nodeNameDescription parameters do not apply when running a non-GUI client application on UNIX, as a non-GUI client application is installed on UNIX as a subsystem, which is itself a service.

In addition, the virgule, or forward slash, separator ( /) is used in file and directory paths in the UNIX operating system, in contrast to the backslash character ( \) used as a separator in file and directory path names on a workstation running under a Microsoft Windows operating system.

Note The jadclient program treats processing arguments enclosed in double (" ") or single (' ') quotation marks after the endJade parameter as single-string entries in the huge string array. The handling of strings in this huge string array is application-specific. For example, path= "program files" is treated as a two-string entry and "path= program files" is treated as a one-string entry. How these entries are handled is determined by your application.

The non-GUI client application program displays a progress report as the application initializes. Standard initialization information is output to stdout and error information is output to stderr. If the jadclient program fails, a non-zero exit code is returned and an error message is displayed; for example, if the schema is invalid or you attempt to remove a service that is not installed.

The jadclient program uses the parameters in the [NonGuiClient] section of the JADE initialization file.

Initiating Non-GUI Applications when the Application Server is Initiated

Use the ServerApplication parameter in the [NonGuiClient] section of the JADE initialization file to specify a non-GUI client application that is executed when the server or application server node initializes.





JADEICG-6.3

Initiating Non-GUI Applications at a Specific Time

Specify the optional time variable in the [NonGuiClient] section of the JADE initialization file to specify a non-GUI client application that is executed at a specified time.



Java Framework You must set up the JADE environment to run Java applications that interact with JADE. The eclipse.sh and java.sh linked sample scripts are provided to set up the JADE environment and run Eclipse or Java. These scripts assume that the eclipse and java commands will execute the required executables. You can set up a similar script for other required Java development environments.

Before running java.sh, you must set up the Java CLASSPATH environment variable to specify the location of the Java user classes.

Locales and Translatable Messages The Microsoft Windows implementations of JADE supplies the jadmsgs.eng file that maps error numbers to error messages. This enables you to translate and extend error messages for users of deployed JADE applications.

The UNIX implementation of JADE uses the jadmsgs message catalog instead of the jadmsgs.eng file. (The jadmsgs.eng file is supplied but is not used.)

The selection of which jadmsgs message catalog to use is determined by a combination of the LANG, NLSPATH, and JADELANGDIR environment variables.

If messages need to be translated, the following command generates a standard text file that can be edited as required.

dspcat –g ./jadmsgs.cat > jadmsgs.msg

Set 1 is used for error numbers that are positive and set 2 is used for negative error numbers. As message catalog message numbers can only be positive, the message number in set 2 is the absolute value of the error number.

To generate a new message catalog from the edited jadmsgs.msg file, use the following command.

gencat jadmsgs.cat jadmsgs.msg

When you have generated your new message catalog, place the new jadmsgs.cat catalog in the $JADEHOME/lib/nls/msg/$LANG/ directory to which the translated file belongs.

Locales The internal translation table lists the LANG variables and their LCID descriptive names. This table is used if the [LANG2LCID] section in the JADE initialization file does not contain a value that matches the LANG environment variable.



JADEICG-6.3

JADE internally performs the following actions to map the LANG variable to a Microsoft LCID number.

If the language and country portions of the LANG variable match, the matching LCID number is used.

If only the language matches, the primary LCID language is used with the sublanguage of SUBLANG_NEUTRAL.

If neither the language nor the country portion matches, the LCID number is set to 1033 English (USA).

The first letter of the LANG environment variable is changed to a lowercase character and then looked up in the following internal translation table.


af 54 Afrikaans

ar 1 Arabic (Saudi Arabia)

ar_AE 20481 Arabic (United Arab Emirates)

ar_BH 21505 Arabic (Bahrain)

ar_DZ 5121 Arabic (Algeria)

ar_EG 3073 Arabic (Egypt)

ar_IQ 2049 Arabic (Iraq)

ar_JO 17409 Arabic (Jordan)

ar_KW 19457 Arabic (Kuwait)

ar_LB 18433 Arabic (Lebanon)

ar_LY 4097 Arabic (Libya)

ar_MA 6145 Arabic (Morocco)

ar_OM 8193 Arabic (Oman)

ar_QA 22529 Arabic (Qatar)

ar_SY 16385 Arabic (Syria)

ar_TN 7169 Arabic (Tunisia)

ar_YE 9217 Arabic (Yemen)

be 35 Byelorussian

bg_BG 2 Bulgarian

c 2048 LANG_NEUTRAL/SUBLANG_SYS_DEFAULT

ca_ES 3 Catalan

cs_CZ 5 Czech

da_DK 6 Denmark

de 7 German

de_AT 3079 German (Austrian)

de_CH 2055 German (Swiss)

de_DE 1031 German (Germany)

de_LI 5127 German (Liechtenstein)

de_LU 4103 German (Luxembourg)

el_GR 8 Greek

en 9 English

en_AU 3081 English (Australian)



JADEICG-6.3


en_CA 4105 English (Canadian)

en_GB 2057 English (UK)

en_IE 6153 English (Irish)

en_JM 8201 English (Jamaica)

en_NZ 5129 English (New Zealand)

en_US 1033 English (USA)

en_ZA 7177 English (South Africa)

es 10 Spanish

es_AR 17418 Spanish (Argentina)

es_BO 22538 Spanish (Bolivia)

es_CL 19466 Spanish (Chile)

es_CO 9226 Spanish (Colombia)

es_CR 5130 Spanish (Costa Rica)

es_DO 7178 Spanish (Dominican Republic)

es_EC 18442 Spanish (Ecuador)

es_ES 1034 Spanish (Castilian)

es_GT 4106 Spanish (Guatemala)

es_MX 2058 Spanish (Mexican)

es_PA 6154 Spanish (Panama)

es_PE 16394 Spanish (Peru)

es_PY 21514 Spanish (Paraguay)

es_UY 20490 Spanish (Uruguay)

es_VE 8202 Spanish (Venezuela)

et_EE 37 Estonian

eu 45 Basque

fa_FA 41 Farsi / Persia

fi_FI 11 Finnish

fo_FO 56 Faroese

fr 1036 French

fr_BE 2060 French (Belgian)

fr_CA 3084 French (Canadian)

fr_CH 4108 French (Swiss)

fr_FR 12 French (France)

fr_LU 5132 French (Luxembourg)

he 13 Hebrew (formerly iw)

hr_HR 26 Croatian

hu_HU 14 Hungarian

id_ID 33 Indonesian

is_IS 15 Icelandic

it 1040 Italian

it_CH 2064 Italian (Swiss)

it_IT 16 Italian (Italy)

ja_JP 17 Japanese



JADEICG-6.3


ko 18 Korean

ko_KP 2066 Korean (Johab)

ko_KR 1047 Korean (Korea)

lt_LT 39 Lithuanian

lv_LV 38 Latvian, Lettish

nl 19 Dutch

nl_BE 2067 Dutch (Belgian)

nl_NL 1043 Dutch (Holland)

no 20 Norwegian

no_NO 20 Norwegian (Norway)

pl_PL 21 Polish

pt 22 Portuguese

pt_BR 1046 Portuguese (Brazilian)

pt_PT 2070 Portuguese (Portugal)

ro_RO 24 Romanian

ru_RU 25 Russian

sk_SK 27 Slovak

sl_SI 36 Slovenian

sq_AL 28 Albanian

sr_SR 46 Serbian

sv_CH 29 Swedish

th_TH 30 Thai

tr_TR 31 Turkish

uk_UA 34 Ukrainian

zh 4 Chinese

zh_CH 4 Chinese (China)

zh_CN 2052 Chinese (PR China)

zh_HK 3076 Chinese (Hong Kong)

zh_SG 4100 Chinese (Singapore)

zh_TW 1028 Chinese (Taiwan)

To allow consistent locale handling behavior between Microsoft Windows and UNIX, the supplied locbuild program (both in source code and the Windows executable) was used to step through all installed locales on a development machine to create the locales.msg file. (For details about the locbuild program, see /usr/jade/tools on the JADE CD-ROM.)

Each set number corresponds to an LCID value, and the message number corresponds to each LCTYPE value.

In simplified terms, the reimplementation of the Microsoft Windows GetLocaleInfo(LCID, LCTYPE, LPTSTR, int) API call uses the LCID as the set number and LCTYPE as the message number, and performs a UNIX catgets (locales_cat, LCID, LCTYPE, default) API call.



JADEICG-6.3

If you want to add additional locale support or alter the current information, you can use the supplied locbuild program to create a new locales.msg file on a Windows host that has your required locale installed, as follows.

locbuild > locales.msg

Alternatively, on a UNIX host you can:

1. Convert the locales.cat catalog to a text file, as follows.

dspcat –g ./locales.cat > locales.msg

2. Edit the contents to meet your requirements.

3. Recreate the locales.cat file, as follows.

gencat locales.cat locales.msg

Note When copying the generated locales.msg file from a Microsoft Windows host to UNIX, you must change the CR/LF (carriage return/linefeed) line terminators to LF (linefeed).

____________________________________

JADEICG-6.3

Chapter 5 Configuring JADE

____________________________________ This chapter covers the following topics.

Example Production System Configurations

Directory Locations

Configuring Your Network Protocol

Selecting Network Addresses

Local Intra-Machine Transport

Connecting to JADE Applications from Internet Information Server (IIS)

Connecting to JADE Applications from an Apache HTTP Server

Configuring Your JADE Software

Portable GUI Configuration

Configuring JadeHttp for Remote Connections

– Firewall for the JADE Internet Environment

– Controlling the Location of Files Uploaded via a Web Application

– [application-name] Section

– [Jadehttp Files] Section

– [Jadehttp Logging] Section

Configuring Apache for Remote Connections

Tuning Your Systems

Specifying Parameters in the JADE Command Line

Specifying Your Administration Options

Reregistering a JADE System in Batch Mode

Using the JADE Version Information Utility


Chapter 5 Configuring JADE 101

JADEICG-6.3

Example Production System Configurations The following table represents some business-critical production system hardware configurations as at July 2007. These are intended as indicative examples only. More-powerful configurations may be required, depending on the scale of your JADE applications and the performance requirements of your system.

Note In the following table, all CPUs are Intel or Intel-compatible.

Peak Users Nodes Database Size Hardware Description

8 1 5G bytes Single server

1 x Single core 1 GHz CPU

2G bytes ECC RAM

2 x 72G bytes 15K drives (database/OS)

2 x 72G bytes 15K drives (journals/backup)


1 x Dual Core 1 GHz CPU

2.5G bytes ECC RAM

2 x 72G bytes 15K drives (database/OS)

2 x 72G bytes 15K drives (journals/backup)

190 20 80G bytes Two servers, clustered, each server with:

2 x single core 3.4 GHz CPUs with Hyperthreading

5G bytes ECC RAM

2 x 72G bytes 15K drives (OS/workspace)

Storage Area Network (SAN) containing:

8 x 72G bytes 15K drives (database)

2 x 144G bytes 15K drives (journals)

4 x 300G bytes 15K drives (backup)


4 x single core 3 GHz CPUs with Hyperthreading

7.5G bytes ECC RAM


2 x 144G bytes 15K drives (journals)

8 x 144G bytes 15K drives (backup)


8 x single core 3 GHz CPUs

20G bytes ECC RAM


SAN containing:


20 x 144G bytes 15K drives (backup/journals)



JADEICG-6.3

Peak Users Nodes Database Size Hardware Description

200 17 250G bytes Two servers, clustered, each server with:

8 x single core 2 GHz CPUs

6G bytes ECC RAM


SAN containing:

20 x 72G byes 15K drives (database)

20 x 144G bytes 15K drives (backup/journals)

Directory Locations In conjunction with support for JADE running on the Microsoft Windows Vista operating system, you can install JADE under the \Program Files directory. (

The ability to return locations other than the JADE HOME directory for program and user data requests is dependent on where the JADE binaries have been installed. If the JADE programs are not installed in the system-wide location for installed applications (\Program Files on Windows and /opt on UNIX), returning alternate addresses is not implemented.

It is assumed that the programs installed in custom locations have sufficient security privileges to work in the style of earlier JADE 6.1 and JADE 6.2 releases.

Although the alternate names and locations are driven by Windows Vista requirements, the code is portable across Windows and UNIX-based implementations.

Because security restrictions can deny appropriate access to directories or the directories are a unique location for each user, the Node and Process classes provide methods that enable you to access other directory locations in the file system hierarchy. In addition, the [ JadeEnvironment] section of the JADE initialization file provides the JadeWorkDirectory, ProgramDataDirectory, and UserDataDirectory parameters, which enable you to specify the location of JADE work files, program data, and user data, respectively.

In the methods summarized in the following subsections, a method on a specific:

Node instance performs its action on the specified node instance, which does not have to be the current node. If the current node is required, use the node environmental object (system variable).

Process instance performs its action on the owning node (that is, a Process.node instance) if the process is not associated with a presentation client. If the process has an associated presentation client, the action is performed on the presentation client. The presentation client does not have to be the current presentation client or a presentation client attached to the same application server.

For details, see Volume 1 and Volume 2 of the JADE Encyclopaedia of Classes and “JADE Environment [ JadeEnvironment] Section”, in the JADE Initialization File Reference.



JADEICG-6.3

Installation Directory Location The getJadeInstallDirectory method defined in the Node and Process classes returns a string containing the directory in which the executable of the current executing program is located; that is, the directory in which the JADE binaries are installed.

See also “Work File Directory Location”, later in this chapter.

Home Directory Location The getJadeHomeDirectory method defined in the Node and Process classes returns a string containing the parent directory of the installation directory.

Program Data Directory Location The getProgramDataDirectory method defined in the Node and Process classes returns a string containing the program data directory, which is dependent on the:

Value of the ProgramDataDirectory parameter in the [ JadeEnvironment] section of the JADE initialization file. The parameter is read each time the getProgramDataDirectory method is called. When you call this method and the directory does not already exist, JADE creates it based on the value of the ProgramDataDirectory parameter.

Location of the installation directory.

Files that should be placed under the returned location are entities that should be shared across multiple users of these binaries; for example, the jommsg.log file or shared dictionary spelling files that are updated.

If the installation directory is a subdirectory of the programmatically determined location of \Program Files on Windows or the fix value /opt on Linux, translation rules are applied. However, if the installation directory is not a subdirectory of the respective \Program Files or /opt location, the return value is the same as the JADE HOME directory.

The ProgramDataDirectory parameter in the [ JadeEnvironment] section of the JADE initialization file can have one the following values.

<default>, which is the default value

On a machine running a Windows release earlier than Windows Vista, the <default> value has the same meaning as the <homedir> value. On a machine running Windows Vista or Linux, the <default> value has the same meaning as the <programdata> value.

<homedir>

The value of the JADE HOME directory is returned.

<programdata>

On a machine running Windows, the \Program Files portion of the HOME directory is replaced with the programmatically obtained location for the common application data directory. For example, a presentation client installed into \Program Files\Jade Software Corporation\parsys returns \Documents and Settings\All Users\Application Data\Jade Software Corporation\parsys if running on a Windows operating system earlier than Vista, or \ProgramData\Jade Software Corporation\parsys if running on Windows Vista.



JADEICG-6.3

On a machine running Linux, the /opt portion of the HOME directory is replaced with /var/opt. For example, a presentation client installed into /opt/jade/parsys returns /var/opt/jade/parsys as the program data directory.

A user-specified directory name, which returns the specified directory

An existing system on Windows functions as it did in earlier JADE releases. There is no difference in behavior unless the system is running on Windows Vista and it was installed under the \Program Files directory. There is no difference in behavior on a Linux-based system unless it was installed under the /opt directory.

The directory location is created, if necessary, and returned in the required format.

User Data Directory Location The getUserDataDirectory method defined in the Node and Process classes returns a string containing the user data directory, which is dependent on the:

Value of the UserDataDirectory parameter in the [ JadeEnvironment] section of the JADE initialization file. The parameter is read each time the getUserDataDirectory method is called. When you call this method and the directory does not already exist, JADE creates it based on the value of the UserDataDirectory parameter.

Location of the installation directory.

Files that should be placed under the returned location are entities that should be unique to each user of these binaries; for example, if a presentation client installation occurs on a Windows machine running Citrix or Terminal Services and all users run the same thin client binaries, any data created on the client file system should be stored under this location (that is, unique dictionaries for each user).

If the installation directory is a subdirectory of the programmatically determined location of \Program Files on Windows or the fix value /opt on Linux, translation rules are applied. However, if the installation directory is not a subdirectory of the respective \Program Files or /opt location, the return value is the same as the JADE HOME directory.

The UserDataDirectory parameter in the [ JadeEnvironment] section of the JADE initialization file can have one the following values.

<default>, which is the default value

On a machine running a Windows release earlier than Windows Vista, the <default> value has the same meaning as the <homedir> value. On a machine running Windows Vista or Linux, the <default> value has the same meaning as the <userdata> value.

<homedir>

The value of the JADE HOME directory is returned.



JADEICG-6.3

<userdata>

On a machine running Windows, the \Program Files portion of the HOME directory is replaced with the programmatically determined location for the specific user application private data directory. For example, a presentation client installed into \Program Files\Jade Software Corporation\parsys and executed by user wilbur returns \Document and Settings\wilbur\Application Data\Jade Software Corporation\parsys if running on a Windows operating system earlier than Vista, or \Users\wilbur\AppData\Local\Jade Software Corporation\parsys if running on Windows Vista.

On a machine running Linux, the /opt portion of the HOME directory is replaced with the user-specific location of /home/user-name/.jade. For example, a presentation client installed into /opt/jade/parsys and executed by user wilbur returns /home/wilbur/.jade/jade/parsys as the user data directory.

A user-specified directory name, which returns the specified directory

An existing system on Windows functions as it did in earlier JADE releases. There is no difference in behavior unless the system is running on Windows Vista and it was installed under the \Program Files directory. There is no difference in behavior on a Linux-based system unless it was installed under the /opt directory.

The directory location is created, if necessary, and returned in the required format.

Work File Directory Location The getJadeWorkDirectory method defined in the Node and Process classes returns a string containing the JADE work directory, which is dependent on the:

Value of the JadeWorkDirectory parameter in the [ JadeEnvironment] section of the JADE initialization file. The parameter is read each time the getJadeWorkDirectory method is called and the directory is accessed. When you call this method and the directory does not already exist, JADE creates it based on the value of the JadeWorkDirectory parameter.

Location of the JADE HOME directory.

By default, the jade.exe and jadepg executable program files do not directly create or update files in the binary directory.

The JadeWorkDirectory parameter in the [ JadeEnvironment] section of the JADE initialization file determines the directory in which work files are created. By default, this directory is created at the same level as the JADE binary directory and is named temp on Windows and tmp on Linux. For example, the directory is named c:\ Jade\temp if the JADE installation directory is c:\ Jade\bin on Windows.

The JadeWorkDirectory parameter can specify an absolute path or a relative path (relative to the JADE HOME directory, which is c:\ Jade in the above example).

The presentation cache file is written into the directory defined by the value of the JadeWorkDirectory parameter unless the FormCacheFile parameter in the [ JadeThinClient] section of the JADE initialization file specifies the location of the form cache file.

The presentation client automatic download process lock files are created in the directory specified by the JadeWorkDirectory parameter.



JADEICG-6.3

The automatic presentation client download log file is written to the location specified by the LogDirectory parameter in the [ JadeLog] section of the JADE initialization file.

The only situations in which a file creation or update will occur within the JADE binary directory are as follows.

If the JADE initialization file is positioned in the binary directory (the default action for a presentation client). You can avoid this by using the ini parameter in the JADE presentation client command line to specify an alternate location on initiation of the presentation client.

When the jaddinst executable program installs files downloaded by the JADE thin client automatic download facility.

Configuring Your Network Protocol TCP/IP is required for multiuser configurations. TCP/IP must be installed on each workstation that is to participate as a node in the JADE environment. Your network manufacturer supplies TCP/IP and your network administrator supplies the TCP/IP address.

JADE also provides a fast local intra-node transport for JADE modules on the same machine. (For details, see “Local Intra-Machine Transport”, later in this chapter.) Use the NetworkSpecification parameter in the [ JadeServer] section of the JADE initialization file to specify the transport types used by a JADE server. Use the ServerNodeSpecifications parameter in the [ JadeClient] section of the JADE initialization file to specify the transport type used by a JADE client to connect to the server in.

Selecting Network Addresses Use the reserved range of Class C network addresses if you want to set up a small private network for demonstration purposes. (The reserved private Class C network addresses are in the range 192.168.0 through 192.168.255, and are often used for broadcast messages.) If you therefore select network number 192.168.1, for example, you can then assign all IP addresses for your host in the range 192.168.1.1 through 192.168.1.254.

Ensure that the first three parts of this address are the same for all interfaces connected to the same LAN segment, and set the subnet mask to 255.255.255.0.

Tip Choose a reserved private Class C IP address when one or more of the workstations also needs to connect to the Internet by using an Internet Service Provider (ISP). If you use these reserved addresses, they should not conflict with any valid Network Interface Controller (NIC)-assigned Internet addresses. Avoid using random numbers for IP addresses, as this usually fails.

When you have configured your network and IP addresses, check that workstations can see each other using the IP protocol.

A simple test is to use ping from a command prompt, by entering one or both of the following command prompts from any workstation:

ping computer-name

ping remote-IP-address

If this does not provide a response, you will not be able to use the specified workstation name as the server node name in the ServerNodeSpecifications parameter of the [ JadeClient] section of your JADE initialization file.



JADEICG-6.3

If the IP is functioning correctly and the ping remote-IP-address command prompt provides a positive response, setting the ServerNode parameter to the server node IP address value in the ServerNodeSpecifications parameter in the [ JadeClient] section of your JADE initialization file should work. Setting this ServerNode parameter to the workstation name of the server node may not always work even if the ping server-node-computer-name command prompt gives a valid response, as this alias to standard TCP/IP cannot always be relied on to work.

If you do not have Windows Internet Naming Services (WINS) or a Domain Name Server (DNS) server, you should set up a hosts file with IP address-to-name mappings and then use the names from there. If you have a small single-segment LAN and you do not know what Dynamic Host Configuration Protocol (DHCP)/DNS or WINS are, do not use them for your local networking. Only an experienced network administrator should set these up. (If you have Internet access, you will almost certainly have DNS configured.)

Local Intra-Machine Transport JADE provides a fast transport mechanism between JADE modules on the same machine (for example, one that has multiple CPUs).

As JADE database servers and JADE application servers can often reside on the same machine, you can use local intra-machine transport to significantly improve performance. You can also use this transport mechanism to communicate from standard (fat) clients and JADE application servers to JADE servers if these processes run on the same physical machine, to significantly improve overall performance. Intra-machine local transport uses shared memory on Windows and domain sockets on UNIX.

Note Local intra-machine transport is used only when the transport type is defined as JadeLocal on both the server and client and the network state on the server is defined as enabled.

To detect whether a connection has been lost, a polling mechanism ensures that some minor communication is taking place regularly. See also “SharedMemoryTransportIdlePollInterval” under “JADE Object Manager Server Section [ JadeServer]”, in your JADE Initialization File Reference.

You can enable local intra-machine transport only by specifying the appropriate JADE initialization file parameters (that is, the NetworkSpecification parameter in the [ JadeServer] section and the ServerNodeSpecifications parameter in the [ JadeClient] section). You cannot do so from the JADE Remote Node Access utility (that is, from jadrap).

The JadeLocal transport between the JADE database and application servers and standard clients is implemented by the use of shared memory and global events and semaphores on Windows Vista. Vista does not allow objects to be created in the Global namespace without a specific privilege that is not available to a standard user.

The optional base-name value of the NetworkSpecification parameter in the [ JadeServer] section and the ServerNodeSpecifications parameter in the [ JadeClient] section of the JADE initialization file can have an optional Local\ or Global\ prefix. If the prefix is absent on Windows XP, it defaults to Global\, which retains the behavior of earlier JADE releases. On Vista, it defaults to Local\, which is consistent with running with the least-privileges mode. The following discussion is based on the use of the JadeLocal transport feature on Vista.



JADEICG-6.3

When running under Vista as a standard user, the value of the base-name variable is created in the Local\ or session namespace, which means that all JADE programs must be running as the same user logon and also in the same Windows session, to be able to connect to this RPC transport. For example, if the database is installed as a service, all application servers and standard clients wanting to connect to this database via JadeLocal transport must also be running as services and under the same user logon.

If you require the Windows XP behavior of JadeLocal from earlier releases under Windows Vista, you require the following configuration and setup. Change the following configuration parameters in the respective [ JadeServer] and [ JadeClient]sections of the JADE initialization file.

NetworkSpecification<n>=JadeLocal,Enabled,Global\basename

ServerNodeSpecifications=JadeLocal,Global\basename

In addition, your Windows administrator must configure the user logon to add the following Windows privilege Create global objects (SeCreateGlobalPrivilege at the programming API level), which can be done directly to the user logon or to a group of which that user is a member. On a machine that is not part of a Windows domain, this can be done by accessing the Local Security Policy in the Administrative tools directory and adding the Create global objects policy under Local Policies / User Rights Assignment to the desired group or user.

These changes allow JADE programs that need to connect via the JadeLocal intra-machine transport to work across multiple Windows sessions or user logons.

If a standard user attempts to create a Global\basename value in either of these initialization file parameters, it fails because of insufficient privileges.

Connecting to JADE Applications from Internet Information Server (IIS) Your connections from the Internet Information Server (IIS) to JADE applications is via a TCP/IP connection. (For more details, see “Configuring JadeHttp for Remote Connections”, later in this chapter.)

To implement a TCP/IP connection from IIS to JADE release 6.3 applications, define a section within the jadehttp.ini file for each application, with the ApplicationType parameter and unique multiple TcpPort[n], MinInUse[n], MaxInUse[n], TcpConnection[n], CloseDelay[n], and ConnectionGroup[n] parameters within each [application-name] section. Set the ApplicationType parameter in each [application-name] section to WebEnabledForms, WebServices, or HtmlDocuments.

The following is an example of these parameters.

[HtmlCompany] ApplicationType = HtmlDocuments TcpConnection = Host1a TcpPort = 22000 MinInUse = 2 MaxInUse = 10 CloseDelay = 600 TcpConnection2 = Host2a TcpPort2 = 22001 MinInUse2 = 2 MaxInUse2 = 10 CloseDelay2 = 600



JADEICG-6.3

For NamedPipe connections to JADE 6.3 applications from IIS, you must define a section within the jadehttp.ini file for each application. Set the ApplicationType parameter in each [application-name] section of the jadehttp.ini file to Jade61.

If you upgrade the jadehttp.dll to JADE 6.3 but not a JADE 6.2 application, you must define a section within the jadehttp.ini file for each application with the ApplicationType parameter in each [application-name] section of the jadehttp.ini file set to Jade61 so that the application will run in a JADE 6.3 environment. In addition, each [application-name] section of the jadehttp.ini file requires the following parameters for JADE 6.1 functionality.

1. TcpConnection[n]=tcp-address

2. FirstTcpPort[n]=first-tcp-port-number-in-the-available-range

3. LastTcpPort[n]=last-tcp-port-number-in-the-available-range

As the LastTcpPort[n] parameter is optional in JADE 6.1 application, only one TCP/IP port is used if this value is not present. The following is an example of these parameters.

[CustomerApp] ApplicationType = Jade61 TcpConnection = 143.67.78.90 FirstTcpPort = 6014 LastTcpPort = 6016

Each connection to the application uses one of the connection numbers in that range. The jadehttp library attempts to open a connection to each of those port numbers and keeps attempting to open them when no free connections are available. Your port number range should therefore reflect exactly the number of connections that will be opened by the JADE application (or copies of the JADE application).

Notes If the [application-name] section of the jadehttp.ini file has the ApplicationType parameter set to Jade61 and it does not contain a TcpConnection[n] parameter, the connections are opened using named pipe connections.

As a named pipe deals only with messages and cannot read the data in small pieces, we therefore recommend that you use a TCP/IP connection instead of a named pipe connection. (TCP/IP connections are also slightly faster than named pipe connections.)

The jadehttp.dll provides support for JADE 6.1 and JADE 6.2 Web applications, with the valid combinations listed in the following table.

Node ApplicationType TCP/IP Named Pipe

JADE 6.1 Jade61 JADE 6.1 jadehttp.ini file values JADE 6.1 jadehttp.ini file values

JADE 6.2 Jade61 Single port number, single connection, Web services only JADE 6.1 jadehttp.ini file values

JADE 6.2 WebServices Single port number, multiple connections, Not allowed HtmlDocuments all Web applications WebEnabledForms



JADEICG-6.3

Application Requirements for a Jade61 Application Type To use a TCP/IP connection rather than a named pipe if the [application-name] section of the jadehttp.ini file has the ApplicationType parameter set to Jade61, you must make the following changes to your application.

1. Change the value in the Connection Name text box of the Application Definition dialog Web Options sheet to the <TCP-address>:<starting-port-number>.

The following is an example of a value in the Connection Name text box.

143.67.78.90:6014

2. The number of copies specified in the Application Copies text box of that dialog then determines the end port number of the range. For example, three copies would mean the last TCP/IP port number is 6016 when using the starting port number of 6014.

3. If your application has subclassed the InternetPipe class, you must replace it with a subclass of the JadeInternetTCPIPConnection class. Each connection that is created and opened needs to be assigned one of the port numbers in the defined range.

Standard JADE Web applications start a new copy of the application for the defined number of copies and each copy is assigned one of the TCP/IP port numbers.

Connecting to JADE Applications from an Apache HTTP Server Your connections from the Apache HTTP Server to JADE applications can be via a TCP/IP connection only. The design and configuration of the mod_jadehttp module fully conforms to Apache HTTP Server 2.2 module usage and configuration practices.

You can obtain more information about the Apache Software Foundation from one of the following Web sites.

http://www.apache.org

http://httpd.apache.org

JADE supports the Apache HTTP Server by supplying mod_ jadehttp for Linux and Windows operating systems. Only JadeInternetTCPIPConnection class TCP/IP communications are supported for all versions of mod_ jadehttp, regardless of the operating system; that is, TCP/IP connections only are used for connections to JADE applications running under a Windows or Linux operating system from the Apache HTTP Server. For details, see “Using the mod_ jadehttp Module”, in the following subsection.

The mod_ jadehttp library module supplied by JADE for the Apache HTTP Server implements support for the following Multi-Processing Modules (MPMs). The selection of the default MPM is selected based on the operating system on which the Apache server is running, as follows.

mpm_winnt, which is the default value for Microsoft-based operating systems.

prefork, which is the default value for UNIX-based operating systems (that is, Linux).

If you build the Apache server from source code, you can build and select whichever MPM you want to use, on the operating system of your choice.

http://www.apache.org/

http://httpd.apache.org/



JADEICG-6.3

Some relevant MPMs with respect to JADE and the mod_ jadehttp library are listed in the following table.

Multi-Processing Module (MPM) Implements a …

mpm_winnt Multiple-threaded single process Web server

prefork Non-threaded, pre-forking Web server

worker Hybrid multiple-threaded multiple-process Web server

The mod_ jadehttp module ensures that the same destination IP address and port number combination are used for a specific logical connection, by using the hidden fields that both the jadehttp and the mod_ jadehttp libraries insert into the HTML data.

The mod_ jadehttp library module provides support for JADE 6.1 and JADE 6.2 Web applications, with the valid combinations of the ApplicationType directive values listed in the following table.

Node ApplicationType Directive Value TCP/IP

JADE 6.1 Jade61 JADE 6.1 mod_ jadehttp configuration directive values

JADE 6.2 Jade61 Single port number, single connection, Web services only

JADE 6.2 WebServices, HtmlDocuments, WebEnabledForms Single port number, multiple connections, all Web applications

To install the mod_ jadehttp module

Copy the mod_ jadehttp.so file into the modules directory of your Apache HTTP Server.

Notes The name mod_ jadehttp.so applies to all operating systems.

Ensure that you use the correct operating system binary.

Apache and the HTTP generally use UTF-8 as the encoding scheme for Unicode data on the Web. As mod_ jadehttp currently does not allow for this and it passes the data directly to JADE, only ANSI data can be read from or written to the JadeInternetTCPIPConnection object.

For details about configuring the Apache HTTP Server, see “Configuring Apache for Remote Connections”, later in this chapter.

Using the mod_ jadehttp Module JADE on Linux Intel includes mod_ jadehttp32.so and mod_ jadehttp64.so, for the 32-bit and 64-bit version of Apache 2.2.3, respectively.

To use the mod_ jadehttp module

1. Ensure that you are running Apache 2.2.3 or a higher 2.2.n version. (Apache 2.2.3 is the default version installed on SLES10 and RHEL5.)

2. Determine whether 32-bit or 64-bit Apache is installed. (If the operating system installation is a 64-bit version, it is most likely that Apache is also the 64-bit version.)

3. Load the correct mod_ jadehttp module into Apache. Note that path names in following examples may differ from those in your environment.



JADEICG-6.3

For 32-bit versions of Apache:

LoadModule jadehttp_module modules/mod_jadehttp32.so

For 64-bit versions of Apache:

LoadModule jadehttp_module modules/mod_jadehttp64.so

Configuring Your JADE Software The JADE initialization file, which enables you to configure JADE to your requirements, contains:

[ Jade] section, which contains information that customizes the start-up image that is displayed when JADE opens the database and initializes the application.

[ JadeCommandLine] section, which contains information that would normally be placed on the command line.

[ JadeCompiler] section, which contains information that controls the logging of compiler warnings.

[ JadeClient], [ JadeLoader], and [ JadeServer] sections, which contain information that defines your JADE Object Manager environment. Certain modules of the JADE Object Manager can use the information stored in these sections to configure themselves to meet defined performance or resource constraints or your own configuration requirements.

[ JadeEnvironment] section, which contains information that is relevant to both standard clients and thin client nodes (that is, the location of program data, user data, and JADE work file directories).

[ JadeExecuteFlags] section, which contains a parameter that determines whether instructions within an executeWhen instruction are to be loaded and executed.

[ JadeExtractSort] section, which contains the name and optional relative path of the directory in which temporary sort files are located.

[ JadeInterpreter] and [ JadeInterpreterOutputViewer] sections, which contain information about the method cache and whether the write instruction can be actioned.

[ JadeLog] section, which contains information that controls the logging of JADE errors.

[ JadeMonitor], [ JadeMonitorBackground], and [ JadeMonitorSecurity] sections, which contain information used to initialize JADE Monitor sessions.

[PersistentDb] and [TransientDb] sections, which contain information used to initialize individual database engines on each JADE node; for example, to enable roll-forward recovery in the event of media failure. (By default, archival recovery is not enabled.)

The physical database layer or database engine of the JADE Object Manager can use the information stored in these sections to configure itself to meet defined performance or resource constraints, or user preferences.

Note In a multiple-database environment, each database can have its own unique JADE initialization file and configuration parameters.

[ JadeSecurity] section, which contains information that enables the JADE authentication and encryption hooks and access to the JADE development environment. For details about JADE security, see “JADE Security”, in Chapter 2 of your JADE Object Manager Guide.



JADEICG-6.3

[ JadeOdbc] and [ JadeOdbcServer] sections, which contains parameters that apply to accessing a JADE database through the Open Database Connectivity (ODBC) interface provided by JADE.

[ JadePatchControlExtensions] section, which controls patch control extensions.

[ JadePrinting] section, which controls the meta file and print data formats.

[ JadeProfiler] section, which contains the name of the JADE profile statistics output file.

[ JadeDumpLoad] section, which controls the dumping and loading of user data.

[ JadeHelp] section, which provides flexibility when using Adobe Acrobat Portable Document Format (PDF) files in a JADE environment.

[ JadeFontSubstitutions] section, which enables you to substitute preferred fonts on client nodes for those defined in an application. JADE applications written in a Windows environment rely on the Windows environment to provide specific common fonts.

When a JADE application written under Windows runs in a portable GUI non-Windows environment, none of the Windows standard fonts are normally available. Although the Java runtime provides its own font substitution for missing fonts, application users can substitute their own preferred fonts for those defined in an application, simply by adding the appropriate font entries to the [ JadeFontSubstitutions] section of the JADE initialization files on their client nodes.

[DatabaseBackup] section, which contains parameters that store the settings specified in the Backup Database dialog.

[DeltaOptions] section, which contains a parameter that specifies whether methods can be checked out to one delta only or to multiple deltas.

[ExternalDb] section, which contains parameters that affect the operation of your external databases.

[FaultHandling] section, which contains parameters that affect the operation of fault handling.

[LANG2LCID] section, which enables you to specify the language to be used for locales and translated messages on UNIX platforms.

[ JadeAppServer], [ JadeThinClient], and [environment-type] sections, which contain parameters that enable you to configure JADE thin client mode of operation.

[ JadeJava] section, which contains parameters that enable you to configure JADE portable GUI clients.

[NonGuiClient] section, which contains parameters that enable you to configure non-GUI clients.

[ JadeReorg] section, which contains parameters that enable you to configure the database reorganization process.

[ JadeReportWriter] section, which contains parameters that you can use as a diagnostic resource to help you to understand the query phase for a specific report and for exception handling.



JADEICG-6.3

[ConnectionParams], [ JadeRps], [JadeRpsManager], [ JadeSDSAdmin], [RpsIgnoreMethodExceptions], and [SyncDbService] sections, which contains information used to initialize a Synchronized Database Service environment (SDE), including RPS nodes.

[WebOptions] section, which enables you to specify options for your Web pages in HTML thin client applications.

[WebSession] section, which enables you to specify options for your Web sessions.

For details, see “JADE Initialization File”, in your JADE Initialization File Reference.

You can also:

Set options to specify your user configuration in the JADE command line, for use when running a JADE application from outside the development environment. For details, see “JADE Configurations under Windows”, in Chapter 1.

Specify your installation global preferences that apply to all JADE Browser and Painter windows for your JADE development environment work sessions in the installed JADE release. For details, see “Specifying Your Administration Options”, later in this chapter.

Specify options in the jadehttp.ini file for use when accessing JADE applications from the Internet Information Server (IIS). For details, see “Configuring JadeHttp for Remote Connections”, later in this chapter.

Specify options in the mod_ jadehttp module, for use when accessing JADE applications from the Apache HTTP Server. For details, see “Configuring Apache for Remote Connections”, later in this chapter.

Portable GUI Configuration To allow the JADE portable GUI to use the Java 2 Runtime Environment ( JRE) and Java Media Framework ( JMF) packages, you must perform the following configuration actions.

1. Download the Sun or IBM Virtual Machine Java 2 Runtime Environment ( JRE), Standard Edition ( J2SE) Version 6.0 software package from the Sun Microsystems Java Web site http://java.sun.com/ or the IBM Web site http://www.ibm.com/developerworks/java/. Download the Java Media Framework ( JMF) 2.1.1e software package from the Sun Microsystems Java Web site http://java.sun.com/. (Under Linux, the Java Virtual machine may be available on the Linux distribution release medium.)

Download the appropriate Windows Intel version, Linux Intel version (for SUSE and Red Hat Linux under Intel), or All Java version of these software packages.

2. Install the Java 2 Runtime Environment and Java Media Framework as directed by the instructions provided during the download of these packages.

Note For the 64-bit version of JADE, the Java Media Framework ( JMF) library must be the portable version (that is, all Java code and no .so files or .dll files), not the i386 version.

3. Ensure that the JAVA_HOME or JRE_HOME environment variable or the JavaHome parameter in the [ JadeJava] section of the JADE initialization file contains the path to the Java 2 Runtime Environment installation. (For details, see “JADE Portable GUI Java Section [ JadeJava]”, in your JADE Initialization File Reference.)






JADEICG-6.3

Setting the JAVA_HOME or JMFHOME environment variable is the preferred method of specifying the absolute path of Java or JMF. If it is not set, the jadepg.sh executable searches in the following order.

a. Checks to see if $JADEHOME/jre and $JADEHOME/jmf exist and then uses this version.

b. Searches for the Java version against which this release of JADE has been tested (for example, Java 6).

4. Ensure that the CLASSPATH environment variable enables you to pass user-specified Java Archive ( jar) files to the JRE for loading during initialization or the ClassPath or UserJVMJars<n> parameter in the [ JadeJava] section of the JADE initialization file contains the full path to each of the jmf.jar, mediaplayer.jar, and multiplayer.jar Java Archive ( jar) files installed with the Java Media Framework.

On Windows, the CLASSPATH environment variable has already been configured correctly by the Java Media Framework installer.

On Linux, you must specify the full path to the lib directory within the Java Media Framework in the LD_LIBRARY_PATH environment variable. If you did not install the dynamically loadable libraries installed with JMF into the Windows system directory, you may have to specify the full path to the Java Media Framework bin directory in the Windows PATH environmental variable.

Alternatively, on Windows or Linux, ensure that the jmf.jar file is located in the path specified in the UserJVMJars<n> parameter in the [ JadeJava] section of the JADE initialization file and that the JMFHOME environment variable specifies the full path to the Java Media Framework installation. In this configuration, JMF can find the rest of the required Java Jar files based on the JMFHOME directory.


Portable GUI Environment Variables When running a portable GUI environment under Windows and UNIX, the jadepg program requires the following values.

1. Either the JAVA_HOME or JRE_HOME environment variable.

2. Either the CLASSPATH environment variable (including the jmf.jar files) or the UserJVMJars<n> parameter specified in the [ JadeJava] section of the JADE initialization file.

When running a portable GUI environment under UNIX and not using the example script, the LD_LIBRARY_PATH environment variable must include the appropriate JRE and JMF paths. Conversely, when running a portable GUI environment under UNIX and you use the example script, the jadepg program requires only the JMFHOME environment variable. For details, see the following subsections.

CLASSPATH

The CLASSPATH environment variable is the standard Windows or UNIX environment variable that indicates the full path to each of the Java Archive ( jar) files; that is, to the jmf.jar, mediaplayer.jar, and multiplayer.jar files installed with the Java Media Framework.



JADEICG-6.3

To set this variable in the Bourne Again Shells (bash) under UNIX:

CLASSPATH=$JAVA_HOME/lib:$CLASSPATH:/usr/lib; export CLASSPATH

To set this variable in the csh under UNIX:

setenv CLASSPATH $JAVA_HOME/lib:$CLASSPATH:/usr/lib

JAVA_HOME

The JAVA_HOME environment specifies the absolute path of the directory in which the Sun or IBM Virtual Machine Java 2 Runtime Environment ( JRE) software that JADE uses has been installed; for example:

/usr/java/jre1.6.0_12

To set this variable in the Korn and Bourne shells under UNIX:

JAVA_HOME=/home/jre/java; export JAVA_HOME


setenv JAVA_HOME /home/jre/java

JRE_HOME

The JRE_HOME environment variable specifies the absolute path of the directory in which the Java 2 Runtime Environment ( JRE) software that JADE uses has been installed. As a minimum below this directory, there are the bin and lib subdirectories and often the system directory. To set this variable in the Korn and Bourne shells under UNIX:

JRE_HOME=/home/jre/java; export JRE_HOME To set this variable in the csh under UNIX:

setenv JRE_HOME /home/jre/java

JMFHOME

The JMFHOME environment variable is full path to the directory in which the Java Media Framework has been installed; for example:

/usr/java/JMF-2.1.1e

To set this variable in the Korn and Bourne shells under UNIX:

JMFHOME=/home/jre/java; export JMFHOME


setenv JMFHOME /home/jre/java

LD_LIBRARY_PATH

The LD_LIBRARY_PATH environment variable is the standard UNIX environment variable that indicates the location of shared objects and libraries. This variable, which applies only to Linux, must include the lib directory of this JADE portable GUI installation.

To set this variable in the Bourne Again Shells (bash) under UNIX with the IBM Virtual Machine JRE:

LD_LIBRARY_PATH=$JAVA_HOME/lib:$LD_LIBRARY_PATH:/usr/lib; export LD_LIBRARY_PATH



JADEICG-6.3

To set this variable in the Bourne Again Shells (bash) on Intel under UNIX with the Sun JRE:

LD_LIBRARY_PATH=$JRE_HOME/lib/i386:$JRE_HOME/lib/i386/client: $LD_LIBRARY_PATH:/usr/lib; export LD_LIBRARY_PATH

To set this variable in the csh on Intel under UNIX with the IBM Virtual Machine JRE:

setenv LD_LIBRARY_PATH $JAVA_HOME/lib:$LD_LIBRARY_PATH:/usr/lib

To set this variable in the csh under on Intel under UNIX with the Sun JRE:

setenv LD_LIBRARY_PATH $JAVA_HOME/lib/i386:$JRE_HOME/lib/i386/client: $LD_LIBRARY_PATH:/usr/lib

Running a Headless Portable GUI Program You can run the portable GUI so that the program has no GUI operation; that is, it is headless. The headless portable GUI facility enables you to run a non-GUI application on a client or server node that has no installed GUI.

Set the headless portable GUI option by setting the -Djava.awt.headless=true argument in the UserJVMArgs<n> parameter in the [ JadeJava] section of the JADE initialization file; for example:

UserJVMArgs3 = -Djava.awt.headless=true

Note that if you start the jadepg program as a headless operation:

The splash screen is ignored

Calls the Application::msgBox method are treated as unattended, and are automatically logged and answered

The exception dialog is automatically aborted without display

Running a GUI application is rejected

Creating any form is rejected, with the exception of print and Web forms

Web and print functionality are available, except for rich text and multimedia functionality that require the GUI

Configuring JadeHttp for Remote Connections The jadehttp library module can handle multiple TCP/IP address connections to the same application, which allows the Web server to connect to multiple copies of the same JADE application on multiple hosts. For details, see “[application-name] Section”, later in this chapter. To handle the transfer of large files from a user’s browser to JADE for JadeInternetTCPIPConnection class connections, data is read in small pieces and written into a temporary file as it goes.

If the Firewall parameter in the [ Jadehttp Files] section of the JadeHttp initialization file and the Firewall parameter in the [WebOptions] section of the JADE initialization file are set to true, the contents of the temporary file is sent (in pieces) to JADE when the entire data stream has been received. JADE then reads those pieces and writes the file contents as it goes (therefore avoiding large memory allocations). This is transparent if the Firewall parameter is set to false or if it is set to true and one of the following applies.

The FileTransferDirectory parameter in the [ Jadehttp Files] section of the jadehttp.ini file is set to default or to a valid directory (used to hold temporary file contents as the data is read from the Internet).



JADEICG-6.3

The standard readPipeCallback method of the JadeInternetTCPIPConnection class is used to read the data.

Note The firewall must be enabled at both ends of the connection (that is, if you are uploading images from another machine for a JADE Web-enabled form over a TCP/IP connection, the Firewall parameter in the [ Jadehttp Files] section of the JadeHttp initialization file or the Firewall configuration directive in the JADE mod_ jadehttp module and the Firewall parameter in the [WebOptions] section of the JADE initialization file must both be set to true).

The jadehttp.ini file is located in the virtual directory (that is, the IIS server location). Each virtual directory has its own jadehttp.ini file. (For details about the paths, see “[ Jadehttp Files] Section”, later in this chapter.)

The JadeHttp initialization file is read only when the first request for an application is received. If you update a parameter value in this file, you must therefore stop the Internet service and then restart it.

Firewall for the JADE Internet Environment As the JadeHttp library can communicate via a TCP/IP connection to a different workstation running the JADE application, you can ensure that the JADE environment is entirely behind the firewall. In the default implementation of the JADE Internet environment, the JADE application writes image files directly into the virtual directory for subsequent Web browser access.

For details, see the HTML Thin Client Using HTML Documents and HTML Thin Client Using JADE Forms white papers on the JADE Web site at http://www.jadeworld.com/jade/whitepapers.htm.

Files transferred by a Web browser to the JadeHttp library are written into a directory for access by the JADE application, as shown in the following diagram.

Use of a firewall requires that there are no network directory services running between the Web browser and JADE environments.

The only available links are TCP/IP connections. JADE applications do not write files directly into the virtual directory outside the firewall. Instead, the files must be passed via the TCP/IP connection to the JadeHttp library, which creates the file in the virtual directory. Similarly, files arriving at the JadeHttp library from a Web browser are passed to the JADE application via the TCP/IP connection.

The JADE application writes these files into the JADE Web application directory.

Image Files Created by the JADE Application

Use the Firewall parameter in the [ Jadehttp Files] section of the JadeHttp initialization file to control whether JADE uses this facility for its automatic HyperText Markup Language (HTML) generation. When this parameter is set to the default value of false, files are written directly to the virtual directory by JADE. When you set this parameter to true and the Firewall parameter in the [WebOptions] section of the JADE initialization file is also set to true, files are transferred to the JadeHttp library via the TCP/IP connection before being passed to the virtual directory.

The WebSession class provides a createVirtualDirectoryFile method, which enables you to pass image files created by a JADE application to the JadeHttp library.




JADEICG-6.3

The createVirtualDirectoryFile method has the following signature:

createVirtualDirectoryFile(fileName: String; fileContents: Binary; retain: Boolean): Integer;

The createVirtualDirectoryFile method parameters are listed in the following table.

Parameter Description

fileName Name of the file to be created in the virtual directory

fileContents Binary holding the file contents

retain Creates read-only files when set to true or standard files when set to false

The JadeHttp library creates the specified file in the directory (the virtual directory visible to Web browsers) in which the library is running. This method returns zero (0) if the method successfully formats a request to the JadeHttp library or it returns the non-zero Windows error code indicating the failure to create the file.

The image files must be passed before the final reply to the Web request is returned.

This process is transparent to you if your application is using the standard JADE generated Internet facility. However, if your application logic does additional file generation of its own, you must call the WebSession class createVirtualDirectoryFile method. When an application transfers files to the jadehttp library module by using the createVirtualDirectoryFile method, the directory that is used is determined as follows.

If the file name specified in the fileName parameter includes a directory, the file is written into that directory.

If the file name does not include a directory and the application’s section of the jadehttp.ini file contains a directory value for the VirtualDirectory parameter, the files are written into that directory.

If neither the file name nor the [application-name] section of the jadehttp.ini file contains a directory, the files are written into the same directory as the jadehttp library module. (This enables you to control directory permissions so that the directory containing the jadehttp library module does not need to have read and write access.)

Use the WebSession class isVDFilePresent method to return whether the requested file specified in the fileName parameter of the method is present on the Web server side of the firewall when using the JADE Web interface via the jadehttp library file. This method sends a message to the jadehttp library file to perform this action. If the specified file name does not have a directory part, the current virtual directory defined in the VirtualDirectory parameter in the JadeHttp.ini file for the application is used.

The file specified in the fileName parameter of the isVDFilePresent method is used if the file name has a directory part.



JADEICG-6.3

Notes If your applications are not using the standard JADE generated Internet facility, you need to set the Firewall parameter in the [ Jadehttp Files] section of the jadehttp.ini file and the [WebOptions] section of the JADE initialization file to true and call the WebSession class createVirtualDirectoryFile method only if you require firewall separation. If you do not require firewall separation, JADE creates image files directly into the virtual directory and bypasses the JadeHttp library.

The file cleanup process that is started when the jadehttp.ini file Firewall parameter is set to true deletes only files that are not read-only and which are of type .jpg, .png, or .gif. You should therefore make all other files in this directory that you want to retain read-only, by setting the retain parameter to true.

Files Transferred from the Web Browser

Use the Firewall parameter in the [ Jadehttp Files] section of the jadehttp.ini file to control whether firewall separation is used when transferring files to JADE from Web browsers. When the Firewall parameter is set to false, the default mechanism is used.

When you set the Firewall parameter to true and the Firewall parameter in the [WebOptions] section of the JADE initialization file is also set to true, files are transferred to the JADE application over the TCP/IP connection and each file transferred from a Web browser is sent to the JADE application as a separate message. Your JADE application must distinguish this message from a normal Web browser request and store the transferred file.

The JadeHttp library reads data in small pieces and writes it into a temporary file as it goes. The contents of the temporary file are sent (in pieces) when the entire data stream is received. JADE then reads those pieces and writes the file contents as it goes, which avoids large memory allocations. For details, see “Configuring JadeHttp for Remote Connections”, earlier in this section.

For details about the location of files, see “Controlling the Location of Files Uploaded via a Web Application”, later in this chapter.

The message sent through the firewall is formatted as follows.

File Component Description

Header TRF, followed by a null

File name Name of the file that is to be created, followed by a null

File contents Binary image

The handling of this message is placed in the Connection class readPipeCallback method before the rest of the general processing. (Note that no reply should be sent for this message.) When the JADE application receives the Web browser request, it stores the file in the specified Web application directory.

Note There is no cleanup method invoked if your user logic does not remove the files. Your application should delete these files when processing on them is complete.

When a file is transferred to JADE from a Web browser by using the default connection mechanism, the text for the text box that generated the transfer is changed by the JadeHttp library to:

<original-file-name>;<temporary-file-name-and-path>



JADEICG-6.3

If you have set the Firewall parameter in the [ Jadehttp Files] section in the jadehttp.ini file and the Firewall parameter in the [WebOptions] section of the JADE initialization file to true, the text is set to:

<original-file-name>;<temporary-file-name>

Your application logic that accesses the file must append the Web application directory to the temporary file name to form the actual path. (To get the name of the Web application directory, call the Application class webApplicationDirectory method, which returns a string containing the directory name.)

Internal Housekeeping of the Virtual Directory

When JADE sends a file to the JadeHttp library, any file that is not to be retained is created as a standard file of type .jpg, .png, or .gif when the jadehttp.ini file Firewall parameter, the Firewall parameter in the [WebOptions] section of the JADE initialization file, and the retain parameter in the WebSession class createVirtualDirectoryFile method are set to true. Files that are to be retained are created as read-only files.

To clean up files in the virtual directory, JADE initiates a separate thread when JadeHttp is started up if the Firewall parameter in the [ Jadehttp Files] section of the JadeHttp initialization file is set to true. Every hour this thread removes any standard files of type .jpg, .png, or .gif that are more than 12 hours old. (As the JadeHttp library has no life of its own until a message is received, this thread is initiated only after the first Web browser message is received.)

Controlling the Location of Files Uploaded via a Web Application If your JADE application accepts file input in text boxes on a Web page (by using the webInputType property of a TextBox control with the Web_InputType_File setting to upload a file from a Web session), you can use the FileTransferDirectory parameter in the [ Jadehttp Files] section of the jadehttp.ini file to specify the directory to which the file is written.

This parameter controls the directory in which any files transferred using the HTML InputType=file option are placed. (This parameter applies only when the Firewall parameter in the [ Jadehttp Files] section of the jadehttp.ini file is set to false.) By default, any transferred files are placed in the same directory as the jadehttp library file.

The format of the text property value of the TextBox control is as follows.

<source-file-name>;<destination-file-path><destination-file-name>

The source-file-name value is the name (excluding the path) of the originating file on the client workstation from which the file was loaded (that is, the workstation that is running the Web browser). A semicolon character (;) separates this and the destination-file-path and destination-file-name values, which are the full path to which the file is written (uploaded) and the name of that file; for example:

UsefulStuff.doc;d:\jade63\bin\txf188.tmp

In this example, accessing the txf188.tmp file in the specified directory opens a document file that contains the information in the UsefulStuff.doc file uploaded via the Web browser.

To provide increased security for applications running in HTML thin client mode, a text file input by using the TextBox class webInputType property with a value of Web_InputType_File must be processed in the event that resulted in the file upload occurring (for example, in the click event method of a Completed button). In addition, set the value of the Trace parameter in the [ Jadehttp Logging] section of the jadehttp.ini file to true to ensure the security of your data.



JADEICG-6.3

For details about directing Web browser replies to any connection within a connection group, see the GroupSharesConnections parameter in the [application-name] section of the jadehttp.ini file.

Caution To prevent malicious use of files uploaded to Web-enabled applications, the files are removed as soon as the event that resulted in their upload has completed. You should therefore process the file immediately or move it into a directory that is not available from the Web if you require that file for future processing.

[application-name] Section To ensure that an application specified in a Web browser cannot cause an attachment to a non-JADE environment within Windows 2003 Server, Windows Vista, Windows XP, or Windows 2000, you must specify the name of the Web application to which users can connect, by defining a unique [application-name] section for each Web-enabled JADE application. For details about configuring jadehttp.dll in IIS 7.0 for Vista, see FAQ 43941 on the JADE Web site at http://www.jadeworld.com/bin/jadehttp.dll?JWS&n=faqsearch&_p=JADE&_r=43941&_v=190.

IIS attempts to attach only to the applications whose names are specified as section names in the jadehttp.ini file.

Note The jadehttp library module can handle connections for up to 50 different hosts (that is, you can define up to 50 unique TcpPort[n], MinInUse[n], MaxInUse[n], TcpConnection[n], CloseDelay[n], ConnectionGroup[n], FirstTcpPort[n], and LastTcpPort[n] parameters within each [application-name] section).

The [application-name] section of the jadehttp.ini file contains parameters that define TCP/IP connections that are used instead of the default named pipe connections. For more details and the application requirements for TCP/IP connections, see “Connecting to JADE Applications from Internet Information Server (IIS)”, earlier in this chapter.

To specify that TCP/IP connections are used to connect to JADE release 6.3 applications from IIS, you must define a section with a unique name within the jadehttp.ini file for each application, with the ApplicationType parameter and unique multiple TcpPort[n], MinInUse[n], MaxInUse[n], TcpConnection[n], CloseDelay[n], and ConnectionGroup[n] parameters within each [application-name] section. Set the ApplicationType parameter in each [application-name] section to WebEnabledForms, WebServices, or HtmlDocuments.

For applications of Jade61-type, you must define a section with a unique name within the jadehttp.ini file for each application, with the ApplicationType parameter and unique multiple TcpPort[n], TcpConnection[n], FirstTcpPort[n], and LastTcpPort[n] parameters within each [application-name] section. Set the ApplicationType parameter in each [application-name] section to Jade61.

The [application-name] section can contain the following parameters.

ApplicationType

Value Type String Default Not specified

Purpose

The ApplicationType parameter, which is required in all [application-name] sections of the jadehttp.ini file, specifies the type of application that will be supported and how the interfaces to JADE function.

http://www.jadeworld.com/bin/jadehttp.dll?JWS&n=faqsearch&_p=JADE&_r=43941&_v=190



JADEICG-6.3

The valid parameter values are listed in the following table.

Parameter Value Description

WebEnabledForms JADE 6.2 Web-enabled forms. This application type results in all requests from a user being directed to the same JADE application copy during the user’s session. JadeHttp no longer inserts the tags into the HTML output; the JADE software now performs this function. The JADE side uses the multi-worker TCP facility to perform routing and queuing.

WebServices JADE 6.2 Web service operation, where user requests are sent to any available connection. The JADE side uses the multi-worker TCP facility to perform routing and queuing.

HtmlDocuments JADE 6.2 HTML documents operation where user requests are sent to any available connection. The JADE side uses the multi-worker TCP facility to perform routing and queuing.

Jade61 Retains the same operation for JadeHttp and its interface to JADE as at JADE release 6.1.

CloseDelay[n]

Value Type Integer (number-of-seconds) Default Not specified

Purpose

When the current number of in-use connections for the TCP/IP specified in the TcpPort[n] parameter exceeds the value of the MinInUse[n] parameter, the CloseDelay[n] parameter indicates how many seconds before the extra connections are closed after they become inactive. This value is used only when the value of the ApplicationType parameter is set to WebEnabledForms, WebServices, or HtmlDocuments.

Notes

The CloseDelay[n] parameter is ignored by Jade61-type applications.

If you specify a value of zero (0), idle connections are never closed.

ConnectionGroup[n]

Value Type String Default Not specified

Purpose

The ConnectionGroup[n] parameter specifies the name of the connection group associated with the value of the TcpPort[n] parameter (that is, the TCP/IP port to be used for the connection).

The connection group is the unique name that is used by applications of type WebEnabledForms to identify the TCP/IP port (the value of the TcpPort[n] parameter) to which a user request is to be sent.

Note

If you do not specify this parameter with a unique connection group name, this process does not function correctly.

FirstTcpPort[n]

Value Type Integer (first-tcp-port-number-in-the-available-range) Default Not specified

Purpose

The FirstTcpPort[n] parameter specifies the first valid TCP/IP port number for connection to the JADE application on the server (remote) node.



JADEICG-6.3

To guarantee that there are no conflicts with any TCP/IP-based application, specify a unique port number on the server node. Some systems allow only a restricted range of ports.

A port number should be in the range 49152 through 65535 inclusive, but any value greater than 1023 is valid. Internet Assigned Numbers Authority (IANA) port numbers in the range 0 through 1023 are reserved, those in the range 1024 through 49151 are registered and may have been assigned to specific applications, and those in the range 49152 through 65534 are dynamic, or set aside for private use.

Note

This parameter is used only when the value of the ApplicationType parameter is Jade61. It is ignored for other application types.

GroupSharesConnections

Value Type Boolean Default False

Purpose

The GroupSharesConnections parameter specifies whether all connections in a group are considered equal so that Web browser replies are directed to any connection within a connection group.

When this parameter is set to the default value of false, the jadehttp library module includes hidden fields in the reply so that subsequent inputs are channeled to the same connection each time when the Hypertext Markup Language (HTML) is sent back to the Web browser.

This process searches the HTML output for the "<INPUT TYPE=HIDDEN NAME=session" and "&session=" key sequences, which it modifies for this purpose. If these sequences are not found, the next Web browser input is directed to any available connection.

When you set the GroupSharesConnections parameter to true, the HTML is scanned and the jadehttp library module inserts hidden fields into the reply but any connection in the identified group can be used.

Consider the following example of an [application-name] section of the jadehttp.ini file.

[Jade61WebApp] TcpConnection = PC1 FirstTcpPort = 6010 LastTcpPort = 6019 TcpConnection2 = PC2 FirstTcpPort2 = 6100 LastTcpPort2 = 6119

If the PC1 connection on port 6010 is initially used to process a Web browser message when the GroupSharesConnections is set to true, any of the connections for PC1 ports 6010 through 6019 can be used subsequently. This requires you to write the JADE application in such a way that objects are accessible across application copies (for example, so that shared transient objects are created).

Caution Do not set the GroupSharesConnections parameter to true for a standard JADE Web-generated application.



JADEICG-6.3

Note


JadeHost

Value Type String (host-name or IP-address) Default Not specified

Purpose

The JadeHost parameter specifies the name of the JADE host server only when using named pipe access; it is ignored for other types of access.

Note


LastTcpPort[n]

Value Type Integer (first-tcp-port-number-in-the-available-range) Default Not specified

Purpose

The LastTcpPort[n] parameter specifies the last valid TCP/IP port number for connection to the JADE application on the server (remote) node.

To guarantee that there are no conflicts with any TCP/IP-based application, specify a unique port number on the server node. Some systems allow only a restricted range of ports. A port number should be in the range 49152 through 65535 inclusive, but any value greater than 1023 is valid.

Internet Assigned Numbers Authority (IANA) port numbers in the range 0 through 1023 are reserved, those in the range 1024 through 49151 are registered and may have been assigned to specific applications, and those in the range 49152 through 65534 are dynamic, or set aside for private use.

See also “Application Requirements for a Jade61 Application Type” under “Connecting to JADE Applications from Internet Information Server (IIS)”, earlier in this chapter, for details about the changes that you must make to your application when using the TCP/IP communications protocol for connecting to JADE applications from the IIS (particularly the value defined in the Application Copies text box of the Application Definition dialog Web Options sheet).

Note


MaximumPipes

Value Type Integer Default 10

Purpose

The MaximumPipes parameter specifies the maximum number of named pipe connections to JADE applications from the IIS. This indicates to the jadehttp library how many instances of the Web-enabled application it can expect to find running over a named pipe connection. It then attempts to connect to those applications or poll periodically to find the number of applications specified in this parameter.



JADEICG-6.3

Each copy of the JADE application opens its own instance of the named pipe.

Notes

Specifying a greater number of Web-enabled applications than you expect to run may impact on performance when jadehttp library polls to attempt to find the “missing” applications. Unless you therefore intend to increase the number of Web-enabled applications, there is little point in increasing the value of the MaximumPipes parameter.

Use the Application Copies text box on the Application Definition dialog Web Options sheet to specify the number of application copies that you require for TCP/IP connections to JADE applications from IIS.

This parameter is used only when the value of the ApplicationType parameter is Jade61 and the application is using named pipe access. It is ignored for other application and access types.

MaxInUse[n]

Value Type Integer Default Not specified

Purpose

The MaxInUse[n] parameter specifies the maximum number of connections that can be opened for the corresponding value of the TcpPort[n] parameter only when the value of the ApplicationType parameter is set to WebEnabledForms, WebServices, or HtmlDocuments.

Note

The MaxInUse[n] parameter is ignored by Jade61-type applications.

MaxMessageSize

Value Type Integer Default 1000000 bytes

Purpose

The MaxMessageSize parameter specifies the maximum size allowed for a single-part Web message (that is, a single stream of data with minimal formatting).

If the size of a single-part message exceeds the specified value of this parameter, the request is rejected and the following message is displayed to the user.

The size of the input data exceeds the limit permitted for this application and has been rejected.

Note

Multiple-part formatted Web messages are not limited in size (each message is made up of a series of sections that are specifically formatted).

MaxQueueDepth

Value Type Integer Default 0

Purpose

The MaxQueueDepth parameter specifies the maximum number of entries that can be queued at any time. The default value of zero (0) indicates that there is no queue limit.

When you specify a maximum number of queued entries, any additional request received that would also be queued when the maximum queued entries is reached will be rejected.



JADEICG-6.3

The user will be sent the contents of a file named busy.htm from the same directory as the jadehttp.ini file (as it is for the jadehttp.htm error file, described under “Message Logging”, in your JADE Web Application Guide).

If the busy.htm file is not available, the following text response will be sent.

The application is too busy This request cannot be processed at this time due to heavy usage - please try again shortly.

Note

This parameter is used only when the value of the ApplicationType parameter is Jade61 and the application is using named pipe access. It is ignored for other application and access types.

Hint

This parameter is intended mostly for use in a Microsoft clustering environment where the Cluster Server does not handle the situation in which IIS has too many requests queued, stops accepting connections, and actually forces IIS to terminate and restart, which causes significant service impact.

When you set this value, take into account the IIS RequestQueueMax registry setting so that it ensures the number of requests that can be queued within the jadehttp library does not exceed the value of the MaxQueueDepth parameter. If the value of MaxQueueDepth parameter exceeds the value of the RequestQueueMax registry setting, the Cluster Server treats IIS as not responding and acts accordingly.

Setting this parameter is of little use in any situation other than a Microsoft clustering environment, as standard IIS queue handling with Server Too Busy errors and connection rejection provide enough information for Web browser clients.

MessageTimeout

Value Type Integer (seconds) Default 300

Purpose

The MessageTimeout parameter specifies the maximum number of seconds that the JadeHttp.dll library waits for a reply from a JADE system before sending a failure message to the requesting Web browser.

Hints

This parameter enables you to test the effects of unexpectedly long request processing without having to wait the default five minutes for each test.

When Web-enabled applications are all busy, you can control the time that a Web browser window shows no action before returning the Service unavailable response.

MinInUse[n]

Value Type Integer Default Not specified

Purpose

The MinInUse[n] parameter specifies the minimum number of connections that can be opened for the corresponding value of the TcpPort[n] parameter only when the value of the ApplicationType parameter is set to WebEnabledForms, WebServices, or HtmlDocuments.



JADEICG-6.3

Note

The MinInUse[n] parameter is ignored by Jade61-type applications.

MinMessageSize

Value Type Integer Default 10 bytes

Purpose

The MinMessageSize parameter specifies the minimum size allowed for a Web message received from JADE using the WebSession class reply method to send HTML string Web requests back to the client node.

The minimum value is 1 byte, the maximum value 1024 bytes, and the default value 10 bytes.

This value is read the first time the application specified in the [application-name] section is accessed after jadehttp.dll has been loaded by Internet Information Server (IIS).

TcpConnection[n]

Value Type Integer (tcp-address) Default Not specified

Purpose

The TcpConnection[n] parameter specifies the unique valid TCP/IP address of the port to connect to on the server (remote) node, to enable Web client nodes to connect to the specified server node across the network through a TCP/IP connection.

TcpPort[n]

Value Type Integer (tcp-port-number) Default Not specified

Purpose

The TcpPort[n] parameter specifies the TCP/IP port number to be used for the connection specified in the corresponding TcpConnection[n] parameter for applications of type WebEnabledForms, WebServices, and HtmlDocuments.

Multiple instances of the connection are opened using the same port number instead of using a port range, as was the case in JADE release 6.1.

Note

The TcpPort[n] parameter is ignored by Jade61-type applications.

VirtualDirectory

Value Type String (virtual-directory-name) Default Not specified

Purpose

The VirtualDirectory parameter enables you to specify a string containing the name of the virtual directory for the HTML-enabled application.

Hints

The value specified for this parameter is used if the fileName parameter value of the WebSession class createVirtualDirectoryFile method does not include a directory. If neither this parameter nor the file name in the createVirtualDirectoryFile method contains a directory, the files are written into the same directory as the jadehttp library module.



JADEICG-6.3

This parameter enables you to control virtual directory permissions so that the directory containing the jadehttp library module does not need to have read and write access.

For details about retaining files passed to the jadehttp library, see “Firewall for the JADE Internet Environment”, earlier in this chapter. For details about returning whether a specified file is present on the IIS side of the firewall when using the JADE HTML thin client interface via the jadehttp library file, see “Image Files Created by the JADE Application”, earlier in this chapter.

Sample [application-name] Section

The following are examples of an [application-name] section in the jadehttp.ini file for the four application types specified by the ApplicationType parameter.

[Company] ApplicationType = WebEnabledForms TcpConnection = Host1a TcpPort = 20000 ConnectionGroup = CompanyForms MinInUse = 1 MaxInUse = 5 CloseDelay = 600

[WebCompany] ApplicationType = WebServices TcpConnection = Host1a TcpPort = 21000 MinInUse = 5 MaxInUse = 15 CloseDelay = 600 TcpConnection2 = Host2a TcpPort2 = 21001 MinInUse2 = 5 MaxInUse2 = 15 CloseDelay2 = 600

[HtmlCompany] ApplicationType = HtmlDocuments TcpConnection = Host1a TcpPort = 22000 MinInUse = 2 MaxInUse = 10 CloseDelay = 600 TcpConnection2 = Host2a TcpPort2 = 22001 MinInUse2 = 2 MaxInUse2 = 10 CloseDelay2 = 600

[Jade61Web] ApplicationType = Jade61 TcpConnection = Host1a FirstTcpPort = 58200 TcpPort = 58200 GroupSharesConnections = false VirtualDirectory = c:\web\myWebApp\files MaxMessageSize = 1000000 MaxQueueDepth = 0 MessageTimeout = 180 MinMessageSize = 100 TcpConnection2 = hostYour



JADEICG-6.3

FirstTcpPort2 = 6001 LastTcpPort2 = 6010 TcpConnection3 = hostTheir FirstTcpPort3 = 6010 LastTcpPort3 = 6019

The example for the Jade61 application type provides connections to three hosts for the Jade61Web application, as follows.

Host1a port 58200

hostYour ports 6001 through 6010

hostTheir ports 6010 through 6019

[Jadehttp Files] Section The [ Jadehttp Files] section of the jadehttp.ini file contains parameters that control firewall security and the location of files uploaded from a Web-enabled application.

Caution To prevent malicious use of files uploaded to Web-enabled applications, the files are removed as soon as the event that resulted in their upload has completed. You should therefore process the file immediately or move it into a directory that is not available from the Web if you require that file for future processing.

The jadehttp library derives a path for the jadehttp.ini, jadehttp.log, and transfer files, ensuring that they are completely secure. The directories are derived from the jadehttp library directory for these files, as follows.

1. JadeHttp attempts to create the required directories if they do not exist if security permits this. These directories, based on the example c:\ jade6302\bin\ jadehttp.dll file, are listed in the following table.

Directory Description Example

dll-path_dll-name\ini\ For the initialization file and the default c:\jade6302\bin_jadehttp\ini\jadehttp.ini error dll-name.htm file

dll-path_dll-name\logs\ For all dll-name logs c:\jade6302\bin_jadehttp\logs\jadehttp.log

dll-path_dll-name\transfer\ For the location of any temporary files c:\jade6302\bin_jadehttp\transfer\... created during file transfer

2. If the initialization file option to specify the log path is set, the logs directory is not created or used.

3. If the initialization file option to specify the transfer path is set, the transfer directory is not created or used.

4. As the dynamic link library can be renamed, its name is included. The library path therefore does not need to contain any other files, and users cannot access any of the files listed in the previous table.

For details about implementing a TCP/IP connection from the IIS to JADE applications, see “Connecting to JADE Applications from Internet Information Server (IIS)” and “Configuring JadeHttp for Remote Connections”, earlier in this chapter.

The [ Jadehttp Files] section can contain the following parameters.



JADEICG-6.3

FileTransferDirectory

Value Type String (disk-path) Default Not specified

Purpose

The FileTransferDirectory parameter specifies the directory to which files are uploaded during Web sessions from JADE applications that accept file input in text boxes on Web pages (by using the webInputType property of a TextBox control with the Web_InputType_File setting to upload a file from a Web session).

Note This parameter applies only when the Firewall parameter in the [ Jadehttp Files] section of the jadehttp.ini file is set to false or it is set to true and the FileTransferDirectory parameter is set to default or to a valid directory. (For details, see “Configuring JadeHttp for Remote Connections”, earlier in this section.)

This parameter controls the directory in which any files transferred by using the HTML InputType=file option are placed. (The file transfer directory must be a valid directory that is relative to the virtual directory, or IIS server.)

If you define a value for the FileTransferDirectory parameter, the transfer directory in the same directory as the jadehttp library is neither created nor used. The file transfer directory path cannot be greater than 260 characters. For more details, including the format of the text property value of the TextBox control, see “Controlling the Location of Files Uploaded via a Web Application”, earlier in this chapter.

Firewall


Purpose

The Firewall parameter controls whether firewall separation is used when transferring files to JADE from Web browsers. When this parameter is set to the default value of false, files are written to the transfer directory directly by the JadeHttp library.

The firewall must be enabled at both ends of the connection (that is, if you are uploading images from another machine for a JADE Web-enabled form over a TCP/IP connection, the Firewall parameter in the [ Jadehttp Files] section of the JadeHttp initialization file and the Firewall parameter in the [WebOptions] section of the JADE initialization file must both be set to true).

For details about the handling of data from the user’s browser through to JADE, see “Configuring JadeHttp for Remote Connections”, earlier in this section.

Set this parameter to true if you want files transferred to the JADE application over the TCP/IP connection. Each file transferred from a Web browser is sent to the JADE application as a separate message. Your JADE application must distinguish this message from a normal Web browser request and store the transferred file. For more details, including the format of messages sent through the firewall, see “Firewall for the JADE Internet Environment”, earlier in this chapter.

Sample [Jadehttp Files] Section

The following is an example of a [ Jadehttp Files] section in the jadehttp.ini file.

[Jadehttp Files] FileTransferDirectory = c:\jade63\bin_jadehttp\transfer Firewall = true



JADEICG-6.3

[Jadehttp Logging] Section The [ Jadehttp Logging] section of the jadehttp.ini file controls logging by the jadehttp library file. For details about the messages that are logged when tracing is set, see “Message Logging”, in your JADE Web Application Guide.

The [ Jadehttp Logging] section can contain the following parameters.

Trace


Purpose

The Trace parameter controls logging by the jadehttp library file. You can use this parameter to debug data passing through the jadehttp library file, if required.

Set this parameter to true to ensure the security of your data. When the value is true, messages logged to the jadehttp.log file do not include any of the text sent or received from the client, as this text could contain personal information, passwords, credit card details, and so on. Logged messages then only acknowledges that a message has been received or sent, because it is not possible to distinguish what is sensitive data and what is not.

TraceFile

Value Type String (file-path) Default Default

Purpose

The TraceFile parameter specifies an optional path and a file name that overrides the default jadehttp.log file name so that log files can be placed in other directories.

If you define a value for the TraceFile parameter, the log file in the same directory as the jadehttp library is neither created nor used. The file transfer directory path cannot be greater than 260 characters.

Sample [Jadehttp Logging] Section

The following is an example of a [ Jadehttp Logging] section in the jadehttp.ini file.

[Jadehttp Logging] Trace = true TraceFile = c:\jade63\bin_jadehttp\logs\jadehttp.log

Configuring Apache for Remote Connections TCP/IP connections only are used for connections to JADE applications running under a Windows or Linux operating system from the Apache HTTP Server.

This section covers the following topics.

Apache Configuration Directives

Apache Configuration Examples

Apache Considerations



JADEICG-6.3

For details about installing the mod_ jadehttp library module supplied by JADE for the Apache HTTP Server and the MPMs that it implements, see “Connecting to JADE Applications from an Apache HTTP Server”, earlier in this chapter.

Apache Configuration Directives The configuration directives in this section are available to configure the JADE mod_ jadehttp module. It uses the standard Apache configuration syntax, rather than implementing configuration via an initialization file.

Set the value of the JadeHttp_Trace directive to true to ensure the security of your data.

The concept and intent of these directives is the same as the jadehttp.ini file parameters, but the syntax differs. For details about the jadehttp.ini file parameters, see “Configuring JadeHttp for Remote Connections”, earlier in this chapter.

Most of the directives specific to mod_ jadehttp have the same meaning as their IIS counterparts (described in “Controlling the Location of Files Uploaded via a Web Application” under “Configuring JadeHttp for Remote Connections”, earlier in this chapter).

The JADE mod_ jadehttp module configuration directives are as follows.

SetHandler

ApplicationType

Application

FaultDocument


Firewall

GroupSharesConnection

JadeHttp_Trace

JadeServer

JadeTimeout

LocalInterface

MaximumPipes

MaxMessageSize

MaxQueueDepth

MinMessageSize

PhysicalDirectory

PurgeDirectoryFrequency

PurgeFileAge

TcpConnection[n]

VirtualDirectory

For details, see the following subsections.



JADEICG-6.3

To specify that TCP/IP connections are used to connect to JADE applications from Apache, you must define a <Location> directive within jadehttp.conf for each application, with an ApplicationType directive and unique multiple TcpConnection[n] directives between each Application directive.

For applications of Jade61-type, you must define a <Location> directive within jadehttp.conf for each application, with the ApplicationType directive and unique multiple TcpConnection[n] directives within each Application directive.

The following mod_ jadehttp directives apply between the core Apache <Location> and </Location> directives. Apache processes the <Location> directives in the order in which they are found in the configuration file, following any <Files> and <Directory> sections and after .htaccess files have been read and processed.

<Location /jade> SetHandler jadehttp-handler ApplicationType WebServices Application WebApplication TcpConnection PC1 21000 5 15 300 </Location>

This allows mod_ jadehttp directives to be placed in higher locations and their values to become the defaults for lower locations unless you explicitly override them.

In the following example, the handler and FaultDocument directive specified in <Location /jade> also apply to <Location /jade/subloc>.

<Location /jade> SetHandler jadehttp-handler FaultDocument PostTooLarge “http://server/ohdarn.html” </Location> <Location /jade/subloc> ApplicationType WebEnabledForms Application WebApplication TcpConnection PC1 21000 5 10 </Location>

SetHandler

The standard SetHandler Apache directive, whose characteristics are listed in the following table, selects the mod_ jadehttp module to handle this location.

Characteristic Value

Action Forces all matching files to be processed by a handler

Syntax SetHandler handler-name

Context server config, virtual host, directory, .htaccess

Module Core

Examples SetHandler jadehttp-info and SetHandler jadehttp-handler

The jadehttp-handler, which is the primary handler inside the mod_ jadehttp module, formats and passes data to JADE and returns the results to the Web browser.

The jadehttp-info handler reports internal information about the configuration and current status of the mod_ jadehttp module back to the Web browser.



JADEICG-6.3

This handler is similar to the standard Apache mod_info module that provides a comprehensive overview of the server configuration. Access to locations that use this handler should be restricted to trusted sites.

ApplicationType

The ApplicationType directive specifies the type of application that will be supported and how the interfaces to JADE function.

Note You must define this directive before the TcpConnection[n] directive within each Application directive.

The application type characteristics are listed in the following table.


Action Specifies the JADE application type

Syntax ApplicationType application-type

Context Location

Handler jadehttp-handler

Module mod_ jadehttp

Example ApplicationType WebServices

The valid application type values are listed in the following table.

Value Description

WebEnabledForms JADE 6.2 Web-enabled forms. This application type results in all requests from a user being directed to the same JADE application copy during the user’s session. JadeHttp no longer inserts the tags into the HTML output; the JADE software now performs this function.

The JADE side uses the multi-worker TCP facility to perform routing and queuing.

WebServices JADE 6.2 Web service operation, where user requests are sent to any available connection.


HtmlDocuments JADE 6.2 HTML documents operation where user requests are sent to any available connection.


Jade61 Retains the same operation for mod_ jadehttp and its interface to JADE as at JADE release 6.1.

Application

The Application directive, whose characteristics are listed in the following table, specifies the name of the Web-enabled JADE application.


Action Specifies the JADE application to use

Syntax Application application-name

Context Location


Module mod_ jadehttp

Example Application ErewhonShop



JADEICG-6.3

This directive is similar to the functionality of the [application-name] section of the jadehttp library module for IIS, described earlier in this chapter.

FaultDocument

The FaultDocument directive, whose characteristics are listed in the following table, specifies what the mod_ jadehttp module does when it encounters an error.


Action Specifies the URL or path name for redirection when an error occurs

Syntax FaultDocument cause redirect-url

Context Location

Handler jadehttp-handler, jadehttp-info

Module mod_jadehttp

Example 1 FaultDocument TcpConnectFailed http://secondary.example.com:80/page.html

Example 2 FaultDocument PostTooLarge bigpost.html

You can specify the cause value in numeric or text form. Valid values for the cause are listed in the following table.

Numeric Name Text Name

600 TcpConnectFailed

601 PostTooLarge

602 ServiceFailed

603 DataReadFailed

You must specify a valid URL or path name for the redirect-url value, which can be on the local Web server or on a remote Web server. If you do not specify a redirect-url value and an error occurs, an error page is generated internally in the mod_ jadehttp module.


The FileTransferDirectory directive, whose characteristics are listed in the following table, specifies the name of a local directory to use when files are uploaded from the Web browser to the JADE application.


Action Specifies the directory to use when files are uploaded from the Web browser

Syntax FileTransferDirectory local-directory-name

Context Location


Module mod_jadehttp

Example FileTransferDirectory /var/tmp/appname

The FileTransferDirectory directive is similar to the FileTransferDirectory parameter in the [ Jadehttp Files] section of the jadehttp.ini file for IIS servers, described earlier in this chapter.



JADEICG-6.3

As the mod_ jadehttp module must put the transfer files somewhere before transferring them to JADE, this directive specifies the directory to which the file or files are written.

Firewall

The Firewall directive, whose characteristics are listed in the following table, specifies whether there is a firewall between the mod_ jadehttp module and the JADE application.


Action Indicates if there is a firewall between mod_jadehttp and JADE

Syntax Firewall on|off

Context Location


Module mod_jadehttp

Example Firewall on

The Firewall directive is similar to the Firewall parameter in the [ Jadehttp Files] section of the jadehttp.ini file for IIS servers, described earlier in this chapter. If a firewall is present, file transfers between JADE and the Web server must be done by using the mod_ jadehttp module.

The firewall must be enabled at both ends of the connection (that is, if you are uploading images from another machine for a JADE Web-enabled form over a TCP/IP connection, the Firewall configuration directive in the JADE mod_ jadehttp module must be set to on and the Firewall parameter in the [WebOptions] section of the JADE initialization file must be set to true).

When transferred, the files will be placed in the directory specified in the PhysicalDirectory directive.

GroupSharesConnection

The GroupSharesConnection directive, whose characteristics are listed in the following table, specifies that HTML input from the Web browser can be sent to any TCP/IP connection within the same group


Action Indicates whether HTML input can be sent to any TCP/IP connection in the same group

Syntax GroupSharesConnection true|false

Default GroupSharesConnection false

Context Location


Module mod_jadehttp

Example GroupSharesConnection true

The GroupSharesConnection directive is similar to the GroupSharesConnections parameter in the [application-name] section of the jadehttp.ini file for IIS servers, described earlier in this chapter.

A group is defined by specifying all TcpConnection[n] directives with the same numeric suffix.

Note

This directive is used only when the value of the ApplicationType directive is Jade61. It is ignored for other application types.



JADEICG-6.3

JadeHttp_Trace

The JadeHttp_Trace directive, whose characteristics are listed in the following table, controls where any mod_ jadehttp tracing is written.


Action Specifies the log file to which JADE trace messages are sent

Syntax JadeHttp_Trace bit-mask [file-name [size[K|M]]] JadeHttp_Trace bit-mask "| rotatelogs-program rotatelogs-arguments"

Context Server config, virtual host, Location

Module mod_jadehttp

Examples JadeHttp_Trace 0x000000ff logs/jade%Y%m%d%H%M%S.log 10M JadeHttp_Trace 0x000000ff "|/usr/sbin/rotatelogs2 -l /var/logs/apache2/jadehttp_%Y%m%d%H%M.log 10M"

The JadeHttp_Trace directive is similar to the Trace and TraceFile parameters in the [ Jadehttp Logging] section of the jadehttp.ini file, documented earlier in this chapter.

Set this parameter to true to ensure the security of your data. When the value is true, messages logged to the jadehttp.log file do not include any of the text sent or received from the client, as this text could contain personal information, passwords, credit card details, and so on. Logged messages then only acknowledges that a message has been received or sent, because it is not possible to distinguish what is sensitive data and what is not.

If the file-name is relative, it is created relative to the ServerRoot location. If you do not specify the file-name, it defaults to "logs/jadehttp%Y%m%d%H%M%S.log".

If you do not specify the size, it defaults to 5M bytes. To disable mod_ jadehttp from attempting to rotate log files, specify a size of zero (0). The size value can have a multiplier appended to it. The K multiplier multiplies by 1,024, the M multiplier multiplies by 1,048,576 bytes, and all other values are treated as bytes.

If the file-name is in a directory that an Apache child httpd process does not have permission to access, the rotation of logs is disabled in mod_ jadehttp. The file name can include % modifiers, which specify values from the current local time (based on the Apache rotatelogs2 program, whose documentation is available at http://httpd.apache.org/docs/2.2/programs/rotatelogs.html, for example), permitted values are AaBbcdHIjMmSUWwXxYyZ%.

If no % modifiers are present, "%Y%m%d%H%M%S" is appended at the end of the file name (before the file extension, if it exists). This adds year, month, day, hour, minute, and second values to the file name.

A new log file is created if the file name changes (due to the changing time and selected modifier values) and if the file exceeds the specified size.

Note Multiple log files could be actively written to concurrently, because of the way that the Apache pre-fork MPM works.

Alternatively, you can use an external program to get log files rotated; for example, the one that is normally provided with the rotatelogs2 Apache distribution. This works well when log files are placed in a directory where the Apache child process does not have permission to create files.

http://httpd.apache.org/docs/2.2/programs/rotatelogs.html



JADEICG-6.3

The use of an external program behaves the same way as the Apache piped logs feature, which is described in the Apache documentation. It involves specifying the rotate program and arguments inside double quote characters (""), with the first character of the string being the pipe ( | ) character.

Note The name of the rotatelogs program can differ, depending on your Apache distribution and operating system.

The bit set values for the bit-mask value are listed in the following table.

Bit Set Description

0x00000001 When a redirect occurs

0x00000002 When a special command is issued

0x00000004 When file purges occur

0x00000008 When mod_ jadehttp sends connection information to JADE

JadeServer

The JadeServer directive, whose characteristics are listed in the following table, is reserved for future implementation.


Action Specifies the JADE server configuration

Syntax JadeServer jade-version byte-order character-size

Context Location


Module mod_jadehttp

Default JadeServer 6.3 localEndian oneByte

Example JadeServer 6 Intel utf-16

This directive allows a single mod_ jadehttp module to connect to JADE, regardless of the combination of Web server architecture and JADE server architecture, allowing mod_ jadehttp to adapt to the installed release of the JADE server.

The jade-version value allows for the protocol to between JADE and the mod_ jadehttp module to be changed. The version number can be in the range 1 through 4, with each number separated with numbers inclusive separated with the dot operator (.) notation; for example, 6.3.06.007.

The byte-order value allows for binary numbers and wide characters to be converted to the native byte ordering of the JADE server, which may be different from the byte ordering of the Web server.

In the default example in the previous table, the localEndian value defaults to littleEndian when the mod_ jadehttp module is running on Intel-based hosts and bigEndian when on PowerPC-based hosts. The entered value is not case-sensitive.



JADEICG-6.3

The primary names and synonyms for the byte-order value are listed in the following table.

Primary Name Synonym

littleEndian Intel

bigEndian PowerPC

The character-size value indicates the size of a JADE character, which is ANSI or Unicode, depending on your JADE installation. If the character size is Unicode where the JADE server is running, the physical size of a JADE character can be one of 1, 2, or 4 bytes in size. This allows mod_ jadehttp to send JADE characters of the correct size and type to the JADE server. (See also “Unicode Character Length”, in your JADE Platform Differences Guide.)

The primary names and synonyms for the entered value, which is not case-sensitive, are listed in the following table.

Primary Name Synonym

oneByte ANSI

twoByte Unicode, Utf16, or Utf-16

fourByte Utf32 or Utf-32

JadeTimeout

The JadeTimeout directive, whose characteristics are listed in the following table, specifies the maximum number of seconds that mod_ jadehttp waits for a reply from a JADE system before sending a failure message to the requesting Web browser.


Action Specifies the maximum number of seconds to wait for a reply from JADE

Syntax JadeTimeout number-of-seconds (the default value is 45 seconds)

Context Location


Module mod_jadehttp

Default JadeTimeout 300 (that is, 5 minutes)

Example JadeTimeout 30

A default value of zero (0) indicates that there is not timeout. The maximum timeout value is 1800 (that is, 30 minutes).

Hints

This directive enables you to test the effects of unexpectedly long request processing without having to wait the default five minutes for each test.

When Web-enabled applications are all busy, you can control the time that a Web browser window shows no action before returning the Service unavailable response.



JADEICG-6.3

LocalInterface

The LocalInterface directive, whose characteristics are listed in the following table, specifies the local network interface and optionally the port number to use when connecting from the mod_ jadehttp module to the JADE Web-enabled application.


Action Specifies the local network interface and optionally the port number

Syntax LocalInterface local-network-interface-handler-name

Context Location


Module mod_jadehttp

Default LocalInterface 0.0.0.0

Example LocalInterface 10.1.1.1

If your Web server host has multiple network interface cards, you can specify which one mod_ jadehttp uses when initiating connections to the Web-enabled JADE application.

The default value of 0.0.0.0 allows the operating system to choose the network interface card.

You would normally require this directive only when there are specific network security or routing issues to be addressed.

Caution Although you can also specify the local outgoing port number, you should take great care when doing so and only when you have a specific requirement. Specifying a LocalInterface port number limits you to a maximum of one TCP/IP connection to JADE for each Apache <Location> directive. In addition, if the Web server terminates abnormally and the port is not properly closed, it may take several minutes before this port becomes available again for use.

MaxMessageSize

The MaxMessageSize directive, whose characteristics are listed in the following table, specifies the largest size of a POST URL before an error is generated.


Action Specifies the maximum size of a POST string

Syntax MaxMessageSize size[M|K]

Context Location


Module mod_jadehttp

Default MaxMessageSize 1M

Example MaxMessageSize 50K

You can append a multiplier to the size value. The M multiplier multiplies by 1,048,756, the K multiplier multiplies by 1,024, and all other values are treated as bytes.

The minimum value is zero (0) and the maximum value is 128M.



JADEICG-6.3

MaxQueueDepth

The MaxQueueDepth directive, whose characteristics are listed in the following table, specifies the maximum number of entries that can be queued at any time. A value of zero (0) indicates that there is no queue limit.


Action Specifies the maximum number of entries that can be queued

Syntax MaxQueueDepth number-of-entries-in-queue

Context Location


Module mod_jadehttp

Default MaxQueueDepth 10

Example MaxQueueDepth 0

When you specify a maximum number of queued entries, any additional request received that would also be queued when the maximum queued entries is reached will be rejected.

The user will be sent the contents of a file named busy.htm from the same directory as mod_ jadehttp (as it is for the jadehttp.htm error file, described under “Message Logging”, in your JADE Web Application Guide).

If the busy.htm file is not available, the following text response will be sent.

The application is too busy This request cannot be processed at this time due to heavy usage - please try again shortly.

Note

This directive is used only when the value of the ApplicationType directive is Jade61 and the application is using named pipe access. It is ignored for other application and access types.

MinMessageSize

The MinMessageSize directive, whose characteristics are listed in the following table, specifies the minimum size allowed for a Web message received from JADE using the WebSession class reply method to send HTML string Web requests back to the client node.


Action Specifies the minimum number of bytes allowed for a Web message from JADE

Syntax MinMessageSize message-size-in-bytes

Context Location


Module mod_jadehttp

Default MinMessageSize 10

Example MinMessageSize 100

The minimum value is 1 byte and the maximum value is 1024 bytes.

This value is read once, when the Apache Web server starts.



JADEICG-6.3

PhysicalDirectory

The PhysicalDirectory directive specifies the name of a local directory to use when files are transferred from JADE to the Web server by using the WebSession class createVirtualDirectoryFile method without specifying a directory in the fileName parameter.

This directory is also used as the location for transferring files when the Firewall directive is set to on. In this situation, it behaves in a similar way to the FileTransferDirectory parameter in the [ Jadehttp Files] section of the jadehttp.ini file for IIS servers, described earlier in this chapter.

The characteristics of the PhysicalDirectory directive are listed in the following table.


Action Specifies the directory to use as a physical directory

Syntax PhysicalDirectory local-directory

Context Location


Module mod_jadehttp

Example PhysicalDirectory /var/tmp/appname/

Note Apache directives require separators to be defined using a forward slash (/) character.

The following is an example of the use of the PhysicalDirectory directive.

<Directory /var/spool/www/jade/images/> order allow,deny allow from all </Directory> Alias /jade/images/ /var/spool/www/jade/images/ <location /jade/webform> SetHandler jadehttp_handler PhysicalDirectory /var/spool/www/jade/images/ </location>

In this example, the physical directory on disk /var/spool/www/jade/images/ needs to be the same in the three places. The actual value can change on a site-specific basis.

PurgeDirectoryFrequency

The PurgeDirectoryFrequency directive, whose characteristics are listed in the following table, specifies how often the physical directory is checked to see if files require purging.


Action Specifies the frequency at which the physical directory is purged

Syntax PurgeDirectoryFrequency time-unit[H|M]

Context Location


Module mod_jadehttp



JADEICG-6.3


Default PurgeDirectoryFrequency 1H

Example PurgeDirectoryFrequency 5H

You can append a multiplier to the time-unit value. The H multiplier multiplies by 3,600, the M multiplier multiplies by 60, and all other time-unit values are treated as seconds. Specify zero (0) for the time-unit value to turn off the purging of the physical directory.

The minimum that you can specify for the time-unit value is 5 minutes and the maximum is 24H (hours). Values outside this range are forced to their respective limits.

PurgeFileAge

The PurgeFileAge directive, whose characteristics are listed in the following table, specifies the length of time since a file was last modified before it is purged from the physical directory.


Action Specifies the minimum modified age before the files are purged

Syntax PurgeFileAge time-unit[D|H|M]

Context Location


Module mod_jadehttp

Default PurgeFileAge 12H

Example PurgeFileAge 1D

You can append a multiplier to the time-unit value. The D multiplier multiplies by 86,400, the H multiplier multiplies by 3,600, the M multiplier multiplies by 60, and all other time-unit values are treated as seconds.

Specify zero (0) for the time-unit value to turn off the purging of the physical directory.

The minimum that you can specify for the time-unit value is 30 seconds and the maximum is 35D (days). Values outside this range are forced to their respective limits.

TcpConnection[n]

The TcpConnection[n] directive can have one of two types of syntax, depending on the value of the ApplicationType directive. The optional [n] value can be a unique number in the range 1 through 9. If you do not specify the optional n group suffix, JADE treats the value as 1.

You can specify the host-name value as a host name or as an IP address. If you specify a host name, it must resolve to a single IP address. If you append the optional n value to the TcpConnection[n] directive, it indicates the group to which the specified host name port number range is assigned.

When you set the GroupSharesConnection directive to true, all connections within a group are treated equally.



JADEICG-6.3

If the value of the ApplicationType directive is Jade61, the syntax is unchanged from earlier JADE releases; that is, the characteristics listed in the following table specify the TCP/IP connection details between the mod_ jadehttp module and the JADE Web application.


Action Specifies the TCP/IP connection to the JADE application

Syntax TcpConnection[n] host-name first-port [last-port]

Context Location


Module mod_jadehttp

Example 1 TcpConnection server1 6008

Example 2 TcpConnection1 10.1.1.99 51030 51039

If the value of the ApplicationType directive is WebEnabledForms, WebServices, or HtmlDocuments, the characteristics listed in the following table specify the TCP/IP connection details between the mod_ jadehttp module and the JADE Web application.



Syntax TcpConnection[n] host-name port [MinInUse [MaxInUse [CloseDelay [ConnectionGroup]]]]

Context Location


Module mod_jadehttp

Example 1 TcpConnection server1 6008

Example 2 TcpConnection2 10.1.1.19 51030 3 15 300

Example 3 TcpConnection3 10.1.1.19 51031 1 10 30 Forms

For details about the optional MinInUse, MaxInUse, CloseDelay, and ConnectionGroup values, see the following subsections.

MinInUse

The optional MinInUse value specifies the minimum number of connections that can be opened for the TcpConnection[n] directive when the value of the ApplicationType directive is set to WebEnabledForms, WebServices, or HtmlDocuments.

The default minimum number of connections is 1.

MaxInUse

The optional MaxInUse value specifies the maximum number of connections that can be opened for the TcpConnection[n] directive when the value of the ApplicationType directive is set to WebEnabledForms, WebServices, or HtmlDocuments.

The default maximum number of connections is the value of MinInUse.



JADEICG-6.3

CloseDelay

When the current number of in-use connections for the TcpConnection[n] directive exceeds the MinInUse value, you can specify the optional CloseDelay value to indicates how many seconds before the extra connections are closed after they become inactive.

The close delay defaults to zero (0) seconds before inactive connections are closed, indicating that the connection is never closed. The maximum value is 300 seconds.

ConnectionGroup

The optional ConnectionGroup value specifies the name of the connection group associated with the TcpConnection[n] directive; that is, the unique name that is used by applications of type WebEnabledForms to identify the TCP/IP port to which a user request is to be sent.

Although there is no default connection group, you must specify a unique value when the value of the ApplicationType directive is set to WebEnabledForms.

VirtualDirectory

The VirtualDirectory directive, whose characteristics are listed in the following table, is an easier way to specify the same value as the PhysicalDirectory directive.

The VirtualDirectory directive is mainly of use when the same jadehttp.conf file is designed to run on multiple hosts.



Syntax VirtualDirectory directory-name]

Context Location


Module mod_jadehttp

Example VirtualDirectory /var/web/myWebApp/files

The following is an example of the use of the VirtualDirectory directive.

<IfModule mpm_winnt.c> <Directory "c:/temp/"> ... </Directory> Alias /jade/images/ "c:/temp/" </IfModule> <IfModule !mpm_winnt.c> <Directory "/tmp/"> ... </Directory> Alias /jade/images/ "/tmp/" </IfModule> <location /jade/webform> SetHandler jadehttp_handler VirtualDirectory /jade/images/ </location>



JADEICG-6.3

In this example, depending on where this jadehttp.conf file is used (that is, on Windows or on Linux), the physical directory to which transferred files are written is different. The VirtualDirectory directive uses the URL location of /jade/images/ to determine the actual directory name to use.

For details about retaining files passed to mod_ jadehttp, see “Firewall for the JADE Internet Environment”, earlier in this chapter.

Apache Configuration Examples In the configuration examples in this section, the following has assumed to have been added to the httpd.conf file, which is the default main configuration file for Apache.

The primary Apache configuration file is normally called http.conf. You can place mod_ jadehttp directives in this file or in a separate file. The recommended method is to create a separate jadehttp.conf file that contains the required mod_ jadehttp directives, and include this file in the primary http.conf file as follows.

LoadModule jadehttp_module modules/mod_jadehttp.so Include conf/jadehttp.conf

Each of the examples in the following subsections has a different jadehttp.conf file.

Minimal Configuration Example

The following is a minimal example of the jadehttp.conf file that enables you to connect to the JADE example Erewhon system and access the Web shop.

<IfModule mod_jadehttp.c>

<Directory "/pictures"> Order deny,allow Allow from All </Directory>

Alias /jadeImages/ "/pictures"

<Location /jade-info> SetHandler jadehttp-info order deny,allow allow from localhost </Location> <Location /Erewhon> SetHandler jadehttp-handler ApplicationType WebEnabledForms Application WebShop TcpConnection jadeserver 6007 VirtualDirectory /jadeImages/ </Location> </IfModule>

From your Web browser, use the http://webserver/Erewhon URL to connect to the example Erewhon system.

To find out status information about what is happening inside the mod_ jadehttp module, use the http://localhost/jade-info URL on the workstation running the Apache Web server.



JADEICG-6.3

Extended Configuration Example

Add the following to the jadehttp.conf file, referred to in the httpd.conf file under “Apache Configuration Examples”, earlier in this chapter (or you can include it in the httpd.conf file itself).

<IfModule mod_jadehttp.c> <Location /jade> SetHandler jadehttp-handler FaultDocument TcpConnectFailed "/messages/CanNotConnect.html" </Location> <Location /jade/info> SetHandler jadehttp-info </Location> <Location /jade/BankOfJade> ApplicationType Jade61 Application BankApp TcpConnection cnwjdc1a 6007 6009 </Location> <Location /jade/Erewhon> ApplicationType WebServices Application Erewhon TcpConnection cnwjdc1a 6007 1 10 </Location> <Location /jade/erewhon/user> ApplicationType WebEnabledForms Application UserApp TcpConnection cnwjdc1a 6007 3 10 30 Group1 </Location> <Location /jade/erewhon/admin> ApplicationType WebServices Application AdminApp TcpConnection cnwjdc1a 6018 </Location> </IfModule>

Extended Configuration Example with Additional Apache Directives

Add the following to the jadehttp.conf file, referred to in the httpd.conf file under “Apache Configuration Examples”, earlier in this chapter (or you can include it in the httpd.conf file itself).

<IfModule mod_jadehttp.c>

<Location /jade-info> JadeHttp_Trace 0xffff Logs/jadehttp.log 5M SetHandler jadehttp-handler FaultDocument TcpConnectFailed "/messages/CanNotConnect.html" ErrorDocument 503 "http://localhost:8080/messages/Custom503.html" </Location>



JADEICG-6.3

<Location /jade/info> SetHandler jadehttp-info Order deny,allow Deny from all Allow from 127.0.0.0/8 10.1.1.100 </Location>

<Location /jade/BankOfJade> JadeHttp_Trace 0xff ApplicationType HtmlDocuments Application BankApp ConnectionGroup FinanceDepartment GroupSharesConnection true TcpConnection cnwjdc1a 6007 Order deny,allow Deny from all Allow from 192.168.0.0/16 </Location>

<Location> ApplicationType WebEnabledForms Application Company ConnectionGroup Customers GroupSharesConnection true TcpConnection Host1a 2000 1 5 300 CompanyForms Order allow,deny Allow from all </Location>

<Location /jade/erewhon/user> ApplicationType WebServices Application WebCompany TcpConnection Host1a 21000 5 15 300 TcpConnection2 Host2a 21001 5 15 300 Order deny,allow Deny from all Allow from 143.96.0.0/16 </Location>

<Location /jade/erewhon/user> ApplicationType HtmlDocuments Application HtmlCompany TcpConnection Host1a 22000 2 10 300 TcpConnection2 Host2a 22001 2 10 300 Order allow,deny Allow from all </Location>

<Location /jade/erewhon/admin> ApplicationType WebServices Application WebCompany TcpConnection Host1a 21000 5 15 300 TcpConnection2 Host2a 21001 5 15 300 Order deny,allow Deny from all Allow from 127.0.0.0/8 </Location>



JADEICG-6.3

<Location /jade/erewhon/admin> ApplicationType Jade61 Application Jade61Web TcpConnection Host1a 58200 GroupSharesConnections false JadeTimeout 180 VirtualDirectory c:\web\myWebApp\files MaxMessageSize 1000000 MaxQueueDepth 0 MinMessageSize 100 TcpConnection2 hostYour 6001 6010 TcpConnection3 hostTheir 6010 6019 </Location>

</IfModule>

Apache Considerations When using the Apache HTTP Server to connect to your JADE applications from the Internet, consider the following.

The JADE Web design considerations documented under “Connecting to JADE Applications from an Apache HTTP Server”, earlier in this chapter.

Only JadeInternetTCPIPConnection class TCP/IP communications are supported. This applies to all versions of mod_ jadehttp, regardless of the operating system.

The security implications for mod_ jadehttp are those of the IIS jadehttp.dll. Access to JADE data from the Web server can be controlled by Apache security directives.

Apache and the HTTP generally use UTF-8 as the encoding scheme for Unicode data on the Web. As mod_ jadehttp does not allow for this and passes the data directly to JADE, only ANSI data can be read or written to the JadeInternetTCPIPConnection object.

As the JadeServer configuration directive that indicates details about the JADE application to which mod_ jadehttp is connected is not yet implemented, it is assumed that the value of this directive is as follows.

JadeServer 6.3 littleEndian Ansi

Tuning Your Systems The JADE object manager uses a default hash value of:

2053 when storing and locating persistent and transient locks.

You can vary these hash values (for example, for systems that are likely to have a large number of concurrent persistent or transient locks) by using the PersistentLockHashSize or TransientLockHashSize parameter in the [ JadeClient] and [ JadeServer] sections of the JADE initialization file.

1019 for notifications. You can vary this hash value (for example, for systems that have a large number of notifications registered) by using the NotificationHashSize parameter in the [ JadeClient] and [ JadeServer] sections of the JADE initialization file.



JADEICG-6.3

Specifying Parameters in the JADE Command Line The JADE command line (or program target), used when running a JADE application from outside of the development environment, contains parameters that enable you to specify your JADE configuration. Each element of the command line has an identifying prefix, followed by an equals sign (=) and a specified value.

Command line elements can be delimited by a space, a tab, or a comma. Parameters containing these delimiters must be enclosed in single quotes ('') or double quote ("") characters.

Notes You can define parameters in the [ JadeCommandLine] section of the JADE initialization file that you would normally specify on the command line and you can define two-level initialization file section names so that multiple programs on the same host can share a JADE initialization file. For details, see “Two-Level Section Names” and “Sharing JADE Initialization Files”, in your JADE Initialization File Reference. See also “Placing Initialization File Parameters on the Command Line”, in the following subsection.

As the command line structure of the batch JADE Database utility program ( jdbutilb) differs from that of other JADE applications, the specification of a command line name parameter that matches an initialization file section unique identifier does not apply.

Unless your JADE initialization file is located in the bin directory, specify the ini parameter on the shortcut command line rather than in the [ JadeCommandLine] section so that the executable knows immediately the location of the JADE initialization file that contains all information required by the program.

For details about running JADE in thin client mode, see “Invoking a JADE Presentation Client” under “Running the Application Server and Presentation Clients”, in Chapter 2 of your JADE Thin Client Guide. For information about the parameters that enable you to handle multiple copies of JADE, see “Handling Multiple Copies of the JADE Program”, later in this chapter.

The command line parameters are listed in the following table.

Parameter Specifies … Example

app Application name app=Jade

path Full path of your JADE database directory containing your *.dat JADE files path=c:\jade\system

schema Schema name (mandatory except when app=Jade) schema=Faults

[server] Server type server=SingleUser

[ini] JADE initialization file path ini=c:\jade\system\jade.ini

[thinClient] That jade.exe or jadepg checks only arguments required to run in thin thinClient=false client mode

[name] That the program checks for a matching initialization file section name name=SecureAppServer

[newcopy] A new copy of jade.exe is to be started (ignored for jadepg) newcopy=false

[host] Host server node name or IP address host=cnwchcs38




[appServer] Remote TCP/IP address or name of the application server appServer=JadeServer

[appServerPort] TCP/IP port number of the application server appServerPort=1500



JADEICG-6.3

Parameter Specifies … Example

[endJade] The end of JADE-specific parameters (applicable to all JADE programs) endJade

[arguments] Optional user-defined parameters MyNonJadeApp.exe

When specifying your JADE command line:

You must include the application (app) parameter.

You must include the schema parameter (except when app=Jade).

You must include the path (path) parameter. The path parameter specifies the location of the JADE database. The database path cannot be greater than 260 characters.

When running in multiuser mode, the path is always relative to the viewpoint of the server node; for example, c:\jade\system refers to the c: drive of the server node and not that of the local client workstation.

You should specify the fully qualified path name.

When you specify a relative path name in the path parameter of the command line, the path name is first converted to an absolute path, by using the following rules.

On Windows, a relative path name with a single leading slash character is pre-pended by the first two characters of the JADE HOME directory on the server node (that is, drive-letter:), which is assumed to be the parent of the bin directory. For example, if your installation directory is Jade\bin (that is, your JADE HOME directory is Jade) and you specify path=system, the full directory path is Jade\system on the server).

On UNIX, a path name with no leading slash character is pre-pended by the JADE HOME directory on the server node (that is, the directory in which JADE has been installed); for example, /opt/jade.

Note For more details about relative directories, see “Relative Directory Handling in the Command Line path Parameter” under “Microsoft Windows Assumptions that Differ Under UNIX”, in your JADE Platform Differences Guide.

In the following Windows examples, the JADE HOME directory is assumed to be c:\ jade.


path=/jade63/system c:/jade63/system

path=system c:/jade/system

In the following UNIX examples, the JADE HOME directory is assumed to be /jade.




The jadepg executable (for a portable GUI JADE environment) with the newcopy command line value is not supported and is ignored.



JADEICG-6.3

The ini parameter specifies the location of the JADE initialization file. Letters specifying the drive are relative to the viewpoint of the client node. The initialization file defaults to Jade.ini, located in your database (system) path.

The optional server parameter specifies SingleUser or MultiUser.

Note If you do not specify a server value, the Server parameter in the [ Jade] section of the JADE initialization file is used. If this parameter is not specified in the JADE initialization file, the server defaults to MultiUser.

When you specify the name of a port rather then the number in the optional port parameter, the port name cannot start with a numeric value.

Identifying prefixes are case-insensitive.

Spaces are required only between the end of one parameter and the start of the next.

Names and paths with embedded spaces should be enclosed in double quote characters ("").

If you want to specify parameters to your JADE application, specify the endJade parameter as the last of the JADE parameters before the first of your own parameters.


Specify parameters (options) once only, in any order.

If a parameter on the command line is duplicated, the last occurrence found on the command line is used.

When running JADE thin client applications in multiuser mode, ensure that the TCP/IP port number specified in the jadapp (or jadappb) command line appServerPort parameter is a different port number to that specified for the database server (for example, the jadrap JADE Remote Node Access program). The database server TCP/IP port number is specified in the ServerNodeSpecifications parameter remote port value in the [ JadeClient] section and the NetworkSpecification parameter IP-address value in the [ JadeServer] section of the JADE initialization file.

In multiuser mode, you can optionally use:

The host command line parameter, to specify the host server node name or IP address. This parameter specifies a host name that is resolvable by the Domain Name Server (DNS) or host file, and has a maximum length of 255 characters.

The port command line parameter, to specify the host port name or number. If you use this parameter to specify the port name, you must update the applicable file in a Windows operating system, as follows.

/<winnt>/system32/drivers/etc/services

/<windows9x>/services

When specifying a port name in a Linux operating system, update the following file.

/etc/services



JADEICG-6.3

Note A port name cannot begin with a numeric value.

The interface command line parameter, to specify the client (local) node name or IP address. This parameter specifies a host name that is resolvable by the Domain Name Server (DNS) or host file, and has a maximum length of 255 characters.

The localport command line parameter, to specify the client (local) port name or number.

If you use this parameter to specify the local port name, you must update the applicable file in a Windows operating system, as follows.

/<winnt>/system32/drivers/etc/services

/<windows9x>/services

When specifying a local port name in a Linux operating system, update the following file.

/etc/services

Note A local port name cannot begin with a numeric value.

Specify the optional interface and localport parameters if you want to bind a specific network adapter in a server node that has more than one network adapter installed; for example, to allow an administrator to ensure connections from clients connect on the fastest interface or to allow easier security when used in conjunction with a firewall or router access list. (By default, JADE defaults to the primary network adapter in the node.)

If you do not specify a host or a port parameter, the ServerNodeSpecifications parameter value in the [ JadeClient] section of the JADE initialization file is used. If neither of these values is specified in the JADE initialization file, they default to LocalHost and 6005, respectively.

The host, port, interface, and localport command line parameters, if specified, override (but do not update) the ServerNodeSpecifications parameter [host-name or IP-address], [remote-port], [local-interface-name or IP-address], or [local-port] values, respectively, in the [ JadeClient] section of your JADE initialization file.

If you are running multiple copies of JADE, you can have multiple jade.exe or jadepg shortcuts using the same JADE initialization file ( jade.ini) by using the optional name parameter, instead of having separate files for each copy of JADE that you run. For details about multiple JADE programs on the same host sharing a JADE initialization file, see “Sharing JADE Initialization Files”, in your JADE Initialization File Reference.

Placing Initialization File Parameters on the Command Line You can override any JADE initialization file values by placing them on the command line.

Note For JADE executables, specify the fully qualified name of your JADE initialization file in the command line.

JADE first looks for command line parameters of the form section-name.parameter-name=value and if not present, checks the JADE initialization file for the section name and parameter name combination.

Two-level section names are supported in the command line.



JADEICG-6.3

JADE initialization file parameters on a JADE program command line have the following format.

section-name.parameter-name=value

Placing JADE initialization file entries on the command line enables:

JADE developers and system administrators to quickly test alternate configurations, rather than having to create multiple JADE initialization files.

JADE developers to share one JADE initialization file.

For example, if you want to allow specific application servers to run specified applications only, on the command line under Windows, specify the JADE application server executable ( jadapp) shortcut command line as follows.

R:\Jade_Development\jade\bin\jadapp appServerPort=1500 thinClient=true path=r:\jade_development\jade\system ini=r:\jade\system\test\myjade.ini JadeAppServer.EnableAppRestrictions=true JadeAppServer.AllowSchemaAndApp1="MySchema,SecretFixupApp" server=multiUser host=devsrvr38 port=6015

Alternatively, to perform the same action under UNIX, specify the jadappb shortcut command line as follows.

bin/jadappb AppServerPort=1500 thinClient=true path=system ini=myjade.ini JadeAppServer.EnableAppRestrictions=true JadeAppServer.AllowSchemaAndApp1="MySchema,SecretFixupApp" server=multiUser host=devsrvr38 port=6015

Notes As the size of the command line is imposed by the operating system, this may restrict the number of JADE initialization file values that you can place on the command line. We recommend that JADE administrators keep the placement of initialization file parameters to a minimum, because long command lines can become hard to maintain. However, if you require only a few non-updating initialization file values, putting them on the command line saves the creation of a new JADE initialization file section.

You cannot use the Application class setProfileString or setProfileStringAppServer method to update JADE initialization file parameter values specified on the command line. (Attempts to do so return a value of false and the parameter values remain unchanged.)

If you specify JADE initialization file section and parameter names in the command line, initialization file parameter values that are normally updated by methods are not updated, as the command line values have precedence. The parameter values in the JADE initialization file remain unchanged in this situation. For example, if you specify JadeServer.MaxServerThreads=10 in the command line of the JADE Remote Node Access program when the value of the [ JadeServer] section MaxServerThreads parameter is 5 and you then change the Maximum Server Threads text box value in the Thread Configuration dialog to 7, the command line value of the application remains 10 and the [ JadeServer] section MaxServerThreads parameter remains 5.

When obtaining values for command line arguments (for example, path, schema, appServer, and so on), the order of precedence is as follows.

1. Command line

2. If name=unique-identifier is on the command line, the [unique-identifier.JadeCommandLine] section parameter values are obtained from the JADE initialization file

3. The parameters from the [ JadeCommandLine] section of the JADE initialization file



JADEICG-6.3

4. An internal default value, if applicable

See also “Location of the JADE Initialization File”, “Two-Level Section Names” under “Format of the JADE Initialization File”, in your JADE Initialization File Reference.

Handling Multiple Copies of the JADE Program Use the newcopy command line parameter to force a new copy of the jade.exe JADE program to exist; for example, for testing in a multiuser environment. When this parameter is set to true (the default) and the JADE icon is clicked to launch JADE, a new copy of JADE is launched if the database is already open.

Note The newcopy command line value is not supported and is ignored for the jadepg executable (for a portable GUI JADE environment).

Specify a value of false to indicate that when the JADE icon is clicked and JADE is running, another application is started but another copy of the JADE program is not started; that is, execution is transferred to the copy of JADE that is currently running.

When initiating a thin client-based jade.exe executable with the newcopy command line parameter set to false, execution is transferred to an existing jade.exe copy if that copy is running in thin client mode and it is connected to the same application server (the TCP address and TCP/IP port number must match), so that only one copy of jade.exe runs multiple applications connected to the same application server.

If no other matching copy of jade.exe is running, execution continues as normal.

Note If you create a shortcut that has the newcopy parameter set to false and you specify a different JADE initialization file from the one with which the node was started, the active JADE initialization file is the one that was specified when the node started up and not the one specified in the newcopy=false shortcut. (You can call the Application class getIniFileName method in the new application to get the name of the initialization file that was used when the node started up.)

Specifying Your Administration Options When you sign on to JADE, you can select the Administration option button from the Select Options group box to specify your installation preferences. The installation preferences are those that apply to all JADE browser and Painter windows in the JADE development database of your installed JADE release.

When JADE has been installed, these preferences can then be changed individually by a user (by selecting the Preferences command from the Options menu) or for the whole JADE development environment (by using this option).

The JADE installation preferences provide a form that enables you to select the appropriate sheet to specify the global options for your JADE development environment work sessions.



JADEICG-6.3

The options that you can maintain and the sections in this chapter (for options that apply only to the administrative JADE Installation Preferences dialog) or in Chapter 2 of the JADE Development Environment User’s Guide that describe these options are listed in the following table.

Installation Option For details, see…

Accelerator Keys “Maintaining Accelerator Keys”, in Chapter 2 of the JADE Development Environment User’s Guide

Browser “Maintaining Browser Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Editor “Maintaining the Editor Display”, in Chapter 2 of the JADE Development Environment User’s Guide

Editor Key Bindings “Maintaining Editor Key Bindings”, in Chapter 2 of the JADE Development Environment User’s Guide

Editor Options “Maintaining Editor Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Exit “Maintaining Exit Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Lock “Maintaining Lock Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Method “Maintaining Method Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Miscellaneous “Maintaining Miscellaneous Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Painter “Maintaining Painter Options”, later in this chapter

Relationship “Maintaining Relationship Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Schema “Maintaining Schema Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Status list “Maintaining Status List Options”, in Chapter 2 of the JADE Development Environment User’s Guide

Text Templates “Maintaining Text Templates”, in Chapter 2 of the JADE Development Environment User’s Guide

Window “Maintaining Window Options”, in Chapter 2 of the JADE Development Environment User’s Guide

The JADE Installation Preferences dialog also contains the File, Admin, Admin, and Help menus.

Using the File Menu Use the commands in the File menu from the JADE Installation Preferences dialog to administer the installation preferences for your JADE development database.

The File menu commands are listed in the following table.

Command For details, see… Description

Save & Logoff Saving Your Options and Logging Off Saves your options, logs off from JADE, and displays the JADE sign-on dialog

Logoff Logging Off from the Installation Preferences Dialog Logs off from JADE and then displays the JADE sign-on dialog

Save & Exit Saving Options and Exiting from the Installation Preferences Dialog Saves your options and then exits from the JADE Installation Preferences dialog

Exit Exiting from the Installation Preferences Dialog Exits from the JADE Installation Preferences dialog

Saving Your Options and Logging Off Use the Save & Logoff command from the File menu to save your installation preferences and then exit from the JADE Installation Preferences dialog, in preparation for starting a new work session.



JADEICG-6.3

To save your installation preferences and then log off

Select the Save & Logoff command from the File menu.

When all installation preferences have been saved, the JADE Installation Preferences dialog is closed after a momentary delay and the JADE sign-on dialog is then displayed, to enable you to enter your password and start a new JADE work session.

Logging Off from the Installation Preferences Dialog Use the Logoff command from the File menu to exit from the JADE Installation Preferences dialog, in preparation for starting a new work session.

To log off from the JADE Installation Preferences dialog

Select the Logoff command from the File menu.

After a momentary delay, the JADE Installation Preferences dialog is closed and the JADE sign-on dialog is displayed, to enable you to enter your password and start a new JADE work session.

Note No installation preferences that you have specified will be saved.

Saving Options and Exiting from the Installation Preferences Dialog Use the Save & Exit command from the File menu to save your installation preferences and then exit from the JADE Installation Preferences dialog.

To save your installation preferences and then exit

Select the Save & Exit command from the File menu.

When all installation preferences have been saved, the JADE Installation Preferences dialog is then closed after a momentary delay.

Exiting from the Installation Preferences Dialog Use the Exit command from the File menu to exit from the JADE Installation Preferences dialog.

To exit from the JADE Installation Preferences dialog

Select the Exit command from the File menu.

After a momentary delay, the JADE Installation Preferences dialog is then closed.

Note No installation preferences that you have specified will be saved.

Using the Admin Menu Use the commands in the Admin menu from the JADE Installation Preferences dialog to administer the installation preferences for your JADE development database.



JADEICG-6.3

The Admin menu commands are listed in the following table.

Command For details, see…

Reset to Defaults Resetting JADE Default Preferences

Remove Sources Removing Source Code

Backup Database Backing Up Your Development Database from a Client Workstation

Resetting JADE Default Preferences Use the Reset to Defaults command from the Admin menu to reset all installation preferences to the default values.

Any installation preferences that you have specified are then reset to the JADE default preferences. These default values are the installation preferences that were last specified and saved using the JADE Installation Preferences dialog.

If you have not yet specified and saved any installation preferences, the default preferences are those that are supplied with JADE.

Removing Source Code The Remove Sources command enables you to remove source code from your user-defined schemas only. You cannot remove source code from JADE-supplied schemas.

Use this command when you want to release JADE applications that do not contain method source code; for example, when you release a schema containing JADE applications developed for a third-party.

Notes Ensure that you have backed up the schema, including source code, before you use this command.

For details about including recompiled methods in patch versioning when a patch is to be applied to a schema that does not have source available, see “Enabling or Disabling Patch Versioning” and “Setting Up a Patch Number”, in Chapter 3 of your JADE Development Environment Administration Guide. For details about finding the position in a method source if you want to locate the position at which an exception occurred in an application from which source code has been removed, see “Finding a Method Source Position”, in Chapter 4 of your JADE Development Environment User’s Guide. For details about encrypting extracted source code, see “Encrypting Schema Source Files”, in Chapter 11 of your JADE Development Environment User’s Guide.

Backing Up Your Development Database from a Client Workstation The Backup Database command enables you to backup your JADE development environment database without having to sign off all users or bring down the server node.

You can backup your JADE development environment database online when the database is active for both read and write access. When backing up your JADE database, you can:

Specify the backup directory path

Compress or verify backed up files and optionally overwrite existing files

Lock the database for write access



JADEICG-6.3

For more details, see “Backing Up Your JADE Development Environment”, in Chapter 3 of your JADE Database Administration Guide.

Using the Patch Menu Use the commands in the Patch menu from the JADE Installation Preferences dialog to administer patch version control for your JADE development database.

Patch version control enables you to set a numeric patch version that records all additions, deletions, and updates made to schema entities (for example, methods, properties, constants, and so on) until a new patch version number is set and the patch version history is removed when the changed entities in the previous patch version are extracted.

The Patch menu commands are listed in the following table.

Command Documented under… Description

Enable / Disable Enabling or Disabling Patch Versioning Enables or disables patch versioning for your database

Set Patch Number Setting Up a Patch Number Sets a new patch version number

Extract Patch Extracting a Patch Version Extracts all entities that have changed in the current patch version

Recreate History Recreating a History of Patch Version Changes Recreates the history of changes in the current patch version

Remove Patch History Removing a Patch History of Changes Removes the patch history that matched specified criteria

For details, see “Patch Versioning” under “Administering Your JADE Environment”, in Chapter 3 of your JADE Development Environment Administration Guide.

Using the Help Menu Use the commands in the Help menu from the JADE Installation Preferences dialog to access the standard Common User Access (CUA) help options. (For details about these options, see “JADE Online Help”, in Chapter 2 of your JADE Development Environment User’s Guide.)

The Help menu commands are listed in the following table.

Command Description

Index Opens the directory of JADE online help documents

About Displays details about the current version of JADE

Specifying Your JADE Installation Preferences The sheets of the JADE Installation Preferences dialog enable you to maintain your JADE installation preferences. The preferences that you specify apply to all new users.

The preferences for the current users are not modified. For details about maintaining preferences for current users and details about the sheets that are common to administrative installation and to individual user preferences, see “Setting User Preferences”, in Chapter 2 of your JADE Development Environment User's Guide.



JADEICG-6.3

Specify your installation preferences when you first install JADE and before any users sign on, or at any time for new users of the JADE release. The preferences that you set (and then save) become the new default preferences for your installation of JADE.

To maintain your installation preferences

1. From the JADE sign-on dialog, select the Administration option button from the Select Options group box.

The JADE Installation Preferences dialog, shown in the following diagram, is then displayed.

The types of options are contained in sheets, with the Editor sheet displayed by default. (For details about using the Editor sheet, see “Maintaining the Editor Display” and “Maintaining Editor Options”, in Chapter 2 of the JADE Development Environment User’s Guide.)

2. Select the type of options that you want to change, by clicking on the sheet name; for example, click Status List if you want to view or change these options.

3. Make the required option changes.

4. To save your changes, use the Save & Logoff command or the Save & Exit command from the File menu. For details, see “Saving Your Options and Logging Off” or “Saving Options and Exiting from the Installation Preferences Dialog”, respectively, earlier in this chapter.

When you have selected and saved your JADE preferences, the specified preferences become the new JADE default preferences when you exit or log off from the JADE Installation Preferences dialog.



JADEICG-6.3

Maintaining Painter Options In JADE Painter, the default display of toolbars and grids and the position of the Properties dialog can be specified. For example, you can specify that the Control palette is not displayed on the Painter toolbar by default.

As painter values apply to the whole of the JADE development environment, the Painter sheet is available only on the administrative JADE Installation Preferences dialog.

To change the default Painter options

1. Click the Painter sheet of the JADE Installation Preferences dialog. The Painter sheet, shown in the following diagram, is then displayed.

2. If you do not want the Control palette displayed in the Painter toolbar, check the Hide Control Palette check box.

3. If you do not want the Alignment and Size palette displayed in the Painter toolbar, check the Hide Alignment/Size Palette check box.

4. If you do not want the status bar displayed in Painter windows, check the Hide Status Bar check box.

5. If you do not want the Tools palette displayed in the Painter toolbar, check the Hide Tools Palette check box.

6. If you want controls on Painter forms to snap to a grid, check the Snap to Grid check box.

7. If you want a grid displayed on Painter forms, check the Show Grid check box.



JADEICG-6.3

8. If you do not want a default grid width of 10 pixels, enter the required width in the Grid width text box.

9. If you do not want a default grid height of 10 pixels, enter the required height in the Grid height text box.

10. If you want the Properties dialog to be always positioned on top of other control in Painter forms by default, check the Properties On Top check box.

Reregistering a JADE System in Batch Mode The jadregb program enables you to automate the registration of a JADE system with your new licence information by running the registration program in batch mode (for example, from a command script), specifying the following information.

jadregb path=database-directory [online [ini=JADE-initialization-file-absolute-path-and-name]] [help | report | name="licence-name" key=licence-key [minStandard=integer-value] [minJade=integer-value]]

The number of server licences is split over the two types of run time operation; that is, standard (fat client) and JADE thin client.

You can optionally specify the minimum number of licences reserved for both types of run time operation, if required. When you have successfully specified the new licence information for the database:

Standard information is output to stdout and error information is output to stderr.

For details about displaying and redirecting the output from JADE batch utilities, see the DisplayApplicationMessages, LogServer, and UseLogServer parameters under “JADE Log Section [JadeLog]”, in your JADE Initialization File Reference.

The _control.dat file is updated.

Note To run this on UNIX under SUSE Linux Enterprise Server or the Red Hat distribution of Linux, use the jadregb command line parameters described in this section and ensure that the standard JADE environment variables (documented under “Required Environment Variables” in Chapter 3 or Chapter 4, respectively) are correctly defined.

If the jadregb executable program fails, a non-zero exit code is returned and an error message is displayed; for example, the licence key that you specified was invalid or you did not enclose your licence name in double quote characters (""). The batch registration program parameters are described in the following subsections.

path The path parameter specifies the full path of the JADE database directory; for example:

c:\jade\system

ini The optional ini parameter enables you to specify the fully qualified name of your JADE initialization file if it is not located in the database directory or it has a file name other than the default value of jade.ini.



JADEICG-6.3

name The name parameter specifies your registered licence name (displayed on your Certificate of Authorisation, which may be an e-mail message providing you with your licence name and key). For example:

"Snazzy Solutions Incorporated"

You must specify your licence name, enclosed in double quote characters. This name must be typed correctly (it is case-sensitive), as it is validated against your licence key.

key The key parameter specifies the assigned licence key; for example:

99999999FFFFFFFF99999999FFFFFFFF

Enter the licence key exactly as it is specified on your Certificate of Authorisation, but without spaces.

online The optional online parameter specifies that the jadregb program attempts to sign on to the JADE Remote Node Access utility ( jadrap) to update the licence key.

If you specify the online parameter, you may also need to specify the ini parameter, which consists of the full (absolute) path and name of the JADE initialization file that enables the jadregb program to obtain the multiuser initialization file settings that it requires to sign on to the JADE Remote Node Access utility ( jadrap). If you do not specify the online parameter, the _control.dat file is updated directly and no client application or database server can be running.

minStandard The optional minStandard parameter specifies the minimum number of runtime standard fat client licences that can be reserved at run time to ensure that a specific number of licences is available for standard fat clients at any time; for example:

minStandard=4

You cannot specify a minimum number of standard fat client licences greater than the number of your registered server (run time) licences.

The default value of zero (0) indicates that there is no minimum number of standard fat client runtime licences.

minJade The optional minJade parameter specifies the minimum number of runtime JADE thin client licences that can be reserved at run time to ensure that a specific number of licences is available for JADE thin clients at any time; for example:

minJade=6

You cannot specify a minimum number of JADE thin client licences greater than the number of your registered server (run time) licences.

The default value of zero (0) indicates that there is no minimum number of JADE thin client runtime licences.



JADEICG-6.3

report The optional report parameter displays information about all existing licences installed in your system; for example, primary, secondary, and relational licences, as shown in the following diagram.

help The optional help parameter displays the required parameters and their values.

Using the JADE Version Information Utility The jverinfo JADE Version Information utility enables you to check the hot fixes that are applied to your JADE system and to optionally retrieve the version of user data map files. For more details, see the following subsections.

Checking which Hot Fixes are Applied

Obtaining the Version Number of User Database Files

The jverinfo program outputs the following version information to a file so that you can view it on your workstation monitor, print it out, or send it to JADE Support if requested to do so.

System version information (for example, the operating system version, the CPU model, and the registered owner and organization of the software and hardware)

File version information, starting with the installed location, full release version, and modified timestamp of each executable file followed by the installed location, full version number, and modified timestamp of each Dynamic Link Library (DLL) file

Types of CPU and operating system (for example, columns that contain I686 or AMD64 for the CPU type and WinGUI, WinCE, or SYSV for the operating system type)

User data map file version number, starting with the installed location, version number, build type, architecture, and modified timestamp of each user data file

The JADE Version Information utility program is not dependent on any other JADE libraries. You can therefore use one version of the jverinfo program to report on any release, whether it is a Unicode or an ANSI build, and on other architectures (for example, the Linux jverinfo program can report on Windows DLL version numbers, and the reverse).



JADEICG-6.3

To run the jverinfo program under a Windows operating system:

1. Copy the jverinfo.exe program to the JADE binary directory from which you want it run.

Alternatively, you can create a shortcut on your desktop or in the appropriate Start folder.

2. Execute the program to run it.

By default, the program writes its output to a file called versioninfo.txt, which is located in the working directory.

To automate the program, you can optionally specify the binary directory, user data map file directory (which is usually the system directory), system file directory, the output file name, and the location of UNIX shared objects and libraries, in the following format.

jverinfo [binpath=binary-directory-name] [binmask=binary-file-type] [datpath=user-data-directory] [out=output-file-name | stdout] [syspath=system-file-directory] [libpath=lib-directory] [libmask=library-file-type]

The following is an example of the command line set up to run the program.

c:\jade\bin\jverinfo binpath=c:\jade\production_bin datpath=c:\jade\system out=c:\jade63\prodver.txt

You can use the optional:

binpath parameter to specify the binary directory that is to be scanned.

binmask parameter to refine the files that are output using the binpath parameter.

The default syntax of this parameter is *.exe on Windows and * on UNIX. For example, if you have located Linux executables in a Windows binary directory and you want the version information of these Linux files output when the binpath parameter is specified; that is, set binmask="*.*".

out parameter to specify stdout or the name of the output file that is created (defaulting to versioninfo.txt).

datpath parameter to specify the user database map file directory (which is usually the system directory) that is to be scanned. It outputs an unformatted list of all user data map files, including the version number, the ANSI, Unicode 16, or Unicode 32 build type, whether the architecture is LittleEndian or BigEndian, and the time and date that each file was last modified.

syspath parameter to specify the system file directory that is to be scanned and outputs the system file version, the ANSI, or Unicode 16, or Unicode 32 build type, and whether the architecture is LittleEndian or BigEndian, and the time and date that each file was last modified.

libpath parameter, which applies only to UNIX, to specify another location of shared objects and libraries, if required.

libmask parameter to refine the files that are output using the libpath parameter.

The default syntax of this parameter is *.dll on Windows and *.so on UNIX. For example, if you have located Linux shared object libraries in a Windows library directory and you want the version information of these Linux files output when the libpath parameter is specified; that is, set libmask="*.*".



JADEICG-6.3

Version information is handled differently on UNIX platforms, as a static string constant containing the version information that can occur anywhere in the code file that is compiled. You can use standard UNIX utilities to locate this string. For example, you can run the following command from the bin and lib directories, which outputs the relevant version and timestamp information.

strings * | grep '@(#).*JADE'

If there are Windows DLLs present on a Linux UNIX host, the version numbers of these DLLs are also output.

To run this on UNIX under SUSE Linux Enterprise Server or the Red Hat distribution of Linux, use the jverinfo command line and ensure that the standard JADE environment variables (documented under “Required Environment Variables” in Chapter 3 or Chapter 4, respectively) are correctly defined.

Checking which Hot Fixes are Applied Should a problem arise that you cannot resolve by taking the appropriate action described in the relevant error message (documented in the JADEMsgs.pdf file) and your JADE licences include support, you may be asked for your current JADE version information in addition to the log files and user mode or process dumps specified in the previous section.

If you are uncertain of which hot fixes are applied to your JADE database, you can perform the following actions to determine exactly which hot fixes have been applied.

Run the jverinfo JADE Version Information utility to obtain your current system and file versions. This stand-alone utility enables you to output your current JADE version information, the consolidated release you are running, and the hot-fixes with which you are running. Although you may think you have applied fixes, you may sometimes find that your records do not reflect the JADE system information itself.

In the RootSchema, call the Schema class getAppliedPatches method to return a string containing all patches applied by a schema load to system schemas in your database. For details about the format of the string returned by this method, see the getAppliedPatches method in Volume 2 of your JADE Encyclopaedia of Classes.

Obtaining the Version Number of User Database Files If you want to obtain the version number of user database map files (for example, on Windows Mobile devices running under Compact JADE), you can run jverinfo JADE Version Information utility with the optional datpath parameter, to obtain the current user data map file version number. This parameter can be applied only to user database map files; that is, user schema files (for example, _userdev.dat, _userscm.dat, and so on) represented by the DbFile class Kind_User_Schema constant and user data files (for example, _rootdef.dat, locktest.dat, and so on) represented by the DbFile class Kind_User_Data constant.

Use the optional setUserFileVersions command in the jdbutilb batch JADE Database utility to set the user data map file version number to the specified 32-bit unsigned integer value.

When you specify the datpath parameter, the output file contains an unformatted list of all user data map files, including the version number, the ANSI, Unicode 16, or Unicode 32 build type, whether the architecture is LittleEndian or BigEndian, and the time and date that each file was last modified.



JADEICG-6.3

In the following example of user data version information, 93 is the specified user data file version number. If a user data version number has not been specified, the version number is zero (0).

User: (path= c:\jade\system) ============== locktest.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:21 2008 simpleconsumer.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:21 2008 simpleprovider.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:21 2008 wsconsumer.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:22 2008 _dmpload.dat 93 Ansi,LittleEndian Tue Jun 10 04:00:57 2008 _environ.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:20 2008 _monitor.dat 93 Ansi,LittleEndian Tue Jun 10 04:00:57 2008 _reports.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:21 2008 _rootdef.dat 93 Ansi,LittleEndian Tue Jun 10 04:00:57 2008 _stats.dat 93 Ansi,LittleEndian Tue Jun 10 04:00:07 2008 _userdev.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:21 2008 _usergui.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:20 2008 _userint.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:20 2008 _userscm.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:20 2008 _userxrf.dat 93 Ansi,LittleEndian Tue Jun 10 08:16:20 2008

In the RootSchema, call the DbFile class getUserPatchVersion method to return a 32-bit unsigned value as an Integer64 primitive type, which is the unformatted version number of user data map files. If a user data version number is not set, this method returns zero (0).

____________________________________

JADEICG-6.3

Appendix A Exit Values

____________________________________

This appendix covers the following topics.

Overview

Enabling the Use of Generic Exit Values for Windows

General Exit Values Unique to Each Program

Overview JADE provides exit values that apply to JADE programs and utilities when running JADE under a Windows or UNIX operating system. These exit values enable JADE administrators to develop tools that can take appropriate actions based on the exit values of the programs.

Windows-based programs can return exit values in the range of zero (0) through 2^32 and UNIX-based programs can reliably return values in the range of zero (0) through 127. JADE programs on Windows have generally returned zero (0) for success or the JADE error number if a problem occurs. It is not possible for UNIX programs to return the full range of JADE error numbers.

Standard exit values are limited to the range 0 through 127. Any value above this range is reserved by the operating system. On UNIX, exit codes above 127 indicate that the program has exited due to a fatal signal. You can derive the signal number that caused the program to exit by subtracting 128 from the exit value; for example, an exit value of 139 indicates that the program exited because it received a fatal signal 11 (SIGSEGV - Invalid memory reference). For the mapping of numbers to signal names and descriptions, see the UNIX documentation that describes the signal(7) feature, using the following command.

man 7 signal

Using standard exit values, ranges of JADE error numbers are grouped into a common generic exit value. In addition, a range of exit values is set aside for warnings, enabling a program to return information without it being regarded as a fatal problem.

Windows-based programs or utilities default to using current exit values, or the generic exit values by setting an initialization file parameter. For details, see “Enabling the Use of Generic Exit Values for Windows”, in the following section.

Note Using generic exit values does not impact on performance of your JADE programs or utilities. It gives the site administrator the ability to write standard support tools.


Appendix A Exit Values 170

JADEICG-6.3

Enabling the Use of Generic Exit Values for Windows The [FaultHandling] section of the JADE initialization file provides the StandardExitValues parameter that enables you to specify that JADE programs or utilities running in a Windows operating system return generic exit values.

As UNIX programs or utilities always use the generic exit values, this parameter is treated as true on UNIX. This parameter defaults to false for programs or utilities running under a Windows operating system, as they can return exit values in the range of zero (0) through 2^32 by default.

To specify that programs and utilities running under a Windows operating system return generic exit values, set the StandardExitValues parameter in the [FaultHandling] section of the JADE initialization file to true.

In addition, you can use the:

CustomExitValue<JADE-error-message-number> parameter in the [FaultHandling] section of the JADE initialization file when the StandardExitValues parameter is set to true, to remap JADE exit values (error numbers) to a user-defined standard exit code in the range 32 through 63.

In a Windows environment, the CustomExitValue parameter is valid only when the StandardExitValues parameter is set to true. If the StandardExitValues parameter is set to false, JADE exits with the applicable JADE error number. If the StandardExitValues parameter is set to true, JADE exists with the applicable error number from the remap table (listed in the following section) and checks for the existence of the CustomExitValue parameter or parameters in the [FaultHandling] section of the JADE initialization file.

Node class userExitCode property to specify the value that is returned when a JADE program (for example, jade.exe, jadapp, jadrap.exe, jaded, and so on) exits. For more details, see Chapter 1 of your JADE Encyclopaedia of Classes.

Tip You can use the userExitCode property, for example, to set a non-zero exit code that can then be checked in a batch file by using the ERRORLEVEL keyword to check for appropriate values of the userExitCode property.

General Exit Values Unique to Each Program The following table lists the exit values that are unique to each program (that is, an exit value for the jadload program may have a different meaning from that for the jade program).

Value Description JADE Number Range

127 Fatal network errors -101 through -120

0 Success, no error 0

1 Methods in error were detected by the schema load 8510

2 One or more commands in command file did not complete successfully 8514

3 Upgrade validation failed 8723

4 Reorganization is required 8511

5 Reorganization operation cancelled by user request 3404

6 Reorganization is suspended waiting for the transition to be initiated 3413

7 Versioned control subclasses require reorganization during online deployment 8525



JADEICG-6.3


8 Schema load resulted in one or more incomplete schemas 8527

9 through 31 Reserved, on an individual JADE program basis Unspecified

32 through 63 User-defined exit values Unspecified

64 through 78 Reserved by the operating system Unspecified

105 JADE Object Manager errors 4 through 1299

106 Collection exception errors 1300 through 1349

107 Miscellaneous runtime errors 1400 through 1448

114 Trace exception errors 1500 through 1599

127 Remote procedure call (RPC) request errors 1600 through 1699

108 Security errors 1700 through 1799

113 Database engine errors 3000 through 3199

116 Synchronized Database Service (SDS) database errors 3200 through 3399

112 Database reorganization errors 3400 through 3499

127 Database server remote interface errors 3500 through 3599

120 JADE language interpreter errors 4000 through 4499

109 JADE Query Engine internal errors 4500 through 4999

114 File handling errors 5000 through 5099

114 Multimedia handling errors 5100 through 5299

114 Sort errors 5300 through 5399

121 Licence errors 5500 through 5599

112 JADE Object Manager data interchange errors 5700 through 5799

112 Internal management message exchange errors 5900 through 5999

119 Compiler errors 6000 through 6999

118 Method and schema file syntax errors 7000 through 7999

110 External database errors 8000 through 8255

125 ODBC errors 8256 through 8499

126 JADE Schema Load utility errors 8500 through 8599

111 JADE Dump and Load utility upgrade errors 8600 through 8699

111 Upgrade errors 8700 through 8799

112 JADE ActiveX Exposure errors 8800 through 8899

124 JADE Database utility errors 9000 through 9999

117 TCP/IP network errors 10000 through 10499

122 JADE Monitor errors 11000 through 11999

127 JADE Remote Node Access utility errors 12000 through 12999

123 JADE user interface run time errors 14000 through 14499

123 JADE translatable string errors 14500 through 14999

114 Print errors 15000 through 15099

114 Editor errors 15500 through 15599

115 JADE development environment errors 16000 through 16999

117 Application connection errors 30000 through 30999



JADEICG-6.3


117 TCP/IP connection errors 31000 through 31499

117 Network proxy errors 31500 through 31999

117 Secure Sockets Layer (SSL) errors 32000 through 32499

117 X509 Certificate errors 32500 through 32999

112 Shared memory errors 33500 through 33599

116 Kernel, multiple server, errors, SDS 34000 through 34999

116 SDS and inter-node communication errors 35000 through 35999

64 Command line usage error

65 Data format error

66 Cannot open input

67 Addressee unknown

68 Host name unknown

69 Service unavailable

70 Internal software error

71 System error (for example, cannot fork)

72 Critical operating system file missing

73 Cannot create (user) output file

74 Input/output error

75 Temporary failure; user is prompted to retry

76 Remote error in protocol

77 Permission denied

78 Configuration error

____________________________________

JADEICG-6.3

Index

.conf files, 147

.htaccess files, 134

A access

remote, 153 ActiveX Exposure DLL

exporting JADE objects, 20 address

selecting network, 106-107 selecting TCP/IP, 106-107, 153

administration JADE, 156-162 specifying installation preferences, 156-162

Administration option button, 160-161 --all parameter, 56, 84 ANSI files

obtaining version, 165-168 reading and writing data, 111 setting version of, 167

Apache HTTP Server accessing JADE applications, 110-111 configuration directives, 133-146 configuration examples, 147-150 configuring, 132-150 connecting to applications, 110-111 error handling, 136 location, 51, 79 maximum message size, 141 minimum message size, 142

Application directive, 135 application server

automatically created subsystem, 52, 80 batch, 64, 92 invoking, 64, 92 operational requirements, 16, 19, 48, 76 running batch, 63, 91 specifying command line parameters, 64, 92

applications accessing, 153 Apache HTTP Server connections, 110-111, 132-150 application server operational requirements, 16, 19,

48, 76 batch application server, 63, 91 closing conflicting, 22, 37

applications (continued) configuring Compact JADE, 41-43 configuring user, 28-29 controlling execution of JADE thin client, 153 converting, 22-23, 26, 113 crash log, 32 database server node operational requirements, 15-19,

47-48, 75-76 executing at specific times, 67, 95 generic operating system exit values, 169-172 handling fatal errors, 32 handling Windows operating system errors, 32 hardware requirements, 15-17, 47-49, 76-77 headless portable GUI, 117 HTML documents, 123, 135 HTML-enabled, 108-111, 117-150 installing Compact JADE, 36-40 installing JADE thin client, 105-106 installing runtime, 23, 36-40 Internet access security, 121, 132-133, 138 Internet Information Server (IIS) connections, 110 Internet interface, 108-111, 117-150 JADE thin client, 15-19, 34-43, 48-49, 63, 76-77, 91,

114-116 Jade61, 123, 135 Java framework software requirements, 20, 51, 79 Linux Web connections, 110-111 location of installed, 102-106 maximum wait time when starting, 65, 93 multiple, 152-156 multiple Web connections, 110-111 non-GUI batch server, 64, 92 non-GUI client, 65-66, 93-94 operating system process id log, 32 operational requirements of Compact JADE, 34-36 operational requirements of JADE standard client, 17,

49, 77 operational requirements of JADE thin client, 15-19,

34-36, 48-49, 76-77 overview of Compact JADE, 33 performance considerations, 107-108 portable GUI client, 20, 50, 63, 78, 91, 114-116 portable GUI software requirements, 20, 50, 78, 91 presentation client installed file locations, 105-106 presentation client operational requirements, 17-19,

49, 77


Index 174

JADEICG-6.3

applications (continued) Red Hat hardware requirements, 76-77 reserving runtime licences, 31, 163-164 runtime installation, 23, 36-40 security for HTML thin clients, 108-110, 117-132,

135-136, 145-146 setting up for Java framework, 67, 95 software requirements, 18-19 specifying command line parameters, 114, 151, 155 standard (fat) client, 63, 91, 114-116 standard client node operational requirements, 16, 19,

48, 76 starting multiple, 65, 93 substituting fonts, 113 suppressing the logging on Internet messages in, 121,

132-133, 138 SUSE Linux Enterprise Server hardware requirements,

47-49 uploading files from Web-enabled, 130-131, 136 Web service, 123, 135 Web-enabled forms, 123, 135 Windows hardware requirements, 15-17 Windows software requirements, 18-20

ApplicationType directive, 135 ApplicationType parameter, 122-123 archive files

Java, 115 arguments

portable GUI Java Virtual Machine ( JVM), 117 attributes

mapping JADE, 21 specifying UNIX character, 62, 90

AutomaticDownLoad parameter, 156

B backup

database, 113, 159 Backup Database command, 159 batch application server program, 63-64, 91-92 batch database

setting user file version, 167 batch JADE Database utility, 167 batch registration program, 163-164 binmask parameter, 166 binpath parameter, 166 browser

Web, 108-111, 117-150 busy.htm file, 127, 142 byte order, 139-140

C C# class library

exposing JADE objects, 20 C# Exposure wizard, 20

card Apache network interface, 141

case conversion specifying UNIX, 62, 90

catalog jadmsgs, 67-71, 95-99

changes patch version, 160

character attributes specifying UNIX, 62, 90

character classification specifying UNIX, 62, 90

characters size of, 139-140

class JadeInternetTCPIPConnection, 110-111

classes specifying location of Java, 67, 95

classification specifying UNIX character, 62, 90

CLASSPATH environment variable, 67, 95, 114-115 ClassPath parameter, 67, 95, 114 client

C#, 20 client nodes

administering, 156-162 Compact JADE, 34-43 Compact JADE configuration on, 41-43 Compact JADE differences, 33 Compact JADE installation on, 36-40 Compact JADE operational requirements, 34-36 configuring, 27-28 configuring Compact JADE under Windows CE on,

41-43 HTML thin, 108-111, 117-150 initializing, 113 installing Compact JADE under Windows CE on, 36-40 Intel, 63, 91, 115 JADE thin, 63, 91, 114-116 large number of concurrent persistent locks, 150 large number of concurrent transient, 150 Linux, 63, 91, 115 local intra-machine transport, 107-108 non-GUI, 65-66, 93-94 operational requirements, 15-21, 34-36, 48-49, 76-77 persistent lock hash size, 150 portable GUI, 20, 50, 63, 78, 91, 114-116 presentation, 20, 50, 63, 78, 91, 114-116 Red Hat, 76, 91 Red Hat operational requirements, 76-77 registering large number of notifications, 150 running as non-GUI services, 65-66, 93-94 running JADE, 153 runtime licences for HTML (Web) thin, 31, 163-164 runtime licences for JADE thin, 31, 163-164 runtime licences for standard (fat), 31, 163-164


Index 175

JADEICG-6.3

client nodes (continued) selecting network addresses, 106-107 selecting TCP/IP addresses, 106-107, 153 standard (fat), 63, 91, 114-116 substituting fonts, 113 SUSE Linux Enterprise Server, 48, 63, 115 SUSE Linux Enterprise Server operational

requirements, 47-49 transient lock hash size, 150 UNIX, 63, 91, 115 Windows, 14-31, 106-113, 117-132, 151-156, 163-164 Windows CE, 33-43 Windows CE operational requirements, 34-36 Windows operational requirements, 15-20

CloseDelay directive, 146 CloseDelay parameter, 123 code

finding position in source, 159 removing source, 159

columns mapping JADE attributes to relational, 21

command Backup Database, 159 Exit, 158 jadeinstall, 53-57, 81-85 Logoff, 158 Preferences, 156 Removing Source Code, 159 Reset to Defaults, 159 Save & Exit, 158 Save & Logoff, 157 setUserFileVersions, 167

command line application server, 64, 92 initialization file, 30 JADE, 151, 155 jade.ini file parameters, 151, 155 non-GUI client, 65-66, 93-94 qualified jade.ini file section name, 151, 155 user options, 64-65, 92-93, 151-152, 155

communications protocol configuration, 52, 80, 106-108, 153

Compact JADE configuration, 41-43 configuring, 41-43 configuring under Windows CE, 41-43 hardware requirements, 34-36 installing, 33-40 operational requirements, 34-36 overview, 33 software requirements, 34-36

compiler installation, 24 components

installing file, 24 concurrent persistent locks hash size, 150 concurrent transient locks hash size, 150

configuration Apache HTTP Server directives, 133-150 batch application server, 63, 91 communications protocol, 52, 80, 106-108, 153 Compact JADE, 41-43 database, 113 error log file, 112 example production system, 101 JADE, 26-29, 32, 63, 67, 91, 95, 101, 106-143, 148-162,

170 JADE Linux, 63, 91, 115 JADE portable GUI, 114 JADE Red Hat Linux, 91 JADE security, 112 JADE SUSE Linux Enterprise Server, 63, 115 JADE UNIX, 63, 91, 115 local intra-machine transport, 107-108 multiple thread, 153 multiuser, 26-29, 41-43, 106-111, 117-143, 148-150 network, 106-107 single user, 26-29, 41-43, 156 TCP/IP, 52, 80, 106-111, 117-132, 135-150, 153 TCP/IP Apache HTTP Server connections, 110-111,

132-150 TCP/IP Internet Information Server (IIS)

connections, 108-110, 117-131 UNIX, 45-46, 52, 61-74, 80, 89-99, 115 Windows, 26-29, 151-156 Windows CE, 41-43 Windows Mobile device, 41-43

ConnectionGroup directive, 146 ConnectionGroup parameter, 123 connections

closing inactive TCP/IP, 123, 146 multiple Web, 110-111, 132-150 names of, 109, 125-131 sharing group, 122-124, 137 TCP/IP, 123-125, 145 TCP/IP group, 123, 146

conversion specifying UNIX case, 62, 90

converting between JADE releases, 22-23, 26, 113 core dumps

obtaining Linux, 60, 87 CrashLogDirectory parameter, 32 createVirtualDirectoryFile method, 118-119, 128-130, 143 custom installation, 23, 38 CustomExitValue parameter, 170

D daemon

JADE, 62, 90 data

ANSI, 111 debugging, 132, 138-139


Index 176

JADEICG-6.3

data (continued) location of program, 102-104 location of user, 102-104 replicating, 21 security of, 121, 132-133, 138 Unicode, 111 upgrading user, 22-23, 26

data map files obtaining version of user, 165-168 setting version of user, 167

database accessing, 153 administering, 167 automatically created subsystem, 52, 80 backing up, 113, 159 configuring multiple threads, 153 configuring Web-enabled, 113 creating tables and columns in relational, 21 getting applied system schema hot fixes, 165-168 hardware requirements, 15-16, 47-48, 75-76 initializing, 29 mapping JADE, 21 obtaining a relational view, 19 overview of relational, 21 patch version, 160 relational, 21 retrieving and updating objects, 20 setting user data file version number, 167 size of production system, 101 software requirements, 19 specifying path, 163 upgrading JADE, 22-23, 26

database server operational requirements for JADE, 15, 47, 75

datpath parameter, 166 debugger

configuring the JADE Just-In-Time, 32 installing the JADE Just-In-Time, 38

debugging data, 132, 138-139 default installation preferences, 156-162 de-installing JADE on UNIX server nodes, 86 --deploydata parameter, 84 deployment installation, 23, 36-40 desktop

running multiple, 15 destination directory specification, 23-25, 38 --devdata parameter, 56, 84 --devel parameter, 56, 84 development installation, 23, 38 devices

configuring Compact JADE applications on hand-held, 41-43

configuring JADE applications on Windows Mobile, 41-43

installing Compact JADE applications on hand-held, 36-40

installing JADE applications on Windows Mobile, 36-40

devices (continued) running JADE applications on hand-held, 33-36 running JADE applications on PDA, 33-43 running JADE applications on Windows Mobile, 33-43

directive Apache HTTP Server configuration, 133-146 Application, 135 ApplicationType, 135 CloseDelay, 146 ConnectionGroup, 146 FaultDocument, 136 FileTransferDirectory, 136 Firewall, 137 GroupSharesConnection, 137 JadeHttp_Trace, 138-139 JadeServer, 139-140 JadeTimeout, 140 LocalInterface, 141 MaxInUse, 145 MaxMessageSize, 141 MaxQueueDepth, 142 MinInUse, 145 MinMessageSize, 142 PhysicalDirectory, 143 PurgeDirectoryFrequency, 143 PurgeFileAge, 144 SetHandler, 134 TcpConnection, 145 TcpPort, 146 VirtualDirectory, 146

directory Apache transfer, 136 client node Java home, 114-116 Compact JADE files, 38 crash log, 32 HOME, 102-106 JADE files, 25 JADE HOME, 102-106 jadehttp.log file, 132 Java classes, 63, 91, 114-115 location of, 102 location of HOME, 103 location of installation, 103 location of program data, 103 location of user data, 104 location of work, 102, 105-106 operating system process id, 32 physical Apache, 143 portable GUI Java Archive ( jar) file path, 115 portable GUI library path, 115-116 presentation client Java home, 20, 50, 78, 91, 114-116 presentation client Java library path, 115-116 Program Files, 102-104 specifying destination, 23-25, 38 standard (fat) client Java home, 114-116 standard (fat) client library path, 115-116 virtual Apache, 143-144


Index 177

JADEICG-6.3

directory (continued) virtual IIS, 118-132

disk usage using HTML thin clients to improve, 108-111, 117-150 using JADE thin clients to improve, 63, 91, 114-116

--docs parameter, 56, 84 documents

HTML, 123, 135 domain sockets, 107-108 Dr Danyo exception handler, 32 drivers

installing ODBC, 19 dump

obtaining Linux core, 60, 87

E eclipse.sh shell script, 67, 95 editor pane

maintaining default preferences, 161 endJade parameter, 152 entities

mapping JADE, 21 environment

ANSI file, 165-168 file type, 165-168 obtaining file version information, 165-168 setting file version information, 167 Unicode file, 165-168 virtual, 21

environment variable CLASSPATH, 67, 95, 114-115 JADEHOME, 60, 88 JADELANGDIR, 62, 67-71, 90, 95-99 JAVA_HOME, 114-116 JMFHOME, 116 JRE_HOME, 114-116 LANG, 61, 67-71, 89, 95-99 LC_CTYPE, 62, 90 LD_LIBRARY_PATH, 61, 89, 115-116 NLSPATH, 61, 67-71, 89, 95-99 PATH, 61, 89, 115 TMPDIR, 62, 90 UNIX, 60-62, 67-71, 88-90, 95-99, 114-116 Windows, 115-116

error-correcting memory on UNIX, 47, 75 errors

Apache HTTP Server, 136 configuring log files, 112 custom exit values, 170 generic exit values, 170-172 handling fatal, 32 handling Windows operating system, 32 locating source code position, 159 standard exit values, 170 translating UNIX, 67-71, 95-99

example of Apache HTTP Server configuration, 147-150

--examples parameter, 56, 84 exception handler

default, 32 Dr Danyo, 32 Just-In-Time debugger, 32

exceptions handling, 32 locating source code position, 159 system, 32

executable program jadapp, 153-155 jadappb batch, 63-64, 91-92 jadclient, 65-66, 93-94, 153 jade, 26, 29, 41, 151-156 jadepg, 63, 91, 114-117, 152, 156 jadrap, 153 jadregb batch, 163-164 jdbutilb, 167 jverinfo, 165-168 setup, 21-25, 36-40, 44-99 shared jade.ini file, 151, 155

execution application server batch, 64, 92 application server service, 153 controlling JADE thin client application, 153 non-GUI client application, 65-67, 93-95 non-GUI client application under headless portable

GUI, 117 Exit command, 158 exit values

custom, 170 generic, 170-172 standard, 170

external database software requirements, 19 external interface

ActiveX Exposure DLL, 20 Apache local network, 137, 141 C# class library, 20 HTML thin client, 108-111, 117-150 installing, 24 Internet, 51, 79, 108-111, 117-150 ODBC, 19 ODBC RPS mapping, 21 security for HTML thin client, 108-110, 117-132,

135-136, 145-146 extract file automation, 65, 93

F --f parameter, 56, 84 fat (standard) clients

reserving licences, 31, 163-164 support for JADE, 31, 163-164

fatal error handling, 32 FaultDocument directive, 136 files

.conf, 147


Index 178

JADEICG-6.3

files (continued) .htaccess, 134 Apache HTTP Server error, 136 application log, 32 busy.htm, 127, 142 command line parameters in jade.ini, 151, 155 debugging data in jadehttp library, 132 debugging data in mod_ jadehttp, 138-139 extract, 65, 93 generating standard text, 67, 95 getting patches applied to system schema, 165-168 httpd.conf, 148-150 installation destination directory, 23-25, 38 installing, 23-25, 38 JADE Internet environment image, 118-121, 128-131,

143-144 jade.conf, 147-150 jade.ini, 27-32, 52, 58, 62-71, 80, 86, 90-99, 112-121,

131, 150-155, 163, 170 jadehttp library, 108-110, 117-132, 135, 145-146 jadehttp library log, 132 jadehttp library trace, 132 jadehttp.ini, 108-110, 117-132 jadepg executable, 63, 91, 115 jadrap, 153 jadregb, 163-164 Java Archive ( jar), 115 jdbutilb, 167 locales.msg, 70-71, 98-99 location of HOME directory, 103 location of installation directory, 103 location of installed presentation client, 105-106 location of program data, 103 location of user data, 104-106 location of work directory, 102, 105-106 log, 112 mod_ jadehttp module, 110-111, 132-150 mod_ jadehttp trace log, 138-139 multiple jade.ini, 29 obtaining version of, 165-168 obtaining version of ANSI, 165-168 obtaining version of Unicode, 165-168 obtaining version of user data map, 165-168 operating system process id log, 32 parameter, 65, 93 physical directory, 143 qualified section names in jade.ini, 151, 155 readme.txt, 26 selecting installed, 24 setting version of, 167 setting version of ANSI, 167 setting version of Unicode, 167 setting version of user data map, 167 setup executable, 21-25, 36-40, 44-99 sharing jade.ini, 151, 155 text box input, 130-131, 136 two-level section names in jade.ini, 151, 155

files (continued) Unicode version, 18, 51, 79 UNIX translation, 67-71, 95-99 uploading Web-enabled application, 130-131, 136 virtual directory, 118-121, 128-131, 143-144

FileTransferDirectory directive, 136 parameter, 121, 130-131

Firewall directive, 137 Firewall parameter, 118-121, 128-131 firewalls

Web-enabled application security, 117-132, 135-137, 145-146

FirstTcpPort parameter, 108-110, 117, 122-128, 145 fixes

getting applied system schema hot, 165-168 fonts

substituting Windows, 113 --force parameter, 56, 84 forms

extracting, 65, 93 upgrading JADE, 22-23, 26 Web-enabled, 123, 135

framework .NET, 20 Java, 20, 51, 67, 79, 95

G --g parameter, 55, 83 getAppliedPatches method, 165-168 getJadeHomeDirectory method, 103 getJadeInstallDirectory method, 103 getJadeWorkDirectory method, 105-106 getProgramDataDirectory method, 103 getUserDataDirectory method, 104 getUserPatchVersion method, 165-168 grid

displaying, 162 snapping, 162 specifying width and height, 163

group TCP/IP connection, 123, 146

--group parameter, 55, 83 GroupSharesConnection directive, 137 GroupSharesConnections parameter, 122-124

H hand-held devices

configuring Compact JADE applications on, 41-43 installing Compact JADE applications on, 36-40 running JADE applications on, 33-36

handling exceptions, 32 hardware requirements

application server, 16, 48, 76 Compact JADE, 34-36


Index 179

JADEICG-6.3

hardware requirements (continued) database server node, 15-16, 47-48, 75-76 JADE, 15-17, 47-49, 76-77 JADE disk space, 15-17, 47-49, 75-77 JADE standard client, 17, 49, 77 JADE thin client, 15-17, 34-36, 48-49, 76-77 presentation client node, 17, 49, 77 Red Hat, 76-77 standard client node, 16, 48, 76 SUSE Linux Enterprise Server, 47-49 UNIX, 46 Windows, 15-17, 76 Windows CE, 34-36

headless portable GUI running non-GUI application under, 117

help Linux requirements for online, 50, 78 obtaining online, 160

--help parameter, 55, 83 help parameter for batch registration, 165 HOME directory, 102-106

location of, 103-106 home directory of client node Java, 114-116 hooks

authentication and encryption, 112 host

command line parameter, 153-154 specifying UNIX name, 58, 86

host server JADE, 125

hot fixes getting applied system schema, 165-168

HTML documents application type, 123, 135 HTML thin client

accessing JADE applications, 108-111, 117-150 interfacing, 108-111, 117-150 JADE application security, 108-110, 117-132, 135-136,

145-146 reserving runtime licences, 31, 163-164 security, 119

httpd.conf file, 147-150

I --i parameter, 55, 83 IANA. See Internet Assigned Numbers Authority (IANA) IBM xSeries platform. See Intel platform icons

program folder for JADE, 25 IIS. See Internet Information Server (IIS) image files

JADE Internet environment, 118-121, 128-131, 143-144 inactive connections

closing, 123, 146 ini parameter, 62-63, 90-91, 163 initialization file. See jade.ini or jadehttp.ini file

initializing JADE, 29, 66-71, 94-99, 112-115, 118-121, 131, 150, 153

installation application runtime, 23, 36-40 canceling, 26 custom, 23-24, 38 deployment, 23, 36-40 development, 23, 38 ending, 26, 39 external interfaces, 24 JADE, 23 JADE Linux, 44-99 JADE Red Hat Linux, 72-99 JADE SUSE Linux Enterprise Server, 44-71 JADE UNIX, 44-99 JADE Windows, 21-26, 38 presentation client, 23, 36-40 running, 26 specifying destination directory, 25, 38 specifying options, 23-26, 38 specifying preferences, 156-162 specifying program folder, 25 specifying type, 23, 38 specifying user information, 24-25 Windows Mobile device, 36-40

installation directory location of, 103

--installDir parameter, 55, 83 Intel platform

client workstations, 63, 91, 115 deinstalling JADE under Red Hat Linux, 87 deinstalling JADE under SUSE Linux, 59 detailed installation command information, 60-63,

88-91, 115 displaying JADE version packages, 59, 87 installing JADE, 53-55, 82-85 JADE operational requirements, 47-50, 75-78 JADE product and RPM names, 51, 79 Linux port numbers, 52, 80 locales and translatable messages, 67, 95-99 obtaining a core dump for Red Hat Linux, 87 obtaining a core dump for SUSE Linux, 60 online help requirement, 50, 78 overview, 44-45, 72-73 Red Hat Linux, 74-99 registering database for Red Hat, 85 registering database for SUSE Linux, 57 running a non-GUI client application, 65-66, 93-94 running application server under Red Hat, 91-92 running application server under SUSE, 63-64 server workstations, 44-99 setting up Windows client for Red Hat Linux, 86 setting up Windows client for SUSE Linux, 58 SUSE Linux Enterprise Server, 46-67, 115 upgrading a JADE release for Red Hat Linux, 86 upgrading a JADE release for SUSE Linux, 58


Index 180

JADEICG-6.3

interface batch application server, 63, 91 Internet, 19 JADE thin client, 15-19, 34-43, 48-49, 63, 76-77, 91,

105-106, 114-116, 153 internal translation table, 68-71, 95-99 Internet

access security, 121, 132-133, 138 accessing JADE applications, 108-111, 117-150 application security, 108-110, 117-132, 135-136,

145-146 interfacing, 108-111, 117-150 JADE interface, 19, 51, 79 message loggings security, 121, 132-133, 138 minimum reply message size, 128, 142 reserving runtime licences, 31, 163-164 software requirements, 19, 51, 79 text box input type, 121, 130-131, 136 timing out reply messages, 127

Internet Assigned Numbers Authority (IANA), 125 Internet Information Server (IIS), 108-110, 117-131 Internet server

accessing JADE applications, 108-110, 117-132, 135, 145-146

intra-machine local transport, 107-108 IP number specification in UNIX, 58, 86 isVDFilePresent method, 119

J --j parameter, 56, 84 J2SE. See Java 2 Runtime Environment Standard Edition

( J2SE) software J2SE) software jadapp program, 153-155 jadappb batch program, 63-64, 91-92 jadclient program, 65-66, 93-94 JADE

administering, 156-162 command line parameters in the jade.ini file, 151, 155 configuring, 100-168 configuring Compact, 41-43 configuring portable GUI, 114 configuring under Windows, 26-29, 156 configuring under Windows CE, 41-43 configuring UNIX clients, 63, 91, 115 configuring UNIX servers, 52, 61-71, 80, 89-99 de-installing UNIX servers, 86 disk space requirements, 15-17, 47-49, 75-77 displaying licence information, 165 handling multiple program copies, 152-156 hardware requirements, 15-16, 47-49, 76 hardware requirements for Compact, 34-36 initializing, 29, 66-71, 94-99, 109, 112-143, 148-150,

153, 156-162 installing, 21-26, 38, 44-99 installing Compact, 33-40 installing Windows, 21-26

JADE (continued) jade.ini file parameters in the command line, 151, 155 Java framework set-up for, 67, 95 Java framework software requirements, 20, 51, 79 Linux core dump, 60, 87 Linux de-installation, 59, 86-87 Linux installations, 46, 50-57, 78-85 Linux upgrades, 58, 86 list of Linux packages for a specific version of, 59, 87 maintaining multiple copies, 45-46, 73-74 portable GUI software requirements, 20, 50, 78, 91 Red Hat hardware requirements, 76-77 Red Hat installation, 75-77 registering, 30-31, 55-57, 83, 163-164 registering UNIX servers, 57, 85 registering Windows, 30-31, 163-164 selecting program folder, 25 setting up, 23 setting up Linux configuration, 63, 91, 115 setting up Linux installation, 44-99 setting up Red Hat Linux configuration, 91 setting up Red Hat Linux installation, 72-99 setting up SUSE Linux Enterprise Server

configuration, 63, 115 setting up SUSE Linux Enterprise Server installation,

44-71 setting up UNIX configuration, 63, 91, 115 setting up UNIX installation, 44-99 setting up Windows, 21-26, 38 software requirements for Compact, 34-36 specifying command line parameters, 114, 151, 155 SUSE Linux Enterprise Server hardware requirements,

47-49 SUSE Linux Enterprise Server installation, 47-49 uninstalling UNIX servers, 86 UNIX de-installation, 59, 86-87 UNIX hardware requirements, 46 UNIX installations, 46, 50-57, 64-71, 78-85, 92-99 UNIX software requirements, 50-51, 78-79 UNIX upgrades, 58, 86 updating licences, 30-31, 163-164 upgrading, 22-23, 26 Windows CE configuration, 41-43 Windows CE hardware requirements, 34-36 Windows CE installation, 33-40 Windows CE software requirements, 34-36 Windows hardware requirements, 15-17 Windows installation, 14-31, 151-155, 163-164 Windows software requirements, 18-20

JADE applications Internet access security, 121, 132-133, 138 Internet message logging security, 121, 132-133, 138

JADE daemon, 62, 90 JADE deployed applications

hardware requirements, 34-36 software requirements, 34-36


Index 181

JADEICG-6.3

JADE development environment disk space requirements, 15-17, 47-49, 75-77 hardware requirements, 15-16, 47-49, 76 software requirements, 18-19

JADE HOME directory, 102-106 JADE interface. See interface JADE Just-In-Time (JIT) debugger, 32, 38 JADE licence. See licences JADE Object Manager initialization, 29, 66-71, 94-99,

112-113, 118-121, 131, 150, 153 JADE Remote Node Access utility, 153 JADE security

configuring, 112 enabling and disabling, 112

JADE subsystem automatically created, 52, 80

JADE system getting version information, 165-168 reregistering deployed, 163-164 setting user data file version information, 167

JADE thin client controlling application execution, 153 portable GUI handling, 156 reserving runtime licences, 31, 163-164

JADE Version Information utility, 165-167 jade.conf file, 147-150 jade.exe program, 26, 29, 41, 151-156 jade.ini file, 27-32, 52, 58, 62-71, 80, 86, 90-99, 112-121,

131, 150-155, 163, 170 Jade61 application type, 123, 135 jaded program, 61-62, 89-90 JADEHOME environment variable, 60, 88 --jadeHome parameter, 56, 84 JadeHost parameter, 125 jadehttp library file, 108-110, 117-132, 135, 145-146 jadehttp.ini file, 108-110, 117-132 JadeHttp_Trace directive, 138-139 jadeinstall command, 53-57, 81-85 JadeInternetTCPIPConnection class, 110-111 JADELANGDIR environment variable, 62, 67-71, 90,

95-99 jadepg program, 63, 91, 114-117, 152, 156 JadeServer directive, 139-140 JadeTimeout directive, 140 JadeWorkDirectory parameter, 105-106 jadmsgs catalog, 67-71, 95-99 jadrap program, 153 jadregb program, 163-164 jar. See Java Archive ( jar) files Java

archive ( jar) files path directory, 115 classes directory for, 63, 91, 114-115 client node home directory, 114-116 library path directory, 115-116 presentation client home directory, 20, 50, 78, 91,

114-116 presentation client library path directory, 115-116

Java (continued) standard (fat) client home directory, 114-116 standard (fat) client library path directory, 115-116

Java 2 Runtime Environment Standard Edition ( J2SE) software, 20, 50-51, 63, 67, 78-79, 91, 95, 114-116

Java Archive ( jar) files path directory for client node Java, 115

Java font substitution for Windows fonts, 113 Java framework

setting up the, 67, 95 software requirements, 20, 51, 79

Java Media Framework ( JMF) software, 20, 50, 63, 78, 91, 115

Java user classes specifying location of, 67, 95

Java Virtual Machine ( JVM) software archive files for, 115 arguments for, 117

java.sh shell script, 67, 95 JAVA_HOME environment variable, 114-116 JavaHome parameter, 114 jdbutilb program, 167 JIT debugger. See JADE Just-In-Time (JIT) debugger JMF. See Java Media Framework ( JMF) software JMFHOME environment variable, 116 JRE_HOME environment variable, 114-116 jverinfo program, 165-168

K --k parameter, 55, 83 key parameter, 164 keys

licence, 24-25, 30-31, 38, 55, 83, 163-164

L LANG environment variable, 67-71, 61, 95-99 98, 89, 99 languages

specifying UNIX, 61, 67-71, 95-99 LANG-variable parameter, 67-71, 95-99 LastTcpPort parameter, 108-110, 117, 122, 125 LC_CTYPE environment variable, 62, 90 LD_LIBRARY_PATH environment variable, 61, 89,

115-116 libmask parameter, 166 libpath parameter, 166 library

C# class, 20 JadeHttp, 118-121, 128-131 path directory for client node Java, 115 software requirements for .NET, 20

library path directory client node Java, 116

licences confirming agreement terms, 23, 37 developer, 32


Index 182

JADEICG-6.3

licences (continued) displaying information, 165 expiry date, 32 JADE Report Writer, 32 perpetual, 32 process, 32 Rational Rose JADE Link, 32 registering new JADE, 30-31, 163-164 reserving minimum server, 31, 163-164 secondary, 32 server, 31, 163-164 specifying, 24-25, 38 updating JADE, 30-31, 163-164

Linux client nodes, 63, 91, 115 configuring JADE, 63, 91, 115 installing JADE, 44-99 obtaining core dump, 60, 87 operating system, 44-99, 115 Red Hat, 72-99 server nodes, 44-99 shell scripts, 45, 57, 60, 67, 73, 85, 88, 95 SUSE, 44-71, 115 Web connections to JADE applications, 110-111

local intra-machine transport configuration, 107-108 local network interface for Apache, 137, 141 locales

UNIX, 67-71, 95-99 locales.msg file, 70-71, 98-99 LocalInterface directive, 141 location

accessing directory, 102-106 specifying work directory, 102, 105-106

locbuild program, 70-71, 98-99 locks

hash size for concurrent persistent, 150 hash size for concurrent transient, 150

logging Intenet messagesurity, 121, 132-133, 138 Logoff command, 158 logs

application crash, 32 configuring, 112 crash, 32 jadehttp library, 132 mod_ jadehttp, 138-139 operating system process id, 32

M map files

obtaining version of user data, 165-168 setting version of user data, 167

mapping JADE entities to relational database entities, 21 overview of RPS, 21

MaximumPipes parameter, 122, 125 MaxInUse directive, 145

MaxInUse parameter, 126 MaxMessageSize directive, 141 MaxMessageSize parameter, 126 MaxQueueDepth directive, 142 MaxQueueDepth parameter, 126-127 MaxWaitAppStart parameter, 65, 93 memory

critical components, 17, 49, 77 error-correcting UNIX, 47, 75

messages maximum size, 126, 141 minimum size, 128, 142 suppressing the logging of Internet, 121, 132-133, 138 timing out, 140 timing out Web browser reply, 127, 140 translating UNIX, 67-71, 95-99

MessageTimeout parameter, 127 method

createVirtualDirectoryFile, 118-119, 128-130, 143 finding source code position, 159 getAppliedPatches, 165-168 getJadeHomeDirectory, 103 getJadeInstallDirectory, 103 getJadeWorkDirectory, 105-106 getProgramDataDirectory, 103 getUserDataDirectory, 104 getUserPatchVersion, 165-168 isVDFilePresent, 119 readPipeCallback, 120 startApplication, 65, 93

Microsoft SQL Server, 21 Microsoft Vista support, 102-106 migrating to a new JADE release, 22-23, 26, 113 minimum disk space requirements, 15-17, 48-49, 75-77 minimum hardware requirements, 15-17, 47-49, 76-77 minimum software requirements, 16, 48, 76 MinInUse directive, 145 MinInUse parameter, 127 minJade parameter, 164 MinMessageSize directive, 142 MinMessageSize parameter, 127-128 minStandard parameter, 164 Mobile devices

configuring JADE applications on Windows, 41-43 installing JADE applications on Windows, 36-40 operational requirements for Windows, 34-36 running JADE applications on Windows, 33

mod_ jadehttp module file, 110-111, 132-150 mode

default configuration, 26-29, 41-43, 106-111, 117-143, 148-150

HTML (Web) thin client, 31, 108-111, 117-150, 163-164

JADE database server, 15, 47, 75 JADE thin client, 15-19, 31, 34-43, 48-49, 63, 76-77, 91,

105-106, 114-116, 153, 156, 163-164 multiuser, 26-29, 41-43, 106-111, 117-143, 148-150, 153


Index 183

JADEICG-6.3

mode (continued) portable GUI, 63, 91, 114-116 single user, 26-29, 41-43 standard (fat) client, 17, 31, 49, 63, 77, 91, 114-116,

163-164 monitors

multiple, 15 MPM. See Multi-Processing Module (MPM) mpm_winnt Multi-Processing Module (MPM), 111 multiple copies maintenance, 45-46, 73-74 multiple desktop support, 15 multiple thread configuration, 153 multiplier

size, 141 time unit, 144

Multi-Processing Module (MPM) implemented Apache, 110-111, 132 mpm_winnt, 111 prefork, 111 worker, 111

multiuser mode configuring, 26-29, 41-43, 106-111, 117-143, 148-150 local intra-machine transport, 107-108 multiple JADE copies for testing, 153, 156 running JADE, 153 selecting network addresses, 106-107 selecting TCP/IP addresses, 106-107, 153 software requirements, 106-111, 117-143, 148-150

N --n parameter, 55, 83 name parameter, 151, 164 named pipes

Internet Information Server (IIS) connections, 109, 125-131

network configuring, 106-108, 153 selecting addresses, 106-107 specifying number, 106-107

network interface for Apache, 137, 141 NetworkSpecification parameter, 52, 80, 107-108, 153 newcopy command line parameter, 152-153, 156 NLSPATH environment variable, 61, 67-71, 89, 95-99 NodeName parameter, 63-65, 91-93 NodeNameDescription parameter, 63-65, 91-93 nodes

adding processing, 65-66, 93-94 application server, 16, 48, 64, 76, 92, 153 batch application server, 63, 91 C# client, 20 client, 156-162 Compact JADE, 33-43 database server, 15, 47, 75 generic exit values, 170-172 headless portable GUI, 117 HTML thin client, 108-111, 117-150

nodes (continued) initializing client, 113 initializing server, 67, 95 installed file locations on presentation client, 105-106 Intel client, 63, 91, 115 Intel server, 44-99 JADE thin client, 63, 91, 114-116 Linux client, 63, 91, 115 Linux server, 44-99 non-GUI client, 65-66, 93-94 operating system differences in Compact JADE, 33 operational requirements of application server, 16, 19,

48, 76 operational requirements of database server, 15-16, 19,

47-48, 75-76 operational requirements of presentation client, 17-19,

49, 77 operational requirements of standard client, 16, 19,

48, 76 peak users of, 101 portable GUI client, 20, 50, 63, 78, 91, 114-116 presentation client, 15-19, 34-43, 48-49, 76-77, 105-106 Red Hat client, 76 Red Hat Linux client, 91 Red Hat server, 72-99 Relational Population Service (RPS), 21 RS/6000 server, 96 server, 156-162 standard (fat) client, 63, 91, 114-116 standard client, 16-19, 48-49, 76-77 substituting fonts on client, 113 SUSE Linux Enterprise Server, 44-71, 115 SUSE Linux Enterprise Server client, 48 SUSE Linux Enterprise Server server, 48 UNIX client, 63, 91, 115 UNIX server, 44-99 Windows CE client, 33-43 Windows client, 14-31, 106-113, 117-132, 151-156,

163-164 Windows server, 14-31, 106-113, 117-132, 151-156,

163-164 non-GUI applications

batch server, 64-65 client, 65-67, 93-94 configuring headless portable GUI for, 117

non-GUI client applications maximum wait time when starting, 65, 93 running, 65-66, 93-94

NotificationHashSize parameter, 150 notifications

hash size for, 150 registering large number of, 150

O objects

ActiveX access of JADE, 20


Index 184

JADEICG-6.3

objects (continued) automatically replicating, 21 exposing C# class library, 20 mapping JADE, 21 retrieving and updating database, 20

ODBC. See Open Database Connectivity (ODBC) online help

Linux requirements, 50, 78 obtaining, 160

online parameter for batch registration, 164 Open Database Connectivity (ODBC)

decimal specification, 113 installing a driver, 19 obtaining a relational view, 19 RPS mappings, 21 software requirements, 19

operating system generic exit values, 169-172 Linux, 44-99, 110-111, 115 obtaining version, 165-168 Red Hat Linux, 72-99 SUSE Linux Enterprise Server, 44-71, 115 UNIX, 169-172 Vista, 102-105 Windows, 15-31, 102-113, 117-132, 151-156, 163-164,

169-172 Windows CE, 33-43

operational requirements application server, 16, 19, 48, 76 database server, 15, 47, 75 database server node, 15-16, 19, 47-48, 75-76 JADE standard client, 17, 49, 77 JADE thin client, 15-19, 34-36, 48-49, 76-77 presentation client node, 17-19, 49, 77 standard client node, 16, 19, 48, 76

order of bytes, 139-140 out parameter, 166

P Package Manager

Red Hat, 45-46, 73-74, 86 pages

text box input type on Web, 121, 130-131 Painter

default preferences maintenance, 162 maintaining default preferences, 162

palette hiding, 162 parameter

--all, 56, 84 ApplicationType, 122-123 AutomaticDownLoad, 156 binmask, 166 binpath, 166 ClassPath, 67, 95, 114 CloseDelay, 123 command line, 64-66, 92-94, 114, 151-155

parameter (continued) configuration, 27, 112, 151, 155 ConnectionGroup, 123 CrashLogDirectory, 32 CustomExitValue, 170 datpath, 166 --deploydata, 84 --devdata, 56, 84 --devel, 56, 84 --docs, 56, 84 endJade, 152-153 --examples, 56, 84 --f, 56, 84 FileTransferDirectory, 121, 130-131 FirstTcpPort, 108-110, 117, 122-128, 145 --force, 56, 84 --g, 55, 83 --group, 55, 83 GroupSharesConnections, 122-124 help, 165 --help, 55, 83 host, 153-154 --i, 55, 83 ini, 62-63, 90-91, 163 --installDir, 55, 83 interface, 154 --j, 56, 84 --jadeHome, 56, 84 JadeHost, 125 JadeWorkDirectory, 105-106 JavaHome, 114 --k, 55, 83 key, 164 LANG-variable, 67-71, 95-99 LastTcpPort, 108-110, 117, 122, 125 libmask, 166 libpath, 166 MaximumPipes, 122, 125 MaxInUse, 126 MaxMessageSize, 126 MaxQueueDepth, 126-127 MaxWaitAppStart, 65, 93 MessageTimeout, 127 MinInUse, 127 minJade, 164 MinMessageSize, 127-128 minStandard, 164 --n, 55, 83 name, 151, 164 NetworkSpecification, 52, 80, 107-108, 153 newcopy, 152-153, 156 NodeName, 63-65, 91-93 NodeNameDescription, 63-65, 91-93 NotificationHashSize, 150 online, 164 out, 166 path, 62-63, 90-91, 152, 163


Index 185

JADEICG-6.3

parameter (continued) PersistentLockHashSize, 150 port, 153-154 portable GUI ignores newcopy, 152, 156 ProcessDumpDirectory, 32 ProgramDataDirectory, 102-103 --q, 56, 84 --quiet, 56, 84 report, 165 --rte, 56, 84 RunAsService, 57, 63-65, 85, 91-93 --s, 55, 83 ServerApplication, 66, 94 ServerNodeSpecifications, 52, 58, 80, 86, 107-108, 153 --serviceName, 55, 83 setUserFileVersions, 167 StandardExitValues, 170 stdout, 166 syspath, 166 --t, 56, 84 --targetType, 56, 84 TcpConnection, 108-110, 117, 122, 125-128 TcpPort, 123, 128 --thinclient, 56, 85 thinClient command line, 151 Trace, 132 TraceFile, 132 TransientLockHashSize, 150 --u, 55, 83 --U, 56, 84 --Upgrade, 56, 84 --usercode, 55, 83 UserDataDirectory, 102-104 UserJVMArgs<n>, 117 UserJVMJars<n>, 115 --v, 55, 83 --version, 55, 83 VirtualDirectory, 119, 128-130 --w32thinclient, 57, 85

parameter file creating extract, 65, 93

patch version maintenance, 160 patches

getting applied system schema, 165-168 path

database, 163 jade initialization file, 164

PATH environment variable, 61, 89, 115 path parameter

batch registration, 163 command line, 152 JADE daemon, 62, 90 JADE portable GUI, 63, 91

PDA. See Personal Digital Assistant (PDA) devices performance

improving, 107-108

persistent locks hash size for concurrent, 150

persistent object C# access, 20

PersistentLockHashSize parameter, 150 Personal Digital Assistant (PDA) devices, 33-43 physical Apache directory, 143 PhysicalDirectory directive, 143 port

Apache HTTP Server, 137, 141 command line parameter, 153-154 first TCP/IP connection, 123-124, 145 last TCP/IP connection, 125 specifying number, 52, 58, 80, 86, 122-125, 135,

145-146, 153 portable GUI environment

client node Java home directory, 114-116 configuring client nodes for, 63, 91, 114-116 headless, 117 JADE and functional differences, 156 JADE thin client automatic upgrade not supported,

156 Java Archive ( jar) file path directory, 115 Java classes directory, 63, 91, 114-115 Java Virtual Machine ( JVM) arguments, 117 library path directory, 115-116 newcopy command line option not supported, 152,

156 presentation client Java home directory, 20, 50, 78, 91,

114-116 presentation client library path directory, 115-116 standard (fat) client Java home directory, 114-116 standard (fat) client Java library path directory,

115-116 POST URL maximum size, 141 preferences

resetting default JADE, 159 specifying installation, 156-162

Preferences command, 156 prefixes

qualified jade.ini file section name, 151, 155 prefork Multi-Processing Module (MPM), 111 presentation client

installing, 23, 36-40 location of installed files on a, 105-106 operational requirements, 17-19, 49, 77

process adding nodes, 65, 93

ProcessDumpDirectory parameter, 32 processing nodes, 65, 93 production system example configuration, 101 program data directory location, 102-104 Program Files directory, 102-104 ProgramDataDirectory parameter, 102-103 programs

batch database utility, 167 batch registration, 163-164


Index 186

JADEICG-6.3

programs (continued) closing running Windows, 23, 37 handling multiple JADE, 152-156 jadapp, 153-155 jadappb batch, 63-64, 91-92 jadclient, 65-66, 93-94 jade.exe, 26, 29, 41, 151-154 jaded, 61-62, 89-90 jadepg, 63, 91, 114-117 jadrap, 153 jdbutilb, 167 jverinfo, 165-168 locbuild, 70-71, 98-99 shared jade.ini file, 151, 155 uninstall, 86

property userExitCode, 170 webInputType, 121, 130-131

protocols configuring communications, 52, 80, 106-108, 153

PurgeDirectoryFrequency directive, 143 PurgeFileAge directive, 144

Q --q parameter, 56, 84 qualified jade.ini file section name prefixes, 151, 155 queue

maximum depth of, 142 queued requests limit specification, 126-127 --quiet parameter, 56, 84

R RDBMS. See Relational Database Management System

(RDBMS) (RDBMS) readme.txt file, 26 readPipeCallback method, 120 Red Hat

configuring JADE, 91 configuring JADE portable GUI, 91 hardware requirements, 76 installing JADE, 76 installing JADE on Linux, 72-99 shell scripts, 73

Red Hat Package Manager (RPM), 45-46, 73-74, 86 registering a new JADE licence, 30-31, 57, 85, 163-164 registering large number of notifications, 150 relational columns

mapping JADE attributes to, 21 relational database

creating tables and columns in, 21 mapping JADE entities to, 21 overview, 21

Relational Population Service (RPS) mapping JADE entities to, 21 overview, 21

Relational Population Service (RPS) nodes. See RPS nodes

Relational Population Service wizard, 21 relational tables

mapping JADE classes to, 21 relational view

using ODBC for JADE, 19 releases

converting between JADE, 22-23, 26, 113 Remote Node Access utility, 153 Removing Source Code command, 159 replicating the JADE database, 21 reply

minimum message size, 128, 142 timing out message, 127

report parameter for batch registration, 165 requests

maximum message size, 126 maximum queued, 126-127

requirements .NET application development and compilation

software, 20 .NET library generation and usage software, 20 ActiveX Exposure DLL software, 20 application server hardware, 16, 48, 76 application server software, 19 Compact JADE hardware, 34-36 Compact JADE software, 34-36 database server hardware, 15, 47, 75 database server node hardware, 15-16, 47-48, 75-76 database server node software, 19 external database coexistence software, 19 JADE disk space, 15-17, 47-49, 75-77 JADE hardware, 15-16, 47-49, 76 JADE Red Hat hardware, 77 JADE software, 19 JADE standard client hardware, 17, 49, 77 JADE SUSE Linux Enterprise Server hardware, 49 JADE thin client hardware, 15-17, 34-36, 48-49, 76-77 JADE thin client software, 19 JADE UNIX hardware, 46 JADE UNIX software, 50-51, 78-79 JADE Windows CE hardware, 34-36 JADE Windows CE software, 34-36 JADE Windows hardware, 15-17 JADE Windows software, 18-20 Java framework software, 20, 51, 79 portable GUI software, 20, 50, 78, 91 presentation client node hardware, 17, 49, 77 presentation client node software, 19 Red Hat hardware, 76 standard client node hardware, 16, 48, 76 standard client node software, 19 SUSE Linux Enterprise Server hardware, 47-49 Windows hardware, 15-16 Windows software, 18-20

Reset to Defaults command, 159


Index 187

JADEICG-6.3

resource using HTML thin clients to improve, 108-111, 117-150

response connection, 127, 140

return values custom, 170 generic, 170-172 standard, 170

RPM. See Red Hat Package Manager (RPM) RPS mapping, 21 RPS nodes, 21 --rte parameter, 56, 84 RunAsService parameter, 57, 63-65, 85, 91-93 runtime licences

reserving, 31, 163-164

S --s parameter, 55, 83 Save & Exit command, 158 Save & Logoff command, 157 schema

automating extraction, 65, 93 extracting, 65, 93 extracting multiple, 65, 93 getting hot fixes applied to system, 165-168 getting patches applied to system, 165-168 RPS mapping, 21 upgrading JADE, 22-23, 26

scripts eclipse shell, 67, 95 java shell, 67, 95 shell, 45, 57, 60, 73, 85, 88

section names qualified jade.ini file, 151, 155 two-level jade.ini file, 151, 155

security configuring, 112 data, 121, 132-133, 138 enabling and disabling, 112 firewalls for Web-enabled application, 117-132,

135-137, 145-146 HTML thin client, 108-110, 117-132, 135-136, 145-146 Internet access, 121, 132-133, 138 Internet interface, 108-110, 117-132, 135-136, 145-146 Internet message logging, 121, 132-133, 138

server Apache Web, 19, 50-51, 78-79, 110-111, 132-150 application, 64, 92, 153 batch application, 63, 91 IIS Web, 19, 51, 79, 110 Internet, 108-110, 117-132, 135, 145-146 JADE host, 125 Red Hat JADE, 76 specifying mode, 64, 92 SUSE Linux Enterprise Server JADE, 47-49 UNIX JADE, 62, 90

server (continued) Windows JADE, 14-16, 19-31, 151-156, 163-164

server applications non-GUI batch, 64, 92

server licences reserving minimum, 31, 163-164

server nodes administering, 156-162 batch application, 63, 91 configuring, 28 configuring multiple threads, 153 default, 153 exporting JADE components through ActiveX, 20 initializing, 67, 95 Intel, 44-99 JADE thin, 63, 91 large number of concurrent persistent, 150 large number of concurrent transient, 150 Linux, 44-99 local intra-machine transport, 107-108 notification hash size, 150 operational requirements, 15-19, 47-48, 75-76 persistent lock hash size, 150 Red Hat, 72-99 Red Hat operational requirements, 76-77 running as services, 57, 85 running JADE, 153 starting multiple applications, 65, 93 SUSE Linux Enterprise Server, 44-71 TCP/IP port, 52, 80, 122-125, 135, 145-146, 153 transient lock hash size, 150 transport type, 107-108, 122-125, 135, 145-146, 153 UNIX, 44-99 Windows, 14-31, 106-113, 117-132, 151-156, 163-164 Windows operational requirements, 15-20

ServerApplication parameter, 66, 94 ServerNodeSpecifications parameter, 52, 58, 80, 86,

107-108, 153 service

relational population, 21 running server, 57, 65-66, 85, 93-94 Web, 123, 135

--serviceName parameter, 55, 83 SetHandler directive, 134 setting up the Java framework, 67, 95 setup executable program, 21-25, 36-40, 44-99 setUserFileVersions command, 167 setUserFileVersions parameter, 167 shared jade.ini file, 151, 155 shared memory transport, 107-108 shell script, 45, 57, 60, 67, 73, 85, 88, 95 single user mode

configuring JADE, 26-29, 41-43, 156 software requirements, 18

size of characters, 139-140 software

.NET, 20


Index 188

JADEICG-6.3

software (continued) ActiveX access of JADE objects, 20 application server, 19 Compact JADE, 34-36 database server node, 19 external database, 19 JADE thin client, 19 Java 2 Runtime Environment Standard Edition (J2SE),

20, 50-51, 63, 67, 78-79, 91, 95, 114-116 Java Media Framework ( JMF), 20, 50, 63, 78, 91, 115 multiuser mode, 106-111, 117-143, 148-150 Open Database Connectivity (ODBC), 19-20 presentation client node, 19 single user mode, 18 standard client node, 19 UNIX, 50-51, 78-79 Windows, 18-20, 26-27

source code finding position, 159 removing, 159

SQL statements, 19 SQL Server, 21 SQL type

mapping JADE attributes to relational, 21 standard (fat) client licences, 31, 163-164 standard client node operational requirements, 16, 19,

48, 76 StandardExitValues parameter, 170 startApplication method, 65, 93 starting an application at a specific time, 67, 95 status line

hiding Painter, 162 stderr output, 163 stdout output, 163 stdout parameter, 166 substituting Windows for Java fonts, 113 subsystem

automatically created, 52, 80 SUSE Linux Enterprise Server

configuring JADE, 63, 115 configuring JADE portable GUI, 63, 115 hardware requirements, 47-49 installing JADE, 44-71

syspath parameter, 166 system

example configuration of production, 101 handling exceptions, 32 Linux operating, 110-111 reregistering deployed JADE, 163-164 Windows operating, 110-111

system schemas getting hot fixes, 165-168 getting patches, 165-168

T --t parameter, 56, 84

tables internal translation, 68-71, 95-99 mapping JADE classes to relational, 21 overriding UNIX translation, 67-71, 95-99

target application specification on command line, 114 --targetType parameter, 56, 84 TCP/IP

Apache connections, 136-144, 147-150 Apache HTTP Server configuration, 132-150 Apache HTTP Server connections, 110-111 closing inactive connections, 123, 146 configuring, 52, 80, 106-111, 117-132, 135-150, 153 connection group for, 123, 146 first connection port for, 123-124, 145 Internet Information Server (IIS) connections,

108-110, 117-131 last connection port for, 125 selecting addresses, 106-107, 153

TcpConnection directive, 145 TcpConnection parameter, 108-110, 117, 122, 125-128 TcpPort directive, 146 TcpPort parameter, 123, 128 text box Web page input type, 121, 130-131, 136 thin clients

configuring Compact JADE on, 41-43 installing, 105-106 installing Compact JADE on, 36-40 operational requirements for Compact JADE, 34-36 operational requirements for JADE, 15-19, 48-49, 76-77 reserving licences for HTML (Web), 31, 163-164 reserving licences for JADE, 31, 163-164 support for HTML (Web), 31, 108-111, 117-150,

163-164 support for JADE, 31, 153, 163-164 Windows Mobile devices running as, 33

--thinclient parameter, 56, 85 thinClient parameter, 151 threads

configuring multiple, 153 timeouts

message reply, 127, 140 TMPDIR environment variable, 62, 90 toolbar

hiding, 162 Trace parameter, 132 TraceFile parameter, 132 tracing

jadehttp library, 132 mod_ jadehttp, 138-139

transfer directory file, 136

transient locks hash size for concurrent, 150

TransientLockHashSize parameter, 150 translation table

overriding UNIX, 67-71, 95-99 UNIX, 68-71, 95-99


Index 189

JADEICG-6.3

transport local intra-machine, 107-108 type of, 107-108, 122-125, 135, 145-146, 153

tuning performance, 107-108 two-level jade.ini file section names, 151, 155 types

HTML documents, 123, 135 Jade61, 123, 135 mapping JADE attributes to SQL, 21 Web service, 123, 135 Web-enabled forms application, 123, 135

U --u parameter, 55, 83 --U parameter, 56, 84 Unicode character version supported by JADE, 18, 51, 79 Unicode data, 111 Unicode files

obtaining version, 165-168 setting version of, 167

UNIX platform configuring JADE, 63, 91, 115 de-installing JADE, 59, 86-87 displaying list packages for a specific version, 59, 87 environment variables, 60-62, 67-71, 88-90, 95-99,

114-116 error-correcting memory, 47, 75 exit values, 170-172 installing JADE, 44-99 JADE portable GUI, 63, 91, 115 JADE server (daemon), 62, 90 locales, 67-71, 95-99 maintaining multiple copies of JADE, 45-46, 73-74 multiple JADE copies, 45-46, 73-74 obtaining Linux core dump, 60, 87 operating system, 169-172 operational requirements, 46, 50-52, 78-80 overview, 44-45, 72-73 registering JADE, 57, 85 repackaging JADE, 60, 88 running a non-GUI client application, 65-67, 93-95 running an application server, 63-64, 91-92 setting up Windows client, 58, 86 shell scripts, 45, 57, 60, 67, 73, 85, 88, 95 specifying language, 67-71, 95-99 starting and stopping, 57, 85 translating messages, 67-71, 95-99 upgrading JADE, 58, 86

--Upgrade parameter, 56, 84 upgrading from an earlier JADE release, 22-23, 26 user applications

accessing, 153 configuring, 28-29

user classes specifying location of Java, 67, 95

user data upgrade, 22-23, 26

user data directory location of, 102-104

user data map files obtaining version of, 165-168 setting version of, 167

user information specification, 24-25 --usercode parameter, 55, 83 UserDataDirectory parameter, 102-104 userExitCode property, 170 UserJVMArgs<n> parameter, 117 UserJVMJars<n> parameter, 115 users

number of peak, 101 utility

batch JADE Database, 167 batch registration, 163-164 JADE Version Information, 165-167 Remote Node Access, 153 version information, 165-168

V --v parameter, 55, 83 values

custom exit, 170 generic exit, 170-172 standard exit, 170

version getting file, 165-168 getting system, 165-168 maintaining patch, 160 obtaining operating system, 165-168 obtaining user data map file, 165-168 setting user data map file, 167 Unicode, 18, 51, 79

--version parameter, 55, 83 virtual Apache directory, 143-144 virtual environment support, 21 virtual IIS directory, 118-132 VirtualDirectory directive, 146 VirtualDirectory parameter, 119, 128-130 Vista

operating system, 102-105 support for Microsoft, 102-106

W --w32thinclient parameter, 57, 85 Web. See Internet Web pages

text box input type, 121, 130-131, 136 Web server

Apache, 19, 50-51, 78-79, 110-111, 132-150 IIS, 19, 51, 79, 110

Web service application type, 123, 135 Web-enabled forms application type, 123, 135 webInputType property, 121, 130-131


Index 190

JADEICG-6.3

windows maintaining default preferences, 161

Windows environment variables, 115-116 exit values, 170-172 hardware requirements, 15-16 installing JADE, 15-25 JADE configuration, 26-29, 106-113, 117-132, 151-154 operating system, 33-36, 102-105, 169-172 registering JADE, 30-31, 163-164 software requirements, 18-20 substituting fonts with Java fonts, 113 Web connections to JADE applications, 110-111

Windows CE Compact JADE configuration, 41-43 configuring Compact JADE under, 41-43 hardware requirements, 34-36 installing Compact JADE under, 36-40 operating system, 33-43 operational requirements, 34-36 operational requirements of Compact JADE running

under, 34-36 overview of Compact JADE running under, 33 software requirements, 34-36

Windows Mobile 6.0 Professional devices, 33-43 Windows Mobile devices

configuring JADE applications on, 33-43

Windows Mobile devices (continued) installing JADE applications on, 36-40 operational requirements for, 34-36 running JADE applications on, 33

Windows Vista operating system, 102-105

wizard C# Exposure, 20 Relational Population Service, 21

work directory location, 102, 105-106 worker Multi-Processing Module (MPM), 111 workstations

client node, 26 headless portable GUI, 117 Intel, 44-99, 115 multiple, 26 Red Hat, 76 server node, 26 SUSE Linux Enterprise Server, 48 Web browser, 108-111, 117-150 Windows, 15-31, 106-113, 117-132, 151-156, 163-164

World Wide Web (WWW). See Internet WWW. See Internet

X xSeries platform. See Intel platform