Pathway,I Ts Web Client Programming Manual

HP NonStop
Pathway/iTS Web Client
Programming Manual

Abstract
This manual describes how to convert SCREEN COBOL requesters to web clients and
explains how to build and deploy those clients. It also provides the information Java
developers and web designers need to modify and enhance the Java and HTML
portions of the converted clients.
Product Version
Pathway/iTS 1.1
Supported Release Version Updates (RVUs)
This publication supports J06.03 and all subsequent J-series RVUs and H06.03 and all
subsequent H-series RVUs, until otherwise indicated by its replacement publications.

Part Number Published
520270-003 May 2008

Document History
Part Number Product Version Published
426746-001 Pathway/iTS 1.0 October 2000
520270-001 Pathway/iTS 1.0 Update June 2001
520270-002 Pathway/iTS 1.1 May 2007
520270-003 Pathway/iTS 1.1 May 2008

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

HP NonStop Pathway/iTS Web
Client Programming Manual

Index Examples Figures Tables

Legal Notices
What’s New in This Manual vii
Manual Information vii
New and Changed Information vii
About This Manual xi
Who Should Read This Manual xi
Related Documentation xi
Notation Conventions xiii

1. Introduction to Pathway/iTS Web Clients
Development Process for Web Clients 1-2
Run-Time Environment for Web Clients 1-3
Java Import Package 1-3
Router Process 1-4
Terminal Control Process (TCP) 1-4
Gateway Threads 1-5
Pathway/iTS 1.1 1-5

2. How to Compile, Build, and Maintain a Pathway/iTS Web
Client
1. Prepare the SCREEN COBOL Object File 2-2
2. Create a Configuration File 2-2
3. Run the Converter 2-3
4. Modify Java or SCREEN COBOL Code as Needed 2-4
5. Run PROFDBM to Set Up the User Profile Database 2-4
6. Build the Converted Client 2-5
Set Up the Build Environment in an OSS Environment 2-5
Set Up the Build Environment in a Windows Environment 2-6
Build (Compile) the Application in an OSS Environment 2-8
Build (Compile) the Application in a Windows Environment 2-9

Hewlett-Packard Company —520270-003
i

Contents 2. How to Compile, Build, and Maintain a
Pathway/iTS Web Client (continued)

2. How to Compile, Build, and Maintain a Pathway/iTS Web
Client (continued)
7. Deploy the Web Client 2-9
Deploy the Web Client on an OSS Environment 2-9
Deploy the Web Client on a Windows Environment 2-11
8. Customize the Screens 2-12
Copy the HTML Files to be Customized 2-12
Modify the HTML Files 2-13
Redeploy Customized HTML Files 2-13
9. Specify the Port Number of the Router Process 2-13
10. Configure Pathway Servers for User Profiles and User Conversion Routines 2-14
11. Tune the Application for Performance by Changing the Session-Length
Parameter 2-14
12. Maintain the Client 2-16
Modify SCREEN COBOL Source Code 2-16
Modify Java Source Code Only 2-17

3. Logon Security and User Profiles
Logon Security 3-1
User Profiles 3-1
Actions of the Web Client 3-2
Contents of the User Profile Database 3-2
User Profile Options in the Control File 3-3
Use the PROFDBM Utility 3-5
Configure the User Profile Server Class 3-6

4. User-Written User Conversion Procedures for Web Clients
Build Your User Conversion Library 4-2
Configure the User Conversion Server Class 4-2

5. SCREEN COBOL-to-Web Conversion Mappings
Components of the Web Client 5-2
Main Java Applet 5-2
Starting Page 5-2
Initial Page 5-2
Control Page 5-3
Java Classes for the Program Units 5-3
User HTML Pages for the Screen Sections 5-3
Conversion Mappings 5-3
Mappings to Java Classes 5-3
HP NonStop Pathway/iTS Web Client Programming Manual—520270-003
ii

Contents 5. SCREEN COBOL-to-Web Conversion Mappings
(continued)

5. SCREEN COBOL-to-Web Conversion Mappings (continued)
Mappings to User HTML Pages 5-7

6. Java Import Package Reference
Host Connectivity Classes 6-2
Class Gateway 6-2
Class ServerReplyCode 6-11
HTML Screen Interaction Classes 6-13
Class ScreenFieldIdentifier 6-13
Class ScreenField 6-13
Class ScreenFieldArray 6-22
Class ScreenFieldGroup 6-30
Class HTMLHandler 6-32
Class FunctionKey 6-43
Data-Type Classes 6-44
Class ScobolType 6-44
Class ScobolGroupType 6-53
Class Pic9 6-60
Class Pic9P 6-72
Class Pic9V 6-84
Class PicN 6-97
Class PicX 6-103
Transform Class 6-113
Class Transform 6-113
ProgramUnit Class 6-117
Class ProgramUnit 6-117
Special-Register Classes 6-120
Class ScobolLib 6-120
Class Cursor 6-123
Exception Classes 6-126
Class ExitProgramException 6-126
Class ScobolException 6-126
Class ScobolSendException 6-127
Class ScobolTxnException 6-128
Class StopRunException 6-129
Class TransformException 6-129
User Conversion Classes 6-131
Class UserConversion 6-131
Class ScLibUserConversion 6-132

iii

Contents 7. Introduction to Pathway/iTS 1.1

7. Introduction to Pathway/iTS 1.1
Architecture of Pathway/iTS 1.1 7-2
SCOBOL Verbs and Special Register 7-3
Web Clients in Pathway/iTS 1.1 7-4
Difference Between Pathway/iTS 1.0 and Pathway/iTS 1.1 7-4
Server Process Opener and Timeouts on Send to Servers 7-4
TCP Checkpoint Strategy 7-4
Special Registers 7-5
FREEZE SERVER Command Changes 7-6
Statistics Collected by Pathway/iTS 1.1 7-7
Fault Tolerance in Pathway/iTS 1.1 7-7
Error Handling in Pathway/iTS 1.1 7-8

A. Client Error Messages
General Information A-1
Message Descriptions A-1

B. SCREEN COBOL Features Not Supported for Web
Conversion
Index
Examples
Example 2-1. Sample Configuration File for mycfg 2-3
Example 2-2. Sample CONTROL.html File 2-16
Example 5-1. SCREEN COBOL Working-Storage Code Fragment 5-4
Example 5-2. Java Code Resulting From Conversion of Working-Storage
Code 5-4
Example 5-3. SCREEN COBOL Paragraph 5-5
Example 5-4. Java Code Resulting From Conversion of SCREEN COBOL
Paragraph 5-5
Example 5-5. SCREEN COBOL Input-Output Element 5-6
Example 5-6. Java Code Resulting From Conversion of SCREEN COBOL Input-
Output Element 5-6
Example 5-7. SCREEN COBOL Screen Section 5-8
Example 5-8. HTML Code Resulting From Conversion of SCREEN COBOL Screen
Section 5-8
Example 7-1. Sample TCP Statistics for QUEUE INFO. 7-7

Figures
Figure 1-1. Development of a Pathway/iTS Web Client 1-2

iv

Contents Figures (continued)

Figures (continued)
Figure 1-2. Run-Time Environment for a Pathway/iTS Web Client 1-3
Figure 7-1. Architecture of Pathway/iTS 1.1 7-2

Tables
Table B-1. Web Conversion Support Limitations B-2

v

Contents

vi

What’s New in This Manual
Manual Information
HP NonStop Pathway/iTS Web Client Programming Manual

Abstract
Product Version
Pathway/iTS 1.1
Supported Release Version Updates (RVUs)
This publication supports J06.03 and all subsequent J-series RVUs and H06.03 and all
subsequent H-series RVUs, until otherwise indicated by its replacement publications.

Part Number Published
520270-003 May 2008

Document History
Part Number Product Version Published
426746-001 Pathway/iTS 1.0 October 2000
520270-001 Pathway/iTS 1.0 Update June 2001
520270-002 Pathway/iTS 1.1 May 2007
520270-003 Pathway/iTS 1.1 May 2008

New and Changed Information
Changes in the H06.14/J06.03 manual:
• Supported release statements have been updated to include J-series RVUs.
• Added an overview of Pathway/iTS 1.1 on page 1-5.
• Added four delegation methods to the list of Class Gateway on page 6-3 and
added their descriptions on page 6-6.
• Added a data member to Class ScobolLib on page 6-121.
• Added Section 7, Introduction to Pathway/iTS 1.1.

vii

What’s New in This Manual Product Changes in G06.27

• Added these error messages:
• 3115 on page A-8
• 3231 on page A-11
• 3246 on page A-11
• 3247 on page A-12
• 3248 on page A-12
• 3249 on page A-13
• 3250 on page A-13
• 3251 on page A-14
• 3252 on page A-14
• 3253 on page A-15
• 3308 on page A-18
• 3312 on page A-19
• 3313 on page A-19

Product Changes in G06.27
The Pathway/iTS product, formerly called Pathway/TS, was renamed to conform to
current HP product naming standards and to reflect the internet (web client)
capabilities of the product. After the first reference to the product name in each
manual section, subsequent references use the shortened form of the name,
Pathway/iTS.
• Section 2: How to Compile, Build, and Maintain a Pathway/iTS Web Client
• Added a Deployment Environment section toSample Configuration File for
mycfg on page 2-3.
• Reorganized and added detailed information and examples to
6. Build the Converted Client on page 2-5
7. Deploy the Web Client on page 2-9
8. Customize the Screens on page 2-12.
• Changed the step for setting up the user profile database from optional to
required. See 5. Run PROFDBM to Set Up the User Profile Database on
page 2-4.
• Section 4: User-Written User Conversion Procedures for Web Clients
• Corrected the nld utility command description in Build Your User Conversion
Library on page 4-2.

viii

What’s New in This Manual Corrections and Enhancements to the Manual

• Section 5: SCREEN COBOL-to-Web Conversion Mappings
• Added a description of the Initial page in Initial Page on page 5-2.
• Modified the name of the starting page file from name_PAGE1.html to
name_START.html in Starting Page on page 5-2.
• Corrected the code in
Example 5-2 on page 5-4
• Updated information in Mappings to User HTML Pages on page 5-7.
• Section 6: Java Import Package Reference
• Updated the Method send on page 6-10.
• Added the pow method to the ScobolLib class. See Method pow on
page 6-122
• Modified the displayOverlay method in the HTMLHandler class. See Method
displayOverlay on page 6-37.
• Added the displayOverlaySpaces method to the HTMLHandler class. See
Method displayOverlaySpaces on page 6-38.
• Added the addScobolData method to the ScobolGroupType calss. See Method
addScobolData on page 6-54.
• Removed the Class Overlay Manager, Method addOverlay (single overlay
screen), and Method addOverlay (multiple overlay screens).
• General, throughout the manual
• Removed references to the Unix operating system.
• Corrected several examples

Corrections and Enhancements to the Manual
These enhancements have been made to the material in this manual:
• References to Compaq trademarks have been updated.
• Miscellaneous terminology changes and editorial corrections have been made.

ix

What’s New in This Manual Corrections and Enhancements to the Manual

x

About This Manual

Who Should Read This Manual
This manual is intended for these types of readers:
• Application developers who are converting SCREEN COBOL requesters to web
clients
• Java developers who are modifying and enhancing the Java portion of converted
web clients
• Web designers who are modifying the HTML output of converted web clients
The primary focus of this manual is on describing the unmodified converted clients and
how to use them, rather than on how to enhance the clients after conversion.
However, this manual provides information about the structure and content of the
converted Java code and HTML pages so that developers and web designers can
modify them if desired.

Related Documentation
The Pathway environment is supported by three products:
HP NonStop™ Pathway/iTS
HP NonStop™ Transaction Services/MP (NonStop™ TS/MP)
HP NonStop™ Pathway/XM

xi

About This Manual Related Documentation

These manuals may be useful:
Pathway/iTS SCUP Describes the utility program that enables SCREEN
Reference Manual COBOL application programmers to control and
manipulate SCREEN COBOL object files. This
manual includes detailed syntax for the CONVERT
command, used to convert SCREEN COBOL object
files to web clients.
Pathway/iTS SCREEN Describes the SCREEN COBOL programming
COBOL Reference language, which is used for writing programs that
Manual define and control terminal displays or intelligent
devices for online transaction processing
applications running in a PATHMON environment.
Pathway/iTS TCP and A guide for programmers who are writing SCREEN
Terminal Programming COBOL requesters to be used in Pathway
Guide applications.
Pathway/iTS System Describes the interactive management interface to
Management Manual the Pathway/iTS product and describes how to
configure and manage Pathway/iTS objects.
NonStop™ TS/MP Describes the interactive management interface to
System Management the NonStop TS/MP product and describes how to
Manual configure and manage NonStop TS/MP objects. This
interface is used together with the Pathway/iTS
management interface to configure and manage a
Pathway environment.
Pathway/XM System Describes the higher-level management interface
Management Manual provided by the Pathway/XM product, which you
might want to use to configure and manage your
Pathway environment rather than use the
management interfaces provided by Pathway/iTS
and NonStop TS/MP.
Pathway/iTS Describes the management programming interface
Management for Pathway/iTS objects in the PATHMON
Programming Manual environment.
Pathway Products Defines technical terms used in this manual and in
Glossary other manuals for the Pathway products:
Pathway/iTS, NonStop TS/MP, and Pathway/XM.
Operator Messages Describes all messages that are distributed by the
Manual Event Management Service (EMS), including those
generated by NonStop TS/MP and Pathway/iTS
processes.

xii

About This Manual Notation Conventions

Notation Conventions
Hypertext Links
Blue underline is used to indicate a hypertext link within text. By clicking a passage of
text with a blue underline, you are taken to the location described. For example:
This requirement is described under Backup DAM Volumes and Physical Disk
Drives on page 3-2.

General Syntax Notation
The following list summarizes the notation conventions for syntax presentation in this
manual.

UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter
these items exactly as shown. Items not enclosed in brackets are required. For
example:
MAXATTACH

lowercase italic letters. Lowercase italic letters indicate variable items that you supply.
Items not enclosed in brackets are required. For example:
file-name
[ ] Brackets. Brackets enclose optional syntax items. For example:
TERM [system-name.]$terminal-name
INT[ERRUPTS]
A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list may be arranged either vertically, with aligned brackets on
each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:
FC [ num ]
[ -num]
[ text]
K [ X | D ] address-1

{ } Braces. A group of items enclosed in braces is a list from which you are required to
choose one item. The items in the list may be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and
separated by vertical lines. For example:
LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }
ALLOWSU { ON | OFF }

xiii

About This Manual General Syntax Notation

| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
INSPECT { OFF | ON | SAVEABEND }

… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you
can repeat the enclosed sequence of syntax items any number of times. For example:
M address-1 [ , new-value ]...
[ - ] {0|1|2|3|4|5|6|7|8|9}...
An ellipsis immediately following a single syntax item indicates that you can repeat that
syntax item any number of times. For example:
"s-char..."

Punctuation. Parentheses, commas, semicolons, and other symbols not previously
described must be entered as shown. For example:
error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must enter as shown. For example:
"[" repetition-constant-list "]"

Item Spacing. Spaces shown between items are required unless one of the items is a
punctuation symbol such as a parenthesis or a comma. For example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In this example,
there are no spaces permitted between the period and any other items:
$process-name.#su-name

Line Spacing. If the syntax of a command is too long to fit on a single line, each
continuation line is indented three spaces and is separated from the preceding line by
a blank line. This spacing distinguishes items in a continuation line from items in a
vertical list of selections. For example:
ALTER [ / OUT file-spec / ] CONTROLLER

[ , attribute-spec ]...

xiv

About This Manual Notation for Messages

Notation for Messages
The following list summarizes the notation conventions for the presentation of
displayed messages in this manual.

Bold Text. Bold text in an example indicates user input typed at the terminal. For example:
ENTER RUN CODE
?123
CODE RECEIVED: 123.00
The user must press the Return key after typing the input.

Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or
returned exactly as shown. For example:
Backup Up.

lowercase italic letters. Lowercase italic letters indicate variable items whose values are
displayed or returned. For example:
p-register
process-name
[ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For
example:
Event number = number [ Subject = first-subject-value ]
A group of items enclosed in brackets is a list of all possible items that can be
displayed, of which one or none might actually be displayed. The items in the list might
be arranged either vertically, with aligned brackets on each side of the list, or
horizontally, enclosed in a pair of brackets and separated by vertical lines. For
example:
proc-name trapped [ in SQL | in SQL file system ]
{ } Braces. A group of items enclosed in braces is a list of all possible items that can be
displayed, of which one is actually displayed. The items in the list might be arranged
either vertically, with aligned braces on each side of the list, or horizontally, enclosed in
a pair of braces and separated by vertical lines. For example:
obj-type obj-name state changed to state, caused by
{ Object | Operator | Service }
process-name State changed from old-objstate to objstate
{ Operator Request. }
{ Unknown. }

| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
Transfer status: { OK | Failed }

xv

About This Manual Change Bar Notation

% Percent Sign. A percent sign precedes a number that is not in decimal notation. The
%þnotation precedes an octal number. The %Bþnotation precedes a binary number.
The %Hþnotation precedes a hexadecimal number. For example:
%005400
P=%p-register E=%e-register

Change Bar Notation
Change bars are used to indicate substantive differences between this manual and its
preceding version. Change bars are vertical rules placed in the right margin of
changed portions of text, figures, tables, examples, and so on. Change bars highlight
new or revised information. For example:
The message types specified in the REPORT clause are different in the COBOL85
environment and the Common Run-Time Environment (CRE).
The CRE has many new message types and some new message type codes for
old message types. In the CRE, the message type SYSTEM includes all
messages except LOGICAL-CLOSE and LOGICAL-OPEN.

xvi

1
Introduction to Pathway/iTS Web
Clients
The web client feature of HP NonStop Pathway/iTS lets you convert a SCREEN
COBOL application (a group of related compiled program units within an object library)
to a web client and then build and deploy the resulting client in a Pathway environment.
The converted web client consists of a combination of Java code and HTML pages.
These can be deployed on any web server hosted on the HP NonStop Kernel
operating system. The Java client, working with a standard web browser,
communicates with existing Pathway servers by means of router processes, a run-time
web gateway, and the terminal control process (TCP).
Any valid block-mode requester programs for terminal types T16-6520, T16-6530,
T16-6540, and IBM-3270 can be converted. (Intelligent device support (IDS)
requesters cannot be converted.) The specified program units are converted in such a
way that most of the functionality of the original SCREEN COBOL program remains
unchanged.
The conversion feature allows you to maintain the same SCREEN COBOL source
code for both terminals and web clients. Thus you can migrate terminals to the web
gradually. Alternatively, you can fully migrate your terminal requesters to the web and
then use standard web publishing tools to modify and enhance the Java code and the
HTML presentation.
You can configure and manage Pathway applications containing converted web clients
by using either HP NonStop Pathway/XM or PATHCOM. However, HP recommends
using Pathway/XM for this purpose; Pathway/XM provides fuller and easier-to-use
management capabilities for web client configurations, including configuration and
management of router processes. Information about configuring and managing
Pathway/iTS web clients through Pathway/XM is provided in the Pathway/XM System
Management Manual. Information about configuring and managing Pathway/iTS web
clients through PATHCOM is given in the Pathway/iTS System Management Manual.

1 -1

Introduction to Pathway/iTS Web Clients Development Process for Web Clients

Development Process for Web Clients
The process of creating a Pathway/iTS web client is shown in Figure 1-1.
To convert a SCREEN COBOL object program to a web client, you invoke the
Pathway/iTS converter utility through the CONVERT command in the SCREEN
COBOL Utility Program (SCUP). The converter scans the compiled SCREEN COBOL
object code and generates an equivalent web client.

Figure 1-1. Development of a Pathway/iTS Web Client

TM
Compaq NonStop System
SCREEN COBOL SCREEN COBOL
Source Compiler

SCREEN Symbol
COBOL Directory
Table
Object Code

SCUP
Utility

Standard Web
Java HTML optional Publishing
Source Pages with Tools
Code JavaScript

Web Server

VST001.vsd

The web client consists of a combination of Java code and HTML pages. Requester-
based business logic is converted to Java classes. Screen components are converted
to HTML pages with embedded JavaScript code to link them to the Java business
logic.

1 -2

Introduction to Pathway/iTS Web Clients Run-Time Environment for Web Clients

Optionally, before deployment you can customize the converted HTML pages by using
standard web publishing tools.

Run-Time Environment for Web Clients
The run-time environment for a Pathway/iTS web client is shown in Figure 1-2.

Figure 1-2. Run-Time Environment for a Pathway/iTS Web Client

Java Import Package Residing on
Browser-Based Web Client

Internet

Proxy
Proxy

Compaq NonStopTM System

Router
Gateway Threads

TCP

Pathway
Server Class

VST002.vsd

Java Import Package
Pathway/iTS provides a Java import package used by the converted web clients. This
package consists of classes that enable Java-based clients to interact with Pathway
applications. The Java import package includes public classes in these categories:
• Host connectivity (gateway) classes, which define the connectivity protocol with the
host HP NonStop system and also delegate certain host processing on behalf of
the clients.

1 -3

Introduction to Pathway/iTS Web Clients Router Process

• HTML screen interaction classes, which define the attributes and structures
associated with SCREEN COBOL screen fields and the SCREEN COBOL
statements associated with displaying and accepting screens.
• Data-type classes, which define the storage and casting rules associated with
SCREEN COBOL alphanumeric (PIC X), numeric integer (PIC 9), and numeric
non-integer (PIC 9P and PIC 9V) data types.
• The Transform class, which provides methods to implement the SCREEN COBOL
TRANSFORM statement
• The Program Unit class, which provides methods for setting attributes for a
program unit—for example, the currency symbol and the decimal-point character
• Special-register classes, which define the Java equivalents of the SCREEN
COBOL special registers
• Exception classes, which provide handling for SCREEN COBOL exceptions
• User conversion classes, which define the Java equivalent of the standard user
conversion routines in PATHTCPL
The classes and methods in the Java import package are described in detail in
Section 6, Java Import Package Reference.

Note. Although the Pathway/iTS router processes, described in the following subsection,
support both HTTP and raw sockets protocols, the Java import package requires the use of the
HTTP protocol.

Router Process
The Java client, working with a standard web browser, communicates with existing
Pathway servers by sending connection requests to a Pathway/iTS router process
residing on a NonStop system. The router processes listen and distribute connection
requests for servicing. Each router process is configured with a TCP/IP port used to
associate an application with connection requests.
The router processes support converted web clients that use the HTTP or the raw
sockets protocol and user-written intelligent device support (IDS) requesters that use
the raw sockets protocol. The router processes distribute connection requests from
web clients or intelligent devices to started TERM objects within the TCPs in such a
way that the connection load is optimally balanced among all the TCPs in the Pathway
environment. When all the TERM objects in all the configured TCPs are in use, the
router queues new connection requests until a TERM object is available. The router
also queues the TERM objects that are ready for a connection until a connection
request arrives.

Terminal Control Process (TCP)
In support of web clients, the TCPs perform link management and line handling, as
they do for SCREEN COBOL terminal requesters. Within a TCP, each TERM object

1 -4

Introduction to Pathway/iTS Web Clients Gateway Threads

that handles a web client is configured with its FILE attribute pointing to a router
process. Each such TERM object sends a message to the router process indicating
that it is available to service a connection. When a client requests a connection, the
request is sent to the router and the router passes the client information to the TCP.
The TCP then establishes a socket connection to the client, verifies access rights, and
passes control to the gateway thread.
The combination of the router and TCP processes provides general load balancing for
gateway threads. TERM objects within multiple TCP processes are associated with a
given router process. This enables the router process to identify the gateway thread
that will process the connection request. Multiple routers can thus be used to support
more than one gateway application.

Gateway Threads
The run-time web gateway is implemented as a Pathway/iTS intelligent device support
(IDS) requester running on the NonStop system under control of the TCP. This
requester program is provided as part of Pathway/iTS. It handles requests from the
browser-based web client, treating the client as an intelligent device.
The gateway validates user access and performs certain functions on behalf of the
client including beginning and ending transactions, user conversion routines, and send
operations to Pathway server processes.
Client communications with the Pathway/iTS web gateway can use the standard HTTP
protocol to allow optional use of Internet proxy servers. Alternatively, for intranet
applications, a client can use the raw sockets protocol. The protocol is specified by the
system manager when starting the router process.

Pathway/iTS 1.1
PATHTCP4, the TCP component uses SERVERCLASS_SEND_* APIs to process the
existing SEND verb for SCOBOL requesters and converted Java clients. The features
are:
• PATHTCP4 does not communicate with either owner or external PATHMON
process for link management activities. Instead of performing Guardian
WRITEREAD on Pathway server processes to communicate with them,
PATHTCP4 becomes a Pathsend requester and uses Pathsend APIs to
communicate with Pathway servers. Therefore, any existing Pathway/iTS 1.0
application can be used with Pathway/iTS 1.1 with minimal changes to the
applications.
• PATHTCP4 provides four SCOBOL verbs, DIALOG-ABORT, DIALOG-BEGIN,
DIALOG-END, and DIALOG-SEND to enable SCOBOL requesters and converted
Java clients to establish context-sensitive communication with Pathway servers.
The context-sensitive communication allows SCOBOL requesters and converted
Java clients to send more than 32,000 bytes of data to the same Pathway server
process.

1 -5

Introduction to Pathway/iTS Web Clients Pathway/iTS 1.1

The SCUP and Web client components of Pathway/iTS 1.1 product are changed to
support these functionalities. For compatibility reasons, Pathway/iTS 1.1 package
includes PATHTCP3, the legacy TCP component.
For more information, see Section 7, Introduction to Pathway/iTS 1.1.

1 -6

2
How to Compile, Build, and Maintain
a Pathway/iTS Web Client
This section describes the steps you need to take to convert a SCREEN COBOL
program into a Pathway/iTS web client and to compile, build, deploy, and maintain the
resulting web client. The steps are:
1. Prepare the SCREEN COBOL Object File
2. Create a Configuration File
3. Run the Converter
4. Modify Java or SCREEN COBOL Code as Needed
5. Run PROFDBM to Set Up the User Profile Database
6. Build the Converted Client
7. Deploy the Web Client
8. Customize the Screens
9. Specify the Port Number of the Router Process
10. Configure Pathway Servers for User Profiles and User Conversion Routines
11. Tune the Application for Performance by Changing the Session-Length
Parameter
12. Maintain the Client
For each step, a generic description of the step is followed by an example that refers to
a sample SCREEN COBOL application. The sample application used in this section
consists of four program units: LOG1, LOG2, INV1, and INV2. Program units LOG1
and LOG2 are located in the program file LGINCOD and program units INV1 and INV2
are located in the program file INVYCOD. Program units LOG1 and LOG2 perform the
login and user authentication functions for the application. If the login is successful,
the program unit INV1 is called, which in turn calls INV2 to begin process user
requests. The initial program unit for this sample application (as specified in the
INITPROG parameter) is LOG1.

2 -1

How to Compile, Build, and Maintain a Pathway/iTS 1. Prepare the SCREEN COBOL Object File
Web Client

1. Prepare the SCREEN COBOL Object File
Before you run the converter, organize the SCREEN COBOL object (POBJ) file so that
repeated conversions can be done easily.
First, copy the SCREEN COBOL object file to be converted to the desired volume and
subvolume.
If the SCREEN COBOL object program has its symbols stripped, rebuild the object file
with symbols. The converter uses the symbols when creating equivalent Java variable
names. The equivalent symbolic names the converter creates when symbols are
available help make the converted code readable and maintainable. If the converter
cannot locate symbols, it generates an error and does not convert that program unit.
For each application, verify that all the program units that make up this application are
in a single SCREEN COBOL object file, including the program that is specified in the
INITPROG parameter. Doing this enables you to convert the entire application in a
single invocation of the converter. In addition, this organization of the SCREEN
COBOL object code makes it easier to regenerate the Java and HTML files when you
do future enhancements in SCREEN COBOL.
In the sample application, you would move the program units LOG1, LOG2, INV1, and
INV2 into a single SCREEN COBOL object file.

2. Create a Configuration File
Create a configuration file to contain the default values the converter will use. By
creating a configuration file, you can avoid having to repeatedly specify frequently used
values. In addition, because the default compile (build) environment is the HP
NonStop™ Kernel operating system OSS, you must specify a configuration file if your
compile environment is the Microsoft® Windows NT® operating system.
Example 2-1 shows a sample configuration file called mycfg.

2 -2

How to Compile, Build, and Maintain a Pathway/iTS 3. Run the Converter
Web Client

Example 2-1. Sample Configuration File for mycfg
[Screen Section]
Background = mylogo.gif;
Foreground = Black;
Font Type = Courier;
Font Size = 12;

[Convert Environment]
Java Location = system.$java.appa;
HTML Location = system.$html.appa;

[Compile Environment]
OS = NSK;

[Deployment Environment]
Web Root = /usr/webserver/root;

[Limits Section]

To provide a common look and feel for all the web pages, the example provides default
values for background color, foreground color, font type, and font size. For the
background parameter, you could choose a color or a .gif file that contains the
company logo.
Specifying default locations for Java and HTML files in the Convert Environment
section allows you to save the converted files in a well-known location.
Details about the converter configuration file are given in the description of the
CONVERT command in the Pathway/iTS SCUP Reference Manual.

3. Run the Converter
Next, convert the SCREEN COBOL files to a web client. You invoke the converter by
bringing up the SCREEN COBOL Utility Program (SCUP) from a HP Tandem
Advanced Command Language (TACL) prompt:
TACL> SCUP
SCUP displays its starting banner followed by a question-mark prompt. Optionally, you
can redirect the output of the SCUP program to a file by using the OUT command or by
specifying the OUT option while invoking the SCUP program. If OUT is specified,
messages from the converter will be redirected to that file.
At the question-mark prompt, you enter the SCUP CONVERT command, which is
described in detail in the Pathway/iTS SCUP Reference Manual. For the sample
application, you could enter this CONVERT command:
?CONVERT invy (*(1)), INITPROG LOG1, CONFIGFILE mycfg, &
APPNAME inventory

2 -3

How to Compile, Build, and Maintain a Pathway/iTS 4. Modify Java or SCREEN COBOL Code as
Web Client Needed

This command converts version 1 of all the program units in the Inventory application
(stored in invy* object files) and generates the equivalent Java source and HTML files.
The converted files are created in the subvolumes specified in the configuration file
mycfg. The look and feel of the generated HTML files are based on the values
specified in the Screen Section of the configuration file.
Because all the program units are already in the INVYCOD program file, the converter
does not generate a warning message. If the converter encounters any error or
warning conditions, messages are displayed on the SCUP terminal (or if the OUT
command or option was specified, written to the specified OUT file).
For the user's convenience, a conversion summary is displayed after each individual
Program Unit is converted and at the end of CONVERT command.
Detailed syntax for the CONVERT command, the CONVERT summary, and message
text, cause, effect, and recovery information for all converter error messages are
provided in the Pathway/iTS SCUP Reference Manual.

4. Modify Java or SCREEN COBOL Code as
Needed
When you run the converter, it returns error or warning messages if it finds any
problems or any unsupported SCREEN COBOL statements. In such cases, comments
or error messages may also appear in the resulting Java code. If unsupported
statement error messages are returned, you must do one of these:
• Analyze the impact of the unsupported statement and replace it with appropriate
Java code.
• Modify the SCREEN COBOL source code by removing the unsupported SCOBOL
statement and then run the converter again.
For detailed information about the error and warning messages that can be returned by
the converter, see the Pathway/iTS SCUP Reference Manual.
Also, if you plan to use the user profile feature described in Section 3, Logon Security
and User Profiles, you must add Java code to the converted code to check the user
profile field in the logon screen and then use the information in the USERPROF user
profile data base to take appropriate action in accordance with the needs of your
application.

5. Run PROFDBM to Set Up the User Profile
Database
If you are using the user profile feature for web clients, you must set up the user profile
database using the user profile database manager utility, PROFDBM. For detailed
instructions, see Contents of the User Profile Database on page 3-2 and Use the
PROFDBM Utility on page 3-5.

2 -4

How to Compile, Build, and Maintain a Pathway/iTS 6. Build the Converted Client
Web Client

6. Build the Converted Client
You can build (compile) the converted client either on the NonStop system under the
Open System Services (OSS) environment of the NonStop Kernel operating system or
on another machine running the Windows NT operating system. Doing this involves
three steps:
1. Set up the build environment
2. Transfer files to the build environment (if the build environment is Windows NT)
3. Build (compile) the application

Set Up the Build Environment in an OSS Environment
Pathway/iTS provides a TACL MACRO utility named JMAKENV, which is used to set
up the build environment for the converted web client.
This utility uses the MAP file that is created at the time of conversion to generate the
build environment. The MAP file is created at the same location
($volume.subvolume) from which the CONVERT command was run. The MAP file
name is composed of the first four or five SCOBOL object file characters plus the
characters MAP. For example, if the SCOBOL objects are named MYAPPCOD,
MYAPPDIR, and MYAPPSYM, then the MAP file name is MYAPPMAP.
If the build environment is on a NonStop system under the OSS environment,
JMAKENV creates the application home directory under OSS, copies the converted
files to this directory and creates a make file for building and deploying the application.
You must set the CLASSPATH variable to point to the itsjlib.jar file (the Java import
package) and to the current directory.
export CLASSPATH=/usr/tandem/Pathway-iTS/itsjlib.jar:$CLASSPATH
The itsjlib.jar file must be available on the local machine. If it is not available, copy the
file from the installation CD.
Set other environment variables for Java compilation: for example:
• Add /usr/tandem/java/bin to $PATH
• Add /usr/tandem/java/lib/classes.zip to $CLASSPATH
• Add /usr/tandem/java/lib/tandemvm.zip to $CLASSPATH
From the TACL prompt on a NonStop system, run JMAKENV as:

RUN JMAKENV file-name application-home makefile-name

file-name
is the name of the SCREEN COBOL object-file (the POBJ file).

2 -5

How to Compile, Build, and Maintain a Pathway/iTS Set Up the Build Environment in a Windows
Web Client Environment

application-home
is the full path name of the OSS directory from which the application will be run.

makefile-name
is the name of the make file to be created that is used when building and running
the application int he OSS environment.

JMAKENV does these:
• Creates a directory named application-home/build.
• Creates a directory named application-home/bin where the built objects will
be stored.
• Copies all the appropriate files from the Java and HTML location (specified at the
time of the conversion) to the application-home/build directory. The files are
copied with the appropriate .java and .html extensions.
• Creates a make file for building the application. The name of the make file is
specified in the JMAKENV command and is copied to the application-
home/build directory as make-file.mk.
• Sets up the environment variables used by the make file.

Note. The user running JMAKENV must have permission to create and copy files to the
application-home directory in the OSS environment.

For example, you would run the JMAKENV file for the sample application as:
TACL> JMAKENV invy /usr/test/inventory invymk

JMAKENV in the sample application does these:
• Creates the directory /usr/test/inventory/build.
• Creates the directory /usr/test/inventory/bin where the built objects will be
stored.
• Copies all the necessary files from the specified Java and HTML location (in this
example, the volumes default to the same volume and subvolume as mycfg) to
the NonStop Kernel OSS directory /usr/test/inventory/build.
• Creates a make file named invymk for building the application.
• Sets up the environment variables used by invymk.
• Copies invymk to the directory /usr/test/inventory/build as invymk.mk.

Set Up the Build Environment in a Windows Environment
Pathway/iTS provides a TACL MACRO utility named JMAKENV, which is used to set
up the build environment for the converted web client.
2 -6

How to Compile, Build, and Maintain a Pathway/iTS Set Up the Build Environment in a Windows

This utility uses the MAP file that is created at the time of conversion to generate the
build environment. The MAP file is created at the same location
($volume.subvolume) from which the CONVERT command was run. The MAP file
name is composed of the first four or five SCOBOL object file characters plus the
characters MAP. For example, if the SCOBOL objects are named MYAPPCOD,
MYAPPDIR, and MYAPPSYM, then the MAP file name is MYAPPMAP.
If the build environment is on a Windows NT server, JMAKENV creates two batch files
to move the converted files to the desired environment and copy the Java class and
HTML files to a directory under OSS for deployment.
From the TACL prompt on a NonStop, run JMAKENV as:

RUN JMAKENV file-name NT

file-name
is the name of the SCREEN COBOL object-file.

JMAKENV does this when run with the NT option:
Creates two batch files (JGETFILE and JPUTFILE) in the same location from which
JMAKENV was run. JGETFILE includes FTP commands to move files from the OSS
environment to the Windows NT platform. JPUTFILE includes FTP commands to
move files from a Windows NT environment to the OSS deployment directory.
For example, you would run the JMAKENV file for the sample application as:
TACL> JMAKENV invy NT

JMAKENV in the sample application does these:
Creates the JGETFILE and JPUTFILE files in the same location from which JMAKENV
was run.
To move the generated Java and HTML files from a NonStop to a Windows
environment, run JGETFILE from the Windows environment. To move the JGETFILE
file onto a Windows environment, use these steps:
1. At the Windows DOS prompt, execute the command
ftp host-address
where host-address is the IP address of the NonStop where the Java and
HTML files are generated.
2. At the FTP prompt:
• Logon to the system.
• Set the remote directory to the location where JGETFILE is located.
• Set the local directory to location where JGETFILE is to be transferred.

2 -7

How to Compile, Build, and Maintain a Pathway/iTS Build (Compile) the Application in an OSS

• Set the transfer mode to ASCII .
3. Transfer JGETFILE then exit the FTP session using the commands
ftp> ASCII
ftp> get JGETFILE JGETFILE.BAT
ftp> bye
4. When JGETFILE.BAT is copied to the Windows NT environment, copy the
generated Java and HTML files using the command
JGETFILE host-name user-ID password

host-name
is the IP address or name of the NonStop containing the generated Java and
HTML files.

user-ID
is a valid userid on the NonStop server. The userid must have the authority to
read Java and HTML files.

password
is the password for the userid.
This command copies the Java and HTML files to the local directory from where
this batch file was run and automatically assigns the appropriate names to the files.
After all the files have been transferred, build the application.

Build (Compile) the Application in an OSS Environment
The JMAKENV utility you run to set up the build environment generates the make file
that you use to build the converted application code.
To build the converted application, you invoke the make file with this command:
make -f makefile-name all
To clean up the build environment (that is, to delete any previously built components),
you invoke the make file with this command:
make -f makefile-name clean
For example, you could build the sample application by running the make file from the
OSS environment by using a command sequence such as:
TACL> OSS
% cd /usr/test/inventory
% make -f invymk.mk all
This is an example of a make file generated by JMAKENV:
BUILDHOME = $(APPHOME)build
CLASSPATH = $(APPHOME);$(CLASSPATH)

2 -8

How to Compile, Build, and Maintain a Pathway/iTS Build (Compile) the Application in a Windows

OUTDIR = $(APPHOME)bin
WEBROOT = /usr/tandem/webserver/root
JAVAC = Javac -d $(OUTDIR)

.SUFFIXES: .java.class
PROGRAM_FILES = abc.java
xyz.java
main.java
HTML_FILES = start.html
Ctrl.html
GIF_FILES = background.gif

all: $(PROGRAM_FILES)

clean: del /f/q $(BUILDHOME)*.class

.java.class: $(JAVAC) -classpath $(CLASSPATH) $?
publish: all html gif

Build (Compile) the Application in a Windows Environment
Once the Java files are transferred to a Windows environment, you can use the Java
compiler available on the machine to compile the Java source.
A typical Java compilation on a Windows environment is as:
DOS> javac *.java 2> error.txt
This compiles all Java files in the current directory and creates one or more class files.
Compilation errors are stored in the error.txt file.

7. Deploy the Web Client
You are now ready to deploy and test the converted application on the web server.
Two parameters are needed for deployment:
• The location (under the specified web root) where the files are to be published
• The TCP/IP port number of the router process

Deploy the Web Client on an OSS Environment

Transfer the application files to the web server
If you built the client on a Windows platform, you must first transfer the application files
to the web server on the NonStop and then deploy the client. If you built the client on a
NonStop, you can skip the file transfer step and deploy the client immediately.
Use the make file to deploy it on the web server by issuing this command from the
OSS prompt:
make -f makefile-name DEPLOY = path-name publish

2 -9

How to Compile, Build, and Maintain a Pathway/iTS Deploy the Web Client on an OSS Environment
Web Client

makefile-name
is the name of the make file generated by JMAKENV

path-name
is the relative pathname (under web-root) from which the web pages are served.
To deploy the sample application, execute the make file with this command:
make -f invymk.mk DEPLOY=testapp publish
Executing this make file does these:
• Copies all the HTML files from the /usr/test/inventory/bin directory to the
usr/webserver/root/testapp directory, where /usr/webserver/root is
obtained from the WEBROOT variable in the make file .
• Copies all the compiled Java files from the /usr/test/inventory/bin
directory to the /usr/webserver/root/testapp directory, where
/usr/webserver/root is obtained from the WEBROOT variable in the make
file.

Move installation files to the web server
Before running the application, you must move these files to the application directory
on the web server (these files were created when Pathway/iTS was installed):
ITSJLIB.jar, BPathwayiTS.js, OVPathwayiTS.js, and blank.html.
Copy these files to the application directory in the root using these commands:
cp /usr/tandem/Pathway-iTS/itsjlib.jar
/usr/tandem/webserver/root/application-dir/itsjlib.jar
cp /usr/tandem/Pathway-iTS/BPathwayiTS.js
/usr/tandem/webserver/root/application-dir/BPathwayiTS.js
cp /usr/tandem/Pathway-iTS/OVPathwayiTS.js
/usr/tandem/webserver/root/application-dir/OVPathwayiTS.js
cp /usr/tandem/Pathway-iTS/blank.html
/usr/tandem/webserver/root/application-dir/blank.html
In addition, HP recommends you also move the file end.html to the application
directory on the server. This file is displayed when the application terminates and can
be modified. Copy the file using this command:
cp /usr/tandem/Pathway-iTS/end.html
/usr/tandem/webserver/root/application-dir/end.html

Test the converted application
If the URL for the default page on the web server is http://intraweb.mycompany.com,
you can now test the converted application by using this URL:
http://intraweb.mycompany.com/testapp/INVENTORY_START.html

2- 10

How to Compile, Build, and Maintain a Pathway/iTS Deploy the Web Client on a Windows Environment
Web Client

Additional options available in the make file are as:
• Publish only the HTML files from /usr/test/inventory/build
-f invymk.mk DEPLOY=testapp html
• Publish only the class files from /usr/test/inventory/bin
-f invymk.mk DEPLOY=testapp class
• Delete all the class files from /usr/test/inventory/bin
-f invymk.mk clean
• Compile all the Java source files and create the class files in /usr/test/inventory/bin
-f invymk.mk all
• Publish all the gif files (which must be in /usr/tandem/webserver/root)
-f invymk.mk DEPLOY=testapp gif

Deploy the Web Client on a Windows Environment
To deploy the compiled Java class files and the HTML files from a Windows
environment to an OSS directory under the webroot directory, run the JPUTFILE from
the Windows environment.
To get the JPUTFILE onto a Windows environment, use these steps:
1. From the Windows DOS prompt, execute the command:
ftp host-address
where host-address is the IP address of the NonStop Server where the Java
and HTML files are generated
2. At the FTP prompt:
• Logon to the system.
• Set the remote directory to the location where JGETFILE is located; this the
same directorywhere all the class files are generated and the HTML files are
located
• Set the transfer mode to ASCII .
3. Transfer JGETFILE then exit the FTP session using the commands
ftp> ASCII
ftp> get JPUTFILE JPUTFILE.BAT
ftp> bye
Once JPUTFILE.BAT is copied to a Windows environment, deploy the compiled Java
files and HTML files using this command:
JPUTFILE hostname user-ID password application-home

2- 11

How to Compile, Build, and Maintain a Pathway/iTS 8. Customize the Screens
Web Client

hostname
is the IP address or name of the NonStop server where the application is to be
deployed

user-ID
is the valid user ID on the NonStop server

password
is the password for the user ID.

application-home
is the full path name of the OSS directory where the application is to be deployed.
This directory should be subdirectory to the root directory of the web server.
If the URL for the default page on the web server is http://intraweb.mycompany.com,
you can now test the converted application by using this URL:
http://intraweb.mycompany.com/testapp/INVENTORY_START.html

8. Customize the Screens
Copy the HTML Files to be Customized
After you deploy the converted application, you can customize the HTML files.
Because most of the standard HTML editors run on a Windows platform, you probably
need to copy the HTML files from the deployment directory to some directory on
Windows, as:
1. At the Windows DOS prompt, execute
ftp host-address
where host-address is the IP address of the NonStop server where the files are
deployed.
2. Logon to the NonStop server then specify the remote OSS directory where the
HTML files are deployed. Specify local directory to which the files will get copied.
Set the transfer mode to ASCII.
ftp > user x.y password
ftp > cd /usr/webserver/root/testapp
ftp > lcd c:htmledit
ftp > ASCII
3. Use the get or mget command to get one or more HTML files. When the files are
transferred, exit the ftp session.
ftp > prompt off
ftp > mget *.html
ftp > bye

2- 12

How to Compile, Build, and Maintain a Pathway/iTS Modify the HTML Files
Web Client

Modify the HTML Files
Using a standard web editor, open the HTML files, make any modifications, and save
the file in the directory. You might also want to save the modified file in your source
change control database for future use.

Redeploy Customized HTML Files
Once the pages are changed, they need to be deployed again. Use ftp to put the files
back into a OSS deployment directory.
1. At the Windows DOS prompt, execute
ftp host-address
where host-address is the IP address of the NonStop server where the files are
to be deployed.
2. Logon to the NonStop server then specify the remote OSS directory where the
HTML files are deployed. Specify local directory to which the files will get copied.
Set the transfer mode to ASCII.
ftp > user x.y password
ftp > cd /usr/webserver/root/testapp
ftp > lcd c:htmledit
ftp > ASCII
3. Use the get or mput command to put one or more HTML files. When the files are
transferred, exit the ftp session.
ftp > prompt off
ftp > mput *.html
ftp > bye

9. Specify the Port Number of the Router
Process
After you deploy the converted application on the web server, you must configure the
converted Java applet to communicate with a router process running on the NonStop
system. You do this by using the SETPORT utility, provided with the Pathway/iTS
software, to specify an IP port number that matches the port number specified for the
router process.
Run the SETPORT utility on the NonStop system by issuing this command from the
/usr/tandem/Pathway-iTS/ directory in the OSS environment:

SETPORT port-num control-name

2- 13

How to Compile, Build, and Maintain a Pathway/iTS 10. Configure Pathway Servers for User Profiles and
Web Client User Conversion Routines

port-num
is the TCP/IP port number assigned to this application. This number must match
the port number specified when the router process was started, as described in the
Pathway/iTS System Management Manual.

control-name
is either the program-id specified in the INITPROG parameter or the app-name
specified in the APPNAME parameter when the application was converted with the
SCUP CONVERT command that included the full OSS path.
If both the INITPROG and the APPNAME parameters were specified in the
CONVERT command, the app-name from the APPNAME parameter must be
used for control-name.
For example, in the sample application you could use this command:
SETPORT 2500 /usr/tandem/webserver/root/deploy-
directory/INVENTORY
This command configures the converted Java application to send messages to the
router started with port number 2500 on the host NonStop system.

10. Configure Pathway Servers for User
Profiles and User Conversion Routines
Whether an end user is required to enter a password or a user profile is controlled by
the userAuthenticate and getProfile parameters in the control file that is generated by
the CONVERT command.
To use the user profile feature, set the getProfile parameter to true, as described in
User Profile Options in the Control File on page 3-3, and configure the Pathway server
class for the user profile server as detailed in Configure the User Profile Server Class
on page 3-6.
If your application uses user-written conversion routines running on the NonStop host,
you must configure the Pathway server class for USER-LIB-SERVER as described in
Configure the User Conversion Server Class on page 4-2.

11. Tune the Application for Performance by
Changing the Session-Length Parameter
The Java applet portion of the converted SCREEN COBOL application communicates
with the TCP so that the required tasks can be performed on the NonStop host system.
Such tasks include:
• Send operations to server classes
• Beginning, ending, and aborting transactions

2- 14

How to Compile, Build, and Maintain a Pathway/iTS 11. Tune the Application for Performance by
Web Client Changing the Session-Length Parameter

• Accept day/date/time operations
• User conversion routines
These tasks are delegated to the Pathway/iTS web gateway requester threads under
the control of the TCP. Each task involves one complete socket communication cycle
(a write and a read) or one I/O operation in a session.
A session begins when the applet opens the communication channel with the host
NonStop by establishing a socket connection with the TCP. The session ends when
the connection is closed by the applet after the task delegated to the gateway thread is
completed.
While opening a session, the applet sends a connection request to the router process
on the NonStop. The router process assigns the connection request to a waiting
gateway thread associated with a TERM object. The gateway thread then establishes
a socket connection with the applet. The router distributes client connection requests
to the waiting gateway threads while balancing the load optimally among the TCP
processes in the Pathway environment.
The number of I/O operations in a session affects the performance of the application
environment. For example, if this number is specified as 5, then the session with the
client will be kept alive until 5 socket communication cycles are done. In other words,
one gateway thread, with which the connection was established at the beginning of the
session, will be dedicated to that client (applet) until it has performed 5 delegated
tasks. After the 5 tasks are completed, the socket connection is broken, the session is
closed, and the gateway thread is freed to service another connection request from an
applet.
There is one case where the specified number of I/O operations is ignored: the BT-ET
block. After a begin-transaction operation, the session is kept alive, regardless of the
specified number of I/O operations, until the end-transaction operation is done. After
the end-transaction operation, the session is closed.
The length of the session is important in view of the response times when several
hundreds of applets are running. One gateway thread should not be tied to one client
for a long duration. Neither should the length be too small, as each beginning of a
session incurs a fixed overhead of time and resources.
Pathway/iTS provides a default value for the number of I/O operations in a session.
You can modify this value to tune the application for optimal performance.
The value is specified in the sessionlength parameter in the file named
app-name_CONTROL.html generated during the conversion process. The contents
of this file are shown in Example. In this example, the INITPROG of the application is
named LOGON, and the name of the control file is LOGON_CONTROL.html.

2- 15

How to Compile, Build, and Maintain a Pathway/iTS 12. Maintain the Client
Web Client

Example 2-2. Sample CONTROL.html File
<HTML> <HEAD>
<META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-
8859-1">
<TITLE> Control Frame </TITLE>
<SCRIPT LANGUAGE="JavaScript">
</SCRIPT> </HEAD>
<BODY>
<applet code="LOGON_MAINAPP.class", name="PathwayiTS",
archive="itsjlib.jar" width=10, height=10, MAYSCRIPT>
<param name=portnumber value="2500">
<param name=sessionlength value="20">
<param name=userAuthenticate value="true">
<param name=getProfile value="true">
<param name=encoding value="8859_1">
</applet>
</BODY> </HTML>

To modify the number of I/O operations in a session, replace the param sessionlength
default value (within the double quotes; 20 in the example) with the desired integer
value.

12. Maintain the Client
You can maintain the client by modifying either the SCREEN COBOL source files or
the Java source files. If both terminal clients and web clients access the converted
application, you might want to make future modifications in the SCREEN COBOL files
to avoid maintaining two sets of source-code files. On the other hand, if all the clients
accessing the application are web clients, modifying the Java source might be a better
option.

Modify SCREEN COBOL Source Code
Enhancements and maintenance changes to the SCREEN COBOL source code fall
into one of these categories:
• Changes to business logic only
• Changes to business logic and display
• Changes to display section only

Changes to Business Logic Only
If only the business logic changes, all the corresponding changes to the web clients
are in the Java code. In this case, to generate a newer version of the web client, do
these:
1. Reconvert the SCREEN COBOL application.

2- 16

How to Compile, Build, and Maintain a Pathway/iTS Modify Java Source Code Only
Web Client

2. Build the converted application.
3. Discard the generated HTML files and copy the previously customized HTML files
to the /usr/test/inventory/bin directory.
4. Deploy and test the application.

Changes to Business Logic and Display
If the business logic changes and also new display fields are added or existing fields
are changed or removed, the corresponding changes for the web clients will be in both
the Java code and the HTML files. To generate a newer version of the web clients, do
these:
• Reconvert the SCREEN COBOL application.
• Build the converted application.
• Customize the generated HTML files.
• Deploy and test the application.
This situation requires you to reapply the screen customizations that were done before
the last deployment. If this kind of change occurs frequently, you might want to limit
the amount of customization you do to the screens.

Changes to Display Section Only
In this scenario, no new fields are added or existing fields deleted. The changes are
cosmetic and involve moving fields around or adding new or modifying existing literal
text. To generate a newer version of the web clients, the only changes you need to
make are to the HTML files. Modify the HTML files as described under 8. Customize
the Screens and then deploy and test the modified application.

Modify Java Source Code Only
To enhance or maintain the Java source files, use your choice of commercially
available Java development environments on a platform of your choosing, or use the
NonStop Kernel environment.

2- 17

How to Compile, Build, and Maintain a Pathway/iTS Modify Java Source Code Only
Web Client

2- 18

3
Logon Security and User Profiles
This section describes the logon security and user profile features presented to the
user whenever a Pathway/iTS web client is first started. It also describes how to set up
the user profile database.

Logon Security
Whenever an end user opens the browser and goes to the URL for a Pathway/iTS web
client application, a logon screen may be displayed, if required. This screen requires
the user to enter a user name and password and a profile name.
The user name and password must be a Guardian user name and password that is
valid on the NonStop system where the Pathway/iTS software runs. Pathway/iTS
validates the entered user name and password.
If the validation fails, the logon screen reappears. This cycle continues until the user
gives a valid user name and password combination. The user can get out of this loop
by clicking Cancel on the logon screen.

User Profiles
The logon screen also provides a third field for the user to enter a user profile keyword,
which typically identifies a user role such as admin.
As the application programmer, you decide whether to use this feature, and if you use
it, you customize it to the needs of your application.
To set up your application for user profiles, you do these steps as part of the sequence
described in Section 2, How to Compile, Build, and Maintain a Pathway/iTS Web
Client:
• Specify the userAuthenticate and getProfile parameters in the control file
generated by the CONVERT command.
• If you set the getProfile parameter to false, you do not need to complete the
additional user profile configuration steps.
• If you set the getProfile parameter to true, you must:
• Use the PROFDBM utility to set special-register values for each user profile
you want to define.
• Add Java code to the applet to use the values of the special registers, in
accordance with the needs of your application.
• Configure the Pathway server that retrieves values from the user profile
database.

3 -1

Logon Security and User Profiles Actions of the Web Client

Actions of the Web Client
If the logon is successful (that is, if the end user enters a valid user name/password
combination), the client application begins to run. However, before the browser
displays the starting page of the client application, the application communicates with
the host NonStop to retrieve information associated with the profile entered by the end
user. This information resides in a database (with the Guardian file name
USERPROF) on the NonStop.
A Pathway server program supplied as part of Pathway/iTS reads the database and
obtain the profile information on behalf of the application. The applet stores this
information in various special registers for later use. Then the browser displays the
starting page—that is, the HTML page corresponding to the INITIAL program unit in
the SCREEN COBOL source program—and the client application continues to run.
If the end user does not enter a profile (that is, if the entered profile is null), the user ID
and password are validated, but no values are retrieved or set for any of the special
registers.
If the end user enters a valid profile, the profile is sent via the web gateway to the
server. The server retrieves from the database and returns to the application the
values of the seven special registers associated with user profiles (defined in the
following subsection), and also returns values for the PW-TCP-PROCESS-NAME,
PW-TCP-SYSTEM-NAME, and TERMINAL-FILENAME special registers. (All other
SCREEN COBOL special registers have no meaning for web clients; these special
registers always have default values in the converted Java code.)
If the end user enters an invalid profile (one that is not in the user profile database), a
“Profile Not Found” popup message appears. In this case, no values are returned to
the application for the seven special registers associated with user profiles, but values
are returned for the other three special registers.

Contents of the User Profile Database
The USERPROF database is a key-sequenced database with the profile name as the
key. Each record of the user profile database consists of the key and seven fields; the
values of the seven fields are stored in corresponding special registers in the Java
applet. The fields are as:
Corresponding Special
Field Name Type and Length Register in Applet
TERMINAL-PRINTER PIC X(36) TerminalPrinter
LOGICAL-TERMINAL-NAME PIC X(16) logicalTerminalName
USER-PROFILE-1 PIC X(36) userProfile1

3 -2

Logon Security and User Profiles User Profile Options in the Control File

The TERMINAL-PRINTER and LOGICAL-TERMINAL-NAME fields correspond to the
SCREEN COBOL special registers of the same names. The five USER-PROFILE-n
fields are new special registers in the applet; these fields have no corresponding
special registers in SCREEN COBOL programs. Java definitions of the special
registers are given under Special-Register Classes on page 6-120.
After the applet has received the values of these special registers from the NonStop
host, the applet uses the values during execution, just as a SCREEN COBOL
requester does.

User Profile Options in the Control File
Whether an end user is required to enter a password or a user profile is controlled by
the userAuthenticate and getProfile parameters in the control file that is generated by
the CONVERT command. The encoding parameter specifies which byte-to-string
conversion scheme the applet should use.
The control file is named appname_CONTROL.html or initprog_CONTROL.html
and contains these:
<HTML> <HEAD>
<META HTTP-EQUIV="Content-Type" content="text/html;
charset=iso-8859-1">
<TITLE> Control Frame </TITLE>
<SCRIPT LANGUAGE="JavaScript">
</SCRIPT> </HEAD>
<BODY>
<applet code="APPNAME_MAINAPP.class", name="PathwayiTS",
archive="itsjlib.jar", width=10, height=10, MAYSCRIPT >
<param name=portnumber value="PORT_NUMBER" >
<param name=sessionlength value="20" >
<param name=userAuthenticate value="true" >
<param name=getProfile value="true" >
<param name=encoding value="8859_1" >
</applet>
</BODY> </HTML>

3 -3

Logon Security and User Profiles User Profile Options in the Control File

Parameter Values Description
userAuthenticate=true Specifies that the user must enter a valid Guardian user
getProfile = true name, password, and the profile name. The user is
authenticated and the profile data from the profile server is
retrieved. In addition to the values of the registers in the
profile database, values for the PW-TCP-PROCES-SNAME,
PW-TCP-SYSTEM-NAME, and TERMINAL-FILENAME
special registers are also retrieved from the GATEWAY
TERM object.
userAuthenticate=true Specifies that the user must enter a valid Guardian user
getProfile = false name and password only. The user is authenticated and the
values for the PW-TCP-PROCESS-NAME, PW-TCP-
SYSTEM-NAME, and TERMINAL-FILENAME special
registers are retrieved from the GATEWAY TERM object.
The registers of the profile database are set to spaces.
userAuthenticate Specifies that the user must enter a valid profile name only.
=false No authentication is performed. The values of the registers
getProfile = true in the profile database, and the values for the PW-TCP-
PROCESS-NAME, PW-TCP-SYSTEM-NAME, and
TERMINAL-FILENAME special registers are retrieved from
the GATEWAY TERM object.
userAuthenticate Specifies that no logon screen is displayed. When the user
=false opens the browser and goes to the URL for the Pathway/iTS
getProfile = false web application, the application's first screen loads in the
browser. However, before the first screen loads, the values
for the PW-TCP-PROCES-SNAME, PW-TCP-SYSTEM-
NAME, and TERMINAL-FILENAME special registers are
retrieved from the GATEWAY TERM object, and the
registers of the profile database are set to spaces.
encoding Specifies which encoding scheme the applet is to use when
converting the byte-format data it receives from the host to a
string format; valid for single-byte character sets only. The
default value is 8859_1, which supports applications using
the US ASCII character set.
To support applications that use a European character-set,
you must specify the appropriate encoding scheme.
To specify the encoding scheme for applications that use a
Japanese double-byte Kanji-Katakana character set, use the
CHARSET SJIS parameter in the CONVERT command
instead of the encoding parameter in the user profile.

3 -4

Logon Security and User Profiles Use the PROFDBM Utility

Use the PROFDBM Utility
The user profile database manager (PROFDBM) utility allows you to add, update,
search for, and delete records in the USERPROF database.
Before using PROFDBM, create the database as:
TACL> FUP CREATE USERPROF, TYPE K, REC 248, KEYLEN 16

Note. You must use the name USERPROF for this database; do not use any other name.

Then run USERPROF from the TACL prompt:
TACL> RUN PROFDBM
The starting banner for the user profile database manager appears and prompts you to
enter a number corresponding to the action you want to take.

Add a Record
To add a record to the database:
1. Enter the number 1.
2. When prompted, enter the user profile name and press ENTER. This is the name
(maximum 16 characters) that the end user will enter in the logon screen.
3. Then, as prompted, enter the desired special-register values, starting with the
value for TERMINAL-PRINTER (“user printer name”). Press ENTER to enter each
value and go on to the next one. To enter a null value, just press ENTER.
4. After you have entered all values, “1 RECORD ADDED” will be displayed, and
PROFDBM prompts you to select another command.

Update a Record
To update one or more values in an existing record in the database:
2. When prompted, enter the user profile name for the record and press ENTER.
3. PROFDBM displays the current value of the first special register and then prompts
you to enter a new value. To change the value, enter the desired new value and
then press ENTER. To leave that value the same and go to the next value, just
press ENTER. Proceed the same way with the other special registers.
4. After you have entered all values, “1 RECORD UPDATED” is displayed, and
PROFDBM prompts you to select another command.

3 -5

Logon Security and User Profiles Configure the User Profile Server Class

Search for a Record
To search for an existing record in the database:
3. PROFDBM displays the current values of all the special registers in that record.
A blank after the equals sign for a register indicates a null value.
4. After the values are displayed, PROFDBM prompts you to select another
command.

Delete a Record
To delete a record from the database:
3. “1 RECORD DELETED” is displayed, and PROFDBM prompts you to select
another command.

Exit the PROFDBM Utility
To exit and return to the TACL prompt, enter any character other than 1, 2, 3, or 4.

Configure the User Profile Server Class
Pathway/iTS provides a Pathway server program for the server that retrieves values
from the user profile database. To configure the server class for this server, add these
lines to your Pathway/XM configuration source file or your PATHCOM configuration file:
RESET SERVER
SET SERVER AUTORESTART 0
SET SERVER DEBUG OFF
SET SERVER HIGHPIN OFF
SET SERVER LINKDEPTH 1
SET SERVER MAXSERVERS 5
SET SERVER NUMSTATIC 2
SET SERVER PRI 115
SET SERVER PROGRAM PROFSERV
SET SERVER SECURITY "N"
SET SERVER TMF ON
SET SERVER VOLUME $vol.userprof-subvol
ADD SERVER USR-PROF-SERVER

Note. The name of the server class specified in the ADD SERVER command must be
USR-PROF-SERVER. User profiles will be retrieved correctly only if this name is used.

3 -6


Note. For performance tuning in large applications, you might want to change some of the
specified configuration values later.

3 -7


3 -8

Pathway,I Ts Web Client Programming Manual

Pathway,I Ts Web Client Programming Manual

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a Pathway,I Ts Web Client Programming Manual

Semelhante a Pathway,I Ts Web Client Programming Manual (20)

Pathway,I Ts Web Client Programming Manual