iTP Active Transaction
Pages (iTP ATP)
Programmer’s Guide
Abstract
This guide describes iTP Active Transaction Pages (ATP), a product consisting of a
server-side JavaScript environment and a set of tools to facilitate the development of
server-side scripts. This guide is intended primarily for programmers who will develop
scripts. The guide includes instructions for installing iTP ATP and for using ATP objects
to provide web-based interfaces to existing NonStop™ TS/MP, NonStop™ TM/MP,
NonStop™ TUXEDO, NonStop™ SQL/MP, and sockets applications.
Product Version
iTP ATP 2.1
Supported Releases
This guide supports D47, G06, and all subsequent releases until otherwise indicated in a
new edition.
Part Number
Published
522292-002
February 2002
Document History
Part Number
Product Version
Published
141215
iTP ATP 1.0
October 1998
424331-001
iTP ATP 1.2
September 1999
426849-001
iTP ATP 2.0
October 2000
522292-001
iTP ATP 2.1
February 2002
522292-002
iTP ATP 2.1
April 2002
Ordering Information
For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact
your local sales representative.
Document Disclaimer
Information contained in a manual is subject to change without notice. Please check with your authorized
representative to make sure you have the most recent information.
Export Statement
Export of the information contained in this manual may require authorization from the U.S. Department of
Commerce.
Examples
Examples and sample programs are for illustration only and may not be suited for your particular purpose. The
inclusion of examples and sample programs in the documentation does not warrant, guarantee, or make any
representations regarding the use or the results of the use of any examples or sample programs in any
documentation. You should verify the applicability of any example or sample program before placing the software
into productive use.
U.S. Government Customers
FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED
SOFTWARE:
These notices shall be marked on any reproduction of this data, in whole or in part.
NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this
computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in
Section 52.227-19 of the FARS Computer Software—Restricted Rights clause.
RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 52.227-7013.
RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions
as set forth in paragraph (b)(3)(B) of the rights in Technical Data and Computer Software clause in
DAR 7-104.9(a). This computer software is submitted with “restricted rights.” Use, duplication or disclosure is
subject to the restrictions as set forth in NASA FAR SUP 18-52 227-79 (April 1985) “Commercial Computer
Software—Restricted Rights (April 1985).” If the contract contains the Clause at 18-52 227-74 “Rights in Data
General” then the “Alternate III” clause applies.
U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule
Contract.
Unpublished — All rights reserved under the Copyright Laws of the United States.
iTP Active Transaction Pages (iTP
ATP) Programmer’s Guide
Glossary
Index
Examples
What’s New in This Guide
Guide Information
Figures
ix
ix
New and Changed Information
x
About This Guide xiii
Who Should Read This Guide xiii
Organization of This Guide xiv
Related Manuals
xv
Reference Information on the Internet
xviii
Your Comments Invited xix
Notation Conventions xix
Abbreviations
xxii
1. Introduction
Server-Side JavaScript for NonStop Systems
Architecture
ATP Tools
1-1
1-3
1-5
NonStop SQL Tools 1-5
NonStop TS/MP (Pathway) Tools 1-5
NonStop TUXEDO Tools
XML for ATP Tools
1-5
1-5
IEEE Floating-Point Support 1-6
Differences Between IEEE and Compaq Floating-Point Formats 1-6
System Requirements 1-6
Restrictions
1-7
Conversion Routines 1-7
Pathway Data Buffer
1-7
Compaq Computer Corporation —522292-002
i
Tables
2. Installing and Running ATP
Contents
2. Installing and Running ATP
Required Software
2-1
Installation Overview
2-1
Before You Begin the Installation
2-2
Installing ATP 2-2
Run the IPSetup Program 2-2
Copy the ATP Software From the Distribution Medium 2-3
Install the Product and Example Files
Add-On Package Installation
2-4
2-6
NonStop TUXEDO Connectivity Options
2-7
Verifying the Installation 2-7
Customizing the Configuration 2-8
ATP in the WebServer Configuration File 2-8
ATP Configuration File
2-8
ATP TUXEDO Configuration File 2-11
ATP Add-On Configuration File
ATP Add-On Definitions File
ATP Environment Variables
2-11
2-11
2-12
Running ATP 2-14
Uninstalling ATP 2-14
Uninstall Cleanup Steps
2-15
3. ATP Web Page and Script Structure
Web Page Structure
3-1
Web Page Processing
3-2
Meta Tag Used for MultiByte Support
Script and HTML
3-2
3-3
Server-Side Script Structure 3-4
Using NonStop SQL from JavaScript
3-4
Using Pathway TS/MP Servers from JavaScript
3-8
Using NonStop TUXEDO Servers from JavaScript 3-10
Using TCP/IP Sockets from JavaScript 3-15
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
ii
4. ATP Objects, Properties, and Methods
Contents
4. ATP Objects, Properties, and Methods
HTTP Object 4-2
Properties
Methods
4-3
4-7
Exception and Error Information
Sample Application
4-12
4-13
ATPException Object 4-14
Properties
4-14
NonStop SQL Objects
4-16
atp.SQL Object 4-16
atp.sqlvar Object 4-23
NonStop TS/MP (Pathway) Objects
4-25
atp.dictionary Object 4-25
atp.field Object 4-27
atp.request Object
4-32
atp.blob Object 4-34
atp.buffer Object
4-34
NonStop TM/MP (TMF) Object 4-39
atp.transaction Object 4-39
NonStop TUXEDO Objects 4-40
atp.fml_field Object 4-40
atp.fml_table Object 4-41
atp.fml_buffer Object
Sockets Object
4-43
4-47
atp.socket Object
4-47
Global Functions 4-50
5. XML for ATP Add-On Module
XMLDOMNode Object
Properties
Methods
5-2
5-3
5-11
DOMDocument Object 5-16
Properties
Methods
5-18
5-20
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
iii
5. XML for ATP Add-On Module (continued)
Contents
5. XML for ATP Add-On Module (continued)
XMLDOMParseError Object
Properties
5-31
5-31
5-33
XMLDOMNodeList Object
Properties
Methods
5-34
5-34
XMLDOMNamedNodeMap Object
Properties
Methods
5-37
5-38
5-44
XMLDOMAttribute Object
Properties
5-45
XMLDOMElement Object
Properties
Methods
5-36
5-48
5-48
5-49
XMLDOMDocumentFragment Object 5-55
XMLDOMDocumentType Object
Properties
5-56
XMLDOMEntity Object
Properties
5-55
5-57
5-57
XMLDOMEntityReference Object
5-58
XMLDOMImplementation Object 5-59
Method
5-59
XMLDOMNotation Object
Properties
5-59
5-60
XMLDOMProcessingInstruction Object 5-60
Properties
5-61
XMLDOMCharacterData Object
Properties
Methods
5-62
5-63
5-64
XMLDOMComment Object
5-68
XMLDOMText Object 5-68
Method
5-68
XMLDOMCDATASection Object
5-69
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
iv
5. XML for ATP Add-On Module (continued)
Contents
5. XML for ATP Add-On Module (continued)
XMLDecl Object 5-70
Properties
5-70
5-71
Exception and Error Information
Sample Applications
5-73
6. Designing and Debugging ATP Applications
Designing for Performance
6-3
Security Considerations
Writing Robust Scripts
6-1
6-3
Debugging ATP Applications
6-3
6-3
General Guidelines
Displaying Variables
6-4
Setting Breakpoints
6-5
Debugging Scripts that Use SQL
6-5
Running the Server-Side JavaScript Environment from the Korn Shell 6-6
A. SQL Query Tool and Catalog Explorer
Installing the Tools
A-1
Security A-2
The .atp_sql_query Filename Extension
Read-Only Access
A-2
A-3
Using the NonStop SQL Catalog Explorer
Running the Catalog Explorer
A-3
Using the NonStop SQL Query Tool
Running the Query Tool
A-3
A-4
A-4
Entering a Query A-4
Choosing Display Options
A-4
Submitting the Query A-4
Usage Techniques A-5
B. DDL Dictionary Viewer (dview)
Installing dview B-1
Running dview
B-1
Choosing a DDL Dictionary
B-2
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
v
B. DDL Dictionary Viewer (dview) (continued)
Contents
B. DDL Dictionary Viewer (dview) (continued)
Choosing a Message Layout
B-2
Studying the Message Layout
B-2
Using the Field Object Constructors
B-2
C. HTML Forms Generator
Installing the Forms Generator
C-1
Running the Forms Generator
Choosing a DDL Dictionary
C-1
C-2
Choosing Request and Reply Messages
Finishing the Generated Page
C-2
C-4
Usage Considerations C-4
D. JavaScript Utility Driver (jud)
Installing jud D-1
Running jud
D-1
Specifying the Environment D-1
Building the Request Buffer
D-2
Displaying the Reply Message
D-3
E. XML for ATP Tools
ATP WSDL Wizard
E-1
ATP WSDL Viewer
E-2
F. ATP Examples
Index to ATP Examples
F-2
General-Purpose Functions in ATP Examples F-4
Objects Defined in the XML for ATP SOAP Library F-6
G. Migration Considerations
Runtime Operation Differences
ATP Parser Differences
Tuxedo 6.5 Support
G-1
G-2
G-4
General Considerations G-4
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
vi
Glossary
Contents
Glossary
Index
Examples
Example 3-1.
Server-Side Script and HTML 3-3
Example 3-2.
NonStop SQL Definitions and Includes
Example 3-3.
NonStop SQL Includes and Server-Side JavaScript 3-6
Example 3-4.
Implementing a NonStop SQL Statement 3-7
Example 3-5.
NonStop TUXEDO Definitions and Includes
Example 3-6.
NonStop TUXEDO Server-Side Functions 3-13
Example 3-7.
Display of HTML Data for NonStop TUXEDO
Example 3-8.
TCP/IP Sockets Script Structure 3-15
Example 3-9.
Code for TCP/IP Sockets Script - Error Handling 3-16
Example 3-10.
Code for TCP/IP Sockets Script - Function Call
Example 4-1.
Date and Time in SQL Statements 4-22
Example 5-1.
XML Code (sample.xml)
Example 5-2.
Document Type Definition (DTD)
Example 6-1.
Concatenating Strings Before Printing
Example 6-2.
Managing Memory During Long Loops
Example 6-3.
Function to Print Values of Request Variables 6-5
Example 6-4.
Running ATP from the OSS Shell Prompt
Example 6-5.
Executing Multiple Scripts from the OSS Shell 6-6
Example G-1.
Checking the Validity of Your Data Conversions
3-5
3-11
3-15
3-17
5-73
5-74
6-2
6-2
6-6
G-4
Figures
Figure 1-1.
ATP Architecture
1-3
Tables
Table 4-1.
Properties of the HTTP Object 4-2
Table 4-2.
Methods of the HTTP Object 4-2
Table 4-3.
Properties of the ATPException Object
Table 4-4.
Data Types Used by the atp.field Object
Table 5-1.
XML for ATP DOM Objects 5-1
4-14
4-30
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
vii
Tables (continued)
Contents
Tables (continued)
Table 5-2.
Common Properties of XMLDOMNode and Other DOM Objects 5-2
Table 5-3.
Common Methods of XMLDOMNode and Other DOM Objects 5-3
Table 5-4.
DOMDocument Object Properties 5-16
Table 5-5.
DOMDocument Object Methods
Table 5-6.
XMLDOMParseError Object Properties
Table 5-7.
XMLDOMNodeList Object Properties
Table 5-8.
XMLDOMNodeList Object Methods
Table 5-9.
XMLDOMNamedNodeMap Object Properties
Table 5-10.
XMLDOMNamedNodeMap Object Methods
Table 5-11.
XMLDOMNode Object Properties that are Not Valid for the
XMLDOMAttribute Object 5-44
Table 5-12.
XMLDOMNode Object Methods that are Not Valid for the
XMLDOMAttribute Object 5-45
Table 5-13.
XMLDOMAttribute Object Properties
5-45
Table 5-14.
XMLDOMElement Object Properties
5-48
Table 5-15.
XMLDOMElement Object Methods
Table 5-16.
XMLDOMDocumentType Object Properties
Table 5-17.
XMLDOMEntity Object Properties
Table 5-18.
XMLDOMCharacterData Object Properties
Table 5-19.
XMLDOMCharacterData Object Methods
Table 5-20.
XMLDecl Object Properties
Table 6-1.
Examples by Programming Task
Table 6-2.
Functions Defined in ATP Examples
Table 6-3.
Objects Defined in the XML for ATP SOAP Library F-6
5-17
5-31
5-34
5-34
5-37
5-37
5-48
5-55
5-57
5-62
5-62
5-70
F-2
F-4
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
viii
What’s New in This Guide
Guide Information
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide
Abstract
This guide describes iTP Active Transaction Pages (ATP), a product consisting of a
server-side JavaScript environment and a set of tools to facilitate the development of
server-side scripts. This guide is intended primarily for programmers who will develop
scripts. The guide includes instructions for installing iTP ATP and for using ATP objects
to provide web-based interfaces to existing NonStop™ TS/MP, NonStop™ TM/MP,
NonStop™ TUXEDO, NonStop™ SQL/MP, and sockets applications.
Product Version
iTP ATP 2.1
Supported Releases
This guide supports D47, G06, and all subsequent releases until otherwise indicated in a
new edition.
Part Number
Published
522292-002
February 2002
Document History
Part Number
Product Version
Published
141215
iTP ATP 1.0
October 1998
424331-001
iTP ATP 1.2
September 1999
426849-001
iTP ATP 2.0
October 2000
522292-001
iTP ATP 2.1
February 2002
522292-002
iTP ATP 2.1
April 2002
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
ix
What’s New in This Guide
New and Changed Information
New and Changed Information
Note. The content of this manual, 522292-002, is exactly the same as that in 522292-001. The
only difference is that the page numbers in the Glossary are now corrected.
The ATP 2.1 release of this guide includes the following additions and changes:
•
•
•
Added new subsection, IEEE Floating-Point Support on page 1-6, to describe ATP’s
new support for the IEEE floating-point standard.
Rewrote Section 2, Installing and Running ATP, to describe a new and improved
installation process.
Deleted obsolete information from Section 2, Installing and Running ATP:
° The ATP Makefile is no longer used.
° It is no longer necessary to manually relink ATP libraries and objects with a
different CGI library; it is now done automatically.
° NonStop SQL connectivity is now automatic.
° You are no longer required to do command-line configuration changes using the
nld tool.
•
•
•
Added new subsection, HTTP Object on page 4-2, to describe the client-side HTTP
protocol support for communication with HTTP servers. This API is part of the ATP
core package.
Added new subsection, ATPException Object on page 4-14, to describe the
ATPException object, which contains error information defined by the ATP objects,
such as Inet.HTTP and XML.DOMDocument.
Added new Section 5, XML for ATP Add-On Module to describe the optional XML
for ATP, which provides a standardized way to access and manipulate the
information stored in XML documents.
The DOM Objects API serves as a bridge between applications and XML
documents, enabling applications to work with XML document structures and
information as program structures rather than as text streams. Applications and
scripts can read and manipulate these structures without knowing the details of
XML syntax.
•
•
•
Added new Appendix E, XML for ATP Tools, to describe the XML for ATP add-on
tools, ATP WSDL Wizard and ATP WSDL Viewer.
Added new Appendix F, ATP Examples to show descriptions and locations of ATP
example files, including examples for the XML for ATP add-on package. Removed
some of the examples from the end of Section 3 to this appendix.
Changed the second example under Parameters in SQL Statements on page 4-21
based on feedback from QA.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
x
What’s New in This Guide
•
•
•
•
•
New and Changed Information
Removed the atp.freeMemory() function from Global Functions on page 4-50
because it is now obsolete.
Added the atp.println function to Global Functions on page 4-50.
Updated the SELECT statements under NonStop SQL Objects on page 4-16.
Made other technical and editorial changes. The major changes are marked by
change bars.
Added a Glossary.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xi
What’s New in This Guide
New and Changed Information
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xii
About This Guide
This guide describes iTP Active Transaction Pages (ATP), a product consisting of a
server-side JavaScript environment and a set of tools to facilitate the development of
server-side scripts. This guide is intended primarily for programmers who will develop
scripts. It also contains discussions of environment variables and other configuration
options for ATP.
To make full use of this guide and the product, you should also have the following
information available to you:
•
•
A description of the JavaScript programming language
A copy of the iTP Secure WebServer System Administrator’s Guide
A major benefit of ATP is that it lets you develop browser-based interfaces for existing
NonStop SQL/MP, NonStop TS/MP (Pathway), NonStop TM/MP (TMF), NonStop
TUXEDO, and sockets applications. To develop an interface for an existing application,
you must be familiar with the Compaq product on which that application is based.
Finally, you must have access to the example files distributed on the ATP CD.
Who Should Read This Guide
The iTP Active Transaction Pages (iTP ATP) Programmer’s Guide is intended for
experienced programmers who need to install, configure, and manage ATP on a Compaq
system. This guide assumes the following:
•
•
•
•
•
•
•
•
You are an experienced user of Compaq products and are specifically familiar with
the Open System Services (OSS) environment and the PATHCOM interface of
NonStop TS/MP.
You have access to and are familiar with the World Wide Web.
You are familiar with the Common Gateway Interface (CGI/1.1) standard and the
HyperText Transfer Protocol (HTTP/1.0).
You are familiar with the Java language and tools (if you plan to use Java servlets).
You are familiar with writing and using configuration scripts.
You are familiar with the TCP/IP family of protocols.
You are familiar with network security and authentication techniques.
You are familiar with XML, if you choose to use the XML for ATP add-on package.
This guide also assumes that you have experience operating a secure computing system.
For an introduction to basic network security concepts, refer to the iTP Secure
WebServer System Administrator’s Guide.
If you need more information about Compaq NonStop systems, you should consult the
following publications before reading this guide:
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xiii
Organization of This Guide
About This Guide
•
•
Introduction to the NonStop Himalaya K100 and K1000/K2000 or Introduction to
the NonStop Himalaya K10000/K20000 if you use an operating system release
starting with “D,” for example, D47.
G-Series Highlights and Migration Planning Guide if you use an operating system
release starting with “G,” for example, G06.
Organization of This Guide
This guide consists of five sections and four appendixes:
Section 1, Introduction, introduces the product and describes its architecture.
Section 2, Installing and Running ATP, describes how to install the software, customize
the configuration, run ATP, and gain access to the major ATP tools.
Section 3, ATP Web Page and Script Structure, describes the syntax for delimiting
server-side JavaScript on a web page and explains the structure of several sample
scripts.
Section 4, ATP Objects, Properties, and Methods, describes the objects and methods you
use to create scripts that use HTTP, NonStop SQL, NonStop TS/MP, NonStop TM/MP,
NonStop TUXEDO, and sockets.
Section 5, XML for ATP Add-On Module, describes the optional XML for ATP, which
provides a standardized way to access and manipulate the information stored in XML
documents.
Section 6, Designing and Debugging ATP Applications, provides guidelines for writing
resilient, efficient scripts, configuring ATP for performance, and debugging scripts that
use various ATP interfaces.
Appendix A, SQL Query Tool and Catalog Explorer, describes the features and use of
two tools that help you generate and test queries for use in ATP scripts.
Appendix B, DDL Dictionary Viewer (dview), describes a tool you can use to study the
message layouts in a dictionary and to generate constructors for objects representing
fields in a message.
Appendix C, HTML Forms Generator, describes a tool you can use to generate an
HTML form that communicates with a NonStop TS/MP (Pathway) server class.
Appendix D, JavaScript Utility Driver (jud), describes a tool you can use to prototype an
application that communicates with a NonStop TUXEDO service.
Appendix E, XML for ATP Tools, describes the XML Wizard tool and the XML Viewer
tool that are available with the XML for ATP add-on package.
Appendix F, ATP Examples, lists some of the example scripts provided on the ATP CD.
Appendix G, Migration Considerations, describes runtime operation differences, ATP
parser differences, Tuxedo 6.5 support, and general considerations in migrating between
NSK and ATP.
Glossary defines terms used for this and similar products.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xiv
Related Manuals
About This Guide
Related Manuals
The following manuals contain additional information about installing, configuring, and
managing Compaq NonStop systems or other products you can use with ATP.
iTP WebServer Manuals
•
•
iTP Secure WebServer System Administrator’s Guide describes how to install,
configure, and manage the iTP Secure WebServer. It also discusses how to develop
and integrate Common Gateway Interface (CGI) applications and Java servlets into
an iTP Secure WebServer environment. This guide is intended for experienced
Compaq system administrators and operators who need to install, configure, and
manage the iTP Secure WebServer on a Compaq system.
iTP Secure WebServer Operator Messages Manual describes the operator messages
reported by components of the iTP Secure WebServer and related products. The
audience for this manual is system managers and operators who will monitor and
control the operations of an iTP Secure WebServer environment.
NonStop Java Manuals
For information about the features of the Compaq NonStop Server for Java, refer to the
following Compaq manual:
•
The NonStop Server for Java (NSJ) Programmer’s Guide explains the Compaq
NonStop Server for Java, a Java environment that supports compact, concurrent,
dynamic, and portable programs for the enterprise server.
And the following JavaSoft manuals:
•
•
JavaSoft Java Development Kit 1.1.6
JavaSoft Java Language Specification 1.1
If you plan to use NonStop Server for Java with NonStop SQL/MP, you should refer to
the current NonStop SQL/MP manual set.
NonStop TM/MP Manuals
For information about the set of Compaq NonStop Transaction Manager/MP (TM/MP)
manuals, refer to the following manuals:
•
•
The Compaq NonStop TM/MP Application Programmer's Guide describes how to
design requester and server modules for execution in the TMF programming
environment on the NonStop Himalaya range of servers, and how to use the TMF
audit-reading procedures.
The Compaq NonStop™ TM/MP Planning and Configuration Guide describes
planning and configuration for the TM/MP product. It is intended for individuals
responsible for system and database management.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xv
NonStop Transaction Services/MP (NonStop TS/MP)
Manuals
About This Guide
•
•
•
•
The Compaq NonStop™ TM/MP Introduction introduces the concepts of transaction
processing and the features of the TM/MP product. This manual is directed to
business professionals, application designers and programmers, and system
managers.
The Compaq NonStop™ TM/MP Management Programming Manual provides
system-specific information about the management programming interfaces to the
TMF subsystem.
The Compaq NonStop™ TM/MP Operations and Recovery Guide describes how to
perform day-to-day operations with the TM/MP product, how to dump and archive
audit information and the database, and how to recover from error conditions.
The Compaq NonStop™ TM/MP Reference Manual describes how to use the
TMFCOM command interface to the TM/MP product.
NonStop Transaction Services/MP (NonStop TS/MP) Manuals
For information specific to managing PATHMON environments, refer to the following
manuals:
•
•
TS/MP System Management Manual discusses the PATHCOM and TACL
commands used to configure and manage PATHMON environments. This manual
also includes manageability guidelines, information about monitoring and tuning a
PATHMON environment to optimize performance, and methods for diagnosing and
correcting problems.
TS/MP Management Programming Manual describes how to start, configure, and
manage PATHMON environments programmatically and describes the event
messages that report errors and other occurrences of interest to operators.
NonStop TUXEDO Manuals
For information about the set of NonStop TUXEDO manuals, refer to the D- and Gseries TIM collections.
Refer also to the online information in the TIM Independent Product collection listed
under Compaq NonStop TUXEDO 6.5.3, September 2000 Docs. The Programming and
Development folder contains an Application Programming Guide with a list of related
documents. Another folder contains examples.
Open System Services (OSS) Manuals
For information specific to the OSS environment, refer to the following manuals:
•
•
•
Open System Services User’s Guide describes the Open System Services (OSS)
environment: the shell, file-system, and user commands.
Open System Services Installation Guide describes how to install and configure the
Compaq NonStop Kernel OSS environment.
Open System Services Management and Operations Guide describes how to manage
and operate the Compaq NonStop Kernel OSS environment.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xvi
SOAP and XML
About This Guide
SOAP and XML
For information about SOAP and XML, refer to:
•
•
The SOAP4NSK User's Manual provides reference and user information for
SOAP4NSK, a product that provides SOAP or XML access to Pathway services.
The NonStop SOAP User’s Manual provides reference and user information for
NonStop™ SOAP, a product that provides SOAP or XML access to NonStop
TS/MP services. NonStop SOAP also includes a C++ API for access to remote
SOAP servers.
TCP/IP Manuals
For information specific to managing the TCP/IP subsystem, refer to the following
manuals:
•
•
•
The TCP/IP Configuration and Management Manual describes the installation,
configuration, and management of the Compaq TCP/IP subsystem. It is for system
managers, operators, and others who require a basic understanding of the Compaq
TCP/IP implementation.
The TCP/IP (Parallel Library) Configuration and Management Manual describes
how to configure and manage the Parallel Library TCP/IP subsystem. Use this
manual to configure Parallel Library TCP/IP on your system in conjunction with the
TCP/IP (Parallel Library) Migration Guide. The TCP/IP (Parallel Library)
Migration Guide lists migration considerations that could affect your configuration.
The TCP/IP and IPX/SPX Programming Manual describes the programmatic
interface to the Compaq TCP/IP data communications software.
WebSafe2 Manuals
For detailed information about WebSafe2, refer to the following Atalla manuals:
•
WebSafe2 Internet Security Processor Installation and Operations Manual
(domestic and export editions)
Other Related Manuals
The following manuals contain additional information about Compaq NonStop systems:
•
•
•
Introduction to the NonStop Himalaya K100 and K1000/K2000 describes the
NonStop Himalaya K100, K1000, and K2000 servers. It is for anyone who needs an
overview of the system and its capabilities.
Introduction to the NonStop Himalaya K10000/K20000 describes the K10000 and
K20000 servers. It is for anyone who needs an overview of the system and its
capabilities.
G-Series Highlights and Migration Planning Guide gives an overview of the
hardware and software supported for G-series systems and describes how to plan for
the migration to a G-series system. It is for anyone who needs to understand how
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xvii
Reference Information on the Internet
About This Guide
migrating or upgrading to a G-series release affects installation, configuration,
operations, system management, maintenance, and the migration of applications,
networks, and database files.
•
Himalaya S-Series Planning and Configuration Guide describes how to plan and
configure a Himalaya S-series server and provides a case study documenting a
sample system. This guide describes the ServerNet system area network (ServerNet
SAN), the available hardware and software configurations for Himalaya S-series
servers, site planning and preparation, creating the operational environment, and
making hardware and software configuration changes to an existing server. This
guide is for the personnel responsible for planning the installation, configuration,
and maintenance of the server and the software environment at a particular site.
Reference Information on the Internet
The following URL references are available and can be retrieved by using standard web
clients over the Internet:
•
General references:
•
HyperText Transfer Protocol (HTTP) references:
•
Common Gateway Interface (CGI) references:
•
Network and firewall security reference:
•
Digital ID from VeriSign reference:
•
Request for Comments (RFC) reference:
•
Java Servlet reference
http://www.w3.org
http://www.ics.uci.edu/pub/ietf/http/
http://hoohoo.ncsa.uiuc.edu/cgi/
http://www.stars.com/
http://www.nai.com/nai_labs/asp_set/network_security.asp
http://www.verisign.com/idcenter/new/idplus1.html
http://www.cis.ohio-state.edu/hypertext/information/rfc.html
http://java.sun.com/products/servlet/download.html
Refer to the Bibliography in the iTP Secure WebServer System Administrator’s Guide
for a list of books that can help you become more familiar with web technology.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xviii
Your Comments Invited
About This Guide
Your Comments Invited
After using this guide, please take a moment to send us your comments. You can do this
by returning a Reader Comment Card or by sending an Internet mail message.
A Reader Comment Card is located at the back of printed manuals and as a separate file
on the Compaq User Documentation disc. You can either fax or mail the card to us. The
fax number and mailing address are provided on the card.
Also provided on the Reader Comment Card is an Internet mail address. When you send
an Internet mail message to us, we immediately acknowledge receipt of your message. A
detailed response to your message is sent as soon as possible. Be sure to include your
name, company name, address, and phone number in your message. If your comments
are specific to a particular manual, also include the part number and title of the manual.
Many of the improvements you see in Compaq manuals are a result of suggestions from
our customers. Please take this opportunity to help us improve future manuals.
Notation Conventions
General Syntax Notation
The following list summarizes the notation conventions for syntax presentation in this
guide.
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 non-italic letters. Lowercase non-italic letters indicate keywords and reserved
words; enter these items exactly as shown. For example:
gtacl
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
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xix
General Syntax Notation
About This Guide
each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:
LIGHTS [ ON
]
[ OFF
]
[ SMOOTH [ num ] ]
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 }
| 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 the following
example, there are no spaces permitted between the period and any other items:
$process-name.#su-name
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xx
Notation for Messages
About This Guide
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 ]...
Notation for Messages
The following list summarizes the notation conventions for the presentation of displayed
messages in this guide.
Bold Text. Bold text in an example indicates user input entered 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:
LDEV ldev [ CU %ccu | CU %... ] UP [ (cpu,chan,%ctlr,%unit) ]
{ } 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
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xxi
Change Bar Notation
About This Guide
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:
LBU { X | Y } POWER FAIL
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 }
% 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 edition of the
manual and the preceding edition. 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.
Abbreviations
The following list defines abbreviations and acronyms used in this guide. Both industrystandard terms and Compaq terms are included.
AOT. Ahead Of Time
APKB. Atalla Public Key Block
AWT. Abstract Windows Toolkit
ARPA. Advanced Research Project Agency
ATP. Active Transaction Pages
BSD. Berkeley Software Distribution
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xxii
Abbreviations
About This Guide
C.
Country
CA. Certificate Authority
CBC. Cipher Block Chaining
CCITT. Consultative Committee for International Telegraph and Telephone
CGI. Common Gateway Interface
CN. Common Name
CRL. Certificate Revocation List
CWD. Current Working Directory
DES. Data Encryption Standard
DN. Distinguished Name
DOM. Document Objects Model
DNS. Domain Name Server
DTD. Data Type Definition
EMS. Event Management Service (Compaq)
FBA. Forms Based Administration
FTP. File Transfer Protocol
GIF. Graphics Interchange Format
GUI. Graphical User Interface
HTML. HyperText Markup Language
HTTP. HyperText Transfer Protocol
HTTPD. HyperText Transfer Protocol Daemon
IEEE. Institute of Electrical and Electronics Engineers
IEN. Internet Engineering Note
IP.
Internet Protocol
JDBC. Java Data Base Connectivity
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xxiii
Abbreviations
About This Guide
JDK. Java Development Kit
JIT. Just-In-Time (Java compiler)
JNI. Java Native Interface
JSP. Java Server Pages
JVM. Java Virtual Machine
KEK. Key Exchange Key
L.
Locality
LAN. Local Area Network
MAC. Message Authentication Code
MD5. Message Digest
MFK. Master File Key
MIME. Multiple Internet Mail Extensions
NCSA. National Center for Supercomputing Applications
O.
Organization
OLTP. Online Transaction Processing
OSS. Open System Services
OU. Organizational Unit
PAID. Process Accessor ID
PCT. Private Communication Technology
PDF. Portable Document Format
PEM. Privacy Enhanced Message
PKS. Public Key Certificate Standard
PPP. Point to Point Protocol
QIO. Queued Input Output
RFC. Request for Comments
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xxiv
Abbreviations
About This Guide
RLS. Resource Locator Service
RSA. Rivest, Shamir, and Adelman
SCF. Subsystem Control Facility
SCT. Secure Configuration Terminal
SGC. Server Gated Cryptography (Microsoft)
SGML. Standard Generalized Markup Language
SHA1. Secure Hash Algorithm
SI.
Session Identifier
SLIP. Serial Line IP
SMTP. Simple Mail Transfer Protocol
SOAP. Simple Object Access Protocol
SSC. Servlet Server Class (for Java)
SSI. Server Side Include
SSL. Secure Sockets Layer
ST. State
TACL. Tandem Advanced Command Language
TAL. Transaction Application Language
Tcl. Tool Command Language
Tcl/CGI. Tool Command Language/Common Gateway Interface
TCP/IP. Transmission Control Protocol/Internet Protocol
TS/MP. Transaction Services/Massively Parallel
URL. Uniform Resource Locator
WID. WebSafe2 Interface Driver
WISP. WebSafe2 Internet Security Processor
X.509. CCITT Recommendation for security service
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xxv
Abbreviations
About This Guide
XML. Extensible Markup Language
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
xxvi
1
Introduction
iTP Active Transaction Pages (ATP) is a server-side JavaScript environment for
NonStop systems. This section summarizes the features and architecture of iTP ATP.
Note. For convenience, this manual usually refers to iTP ATP as ATP. Assume that any
reference to ATP (in uppercase) stands for the full product name iTP Active Transaction Pages
(iTP ATP).
This section includes the following subsections:
•
•
•
•
Server-Side JavaScript for NonStop Systems on page 1-1
Architecture on page 1-3
ATP Tools on page 1-5
IEEE Floating-Point Support on page 1-6
Server-Side JavaScript for NonStop Systems
Server-Side JavaScript for NonStop Systems enriches the iTP Secure WebServer
application-development process by letting you use the popular JavaScript scripting
language and readily available web-content authoring tools.
ATP uses the Netscape JavaScript interpreter with extensions to provide interfaces to
Compaq products such as NonStop SQL/MP, NonStop TS/MP (formerly Pathway),
NonStop TM/MP (TMF), NonStop TUXEDO, and sockets applications.
Some of the benefits of ATP are
•
•
•
•
•
•
You can develop web pages, including forms, that use Pathway (NonStop TS/MP)
server classes, NonStop SQL databases, NonStop TUXEDO servers, and TCP/IP
sockets. Thus ATP gives you a convenient way to provide browser-based access to
existing applications.
You can use workstation-based tools to develop your web pages. For example, you
could use an authoring tool like Microsoft FrontPage or a text editor like vi or
Windows Notepad. You do not need any Compaq or OSS development tools to
develop pages.
You do not have to compile anything. Instead you just edit and test your web page
until it works the way you expect.
You can keep web-page content and layout separate from your script, using standard
HTML notation to mark script boundaries.
ATP does not require extensive configuration. (Some configuration options are
defined for tuning, but you can get started without having to use them.)
You do not have to modify an existing application or database to provide access to it
from a web page.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -1
Introduction
•
•
•
•
Server-Side JavaScript for NonStop Systems
ATP supports a broad range of NonStop TS/MP application architecture and
implementation styles. For instance, ATP is compatible with COBOL and C servers
and has a high tolerance for complex application-message structures and data types.
ATP supports various NonStop TS/MP transaction scenarios. For instance, a
transaction can span multiple sends to server classes, which can run in the same or
different PATHMON environments.
ATP is compatible with any version of Netscape Navigator and Internet Explorer.
(Some ATP example scripts, notably the tools described in ATP Tools on page 1-5,
take advantage of features available only in Netscape Navigator 3.1 or later or
Internet Explorer 4.0 or later.)
All data communication uses HTTP; no plug-ins or back channels are required for
communication.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -2
Architecture
Introduction
Architecture
Figure 1-1 shows the relationship of ATP to the iTP Secure WebServer and to legacy
applications in the NSK environment.
Figure 1-1. ATP Architecture
Web pages
with scripts
Browser
NonStop Tuxedo
Field Tables
iTP Secure
WebServer
ATP CGI
Server
Browser
HTML
DDL Dictionaries
Browser
XML for
ATP addon module
NonStop TS/MP
Applications
NonStop Tuxedo
Applications
NonStop SQL/MP
Databases
VST001
The ATP Common Gateway Interface (CGI) server is a Pathway CGI server class named
atp in the iTP Secure WebServer environment. You configure the iTP Secure
WebServer to route all requests for files with an extension of .atp to this server class.
For information about this configuration step see Section 2, Installing and Running ATP.
Note. Although content in the iTP Secure WebServer environment traditionally resides in the
OSS namespace, ATP web pages can also be stored in the /G namespace. For details, see
the iTP Secure WebServer System Administrator’s Guide.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -3
Architecture
Introduction
ATP parses the .atp page and executes any embedded server-side scripts. These scripts
are identified by special HTML tags: the same tags used by Netscape for their
JavaScript products. For information about the tags, see Section 3, ATP Web Page and
Script Structure.
The atp server class has the following internal components:
•
•
The JavaScript language interpreter (from Netscape).
An HTML parser to identify imbedded server-side scripts and to expand server-side
include files. Include files enable commonly used scripts to be shared by
many pages.
Note. ATP does not support every kind of server-side include described in the iTP Secure
WebServer System Administrator’s Guide. For information about server-side includes
supported by ATP, see Section 3, ATP Web Page and Script Structure.
•
JavaScript language objects to support interfaces with NonStop SQL, NonStop
TS/MP, NonStop TUXEDO, and the NonStop TCP/IP sockets interface.
NonStop SQL interface objects allow direct access to NonStop SQL databases
from web pages.
NonStop TS/MP and Pathway interface objects allow
° Composition and decomposition of application messages
° Data conversion between JavaScript data types and C and COBOL data types
° Use of Data Definition Language (DDL) dictionaries, which NonStop TS/MP
customers traditionally use to define application-message layouts
° Definition of transaction boundaries using NonStop TM/MP
° Pathsend communication with application servers
NonStop TUXEDO interface objects allow
° Use of NonStop TUXEDO FML field tables to define FML and FML32 buffers
° Communication with NonStop TUXEDO request/response servers (but not
conversational servers). ATP objects support both FML and view buffers
The sockets interface object allows web pages to act as sockets clients to TCP/IP
server applications. For example, a web page can send an SMTP message or HTTP
request or act as a Telnet client.
To the JavaScript author, the objects that provide these capabilities appear to be built
into the JavaScript language.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -4
ATP Tools
Introduction
ATP Tools
ATP comes with a set of tools that make it easier to develop server-side scripts. Because
these tools are scripts in themselves, you can print or display the source of each to see
examples of how to use various ATP objects and functions.
NonStop SQL Tools
The following tools help you develop scripts that use NonStop SQL applications:
•
•
The SQL Catalog Explorer enables you to browse the contents of an SQL catalog
and generate a query suitable for pasting into a script. You use HTML features like
check boxes and pull-down lists to describe the desired query. The Explorer
generates the corresponding SQL statement. Appendix A, SQL Query Tool and
Catalog Explorer, describes the Catalog Explorer.
The Query Tool enables you to test a query, displaying the results in different
formats. You can also generate an iqy file for use with Excel. Appendix A, SQL
Query Tool and Catalog Explorer, describes the Query Tool.
NonStop TS/MP (Pathway) Tools
The following tools help you develop scripts that use Pathway applications:
•
•
The DDL Dictionary Viewer (dview) displays the message layouts defined in a
dictionary and generates constructors for objects representing fields in the message.
You can cut these constructors to your clipboard and paste them into your script.
Appendix B, DDL Dictionary Viewer (dview), describes dview.
The HTML Forms Generator enables you to select request and reply messages
from a DDL dictionary, then generates an HTML form that sends the request and
receives the reply using the NonStop TS/MP Pathsend facility. You add error
handling, security features, and code to support COBOL redefines, C unions, and
COBOL occurs to the script. Appendix C, HTML Forms Generator, describes the
Forms Generator.
NonStop TUXEDO Tools
The JavaScript Utility Driver (jud) helps you develop scripts that use NonStop
TUXEDO applications. It lets you specify fields from NonStop TUXEDO field tables
and views, then send an FML or FML32 buffer to a NonStop TUXEDO service. This
implementation of the NonStop TUXEDO jud utility is especially useful for
prototyping applications. Appendix D, JavaScript Utility Driver (jud), describes the
JavaScript Utility Driver.
XML for ATP Tools
Two tools, ATP WSDL Wizard on page E-1 and ATP WSDL Viewer on page E-2, are
delivered with the XML for ATP optional add-on package.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -5
IEEE Floating-Point Support
Introduction
IEEE Floating-Point Support
Depending upon your system, you have the option of choosing between IEEE floatingpoint format and Compaq floating-point format in your native C and C++ programs for
performing floating-point arithmetic.
The data format is different between the two floating-point options. Data interchange
with systems other than Compaq systems is easier with IEEE floating-point format than
with Compaq floating-point format.
Differences Between IEEE and Compaq Floating-Point Formats
•
•
•
•
•
•
•
IEEE floating-point data format is an industry standard, whereas Compaq’s floatingpoint format is Compaq’s implementation of floating-point arithmetic.
IEEE and Compaq floating-point data formats have a different range of values and
different precisions.
IEEE and Compaq floating-point data formats have different internal layouts (for
example, the exponents are in different bit fields).
IEEE floating-point format enables your application to take advantage of the greater
performance provided by the floating-point instructions available in some processor
hardware.
IEEE floating-point format is good for porting applications.
IEEE floating-point has good default handling of overflow, underflow, divide-byzero, and invalid operation.
IEEE floating-point denormalized numbers avoid computational problems that arise
from very small numbers as intermediate results in computations.
System Requirements
The ATP 2.1 IEEE floating-point support is only available when the target
hardware/software system supports IEEE-floating point format. The following list
shows the basic system requirements for IEEE floating-point support.
•
•
IEEE floating-point format runs on S7000 and S72000 or above processors. It does
not run on S70000 processors.
IEEE floating-point format requires the G06.06 or later release of native C and C++
compilers and the nld utility for linking.
The processor type and operating system release version used are determined during the
installation process, so be sure you install ATP on a CPU on which IEEE floating-point
format can run (refer to Before You Begin the Installation on page 2-2). The installation
process automatically selects the correct libraries and builds the final executable binary.
For further information, refer to the Guardian Programmer’s Guide.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -6
Restrictions
Introduction
For a list of conversion routines, refer to the Guardian Programmer’s Guide, and for
more information about conversion routines, refer to the Guardian Procedure Calls
Reference Manual.
Restrictions
When IEEE floating-point support is enabled, the following restrictions are applied to
ATP 2.1:
•
•
No NonStop Tuxedo support is available. The NonStop Tuxedo software supports
only Compaq floating-point values. All Tuxedo-related objects, such as
atp.fml_field, atp.fml_buffer, and atp.fml_table, become
undefined. Once the installation process detects IEEE floating-point support on the
target system, the NonStop Tuxedo installation options are disabled automatically.
Conversion routines are invoked internally, as described under Conversion Routines
on page 1-7.
Conversion Routines
Compaq and IEEE floating-point conversion routines are invoked internally for
SQL/MP functions. The precision of conversion, which is handled by ATP, depends on
NSK system functions, such as:
•
•
•
•
NSK_FLOAT_TNS64_TO_IEEE64_
NSK_FLOAT_TNS32_TO_IEEE64_
NSK_FLOAT_IEEE64_TO_TNS32_
NSK_FLOAT_IEEE64_TO_TNS64_
Pathway Data Buffer
The atp.buffer.ieee property enables you to specify the floating-point format of
the Pathway data buffer.
The atp.buffer.ieee property is a JavaScript Boolean type variable. The default
value is false, which means that the Compaq floating-point format is used and that
conversion routines (described previously) will be invoked if the target system supports
IEEE floating-point format.
To communicate with the IEEE floating-point enabled Pathway server, you must set the
atp.buffer.ieee property to true prior to using the setData or setBinary
methods.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -7
Introduction
Pathway Data Buffer
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
1 -8
2
Installing and Running ATP
This section describes how to install ATP, how to set up the configuration for optimum
performance, and how to run ATP. This section includes the following subsections:
•
•
•
•
•
•
•
•
•
Required Software on page 2-1
Installation Overview on page 2-1
Installing ATP on page 2-2
Verifying the Installation on page 2-7
Customizing the Configuration on page 2-8
ATP in the WebServer Configuration File on page 2-8
ATP Environment Variables on page 2-12
Running ATP on page 2-14
Uninstalling ATP on page 2-14
Required Software
You must install and configure the following software before you install ATP.
•
•
•
•
•
NonStop Kernel D47 or later, or G06.06 or later
Open System Services (OSS)
Native C++ Compiler, IPM AAS or later
iTP WebServer or iTP Secure WebServer, IPM ABI or later
TCP/IP and its SCF product module, D40 or later
You also need a TMF-audited volume, if you plan to use the SQL examples.
Installation Overview
The ATP files need to be installed into your iTP WebServer directory within the
subdirectory /atp. You will be prompted for the path of the iTP WebServer directory
during the installation process, so you will need to have access to it. For the examples in
this section, the default source installation directory on the CD is assumed to be:
/usr/tandem/atp/<version>/
where <version> is the vproc of the package (for example,
T0345V21_31JAN02_BASE_V210_5)
After the ATP product is installed, the files reside in the default target directory that you
specify. For purposes of this documentation, the default target directory is referred to as
/usr/tandem/webserver/atp; your target directory could be named something
else.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -1
Installing and Running ATP
Before You Begin the Installation
Before You Begin the Installation
•
•
•
•
•
•
•
•
Review the readme file on the product CD to make sure you have the correct version
for all products installed on your system.
Make sure your site meets the minimum hardware and software requirements, as
indicated in the IPSetup User's Guide on the product CD.
Make sure you know the path of your iTP WebServer directory, which will be the
target directory for <your_webserver_path>/atp files.
Check whether previous installations of ATP products and examples are already
installed on the system where you intend to install this version of ATP.
If you haven't used the IPSetup program before, you might want to refer to the
IPSetup User's Guide on the product CD for information about this installation
utility. The file is USRGUIDE.PDF on the CD.
Before running ./setup under Install the Product and Example Files on page 2-4,
you must be logged on as the same userid that originally installed iTP WebServer.
If you want IEEE floating-point format enabled, make sure, before you run
./setup, that the OSS Shell (osh) currently running on the CPU supports IEEE
floating-point.
Any atp.config file that exists before the installation will be saved into a backup file
named atp.config.backup during the installation process.
Installing ATP
The installation program, ./setup, is implemented in Tcl scripts. The setup program
stores all installation information, including all of the installed add-on packages, into the
setup.env file under the target installation directory. All options in the setup program
have default values. You press the enter key to accept the default values during the
installation process.
You can install ATP in one of these two ways:
•
•
Run the IPSetup Program
Copy the ATP Software From the Distribution Medium.
Run the IPSetup Program
1. Open the product CD by double clicking on the CD drive.
2. Click the View Readme file button. Setup opens the readme file in Notepad. Be sure
to review the entire readme before proceeding.
3. Click the IPSetup button to launch IPSetup. The program displays a Welcome
Screen and a License Agreement screen. To continue the installation, click Next on
each of these screens.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -2
Installing and Running ATP
Copy the ATP Software From the Distribution
Medium
4. On the Placement Options screen, click the NonStop Kernel RISC radio button.
Uncheck the box for “Use DSM/SCM to complete installation on host.” Click Next.
5. On the Product Selection screen, highlight ATP as the product you want to install.
Click the ADD button. Click Next.
6. Log on with a userid that is capable of writing to the /usr OSS directory (for
example, super.super) by following the instructions on the Host Information screen.
You can use either the system name or the system IP address to log on. Click Next.
7. On the Host Target screen, you can either accept the default locations for Work and
Backup subvolumes or browse to locations of your choice. Click Next when you are
satisfied with the locations.
8. On the Host File Placement screen, you can either accept the default disk locations
or browse to locations of your choice. Click Next when you are satisfied with the
locations.
9. On the Placement Manifest screen, review the file locations. You can click Back to
go back and change them. When you are satisfied with the locations, click Next.
This step may take a few minutes to complete.
10. On the Placement Complete screen, you can choose the check boxes to view the
release documentation. It is recommended that you review the release
documentation. Click Finish to complete running IPSetup.
Copy the ATP Software From the Distribution Medium
If you are using IPSetup with a product CD, the following procedure is handled
automatically, so ignore these steps and move on to Install the Product and Example
Files on page 2-4 after IPSetup completes.
If you are not using IPSetup, follow these steps to copy the ATP software from the
distribution medium:
1. Copy the product files to $ISV.ZATP (where ISV is the name of your installation
subvolume).
If you will also be installing a new XML for ATP, be sure to copy the product files
for it.
2. On the Compaq NonStop system, log on as SUPER.SUPER, go to $ISV.ZATP, and
unpax the product file using the TACL macro COPYOSS:
TACL>
TACL>
TACL>
TACL>
LOGON SUPER.SUPER
VOLUME $ISV.ZATP
RUN COPYOSS T0345PAX
RUN COPYOSS T1242PAX (if you’re installing XML for ATP)
This places the contents of T0345PAX into the directory /usr/tandem/atp and,
if you are installing XML for ATP, places the contents of T1242PAX into the
directory /usr/tandem/atp/pkgs.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -3
Installing and Running ATP
Install the Product and Example Files
Install the Product and Example Files
Use the following steps to install the product and example files. What you need to enter
is shown in bold type and the information displayed by your system is shown in italics.
1. Go to the install directory:
cd /usr/tandem/atp/<version>
where <version> is the vproc of the package (for example,
T0345V21_31JAN02_BASE_V210_5)
2. Run the ./setup command from the same userid that originally installed iTP
WebServer (you must be logged on as that userid before running ./setup):
./setup
This script installs the iTP Active Transaction Pages (ATP) and allows you to
configure the ATP environment.
You will be asked to enter some install-related information.
Please have the following information handy:
o iTP WebServer install location (Default: /usr/tandem/webserver).
All the prompts for information have default values within square brackets ([]).
Press enter to use the default value or enter the customized value you want the setup
program to use. For example: Enter the iTP WebServer install location
[/usr/tandem/webserver]. Press the 'Enter' key to use the default location or else you
can enter a specific location like /home/webman/webserver and then press the
'Enter' key.
Enter the iTP WebServer install location [/usr/tandem/webserver] ...
3. Press Enter to use the default location or type in a different location.
Preparing ATP sample files … Please Wait
You will be prompted to enter the Guardian Volume name for the area you would
like to install the Guardian based files for ATP library and sample applications.
Please enter the name without a leading $ or /G
Enter Guardian Volume Name ([DATA00] DATA07 DATA13 DATA24 SYSTEM):
4. Press Enter to use the default Guardian volume name, or type in an alternative name
without a leading $ or /G.
Preparing CGI library ... Please Wait
Setup detects that your system has IEEE floating-point format support. IEEE
floating-point format has better performance and precision in JavaScript arithmetic.
However, ATP Tuxedo objects will be disabled, if IEEE floating-point is enabled,
because NonStop Tuxedo Software cannot support IEEE floating-point format.
Do you want to apply IEEE floating point support? ... ([y]/n)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -4
Installing and Running ATP
Install the Product and Example Files
5. Press Enter to apply IEEE floating-point support.
Assuming that you selected IEEE floating-point support and that you purchased the
XML for ATP Add-On Module, the system displays the following information:
Your selection of IEEE floating point support will disable ATP Tuxedo support.
checking add-on packages at /usr/tandem/atp/pkgs ...
checking /usr/tandem/atp/pkgs/<version>/ ...
found xml
Do you want to install ATP for XML from /usr/tandem/atp/pkgs/<version>/ ...
([y]/n)
6. Press Enter to install the XML for ATP add-on package.
creating atp.pway. Please wait...
(Some NLD warnings were suppressed because the -verbose option was off.)
creating atpd.pway. Please wait...
(Some NLD warnings were suppressed because the -verbose option was off.)
invoking SQL compiler for atp.pway. Please wait...
invoking SQL compiler for atpd.pway. Please wait...
!!! No tuxedo support when ATP uses IEEE floating point. !!!
Would you like to install the ATP sample applications? ([y]/n):
7. Press Enter to install the ATP sample applications.
You will be prompted to enter a subvolume. This prefix will be used to create three
Guardian subvolumes for the Guardian portions of the examples. The default prefix
is ZATP with the example files being created in directories suffixed EM (employee)
FU (file upload) and HM (home bank).
Enter Subvolume Prefix (up to 6 chars) Default = ZATP :
8. Press Enter to use the default subvolume prefix, or type in an alternative prefix of
up to six characters in length.
cd /usr/tandem/webserver/atp/examples/pathway/employee
making pathway employee samples ...
…
making pathway file_upload samples ...
cp -Wclobber ddlsrc.ddl /G/DATA00/ATPDEVFU/ddlsrc
…
making pathway homebank samples ...
cp -Wclobber ddlsrc.ddl /G/DATA00/ATPDEVHM/ddlsrc
…
cp /usr/tandem/webserver/atp/conf/atp.config -> /usr/yijou/ws/conf
ln -s /usr/tandem/webserver/atp/bin/atp.pway -> /usr/tandem/webserver/bin
ln -s /usr/tandem/webserver/atp/bin/atpd.pway -> /usr/tandem/webserver/bin
Preparing ATP/XML sample files. Please wait…
Would you like to install the XML sample database? ([y]/n):
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -5
Installing and Running ATP
Add-On Package Installation
9. Press Enter to install the XML for ATP add-on sample database.
The Setup program is going to create a database for the ATP/XML
sample application. The default volume is $DATA00.
You will be prompted to enter a Guardian subvolume name.
Enter a Guardian subvolume name (up to 8 chars) Default = ZATPXML :
10. Press Enter to use the default Guardian subvolume, or type in an alternative
Guardian subvolume name.
creating ATP XML/DB sample database ...
Active Transaction Page installation is complete.
- To use the ATP features, copy the following command
to your httpd.config file before start/restart iTP WebServer.
source /usr/tandem/webserver/conf/atp.config
- To uninstall ATP sample applications, run the following
two commands under osh after stop iTP WebServer
cd /usr/tandem/webserver/atp
./uninstall
- To remove all installed directories/files completely,
run the following command under osh
rm -rf /usr/tandem/webserver/atp
In your browser, visit http://<your_server>:<your_port>/atp/
for more information on the ATP and to look at ATP examples
11. To use the ATP features, start or restart your iTP WebServer application.
The default atp.config file is copied to where the iTP WebServer configuration
directory resides, as well.
If you have installed IEEE floating-point format and some of the CPUs in your
system do not support IEEE floating-point format, you must edit your atp.config file
to indicate which CPU the atp.pway server class should run in. See ATP
Configuration File on page 2-8 for more information.
Add-On Package Installation
The add-on component design is a new feature introduced in ATP V21. In general, an
add-on component is a top-level ATP object similar to a Java package, which groups all
related objects together. For example, the first add-on component is the XML for ATP
Add-On Module package, which contains all DOM-related objects.
The add-on package is optional to the core ATP package and is also shipped as an
independent product with its own T-number. There is no independent setup program for
add-on packages. All add-on packages require that you run the ATP core installation
program to include the packages.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -6
Installing and Running ATP
NonStop TUXEDO Connectivity Options
/usr/tandem/atp/pkgs is the default root directory for all add-on packages. The
ATP main installation program searches all immediate sub-directories of the add-on root
directory to check the possible add-on package candidates for installation.
Caution. Since the add-on package installations are automatically picked up by the ATP
installation main program, the add-on package installation will not be included if:
•
•
•
The add-on package is unpacked into an incorrect path.
The add-on package setup files, setup.ini and/or setup.tcl, are missing or moved into a
wrong directory.
The add-on package setup files, setup.ini and/or setup.tcl, are incorrectly modified.
NonStop TUXEDO Connectivity Options
The ATP installation procedure detects whether NonStop TUXEDO is present and, if so,
asks you to select the version. ATP then installs the ATP objects required for that version
of TUXEDO.
Note. If you installed IEEE floating-point format, ATP Tuxedo objects are disabled because the
current NonStop TUXEDO software cannot support IEEE floating-point format.
If NonStop TUXEDO is present, the following dialog is displayed:
Tuxedo software is installed.
Select your level of support.
(The default is 0, No Tuxedo Support.)
0)No Tuxedo->/G/system/system/atplib
1)Tuxedo Version 2 ->/G/system/system/ltuxt2
2)Tuxedo 65 ->/G/system/system/ltuxt65
Enter a number from 0 to 2 now:
Remember, if you change from one version of Tuxedo support to another, you must
change the setting of the environmental variable ATP_TUXEDO_VERSION.
Verifying the Installation
Verify the vproc of the WebServer’s /bin/atp.pway binary. There should be a set of
T0345 vprocs that match the <version> portion of the installation directory. If there
is not a match, then an installation error has occurred and must be corrected before
proceeding. Additionally, if XML for ATP was installed, there should be a
corresponding T1242 vproc displayed.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -7
Installing and Running ATP
Customizing the Configuration
Customizing the Configuration
Once the setup script has run, do not delete or modify the /atp directory located in the
WebServer's directory as there are OSS symbolic links pointing back to that directory
tree. If you do delete any of these directories or subdirectories, you will have to reinstall
the product starting with the ./setup step.
The ATP installation procedure implements a configuration suitable for running the ATP
software and example programs. To tune the configuration and support your own
applications, you might have to modify the ATP configuration file (atp.config) or
the ATP TUXEDO configuration file (atp-tuxedo.config.sample). You might
also have to create configuration files for your own applications. Include all these files in
the iTP Secure WebServer configuration file (httpd.config).
For information about modifying the configuration files to fit your own application
requirements, see ATP in the WebServer Configuration File on page 2-8.
After modifying the configuration, you must restart the iTP Secure WebServer using the
restarth script or the corresponding Administration Server command. For
information about restarting the iTP Secure WebServer, see the iTP Secure WebServer
System Administrator’s Guide.
ATP in the WebServer Configuration File
The ATP installation procedure generates configuration files that you can edit and
include in the httpd.config file for your iTP Secure WebServer environment. These
files are put in the following locations:
•
•
ATP Configuration File: /usr/tandem/webserver/atp/conf/atp.config
ATP TUXEDO Configuration File: /usr/tandem/webserver/atp/conf/atptuxedo.config.sample
•
ATP Add-On Configuration File: /usr/tandem/webserver/atp/conf/atp-add-
•
ATP Add-On Definitions File: /usr/tandem/webserver/atp/conf/atp-add-
on.config
on.def
This guide describes the versions of those files that were current when the guide was
written; the files on the CD might differ slightly. Use the following descriptions as a
guide for understanding how you might modify the files to suit your own needs.
Note. The files include comments that do not appear in this guide, and this guide includes
comments that do not appear in the files. Likewise, boldface headings appear in this
document, not in the configuration files.
ATP Configuration File
The directives described under the next several headings appear in the file called
atp.config.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -8
ATP Configuration File
Installing and Running ATP
Set Statement and Filemap Directive
The file begins with the set statement and Filemap directive. The set statement
defines the variable ATP_ROOT to be equal to the name of the directory where ATP is
installed. The Filemap directive maps the URL component /atp to the location of
the ATP examples directory, which contains the ATP home page.
set ATP_ROOT /usr/tandem/webserver/atp
Filemap /atp $ATP_ROOT/examples
MimeType and PathwayMimeMap Directives
The MimeType directive indicates that files with the extension .atp have the mime
type application/x-httpd-guardian. The corresponding PathwayMimeMap
directive indicates that files with the extension .atp are processed by the atp server
class.
MimeType application/x-httpd-guardian
PathwayMimeMap
atp atp
atp
For security reasons, you might want some scripts to be processed in a separate
PATHMON environment. If so, add lines like the following to the ATP configuration
file. In this example, files with the extension .atp_sql_query are processed by the
server class atp under control of the PATHMON process /G/DJCP:
MimeType application/x-httpd-guardian atp_sql_query
PathwayMimeMap
atp_sql_query /G/DJCP:atp
For more information about using separate PATHMON environments, see The
.atp_sql_query Filename Extension on page A-2.
Server Directive
The Server directive defines the atp server class, which is named atp.pway in this
example. You could define multiple atp server classes. The left brace introduces the
subcommands for this Server directive.
Server /usr/tandem/webserver/atp/bin/atp.pway {
Environment Variables
The Env subcommands of the Server directive specify ATP environment variables.
For descriptions of these and other ATP environment variables, see ATP Environment
Variables on page 2-12.
Env
Env
Env
Env
SQL_STATEMENT_CACHE_SIZE=50
ATP_PAGE_CACHE_SIZE=0
TUXEDO_FTBL_CACHE_SIZE=0
ATP_TUXEDO_VERSION = 0
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2 -9
ATP Configuration File
Installing and Running ATP
Map Defines
The MapDefine subcommands of the Server directive specify the locations of
processes and database tables used in the sample applications. Add to this list to include
map defines for tables and views used in your own applications or for additional
PATHMON processes. ATP creates an implicit define called
=TANDEM_PATHMON_NAME, which refers to the PATHMON environment where this
atp server class is defined. This define is derived from an iTP Secure WebServer
environment variable also called TANDEM_PATHMON_NAME. If you choose to define a
separate PATHMON environment for any application, the map define that specifies the
PATHMON process name must be consistent with the makefile for that application.
The following map defines specify the locations of DDL dictionaries. The volume and
subvolume names depend on what you specified during installation.
MapDefine =atp_EM_DDL
MapDefine =atp_FU_ddl
MapDefine =atp_HM_ddl
/G/data02/ZATPEM/dictddf
/G/data02/ZATPFU/dictddf
/G/data02/ZATPHM/dictddf
The following map defines specify the locations of SQL tables:
MapDefine
MapDefine
MapDefine
MapDefine
MapDefine
MapDefine
MapDefine
=cust
=tran
=account
=access
=userid
=acl
=bankapp-account
/G/DATA02/ZATPHM/cust
/G/DATA02/ZATPHM/tran
/G/DATA02/ZATPHM/account
/G/DATA02/ZATPHM/access
/G/DATA02/ZATPHM/userid
/G/DATA02/ZATPHM/acl
/G/DATA02/ZATPHM/account
The following map define is for the NonStop TUXEDO bankapp application. Remove
the comment character (#) if you are running NonStop TUXEDO.
#MapDefine =bankapp-account
/G/YOUR_VOLUME/YOUR_SUBVOLUME/account
Maxlinks, Maxservers, and Numstatic Parameters
The following parameters specify the number of concurrent links to a server in the atp
server class (Maxlinks), the maximum number of servers in the class
(Maxservers), and the number of static servers in the class (Numstatic). Each atp
process is single threaded, so the value of Maxlinks must remain 1. In a production
environment, a large value of Numstatic will provide better performance than the
value given here; ideally, the value of Numstatic should be equal to the average
number of concurrent requests to the atp server class.
Maxlinks
1
Maxservers 20
Numstatic
4 }
Source Statements
The atp.config file checks for the presence of configuration files for NonStop
TUXEDO and the example applications. If a configuration file is present, it is included
in atp.config.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 10
ATP TUXEDO Configuration File
Installing and Running ATP
ATP TUXEDO Configuration File
The directives described under the next several headings appear in the file called atptuxedo.config.samples. Modify this file to reflect your NonStop TUXEDO
configuration; then rename or copy the file to /conf/atp-tuxedo.config.
The following lines specify NonStop TUXEDO variables that apply to all the ATP
sample programs. (The Region directive specifies the tuxedo* directory and, within
it, all files with the extension .atp.) For definitions of these environment variables, see
the NonStop Tuxedo manual set or the TPINIT man page.
Note. The TUXCONFIG environment variable is case-sensitive even when pointing to a
Guardian file name.
Region /atp/tuxedo*.atp {
AddCGI TUXEDO_TPINIT_USRNAME
AddCGI TUXEDO_TPINIT_CLTNAME
AddCGI TUXEDO_TPINIT_PASSWD
# AddCGI TUXEDO_TPINIT_GRPNAME
AddCGI TUXEDO_TPINIT_DATA
AddCGI TUXDIR /tuxedoD46
User
Client
Password
BANKB1
Data
The following lines specify NonStop TUXEDO variables that apply to the sample
banking application. For definitions of these environment variables, see the NonStop
TUXEDO manual set. Change the pathnames to match your configuration.
AddCGI TUXCONFIG
AddCGI FLDTBLDIR
AddCGI FIELDTBLS
/G/DATA02/DJCBACF/TUXCFG
/tuxedoD46/udataobj:/home/your_name/bankapp
Usysflds,bank.flds
Note that if you have selected Tuxedo 6.5 support, change the last line shown above:
From this
AddCGI FIELDTBLS Usysflds,bank.flds
To this
AddCGI FIELDTBLS Usysflds,bankflds
In other words, remove the period.
The following lines apply only to /WS connections. Remove the comment character (#)
and modify the values if appropriate to your configuration:
# AddCGI WSNADDR=0x0002961882fc03de
# AddCGI WSTYPE=NONSTOPKERNEL
}
ATP Add-On Configuration File
This file should not be modified.
ATP Add-On Definitions File
This file should not be modified.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 11
Installing and Running ATP
ATP Environment Variables
ATP Environment Variables
You can specify any of the following ATP environment variables in your configuration
file:
ATP_COMPILED_PAGE_CACHE_SIZE
Use this variable to specify the maximum entries allowed in the cache where
atp.pway stores the compiled pages. ATP will not check the time stamp of a page
in the cache until the cache is full. Once the cache is full and a new page comes in,
atp.pway will check the time stamp and replace the least recently used (LRU) page
with the new page.
A larger number of entries means more memory may be consumed by the page
cache; a smaller number means the server must check the file’s time stamp and swap
the files more frequently once the cache becomes full. Therefore the best value
depends on system memory size and the total number and size of the application’s
pages.
ATP_COMPILED_PAGE_CACHE_SIZE accepts a value from 1 to 1024. The
minimum value (1) causes checking and swapping to be performed every time a new
page comes in. Although the maximum size is 1024, the runtime maximum size may
be smaller if the application has large source files in the cache.
If this environment variable is not used, a default value of 23 entries will be used.
ATP_PAGE_CACHE_SIZE
Use this variable to configure a web-page cache within atp.pway to improve
performance in situations where web pages are not changing very frequently. Pages
are retained in a local cache in parsed format. The value signifies a number of web
pages (the number of .atp pages to be retained in cache). ATP will not consult the
disk version of a page until the cache becomes full, or until the atp.pway process
has stopped or received a signal defined by the variable
ATP_PAGE_CACHE_SIGNAL.
The minimum value of ATP_PAGE_CACHE_SIZE is 0; the maximum value is
1024. The minimum value, 0, will disable the context cache mechanism and will
cause expensive construct and destruct operations for each request. The default value
for ATP_PAGE_CACHE_SIZE is 20.
To determine the best value of ATP_PAGE_CACHE_SIZE for your needs, use a value
slightly greater than the number of frequently used root pages in your application.
(Do not count server-side includes, just the pages that call the includes.)
ATP_RESTART_PAGE
Use this variable to refresh a cached page after the page is accessed a specified
number of times. The default value is 50, which means that a page will be accessed
50 times before it is refreshed. A value of 0 means that the page will never be
refreshed.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 12
Installing and Running ATP
ATP Environment Variables
ATP_COMPILE
This variable is obsolete because ATP V20 and ATP V21 always have the cache for
compiled pages.
If you have configured a web-page cache, you can further improve performance by
having the script pseudo-code retained in the cache. In this case, ATP need not
compile the script each time that the web page is used. Compiled pseudo-code
retention can make a noticeable difference in performance.
Note. If you choose this option, ensure that the web page does not preserve context that
could result in errors on repeated invocation. For example, ensure that the web page
initializes its variables, closes SQL cursors, and commits or rolls back transactions as
appropriate
Set the ATP_COMPILE environment variable either globally, by specifying Env
ATP_COMPILE=1 for the atp.pway server class, or locally (for a set of
directories) by specifying AddCGI ATP_COMPILE 1 in a Region command. At
the individual page level, use <meta compile="on"> anywhere before the
</head> tag. The permissible values of this variable are 0 or 1, ON or OFF.
ATP_PAGE_CACHE_SIGNAL
This variable is obsolete because the ATP V20 and ATP V21 versions of atp.pway
check the time stamp to recompile the source files on demand.
ATP_SCRIPT_STACKSIZE
Include this variable in the Env directive to specify the chunk size in which the
script interpreter stack is allocated. The default value is 32000. Increase the value
only if your application runs out of memory; the maximum value is 96 megabytes
(your system maximum memory may be lower than this value).
ATP_SCRIPT_RUNTIME_SIZE
Include this variable in the Env directive to specify the memory size of the heap
used by script interpreter. The default value is 1000000. Increase the value only if
your application runs out of memory; the maximum value is 96 megabytes (your
system maximum memory may be lower than this value).
SQL_STATEMENT_CACHE_SIZE
If you plan to use JavaScript objects for access to NonStop SQL, use this
environment variable to increase the size of the SQL statement cache. The default
value is 50 statements. The minimum value is 20.
A large SQL statement cache could cause the atp.pway process to run out of PFS
space because of the number of open SQL tables. You can use nld to increase the
amount of PFS space. A guideline for setting the SQL statement cache size is to add
some slack to the greater of
•
•
The maximum number of SQL statements on any one web page
The aggregate number of SQL statements on the most frequently used pages
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 13
Installing and Running ATP
Running ATP
TUXEDO_FTBL_CACHE_SIZE
Use this variable to configure an FML Field Table cache within atp.pway to
improve performance for web pages that use FML buffers for access to NonStop
TUXEDO servers. The field tables are retained in a local cache in semi-compiled
format. The value indicates the number of field tables retained in cache. ATP does
not consult the disk version of a field table until the cache becomes full, the server
class has been stopped, or a server process receives a signal defined by
ATP_PAGE_CACHE_SIGNAL.
ATP_TUXEDO_VERSION = number
Use this variable to select the level of TUXEDO support. The version numbers are:
•
•
•
0 - Do not use TUXEDO objects (this is the default)
2 - Use NonStop TUXEDO Release 2
65 - Use NonStop TUXEDO Release 6.5
Running ATP
When you start or restart the iTP Secure WebServer after installing ATP, the atp.pway
server class starts automatically. For access to the ATP sample programs and
development tools, load the ATP home page from
$ATP_ROOT/examples/index.html.
Uninstalling ATP
To uninstall the previously installed sample database, including all add-on packages,
enter the following commands:
1. Go to the location where ATP is installed by issuing the following OSS command
(the following is the default location, but your files might be elsewhere):
cd /usr/tandem/webserver/atp/
2. Type:
./uninstall
Your system uninstalls ATP and responds with the following information:
cd /usr/tandem/webserver/atp/examples/pathway/employee
clean pathway employee samples ...
...
cd /usr/tandem/webserver/atp/examples/pathway/file_upload/Application
clean pathway file_upload samples ...
...
cd /usr/tandem/webserver/atp/examples/pathway/homebank/Application
clean pathway homebank samples ...
...
purging ATP XML/DB sample database ...
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 14
Installing and Running ATP
Uninstall Cleanup Steps
Uninstall Cleanup Steps
The default installation of iTP ATP V21 may optionally create various database files for
the examples. The uninstall process, described above, will delete those files. After
uninstalling ATP, perform the following cleanup steps:
1. Delete the WebServer’s /atp directory
(for example, rm -rf /usr/tandem/webserver/atp)
2. Delete the atp.config file from the /conf directory and remove any reference
to it in the httpd.config file.
3. Remove the /usr/tandem/atp/<version> and
/usr/tandem/atp/pkgs/<version> directories by entering the following
commands:
OSS:
OSS:
OSS:
OSS:
cd
rm
cd
rm
/usr/tandem/atp
-rf <atp version>
/pkgs
-rf <xml version>
Note. Removal of these directories will require any future installations of these versions to
start with the COPYOSS and/or IPSetup steps.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 15
Installing and Running ATP
Uninstall Cleanup Steps
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
2- 16
3
ATP Web Page and Script Structure
This section describes the syntax for delimiting server-side JavaScript on a web page
and explains the structure of several sample scripts.
This section includes the following subsections:
•
•
•
•
•
Web Page Structure on page 3-1
Web Page Processing on page 3-2
Meta Tag Used for MultiByte Support on page 3-2
Script and HTML on page 3-3
Server-Side Script Structure on page 3-4
Web Page Structure
ATP recognizes server-side HTML markup tags that follow Netscape LiveWire
conventions, so you can use Web authoring tools that support those specific server-side
tags.
A page that includes server-side JavaScript must have the extension .atp. To mark the
boundaries of a server-side script, use any of the following tags:
•
•
<server></server>
<% %>
This option supports migration of Microsoft Active Server Pages (ASP). You also
can use the % delimiter to print out the value of a variable as follows:
<%=variable %>
•
` (backquote)
This option lets you embed a script in another tag, such as
<ahref="`bit of script`">
You can use the <server></server> syntax within a tag, but backquotes are
more readable. Backquotes that appear within server tags are ignored.
•
•
\Q (escaped backquote)
<script language=atpScript></script>
This option lets you use web authoring environments, such as Microsoft FrontPage,
which do not recognize the other script boundary declarations shown above.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -1
ATP Web Page and Script Structure
Web Page Processing
Server-side includes also follow Netscape conventions. For example:
* <!-- #include file="shared-script-functions.inc" -->
Script is not permitted within a meta tag (such as <meta http-equiv=”contenttype” content=text/html>) or in an #include statement. Otherwise,
fragments of script can appear anywhere, for example to define a file extension
dynamically or to modify the behavior of a client-side script.
Recursive includes are not checked, but are not allowed. The system loops until it
runs out of resources.
Include file is the only include tag supported by ATP.
Web Page Processing
ATP processes a page as follows:
1. Saves meta-tags.
2. Expands server-side includes.
3. Distinguishes active content (server-side scripts) from passive content (to be passed
unaltered to the Web browser).
4. Executes server-side scripts. Script output appears in the location occupied by the
script in the original .atp page. The script is effectively replaced by its output,
which can consist of nothing or any number of lines of output data obtained from
application servers.
The browser parses and presents the resulting stream of HTML, text, and possibly
client-side JavaScript.
Note. ATP does not provide a way to change HTTP headers dynamically in a script. To
change a header, use an HTML meta tag. For example, to generate plain text output, you
could use the following statement:
<META HTTP-EQUIV=”content-Type” CONTENT=”text/plain”>
Meta Tag Used for MultiByte Support
A new meta tag is now available to override the value of the
ATP_DISABLE_BACKQUOTE variable (for the pages that contain this meta tag). Your
application may have multiple backquote meta tags to enable or disable backquotes on
different sections of the same page.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -2
ATP Web Page and Script Structure
Script and HTML
Script and HTML
You can include HTML within a server-side script, or script within HTML, depending
on the proportions of each that your application requires. ATP regards any HTML in the
clear as passive content of the page and passes it directly to the browser for processing.
Your script need not—and should not, for reasons of efficiency—explicitly print lines of
HTML to the browser: ATP passes multiple lines of HTML in a single operation.
The code fragment in Example 3-1 illustrates a combination of server-side script and
HTML in the clear, with server-side JavaScript and its delimiters highlighted. Wherever
one or more lines of HTML appear in the clear—for instance, before the first
<server> tag or between the </server> tag and the first backquote (‘)— ATP
passes the lines in a single print operation to the browser. (In this example, all the
HTML between the do and while statements is passed to the browser repeatedly,
once for each execution of the loop.) For expressions like ‘account_id()‘, which
refer to functions that return table data from ATP objects, ATP evaluates the expression
and passes the value to the browser at the location where the expression occurred in the
HTML.
Example 3-1. Server-Side Script and HTML
<table border=3 cellpadding=3 cellspacing=3>
...
<!--HTML to print the column headings (omitted here)-->
...
<server>
do {
</server>
<tr>
<!-- The from radio button...-->
<td align=center>
<input type=radio name=FromAccount value=‘account_id();‘>
</td>
<!-- The data about the account...-->
<td align=center> ‘last_name();‘ </td>
<td align=center> ‘first_name();‘ </td>
<td align=center> ‘account_id();‘ </td>
<td align=center> ‘balance();‘ </td>
<!-- The to radio button...-->
<td align=center>
<input type=radio name=ToAccount value=‘account_id();‘>
</td>
</tr>
<server>
}
while (nextAcct() && rowCount++ <10);
</server>
...
</table>
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -3
ATP Web Page and Script Structure
Server-Side Script Structure
Server-Side Script Structure
The best way to familiarize yourself with ATP script structure and programming
techniques is to study the many example scripts in the ATP examples directory. This
section describes the structure of one example script for each major type of application
with which ATP pages can communicate:
•
•
•
•
NonStop SQL
NonStop TS/MP (formerly Pathway)
NonStop TUXEDO
Sockets (TCP/IP)
Some of these examples also illustrate the use of NonStop TM/MP (formerly TMF).
For a list of examples that demonstrate particular programming tasks, see Table 6-1,
Examples by Programming Task, on page F-2. For a list of example functions that you
can copy and adapt to your own needs, see Table 6-2, Functions Defined in ATP
Examples, on page F-4.
Using NonStop SQL from JavaScript
The directories called sql and sql_tools within the ATP examples directory
contain many examples that illustrate SQL script structure. One such example is the file
/examples/sql/homebank/Webpages/address.atp. The script enables a
user to change the name or address of a homebanking customer.
Selections from the file address.atp are displayed with accompanying text below. Print
that file or display it on screen if you need to see the complete code.
Definitions and Includes
The script (/examples/sql/homebank/Webpages/address.atp) begins
with definitions of functions that validate components of a customer name and address.
They are in client-side JavaScript because there is no reason for input-validation
functions to occur on the server. (See Example 3-2 on page 3-5.)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -4
ATP Web Page and Script Structure
Using NonStop SQL from JavaScript
Example 3-2. NonStop SQL Definitions and Includes
<!DOCTYPE HTML PUBLIC "-//SoftQuad//DTD HTML 3.2 + extensions
for HoTMetaL PRO
3.0(U) 19961211//EN" "hmpro3.dtd">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html">
<TITLE>Name and Address Change</TITLE>
<!--------------------------------------------------------->
<script language="JavaScript">
//Client side validation script functions (it's all JavaScript!)
function ValidateLastName (t) {
if (t.value=="") {
alert ("Please enter Last Name")
return false
}
return true
}
function ValidateFirstName (t) {
if (t.value=="") {
alert ("Please enter First Name")
return false
}
return true
}
In Example 3-3 on page 3-6, the body of the script begins by including several files that
define required functions. The tag <SERVER> shows where the server-side JavaScript
begins. The script checks security each time the page is loaded because the execution of
any script is context free: ATP does not implement the concept of a session.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -5
ATP Web Page and Script Structure
Using NonStop SQL from JavaScript
Example 3-3. NonStop SQL Includes and Server-Side JavaScript
</script>
<!--------------------------------------------------------->
</HEAD>
<BODY>
<!--#include file="util_server.inc"-->
<!--#include file="send_to_server.inc"-->
<!--#include file="access_check.inc"-->
<!--------------------------------------------------------->
<SERVER>
// Check why this page is being loaded (the page invokes
// itself to do transactions)
var ServiceName;
if (atp.request.REQUEST_METHOD=="POST")
// page is being loaded because user submitted a transaction
ServiceName = "addresschangeaccept";
else
ServiceName = "addresschangedisplay"
//
//
Check security and get back the userid (in
'globalAccessUserid')....
Accepting the Request from the Browser
To identify the kind of request received from the browser, the script
(/examples/sql/homebank/Webpages/address.atp) examines the
atp.request object. Specifically, the script tests the REQUEST_METHOD
environment variable, which is a property of the atp.request object. The value
POST indicates that the user submitted a form. In this case, POST signifies that the user
requested a transaction. (Alternatively, a script could recognize a transaction by
detecting that a specific button was pressed.)
The general structure of the script depends on the request method:
•
•
If this is a GET operation, get the current data, then print it.
If this is a POST operation, update the database, get the current (updated) data, and
then print it.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -6
ATP Web Page and Script Structure
Using NonStop SQL from JavaScript
Performing the Requested Transaction
To implement an SQL statement, the script
(/examples/sql/homebank/Webpages/address.atp) must first create an
instance of the atp.SQL object. In creating the object, the script specifies the SQL
statement type, but the constructor (the call to create the object) does not implicitly
execute the statement.
Before using the execute method, the script creates an atp.transaction object
so the database update will be protected by NonStop TM/MP. (The
atp.transaction object could have been created before the SQL object; it must be
created before the script invokes the execute method. The transaction doesn’t begin
until the script supplies the atp.transaction object as a parameter to a method, in
this case the execute method.)
After the execute method call, the script checks the SQL error code, using the
sqlcode property of the atp.SQL object. According to the error code, the script
either commits or rolls back the transaction, using the commit or rollback method
of the atp.transaction object, and displays a message to the user, indicating the
outcome of the transaction.
ATP example scripts follow the convention of displaying error messages at the top of the
screen.
Example 3-4. Implementing a NonStop SQL Statement
// If we're in "POST" mode, process the transaction request...
if (atp.request.REQUEST_METHOD=="POST") {
var tdict=new atp.dictionary("=atp_HM_ddl","cust_update_request",
"cust_update_reply", "reply_header");
var treqBuf= new atp.buffer("c");
with (tdict.element.cust_update_request) {
// Set up the update request buffer ....
treqBuf.setData("addresschangeaccept",
request_header.service_name);
treqBuf.setData(globalAccessUserid,
cust_record.custid);
treqBuf.setData(atp.request.LastName,
cust_record.last_name);
treqBuf.setData(atp.request.FirstName,
cust_record.first_name);
treqBuf.setData(atp.request.AddressLine1, cust_record.address_line_1);
treqBuf.setData(atp.request.AddressLine2, cust_record.address_line_2);
treqBuf.setData(atp.request.AddressCity , cust_record.address_city);
treqBuf.setData(atp.request.AddressState, cust_record.address_state);
treqBuf.setData(atp.request.AddressZip , cust_record.address_zip);
treqBuf.setData(atp.request.RowVersion , cust_record.row_version);
} // end of 'with' scope
// Do the update transaction ...
sendToServer ("=tandem_pathmon_name", "atp-customer", treqBuf,
tdict.element.reply_header);
trepBuf = treqBuf.reply;
// There could be a warning message...
var userMsg=
trepBuf.getData(tdict.element.cust_update_reply.reply_header.message);
if (userMsg.length == 0)
userMsg = "Customer record updated.";
print ('<strong><i>'+userMsg+'</i></strong>');
} // End of special POST method processing
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -7
ATP Web Page and Script Structure
Using Pathway TS/MP Servers from JavaScript
Displaying the Results
To display the results of the previous transaction, the script
(/examples/sql/homebank/Webpages/address.atp) reads the data back
from the cache. (Another implementation option would be to echo the new data from the
request, but reading the data back from the cache is easier to code and confirms that the
update took place.) To read the data, the script creates another instance of the atp.SQL
object. This time the SQL statement type is SELECT.
To execute the SELECT statement, the script first invokes the execute method to
establish the cursor. Then it invokes the next method to read the row. (For a SELECT
statement, the execute method does not automatically read the row.) No transaction
object was required because reading is an operation that can be safely repeated.
The script checks the error code, using the sqlcode property of the atp.SQL object,
and prints a message if appropriate.
The </SERVER> tag shows where a block of server-side JavaScript ends. A script can
include multiple blocks of server-side JavaScript, each delimited by <server>
</server> tags. It can also contain fragments of server-side JavaScript in
backquotes. To display the form, the script uses data from the atp.SQL object created
for the SELECT statement. (The column_values property of the atp.SQL object
is an array of values representing the contents of a row.)
Using Pathway TS/MP Servers from JavaScript
The directories called pathway and pathway_tools within the ATP examples
directory contains many examples that illustrate Pathway script structure. The file
/examples/pathway/homebank/Webpages/address.atp is functionally
the same as the SQL example described above but uses a different set of objects to send
a request to a server class.
Print the file or display it on the screen and refer to it as you read the next few
paragraphs.
Also print or display the file
examples/pathway/homebank/Webpages/send_to_server.inc, which
the address.atp script uses as an include file.
For detailed information about objects and methods used for access to NonStop TS/MP,
see Section 4, ATP Objects, Properties, and Methods.
Definitions and Includes
The script begins with definitions of functions that validate components of a customer
name and address. They are in client-side JavaScript because there is no reason for
input-validation functions to occur on the server.
The body of the script begins by including several files that define required functions.
The tag <SERVER> shows where the server-side JavaScript begins.
The script checks security each time the page is loaded because the execution of a script
is context free: ATP does not implement the concept of a session.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -8
ATP Web Page and Script Structure
Using Pathway TS/MP Servers from JavaScript
Accepting the Request from the Browser
To identify the kind of request received from the browser, the script
(/examples/pathway/homebank/Webpages/address.atp) examines the
atp.request object. Specifically, it tests the REQUEST_METHOD environment
variable, which is a property of the atp.request object. A value of POST indicates
that the user submitted a transaction.
So far this example is like the SQL example.
Performing the Requested Transaction
To send a request to a server class, the script
(/examples/pathway/homebank/Webpages/address.atp) creates an
instance of the atp.dictionary object. This object represents a Data Definition
Language (DDL) dictionary that defines the message layouts meaningful to the server
class. (Alternatively, a script author could use output from the dview tool, which
allows passive use of the DDL dictionary.)
Next the script creates an atp.buffer object to hold the request and later the reply.
The setData method fills the buffer, using data from the request as represented by the
atp.request object. To place values in multiple fields, a script must invoke the
setData method once for each field; for example, a script could use a loop to fill rows
of a table.
To update the database, the script calls the send_to_server function, which
1. Creates an atp.transaction object to protect the database update.
2. Uses the send method of the atp.buffer object to send the buffer to the server
class specified in the function call.
3. Checks the Pathsend error code, stored in the error property of the atp.buffer
object.
4. Commits or rolls back the transaction, using methods of the atp.transaction
object.
The reply to the request is in the reply property of the atp.buffer object. The
reply property is itself a buffer object, named replyBuf in this example. To extract
the fields from the reply, the send_to_server function uses the
atp.dictionary object, which defined the message formats, and the getData
method applied to the atp.buffer object replyBuf.
Upon return from send_to_server, the script checks for a message in the reply
buffer and prints the message if there is one.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3 -9
ATP Web Page and Script Structure
Using NonStop TUXEDO Servers from JavaScript
Displaying the Results
As in the NonStop SQL example, to display the results of the previous transaction, the
script (/examples/pathway/homebank/Webpages/address.atp)
implements a read operation. In this case, the script creates new atp.dictionary
and atp.buffer objects and calls the send_to_server function to send the new
buffer. Upon return from send_to_server, the script checks for a message in the
reply buffer and prints the message if there is one.
To display the form containing the results, the script uses the getData method applied
to the reply buffer object (which is the reply property of the request buffer object).
Using NonStop TUXEDO Servers from JavaScript
The directories called tuxedo and tuxedo_tools within the ATP examples
directory contains many examples that illustrate TUXEDO script structure. The file
/examples/tuxedo/bankapp/transfer.atp shows two external data sources
being used from the same web page:
•
•
An SQL object accesses a NonStop SQL database to display a form that represents
the first few accounts from the bankapp ACCOUNT table. (bankapp is a
standard NonStop TUXEDO sample application.)
NonStop TUXEDO objects transfer money between any two selected accounts.
Selections from the file transfer.atp are displayed with accompanying text below. Print
that file or display it on screen if you need to see the complete code.
For detailed descriptions of objects and methods used for access to NonStop TUXEDO,
see Section 4, ATP Objects, Properties, and Methods.
Definitions and Includes
The script in Example 3-5 begins with definitions of functions that validate information
about customer accounts. These functions are in client-side JavaScript because there is
no reason for input-validation functions to occur on the server.
The body of the script begins by including several files that define required functions.
The tag <SERVER> (see NonStop TUXEDO Server-Side Functions on page 3-13)
shows where the server-side JavaScript begins.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 10
ATP Web Page and Script Structure
Using NonStop TUXEDO Servers from JavaScript
Example 3-5. NonStop TUXEDO Definitions and Includes (page 1 of 2)
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html">
<TITLE>bankapp Transfer Transaction - NonStop SQL and NonStop
TUXEDO</TITLE>
<!---------------------------------------------------------->
<script language="JavaScript">
//-C L I E N T
S I D E
V A L I D A T I O N
S C R I P T S-
var FromIndex = 0
var ToIndex = 0
function ValidateFromAccount (r) {
var i
for (i=0; i<r.length; i++)
if (r[i].checked) {
FromIndex = i
return true
}
alert ("From account must be selected")
return false
}
function ValidateToAccount (r) {
var i
for (i=0; i<r.length; i++)
if (r[i].checked) {
ToIndex = i
return true
}
alert ("To account must be selected")
return false
}
function ValidateTransferAmount (t) {
if (parent.isMoney(t.value) == false) {
alert
("Amount must be a number with up to 2 decimal places and no commas")
return false
}
if (parseFloat(t.value) == 0.0) {
alert ("Amount must be non-zero")
return false
}
return true
}
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 11
ATP Web Page and Script Structure
Using NonStop TUXEDO Servers from JavaScript
Example 3-5. NonStop TUXEDO Definitions and Includes (page 2 of 2)
function ValidateTransferForm (f) {
if (ValidateFromAccount
(f.FromAccount) &&
ValidateToAccount
(f.ToAccount) &&
ValidateTransferAmount (f.Amount))
if (FromIndex != ToIndex)
return true
else
alert ("From and To accounts must be different")
alert ("Form not submitted")
return false
}
</script>
</head>
<body>
Server-Side Functions
Example 3-6 (/examples/tuxedo/bankapp/transfer.atp) defines a
function called doTransfer to communicate with the NonStop TUXEDO
environment, just as the Pathway example defines the send_to_server function to
communicate with the Pathway servers. However, this example includes the function in
the web page, whereas the Pathway example uses an include file. Whether to define
the function in the page or in an include file is a matter of programming style. In
general, an include file is easier to incorporate into multiple applications and enforces
encapsulation: the web page designer need not be concerned with how the function is
implemented, only with how to call it. However, defining the function on the page has
the advantage of making the flow of operations easier to study.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 12
Using NonStop TUXEDO Servers from JavaScript
ATP Web Page and Script Structure
Example 3-6. NonStop TUXEDO Server-Side Functions
<server>
//--- T U X E D O
T R A N S F E R
// --------------- U P D A T E
T R A N S A C T I O N ---
F U N C T I O N
-------------
function doTransfer (from_acct, to_acct, amount)
{
var ftbl = new atp.fml_table('bank.flds');
var fbfr = new atp.fml_buffer('fml');
fbfr.setData (from_acct, ftbl.ACCOUNT_ID, 0);
fbfr.setData (to_acct,
ftbl.ACCOUNT_ID, 1);
fbfr.setData (amount,
ftbl.SAMOUNT);
var tran = new atp.transaction ();
if (!fbfr.tpcall('TRANSFER', tran)) {
tran.rollback();
if (fbfr.error != 0)
return ('tpcall TRANSFER failed: ' + fbfr.error_text);
return (fbfr.reply.getData(ftbl.STATLIN));
}
tran.commit ();
return ('Debit Account Balance: ' + fbfr.reply.getData(ftbl.SBALANCE) +
' ; Credit Account Balance: ' + fbfr.reply.getData(ftbl.SBALANCE, 1)
);
}
For more information about doTransfer, see Performing the Requested Transaction
on page 3-13.
Accepting the Request from the Browser
To identify the kind of request received from the browser, the script
(/examples/tuxedo/bankapp/transfer.atp) examines the atp.request
object. Specifically, the script tests the REQUEST_METHOD environment variable,
which is a property of the atp.request object. A value of POST indicates that the
user submitted a transaction.
Performing the Requested Transaction
To perform the transaction, the script
(/examples/tuxedo/bankapp/transfer.atp) uses the doTransfer
function, which performs the following processing:
1. Creates a new atp.fml_table object to represent the field table. The parameter
specifies the file that contains the table.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 13
ATP Web Page and Script Structure
Using NonStop TUXEDO Servers from JavaScript
2. Creates a new atp.fml_buffer object to represent the message to send to the
NonStop TUXEDO server.
3. Uses the setData method of the atp.fml_buffer object to fill the buffer with
data supplied by the function caller. The data comes from fields in the
atp.request object, as you see in the function call. To fill multiple fields, a
script must invoke the setData method once for each field.
4. Creates a new atp.transaction object to protect the transaction. (The
transaction object could have been created before the FML table and buffer objects.)
5. Invokes the tpcall method on the buffer object, specifying the required TUXEDO
service and the transaction object. (The transaction begins at this time.)
6. Rolls back the transaction and returns an error in the case of a failure. The error
property of the buffer object identifies the error from the NonStop TUXEDO call,
and the error_text property describes the error. STATLIN is a standard error
message defined by NonStop TUXEDO.
7. Commits the transaction and returns the resulting account balances if the request
was successful. The script uses the getData method to extract the two new
balances from the reply property of the atp.fml_buffer object. The reply
property is itself an atp.fml_buffer object, created automatically by the
tpcall method. The parameters supplied to getData identify a field from the
atp.fml_table object and an optional subscript.
Upon return from the doTransfer function, the script prints a message if the function
returned an error.
Displaying Results
To display the results, the script
(/examples/tuxedo/bankapp/transfer.atp) reads the new data from the
cache, using an atp.SQL object and methods. The script uses the global function
atp.formatMoney to format the account balance for presentation.
The script in Example 3-7 displays the new data on an HTML form, using server-side
JavaScript to implement the loop that prints the table data:
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 14
ATP Web Page and Script Structure
Using TCP/IP Sockets from JavaScript
Example 3-7. Display of HTML Data for NonStop TUXEDO
<server>
do {
</server>
<tr>
...
...
...
</tr>
<server>
}
while (nextAcct() ...;
</server>
Using TCP/IP Sockets from JavaScript
The directory called sockets within the ATP examples directory contains several
examples that show sockets script structure. The file
/examples/sockets/sendmail.atp shows how to use the ATP sockets
interface to send an electronic-mail message using the Simple Mail Transfer Protocol
(SMTP).
Selections from the file sendmail.atp are displayed with accompanying text below. Print
that file or display it on screen if you need to see the complete code.
The example script in Example 3-8 contains only enough HTML to permit invocation
from a browser. No HTML would be needed to run the script in an OSS shell
environment.
Example 3-8. TCP/IP Sockets Script Structure
<head>
<title>Using SMTP With Server-Side JavaScript Sockets</title>
</head>
<body>
<h3>Using SMTP With Server-Side JavaScript Sockets</h3>
<server>
The code starts with error handling in Example 3-9.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 15
ATP Web Page and Script Structure
Using TCP/IP Sockets from JavaScript
Example 3-9. Code for TCP/IP Sockets Script - Error Handling
// Report socket related errors .....
function handleErrors (sock, comment) {
if (sock.error != 0) {
atp.print ('TCP/IP socket error: ',comment,' - ',
sock.error, ' ', sock.error_text, '\n');
sock.close();
atp.quit (1);
}
}
// Report SMTP related errors .....
function handleReply (sock, comment, alsoGood) {
var str, buf;
var eol;
var chr;
var rc=0;
buf = '';
eol = '';
chr = '';
sock.setSoTimeout(3000);
while (true) {
chr = sock.read(1);
// atp.print ('char='+chr+';error='+sock.error+'\n');
if (chr == null)
break;
handleErrors (sock, comment);
sock.setSoTimeout(30);
buf += chr;
}
if (buf.length == 0)
return 0;
// atp.print ("\n<br>"+buf+"\n");
while (true) {
rc = parseInt (buf);
if ((rc >= 200 && rc < 300) ||
(handleReply.arguments.length==3 && rc==alsoGood))
;
else {
atp.print ('SMTP error: ',comment,' - ', buf, '\n');
sock.close();
atp.quit (1);
}
eol = buf.indexOf ('\n');
if (eol == -1)
break;
buf = buf.substring(eol+1,buf.length);
if (buf.length == 0)
break;
}
return rc;
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 16
ATP Web Page and Script Structure
Using TCP/IP Sockets from JavaScript
The script in Example 3-10 consists of a call to a function called sendMail, which in
turn calls other functions defined earlier in the script. The order of operations is typical
for a sockets application:
Example 3-10. Code for TCP/IP Sockets Script - Function Call
// Send a mail message ...
function sendmail (smtphost, from, fromHost, to, toHost, subject,
message) {
var rc;
// Create a socket connection .....
var s=new atp.socket (smtphost, 25);
handleErrors (s, 'constructor');
// Get started ....
s.write ("HELLO " + fromHost + "\n");
handleErrors (s, 'HELLO write');
rc = handleReply (s, 'HELLO reply');
// Write the sender ....
s.write ("MAIL FROM: " + from + '@' + fromHost+ "\n");
handleErrors (s, 'MAIL FROM write');
rc = handleReply (s, 'MAIL FROM reply');
// Write the recipient ....
s.write ("RCPT TO: " + to + '@' + toHost+ "\n");
handleErrors (s, 'RCPT TO write');
rc = handleReply (s, 'RCPT TO reply');
// Write the data header ...
s.write ("DATA\n");
handleErrors (s, 'DATA write');
rc = handleReply (s, 'DATA reply', 354);
//
Write the subject ....
s.write ("SUBJECT: " + subject + "\n");
handleErrors (s, 'SUBJECT write');
// Write the message body ...
if (message.indexOf('\n',message.length-1) == message.length-1)
message += '.\n';
else
message += '\n.\n';
s.write (message);
handleErrors (s, 'message body write');
rc = handleReply (s, 'message body reply');
// Finish off ...
s.write ("QUIT\n");
handleErrors (s, 'QUIT write');
rc = handleReply (s, 'QUIT reply');
// Close the TCP/IP socket
s.close ();
atp.print ('<br>Message sent.<br>\n');
return;
}
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 17
ATP Web Page and Script Structure
Using TCP/IP Sockets from JavaScript
1. sendMail creates an atp.socket object to represent a TCP/IP connection. The
constructor implicitly opens a socket.
2. sendMail checks for socket errors. The handleErrors function checks the
error property of the socket object. If an error occurred, handleErrors uses
the global function atp.print to print the error, the close method of the socket
object to close the connection, and the global function atp.quit to stop execution
of the script.
3. sendMail writes the message to the socket, using a series of calls to the write
method of the socket object.
4. After each write to the socket, sendMail checks for socket errors (using
handleErrors), then for SMTP errors (using handleReply). handleReply
checks for errors by setting a timeout with the setSoTimeout method, then
reading the reply message one byte at a time, using a shorter timeout. On an error,
handleReply uses the global function atp.print to print the error, the close
method of the socket object to close the connection, and the global function
atp.quit to stop execution of the script.
This way of reading the reply is specific to the SMTP protocol, which indicates the
length of a message at the beginning of the message. Other sockets protocols might
use different conventions.
5. After sending the whole message, sendMail uses the close method to close the
socket and the global function atp.print to report that the message was sent.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
3- 18
4
ATP Objects, Properties, and Methods
This section describes the following ATP objects and functions:
•
•
•
•
•
•
•
•
HTTP Object
ATPException Object
NonStop SQL Objects
° atp.SQL Object
° atp.sqlvar Object
NonStop TS/MP (Pathway) Objects
°
°
°
°
°
atp.dictionary Object
atp.field Object
atp.request Object
atp.blob Object
atp.buffer Object
NonStop TM/MP (TMF) Object
° atp.transaction Object
NonStop TUXEDO Objects
° atp.fml_field Object
° atp.fml_table Object
° atp.fml_buffer Object
Sockets Object
° atp.socket Object
Global Functions
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -1
ATP Objects, Properties, and Methods
HTTP Object
HTTP Object
The HTTP client interface provides client-side HTTP protocol support for
communication with HTTP servers. The current version supports only HTTP 1.0
protocol. This API is part of the ATP core package.
Refer to Sample Application on page 4-13 for a sample application demonstrating use of
the HTTP object.
Table 4-1 summarizes the properties of the HTTP object.
Table 4-1. Properties of the HTTP Object
Properties
Description
host
Contains the server host name.
path
Contains the Path value from the URL.
port
Specifies the TCP port number to be used for the OPEN method.
queryString
Contains the QueryString value from the URL.
statusText
Contains the HTTP reason phrase of the reply message from the
GET or POST method.
status
Contains the HTTP status code of the reply message from the GET
or POST method.
timeout
Contains the timeout value for TCP socket operations. The default
value is 100 (1 second).
url
Contains the URL value for the HTTP request.
responseHeaderNames
Contains an array of header names returned by the server after the
GET and POST methods.
responseText
Represents the response entity body as a UTF-8 string.
responseBinary
Represents the response entity body as a UTF-16 string.
responseXML
Represents the response entity body as parsed by the XML parser.
This property is available only upon XML for ATP add-on package
installation.
Table 4-2 summarizes the methods of the HTTP object.
Table 4-2. Methods of the HTTP Object (page 1 of 2)
Method
Description
open
Opens a HTTP connection to the server.
close
Closes the socket connection and destroys the response header
fields and entity body, if they exist.
GET
HTTP GET request.
POST
HTTP POST request. The post data will be converted UTF-8
format.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -2
ATP Objects, Properties, and Methods
Properties
Table 4-2. Methods of the HTTP Object (page 2 of 2)
Method
Description
postBinary
HTTP POST request. The post data will be converted UTF-16
format.
getResponseHeader
Returns the response header value with a supplied header name.
setRequestHeader
Specifies the request header value before GET and POST methods.
setUserInfo
Specifies the user information before opening an HTTP
connection.
setProxyInfo
Specifies the proxy information before opening an HTTP
connection.
postXML
Sends a DOMDocument by the HTTP POST method. This method
is available only upon XML for ATP add-on package installation.
Properties
host
This property contains the HTTP server’s name or address. You can use the URL or
this property to specify the HTTP server’s host name or address prior to the OPEN
method.
Remarks
String. Read/write.
Syntax
stringValue = oHTTP.host
oHTTP.host = stringValue
path
This property contains the path of the request URL in a string. You can use the URL
or this property to change the request path value prior to the GET or POST methods.
Remarks
String. Read/write.
Syntax
stringValue = oHTTP.path
oHTTP.path = stringValue
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -3
ATP Objects, Properties, and Methods
Properties
port
This property contains the TCP port number to be used for the underlying HTTP
connection. You can use the URL or this property to change the HTTP server’s port
number prior to the OPEN method.
Remarks
Unsigned integer. Read/write.
Syntax
intValue = oHTTP.port
oHTTP.port = intValue
queryString
This property contains the query string of the request URL. You can use the URL or
this property to change the request queryString value prior to the GET or POST
methods.
Remarks
String. Read/write.
Syntax
stringValue = oHTTP.queryString
oHTTP.queryString = stringValue
statusText
This property contains the reason phrase of the status line in the response message.
It returns the text of the HTTP status from the HTTP POST or GET operations.
Remarks
String. Read-only.
Syntax
stringValue = oHTTP.statusText
status
This property contains the HTTP status code of the reply message from the GET or
POST method.
Remarks
Integer. Read-only.
Syntax
intValue = oHTTP.status
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -4
ATP Objects, Properties, and Methods
Properties
timeout
This property contains the timeout for TCP socket operations. The default value is
100 (1 second). You can use this property to change the timeout value before or
between low-level socket operations.
Remarks
Unsigned integer. Read/write.
Syntax
intValue = oHTTP.timeout
oHTTP.timeout = intValue
url
This property contains the URL that will be used by OPEN and HTTP operations.
The URL value will be parsed into host, port, and queryString properties.
Remarks
String. Read/write.
Syntax
stringValue = oHTTP.url
oHTTP.url = stringValue
Examples
The following examples show the possible URL formats:
http://inline.company.com
host: inline.company.com
port: 80 (default)
path: / (default)
queryString: empty string (default)
myst.loc201.company.com:8080/index.htm?abc=123
host: myst.loc201.company.com
port: 8080
path: /index.htm
queryString: abc=123
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -5
ATP Objects, Properties, and Methods
Properties
responseHeaderNames
This property contains an array object that stores HTTP response header field
names. It returns the array of HTTP response header field names after the HTTP
POST or GET operations that reflect the internal HTTP response header table, even
before any HTTP operations.
Note. You should check the length property of the return object before accessing the
specific elements in the array object.
Remarks
Array. Read-only.
Syntax
oArray = oHTTP.responseHeaderNames
responseText
This property represents the response entity body as a UTF-8 string. An empty
string is returned if the response body is not available.
Remarks
String. Read-only.
Syntax
stringValue = oHTTP.responseText
responseBinary
This property represents the response entity body as a UTF-16 string. An empty
string is returned if the response body is not available.
Remarks
String. Read-only.
Syntax
stringValue = oHTTP.responseBinary
responseXML
This property represents the response entity body as parsed by the XML parser. This
property is available only when the XML for ATP add-on package is properly
installed on the system. It returns an “undefined” string if you try to access this
property without the XML for ATP package.
If the response entity body is not valid XML, this property returns the
DOMDocument object that was parsed so that you can access the error object,
XMLDOMParseError.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -6
ATP Objects, Properties, and Methods
Methods
Remarks
String. Read-only.
Syntax
oDOMDocument = oHTTP.responseXML
Methods
open
Initializes a socket connection to the HTTP server. You need to set the correct host
and port properties prior to calling this method.
Syntax
oHTTP.open()
Parameters
None
Return Value
None
ATPException
The possible error codes are:
•
•
•
ATP_HTTP_INVALID_URL(2): The host name is not initialized properly.
ATP_HTTP_CREATE_FAILED(101): Internal socket error. Cannot create a
new socket.
ATP_HTTP_CONNECT_FAILED(102): Server is not available or the host
name or address is invalid.
You can check the detail error code from the errorDetail property defined in the
outstanding ATPException object.
close
Closes the socket connection and destroys the response header fields and entity
body, if they exist.
Syntax
oHTTP.close()
Parameters
None
Return Value
None
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -7
ATP Objects, Properties, and Methods
Methods
GET
Sends an HTTP GET request to the HTTP server. You need to specify correct URL
information before calling this method. If the connection has not been opened, this
method calls the OPEN method internally before sending the HTTP request.
Syntax
oHTTP.GET()
Parameters
None
Return Value
None
ATPException
The possible error codes are:
•
•
•
•
•
•
ATP_HTTP_INVALID_URL(2): The host name is not initialized properly.
ATP_HTTP_CREATE_FAILED(101): Internal socket error. Cannot create a
new socket.
ATP_HTTP_CONNECT_FAILED(102): Server is not available or the host
name or address is invalid.
ATP_HTTP_HEADER_TOO_LONG(202): The request header reached the
maximum size limit (16K bytes).
ATP_HTTP_SEND_FAILED(103): Internal socket write failed.
ATP_HTTP_READ_FAILED(104): Internal socket read failed. The error may
be caused by an AWAITIOX function timeout (errorDetail = 40).
You can check the detail error code from the errorDetail property defined in the
outstanding ATPException object.
POST
Sends an HTTP POST request to the HTTP server. You need to specify correct URL
information before calling this method. If the connection is not opened, this method
calls the OPEN method internally before sending the HTTP request.
Syntax
oHTTP.POST(data)
Parameters
data – The string value to be sent to the HTTP server.
Return Value
None
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -8
ATP Objects, Properties, and Methods
Methods
ATPException
The possible error codes are:
•
•
•
•
•
•
ATP_HTTP_INVALID_URL(2): The host name is not initialized properly.
ATP_HTTP_CREATE_FAILED(101): Internal socket error. Cannot create a
new socket.
ATP_HTTP_CONNECT_FAILED(102): Server is not available or the host
name or address is invalid.
ATP_HTTP_HEADER_TOO_LONG(202): The request header reached the
maximum size limit (16K bytes).
ATP_HTTP_SEND_FAILED(103): Internal socket write failed.
ATP_HTTP_READ_FAILED(104): Internal socket read failed. The error may
be caused by an AWAITIOX function timeout (errorDetail = 40).
You can check the detail error code either from the errorDetail property defined in
the outstanding ATPException object or the HTTP object.
postBinary
Sends an HTTP POST request to the HTTP server. You need to specify correct URL
information before calling this method. If the connection is not opened, this method
calls the OPEN method internally before it sends the HTTP request.
Syntax
oHTTP.POST(data)
Parameters
data – The string value to be sent to the HTTP server. The data is converted to a
UTF-16 string before it is sent to the server.
Return Value
None
ATPException
The possible error codes are:
•
•
•
•
•
ATP_HTTP_INVALID_URL(2): The host name is not initialized properly.
ATP_HTTP_CREATE_FAILED(101): Internal socket error. Cannot create a
new socket.
ATP_HTTP_CONNECT_FAILED(102): Server is not available or the host
name or address is invalid.
ATP_HTTP_HEADER_TOO_LONG(202): The request header reached the
maximum size limit (16K bytes).
ATP_HTTP_SEND_FAILED(103): Internal socket write failed.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4 -9
ATP Objects, Properties, and Methods
•
Methods
ATP_HTTP_READ_FAILED(104): Internal socket read failed. The error may
be caused by an AWAITIOX function timeout (errorDetail = 40).
You can check the detail error code either from the errorDetail property defined in
the outstanding ATPException object or the HTTP object.
getResponseHeader
Retrieves the value of an HTTP header field from the response body.
Syntax
strValue = oHTTP.getResponseHeader(name)
Parameters
name – The string value containing the case-insensitive header name.
Return Value
String. Contains the header field value. The results of this method are valid only
after the GET or POST methods have been successfully completed. It returns an
empty string if there is no such header name in the response body.
setRequestHeader
Specifies the name of an HTTP request header field.
Syntax
oHTTP.setRequestHeader(name, value)
Parameters
name – The string containing the case-insensitive header name.
value [optional] – The string value of the header. If this parameter is null or
missing, the request header is reset to an empty string, which then will not be
included in the request.
Return Value
None.
setUserInfo
Specifies the user name and password for authorization. The user and password
information must be set prior to any GET or POST operations. The user and
password are encrypted by the RFC 2617 basic authorization algorithm before being
sent to a server. For security concerns, refer to the RFC 2617 for details.
Syntax
oHTTP.setUserInfo(user, password)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 10
ATP Objects, Properties, and Methods
Methods
Parameters
user [optional] – Name of the user for authorization. If this parameter is null or
missing, the user name and password are reset to an empty string.
password [optional] – Password for authorization. If this parameter is null or
missing, the password is reset to an empty string.
Return Value
None.
setProxyInfo
Specifies the proxy information. The proxy information must be set prior to any
OPEN operation. The user and password are encrypted by the RFC 2617 basic
authorization algorithm before being sent to the server.
Syntax
oHTTP.setProxyInfo(host, port, user, password)
Parameters
host [optional] – Host name of the proxy server. Default value is an empty string.
If this parameter is null or missing, the proxy host, port, user, and password are reset
to their default values.
port [optional] – Port number of the proxy server. Default value is 80.
user [optional] – Name of the user for proxy authorization. Default value is an
empty string. If this parameter is null or missing, the user and password are reset to
their default values.
password [optional] – Password for proxy authorization. Default value is an
empty string. If this parameter is null or missing, the password is reset to the default
value.
Return Value
None.
postXML
Posts an XML document to the HTTP server. This method is only available upon
XML for ATP add-on package installation on the system.
Syntax
oHTTP.postXML(xml)
Parameters
xml – XMLDOMDocument object to be sent to the server. This method is
equivalent to the POST(objDOMDocument.xml) method.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 11
ATP Objects, Properties, and Methods
Exception and Error Information
Return Value
None.
ATPException
ATP will return a “postXML is not a function” error message if the XML add-on
package is not installed properly. Otherwise, the possible error codes are:
•
•
•
•
•
•
•
ATP_ERR_DOM_INVALID_PARAM_TYPE(4): The argument is not an
XMLDOMDocument object.
ATP_HTTP_INVALID_URL(2): The host name is not initialized properly.
ATP_HTTP_CREATE_FAILED(101): Internal socket error. Cannot create a
new socket.
ATP_HTTP_CONNECT_FAILED(102): Server is not available or the host
name or address is invalid.
ATP_HTTP_HEADER_TOO_LONG(202): The request header reached the
maximum size limit (16K bytes).
ATP_HTTP_SEND_FAILED(103): Internal socket write failed.
ATP_HTTP_READ_FAILED(104): Internal socket read failed. The error may
be caused by an AWAITIOX function timeout (errorDetail = 40).
You can check the detail error code from the errorDetail property defined in the
outstanding ATPException object.
Exception and Error Information
An ATPException object might be thrown while executing the HTTP methods. To
prevent the program from stopping on any exception, you should use a try-catch block to
check the error information and recover from any exception.
The following list shows the possible values for the error property of the ATPException
object:
•
•
•
•
•
•
•
•
ATP_HTTP_OK(0)
ATP_HTTP_SERVER_ERROR(1): An HTTP server error was found.
ATP_HTTP_INVALID_URL(2): Invalid host, path, or query string.
ATP_ERR_DOM_INVALID_PARAM_TYPE(4): The argument is not an
XMLDOMDocument object.
ATP_HTTP_NO_MEMORY(10): Out of Memory.
ATP_HTTP_NULL_POINTER(11): Internal null pointer error.
ATP_HTTP_NO_CONNECTION(12): No connection or connection closed prior to
socket operations.
ATP_HTTP_SOCKET_INVALID(100): Internal error.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 12
ATP Objects, Properties, and Methods
•
•
•
•
•
•
Sample Application
ATP_HTTP_CREATE_FAILED(101): Internal socket error. Check errorDetail value
for Guardian system error message.
ATP_HTTP_CONNECT_FAILED(102): Internal socket error. Check errorDetail
value for Guardian system error message.
ATP_HTTP_SEND_FAILED(103): Internal socket error. Check errorDetail value
for Guardian system error message.
ATP_HTTP_READ_FAILED(104): Internal socket error. Check errorDetail value
for Guardian system error message.
ATP_HTTP_HEADER_INVALID(200): Invalid request/response header.
ATP_HTTP_HEADER_TOO_LONG(202): Internal error. The HTTP request header
is too long.
Sample Application
The following sample application shows how to get the default home page from
www.yahoo.com. You should modify proxy information according to your own network
configurations.
<server>
try
{
var http = new Inet.HTTP;
http.url = "http://www.yahoo.com/"
http.setProxyInfo("proxy.tandem.com", 8080);
http.GET();
}
catch (e)
{
println("!!! HTTP Exception: !!!");
println("code: " + e.code);
println("detail: " + e.detail);
println("description: " + e.description);
println("method: " + e.method);
println("module: " + e.module);
println("");
}
// print all response header fields.
headers = http.responseHeaderNames;
for (i=0; i<headers.length; i++)
{
println(headers[i] + ": " + http.getResponseHeader(headers[i]));
}
println("status: " + http.status);
println("statusText: " + http.statusText);
var body = http.responseText;
println(http.responseText);
</server>
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 13
ATP Objects, Properties, and Methods
ATPException Object
ATPException Object
The ATPException object contains error information defined by the ATP objects, such as
Inet.HTTP and XML.DOMDocument. The ATPException object is thrown when the
ATP page is unable to recover from an error while executing scripts. It is recommended
to use try-catch clauses to recover from run-time errors by checking the information
provided by the ATPException object.
Table 4-3 summarizes the properties of the ATPException object.
Table 4-3. Properties of the ATPException Object
Properties
Description
code
Contains the error number.
detail
Contains the detail error number.
description
Contains the error description in a text string.
module
Contains the module name where the error is thrown.
method
Contains the method name where the error is thrown.
Properties
code
Contains the error number. Each ATP object defines the possible values and
meanings. Different ATP objects may define the same value for different meanings.
You can check the module and method to determine where the exception is thrown.
Remarks
Integer. Read-only.
Syntax
nErrorCode = oException.code
detail
Contains the detail error number. Each ATP object defines the possible values and
meanings. The same ATP object may define different error codes with the same
error detail numbers. You should check the code property before checking the detail
property.
Remarks
Integer. Read-only.
Syntax
nErrorDetail = oException.detail
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 14
ATP Objects, Properties, and Methods
Properties
description
Contains the error description in a text string. This is the default property of the
ATPException object. In other words, the value of the description is shown if the
ATPException object is not caught by ATP scripts.
Remarks
String. Read-only.
Syntax
sDescription = oException.description
module
Contains the module name where the error is thrown. Usually the module name
contains the object’s class name, such as HTTP and DOMDocument.
Remarks
String. Read-only.
Syntax
sModule = oException.module
method
Contains the method name where the error is thrown. You should check the module
property before checking the method property.
Remarks
String. Read-only.
Syntax
sMethod = oException.method
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 15
ATP Objects, Properties, and Methods
NonStop SQL Objects
NonStop SQL Objects
NonStop SQL objects enable you to develop scripts that use NonStop SQL databases.
For a discussion and example of using these objects, see Using NonStop SQL from
JavaScript on page 3-4.
atp.SQL Object
The atp.SQL object represents one NonStop SQL statement, including any derived
cursors, result data, and error reporting information. You can use atp.transaction
objects with the atp.SQL object for transaction protection.
Constructor
new atp.SQL (statement)
statement
This parameter contains any statement supported by dynamic NonStop SQL. The
only statements excluded are some related specifically to imbedded SQL or the
underlying implementation of dynamic SQL.
The atp.SQL object caches SQL statements to ensure good performance. The
cache is much more effective if the NonStop SQL statements are parameterized,
with variable data provided in the atp.SQL execute() method call.
See atp.SQL Object Usage Considerations below.
Properties
statement (read-only)
This property contains the statement specified in the constructor.
column_name (read-only)
This array contains the column name of each column that will be returned by a
SELECT statement. Summary columns, such as COUNT(*) have a zero length
column_name array element. Subscripts are numeric; the range is from zero to the
number of columns in the query.
column_value (read-only)
This array contains the column value, as a string, of each column returned by a
SELECT statement. The atp.SQL next() method puts one row at a time into
this property. SQL null is represented by the JavaScript null value. Subscripts are
numeric or text (lowercase) in the form tablename.colname (for example,
stmt.column_value["cust.first_name"]). As in other JavaScript
implementations, references to undefined array elements (such as misspelled column
names) are not reported as errors. The value is returned as the JavaScript undefined
value.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 16
ATP Objects, Properties, and Methods
atp.SQL Object
row_print_format
This property, if set, contains a string that describes the format in which to print
rows of a table. If you use this property, the next() method retrieves and prints a
row without placing the data in the column_value array and without requiring
your script to invoke print functions explicitly. This option reduces CPU and
memory use and can therefore greatly improve performance, especially if your script
retrieves and prints many rows of data (for example, more than 5000 rows).
The string follows C language printf conventions and can contain a combination
of text and HTML. Use the notation %s to represent the position of each column in
the format, regardless of the data type of the column in the table. For example:
s1.row_print_format="<tr><td>%s</td><td>%s</td><td>%s</td></tr>"
To include the symbol % in the output, use the notation %%.
variables (read-only)
This array contains the variable name of each variable (designated with ?) in the
SQL query. Subscripts are numeric.
cursor_name (read-only)
If the atp.SQL object represents a SELECT statement, this property contains the
cursor name. The atp.SQL execute() method establishes the name. All
SELECT statements have cursors, even if only one row is returned or expected. This
property has no significance for other types of SQL statements.
sqlcode (read-only)
This error number is set by the atp.SQL constructor and the execute(),
next(), and close() methods. Positive numbers are warnings (100 is No More
Rows), negative numbers are errors, and 0 means success. For descriptions of the
errors, see the NonStop SQL/MP manual set.
filesystem_error (read-only)
This property contains an operating-system error number. The value is set by the
atp.SQL constructor and the execute(), next(), and close() methods.
sqlca (read-only)
This text representation of the SQLCA structure is set by the atp.SQL constructor
and the execute(), next(), and close() methods. This structure contains
human-readable diagnostic information, including a text error message. See the
NonStop SQL/MP manual set for detailed information about the SQLCA structure.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 17
ATP Objects, Properties, and Methods
atp.SQL Object
statement_type (read-only)
This property contains a code indicating the type of SQL statement represented by
the atp.SQL object. The codes are:
Code Number
SQL Statement
1
SELECT
2
INSERT
3
UPDATE
4
DELETE
5
DDL - any non-control statement, such as CREATE
6
CONTROL
7
DCL
8
GET
This value comes from the SQLSA structure, which contains human-readable
statistics information related to the query or table. See the NonStop SQL/MP manual
set for detailed information about the SQLDA structure.
records_accessed (read-only)
This property contains a cumulative statistic for the atp.SQL object. The count
includes all tables used by the query. This value is aggregated from the SQLSA on
every SQL operation.
records_used (read-only)
This property contains a cumulative statistic for the atp.SQL object. Count
includes all tables used by the query. This value is aggregated from the SQLSA on
every SQL operation.
Methods
execute(value1, ...., transaction)
For SELECT statements, the execute() method opens a cursor. For other
statements, this method causes the execution of the other statements. This method is
equivalent to the SQL OPEN cursor operation.
This method returns the value false if there is a SQL error; otherwise, it returns
the value true.
value1, ...
Parameter values are substituted in order into the placeholders in the SQL
statement, as shown in atp.SQL Object Usage Considerations. There must be
one parameter for each placeholder; no defaults are defined. (If you don’t
specify one parameter for each placeholder, ATP displays an error message.)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 18
ATP Objects, Properties, and Methods
atp.SQL Object
Specify all values as strings. SQL null is represented by the JavaScript null
value.
Note. ATP does not validate application data except to assure that adjacent data, for instance
an adjacent column, is not corrupted. Your application must validate input data for both type
and range. Invalid data will cause unpredictable results.
transaction
You can provide a transaction object to protect the transaction performed by the
statement. The rules regarding when to specify transactions are the same as for
NonStop SQL/MP.
next(transaction)
This method, meaningful only if the statement type is SELECT, fetches one row into
the column_value property array. This method is equivalent to the SQL FETCH
operation.
This method returns the value false if there is a SQL error or there are no more
rows (sqlcode=100). Otherwise it returns the value true.
transaction
You can provide a transaction object to protect the transaction. The rules
regarding when to specify transactions are the same as for NonStop SQL/MP.
close(transaction)
For SELECT statements, the close() method closes the cursor. This method is
equivalent to the SQL CLOSE cursor operation. Open cursors are automatically
closed when ATP performs garbage collection occurs for the atp.SQL object.
However, the close() method lets you close the cursor in a timely way and allows
for a TMF transaction.
This method returns the value false if there is a SQL error; otherwise, it returns
the value true.
transaction
You can provide a transaction object to protect the transaction. The rules
regarding when to specify transactions are the same as for NonStop SQL/MP.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 19
ATP Objects, Properties, and Methods
atp.SQL Object
atp.SQL Object Usage Considerations
The examples discussed in Section 3, ATP Web Page and Script Structure, demonstrate
important design and usage techniques. The following text includes some special rules
and guidelines for using the atp.SQL object.
SELECT Statements
SQL SELECT statements always require the following three calls:
1. atp.SQL constructor, to prepare the statement and declare a cursor.
2. execute() method, to open a cursor.
3. next() method, to fetch one result row.
For example:
s1 = new atp.SQL ("select * from =account");
if (s1 == null){
atp.print ("failed to create SQL object")
atp.quit (0)
}
if (s1.sqlcode) {
atp.print ("SQL error = "+s1.sqlcode)
atp.quit (0)
}
s1.execute();
if (s1.sqlcode){
atp.print("SQLexecute failed:" +s1.sqlcode)
atp.quit (0)
}
while (s1.next())
{
atp.print (s1.column_value["account.account_type"]);
}
s1.close();
Map Class Defines
Names of tables, views, and other files in SQL statements can be either map class
defines or physical file names. Set up defines by including MapDefine commands
when you define the atp.pway server class in the ATP configuration file
(atp.config). For example, the following directive maps the name cust to a
specific location in the file system.
MapDefine =cust /G/data02/djcanta3/cust)
For more examples, see ATP in the WebServer Configuration File on page 2-8.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 20
ATP Objects, Properties, and Methods
atp.SQL Object
Parameters in SQL Statements
Parameterize SQL statements to maximize cache efficiency and script performance.
In the following example, the constructor specifies the SQL statement with the
parameter first; the execute() method invocation provides the value Roger:
s=new atp.SQL("select * from =cust where first_name =
?first browse access");
s.execute("Roger");
s.next();
The following example is functionally the same but not as efficient:
name = "Roger";
s=new atp.SQL("select * from =cust where first_name = '" +
name + "' browse access");
s.execute();
s.next();
Updateable Cursors
You can use the cursor_name property to refer to an updateable cursor in SQL Data
Management Language (DML) statements. For example:
tran = new atp.transaction();
var s1 = new atp.SQL ("select * from =cust for update of last_name");
s1.execute (tran);
while (s1.next(tran))
{
var s2 = new atp.SQL ("update =cust set last_name = ?last"+
"where current of " + s1.cursor_name);
s2.execute ("Smith", tran);
}
tran.commit();
Using SQL Null
In server-side JavaScript, the keyword null (not the string “null”) indicates a null
value. The following example illustrates the syntax to use in update statements for
setting columns to SQL null. The execute() method considers the two variables to be
one variable. This first example shows incorrect usage:
tran = new atp.transaction();
var s1 = new atp.SQL ("update =table set mycolumn = ?x
indicator ?y for stable access");
s1.execute (null, tran);
tran.commit();
To set multiple columns to SQL null, use a different indicator variable for each column.
This example shows correct usage:
update =table
set col1= ?x1 indicator ?ind1
set col2= ?x2 indicator ?ind2
s1.execute(gCol1_val, gCol2_val, tran);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 21
ATP Objects, Properties, and Methods
atp.SQL Object
Date and Time in SQL Statements
If you express the date and time as a literal in an SQL statement, you must also
explicitly include the type—for instance, year to day—in the statement. However, if you
express the data and time as a variable in the SQL statement, you must not explicitly
include the type. The code fragment in Example 4-1 demonstrates these rules:
Example 4-1. Date and Time in SQL Statements
atp.print (‘********************************************\n’);
tran = new atp.transaction();
//Date time value as a literal
s1 = new atp.SQL(
"select tran.accountid,tran.tran_date,tran.tran_amount,"
+"tran.tran_origin"
+"from \\ATX.$DATA02.DJCANTA3.TRAN tran"
+"where tran.tran_date > datetime '1995-07-31' year to day"
+"for stable access"
);
SQLError (s1,tran);
s1.execute(tran);
SQLError (s1,tran);
while (s1.next(tran)) {
atp.print (s1.column_value,'\n');
}
SQLError (s1,tran);
atp.print (‘********************************************\n’);
//Date time value as a variable
s2 = new atp.SQL(
"select tran.accountid,tran.tran_date,tran.tran_amount,"
+"tran.tran_origin"
+"from \\ATX.$DATA02.DJCANTA3.TRAN tran"
+"where tran.tran_date > ?START_DATE"
+"for stable access"
);
SQLError (s2,tran);
s2.execute('1995-07-31', tran);
SQLError (s2,tran);
while (s2.next(tran)) {
atp.print (s2.column_value,'\n');
}
SQLError (s2,tran);
tran.commit();
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 22
ATP Objects, Properties, and Methods
atp.sqlvar Object
atp.sqlvar Object
The atp.sqlvar object represents the detailed description of one column or variable
from a NonStop SQL query. Most applications do require this object. The object is
useful for applications that dynamically create the format (as well as the content) of
HTML pages based on an SQL query directly entered by an application user. Such
applications include decision-support applications, testing tools, and database
administration tools.
Constructor
new atp.sqlvar (atp.SQL_object, column/variable_index,
input/output_flag)
atp.SQL_object
This parameter is a previously instantiated object that represents one NonStop SQL
statement, typically a DML-style statement such as SELECT or INSERT. The
NonStop SQL statement could return columns and take variables as input. (A
variable is designated by a ? in the query).
column/variable_index
This parameter is the index of either a column or variable within the query. (The
next parameter, input_output_flag, indicates which.) For a column, the value
is the index of the atp.SQL object column_name array. For a variable, the value
is the index of the atp.SQL object variables array.
You could use this object to loop through the atp.SQL object column_name
array, instantiate an atp.sqlvar object for each index, and dynamically create
HTML based on the atp.sqlvar properties. For example, you could use the data
type to set the alignment in an HTML table of the data, or to lay out a form for input
of query variables. (The atp.sqlvar object indicates the data type of an object,
which has implications for the layout of an HTML table or form.)
input/output_flag
This parameter indicates whether the object represents input or output data. Its
permissible values are 0 and 1. Use 0 for information about output items (generally
columns). Use 1 for information about input items (variables). By default the value
is 0 (zero).
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 23
ATP Objects, Properties, and Methods
atp.sqlvar Object
Properties
The properties of this object are derived very closely from the SQLDA structure. For
detailed descriptions of the properties, see the NonStop SQL/MP Programming Manual
for C. Each property has the same range of values as in the SQLDA structure.
data_type_code (read-only)
This property is a numeric code indicating the data type of the column or variable.
length (read-only)
This property gives the internal storage length of a column or variable. For example,
the value is 2 bytes for a short integer.
numeric_scale (read-only)
This property gives the number of decimal places for binary and decimal numbers.
numeric_precision (read-only)
This property gives the precision of binary numerics.
date_time_interval_range (read-only)
This property is a numeric code representing the scope of a date/time or interval
item. For example, the value 9 represents “year to day.” See the NonStop SQL
manual set for a description of this property and its values.
date_time_interval_leading_precision (read-only)
This property is defined in the NonStop SQL manual set.
date_time_interval_fraction_precision (read-only)
This property is defined in the NonStop SQL manual set.
character_set_id: (read-only)
For character items, this property identifies the character set. For example,
0=unknown,103=ISO88593. For a complete description, see the NonStop SQL
manual set.
null_permitted (read-only)
This property is a Boolean value indicating whether an SQL null value is permitted
for the column.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 24
ATP Objects, Properties, and Methods
NonStop TS/MP (Pathway) Objects
NonStop TS/MP (Pathway) Objects
The NonStop TS/MP (Pathway) objects let you develop scripts that use Pathway
applications and Data Definition Language (DLL) dictionaries. For a discussion and
example of using these objects, see Using Pathway TS/MP Servers from JavaScript on
page 3-8.
atp.dictionary Object
The dictionary object represents one or more application-message layout definitions
from a DDL dictionary. You can use this object in conjunction with the buffer object
getData() and setData() methods.
Constructor
new atp.dictionary (name, element, element, ...)
name
This parameter is the name of an OSS symbolic link to a DDL dictionary subvolume
or a map class define for the DDL dictionary dictddf file. The DDL dictionary
contains the application-message layout definitions.
The symbolic link name is relative to the directory of the current script and must not
start with a . (dot) or / (forward slash). You use the ln command to create symbolic
links.
For example:
ln -s /G/data/subvol mydict.ddldict
The map class define (for example, =paydict) refers to the DDL dictddf file in
the DDL dictionary subvolume. You establish the define in the iTP Secure
WebServer httpd.config file, using the MapDefine configuration directive.
For example:
MapDefine =paydict /G/data02/payroll/dictddf
element
This parameter specifies one or more DDL DEFs of application messages. If no
element is specified, the new object instance represents all DEFs from the
dictionary. For best performance, explicitly specify the DEFs the application will
use.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 25
ATP Objects, Properties, and Methods
atp.dictionary Object
Properties
name (read-only)
This property contains the value supplied to the constructor.
element (read-only)
This array contains one atp.field object for each DDL DEF that the
atp.dictionary object represents.
element.DEF properties (read-only):
These dynamically created properties of the element property are atp.field
objects, each representing one DDL DEF that the atp.dictionary object
represents. That is, for each DEF there is a property whose name consists of the
word “element,” followed by a period, followed by the name of the DEF.
atp.dictionary Object Usage Considerations
The constructor for the atp.dictionary object uses the DDL dictionary to build a
hierarchy of atp.field objects. This operation causes disk (or disk cache) activity,
which can affect application performance. Alternatively, applications can construct
atp.field objects directly; however the specification of atp.field object
constructors is tedious and error prone.
For convenience, you can use the dview example application program, described in
Appendix B, DDL Dictionary Viewer (dview), to generate atp.field object
constructors to be copied into your application. The generated constructors provide a
static definition of the DDL message within the JavaScript application.
Note that if you use dview to create constructors, updates to the DDL dictionary will
not automatically be reflected in your application. In contrast, the atp.dictionary
object continually accesses the DDL dictionary. The major advantage of static
atp.field object constructors is to improve performance by reducing DDL
dictionary-related disk activity.
To use the static atp.field object constructors, copy and paste them into the
JavaScript application. You can use a server-side include file to facilitate updates when
the DDL dictionary changes.
In addition to atp.field object constructors, the dview tool generates other
constructors that describe relationships among fields. For efficiency, use only the actual
atp.field object constructors (of the form new atp.field(....)) when you
invoke the atp.buffer setData(), getData(), and setBinary() methods.
For example:
myvar=mybuffer.getData(new atp.field('reply_code',2, 'Binary 16
unsigned',3,0,2,0,0,0,new Array(0,0,0,0,0,0,0),1));
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 26
ATP Objects, Properties, and Methods
atp.field Object
atp.field Object
The field object describes a data field within an application message. The data field can
be an elementary or group (structured) field with up to 49 levels of nesting.
Constructor
new atp.field (name, level, type, structure, offset, length, decimals,
bit_offset, bit_length, subscript_multipliers, occurs_max)
An atp.dictionary object automatically creates atp.field objects. You can
also construct an atp.field object explicitly, for example with the statement
new atp.field('total_salary',1,'Binary 32
unsigned',5,98,4,2,0,0, new Array(0,0,0,0,0,0,0),1)
Using the atp.dictionary object to generate the atp.field objects is easier and
less error-prone than creating atp.field objects explicitly. You can also use the
dview example application program to create atp.field objects, as described in
atp.dictionary Object Usage Considerations on page 4-26.
name
This parameter specifies the name of the field.
level
This parameter indicates the level at which the field exists in the applicationmessage structure. The level is between 0 and 48.
type
This parameter contains text identifying the data representation of the field within
the application-message buffer. The Description column in Table 4-4 on page 4-30
lists the text for each type.
structure
This parameter contains a number identifying the data representation of the field
within the application-message buffer. The numbers are the same as those used
within the DDL dictionary dictobl file. Table 4-4 on page 4-30 lists the supported
data types.
offset
This parameter contains a number representing the byte offset of the field within the
application-message buffer. For subscripted items, the value is the offset of the first
instance. The first field has an offset of zero.
length
This parameter gives the length (in bytes) of the field within the applicationmessage buffer.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 27
ATP Objects, Properties, and Methods
atp.field Object
decimals
This parameter gives the number of implied decimal places (COBOL "V" picture
option). The value can be a negative number for scaled numbers (COBOL "P"
picture option).
bit_offset
This parameter gives the bit offset (starting at 0, maximum 15) of a DDL bit data
type.
bit_length
This parameter gives the bit length (minimum 1, maximum 15) of a DDL bit data
type.
subscript_multipliers
This parameter is an array of sizes, in bytes, of the enclosing repeating structures of
subscripted fields. Up to seven subscripts are supported.
occurs_max
This parameter gives the maximum number of occurrences specified for a field. The
value is 1 for non-repeating fields. If a repeating field has subfields, the repeating
field has an occurs_max value other than 1; each subfield, however, has an
occurs_max value of 1 unless a given subfield is also specified as repeating,
resulting in a nested table.
Properties
name (read-only)
This property gives the name of the field.
level (read-only)
This property indicates the level at which the field exists in the application-message
structure. The level is between 0 and 48.
type (read-only)
This property contains text identifying the data representation of the field within the
application-message buffer. The Description column of Table 4-4 on page 4-30 gives
the text for each type.
structure (read-only)
This property contains a number identifying the data representation of the field
within the application-message buffer. The numbers are the same as those used
within the DDL dictionary dictobl file. Table 4-4 on page 4-30 lists the supported
data types.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 28
ATP Objects, Properties, and Methods
atp.field Object
offset (read-only)
This property contains a number representing the byte offset of the field within the
application-message buffer. For subscripted items, the value is the offset of the first
instance. The first field has an offset of zero.
length (read-only)
This property gives the length in bytes of the field within the application message
buffer.
decimals (read-only)
This property gives the number of implied decimal places (COBOL "V" picture
option). The value can be a negative number for scaled numbers (COBOL "P"
picture option).
bit_offset (read-only)
This property gives the bit offset (starting at 0, maximum 15) of a DDL bit data
type.
bit_length (read-only)
This property gives the bit length (minimum 1, maximum 15) of a DDL bit data
type.
subscript_multipliers (read-only)
This property is an array of sizes, in bytes, of the enclosing repeating structures of
subscripted fields. Up to 7 subscripts are supported.
occurs_max (read only)
This property gives the maximum number of occurrences specified for a field. The
value is 1 for non-repeating fields. If a repeating field has subfields, the repeating
field has an occurs_max value other than 1; each subfield, however, has an
occurs_max value of 1 unless a given subfield is also specified as repeating,
giving a nested table.
fields (read-only)
This property is an array of the field objects owned by this field object. Fields own
the fields declared with a higher level number within an application message
structure. (If a field has fields in it, the contained fields have a higher level number
than the field that contains them.) In the C language, this concept corresponds to a
struct owning its elements; in COBOL, group data items own their elements.
field (read-only)
The value of this property is the name of a field object owned by this field object.
Thus, you can refer to a field within a field object by using either the name of the
field or an index into the fields array.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 29
ATP Objects, Properties, and Methods
Table 4-4. Data Types Used by the atp.field Object (page 1 of 3)
Structure Number
Description
0
Alphanumeric string
1
Numeric string unsigned
2
Binary 16 signed
3
Binary 16 unsigned
4
Binary 32 signed
5
Binary 32 unsigned
6
Binary 64 signed
8
Float 32
9
Complex 32*2 (not currently supported)
10
Float 64
12
Numeric string trailing imbedded sign
13
Numeric string trailing separate sign
14
Numeric string leading imbedded sign
15
Numeric string leading separate sign
17
Logical*1
19
Logical*2
21
Logical*4
22
Binary 8 signed
23
Binary 8 unsigned
24
Varchar
25
Enumeration
26
Bit signed
27
Bit unsigned
28
National string
32
Datetime year
33
Datetime month
34
Datetime year to month
35
Datetime day
36
Datetime month to day
37
Datetime year to day
38
Datetime hour
39
Datetime day to hour
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 30
atp.field Object
ATP Objects, Properties, and Methods
Table 4-4. Data Types Used by the atp.field Object (page 2 of 3)
Structure Number
Description
40
Datetime month to hour
41
Datetime year to hour
42
Datetime minute
43
Datetime hour to minute
44
Datetime day to minute
45
Datetime month to minute
46
Datetime year to minute
47
Datetime second
48
Datetime minute to second
49
Datetime hour to second
50
Datetime day to second
51
Datetime month to second
52
Datetime year to second
53
Datetime fraction
54
Datetime second to fraction
55
Datetime minute to fraction
56
Datetime hour to fraction
57
Datetime day to fraction
58
Datetime month to fraction
59
Datetime year to fraction
60
Interval year
61
Interval month
62
Interval year to month
63
Interval day
64
Interval hour
65
Interval day to hour
66
Interval minute
67
Interval hour to minute
68
Interval day to minute
69
Interval second
70
Interval minute to second
71
Interval hour to second
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 31
atp.field Object
ATP Objects, Properties, and Methods
atp.request Object
Table 4-4. Data Types Used by the atp.field Object (page 3 of 3)
Structure Number
Description
72
Interval day to second
73
Interval fraction
74
Interval second to fraction
75
Interval minute to fraction
76
Interval hour to fraction
77
Interval day to fraction
Note
SQL nullable option supported for most data types
atp.request Object
The request object contains information related to one request from a web browser.
Constructor
Private
This object is constructed from each request received from the iTP Secure
WebServer.
Properties
variables (read-only)
This variable property is read-only. If you try to modify the value, ATP will report
an error message. The variables array contains one entry for each environment
variable passed in the request. These environment variables contain information
about the web browser and web server (for example REMOTE_ADDR,
SERVER_SOFTWARE). The array also contains an entry for each name provided on
a form or in a query URL from the web browser. This array does not contain entries
for ATP configuration variables, because those variables are not passed in the
request message.
To iterate through the variable values, try the following technique:
for (i=0; i<atp.request.variables.length;i++)
{
atp.print (atp.request.variables[i] + '=' +
atp.request[atp.request.variables[i]] + '\n');
}
This technique works because JavaScript lets you use array subscript notation for
access to object properties.
If duplicate environment variables occur (for example, as a result of identically
named fields on a form), only the last arriving value is stored. To get duplicate
values, either use the GET method and parse the data out of QUERY_STRING (a
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 32
ATP Objects, Properties, and Methods
atp.request Object
difficult approach) or suffix field names with a numeric index (such as
PartField_01 or PartField_02) and get the values as follows:
for (i=0; i<atp.request.variables.length;i++)
{
if ((atp.request.variables[i]).indexOf('PartField_')==0)
{
atp.print (atp.request.variables[i] + '=' +
atp.request[atp.request.variables[i]] + '\n');
}
}
variable property (read-only)
For each variable in the variables array, the atp.request object also has a
property with the same name as the variable. The value of the property is the value
of the environment variable of the same name. All values are strings except when
you use RFC1867/multipart/form-data support for forms-based file upload. In the
latter case, the type of variable is file, and the value is an atp.blob object.
Methods
close
ATP 2.0 will release the internal cache entry of the SQL statement when the close
method is called. The subsequent methods like execute or next will report an error,
“Invalid SQL statement”, after the close method. The close method between
multiple execute methods is not necessary for the same SQL statement on the same
page. ATP 2.0 will close and re-open the internal SQL cursor for the second and
subsequent execute methods.
execute
ATP 2.0 will check the number and types of parameter values passed by the
applications. ATP will report errors if the syntax of the parameters violates the
following rules:
1. There must be one parameter for each SQL placeholder in the SELECT
statement.
2. If the number of parameters is greater than the number of SQL variable
placeholders in the SELECT statement, the type of parameter following the last
SQL placeholder must be the atp.transaction object.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 33
ATP Objects, Properties, and Methods
atp.blob Object
atp.blob Object
The blob object is a container for binary data. atp.blob objects are created as
properties of the atp.request object as part of forms-based file upload support
(RFC1867 /multipart/form-data). Use the atp.buffer object setBinary() method
to move atp.blob objects to atp.buffer objects.
Constructor
new atp.blob (string_name,string_filename, string_type, string_data)
string_name
This parameter contains descriptive data. For atp.blob objects created as part of
forms-based file upload, this value is the input field name.
string_filename
This parameter contains descriptive data. For atp.blob objects created as part of
forms-based file upload, this value is the name of the file being uploaded.
string_type
This parameter contains descriptive data. For atp.blob objects created as part of
forms-based file upload, this value is the content type of the uploaded file.
string_data
This parameter contains the blob data. For atp.blob objects created as part of
forms-based file upload, this value consists of the contents of the file being
uploaded. (The largest supported file size is 200,000 bytes.) The content is binary
data.
Properties
The atp.blob object has a property corresponding to each parameter you supply
in the constructor.
atp.buffer Object
You use the buffer object to store application-message data and to communicate with a
Pathway (NonStop TS/MP) server class through the Pathsend facility.
Constructor
new atp.buffer(string_type)
string_type
The string_type indicates the convention used by the application to store
strings in application messages. Its value must be the string "c" (trailing null) or the
string "cobol" (trailing spaces). The default is "c".
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 34
ATP Objects, Properties, and Methods
atp.buffer Object
Properties
data_length
This property is the number of bytes to be sent with the next send() method call,
or the number of bytes received in a reply buffer. In either case, data_length is
the length of relevant data stored in the application-message structure. The
data_length property is automatically adjusted by the setData() and
setBinary() methods (which put data into application-message structures) and
reflects the offset, from the beginning of the structure, of the last byte placed in the
buffer, even if fields earlier in the structure are empty.
The range of this property is 1 to 31,000 bytes.
reply
The reply property of a buffer is set by the send() method. For successful
sends, the reply property is an automatically created buffer object, which you use
to access and process the application reply data. The length of this value is the
length of the reply from the server.
string_type
This property has the value provided in the constructor.
error (read-only)
The error property is set by the send() method and is the Pathsend error
number. A value of 0 signifies successful communication with an application server.
error_detail (read-only)
If the error property is non-zero, error_detail is the associated file-system
error number (if any).
pathsend_error_text (read-only)
If the error property is non-zero, pathsend_error_text is text describing
the Pathsend error.
pathsend_timeout
This property contains the timeout, in hundredths of a second, used by the send()
method. The range is the same as for a serverclass_send_ call in the NonStop
TS/MP programming environment; see the NonStop TS/MP manual set for more
information. The default value is 60 seconds.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 35
ATP Objects, Properties, and Methods
atp.buffer Object
Methods
send (pathmon, server_class, transaction)
This method sends the application-message buffer to the specified Pathway server
class. You must first construct the message in a buffer object by using the
setData() method.
pathmon
This parameter contains the name of a map class define (for example,
=payroll) that refers to the required application's PATHMON process. You
set up a map class define by using the MapDefine command in the
atp.config file, for example:
MapDefine =payroll /G/payr
The predefined value =loopback causes the reply to have exactly the same
contents as the buffer sent to the server.
The predefined value =TANDEM_PATHMON_NAME is also the default value. It
represents the PATHMON environment established by the httpd.config file
that includes this atp.config file.
server_class
This parameter contains the name of the Pathway server class to which the
application message should be sent.
transaction (optional)
This parameter is an atp.transaction object under whose TMF
transaction the current send operation should be initiated.
setData (data, field, subscript1, subscript2, ...)
This method moves data to be sent to the Pathway server class to the applicationmessage buffer. The setData() method differs from the setBinary() method
in that the data is converted according to the field definition of the destination.
data
This parameter is the data to be put into the application-message buffer. Express
the data as a string, regardless of the data type it represents. (For example, it
could represent a floating point number.) To convert a value to a string, use the
JavaScript .toString feature.
Note. ATP does not validate application data except to ensure that adjacent data, for
instance an adjacent column, is not corrupted. Your application must validate input
data for both type and range. Invalid data will cause unpredictable results.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 36
ATP Objects, Properties, and Methods
atp.buffer Object
field
This parameter is an atp.field object (which is a property of an
atp.dictionary object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the offset within the applicationmessage buffer, and other information needed to convert and place the data item.
subscript1, ...
Up to seven numeric subscripts are supported; each subscript represents an array
dimension. The value of any subscript starts at zero (0). Subscripts are optional.
setBinary (data, field, subscript1, subscript2, ...)
This method moves data to be sent to the Pathway server class to the applicationmessage buffer. The setBinary() method differs from the setData() method
in that the data is transferred byte by byte; that is, no data conversion is performed.
data
This parameter contains the data to be put into the application-message buffer.
The data is not converted to be consistent with DDL representation.
Furthermore, data can overflow a field; this feature provides automatic support
for variable-length messages and is especially useful when used with
atp.blob objects for forms-based file upload. Be careful not to overflow
fields accidentally.
field
This parameter is an atp.field object (which is a property of an
atp.dictionary object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the offset within the applicationmessage buffer, and other information needed to place the data item.
subscript1, ...
Up to seven numeric subscripts are supported; each subscript represents an array
dimension. The value of any subscript starts at zero (0).
return = getData (field, subscript1, subscript2, ...)
This method retrieves converted data from the application-message buffer. The
getData() method differs from the getBinary() method in that the data is
converted according to the field definition of the destination.
return
The value of the data item from the application message is returned in string
format, regardless of the application data type. To perform computations with
the value, use the JavaScript parseInt feature.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 37
ATP Objects, Properties, and Methods
atp.buffer Object
field
This parameter is an atp.field object (which is a property of an
atp.dictionary object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the offset within the applicationmessage buffer, and other information needed to convert and place the data item.
subscript1, ...
Up to seven numeric subscripts are supported; each subscript represents an array
dimension. The value of any subscript starts at zero (0).
return = getBinary (field, subscript1, subscript2, ...)
This method retrieves data from the application-message buffer. The
getBinary() method differs from the getData() method in that the data is
retrieved byte by byte; that is, no data conversion is performed.
return
The value of the data item from the application message is returned in string
format regardless of the application data type (and might contain nonprintable
characters.)
field
This parameter is an atp.field object (which is a property of an
atp.dictionary object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the offset within the applicationmessage buffer, and other information needed to place the data item.
subscript1, ...
Up to seven numeric subscripts are supported; each subscript represents an array
dimension. The value of any subscript starts at zero (0).
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 38
ATP Objects, Properties, and Methods
NonStop TM/MP (TMF) Object
NonStop TM/MP (TMF) Object
This object enables you to develop scripts that implement transaction protection. For a
discussion and example of using this object, see Using Pathway TS/MP Servers from
JavaScript on page 3-8.
atp.transaction Object
The transaction object represents a TMF transaction. The TMF transaction starts when
the application refers to the atp.transaction object when invoking the send()
method of an atp.buffer object, or the execute() or next() methods of the
atp.SQL object. Internally the transaction begins, and is then suspended until it
receives a commit( ) or rollback( ).
Constructor
new atp.transaction()
Instantiate this object whenever a new TMF transaction is needed.
Properties
error (read-only)
This property is a NonStop Kernel error code and is set both by implicit and explicit
method calls. The implicit method calls to begin a TMF transaction occur when the
application first refers to an atp.transaction object. A zero (0) value indicates
that no error occurred.
status (read-only)
This property is the transaction status (for example, committed or hung), expressed
as text. See the NonStop TM/MP manual set for a list and descriptions of defined
values.
transid (read-only)
This property is the TMF transid expressed as text.
Methods
commit()
This method commits the TMF transaction represented by the
atp.transaction object. Check the error property for error conditions.
rollback()
This method rolls back the TMF transaction represented by the
atp.transaction object. Check the error property for error conditions.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 39
ATP Objects, Properties, and Methods
NonStop TUXEDO Objects
NonStop TUXEDO Objects
The NonStop TUXEDO objects enables you to develop scripts that use NonStop
TUXEDO (Release 2) applications. For a discussion and example of using these objects,
see Using NonStop TUXEDO Servers from JavaScript on page 3-10.
atp.fml_field Object
The fml_field object represents one FML field from a NonStop TUXEDO FML
field table.
Constructor
new atp.fml_field (name, type, type_text, base, field_id)
This object is usually instantiated automatically from an FML field table when the
application instantiates the atp.fml_table object.
name
This parameter is the name of the FML field.
type
This parameter contains a numeric code representing the type of the field. The codes
are standard in TUXEDO:
0=short int
1=long int
2=character
3=single-precision float
4=double-precision float
5=string—null terminated
6=character array)
type_text
This parameter is the data type expressed as text. (The text is the same as in the list
of type codes above.)
base
This parameter is the *base specification for the field from the field table. For
information about the base used to calculate a TUXEDO field ID, see the NonStop
TUXEDO manual set.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 40
ATP Objects, Properties, and Methods
atp.fml_table Object
field_id
This parameter is the field ID of the FML field from the field table. When added to
the base, this value gives the absolute field ID. (TUXEDO gets the run-time field ID
by combining the absolute field ID with the numeric data type. In the JavaScript
environment, the calculation is performed automatically by the methods of the
atp.fml_buffer object.)
Properties
The atp.fml_field object has a property corresponding to each parameter in the
constructor.
atp.fml_table Object
The fml_table object represents one field table. It is used primarily with the
atp.fml_buffer setData() and getData() methods.
Constructor
new atp.fml_table(field_table[,field_name][,field_name]...)
field_table
This parameter contains the name of the OSS file containing an FML field table.
The file name is relative to the directory of the page containing the referring script.
If the file name does not contain a directory, then the FLDTBLDIR32 and
FLDTBLDIR paths are searched for the field table. Set up the paths using iTP
Secure WebServer AddCGI configuration commands.
Note. Path searching uses more runtime resources than page-relative file naming.
field_name
By default all fields from the table are represented by the instantiated
atp.fml_table object. Using field name(s) in the constructor restricts the
atp.fml_table object to the designated fields. When you use large field tables,
restricting the fields in the table can benefit performance.
Properties
name (read only)
This property is a file name of the field table.
fields (read only)
This array contains an element for each atp.fml_field object derived from the
FML field table.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 41
atp.fml_table Object
ATP Objects, Properties, and Methods
field property (read only)
Each field contained in the FML field table is also a property, with the same name as
the FML field.
atp.fml_table Object Examples
The following three examples show uses of the atp.fml_table object.
Example 1
The following NonStop TUXEDO field table yields the following objects from this
constructor:
ftbl=new atp.fml_table("emp.tbl")
*base 100
# name
MESSAGE_TEXT
#
DEPTNUM
EMPLOYEE_NUMBER
JOBCODE
FIRST_NAME
LAST_NAME
SALARY
number
1
type
string
100
101
102
103
104
105
short
short
short
string
string
long
flags comments
-
-
Objects created:
ftbl (atp.fml_table)
ftbl.MESSAGE_TEXT (atp.fml_field)
ftbl.DEPTNUM (atp.fml_field)
ftbl.EMPLOYEE_NUMBER(atp.fml_field)
ftbl.JOBCODE (atp.fml_field)
ftbl.FIRST_NAME (atp.fml_field)
ftbl.LAST_NAME (atp.fml_field)
ftbl.SALARY (atp.fml_field)
ftbl.fields[0] to ftbl.fields[6] (atp.fml_field objects)
Example 2
The following script prints out all the atp.fml_field properties of an
atp.fml_table object:
ftbl = new atp.fml_table ("emp.tbl");
for (i=0; i<ftbl.fields.length; i++) {
fld = ftbl.fields[i];
atp.print (fld.name + ': type=' + fld.type_text + '\n');
}
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 42
atp.fml_buffer Object
ATP Objects, Properties, and Methods
Example 3
The following constructor creates an atp.fml_table object with an incomplete set
of fields:
ftbl = new atp.fml_table ("emp.tbl", "FIRST_NAME", "LAST_NAME");
Using the fml_table object - a bankapp Transaction...
var ftbl = new atp.fml_table('bank.flds');
var fbfr = new atp.fml_buffer('fml');
fbfr.setData ("10040",
fbfr.setData ("10041",
fbfr.setData ("200.99",
ftbl.ACCOUNT_ID, 0);
ftbl.ACCOUNT_ID, 1);
ftbl.SAMOUNT);
var tran = new atp.transaction ();
if (!fbfr.tpcall('TRANSFER', tran)) {
tran.rollback();
if (fbfr.error != 0)
return ('tpcall TRANSFER failed: ' + fbfr.error_text);
return (fbfr.reply.getData(ftbl.STATLIN));
}
tran.commit ();
atp.print ('Debit Account Balance: ' + fbfr.reply.getData(ftbl.SBALANCE) +
' ; Credit Account Balance: ' + fbfr.reply.getData(ftbl.SBALANCE, 1);
atp.fml_buffer Object
The fml_buffer object represents a FML or FML32 buffer. The tpcall() method
sends the buffer to a NonStop TUXEDO service.
Constructor
new atp.fml_buffer(fml_type [,buffer_size])
fml_type
This parameter specifies whether you want an FML or FML32 buffer. Specify the
string “fml” or “fml32”, depending on the requirements of the NonStop TUXEDO
service to which the buffer is to be sent.
buffer_size
This parameter specifies the size of the buffer. The default buffer size is 8192 bytes.
ATP automatically increases the size of the buffer as necessary, but it is more
efficient for the script to allocate a large enough buffer when creating the object.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 43
ATP Objects, Properties, and Methods
atp.fml_buffer Object
Properties
fml_type (read-only)
This property identifies the TUXEDO buffer type: either “fml” or “fml32”. If the
buffer represents a request, this type will always match the value supplied to the
constructor; if the buffer represents a reply, the type is determined by the service that
created the reply.
reply (read-only)
The tpcall() method sets this property. For successful requests, the property
contains an automatically created fml_buffer object, which is used to access and
process the application reply data.
view
The application sets this property to a TUXEDO view name to communicate with a
TUXEDO service that accepts only view buffers. ATP uses the TUXEDO FML
views interface to convert the data in the fml_buffer object to a view. If the response
is a view, it is converted also. This step requires that the relevant TUXEDO field
tables and view files be complete and that the needed TUXEDO environment
variables are specified in iTP Secure WebServer commands. The variables required
for this operation are FIELDTBLS, FLDTBLDIR, FIELDTBLS32,
FLDTBLDIR32, VIEWFILES, and VIEWDIR. On return from the tpcall()
method, the view property contains the name of the view returned by the TUXEDO
service. The service can also return an FML buffer.
user_return_code (read-only)
This property is the tpurcode returned by the TUXEDO service. It is set by the
tpcall() method.
error (read-only)
This property is the error number set by unsuccessful method calls. It reflects the
NonStop TUXEDO tperrno or Ferror (depending on the method).
error_text (read-only)
This property contains a string of error message text. It reflects the NonStop
TUXEDO tpstrerror or Fstrerror (depending on the method).
Methods
tpcall (service [,transaction])
This method sends the fml_buffer object's data to the identified TUXEDO service
(for example, TRANSFER). The method returns a value of false in any of the
following cases:
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 44
ATP Objects, Properties, and Methods
•
•
•
atp.fml_buffer Object
The TUXEDO tpcall fails
TMF problems occur
The TUXEDO application cannot be joined (tpinit())
To find out what type of error occurred, check the error property of the
atp.transaction object and the atp.fml_buffer object.
There is an implied join to the application on the first call to the tpcall() method
for a given atp server process. The implied underlying TUXEDO tpinit() call
uses default values of parameters unless one or more of the following environment
variables are configured using iTP Secure WebServer AddCGI commands or
provided with the request by means of a form or query URL:
TUXEDO_TPINIT_USRNAME
TUXEDO_TPINIT_CLTNAME
TUXEDO_TPINIT_GRPNAME
TUXEDO_TPINIT_PASSWD
TUXEDO_TPINIT_DATA
service
This parameter specifies the NonStop TUXEDO service to which the data is to
be sent. As a reply, the predefined service =loopback returns the same buffer
it received.
transaction
This parameter specifies an atp.transaction object under whose TMF
transaction the current operation should be initiated. If TM/MP (TMF)
protection is required, include a reference to an atp.transaction object.
setData(data, fml_field [,subscript])
This method puts data from the data parameter into the buffer.
data
This parameter is the data to be put into the buffer. Express the data as a string,
regardless of the data type it represents. (For example, it could represent a
floating point number.) To convert a value to a string, use the JavaScript
.toString feature.
Note. ATP does not validate application data, except to ensure that adjacent data, for
instance an adjacent column, is not corrupted. Your application must validate input
data for both type and range. Invalid data will cause unpredictable results.
Use the JavaScript keyword null as the value of the data parameter to delete
a field from the buffer. This method returns a value of true if the operation is
successful; it returns a value of false and sets the error property if the
operation is unsuccessful.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 45
ATP Objects, Properties, and Methods
atp.fml_buffer Object
fml-field
This parameter is an atp.fml_field object (which is a property of an
atp.fml_buffer object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the field ID, and other information
needed to convert and place the data item.
subscript
You can provide a subscript, as defined by NonStop TUXEDO; see the NonStop
TUXEDO man pages for information about subscript limits.
getData(fml_field [,subscript])
This method returns the data identified by the fml_field object and optional
subscript as a string. This method returns a value of true if the operation is
successful; it returns a value of false and sets the error property if the operation
is unsuccessful.
The value of the data is returned in string format, regardless of the application data
type. To perform computations with the value, use the JavaScript parseInt
feature.
fml-field
This parameter is an atp.fml_field object (which is a property of an
atp.fml_buffer object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the field ID, and other information
needed to convert the data item.
subscript
You can provide a subscript, as defined by NonStop TUXEDO; see the NonStop
TUXEDO man pages for information about subscript limits.
getOccurs(fml_field)
This method returns an integer count of the number of occurrences in the buffer of
the field identified by the fml_field object. A value of zero (0) indicates that the
field is not present in the buffer.
fml-field
This parameter is an atp.fml_field object (which is a property of an
atp.fml_buffer object, usually generated as a result of a field object
hierarchy). The field indicates the data type, the field ID, and other information
needed to identify the data item.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 46
ATP Objects, Properties, and Methods
Sockets Object
getMap(fml_table [,fml_table] [,fml_table] ...)
This method scans the buffer and returns an array of fml_field objects with one
element for each field (not field occurrence) in the buffer.
For example, this script prints out the names and values of fields in a buffer (fbfr).
All occurrences of subscripted fields are printed.
var emptbl=new atp.fml_table ("emp.tbl");
var systbl=new atp.fml_table ("Usysflds");
mapArray = fbfr.getMap (emptbl, systbl);
for (i=0; i < mapArray.length; i++) {
atp.print (mapArray[i].name+'\n');
fldocc = fbfr.getOccurs(mapArray[i]);
for (j=0; j < fldocc; j++)
þatp.print (fbfr.getData (mapArray[i], j) + '\n');
}
fml-table
This parameter contains a list of fml_field objects. The fml_table object
parameters are used, in the order specified, to find the matching fml_field
objects.
Sockets Object
This object enables you to develop scripts that use NonStop TCP/IP applications. For a
discussion and example of using these objects, see Using TCP/IP Sockets from
JavaScript on page 3-15.
atp.socket Object
The socket object represents a TCP/IP connection. The socket object allows the
JavaScript script to act as a TCP/IP sockets client. The object provides basic socketsclient functionality; some protocol options are not supported.
Note. The examples on the ATP product CD include a JavaScript class library that supports
parts of the HTTP protocol. See the iurlclass server-side include file.
Constructors
new atp.socket(remote_host,remote_port)
new atp.socket(remote_host,remote_port,tcp/ip_process)
new atp.socket(remote_host,remote_port,tcp/ip_process,
local_IP_address)
new atp.socket(remote_host,remote_port,tcp/ip_process,
local_IP_address,local_port)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 47
ATP Objects, Properties, and Methods
atp.socket Object
remote_host
This parameter specifies the host with which to establish the connection. The value
is a string in either numeric ("130.252.3.44") or alpha ("www.compaq.com") form.
remote_port
This parameter specifies the port number (for example, 8080).
tcp/ip_process
This parameter specifies the NonStop TCP/IP process name as a string (for example,
"$ztc4"). Use the keyword null (not quoted) to default. If the system
configuration includes a define for tcpip^process^name, that process name is
the default value; otherwise the system default applies.
local_IP_address
This parameter is a string that specifies the local address in numeric form (for
example, "12.13.14.15"). Use the keyword null (not quoted) to default to the local
address associated with the value of tcp/ip_process.
local_port
This parameter specifies the local port as a number (for example, 20000). Use 0
(zero) to select the next available port.
Properties
error (read-only)
This property contains the error code from invoked socket methods. The value is
zero (0) if no error occurred. Otherwise, the value is the error passed back from the
sockets API. See the TCP/IP and IPX/SPX Programming Manual for descriptions of
the errors.
error_text (read-only)
This property contains a text description of the latest error.
timeout (read-only)
This property indicates the timeout used for TCP/IP functions, in hundredths of a
second. Use the setSoTimeout() method to set this value. The default value is
3000 (30 seconds).
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 48
ATP Objects, Properties, and Methods
atp.socket Object
Methods
read([readcount])
This method reads readcount bytes from the socket and returns data in a string.
The method returns a value of null (a JavaScript reserved word) to indicate that
there is no more data. Thus, this method is usually invoked at least twice. For
example:
var str;
for (str=s.read(); str != null; str=s.read())
atp.print (str);
readcount
This parameter specifies the number of bytes to read. The default value is
15000; the maximum value is 15000.
write(string)
This method writes a string to the socket.
string
This parameter specifies the string to be written.
close()
This method closes the socket. If you do not call this method explicitly, ATP closes
the socket automatically at the end of the script.
setSoTimeout(timeout)
This method sets the timeout for subsequent socket methods.
timeout
This parameter specifies the timeout interval in hundredths of a second.
setSoKeepAlive()
This method enables TCP/IP keep-alive messages to ensure that a socket connection
does not time out.
setTcpNoDelay()
This method minimizes buffering of outbound (write) data within TCP/IP. For more
information, see the description of the socket option in the TCP/IP and IPX/SPX
Programming Manual.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 49
ATP Objects, Properties, and Methods
Global Functions
Global Functions
The following functions are useful for many kinds of scripts:
atp.execute (path)
This method calls an ATP file and processes it as if it were part of the calling ATP script.
The atp.execute method is similar and is an alternative to the server-side include tag.
The path parameter must be specified. This is a string specifying the location of the ATP
file to execute. The path must be relative to the calling page.
The atp.execute method provides a way for you to divide a complex application into
individual modules. Using this method you can develop a library of ATP files that you
can call as needed. After ATP processes the specified file, the response is returned to the
calling ATP script.
The following example demonstrates executing an ATP file that returns some text.
The text to be returned is
I am at Page One
I am at Page Two
I am back at Page One again
The code fragments are:
Page1.atp
<HTML><BODY>
<server>
atp.print (“I am at Page One <BR>”);
atp.execute (“Page2.atp”);
atp.print (“I am back at Page One again <BR>”);
...
Page2.atp
<% atp.print (“I am at Page Two<BR>”)%>
atp.print(JavaScript_expression)
This function is used to output results from the server-side script. The output from the
script logically replaces the script within the .atp page as the page is processed. The
web browser sees only the output of a server-side script, not the script itself.
You can use HTML in the clear in your script. Do not use the atp.print function to send
the HTML to the browser. ATP automatically sends the HTML to the browser more
efficiently than your script can do it using atp.print.
atp.println()
This function is the same as the atp.print function, except that it prints an extra new line.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 50
ATP Objects, Properties, and Methods
Global Functions
atp.quit(integer)
This function stops processing of the current .atp page and flushes all output to the
web browser. A zero (0) parameter indicates failure; in such cases, a JavaScript alert
message is also displayed. A non-zero parameter indicates that no alert message should
be displayed. The default value for the parameter is zero (0).
return = atp.escape (string)
This function modifies a string by replacing each special character with its hexadecimal
equivalent in the form %xx to allow the use of the string in a query URL.
The following function (not part of ATP) would have the reverse effect, replacing a
hexadecimal number with the corresponding special character:
<server>
function unescape (s) {
var i;
var str_out;
str_out = '';
for (i=0; i<s.length; i++) {
var c;
c = s.substring(i,i+1);
if (c.indexOf('%') == 0)
str_out += '\\x';
else
str_out += c;
}
str_out = eval ('"'+str_out+'"');
return str_out;
}
atp.print
(unescape(‘add%20define%20%3demployee%20class%20%20map%3b’));
</server>
return = atp.formatMoney(format, amount)
This function formats a number according to local currency conventions. The format
parameter follows the conventions used by the C language library strfmon() routine.
In ATP the format parameter is ignored. The format of the result has two places after
the decimal point and contains no commas; for example, if you supplied the amount
2345, the function would return the value 2345.00.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 51
ATP Objects, Properties, and Methods
Global Functions
ATP_DISABLE_BACKQUOTE
Although backquotes can be used instead of the <server> and </server> tags, Compaq
does not recommend this practice. Use a different delimiter to mark the server-side
script boundaries instead of the backquote, especially if you use double-byte character
sets to represent languages such as Kanji, because the backquote character frequently
appears in those representations.
You can use the ATP_DISABLE_BACKQUOTE global variable to disable and enable
the backquote tags on all pages for all instances of atp.pway. The default value is OFF.
To disable the backquote add a directive similar to the following example:
Region /newscripts/* {AddCGI ATP_DISABLE_BACKQUOTE 1}
Note that this is a global setting. To override this global setting or provide its
functionality within a page or on a page-by-page basis, consult the Meta Tag Used for
MultiByte Support.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
4- 52
5
XML for ATP Add-On Module
The optional XML for ATP add-on module provides a standardized way to access and
manipulate the information stored in XML documents. The Document Object Model
(DOM) Objects API serves as a bridge between applications and XML documents,
enabling applications to work with XML document structures and information as
program structures rather than as text streams. Applications and scripts can read and
manipulate these structures without knowing the details of XML syntax.
The DOM uses two key abstractions: a tree-like hierarchy and nodes that represent
document content and structures. In other words, the DOM model provides a generic
container, the node, that can be used to represent elements, attributes, textual contents,
comments, and so forth. Each node type has different access methods and content
limitations.
Table 5-1 shows the types of nodes and related objects defined in the XML for ATP
DOM objects library. Each object is then described, along with the properties and
methods that are unique to that object only.
Table 5-1. XML for ATP DOM Objects (page 1 of 2)
Object
Description
XMLDOMNode Object
The primary data type for the entire document object
model, this object represents a single node in the
document tree. The actual type of the node is
determined by the property nodeType.
DOMDocument Object
Represents the top node of the XML for ATP DOM
tree.
XMLDOMParseError Object
Returns detailed information about the last error,
including the error number, line number, character
position, and a text description.
XMLDOMNodeList Object
Supports iteration and indexed access operations on
the live collection of XMLDOMNode objects.
XMLDOMNamedNodeMap
Object
Provides iteration and access by name to the
collection of attributes. This interface includes
support for namespaces.
XMLDOMAttribute Object
Represents an attribute object.
XMLDOMElement Object
Represents the element object.
XMLDOMDocumentFragment
Object
Represents a lightweight object that is useful for tree
insert operations.
XMLDOMDocumentType Object
Contains information associated with the document
type declaration.
XMLDOMEntity Object
Represents a parsed or unparsed entity in the XML
document.
XMLDOMEntityReference
Object
Represents an entity reference node.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -1
XMLDOMNode Object
XML for ATP Add-On Module
Table 5-1. XML for ATP DOM Objects (page 2 of 2)
Object
Description
XMLDOMImplementation Object Provides methods that are independent of any
particular instance of the document object model.
XMLDOMNotation Object
Contains a notation declared in the document type
definition (DTD) file or XML schema.
XMLDOMProcessingInstruction
Object
Represents a processing instruction, which XML
defines to keep processor-specific information in the
text of the document.
XMLDOMCharacterData Object
Quotes or escapes blocks of text so that text is not
interpreted as markup language.
XMLDOMComment Object
Represents the content of an XML comment.
XMLDOMText Object
Represents the text content of an element or attribute.
XMLDOMCDATASection Object
Refers to the data from an XML CDATA section.
XMLDOMNode Object
The XMLDOMNode object is the principal object within the Document Object Model
(DOM). Elements, attributes, comments, processing instructions, and every other
document component can be represented as an XMLDOMNode object. The
DOMDocument Object is itself an XMLDOMNode object, as are the members of node
lists and named node maps.
Table 5-2 specifies the common properties of XMLDOMNode and other DOM objects.
Table 5-2. Common Properties of XMLDOMNode and Other DOM
Objects (page 1 of 2)
Property
Description
attributes
Contains an XMLDOMNamedNodeMap Object, which stores
all attributes of this node.
childNodes
Contains an XMLDOMNodeList Object, which stores all
children of this node.
firstChild
Contains the first child of this node.
lastChild
Contains the last child of this node.
nextSibling
Contains the node immediately following this node in the
parent’s child list.
nodeName
Contains the name of this document.
nodeType
Specifies the XMLDOM node type, which determines valid
values and whether the node can have child nodes.
nodeValue
Contains the text value associated with the node.
ownerDocument
Returns the root of the document that contains this node.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -2
Properties
XML for ATP Add-On Module
Table 5-2. Common Properties of XMLDOMNode and Other DOM
Objects (page 2 of 2)
Property
Description
parentNode
Contains the parent node (for nodes that can have parents).
previousSibling
Contains the node immediately preceding this node in the
parent’s child list.
xml
Contains the XML representation of the node and all its
descendants.
Table 5-3 specifies the common methods of XMLDOMNode and other DOM objects.
Table 5-3. Common Methods of XMLDOMNode and Other DOM Objects
Method
Description
appendChild
Adds newChild to the end of the list of children of this node.
cloneNode
Serves as a generic copy constructor for nodes.
hasChildNodes
Provides a convenient method to allow easy determination of
whether a node has any children.
insertBefore
Inserts the node newChild before the existing child node
refChild.
removeChild
Removes the child node indicated by oldChild from the list
of children, and returns it.
replaceChild
Replaces the child node oldChild with newChild in the
list of children and returns the oldChild node.
Properties
attributes
Contains an XMLDOMNamedNodeMap Object, which stores all the attributes of
this node if it is an element or null if it is unspecified.
Remarks
Object. Read-only.
Syntax
var objNamedNodeMap = oNode.attributes
Example
var domDoc = new XML.DOMDocument;
domDoc.load("sample.xml");
var mapNodes = domDoc.documentElement.attributes;
println(“total attributes = “ + mapNodes.length);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -3
XML for ATP Add-On Module
Properties
Output
total attributes = 0
childNodes
Gets a node list that contains all children of this node. If there are no children, this is
an XMLDOMNodeList Object that contains no nodes. The content of the returned
object is “live” in the sense that, for instance, changes to the children of the node
object that it was created from are immediately reflected in the nodes returned by
the XMLDOMNodeList accessors; in other words, it is not a static snapshot of the
content of the node. This is true for every XMLDOMNodeList object, including the
ones returned by the getElementsByTagName method.
Remarks
Object (XMLDOMNodeList Object). Read-only.
Syntax
var oNodeList = oNode.childNodes
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var children = root.childNodes;
println("There are " + children.length + " childNodes");
Output
There are 5 childNodes
firstChild
Gets the first child of this node, or null if it is unspecified.
Remarks
Object (XMLDOMNode Object). Read-only.
Syntax
var oNode = oNode. firstChild
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
println("firstChild nodeName: " + root.firstChild.nodeName);
Output
firstChild nodeName: student
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -4
XML for ATP Add-On Module
Properties
lastChild
Gets the last child of this node, or null if it is unspecified.
Remarks
Object (XMLDOMNode Object). Read-only.
Syntax
var oNode = oNode.lastChild
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var last = root.lastChild;
var idNode = last.childNodes.item(0);
print("lastChild ")
println(idNode.nodeName + " = " +
idNode.childNodes.item(0).nodeValue);
Output
lastChild name = John Martin
namespaceURI
Gets the namespace URI of this node, or null if it is unspecified.
This is not a computed value that is the result of a namespace lookup based on an
examination of the namespace declarations in scope. It is merely the namespace URI
given at creation time.
For nodes of any type other than XMLDOMElement and XMLDOMAttribute and
nodes created with a DOM level-1 method, such as createElement from the
DOMDocument, this is always returned null. This property is a level-2 extension of
the W3C DOM.
Data Type
String. Read-only.
Syntax
var strURI = oNode.namespaceURI
nextSibling
Gets the node immediately following this node, or null if it is unspecified.
Remarks
Object (XMLDOMNode Object). Read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -5
Properties
XML for ATP Add-On Module
Syntax
var oNode = oNode.nextSibling
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var next = root.firstChild.nextSibling;
print("nextSibling: " + next.childNodes.item(0).nodeName + "
= ");
println(next.childNodes.item(0).childNodes.item(0).nodeValue;
Output
nextSibling: name = Lily Ramos
nodeName
Gets the name of this node. The nodeName value varies as follows, depending on
the nodeType property.
Node Type
Node Name
NODE_ATTRIBUTE
Contains the name of the attribute
NODE_CDATA_SECTION
Contains the literal string "#cdata-section"
NODE_COMMENT
Contains the literal string "#comment"
NODE_DOCUMENT
Contains the literal string "#document"
NODE_DOCUMENT_TYPE
Contains the name of the document type; for
example, xxx in <!DOCTYPE xxx ...>
NODE_DOCUMENT_FRAGMENT
Contains the literal string "#documentfragment"
NODE_ELEMENT
Contains the name of the XML tag, with any
namespace prefix included, if present
NODE_ENTITY
Contains the name of the entity
NODE_ENTITY_REFERENCE
Contains the name of the entity referenced.
Note that the name does not include the
leading ampersand or the trailing semicolon.
The name includes the namespace if one is
present
NODE_NOTATION
Contains the name of the notation
NODE_PROCESSING_INSTRUCTION
Contains the target; the first token following
the <? characters
NODE_XMLDECL
Contains the literal string "#xmldecl"
NODE_TEXT
Contains the literal string "#text"
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -6
Properties
XML for ATP Add-On Module
Remarks
String. Read-only and always contains a non-empty string.
Syntax
var strName = oNode.nodeName
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
println("nodeName = " + root.nodeName);
Output
nodeName = class99
nodeType
Gets an enum value representing the type of the underlying object. The
DOMNodeType enumeration defines the following valid values that can appear in
the nodeType property.
Node Type
Value
NODE_ELEMENT
1
NODE_ATTRIBUTE
2
NODE_TEXT
3
NODE_CDATA_SECTION
4
NODE_ENTITY_REFERENCE
5
NODE_ENTITY
6
NODE_PROCESSING_INSTRUCTION
7
NODE_COMMENT
8
NODE_DOCUMENT
9
NODE_DOCUMENT_TYPE
10
NODE_DOCUMENT_FRAGMENT
11
NODE_NOTATION
12
NODE_XMLDECL
13
Remarks
Enumeration. Read-only.
Syntax
var intType = oNode.nodeType
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -7
Properties
XML for ATP Add-On Module
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
println("nodeType = " + root.nodeType);
Output
nodeType = 1
nodeValue
Gets the value of this node.
Node Type
NodeValue
NODE_ELEMENT
null, read/write
NODE_ATTRIBUTE
attribute value, read-only
NODE_TEXT
text node content, read-only
NODE_CDATA_SECTION
CDATA section content, read-only
NODE_ENTITY_REFERENCE
null, read/write
NODE_ENTITY
null, read/write
NODE_PROCESSING_INSTRUCTION
entire content, excluding the target,
read-only
NODE_COMMENT
comment content, read-only
NODE_DOCUMENT
null, read/write
NODE_DOCUMENT_TYPE
null, read/write
NODE_DOCUMENT_FRAGMENT
null, read/write
NODE_XMLDECL
null, read/write
NODE_NOTATION
null, read/write
Remarks
String. Read-only, read/write, or null.
Syntax
var strValue = oNode.nodeValue
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the nodeValue attribute is read-only for this DOM object type.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -8
XML for ATP Add-On Module
•
Properties
DOMSTRING_SIZE_ERR(2): This error-detail code indicates that the value
that would be returned is too large to be contained by a string type in the given
implementation.
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var node =
root.childNodes.item(0).childNodes.item(0).firstChild;
println("nodeValue = " + node.nodeValue);
Output
nodeValue = Jenny Mabry
ownerDocument
Gets the DOMDocument Object associated with this node. This is also the
DOMDocument object used to create new nodes. When this node is a
DOMDocument Object or an XMLDOMDocumentType Object that is not used with
any DOMDocument yet, this is null.
Remarks
Object (DOMDocument Object). Read-only.
Syntax
var oNode = oNode.ownerDocument
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
println("OwnerDocument = " + root.ownerDocument.nodeName);
Output
OwnerDocument = #document
parentNode
Gets the parent of this node. All nodes except for DOMDocument Object,
XMLDOMDocumentFragment Object, and XMLDOMAttribute Object can have a
parent. However, if a node has just been created and not yet added to the tree, or if it
has been removed from the tree, a null is returned.
Remarks
Object (XMLDOMNode Object). Read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5 -9
XML for ATP Add-On Module
Properties
Syntax
var oNode = oNode.parentNode
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var node = root.childNodes.item(0);
println("ParentNode=" + node.parentNode.nodeName);
Output
ParentNode=class99
prefix
Gets the namespace prefix of this node. This is a DOM level-2 property. It is not
fully supported by current Xerces C++ library.
Remarks
String. Read-only.
Syntax
var oNode = oNode.prefix
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var node = doc.documentElement.childNodes.item(0);
println(“OwnerDocument = “ + node.ownerDocument.prefix);
previousSibling
Gets the node immediately preceding this node. If there is no such node, this returns
null.
Remarks
Object (XMLDOMNode Object). Read-only.
Syntax
var oNode = oNode.previousSibling
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
println("previousSibling = " +
root.previousSibling.nodeName);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 10
XML for ATP Add-On Module
Methods
Output
previousSibling = #comment
xml
Contains the string representation of the node and all its descendents.
Remarks
String. Read-only.
Syntax
var strValue = oNode.xml
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = false;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var node = root.childNodes.item(1);
println(node.xml);
Output
<student id="NUM16001">
<name>Jenny Mabry</name>
<department>Computer Science</department>
<GPA>3.6</GPA>
<gender>Female</gender>
<address street="Yes" permanent="Yes">1010 Fargo Drive,
Cupertino, California 95014 </address>
</student>
Methods
appendChild
Adds a new node to the end of the list of children of this node. If the newChild is
already in the tree, it is first removed.
Syntax
var oReturn = oNode.appendChild(newChild)
Parameters
newChild – The node to add. If it is an XMLDOMDocumentFragment Object, the
entire contents of the document fragment are moved into the child list of this node.
Return Value
oReturn – The new child node successfully appended to the list.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 11
XML for ATP Add-On Module
Methods
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
•
HIERARCHY_REQUEST_ERR(3): Raised if this node is of a type that does
not allow children of the type of the newChild node, or if the node to append is
one of this node’s ancestors.
WRONG_DOCUMENT_ERR(4): Raised if newChild was created from a
different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR(7): Raised if this node or the node
being appended is read-only.
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var newNode = domDoc.createNode(1, "newNode");
root.appendChild(newNode);
println("There are " + root.childNodes.length + "
childNodes");
Output
There are 6 childNodes
cloneNode
Returns a duplicate of this node. The duplicate node has no parent. Cloning an
XMLDOMElement Object copies all attributes and their values, including those
generated by the XML processor to represent defaulted attributes, but this method
does not copy any text it contains unless it is a deep clone, since the text is
contained in a child text node. Cloning any other type of node simply returns a copy
of this node.
Syntax
var oClone = oNode.cloneNode(deep)
Parameters
deep – if true, recursively clone the subtree under the specific node; if false, clone
only the node itself (and its attributes, if it is an XMLDOMElement Object).
Return Value
oClone – The duplicate node.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 12
XML for ATP Add-On Module
Methods
Example
var domDoc = new XML.DOMDocument;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var node = root.childNodes.item(1);
var newNode = node.cloneNode(true);
println(newNode.xml);
Output
<student id="NUM16001">
<name>Jenny Mabry</name>
<department>Computer Science</department>
<GPA>3.6</GPA>
<gender>Female</gender>
<address street="Yes" permanent="Yes">1010 Fargo Drive,
Cupertino, California 95014 </address>
</student>
hasChildNodes
This is a convenient method to allow easy determination of whether a node has any
children.
Syntax
var bHas = oNode.hasChildNodes()
Parameters
None.
Return Value
true if the node has any children, false if the node has no children.
Example
var domDoc = new XML.DOMDocument;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
println("Does root have childNodes? " +
root.hasChildNodes());
Output
Does root have childNodes? true
insertBefore
Inserts a new node before the existing child node. If refChild is null, this inserts
newChild at the end of the list of children. If newChild is an
XMLDOMDocumentFragment Object, all of its children are inserted, in the same
order, before refChild. If the newChild is already in the tree, it is first
removed. Note that an XMLDOMNode Object that has never been assigned to refer
to an actual node is null.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 13
XML for ATP Add-On Module
Methods
Syntax
var oNewNode = oNode.insertChild(newChild, refChild)
Parameters
newChild – The node to insert.
refChild – The reference node, which is the node before which the new node
must be inserted.
Return Value
oReturn – The new child node being inserted.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
•
•
HIERARCHY_REQUEST_ERR(3): Raised if this node is of a type that does
not allow children of the type of the newChild node, or if the node to insert is
one of this node’s ancestors.
WRONG_DOCUMENT_ERR(4): Raised if newChild was created from a
different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR(7): Raised if this node or the node
being appended is read-only.
NOT_FOUND_ERR(8): Raised if refChild is not a child of this node.
Example
var domDoc = new XML.DOMDocument;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var node = root.childNodes.item(1);
var newNode = domDoc.createNode(1, "newNode");
node.insertBefore(newNode, node.childNodes.item(1));
println(node.xml);
Output
<student id="NUM16001">
<newNode/><name>Jenny Mabry</name>
<department>Computer Science</department>
<GPA>3.6</GPA>
<gender>Female</gender>
<address street="Yes" permanent="Yes">1010 Fargo Drive,
Cupertino, California 95014 </address>
</student>
removeChild
Removes the child node indicated by oldChild from the list of children, and
returns it.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 14
XML for ATP Add-On Module
Methods
Syntax
var oRemoveNode = oNode.removeChild(oldChild)
Parameters
oldChild – The node to remove.
Return Value
oRemoveNode – The node removed.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
NO_MODIFICATION_ALLOWED_ERR(7) – Raised if this node or the node
being appended is read-only.
Example
var domDoc = new XML.DOMDocument;
domDoc.validateOnParse = true;
domDoc.load("sample.xml");
var root = domDoc.documentElement;
var oldChild = root.removeChild(root.childNodes.item(1));
println("There are " + root.childNodes.length + "
childNodes");
Output
There are 4 childNodes
replaceChild
Replaces the child node oldChild with newChild in the list of children, and
returns the oldChild node. If newChild is an XMLDOMDocumentFragment
Object, oldChild is replaced by all of the XMLDOMDocumentFragment
children, which are inserted in the same order. If newChild is already in the tree, it
is first removed.
Syntax
var oReplaced= oNode.replaceChild(newChild, oldChild)
Parameters
newChild – The new node to put in the child list.
oldChild – The node being replaced in the list.
Return Value
oReturn – The node replaced.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 15
DOMDocument Object
XML for ATP Add-On Module
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
•
•
HIERARCHY_REQUEST_ERR(3): Raised if this node is of a type that does
not allow children of the type of the newChild node, or if the node to insert is
one of this node’s ancestors.
WRONG_DOCUMENT_ERR(4): Raised if newChild was created from a
different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR(7): Raised if this node or the parent
of the new node is read-only.
NOT_FOUND_ERR(8): Raised if oldChild is not a child of this node.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var newNode = doc.createElement(“REPLACE”);
root.replaceChild(newNode, root.childNodes.item(2));
DOMDocument Object
The DOMDocument object acts as the root node for all of the other nodes in the DOM
tree. It contains the root element of the document, as well as information from before the
root element and after the end of the root element.
The DOMDocument node can contain multiple XMLDOMProcessingInstruction Object
and XMLDOMComment Object nodes, and one each of the XMLDOMElement Object
and XMLDOMDocumentType Object nodes. These nodes are treated as children, and
appear in the same sequence in which they appeared in the original XML document.
The DOMDocument object is the only one that can be created among XMLDOM
objects by the new operator; all other objects are accessed or created from the document.
Table 5-4 specifies the additional common properties of the DOMDocument object.
Table 5-4. DOMDocument Object Properties (page 1 of 2)
Property
Description
doctype
Contains the document type node that specifies the DTD for
this document.
documentElement
Contains the root element of the document.
implementation
Contains an XMLDOMImplementation Object for this
document.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 16
DOMDocument Object
XML for ATP Add-On Module
Table 5-4. DOMDocument Object Properties (page 2 of 2)
Property
Description
parseError
Returns an XMLDOMParseError Object that contains
information about the last parsing error.
preserveWhiteSpace
Specifies true if default processing preserves white space;
false otherwise.
validateOnParse
Indicates whether the parser should validate this document.
Table 5-5 specifies the common methods of the DOMDocument object.
Table 5-5. DOMDocument Object Methods
Method
Description
createAttribute
Creates an attribute node (XMLDOMAttribute Object) of the
given name.
createCDATASection
Creates a CDATA Section node (XMLDOMCDATASection
Object) whose value is the specified string.
createComment
Creates a Comment node (XMLDOMComment Object) given
the specified string.
createDocumentFragment
Creates an empty document fragment node
(XMLDOMDocumentFragment Object).
createElement
Creates an element of the type specified.
createEntityReference
Creates an entity reference node (XMLDOMEntityReference
Object).
createNode
Creates a node using the supplied type, name, and namespace.
createProcessingInstruction
Creates a processing instruction node
(XMLDOMProcessingInstruction Object) given the specified
name and data string.
createTextNode
Creates a text node (XMLDOMText Object) given the
specified string.
getElementsByTagName
Returns an XMLDOM node list (XMLDOMNodeList Object)
of all the elements with a given tag name.
load
Loads an XML document from the specified location.
loadXML
Loads an XML document using the supplied string.
nodeFromID
Returns the node whose ID attribute matches the supplied
value.
save
Saves an XML document to the specified location.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 17
XML for ATP Add-On Module
Properties
Properties
doctype
Gets the Document Type Declaration (DTD) associated with this document. For
documents without a document type declaration, this returns a null reference object.
The DOM Level 1 does not support editing the Document Type Declaration,
therefore doctype cannot be altered in any way.
Remarks
Object (XMLDOMDocumentType Object). Read-only.
Syntax
var oNode = domDoc.doctype
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
println("Document type name= " + doc.doctype.name);
Output
Document type name= class99
documentElement
Contains the root element of the document. This property returns the root element of
the XML document tree, or null if no root exists.
Remarks
Object (XMLDOMElement Object). Read-only.
Syntax
var objElement = domDoc.documentElement
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
println(doc.documentElement.nodeName);
Output
class99
implementation
Contains the XMLDOMImplementation Object of the document.
Remarks
Object (XMLDOMImplementation Object). Read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 18
XML for ATP Add-On Module
Properties
Syntax
var objImplementation = domDoc.implementation
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
println(doc.implementation.hasFeature("XML", "1.0"));
Output
true
parseError
Returns an XMLDOMParseError object that contains information about the last
parsing error. The returned object is always a valid object. This is an extension of
the W3C DOM.
Remarks
Object (XMLDOMParseError). Read-only.
Syntax
var objParseError = domDoc.parseError
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var err = doc.parseError;
println("errorCode = " + err.errorCode);
Output
errorCode = 0
preserveWhiteSpace
Contains the “include ignorable whitespace” flag for the DOM parser. When set to
true, all ignorable white spaces will be added to the DOM tree as text nodes.
When set to false, all ignorable white spaces will be discarded and no text node is
added to the DOM tree. The default value is false. Applications intended to
process the “xml:space” attribute should not set this flag to false.
This property is applicable only when the DTD is defined in the DOMDocument
Object.
Remarks
Boolean. Read/write.
Syntax
var objElement = domDoc.preserveWhiteSpace
domDoc.preserveWhiteSpace = true|false
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 19
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.preserveWriteSpace = false;
doc.load("sample.xml");
println(doc.documentElement.childNodes.length);
Output
5
validateOnParse
Indicates whether the parser should validate this document. When set to true, it
enables the parser’s validation checks; when set to false, it disables the check.
The default value is false.
This property is applicable only when the DTD is defined in the DOMDocument
Object.
Remarks
Boolean. Read/write.
Syntax
var boolValue = domDoc.validateOnParse
domDoc.validateOnParse = true|false
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
println(doc.documentElement.childNodes.length);
Output
5
Methods
createAttribute
Creates a new XMLDOMAttribute Object with the specified name or the optional
namespace. Creating an attribute with this method is the same as using createNode
where the type parameter value is NODE_ATTRIBUTE.
Syntax
objAttribute = doc.createAttribute(name[,namespaceURI]);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 20
XML for ATP Add-On Module
Methods
Parameters
name – The name of the attribute.
namespaceURI (optional) – The namespace URI of the attribute to create.
Return Value
objAttribute – XMLDOMAttribute Object.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INVALID_CHARACTER_ ERR(5): Raised if the specified qualified name
contains an invalid character.
NAMESPACE_ERR(14): The name is malformed if:
° The name has a prefix and the namespaceURI is null or an empty string
° The name has a prefix that is “xml” and the namespaceURI is different from
“http://www.w3.org/XML/1998/namespace”
° The name has a prefix that is “xmlns” and the namespaceURI is different
from “http://www.w3.org/2000/xmlns/”
° The name is “xmlns” and the namespaceURI is different from
“http://www.w3.org/2000/xmlns/”
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(0).childNodes.item(0);
var newAttr = doc.createAttribute("status");
newAttr.nodeValue = "new";
node.setAttributeNode(newAttr);
println(node.xml);
Output
<name status="new">Jenny Mabry</name>
createCDATASection
Creates an XMLDOMCDATASection Object that contains the supplied data.
Creating a CDATA section with this method is the same as using createNode where
the type parameter value is NODE_CDATA_SECTION and no namespace is
specified. Although this method creates the new object in the context of this
document, it does not automatically add the new object to the document tree.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 21
XML for ATP Add-On Module
Methods
Syntax
objCDATASection = doc.createCDATASection(data);
Parameters
data – The data for CDATA section contents.
Return Value
objCDATASection – XMLDOMCDATASection Object.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
NOT_SUPPORTED_ERR(9): Raised if this document is an HTML document.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(0).childNodes.item(0);
var newCDATA = doc.createCDATASection("New CDATA Section");
node.appendChild(newCDATA);
println(node.xml);
Output
<name>Jenny Mabry<![CDATA[New CDATA Section]]></name>
createComment
Creates a XMLDOMComment Object node that contains the supplied data. Creating
a comment with this method is the same as using createNode where the type
parameter value is NODE_COMMENT and no namespace is specified. Although
this method creates the new object in the context of this document, it does not
automatically add the new object to the document tree.
Syntax
objComment = doc.createComment(data);
Parameters
data – String specifying the value to be supplied to the new XMLDOMComment
Object nodeValue property.
Return Value
objComment – XMLDOMComment Object.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 22
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(0).childNodes.item(0);
var comment = doc.createComment("New Comment");
node.appendChild(comment);
println(node.xml);
Output
<name>Jenny Mabry<!--New Comment--></name>
createDocumentFragment
Creates an empty XMLDOMDocumentFragment Object node. Creating a document
fragment with this method is the same as using createNode where the type
parameter value is NODE_DOCUMENT_FRAGMENT and no namespace is
specified. Although this method creates the new object in the context of this
document, it does not automatically add the new object to the document tree.
Syntax
objFragment = doc.createDocumentFragment();
Parameters
None.
Return Value
objFragment – XMLDOMDocumentFragment Object.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var fragment = doc.createDocumentFragment();
println(fragment.nodeType);
Output
11
createElement
Creates an element using the supplied name and namespace. Creating an element
with this method is the same as using createNode where the type parameter value is
NODE_ELEMENT. Although this method creates the new object in the context of
this document, it does not automatically add the new object to the document tree.
Syntax
objElement = doc.createElement(tagName[, namespaceURI]);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 23
XML for ATP Add-On Module
Methods
Parameters
tagName – The name of the element type to instantiate.
namespaceURI (optional) – The namespace URI of the element to create.
Return Value
objElement – XMLDOMElement Object.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INVALID_CHARACTER_ ERR(5): Raised if the specified qualified name
contains an invalid character.
NAMESPACE_ERR(14): The name is malformed if:
° The name has a prefix and the namespaceURI is null or an empty string
° The name has a prefix that is “xml” and the namespaceURI is different from
“http://www.w3.org/XML/1998/namespace”
° The name has a prefix that is “xmlns” and the namespaceURI is different
from “http://www.w3.org/2000/xmlns/”
° The name is “xmlns” and the namespaceURI is different from
“http://www.w3.org/2000/xmlns/”
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(0).childNodes.item(0);
var elem = doc.createElement("newElement");
node.appendChild(elem);
println(node.xml);
Output
<name>Jenny Mabry<newElement/></name>
createEntityReference
Creates a new XMLDOMEntityReference Object. Creating an entity reference with
this method is the same as using createNode where the type parameter value is
NODE_ENTITY_REFERENCE. Although this method creates the new object in the
context of this document, it does not automatically add the new object to the
document tree.
Syntax
objEntityRef = doc.createEntityReference(name);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 24
Methods
XML for ATP Add-On Module
Parameters
name – String specifying the name of the entity referenced. This name is
subsequently available as the new object’s nodeName property.
Return Value
objEntityRef – XMLDOMEntityReference Object.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
INVALID_CHARACTER_ ERR(5): Raised if the specified qualified name
contains an invalid character.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(0).childNodes.item(0);
var ref = doc.createEntityReference("newRef");
println("name = " + ref.nodeName + "; type = " +
ref.nodeType);
Output
name = newRef; type = 5
createNode
Creates a node using the supplied type, name, and namespace. The name parameter
depends on the value of the type parameter. The relations between node name and
node type are summarized below.
Node Type
Name
NODE_ATTRIBUTE
The name of the attribute.
NODE_CDATA_SECTION,
NODE_COMMENT,
NODE_DOCUMENT_FRAGMENT,
NODE_TEXT
The nodeName property for these node
types is a constant value; the name
parameter is ignored.
NODE_ELEMENT
The name of the XML tag.
NODE_ENTITY_REFERENCE
The name of the entity referenced.
NODE_PROCESSING_INSTRUCTION
The target. The namespaceURI here is for
processing instruction content.
You cannot create a node of type NODE_DOCUMENT,
NODE_DOCUMENT_TYPE, or NODE_ENTITY. An attempt to do this generates
an ATP_ERR_DOM_INVALID_NOTE_TYPE(3) error.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 25
XML for ATP Add-On Module
Methods
Syntax
oNode = doc.createNode(type, name[, namespaceURI]);
Parameters
type – XMLDOMNodeType enumeration value.
name – String containing the value for the new node’s nodeName property.
namespaceURI (optional) – The namespace URI of the element to create.
Return Value
oNode – XMLDOMNode Object.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INVALID_CHARACTER_ ERR(5): Raised if the specified qualified name
contains an invalid character.
NAMESPACE_ERR(14): The name is malformed if:
° The name has a prefix and the namespaceURI is null or an empty string
° The name has a prefix that is “xml” and the namespaceURI is different from
“http://www.w3.org/XML/1998/namespace”
° The name has a prefix that is “xmlns” and the namespaceURI is different
from “http://www.w3.org/2000/xmlns/”
° The name is “xmlns” and the namespaceURI is different from
“http://www.w3.org/2000/xmlns/”
Example
The following example creates an attribute node NewAttr and adds it to the
attributes for the DOMDocument Object:
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var newNode = doc.createNode(1, "newNode");
println(newNode.xml);
Output
<newNode/>
createProcessingInstruction
Creates a XMLDOMProcessingInstruction Object node given the specified name
and data strings.
Creating a processing instruction with this method is the same as using createNode,
where the type parameter value is NODE_PROCESSING_INSTRUCTION.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 26
XML for ATP Add-On Module
Methods
Although this method creates the new object in the context of this document, it does
not automatically add the new object to the document tree.
Syntax
objInstruction = doc.createProcessingInstruction(target, data);
Parameters
target – The target part of the processing instruction.
data – The data for the node.
Return Value
objInstruction – XMLDOMProcessingInstruction Object.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
INVALID_CHARACTER_ ERR(5): Raised if the specified qualified name
contains an invalid character.
Example
The following example generates the processing instruction
<?XML version="1.0"?>, in which the target string is XML and the data string
is version="1.0":
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var instruction = doc.createProcessingInstruction("xml",
"version=\"1.0\"");
println(instruction.xml);
Output
<?xml version="1.0"?>
createTextNode
Creates a XMLDOMText Object node that contains the supplied data. Creating a
text node with this method is the same as using createNode where the type
parameter value is NODE_TEXT and no namespace is specified. Although this
method creates the new object in the context of this document, it does not
automatically add the new object to the document tree.
Syntax
objText = doc.createTextNode(data);
Parameters
data – String specifying the value to be supplied to the new XMLDOMText
object’s nodeValue property.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 27
XML for ATP Add-On Module
Methods
Return Value
objText – XMLDOMText Object.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(0).childNodes.item(0);
var text = doc.createTextNode("New Text");
println(text.xml);
Output
New Text
getElementsByTagName
Returns an XMLDOM node list of all the elements with a given tag name. The
returned node list is “live,” in that changes to the document tree made after a
nodelist is initially returned are immediately reflected in the node list. The elements
in the node list are returned in the same order in which they would be encountered in
a preordered traversal of the document tree.
Syntax
oNodeList = doc.getElementsByTagName(tagName [, namespaceURI]);
Parameters
tagName – String specifying the name of the tag to match on. The special value
“*” matches all tags.
namespaceURI – The namespace URI of the elements to match on. The special
value "*" matches all namespaces.
Return Value
An XMLDOMNodeList Object that contains all the matched XMLDOMElement
Objects.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var list = doc.getElementsByTagName("student");
println(list.length);
Output
5
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 28
XML for ATP Add-On Module
Methods
load
Loads an XML document from a file. Calling load or loadXML immediately
discards the content of the existing document. This method is an extension of the
W3C DOM.
Syntax
boolValue = doc.load(filename|atp.request);
Parameters
filename – String that specifies the name of the source file.
atp.request object – Loads XML content from the CGI interface.
Return Value
Boolean. Returns true if the load succeeded; false if the load failed.
Example
var doc = new XML.DOMDocument;
if(false == doc.load("sample.xml"))
{
print("error = " + doc.parseError.errorCode + " ");
print("line = " + doc.parseError.line + " ");
println("linepos = " + doc.parseError.linepos + " ");
println("reason = " + doc.parseError.reason);
}
Output
error = 4 line = 483 linepos = 0
reason = Could not determine base pathname of the file
loadXML
Loads an XML document using the supplied string. Calling load or loadXML
immediately discards the content of the existing document. This method is an
extension of the W3C DOM.
Syntax
boolValue = doc.loadXML(strXML);
Parameters
strXML – Contains the XML string to load into this XML document object. This
string can contain an entire XML document or a well-formed fragment.
Return Value
Boolean. Returns true if the load succeeded; false if the load failed.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 29
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.loadXML("<employee><id>0001</id><name>Joe</name>
</employee>");
println(doc.xml);
Output
<employee><id>0001</id><name>Joe</name></employee>
nodeFromID
Returns the node whose ID is given by the supplied string. The ID is specified in the
DTD. The ID is for the attribute in each element, and no element can specify more
than one ID attribute. If no ID is specified, null is returned. This method is an
extension of the W3C DOM.
Syntax
oNode = doc.nodeFromID(strID);
Parameters
strID – The unique ID value for an element.
Return Value
oNode – The matching node.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var node = doc.nodeFromID("NUM16004");
println(node.xml);
Output
<student id="NUM16004">
<name>Maria Jones</name>
<department>Electrical Engineering</department>
<GPA>3.7</GPA>
<gender>Female</gender>
<address street="Yes" permanent="Yes">277 South Road.
Sunnyvale, California 94087</address>
</student>
save
Saves an XML document to the specified location. The file is created if necessary
and the contents are entirely replaced with the contents of the saved document.
Syntax
doc.save(filename);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 30
XMLDOMParseError Object
XML for ATP Add-On Module
Parameters
filename – String specifying the name of the target file.
Return Value
None.
ATPException
An ATPException is raised, where error code equals ATP_ERR_DOM_FILE_IO, if
there is a failure to save data to the file.
Example
var doc = new XML.DOMDocument;
doc.load(“sample.xml”);
doc.save(“sample2.xml”);
XMLDOMParseError Object
This object contains detailed information about the last parse error, including the error
number, line number, character position, and a text description. Table 5-6 specifies the
common properties of the XMLDOMParseError object.
Table 5-6. XMLDOMParseError Object Properties
Property
Description
errorCode
Contains the error code of the last parse error. Read-only.
line
The line number of the end of the text where the exception
occurred. Read-only.
linepos
The column number of the end of the text where the exception
occurred. Read-only.
reason
The message explains the reason for error. Read-only.
url
Get the system identifier or the entity where the exception
occurred. If the system identifier is a URL, it will be resolved
fully. Read-only.
Properties
errorCode
Contains the error code of the last parse error. 0 means no error.
Remarks
Integer. Read-only.
Syntax
intValue = oXMLDOMParseError.errorCode
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 31
XML for ATP Add-On Module
Properties
Example
var doc = new XML.DOMDocument
doc.load(“sample.xml”);
if (doc.parseError.errorCode != 0) {
println(“load failed, error code = “ +
doc.parseError.errorCode)
}
line
Contains the error code of the last parse error. This is an integer representing the line
number, or –1 if none is available.
Remarks
Integer. Read-only.
Syntax
intValue = oXMLDOMParseError.line
Example
var doc = new XML.DOMDocument
doc.load(“sample.xml”);
if (doc.parseError.errorCode != 0) {
println(“load failed, line number = “ +
doc.parseError.line)
}
linepos
The column number of the end of the text where the exception occurred. The first
column in a line is position 1.
Remarks
Integer. Read-only.
Syntax
intValue = oXMLDOMParseError.linepos
Example
var doc = new XML.DOMDocument
doc.load(“sample.xml”);
if (doc.parseError.errorCode != 0) {
println(“load failed, column number = “ +
doc.parseError.linepos)
}
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 32
XML for ATP Add-On Module
XMLDOMNodeList Object
reason
Contains the reason for the last parse error, displaying a description of the error.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMParseError.errorCode
Example
var doc = new XML.DOMDocument
doc.load(“sample.xml”);
if (doc.parseError.errorCode != 0) {
println(“load failed, reason = “ + doc.parseError.reason)
}
url
Returns the system identifier of the entity where the exception occurred, or null if
none is available. If the system identifier is a URL, it will be resolved fully.
Remarks
String. Read-only.
Syntax
strURL = oXMLDOMParseError.url
Example
var doc = new XML.DOMDocument
doc.load(“sample.xml”);
if (doc.parseError.errorCode != 0) {
println(“load failed, url = “ + doc.parseError.url)
}
XMLDOMNodeList Object
The XMLDOMNodeList object provides the abstraction of an ordered collection of
nodes. A XMLDOMNodeList Object collection is “live,” in that any changes to the
document tree are immediately reflected in any node lists that may have been created for
that tree.
There are two ways to create an XMLDOMNodeList object:
•
•
The getElementsByTagName method of the DOMDocument Object
The childNodes property of the XMLDOMNode Object
The items in the XMLDOMNodeList object are accessible via an integral index, starting
from 0.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 33
Properties
XML for ATP Add-On Module
Table 5-7 specifies the common properties of the XMLDOMNodeList object.
Table 5-7. XMLDOMNodeList Object Properties
Method
Description
length
Indicates the number of items in the collection.
Table 5-8 specifies the common methods of the XMLDOMNodeList object.
Table 5-8. XMLDOMNodeList Object Methods
Method
Description
item
Returns the item specified by the index value in the collection.
nextNode
Returns the next node in the collection.
reset
Resets the iterator.
Properties
length
Indicates the number of items in the collection.
Remarks
Unsigned Integer. Read-only.
Syntax
nValue = oXMLDOMNodeList.length
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var list = doc.documentElement.childNodes;
println(list.length);
Output
5
Methods
item
Returns the item specified by the index value in the collection. The range of the
index is 0 to length -1.
Syntax
var objXMLDOMNode = oXMLDOMNodeList.item(index)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 34
XML for ATP Add-On Module
Methods
Parameters
index – Unsigned Integer. Index of the item within the collection.
Return Value
objXMLDOMNode – The node at the index position in the list, or null if that is not a
valid index.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var list = doc.documentElement.childNodes;
println(list.item(0).childNodes.item(0).nodeName);
Output
name
nextNode
Returns the next node in the collection. The iterator initially points before the first
node in the list so that the first call to nextNode returns the first node in the list.
This method returns nulls when the current node is the last node or there are no
items in the list.
Syntax
var objXMLDOMNode = oXMLDOMNodeList.nextNode()
Parameters
None.
Return Value
objXMLDOMNode – Refers to the next node in the collection. Returns null if there
is no next node.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var list = doc.documentElement.childNodes.item(0).childNodes;
while(1)
{
var node = list.nextNode();
if(node == null) break;
print(node.nodeName + " ");
}
Output
name department GPA gender address
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 35
XML for ATP Add-On Module
XMLDOMNamedNodeMap Object
reset
Resets the iterator. This method reinitializes the iterator to point before the first node
in the XMLDOMNodeList Object so that the next call to nextNode returns the
first item in the list. This member is an extension of the W3C DOM.
Syntax
oXMLDOMNodeList.reset()
Parameters
None.
Return Value
None.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
var list = doc.documentElement.childNodes.item(0).childNodes;
while(1)
{
var node = list.nextNode();
if(node == null) break;
print(node.nodeName + " ");
}
list.reset();
println("\n" + list.nextNode().nodeName);
Output
name department GPA gender address
name
XMLDOMNamedNodeMap Object
XMLDOMNamedNodeMap objects are used to represent collections of nodes that can
be accessed by name. Note that XMLDOMNamedNodeMap does not inherit from the
XMLDOMNodeList Object; XMLDOMNamedNodeMap objects are not maintained in
any particular order. Nodes contained in an XMLDOMNamedNodeMap object can also
be accessed by an ordinal index, but this is simply to allow convenient enumeration of
the contents and does not imply that the DOM specifies an order to these nodes.
XMLDOMNamedNodeMap objects are instantiated by these methods:
•
•
•
XMLDOMNode.attributes
XMLDOMDocumentType.entities
XMLDOMDocumentType.notations
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 36
Properties
XML for ATP Add-On Module
Table 5-9 specifies the common properties of the XMLDOMNamedNodeMap object.
Table 5-9. XMLDOMNamedNodeMap Object Properties
Property
Description
length
Indicates the number of nodes in the map.
Table 5-10 specifies the common methods of the XMLDOMNamedNodeMap object.
Table 5-10. XMLDOMNamedNodeMap Object Methods
Method
Description
item
Returns the index(th) item in the collection.
getNamedItem
Retrieves a node specified by name.
getQualifiedItem
Retrieves a node specified by local name and namespace URI.
nextNode
Returns the next node in the collection.
reset
Resets the iterator.
removeNamedItem
Removes a node specified by name.
removeQualifiedItem
Removes a node specified by local name and namespace URI.
setNamedItem
Adds a node using its nodeName attribute.
Properties
length
Indicates the number of nodes in the map.
Remarks
Unsigned Integer. Read-only.
Syntax
nValue = oXMLDOMNamedNodeMap.length
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
println(map.length);
Output
2
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 37
XML for ATP Add-On Module
Methods
Methods
item
Returns the item specified by the index value in the collection. The range of the
index is 0 to length -1.
Syntax
var objXMLDOMNode = oXMLDOMNamedNodeMap.item(index)
Parameters
index – Unsigned Integer. Index of the item within the collection.
Return Value
objXMLDOMNode – The node at the index position in the list, or null if that is not a
valid index.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
println(map.item(0).nodeName);
Output
street
getNamedItem
Retrieves a node specified by name.
Syntax
var objXMLDOMNode = oXMLDOMNamedNodeMap.getNamedItem(name)
Parameters
name – The nodeName of a node to retrieve.
Return Value
Object – An XMLDOMNode Object with the specified nodeName, or null if it
does not identify any node in the map.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 38
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
println(map.getNamedItem("permanent").nodeValue);
Output
Yes
getQualifiedItem
Retrieves a node specified by local name and namespace URI.
Syntax
var objXMLDOMNode =
oXMLDOMNamedNodeMap.getQualifiedItem(baseName, namespaceURI)
Parameters
baseName – The local name of the node to retrieve.
namespaceURI – The namespace URI of the node to retrieve.
Return Value
Object – An XMLDOMNode Object with the specified baseName and
namespaceURI, or null if it does not identify any node in the map.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
println(map.getQualifiedItem("permanent", "").nodeName);
Output
permanent
nextNode
Returns the next node in the collection. The iterator initially points before the first
node in the list so that the first call to nextNode returns the first node in the list.
This method returns nulls when the current node is the last node or there are no
items in the list.
Syntax
var objXMLDOMNode = oXMLDOMNameNodeMap.nextNode()
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 39
XML for ATP Add-On Module
Methods
Parameters
None.
Return Value
objXMLDOMNode – Refers to the next node in the collection. Returns null if there
is no next node.
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var node = map.nextNode();
while(node)
{
println(node.nodeName + " = " + node.nodeValue);
node = map.nextNode();
}
Output
street = Yes
permanent = Yes
reset
Resets the iterator. This method reinitializes the iterator to point before the first node
in the XMLDOMNamedNodeMap Object so that the next call to nextNode returns
the first item in the list. This member is an extension of the W3C DOM.
Syntax
oXMLDOMNameNodeMap.reset()
Parameters
None.
Return Value
None.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 40
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var node = map.nextNode();
while(node)
{
print(node.nodeName + " = " + node.nodeValue + " ");
node = map.nextNode();
}
map.reset();
println("\nafter reset, the first node again is " +
map.nextNode().nodeName);
Output
street = Yes permanent = Yes
after reset, the first node again is street
removeNamedItem
Removes a node specified by name. If the removed node is an Attr with a default
value, it is immediately replaced.
Syntax
var objXMLDOMNode = oXMLDOMNamedNodeMap.removeNamedItem(name)
Parameters
name – The nodeName of a node to remove.
Return Value
Object – The XMLDOMNode Object removed from the map.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
NOT_FOUND_ERR(8): This error-detail code is raised if there is no node
named name in the map.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the name node map is read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 41
XML for ATP Add-On Module
Methods
Example
The following example creates an attribute node code NewAttr and adds it to the
attributes for the DOMDocument Object:
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = map.removeNamedItem("street");
println(attr.nodeValue);
Output
Yes
removeQualifiedItem
Removes a node specified by the local name and namespace URI. The
nameSpaceURI parameter is the nameSpace prefix that qualifies the attribute name.
Syntax
var objXMLDOMNode =
oXMLDOMNamedNodeMap.removeQualifiedItem(baseName,namespaceURI)
Parameters
baseName – The local name of the node to remove.
namespaceURI – The namespace URI of the node to remove.
Return Value
Object – An XMLDOMNode with the specified baseName and namespaceURI, or
null if it does not identify any node in the map.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
NOT_FOUND_ERR(8): This error-detail code is raised if there is no node
named name in the map.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the name node map is read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 42
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = map.removeQualifiedItem("street", "");
println(attr.nodeValue);
Output
Yes
setNamedItem
Adds a node using its nodeName attribute. As the node name attribute is used to
derive the name which the node must be stored under, multiple nodes of certain
types (those that have a “special” string value) cannot be stored as the names would
clash. This is seen as preferable to allowing nodes to be aliased.
Syntax
var objXMLDOMNode = oXMLDOMNamedNodeMap.setNamedItem(newItem)
Parameters
newItem – A node to store in a named node map. The node will later be accessible
using the value of the nodeName attribute of the node. If a node with that name is
already present in the map, it is replaced by the new one.
Return Value
Object – The XMLDOMNode replaced by the new item with the same
nodeName, otherwise null is returned.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
•
WRONG_DOCUMENT_ERR(4): This error-detail code is raised if newItem
was created from a different document than the one that created the
XMLDOMNamedNodeMap object.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the name node map is read-only.
INUSE_ATTRIBUTE_ERR(10): Raised if arg is an Attr that is already an
attribute of another Element object. The DOM user must explicitly clone Attr
nodes to re-use them in other elements.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 43
XMLDOMAttribute Object
XML for ATP Add-On Module
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = doc.createAttribute("test");
attr.nodeValue = "true";
map.setNamedItem(attr);
for(var i=0; i<map.length; i++)
{
var node = map.item(i);
print(node.nodeName + " = " + node.nodeValue + " ");
}
Output
test = true street = Yes permanent = Yes
XMLDOMAttribute Object
The XMLDOMAttribute object represents an attribute of an XML element. Typically
the allowable values for the attribute are defined in a document type definition (DTD)
file. XMLDOMAttribute objects have all XMLDOMNode properties and methods, but
since attributes are not actually child nodes of the elements they are associated with, the
DOM does not consider them part of the document tree. Thus, the XMLDOMAttribute’s
parentNode, previousSibling, and nextSibling properties all have a null value.
You need to be aware that XMLDOMAttribute nodes have some things in common with
other objects inheriting the XMLDOMNode object, but they also are quite different.
Table 5-11 specifies the properties defined in XMLDOMNode Object that are not valid
for the XMLDOMAttribute object.
Table 5-11. XMLDOMNode Object Properties that are Not Valid for the
XMLDOMAttribute Object
Property
Description
attributes
Null
childNodes
Null
firstChild
Null
lastChild
Null
nextSibling
Null
parentNode
Null
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 44
Properties
XML for ATP Add-On Module
Table 5-12 specifies the methods defined in XMLDOMNode Object that are not valid
for the XMLDOMAttribute object.
Table 5-12. XMLDOMNode Object Methods that are Not Valid for the
XMLDOMAttribute Object
Method
Expected Exception
appendChild
ATPException.code = ATP_ERR_DOM_EXCEPTION, detail
= HIERARCHY_REQUEST_ERR(3)
cloneNode
ATPException.code = ATP_ERR_DOM_EXCEPTION, detail
= HIERARCHY_REQUEST_ERR(3)
hasChildNodes
ATPException.code = ATP_ERR_DOM_EXCEPTION, detail
= HIERARCHY_REQUEST_ERR(3)
insertBefore
ATPException.code = ATP_ERR_DOM_EXCEPTION, detail
= HIERARCHY_REQUEST_ERR(3)
removeChild
ATPException.code = ATP_ERR_DOM_EXCEPTION, detail
= HIERARCHY_REQUEST_ERR(3)
replaceChild
ATPException.code = ATP_ERR_DOM_EXCEPTION, detail
= HIERARCHY_REQUEST_ERR(3)
Table 5-13 specifies the common properties of the XMLDOMAttribute object.
Table 5-13. XMLDOMAttribute Object Properties
Property
Description
name
Returns the name of this attribute.
ownerElement
Contains the XMLDOMElement Object node this attribute is
attached to.
specified
Indicates whether this attribute is explicitly specified or derived
from a default value in the DTD.
value
Contains the attribute value.
Properties
name
Returns the name of this attribute.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMAttribute.name
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 45
XML for ATP Add-On Module
Properties
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = map.item(1)
println(attr.name);
Output
permanent
ownerElement
Contains the XMLDOMElement Object node this attribute is attached to. This
property returns null if the attribute is not in use.
Remarks
Object (XMLDOMElement Object). Read-only.
Syntax
objAttribute = oXMLDOMAttribute.ownerElement
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = map.item(1)
println(attr.ownerElement.xml);
Output
<address street="Yes" permanent="Yes">1010 Fargo Drive,
Cupertino, California 95014 </address>
specified
Indicates whether this attribute is explicitly specified or derived from a default value
in the DTD. This property returns true if the attribute received its value explicitly
in the XML document, or if a value was assigned programmatically. It returns
false if the attribute value came from the default value declared in the document
DTD.
Remarks
Boolean. Read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 46
XML for ATP Add-On Module
Properties
Syntax
boolValue = oXMLDOMAttribute.specified
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = map.item(1)
println(attr.specified);
Output
true
value
Contains the attribute value. The value of the attribute is returned as a string.
Character and general entity references are replaced with their values. A text node
with the unparsed contents of the string assigned by the value property will be
created.
Remarks
String. Read/write.
Syntax
strValue = oXMLDOMAttribute.value
oXMLDOMAttribute.value = strValue
Example
var doc = new XML.DOMDocument;
doc.validateOnParse = true;
doc.load("sample.xml");
root = doc.documentElement;
var map =
root.childNodes.item(0).childNodes.item(4).attributes;
var attr = map.item(1)
println(attr.value);
Output
Yes
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 47
XMLDOMElement Object
XML for ATP Add-On Module
XMLDOMElement Object
XMLDOMElement objects are among the most common objects in the XML document
tree. Element nodes can have attributes associated with them. The attributes are not
defined as child nodes of an element and are not considered to be part of the document
tree. Accordingly, the XMLDOMElement object provides methods to make it easier to
manage attributes, including methods to associate an attribute with an element and
retrieve an attribute object and the attribute value by name.
In XML, where an attribute value may contain entity references, an XMLDOMAttribute
Object should be retrieved to examine the possibly fairly complex subtree representing
the attribute value.
Table 5-14 specifies the common properties of the XMLDOMElement object.
Table 5-14. XMLDOMElement Object Properties
Property
Description
tagName
Contains the element name (the name that appears within the
tag).
Table 5-15 specifies the common methods of the XMLDOMElement object.
Table 5-15. XMLDOMElement Object Methods
Method
Description
getAttribute
Retrieves an attribute value by name.
getAttributeNode
Retrieves an attribute node by name.
getElementsByTagName
Returns an XMLDOMNodeList of all descendant elements
with a given tag name, in the order in which they would be
encountered in a preorder traversal of the XMLDOMElement
tree.
normalize
Normalizes all descendant elements; combines two or more
adjacent text nodes into one unified text node.
removeAttribute
Removes an attribute by name.
removeAttributeNode
Removes the specified attribute node.
setAttribute
Adds a new attribute.
setAttributeNode
Adds a new attribute.
Properties
tagName
Contains the element name (the name that appears within the tag). For example, in
<customer ID=”ABC12345”>, the tagName has the value “customer”. Note that this
is case-preserving in XML, as are all of the operations of the DOM.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 48
XML for ATP Add-On Module
Methods
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMElement.tagName
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
println(root.tagName);
Output
class99
Methods
getAttribute
Retrieves an attribute value by name.
Syntax
strValue = oXMLDOMElement.getAttribute (name)
Parameters
name – The name of an attribute to retrieve.
Return Value
String – Returns a string that contains the attribute value or returns the empty
string if the named attribute does not have a specified or default value.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var node = root.childNodes.item(1).childNodes.item(9);
println(node.getAttribute("permanent"));
Output
Yes
getAttributeNode
Retrieves an attribute node by name.
Syntax
var objXMLDOMAttribute = oXMLDOMElement.getAttributeNode(name)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 49
XML for ATP Add-On Module
Methods
Parameters
name – The name of an attribute to retrieve.
Return Value
Object – Returns the XMLDOMAttribute with the supplied name, or null if the
named attribute cannot be found on this element.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var node = root.childNodes.item(1).childNodes.item(9);
println(node.getAttributeNode("permanent").name);
Output
permanent
getElementsByTagName
Returns a XMLDOMNodeList of all descendant elements with a given tag name, in
the order in which they would be encountered in a preorder traversal of the
XMLDOMElement tree.
Syntax
var obj XMLDOMNodeList = oXMLDOMElement.getElementsByTagName
(name)
Parameters
name – The name of the tag to match on. The special value “*” matches all tags.
Return Value
Object – The XMLDOMNodeList object containing all elements that matched the
supplied name.
Note that the XMLDOMNodeList object is returned even if there are no matches. In
such a case, the length of the list is set to zero. The XMLDOMNodeList object is
live and immediately reflects changes to the nodes that appear in the list.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var list = root.getElementsByTagName("GPA");
println(list.length);
Output
5
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 50
XML for ATP Add-On Module
Methods
normalize
Normalizes all descendant elements; combines two or more adjacent text nodes into
one unified text node. This method puts all XMLDOMText nodes in the full depth of
the subtree underneath the XMLDOMElement object into a normal form where only
markup (for example, tags, comments, processing instructions, CDATA sections, and
entity references) separates XMLDOMText nodes. For example, there are neither
adjacent XMLDOMText nodes nor empty XMLDOMText nodes. This can be used
to ensure that the DOM view of a document is the same as if it were saved and
reloaded, and is useful when operations that depend on a particular document tree
structure are to be used.
Syntax
var objXMLDOMElement = oXMLDOMElement.normalize()
Parameters
None.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
println(root.normalize());
Output
true
removeAttribute
Removes an attribute by name. If the removed attribute is known to have a default
value, an attribute immediately appears containing the default value as well as the
corresponding namespace URI, local name, and prefix when applicable.
Syntax
oXMLDOMElement.removeAttribute(name)
Parameters
name – The name of the attribute to remove.
Return Value
None.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the nodeValue attribute is read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 51
XML for ATP Add-On Module
Methods
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var node = root.childNodes.item(1).childNodes.item(9);
println(node.attributes.length);
node.removeAttribute("permanent");
println(node.attributes.length);
Output
2
1
removeAttributeNode
Removes the specified attribute node. If the removed attribute has a default value, it
is immediately replaced. The replacing attribute has the same namespace URI, local
name, and original prefix when applicable.
Syntax
objXMLDOMAttribute = oXMLDOMElement.removeAttributeNode(oldAttr)
Parameters
oldAttr – The XMLDOMAttribute node to remove from the attribute list.
Return Value
Object – The XMLDOMAttribute node that was removed.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
NOT_FOUND_ERR(8): This error-detail code is raised if oldAttr is not an
attribute of the element.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the element is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var node = root.childNodes.item(1).childNodes.item(9);
println(node.attributes.length);
var attr = node.getAttributeNode("permanent");
node.removeAttributeNode(attr);
println(node.attributes.length);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 52
XML for ATP Add-On Module
Methods
Output
2
1
setAttribute
Adds a new attribute. If an attribute with that name is already present in the element,
its value is changed to that of the value parameter. This value is a simple string; it is
not parsed as it is being set. So any markup (such as syntax to be recognized as an
entity reference) is treated as literal text and needs to be appropriately escaped by
the implementation when it is written out.
In order to assign an attribute value that contains entity references, you must:
1. Create an XMLDOMAttribute Object node plus any XMLDOMText Object and
XMLDOMEntityReference Object nodes
2. Build the appropriate subtree
3. Use setAttributeNode to assign it as the value of an attribute
Syntax
oXMLDOMElement.setAttribute(name, value)
Parameters
name – The name of the attribute to create or alter.
value – The value to set in string form.
Return Value
None.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INVALID_CHARACTER_ERR(5): This error-detail code is raised if the
specified name contains an invalid character.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var node = root.childNodes.item(1).childNodes.item(1);
node.setAttribute("test", "true");
println(node.xml);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 53
XML for ATP Add-On Module
Methods
Output
<name test="true">Jenny Mabry</name>
setAttributeNode
Adds a new attribute. If an attribute with the name (nodeName) is already present in
the element, it is replaced by the new one.
Syntax
ObjXMLDOMAttribute = oXMLDOMElement.setAttributeNode(newAttr)
Parameters
newAttr – The XMLDOMAttribute Object node to add to the attribute list.
Return Value
Object – If the newAttr attribute replaces an existing attribute, the replaced
XMLDOMAttribute node is returned. Otherwise null is returned.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
•
WRONG_DOCUMENT_ERR(4): This error-detail code is raised if newAttr
was created from a different document than the one that created the element.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code is raised if
this node is read-only.
INUSE_ATTRIBUTE_ERR(10): This error-detail code is raised if newAttr is
already an attribute of another XMLDOMElement Object. The DOM user must
explicitly clone XMLDOMAttribute Object nodes to re-use them in other
elements.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var root = doc.documentElement;
var node = root.childNodes.item(1).childNodes.item(1);
var attr = doc.createAttribute("test");
node.setAttributeNode(attr);
println(node.xml);
Output
<name test="">Jenny Mabry</name>
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 54
XMLDOMDocumentFragment Object
XML for ATP Add-On Module
XMLDOMDocumentFragment Object
XMLDOMDocumentFragment is a minimal DOMDocument Object that enables freeinsert operations. Using this object, you can extract a portion of a document’s tree or
create a new fragment of a document, and use a node for this purpose. Depending on
your implementation, using the XMLDOMDocumentFragment is more simple than
using a potentially unwieldy DOMDocument Object.
Various operations, such as inserting nodes as children of another node, can take
XMLDOMDocumentFragment objects as arguments, resulting in all the child nodes of
the XMLDOMDocumentFragment being moved to the child list of the other node.
The children of an XMLDOMDocumentFragment node are zero or more nodes
representing the tops of any subtrees that define the structure of the document.
XMLDOMDocumentFragment nodes do not need to be well-formed XML documents
(although they do need to follow the rules imposed upon well-formed XML parsed
entities, which can have multiple top nodes). For example, an
XMLDOMDocumentFragment might have only one child and that child node could be a
text node. Such a structure model represents neither an HTML document nor a wellformed XML document.
When an XMLDOMDocumentFragment is inserted into a document or into a node that
can take children, the children of the XMLDOMDocumentFragment (not the
XMLDOMDocumentFragment itself) are inserted into the node.
This helps you to create nodes that are siblings; the XMLDOMDocumentFragment acts
as the parent of these nodes so that you can use the standard methods from the node
interface, such as insertBefore and appendChild.
XMLDOMDocumentFragment has no unique properties or methods of its own, but
exposes the same objects and properties as the XMLDOMNode Object.
XMLDOMDocumentType Object
The XMLDOMDocumentType object provides access to the list of entities and notations
that are defined for the document. This object contains information associated with the
document type declaration. Each DOMDocument Object has a doctype whose value is
either null or an XMLDOMDocumentType object. Table 5-16 specifies the common
properties of the XMLDOMDocumentType object.
Table 5-16. XMLDOMDocumentType Object Properties
Property
Description
name
Contains the name of DTD, the name immediately following
the DOCTYPE keyword in an XML source document.
entities
Is an XMLDOMNamedNodeMap Object containing the
general entities, both external and internal, declared in the
DTD.
notations
Is an XMLDOMNamedNodeMap Object containing an entry
for each notation declared in a document’s DTD.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 55
XML for ATP Add-On Module
Properties
Properties
name
Contains the name of DTD, the name immediately following the DOCTYPE
keyword in an XML source document. When specified, this corresponds to the
single root element of the document tree.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMDocumentType.name
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var node = doc.doctype;
println(node.nodeName);
Output
class99
entities
An XMLDOMNamedNodeMap Object containing the general entities, both external
and internal, declared in the DTD. Parameter entities are not contained. Duplicates
are discarded.
Remarks
Object (XMLDOMNamedNodeMap Object). Read-only.
Syntax
objXMLDOMNamedNodeMap = oXMLDOMDocumentType.entities
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var map = doc.doctype.entities;
for (var i=0; i<map.length; i++)
{
print(map.item(i).nodeName + " ");
}
Output
gt lt amp apos ent1 ent2 ent3 ent4 ent5 quot
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 56
XMLDOMEntity Object
XML for ATP Add-On Module
notations
An XMLDOMNamedNodeMap Object containing an entry for each notation
declared in a document’s DTD. Duplicates are discarded.
Remarks
Object (XMLDOMNamedNodeMap Object). Read-only.
Syntax
objXMLDOMNamedNodeMap = oXMLDOMDocumentType.notations
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var map = doc.doctype.notations;
println(map.length);
Output
2
XMLDOMEntity Object
The XMLDOMEntity object represents an entity, either parsed or unparsed, in an XML
document.
Note. This models the entity itself, not the entity declaration.
The nodeName attribute that is inherited from the XMLDOMNode Object contains the
name of the entity. An XML processor may choose to completely expand entities before
the structure model is passed to the DOM; in this case there will be no
XMLDOMEntityReference Object nodes in the document tree.
Table 5-17 specifies the common properties of the XMLDOMEntity object.
Table 5-17. XMLDOMEntity Object Properties
Property
Description
notationName
Contains the notation name.
publicId
Contains the public identifier of this entity.
systemId
Contains the system identifier of this entity.
Properties
notationName
Contains the notation name. For unparsed entities, this is the name of the notation
for the entity. For parsed entities, this is null.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 57
XML for ATP Add-On Module
XMLDOMEntityReference Object
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMEntity.notationName
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var map = doc.doctype.entities;
println(map.item(4).notationName);
Output
ent1
publicId
Contains the public identifier of this entity. If the public identifier was not specified,
this contains an empty string.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMEntity.publicId
systemId
Contains the system identifier of this entity. If the system identifier was not
specified, this contains an empty string.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMEntity.systemId
XMLDOMEntityReference Object
The XMLDOMEntityReference nodes appears in the structure model when an entity
reference is in the source document, or when you wish to insert an entity reference. The
expansion of the entity appears as child nodes of the entity reference node. The
expansion may be just simple text, or it may be more complex, containing additional
entity references.
This object has no unique properties or methods of its own, but exposes the same objects
and properties as the XMLDOMNode Object.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 58
XML for ATP Add-On Module
XMLDOMImplementation Object
XMLDOMImplementation Object
The XMLDOMImplementation object provides a way to query the capabilities of an
implementation of the DOM. The XMLDOMImplementation object does not inherit
from XMLDOMNode Object, and it has only one method as described below.
Method
hasFeature
Tests if the DOM implementation implements a specific feature.
Syntax
BoolValue = oXMLDOMImplementation.hasFeature(feature, version)
Parameters
feature – The case-insensitive string value to test. The legal values are defined
throughout this specification. The string must be an XML name.
version – This is the version number of the package name to test. In level 1, this
is the string “1.0”. If the version is not specified, supporting any version of the
feature causes the method to return true.
Return Value
boolean – true if the feature is implemented in the specified version, false
otherwise.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var impl = doc.implementation;
println(impl.hasFeature("XML", "1.0"));
Output
true
XMLDOMNotation Object
The XMLDOMNotation object represents a notation declared in the DTD. A notation
either declares, by name, the format of an unparsed entity, or is used for formal
declaration of processing instruction targets. The nodeName attribute inherited from
the XMLDOMNode Object is set to the declared name of the notation. An
XMLDOMNotation node does not have any parent.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 59
XML for ATP Add-On Module
Properties
Properties
publicId
Contains the public identifier of this notation. If the public identifier was not
specified, this contains an empty string.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMNotation.publicId
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var map = doc.doctype.notations;
println(map.item(0).publicId);
Output
notationFile
systemId
Contains the system identifier of this notation. If the system identifier was not
specified, this contains an empty string.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMNotation.systemId
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var map = doc.doctype.notations;
var sysID = map.item(1).systemId;
XMLDOMProcessingInstruction Object
The XMLDOMProcessingInstruction object represents a processing instruction, used in
XML as a way to keep processor-specific information in the text of the document.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 60
XML for ATP Add-On Module
Properties
Properties
data
Contains the content of this processing instruction. This is from the first non-white
space character after the target to the character immediately preceding the ?>.
Remarks
String. Read/write.
Syntax
strValue = oXMLDOMProcessingInstruction.data
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
var pi =
doc.createProcessingInstruction("xml", "version='1.0'");
println(pi.xml);
println("data property is " + pi.data);
Output
<?xml version='1.0'?>
data property is version='1.0'
target
Contains the target of this processing instruction. XML defines this as being the first
token following the markup that begins the processing instruction.
Remarks
String. Read-only.
Syntax
strValue = oXMLDOMProcessingInstruction.target
Example
var doc = new XML.DOMDocument;
var pi =
doc.createProcessingInstruction("xml", "version='1.0'");
println(pi.xml);
println("target property is " + pi.target);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 61
XMLDOMCharacterData Object
XML for ATP Add-On Module
Output
<?xml version='1.0'?>
target property is xml
XMLDOMCharacterData Object
The XMLDOMCharacterData object extends the XMLDOMNode Object with a set of
methods for accessing character data in the DOM. The XMLDOMCharacterData object
does not directly correspond to any node type. The XMLDOMCDATASection Object,
XMLDOMComment Object, and XMLDOMText Object reuse its methods. These
methods handle large amounts of text, including sizes larger than can be manipulated
natively using string constructs.
Table 5-18 specifies the properties that are defined in the XMLDOMCharacterData
object and reused by the XMLDOMCDATASection Object, XMLDOMComment
Object, and XMLDOMText Object.
Table 5-18. XMLDOMCharacterData Object Properties
Property
Description
data
Contains this node’s data, which depends on the node type.
length
Specifies the length, in characters, of the data.
Table 5-19 specifies the methods that are defined in the XMLDOMCharacterData object
and reused by the XMLDOMCDATASection Object, XMLDOMComment Object, and
XMLDOMText Object.
Table 5-19. XMLDOMCharacterData Object Methods
Method
Description
appendData
Appends the supplied string to the existing string data.
deleteData
Deletes the specified substring within the string data.
insertData
Inserts the supplied string at the specified offset.
replaceData
Replaces the specified number of characters with the supplied
string.
substringData
Retrieves a substring of the full string from the specified range.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 62
Properties
XML for ATP Add-On Module
Properties
data
Returns the character data of the node. It contains the same value as the
nodeValue for this node. The meaning of the value depends on the
XMLDOMNode Object nodeType property, as follows:
NODE_CDATA_SECTION
A string representing the text stored in the CDATA
section.
NODE_COMMENT
The content of the comment, exclusive of the comment
start and end sequence.
NODE_TEXT
A string representing the text stored in the text node.
The DOM implementation may not put arbitrary limits on the amount of data that
may be stored in a character data node. However, implementation limits may mean
that the entirety of a node’s data cannot fit into a single string. In such cases, the user
can call substringData to retrieve the data in appropriately sized pieces.
Remarks
String. Read/write.
Syntax
strValue = oXMLDOMCharacterData.data
objXMLDOMCharacterData.data = strValue
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
DOMSTRING_SIZE_ERR(2): Raised when it would return more characters
than fit in a string variable on the implementation platform.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
println(comment.data);
Output
This is comment line
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 63
XML for ATP Add-On Module
Methods
length
Specifies the length, in characters, of the data. The length may be 0.
Remarks
Unsigned integer. Read-only.
Syntax
nValue = oXMLDOMCharacterData.length
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
println(comment.length);
Output
20
Methods
appendData
Appends the string to the end of the character data of the node. Upon success, the
data property provides access to the concatenation of data and the appended string
specified.
Syntax
oXMLCharacterData.appendData(data)
Parameters
data – A string value to append.
Return Value
None.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
comment.appendData("; here is appended data");
println(comment.data);
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 64
XML for ATP Add-On Module
Methods
Output
This is comment line; here is appended data
deleteData
Removes a range of characters from the node. Upon success, the data and
length properties reflect the change.
Syntax
oXMLCharacterData.deleteData(offset, count)
Parameters
offset (unsigned integer) – The offset from which to remove characters.
count (unsigned integer) – The number of characters to delete. If the sum of
offset and count exceeds length then all characters from offset to the end
of the data are deleted.
Return Value
None.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INDEX_SIZE_ERR(1): This error-detail code is raised if the specified offset is
negative or greater than the number of characters in data, or if the specified
count is negative.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
comment.deleteData(0, 6);
println(comment.data);
Output
s comment line
insertData
Inserts a string at the specified character offset.
Syntax
oXMLCharacterData.insertData(offset, data)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 65
XML for ATP Add-On Module
Methods
Parameters
offset (unsigned integer) – The character offset at which to insert.
data (string) – The string value to insert.
Return Value
None.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INDEX_SIZE_ERR(1): This error-detail code is raised if the specified offset is
negative or greater than the number of characters in data, or if the specified
count is negative.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
comment.insertData(8, "<insert>");
println(comment.data);
Output
This is <insert>comment line
replaceData
Replaces the characters starting at the specified character offset with the specified
string.
Syntax
oXMLCharacterData.replaceData(offset, count, data)
Parameters
offset (unsigned integer) – The character offset at which to begin replacing.
count (unsigned integer) – The number of characters to replace. If the sum of
offset and count exceeds the property length value, then all characters to the
end of the data are replaced (that is, the effect is the same as a remove method call
with the same range, followed by an append method invocation).
data (string) – The string value to insert.
Return Value
None.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 66
XML for ATP Add-On Module
Methods
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INDEX_SIZE_ERR(1): This error-detail code is raised if the specified offset is
negative or greater than the number of characters in data, or if the specified
count is negative.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
comment.replaceData(0, 4, ">>>>");
println(comment.data);
Output
>>>> is comment line
substringData
Extracts a range of data from the node.
Syntax
strData = oXMLCharacterData.substringData(offset, count)
Parameters
offset (unsigned integer) – Start offset of the substring to extract.
count (unsigned integer) – The number of characters to extract.
Return Value
StrData (string) – The specified substring. If the sum of offset and count
exceeds the property length value, then all characters to the end of the data are
returned.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INDEX_SIZE_ERR(1): This error-detail code is raised if the specified offset is
negative or greater than the number of characters in data, or if the specified
count is negative.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 67
XML for ATP Add-On Module
XMLDOMComment Object
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var comment = doc.documentElement.previousSibling;
println(comment.substringData(0, 10));
Output
This is co
XMLDOMComment Object
The XMLDOMComment object refers to XML comment nodes in the DOM. The string
value contains all of the characters between the starting ‘<!--’ and ending ‘-->’.
This object has no unique properties or methods of its own, but inherits the properties
and methods from the XMLDOMCharacterData Object.
XMLDOMText Object
The XMLDOMText object represents the textual content of XMLDOMElement Object
or XMLDOMAttribute Object.
If there is no markup inside an XMLDOMElement object’s content, the text is contained
in a single object implementing the XMLDOMText object that is the only child of the
XMLDOMElement object.
If there is markup, it is parsed into a list of elements and XMLDOMText Object nodes
that form the list of children of the XMLDOMElement object.
When a document is first made available through the DOM, there is only one
XMLDOMText node for each block of the text. You can create adjacent XMLDOMText
nodes that represent the contents of a given element without any intervening markup, but
you should be aware that since there is no way to represent the separations between
these nodes in XML, they will not persist between DOM editing sessions.
The normalize method on the XMLDOMElement object merges any such adjacent
XMLDOMText objects into a single node for each block of text; this is recommended
before employing operations that depend on a particular document structure.
The XMLDOMText object has those properties and methods defined for the
XMLDOMNode Object and XMLDOMCharacterData Object.
Method
splitText
Breaks this node into two nodes at the specified offset, keeping both in the tree as
siblings. This node then only contains all the content up to the offset point. A new
node of the same nodeType, which is inserted as the next sibling of this node,
contains all the content at and after the offset point. When the offset is equal to the
length of this node, the new node has no data.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 68
XML for ATP Add-On Module
XMLDOMCDATASection Object
Syntax
var objXMLDOMText = oXMLDOMText.splitText(offset)
Parameters
offset (unsigned integer) – The offset at which to split, starting from 0.
Return Value
Object – The new text node.
ATPException
The following list shows the possible error-detail codes for the ATPException,
where error code is equal to ATP_ERR_DOM_EXCEPTION.
•
•
INDEX_SIZE_ERR(1): This error-detail code is raised if the specified offset is
negative or greater than the number of characters in data, or if the specified
count is negative.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates
that the node is read-only.
Example
var doc = new XML.DOMDocument;
doc.load("sample.xml");
var node =
doc.documentElement.childNodes.item(1).childNodes.item(7);
var textNode = node.firstChild;
println("original text = " + textNode.data);
var n1 = textNode.splitText(3);
print("After splitText(3), firstChild becomes " +
node.firstChild.data + ", ");
println("second child becomes " +
node.firstChild.nextSibling.data + ".");
Output
original text = Female
After splitText(3), firstChild becomes Fem, second child
becomes ale.
XMLDOMCDATASection Object
The XMLDOMCDATASection objects refer to the data from an XML CDATA section.
These are used to escape blocks of text containing characters that would otherwise be
regarded as markup.
The string data associated with the CDATA section may contain characters that need to
be escaped when appearing in an XML document outside of a CDATA section.
Although the XMLDOMCDATASection object inherits all properties and methods from
the XMLDOMCharacterData Object through the XMLDOMText Object, adjacent
CDATASection nodes are not merged by use of the XMLDOMElement.normalize()
methods.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 69
XMLDecl Object
XML for ATP Add-On Module
This object has no unique properties or methods of its own, but inherits the same
properties and methods from XMLDOMText Object.
XMLDecl Object
The XMLDecl object refers to XML declaration nodes in the DOM tree. The Apache
XML parser creates an XMLDecl object for a declaration node, instead of
XMLDOMProcessingInstruction, while parsing an XML document. Therefore, there
will be no XMLDOMProcessingInstruction objects created after loading a document to
an XMLDOMDocument object. The XMLDecl is always the first child node of an
XMLDOMDocument, if the document has a declaration node. The XMLDecl object has
the following three properties.
Table 5-20 specifies the common properties of the XMLDOMEntity object.
Table 5-20. XMLDecl Object Properties
Property
Description
version
Specifies the version string of the XML declaration statement.
encoding
Specifies the encoding string of the XML declaration
statement.
standalone
Specifies the standalone string of the XML declaration
statement.
Properties
version
Specifies the version string of the XML declaration statement.
Remarks
String. Read-only.
Syntax
sVer = oXMLDOMDocument.version
Example
var doc = new XML.DOMDocument
doc.load("sample.xml");
var oDecl = doc.firstChild;
atp.print("XML version =" + oDecl.version);
encoding
Specifies the encoding string of the XML declaration statement. The encoding
property contains an empty string if it is not specified in the original document.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 70
XML for ATP Add-On Module
Exception and Error Information
Remarks
String. Read-only.
Syntax
sEncoding = oXMLDOMDocument.encoding
Example
var doc = new XML.DOMDocument
doc.load("sample.xml");
var oDecl = doc.firstChild;
atp.print("XML encoding =" + oDecl.encoding);
standalone
Specifies the standalone string of the XML declaration statement. The standalone
property contains an empty string if it is not specified in the original document.
Remarks
String. Read-only.
Syntax
sStandalone = oXMLDOMDocument.standalone
Example
var doc = new XML.DOMDocument
doc.load("sample.xml");
var oDecl = doc.firstChild;
atp.print("XML standalone =" + oDecl.standalone);
Exception and Error Information
An ATPException object might be thrown while executing the XML DOM methods. To
prevent the program from stopping on any exception, use a try-catch block to check the
error information and recover from any exception.
The following list shows the possible values for the error code property of the
ATPException object defined for XML objects:
•
•
•
•
•
ATP_ERR_DOM_UNKNOWN(0)
ATP_ERR_DOM_EXCEPTION(1): This exception is thrown by the low-level
XML/DOM parser.
ATP_ERR_DOM_USAGE(2): Indicates an invalid usage of methods, usually an
incorrect number of parameters.
ATP_ERR_DOM_INVALID_NODE_TYPE(3): Indicates that the input parameter
has an invalid DOM_Node type, which is not supported by the method.
ATP_ERR_DOM_INVALID_PARAM_TYPE(4): Indicates that the input parameter
is an invalid object type for the method.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 71
XML for ATP Add-On Module
•
Exception and Error Information
ATP_ERR_DOM_FILE_IO(5): Indicates an I/O failure, which may be caused by an
invalid file path or access permission.
The following list shows the possible error detail values for the error code property
(ATP_ERR_DOM_EXCEPTION) of the ATPException object:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
INDEX_SIZE_ERR(1): Raised if the specified offset is negative or greater than the
number of characters in data, or if the specified count is negative.
DOMSTRING_SIZE_ERR(2): Raised when it would return more characters than fit
in a string variable on the implementation platform. This error-detail code indicates
that the value that would be returned is too large to be contained by a string type in
the given implementation.
HIERARCHY_REQUEST_ERR(3): Raised if this node is of a type that does not
allow children of the type of the newChild node, or if the node to append is one of
this node’s ancestors.
WRONG_DOCUMENT_ERR(4): Raised if newChild was created from a
different document than the one that created this node.
INVALID_CHARACTER_ERR(5): Raised if the specified qualified name contains
an invalid character.
NO_DATA_ALLOWED_ERR(6): Reserved for future use.
NO_MODIFICATION_ALLOWED_ERR(7): This error-detail code indicates that
the nodeValue attribute is read-only for this DOM object type.
NOT_FOUND_ERR(8): Raised if refChild is not a child of this node.
NOT_SUPPORTED_ERR(9): Raised if this document is an HTML document.
INUSE_ATTRIBUTE_ERR(10): Raised if arg is an Attr that is already an
attribute of another Element object. The DOM user must explicitly clone Attr
nodes to re-use them in other elements.
INVALID_STATE_ERR(11): Reserved for future use.
SYNTAX_ERR(12): Reserved for future use.
INVALID_MODIFICATION_ERR(13): Reserved for future use.
NAMESPACE_ERR(14): The name is malformed if:
° The name has a prefix and the namespaceURI is null or an empty string
° The name has a prefix that is “xml” and the namespaceURI is different from
“http://www.w3.org/XML/1998/namespace”
° The name has a prefix that is “xmlns” and the namespaceURI is different from
“http://www.w3.org/2000/xmlns/”
° The name is “xmlns” and the namespaceURI is different from
“http://www.w3.org/2000/xmlns/”
•
INVALID_ACCESS_ERR(15): Reserved for future use.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 72
XML for ATP Add-On Module
Sample Applications
Sample Applications
Example 5-1 shows the sample XML file for the previous examples in this section.
Example 5-1. XML Code (sample.xml)
<?xml version="1.0"?>
<!DOCTYPE class99 SYSTEM "sample.dtd" [
<!ENTITY ent1 "o">
<!ENTITY ent2 "10100 Tantau Ave">
<!ENTITY ent3 "California">
<!ENTITY ent4 "<entElement>Element data</entElement><?PItarget PIdata?>">
<!ENTITY ent5 PUBLIC "entityURI" "entityFile" NDATA notation1>
<!NOTATION notation1 PUBLIC "notationFile" "notation1">
<!NOTATION notation2 SYSTEM "notation2File">
]>
<!--This is a comment line-->
<class99>
<student id="NUM16001">
<name>Jenny Mabry</name>
<department>Computer Science</department>
<GPA>3.6</GPA>
<gender>Female</gender>
<address permanent="Yes">1010 Fargo Drive, Cupertino, California 95014
</address>
</student>
<student id="NUM16002">
<name>Lily Ramos<![CDATA[This is a CDATASection with EntityReference number
3 &ent3;]]>
<![CDATA[This is an adjacent CDATASection with a reference to a tab
&tab;]]></name>
<department>Electrical Engineering</department>
<GPA>3.2</GPA>
<gender>Female</gender>
<address permanent="Yes" street="Yes">&ent2; Cupertino, &ent3;
95014</address>
</student>
<student id="NUM16003">
<name>Michael
Oconnor</name>
<department>Computer Science</department>
<GPA>3.8</GPA>
<gender>Male</gender>
<address permanent="No" street="N&ent1;">PO Box 28 Irving, texas
98553</address>
</student>
<student id="NUM16004">
<name>Maria Jones</name>
<department>Electrical Engineering</department>
<GPA>3.7</GPA>
<gender>Female</gender>
<address permanent="Yes">277 South Road. Sunnyvale, California
94087</address>
</student>
<student id="NUM16005">
<name>John Martin</name>
<department>Computer Science</department>
<GPA>3.0</GPA>
<gender>male</gender>
<address street="Yes">1821 main street, Dallas, Texas 98556</address>
</student>
</class99>
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 73
XML for ATP Add-On Module
Sample Applications
Example 5-2 shows a document type definition (DTD) for the file shown in
Example 5-1:
Example 5-2. Document Type Definition (DTD)
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ATTLIST
name (#PCDATA)>
department (#PCDATA)>
GPA (#PCDATA)>
gender (#PCDATA)>
address (#PCDATA)>
entElement (#PCDATA)>
student (name, department, GPA, gender, address) >
class99 (student)+>
entElement
attr1 CDATA "Attr">
<!ATTLIST address
permanent CDATA #IMPLIED
street CDATA "Yes">
<!ATTLIST student id ID #REQUIRED>
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
5- 74
6
Designing and Debugging ATP
Applications
This section provides guidelines for designing and debugging ATP applications. It
includes the following subsections:
•
•
•
•
Designing for Performance on page 6-1
Security Considerations on page 6-3
Writing Robust Scripts on page 6-3
Debugging ATP Applications on page 6-3
Designing for Performance
The following application design and implementation approaches will contribute to the
optimal performance of your applications.
•
Define Caches
Set environment variables to define page, SQL Statement, and TUXEDO field table
caches, as described in ATP Environment Variables on page 2-12.
•
Limit Use of Dictionary
When instantiating atp.dictionary objects, specify the message names
required. Otherwise the whole dictionary will be read and converted to JavaScript
objects. Alternatively, you can use code generated by the dview sample program to
remove the requirement for reading the DDL dictionary and building large object
trees at run time. For more information about these options and their relative
benefits, see atp.dictionary Object Usage Considerations on page 4-26.
•
Specify FML Fields
When instantiating atp.fml_table objects for large FML tables (more than fifty
items), specify the fields required in the atp.fml_table constructor. By default,
the whole FML table is converted to JavaScript objects. Or consider having multiple
smaller field tables. For more information, see atp.fml_table Object on page 4-41.
•
Avoid eval Operator
Minimize use of the JavaScript eval operator. Use parseInt, parseFloat,
object[property] notation where possible. You can refer to properties of an
object by using array subscript notation; for example, obj.prop is the same as
obj[prop]).
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
6 -1
Designing and Debugging ATP Applications
•
Designing for Performance
Concatenate Strings Before Printing
Minimize the use of atp.print by concatenating strings before printing them.
See Example 6-1.
Example 6-1. Concatenating Strings Before Printing
-str = 'some value';
str + 'more';
...
atp.print(str);
For large strings, it can be most efficient to use commas (,) instead of plus signs (+)
in print statements. A plus sign forces ATP to build an intermediate string, whereas a
comma allows the print function to iterate internally through the fields.
•
Let ATP Pass HTML to Browser
Do not explicitly print HTML statements to the browser. If you include HTML in
the clear in your script, ATP automatically and efficiently prints the HTML to the
browser.
•
Use Multiple Pages for Complex Scripts
If your script is long, split it across multiple web pages. Reducing the quantity of
script on each page helps performance, even though you are using more pages.
•
Use C Functions
For an operation that must occur on every transaction (for example, security
checking), consider writing a function in the C programming language to perform
the operation. For example, the function could be performed by a server class.
Whether this technique benefits performance depends on the complexity and other
characteristics of the operation.
•
Manage Memory During Long Loops
If your script uses long loops (more than 5000) iterations around explicit or implied
object constructors, consider using the JavaScript delete operator and the
atp.freeMemory() function to avoid heap buildup. See Example 6-2.
Example 6-2. Managing Memory During Long Loops
s1 = new atp.SQL("select * from =table for browse access ");
s1.execute();
for (limit=0; limit < 10000 && s1.next(); limit++) {
atp.print (s1.column_value, '<br>\n');
for (j=0;j<s1.column_value.length; j++) {
s1.column_value[i] = null;
delete s1.column_value[i];
}
if (limit % 100 == 0) atp.freeMemory();
}
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
6 -2
Designing and Debugging ATP Applications
Security Considerations
Security Considerations
ATP does not provide any security beyond what is provided by the services with which
your script communicates. For example, a script can open a socket and send an SMTP
message.
If your script implements security checking, it should check security each time a page is
loaded, as demonstrated in several of the sample applications on the ATP CD. ATP does
not implement the concept of a session.
Writing Robust Scripts
The following coding practices can improve the tolerance of your scripts to differences
in the characteristics of JavaScript environments:
•
•
•
•
End each function with an explicit return statement.
End each statement with a semicolon (;).
Declare each procedure or function before calling it.
Use braces in if statements.
Debugging ATP Applications
There is no true debugger for the JavaScript environment on Compaq NonStop Kernel
systems. Instead you must rely on standard language features to debug your application.
This section describes several debugging techniques.
General Guidelines
The following guidelines apply to ATP applications in general:
•
•
•
•
•
Display the document source, using browser menu selections, to discover what ATP
actually sent to the browser.
If a table is not displayed, or is not displayed correctly, temporarily remove the
<table> tag. (If an error occurs during construction of a table, the browser will
not present the output until it encounters the </table> tag. Removing the tag lets
you see the table data.)
If the same page contains client-side and server-side JavaScript, check the tags to
make sure the two types of JavaScript are correctly distinguished. Also, take care to
declare and initialize variables in the environment where they apply.
Check the iTP Secure WebServer error log to determine whether a WebServer error
caused the problem you are trying to solve.
Check the event log for errors from underlying services such as NonStop TS/MP,
NonStop TM/MP, NonStop TUXEDO, and NonStop TCP/IP.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
6 -3
Designing and Debugging ATP Applications
•
Displaying Variables
Include error-handling logic after each SQL and TMF operation. Obtain and display
the transid and transaction status, both properties of the atp.transaction
object.
Displaying Variables
Use any of the following techniques to display values of variables:
•
•
•
Add atp.print() statements to the page.
Explicitly print a closing HTML tag to force display of data. (Browsers often do not
output data until a closing HTML tag is encountered.) Try
atp.print('</td></tr></table>' + my_variable). If in the
<head> section, try atp.print('</head>' + my_variable).
Print the contents of an array with one statement of the form
atp.print (my_array)
•
Print the data type of a variable with a statement of the form
atp.print (typeof my_var);
•
Print a function definition with a statement of the form
atp.print (my_func);
•
Enumerate and print the properties of an object with a statement of the following
form, where prop is a property of object x
for (prop in x) {
atp.print ("x contains " + prop + " whose value
x[prop]) }
•
•
is " +
Log changes in variable values using the Javascript watch feature. The file
/examples/debugging/watchlib.inc on the ATP CD demonstrates this
feature by implementing a debugging object called watchlogObject. This object
logs changes in the values of variables, including the name of the function
responsible for each change. A property and methods defined for the object let you
accumulate the trace information in a buffer and later display the information in the
current window or a new window.
While developing or debugging a page, include a function that prints the values of
request variables. Example 6-3 shows an example function:
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
6 -4
Designing and Debugging ATP Applications
Setting Breakpoints
Example 6-3. Function to Print Values of Request Variables
function doDump() {
for (i=0; i<atp.request.variables.length; i++) {
print("+ atp.request.variables[i]"+':'+
atp.request[atp.request.variables[i]]+'<br>');
}
atp.quit(1);
}
if (secureAction &&atp.request.Action =="Find") {
//doDump ();
set_gvals_find ();
gFormName ='PCL';
}
Setting Breakpoints
Stop execution of your script at any point in either of the following ways:
•
Use atp.quit(). To make sure the browser first displays the output, call
atp.print before quitting:
atp.print('</td></tr></table>');
•
Move the </server> tag to the point where you want execution to stop. The
browser will display the subsequent code as text.
Debugging Scripts that Use SQL
The following guidelines apply to applications that use NonStop SQL:
•
•
•
•
•
•
Check the sqlcode after instantiating or invoking a method of an atp.SQL
object.
Check the error property of atp.transaction objects.
If, after using the atp.SQL execute() method for a SELECT statement, the
application failed to retrieve the first row of an SQL table, insert a call to the
next() method after the call to execute(). For a SELECT statement, the
execute() method does not automatically retrieve the first row.
Verify that the application invokes methods against the intended atp.SQL objects.
Copying and pasting code within a script can reduce typing errors but can also
introduce unintended duplication.
When using transaction objects, commit changes explicitly. Transactions are rolled
back by default.
If other techniques do not pinpoint an SQL problem, invoke the dumpSQL method
on the atp.SQL object. That method dumps the cache; the dump includes the
number of statements, whether the cache is full, and other information of potential
interest to Support personnel.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
6 -5
Designing and Debugging ATP Applications
Running the Server-Side JavaScript Environment
from the Korn Shell
Running the Server-Side JavaScript Environment from the Korn Shell
In some situations, for example if the error is “document has no data,” it can be helpful
to view the output from a page in isolation from the browser and the web server.
In such cases, you can run ATP from the OSS shell prompt, as shown in Example 6-4:
Example 6-4. Running ATP from the OSS Shell Prompt
export VARIABLE1_NEEDED_BY_PAGE=value
export VARIABLE2_NEEDED_BY_PAGE=value
./atp.pway
To execute multiple scripts (mypage, mypage1) a specified number of times (value),
use the following syntax:
Example 6-5. Executing Multiple Scripts from the OSS Shell
cat>ztemp<<EOF
mypage.atp
mypage1.atp
EOF
./atp.pway<ztemp
The cat command directs subsequent lines through the end of file to the file ztemp,
and the line ./atp.pway<ztemp specifies ztemp as the input file.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
6 -6
A
SQL Query Tool and Catalog Explorer
The NonStop SQL Query Tool and Catalog Explorer provide an easy way to generate
queries to cut and paste into your ATP scripts. They also demonstrate a sophisticated use
of direct NonStop SQL access from web pages using ATP.
You can use the Catalog Explorer interactively from your browser to view the contents
and structure of a specified SQL catalog and to generate an SQL query against one or
more tables or views. You can use the Query Tool to test a query that you have typed or
generated with the Catalog Explorer. These applications require the use of Netscape
Navigator 3.01 or later or Internet Explorer 4.0 or later. They can accept and display data
and column headings in kanji, katakana, or hangule if your browser is configured to
support those fonts.
The objects used in the programs are the atp.SQL object for query declaration,
execution, and statistics collection, and the atp.sqlvar object for formatting output
based on the query compilation results. Both programs are located in the directory called
/examples/sql_tools/explorer.
This appendix includes the following subsections:
•
•
•
•
•
Installing the Tools on page A-1
Security on page A-2
Using the NonStop SQL Catalog Explorer on page A-3
Using the NonStop SQL Query Tool on page A-4
Usage Techniques on page A-5
Installing the Tools
The ATP installation procedure automatically configures the Query Tool and Catalog
Explorer to run in the same PATHMON environment as the iTP Secure WebServer.
Alternatively, you could run the tools in a separate PATHMON environment; such a
configuration has security advantages, as described in Security on page A-2.
If you wish to run the tools in the same PATHMON environment as the WebServer,
there are no additional steps required to install them (except making sure that the
WebServer is running).
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
A- 1
SQL Query Tool and Catalog Explorer
Security
Security
In the default configuration, ATP applications execute under the same NonStop Kernel
user ID as the iTP Secure WebServer. This security is generally acceptable for
applications in which access to Compaq resources, such as Pathway servers and
NonStop SQL databases, is defined on the web page. In the iTP Secure WebServer
environment, web pages can be stored and configured only by users who have
appropriate permission, just as only certain users are permitted to put a program into
production.
Tools that permit a browser user to enter NonStop SQL statements present a greater
security concern. By default, the browser user would have the same NonStop SQL
privileges as the person under whose user ID the iTP WebServer is running. In addition,
access to the NonStop Query Tool and Catalog Explorer is password-protected using a
default username of sql and password of sql. You should change these default values
by using the useradm utility included with the iTP Secure WebServer. For details, see
the iTP Secure WebServer System Administrator’s Guide, which describes administering
passwords using the useradm utility.
To provide additional security, see the following subsections:
•
•
The .atp_sql_query Filename Extension
Read-Only Access
The .atp_sql_query Filename Extension
To provide for a more flexible and secure environment, you can define a filename
extension other than .atp for use with the NonStop SQL Query Tool and Catalog
Explorer. For example, you could use the extension .atp_sql_query. This
differentiation allows requests for SQL tools to be processed in a different PATHMON
environment (under a different user ID).
Routing of requests, by file extension, to a specific PATHMON environment is specified
by the PathwayMimeMap directive in the atp.config file. In the following
example, requests for pages that have the extension .atp are assigned to the atp
server class in the iTP Secure WebServer PATHMON environment defined by the
httpd.config file that includes atp.config. Requests for pages that have the
extension .atp_sql_query are assigned to the atp server class in the environment
of PATHMON process $DJCP. To implement a configuration like this, your
atp.config file must also include a map define for the PATHMON name you will
use in the PathwayMimeMap directive.
# Requests for 'standard' Server-JavaScript pages...
MimeType application/x-httpd-guardian atp
PathwayMimeMap atp atp
# Requests for SQL query pages...
MimeType application/x-httpd-guardian atp_sql_query
PathwayMimeMap atp_sql_query /G/DJCP:atp
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
A- 2
SQL Query Tool and Catalog Explorer
Read-Only Access
Read-Only Access
The NonStop SQL Query Tool and Catalog Explorer support one additional security
feature: the DO_SQL_SELECT_ONLY environment variable, if present, restricts the
available SQL statements to the SELECT statement only, therefore limiting the user to
read-only access. Include this environment variable in the configuration file as follows:
Region /*.atp_sql_query {
AddCGI DO_SQL_SELECT_ONLY 1
}
Using the NonStop SQL Catalog Explorer
The NonStop SQL Catalog Explorer enables you to select from a list of all catalogs on
the system and display catalog contents such as:
•
•
•
•
•
•
•
Tables
Views
Files
Indexes
Keys
Partitions
View text
By specifying an SQL statement type and other characteristics, you can generate a
NonStop SQL query with the Catalog Explorer, then execute the query with the
NonStop SQL Query Tool.
The SQL Catalog Explorer does not attempt to generate all possible SQL syntax but can
save you considerable typing (and typographical errors).
Running the Catalog Explorer
You can run the Catalog Explorer by selecting it from the ATP home page
(/examples/index.html), by choosing the SQL Catalog Explorer Window from
the Query Tool, or by entering the URL /examples/sql_tools/expsql.
Note. The sample Catalog Explorer included with iTP ATP is now labelled ATP/SQL Edition
internally and has been derived from a demonstration product of the same name.
The Catalog Explorer includes a quick tour and extensive online help. When using the
Catalog Explorer for the first time, be sure to use these two features.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
A- 3
SQL Query Tool and Catalog Explorer
Using the NonStop SQL Query Tool
Using the NonStop SQL Query Tool
The NonStop SQL Query Tool enables you to either type an SQL query or use a query
generated by the Catalog Explorer.
Running the Query Tool
You can run the Query Tool by navigating to it from the ATP home page
(/examples/index.html), by submitting a query from the Catalog Explorer, or by
retrieving a bookmarked query from an earlier session.
Entering a Query
To enter a query, you can type it, retrieve it from a bookmark, paste or submit it from the
Catalog Explorer. If the query requires parameters (represented by question marks in the
query), the Query Tool displays a form to prompt you for each parameter.
Choosing Display Options
Use the radio buttons to indicate whether to use TMF and to specify any of the following
output styles:
•
•
•
Table style (to present the data in columns)
Form style (to present each row as a separate table)
Comma-separated values (for downloading and importing into applications such as
Microsoft Excel)
Use the text boxes to specify the starting row to display and the maximum number of
rows to display.
To bookmark a query in your browser, enter the bookmark label in the text box, then
click the Prepare to Bookmark button. All query options are retained with the query.
Submitting the Query
To submit the query, click on the Submit button. To clear the window, click on the Reset
button. To open a new Query window, click on the New Query button.
You can also use the Query Tool to generate a file that gives Excel access to query
results without needing a browser. Click on Excel97 iqy File to display instructions for
creating such a file.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
A- 4
SQL Query Tool and Catalog Explorer
Usage Techniques
Usage Techniques
When using the NonStop SQL Query Tool and the NonStop SQL Catalog, consider
using the following techniques:
•
•
You can use bookmarks to save the current NonStop SQL Query Tool and the
current NonStop SQL Catalog. Type a bookmark label in the appropriate box and
click the Prepare to Bookmark button.
Whenever reasonable, leave variable values unspecified in your query. When you
submit the query, the Query Tool automatically generates a form to prompt the user
for the variable value. Leaving variable values unspecified increases the generality
of your queries and greatly improves the effectiveness of the SQL statement cache.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
A- 5
SQL Query Tool and Catalog Explorer
Usage Techniques
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
A- 6
B
DDL Dictionary Viewer (dview)
The Data Definition Language (DDL) Dictionary Viewer (dview) is a sample ATP
application and a useful ATP script-development tool. DDL is the Compaq product you
use to define message layouts for applications that use NonStop TS/MP.
When you use dview, you specify the name of a DDL dictionary and select a message
layout. In response, dview displays information about the message layout and
generates atp.field object constructors you can paste into your script.
As a sample application, dview demonstrates the use of the atp.dictionary,
atp.field, and atp.request objects and several ATP global functions, including
atp.print and atp.quit.
This appendix includes the following subsections:
•
•
•
•
•
•
Installing dview on page B-1
Running dview on page B-1
Choosing a DDL Dictionary on page B-2
Choosing a Message Layout on page B-2
Studying the Message Layout on page B-2
Using the Field Object Constructors on page B-2
Installing dview
The dview application and a sample dictionary are installed automatically when you
run the ATP installation script. You must create and populate any other dictionary you
wish to use.
Running dview
To run dview, navigate to the DDL Dictionary Viewer from the ATP home page
/examples/index.html.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
B- 1
DDL Dictionary Viewer (dview)
Choosing a DDL Dictionary
Choosing a DDL Dictionary
The first step in using dview is to enter the name of the DDL dictionary that defines
the message layouts for your application. In the text entry field, enter either of the
following:
•
•
The name of an OSS symbolic link to your dictionary subvolume. You use the OSS
ln command to create a symbolic link. The name is relative to the directory of the
current script (the directory where dview is installed) and must not start with a
period (.) or a slash (/).
The name of the Map Class Define that refers to the dictddf file in the DDL
dictionary subvolume. You use the MapDefine command in the httpd
configuration file to establish the define; see the ATP configuration-file fragment for
examples.
After you enter the name of your dictionary, click on the Set Dictionary button.
The Reset button clears the text entry field so you can specify a different dictionary.
Choosing a Message Layout
After choosing the dictionary, you see a screen that repeats the dictionary name you
specified, then lists all the message layouts defined in the dictionary. Click on the name
of the layout for the message you wish to create in your script.
Studying the Message Layout
The Message Layout Details screen lists all the fields and structures in the message you
selected. For each component of the message, it displays the nesting level (familiar from
COBOL: a higher level number means the component is nested in a component of the
next lower level) followed by the field or structure name, data type, COBOL type code,
offset, length, number of occurrences in the message, and number of decimal places.
The screen also displays field object constructors corresponding to the components of
the message.
Using the Field Object Constructors
Dview creates two sets of field-object constructors:
•
A function that has a name of the form def_message-layout creates a
hierarchy of new atp.field objects that represent the message and each of its
components. (Message-layout is the name of the layout you specified.) You can
cut and paste the def_message-layout function into your script to create the set
of objects. Alternatively, you can provide the field constructors individually as
arguments to the atp.buffer setData, getData, and setBinary methods
to set or retrieve information from the fields.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
B- 2
DDL Dictionary Viewer (dview)
Using the Field Object Constructors
Note. Unlike the atp.dictionary object, which dynamically accesses the DDL
dictionary and changes the structure of the message in response to changes in the
dictionary, the constructors dview creates are static: the message structure doesn’t
change even if the dictionary changes. Using static constructors helps the performance of
your script by reducing the number of reads from the dictionary file. You can place the
static constructors in a server-side include file to facilitate maintenance.
•
A function that has the name of the form defarray_message-layout
populates the fields array of the atp.field object representing the message
layout. (Message-layout is the name of the layout you specified.) A script does
not use the fields array to operate on the fields of a message; the array is useful
primarily for dictionary browsers and other tools that retrieve and display
information about message structures.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
B- 3
DDL Dictionary Viewer (dview)
Using the Field Object Constructors
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
B- 4
C
HTML Forms Generator
The HTML Forms Generator is a sample ATP application and a useful ATP scriptdevelopment tool.
When you use the Forms Generator, you specify the name of a DDL dictionary and
select the message layouts for request and reply messages. (You can choose multiple
reply formats, each for a different reply code or range of reply codes.) In response, the
Forms Generator produces an HTML form that sends a request to a NonStop TS/MP
application and retrieves the reply.
A form produced by this tool is intended not as a production script, but as a starting
point. You add data validation and security logic appropriate to your application.
As a sample application, the Forms Generator demonstrates the use of many ATP
objects, including the atp.dictionary, atp.field, atp.buffer,
atp.transaction, and atp.request objects and several ATP global functions,
including atp.print and atp.quit.
This appendix includes the following subsections:
•
•
•
•
•
•
Installing the Forms Generator on page C-1
Running the Forms Generator on page C-1
Choosing a DDL Dictionary on page C-2
Choosing Request and Reply Messages on page C-2
Finishing the Generated Page on page C-4
Usage Considerations on page C-4
Installing the Forms Generator
The HTML Forms Generator and a sample dictionary are installed automatically when
you run the ATP installation script. You must create and populate any other dictionary
you wish to use.
Running the Forms Generator
To run the HTML Forms Generator, navigate to it from the ATP home page
/examples/index.html.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
C- 1
HTML Forms Generator
Choosing a DDL Dictionary
Choosing a DDL Dictionary
The first step in using the HTML Forms Generator is to enter the name of the DDL
dictionary that defines the message layouts for your application. In the text entry field,
enter either of the following:
•
•
The name of an OSS symbolic link to your dictionary subvolume. You use the OSS
ln command to create a symbolic link. The name is relative to the directory of the
current script (the directory where dview is installed) and must not start with a
period (.) or a slash (/).
The name of the Map Class Define that refers to the dictddf file in the DDL
dictionary subvolume. You use the MapDefine command in the httpd
configuration file to establish the define; see the ATP configuration-file fragment for
examples.
After you enter the name of your dictionary, click on the Set Dictionary button.
The Reset button clears the text entry field so you can specify a different dictionary.
Note. Scanning the DDL dictionary to retrieve the list of message layouts can be timeconsuming, depending on the size of the dictionary. To avoid repeating the operation on
subsequent uses of the Forms Generator, save the list to an HTML file, using the browser
Save As feature. Later, to get the list of message layouts, you can open the HTML file in your
browser. Edit the HTML file to restrict the set of message layouts to the subset you really plan
to use. This technique saves only the message layouts, not a filled-out form.
Choosing Request and Reply Messages
The screen you see next, after choosing a DDL dictionary, repeats the name you entered
on the first screen, then lists all the message layouts defined in the dictionary. Click on
the name of the layout for the message you wish to create in your ATP script.
Note. To browse the DDL dictionary as a basis for selecting message layouts, you can use the
DDL Dictionary Viewer (dview), described in Appendix B, DDL Dictionary Viewer (dview).
Use the radio buttons in the Request column to select the format of the request message
to be sent to the server class. You can select only one request message.
Use the check boxes in the Reply column to select the format of each type of reply
message the server class can return. In the Reply Code column, type an expression
indicating the condition in which each type of reply message should be returned. The
variable rc represents the reply code that occupies the first two bytes of a reply message
from a Pathway (NonStop TS/MP) server. Use the C expression operators ==, !=, <, >,
<=, >=, !, || and &&, and the keywords (true) and (false) to express the desired
condition.
In the text entry box labeled Pathmon Process, enter the name of the Map Class Define
that identifies the name of the PATHMON process that monitors the target server class.
The Map Class Define must be established in the httpd.config file.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
C- 2
HTML Forms Generator
Choosing Request and Reply Messages
In the text entry box labeled Pathway Server Class, enter the name of the server class as
defined in the PATHCOM configuration file for the environment where the server class
runs.
Use the radio buttons to indicate whether the server class is written in C or COBOL.
Under TMF Options, use the check box to indicate whether the transaction will be TMF
protected (that is, whether an atp.transaction object will be instantiated). In the
text entry box, indicate the condition under which the transaction is committed; the
condition must be based on the value of the reply code and has the same syntax as the
Reply Code column in the message-layout table.
Use the radio buttons after the heading Message Layouts to indicate one of the following
three options:
•
•
•
Use dictionary at runtime. If you select this option, the script creates an
atp.dictionary object that continually monitors changes in the DDL
dictionary. This option ensures that the message layouts are kept up-to-date as the
application runs but implies a potentially large number of disk accesses to read the
DDL dictionary.
Imbedded definitions. If you select this option, the Forms Generator reads the
dictionary once and creates the correct message structures in JavaScript on the web
page. If the DDL dictionary changes, the message structures will be out-of-date
unless you regenerate the script. You could, of course, modify the generated script
manually after the dictionary changes.
atp.field constructors. If you select this option, the Forms Generator creates
atp.field objects for each message and its constituent fields (just as dview
does). If the DDL dictionary changes, the message structures will be out-of-date
unless you regenerate the script. You could create new constructors and paste them
into the script, but this approach can be tedious and error prone. This option can
provide better performance than either of the others, but the maintenance cost makes
Imbedded definitions a better choice for most applications.
Use the check boxes after Appearance Accessories to indicate whether the generated
page should have a sketch of the message structure and/or an HTML link to the
definition of the form. A sketch, displayed in the upper right corner of the screen, can
clarify the structure of a long, complex message and provide a quick way to navigate
among message components: click on a component of the sketch to position to the
corresponding component in the full message layout. An HTML link to the form
definition displays an encoded version of the information you entered to create the form.
Click on the Generate HTML Form button to generate an HTML page that
communicates with the specified server class. Click on the Reset button to clear all
settings on the current form.
Finally, the Forms Generator displays the generated page. If you are using Internet
Explorer, that browser might attempt to interpret the HTML instead of just displaying it;
the result will be a garbled display. In this case, use the browser View Source option,
then copy and paste, or use the browser Save As option to save the page.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
C- 3
HTML Forms Generator
Finishing the Generated Page
Finishing the Generated Page
To prepare the generated page for use, you should
•
•
•
•
•
Test it by opening it with a browser.
Add field validation logic and default values.
Add security logic if your application requires it.
Add error handling and message.
Add code to support COBOL redefines, C unions, and COBOL occurs. The last of
these features is optional but improves the appearance of the page.
Usage Considerations
When using the Forms Generator, consider using the following techniques:
•
•
You can use bookmarks to save the current list of message layouts and parameter
settings for later use. Type a bookmark label in the appropriate box and click the
Prepare to Bookmark button. Then use the facilities of your browser to save the
bookmark. When you later retrieve the bookmark, you implicitly run the Forms
Generator.
Complex message layouts can result in very large generated pages that can be costly
for ATP to parse and therefore slow to load. For large pages, use the
ATP_PAGE_CACHE_SIZE environment variable, described in ATP Environment
Variables on page 2-12, to allocate a cache; use of a cache dramatically speeds up
subsequent loads of the same page.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
C- 4
D
JavaScript Utility Driver (jud)
The JavaScript Utility Driver (jud) for NonStop TUXEDO Servers is an ATP script
that implements the NonStop TUXEDO ud utility. jud shows how to use ATP to
communicate with NonStop TUXEDO servers and is also useful as an application
prototyping and testing tool.
When you use jud, you specify the NonStop TUXEDO field table and view names and
select the fields to be send to the server. jud builds a transaction message, sends the
request to a NonStop TUXEDO application, and retrieves the reply.
jud demonstrates the use of the atp.fml_field, atp.fml_table,
atp.fml_buffer, and atp.transaction objects.
This appendix contains the following subsections:
•
•
•
•
•
Installing jud on page D-1
Running jud on page D-1
Specifying the Environment on page D-1
Building the Request Buffer on page D-2
Displaying the Reply Message on page D-3
Installing jud
The jud utility is installed automatically when you run the ATP installation script. By
default, jud uses the standard TUXEDO bankapp application. You must create and
populate any other field tables or applications you wish to use.
Running jud
To run jud, navigate to the JavaScript Utility Driver from the ATP home page
/examples/index.html.
Specifying the Environment
jud displays an HTML form on which you enter the following information:
•
•
•
Service name. Choose the name of the desired TUXEDO service from the scroll list,
or type the name of a service not in the list. This item is required.
Client name. Enter the client name in the text entry field, as specified in the
NonStop TUXEDO configuration. This item is optional.
TUXEDO directory. Enter the full pathname of the directory in the text entry field.
If you specified a value in the httpd.config file, as described in ATP in the
WebServer Configuration File on page 2-8, jud displays that value as the default
for this item. This item is required.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
D- 1
JavaScript Utility Driver (jud)
•
•
•
•
•
•
•
Building the Request Buffer
User name. Enter the user name in the text entry field, as specified in the NonStop
TUXEDO configuration. This item is optional.
TUXEDO configuration file. Enter the full pathname of the TUXEDO configuration
file. If you specified a value in the httpd.config file, as described in ATP in the
WebServer Configuration File on page 2-8, jud displays that value as the default
for this item. This item is required.
TMF or no TMF. Use the radio buttons to indicate whether you require transaction
protection.
FML or FML32. Use the radio buttons to specify the required type of FML buffer.
FML View. Enter the name of the view in the text entry field.
Password. Enter a password, if the application requires one.
Data. This item contains initialization data from the NonStop TUXEDO TPINIT
structure.
Below the form is a list of current values of various NonStop TUXEDO environment
variables.
Building the Request Buffer
Next, you enter the names of the field tables or associated views that you plan to use.
(See the NonStop TUXEDO manual set for information about views.) The text entry
boxes allow for two entries. In general, one should be the field table that defines the
fields in the application messages, and the other should be Usysflds to provide for
status reporting in the response. The Another option lets you specify more field tables or
views; there is no limit to the number you can specify.
After entering the field-table names, click on the Redraw for Field Selection button at
the top of the form. jud displays a matrix of all the fields defined in each field table.
For each field to be included in the request buffer, check the Keep box.
Next, click on Redraw Showing Selected Fields. For each field, enter the field count
(that is, the number of occurrences of the field), and type a value in the data entry area.
Note. jud does not ensure that the fields and values you specify will combine to form a buffer
meaningful to the server. To use jud, you must know what fields the server expects and what
range of values (apart from the data type) is valid for any field.
Use the buttons near the top of the form to perform any of the following functions at any
time:
•
•
Redraw showing all fields. Redraws the matrix for each field table, including all
defined fields. (Choose this option if you previously redrew the matrix with only a
subset of the fields.)
Redraw showing selected fields. Redraws the matrix for each field table, including
only fields that have the check box marked.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
D- 2
JavaScript Utility Driver (jud)
•
•
•
Displaying the Reply Message
Redraw for field selection only. Redraws the matrix, permitting field selection but
not data entry.
Do NonStop TUXEDO tpcall. Sends the buffer to the NonStop TUXEDO server.
Reset. Clears the form.
Displaying the Reply Message
When you click the Do NonStop TUXEDO tpcall button, jud sends the buffer to the
server, waits for the reply, and displays the reply in two formats:
•
•
The first format lists the fields of the reply in the order in which they occur in the
reply buffer.
The second format lists the fields by field count. It resembles a spreadsheet.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
D- 3
JavaScript Utility Driver (jud)
Displaying the Reply Message
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
D- 4
E
XML for ATP Tools
These tools are provided for the XML for ATP add-on module:
•
•
ATP WSDL Wizard
ATP WSDL Viewer
ATP WSDL Wizard
A WSDL (Web Services Description Language) document is an XML-encoded
document that describes web services as a set of endpoints operating on messages. The
operations and messages are described both in abstract concept and concrete network
protocol and message formats. With these descriptions, a client application could format
request messages to access specific operations and interpret corresponding response
messages.
The ATP WSDL Wizard is a step-by-step tool that guides you to create a WSDL
document for your web services. By publishing a WSDL document, you effectively
publish your web services to any SOAP clients that have access to this document.
The current version of the ATP WSDL Wizard is implemented according to WSDL
specifications 1.1 (see http://www.w3.org/TR/2001/NOTE-wsdl-20010315) with the
following considerations:
•
•
•
•
•
Supports procedure-oriented messages (RPC style)
Supports either one-way operation or request-response operation
Supports any number of input arguments (message parts) but only one output
argument (message part), which is the return value
Supports simple data types (string, int, double)
Creates single service and single port in a document
Caution. The ATP WSDL Viewer is written as a sample program using the ATP SOAP Library
and is provided as is. You are free to include it in your application or change it for your own use.
However, any use of this tool is at your own risk. Compaq does not assume any responsibility
for this tool and does not support this tool.
To use this tool, you need to provide the following information about your web services:
•
•
•
•
•
WSDL File Name
Host Name
Service Name
Port Name
Number of Operations
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
E- 1
XML for ATP Tools
ATP WSDL Viewer
ATP WSDL Viewer
The ATP WSDL Viewer tool loads a WSDL document, interprets it, and displays its
content in terms of service, port, operations, and message formats. Client application
developers can use this tool to view published WSDL documents and format their
SOAP request messages accordingly.
This version of the ATP WSDL Viewer accepts WSDL documents written according to
WSDL specifications 1.1 (see http://www.w3.org/TR/2001/NOTE-wsdl-20010315) with
the limitation that it supports only simple data types, and not complex data types.
Caution. The ATP WSDL Viewer is written as a sample program using the ATP SOAP Library
and is provided as is. You are free to include it in your application or change it for your own use.
However, any use of this tool is at your own risk. Compaq does not assume any responsibility
for this tool and does not support this tool.
To use this tool, you need to provide the following information about your web services:
•
•
•
WSDL File Name
Service Name
Port Name
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
E- 2
F
ATP Examples
The /usr/tandem/atp/<version>/examples directory contains subdirectories
for
•
•
•
•
•
•
•
•
•
HTML files such as home pages, and image files used on those pages. The ATP
home page is at /examples/index.html.
Pathway applications, such as homebank
Pathway tools, such as the DDL Dictionary Viewer and Forms Generator
Sockets applications, such as a class library for HTTP
SQL applications, such as another version of homebank
SQL tools, such as the Query Tool and Catalog Explorer
TUXEDO applications, such as bankapp
TUXEDO tools, such as the JavaScript Utility Driver (jud)
Debugging routines using the JavaScript watch feature
The /usr/tandem/atp/pkgs/<version>/samples directory stores all source
files for the XML for ATP add-on sample applications.
This appendix includes the following subsections:
•
•
•
Index to ATP Examples on page F-2
General-Purpose Functions in ATP Examples on page F-4
Objects Defined in the XML for ATP SOAP Library on page F-6
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-1
Index to ATP Examples
ATP Examples
Index to ATP Examples
Table 6-1 lists some of the example scripts provided on the ATP CD. The first column
lists common ATP programming tasks. The second column gives the names of example
applications or scripts that demonstrate each task. Pathnames are relative to
/usr/tandem/atp.
Note. Compaq does not represent the ATP example programs as complete or suitable for
production use.
Pathnames are relative to /usr/tandem/atp.
Table 6-1. Examples by Programming Task (page 1 of 2)
ATP Programming Task
Example Application or Script(s)
Accessing a web site from a
page, to include context from
the site on the page
examples/sockets/classlib.atp, nested.atp
Browser and version checking
examples/pathway_tools/form_generator/ibcheck.atp,
examples/sql_tools/explorer/ibcheck.atp
Classes, declaring and using
examples/sockets/iurlclass
(The JavaScript HTTP Class Library iurlclass does not
support any new features provided by HTTP/1.1)
Client-side and server-side
JavaScript on the same page
examples/pathway/homebank/Webpages/address.atp,
examples/sql/homebank/Webpages/address.atp
Client-side and server-side
script generation
examples/pathway_tools/form_generator
Client-side validation
examples/pathway/homebank/Webpages/address.atp,
examples/sql/homebank/Webpages/address.atp
Debugging with JavaScript
watch capability
examples/debugging/watchlib.inc
Echoing environment variables
examples/sockets/echo.atp
File upload (blob object)
examples/file_upload (directory)
Forms-based application
examples/pathway/homebank, examples/sql/homebank
Forms, creating dynamically
from information in a DDL
dictionary
examples/pathway_tools/form_generator,
examples/pathway_tools/ddl_viewer
Forms, creating dynamically
from information in an SQL
catalogue (using sqlvar object)
examples/sql_tools/explorer
Frames, multiple
examples/pathway/homebank, examples/sql/homebank
html generation based on
information from an SQL
database
examples/sql/acct_list
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-2
Index to ATP Examples
ATP Examples
Table 6-1. Examples by Programming Task (page 2 of 2)
ATP Programming Task
Example Application or Script(s)
Iterating through message
layouts, recursively
examples/pathway_tools/ddl_viewer
Pathway servers, sending to
(shared wrapper routines)
examples/pathway/employee
Record management, display,
and update
examples/pathway/homebank/Webpages/address.atp
Record management, insert, and
update
examples/pathway/homebank/Webpages/address.atp
Security:logon, creating a
session, timeouts (aging),
security for users to perform
specific functions
examples/pathway/homebank/Webpages/access_check.inc,
examples/pathway/homebank/Webpages/logon.atp,
examples/sql/homebank/Webpages/access_check.inc
SMTP message, sending from
script
examples/sockets/sendmail.atp
SQL cursors
examples/sql/homebank
SQL SELECT
examples/sql/acct_list,
examples/sql_tools/explorer/expquery.atp
SQL UPDATE and DELETE
examples/sql/homebank
Tuxedo and SQL in one script
examples/tuxedo/bankapp/transfer.atp
Tuxedo fml and fml_buffer
objects
examples/tuxedo_tools/javascript_ud
The following are available for the XML for ATP add-on package only
SOAP Calculator Server - Add,
Subtract, Multiply, and Divide
operations
samples/atpxml/soap/atp_soap_samples_p1.html
SQL/MP Virtual Agent - Use
the XML for ATP and the
HTTP client interface in
conjunction with NonStop
SQL/MP database for real
world e-commerce applications
samples/atpxml/db_xml/DBxml.html
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-3
General-Purpose Functions in ATP Examples
ATP Examples
General-Purpose Functions in ATP Examples
Table 6-2 lists functions defined in the example scripts provided on the ATP CD. This
list isn’t complete: however, it includes the functions applicable to a wide range of
applications. You can copy and modify these functions for use in your own scripts.
Note. Compaq does not represent the ATP example programs as complete or suitable for
production use.
Some functions are associated with specific objects defined in the examples. These
objects are not part of the standard ATP interface; they are on the product CD to give
you ideas for your own scripts.
File locations are relative to the directory /usr/tandem/atp.
Table 6-2. Functions Defined in ATP Examples (page 1 of 3)
Function Name
What It Does
Where to Find It
The following functions are defined for the
SQLQuery object
doSQLClose
Closes an SQL object and the
related transaction object, if
present. Reports an SQL
error if appropriate.
examples/sql_tools/explorer/isql.inc
doSQLColumnValue
(col)
Returns a value from the
SQL object column_value
array.
examples/sql_tools/explorer/isql.inc
doSQLError ()
Displays a message reporting
an SQL error.
examples/sql_tools/explorer/isql.inc
doSQLGetSQLcode
()
Returns the SQL error code.
examples/sql_tools/explorer/isql.inc
doSQLNext ()
Reads an SQL table, stopping
when there are no more rows
or when an error occurs.
examples/sql_tools/explorer/isql.inc
doSQLPrintColumnV
alue (col)
Prints a value from the SQL
object column_values array.
examples/sql_tools/explorer/isql.inc
doTMFcommit ()
Commits a transaction and
reports an error if
appropriate.
examples/sql_tools/explorer/isql.inc
doTMFrollback ()
Rolls back a transaction and
reports an error, if
appropriate.
examples/sql_tools/explorer/isql.inc
SQLBuildExecute
(query)
Builds and executes an SQL
query, using parameters from
the request. Optionally
specifies a transaction.
examples/sql_tools/explorer/isql.inc
SQLError (stmt)
Prints an SQL error.
examples/sql/acct_list/acct_list.atp
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-4
General-Purpose Functions in ATP Examples
ATP Examples
Table 6-2. Functions Defined in ATP Examples (page 2 of 3)
Function Name
What It Does
Where to Find It
SQLQuery (query,
tmf, maxrows,
skiprows)
Creates an SQL object and
optionally a transaction
object, and executes the
query.
examples/sql_tools/explorer/isql.inc
SQLQueryCreate
(query)
Creates an SQL object and
optionally a transaction
object, but does not execute
the query.
examples/sql_tools/explorer/isql.inc
The following functions are defined for the URL
object
doSocketErrors
(comment)
Formats a message reporting
a socket error, and stops
execution of the script.
examples/sockets/iurlclass.inc
doURLClose
Closes a URL.
examples/sockets/iurlclass.inc
doURLOpen
Opens a URL and sends
name/value pairs.
examples/sockets/iurlclass.inc
doURLPrint
Retrieves and prints the
contents of a URL.
examples/sockets/iurlclass.inc
doURLPrintHeaders
Prints HTTP headers.
examples/sockets/iurlclass.inc
doURLRead
Reads URL data, and parses
headers.
examples/sockets/iurlclass.inc
URL (protocol, host,
port, file)
Creates a URL object.
examples/sockets/iurlclass.inc
The following functions are defined for the
variables object
doAddVariable
(name, value)
Stores a variable name in the
variables array, and stores the
corresponding value in the
property for that variable
name.
sockets/iurlclass.inc
variablesObject ()
Creates an array of
name/value pairs.
sockets/iurlclass.inc
The following functions are not part of any object
definition
accessCheck
(accessNumber,
serviceName)
Checks a user’s logon ID to
authorize access to the
application.
examples/pathway/homebank
/WebPages/access_check.inc
isDigit (s)
Returns true if the supplied
value is a digit (0-9); returns
false otherwise.
examples/pathway/homebank
/Webpages/util_client.inc
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-5
Objects Defined in the XML for ATP SOAP Library
ATP Examples
Table 6-2. Functions Defined in ATP Examples (page 3 of 3)
Function Name
What It Does
Where to Find It
isMoney (s)
Returns true if the supplied
value is in dollars-and-cents
format; returns false
otherwise.
examples/pathway/homebank
/Webpages/util_client.inc
isPositiveInteger (s)
Returns true if the supplied
value is a positive integer;
returns false otherwise.
examples/pathway/homebank
/Webpages/util_client.inc
RemoveSpaces
Removes spaces from a
string.
examples/pathway/homebank
/Webpages/util_client.inc
sendMail (smtphost,
from, fromHost, to,
toHost, subject,
message)
Sends a mail message, using
Simple Mail Transfer
Protocol (SMTP).
examples/sockets/sendmail.atp
sendToServer
(application,
serverClass,
dictionary,
requestBuf)
Sends a request message to a
server class, using the
Pathsend facility of NonStop
TS/MP.
examples/pathway/employee
/employee_list.atp
Objects Defined in the XML for ATP SOAP Library
Table 6-3 lists objects defined in the example scripts provided on the ATP CD for the
XML for ATP add-on interface. They are not part of the standard ATP interface. This list
isn’t complete: however, it includes the functions applicable to a wide range of
applications. You can copy and modify these objects for use in your own scripts.
Note. Compaq does not represent the XML for ATP example programs as complete or suitable
for production use.
File locations are relative to the directory /usr/tandem/atp/samples/soaplib.
Table 6-3. Objects Defined in the XML for ATP SOAP Library (page 1 of 2)
Object Name
What It Does
Where to Find It
These objects provide a low-level interface for client and
server applications to process and format SOAP messages
SoapReader
Enables a server application to read
and interpret a SOAP request message
and a client application to read and
interpret its SOAP response message.
SoapReader.inc
SoapSerializer
Enables a server application to format
and return a SOAP response message
and a client application to format and
send its SOAP request message.
SoapSerializer.inc
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-6
Objects Defined in the XML for ATP SOAP Library
ATP Examples
Table 6-3. Objects Defined in the XML for ATP SOAP Library (page 2 of 2)
Object Name
What It Does
Where to Find It
SoapException
Reports an exception in the previous
operation when methods encounter an
error. A SoapException reports a
problem in the SOAP protocol level
and can wrap an ATPException caught
in the SOAP Library. An
ATPException usually reports XML,
ATP internal, or JavaScript level
exceptions.
SoapException.inc
SoapFault
Reports problems encountered while
processing a SOAP request. Invoking
this function creates a SoapSerializer
to format the required <Envelope>,
<Body>, and <Fault>.
SoapFault.inc
These objects provides an object interface for a SOAP
application to read and interpret a WSDL document
WSDLReader
Enables a SOAP application to read a
WSDL document. A WSDLReader
represents a WSDL document.
WSDLReader.inc
CollWSDLServices
Represents a collection of services
defined in a WSDL document.
CollWSDLServices.inc
WSDLService
Represents a service defined in the
WSDL document.
WSDLService.inc
CollWSDLPorts
Represents a collection of ports
defined in a WSDLService. A port
defines the endpoint of the service.
CollWSDLPort.inc
WSDLPort
Represents a port defined in the
WSDL document.
WSDLPort.inc
CollWSDLOperations
Represents a collection of operations
defined in a WSDLPort.
CollWSDLOperations.inc
WSDLOperation
Represents an operation defined in a
WSDLPort.
WSDLOperation.inc
CollSoapMappers
Represents a collection of message
parts defined in a WSDLOperation.
CollSoapMappers.inc
SoapMapper
Represents an message part defined in
a WSDLOperation.
SoapMapper.inc
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-7
ATP Examples
Objects Defined in the XML for ATP SOAP Library
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
F-8
G
Migration Considerations
There are four subsections to this appendix:
•
•
•
•
The new Javascript runtime engine and ATP have some differences in operation.
For further details, consult Runtime Operation Differences.
Changes to the way the atp parser preprocesses your source files means that you
may receive more error messages than previously. For further details, consult ATP
Parser Differences.
If you have selected Tuxedo 6.5 support and want to use some of the example
scripts, consult Tuxedo 6.5 Support.
Other General Considerations.
Runtime Operation Differences
IEEE floating-point support is available as an add-on option when the target
hardware/software system supports it. If your system does not support IEEE floating
point, the following conditions apply.
NaN, POSITIVE_INFINITY, and NEGATIVE_INFINITY are not defined in the NSK
platform. As a result, the following conditions apply:
Floating Point
•
•
•
•
•
•
•
isNaN always returns false
isFinite always returns true
MAX_VALUE = 1.15792089237316192e77
MIN_VALUE = -1.15792089237316192e77
NaN = 0
POSITIVE_INFINITY = MAX_VALUE
NEGATIVE_INFINITY = MIN_VALUE
Math Objects
•
•
Only one object failed.
Math.atan2(x, y) failed in ECMA test cases with the following values.
(0, 0), (0, -0), (-0, 0), (-0, -0), (-0, -1)
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
G- 1
Migration Considerations
ATP Parser Differences
Number
•
JavaScript variable has no data type. Double is the internal data type for all numbers
in JS engine
atp.print(Number(123456789.00)) -> 123456789
•
NSK is not good at double arithmetic precision, for example:
atp.print(Number(2147483648)) = 2147483648
atp.print(Number(2147483649)) = 2147483648.99999999
atp.print(Number(2147483649).toPrecision(10)) = 2147483649
parserInt
•
•
Can only handle value from -2147483648 to 2147483647
Overflow/Underflow will return the string ‘NaN’.
Array
•
•
ATP 2.0 max array size -> 2147483646
ECMAv3 max array size -> 4294967295
ATP Parser Differences
In general, ATP releases V20 and V21 perform more syntax checking than previous
versions while preprocessing the source files.
Server -Side Script Tags
Unmatched tags: The ATP parser will report an error if there is no end-tag for the
corresponding begin-tag.
Server-Side Includes
This is not allowed, and an error will be reported by the ATP parser if you have a serverside include tag inside a Javascript function body. For example,
Source File: xyz.atp
<server>
function abc ( ) {
<!-- #include file= “abc.atp” -->
...
}
</server>
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
G- 2
Migration Considerations
ATP Parser Differences
An error message will be returned.
xyz.atp:3: missing } after function body:
xyz.atp:3: function abc ( ) {
xyz.atp:3: .................
xyz.atp (1): ATP parser error:compile failed
Remember, the application can call the atp.execute method to implement the same
functionality. See Global Functions for further details.
ATP Objects
atp.request
This variable property is read-only. If you try to modify the value, ATP will report an
error message.
atp.sql methods
•
•
close
ATP 2.0 releases the internal cache entry of the SQL statement when the close
method is called. The subsequent methods like execute or next report an error,
“Invalid SQL statement”, after the close method. The close method between
multiple execute methods is not necessary for the same SQL statement on the same
page. ATP V20 closes and re-opens the internal SQL cursor for the second and
subsequent execute methods.
execute
ATP V20 checks the number and types of parameter values passed by the
applications. ATP reports errors if the syntax of the parameters violates the
following rules:
° There must be one parameter for each SQL placeholder in the SELECT
statement.
° If the number of parameters is greater than the number of SQL variable
placeholders in the SELECT statement, the type of parameter following the last
SQL placeholder must be the atp.transaction object.
° You must check the validity of your own data. ATP V21 performs data
conversions without checking validity. See Example G-1.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
G- 3
Migration Considerations
Tuxedo 6.5 Support
Example G-1. Checking the Validity of Your Data Conversions
<server>
tran = new atp.transaction();
TMFError("instantiate object");
s = new atp.SQL("update $data.sqld030.btre204 set FLOAT_BASIC =
?floatb where char_1 ='C' for stable access");
if (s.sqlcode != 0) SQLError(s);
s.execute('xyz',tran);
if (s.sqlcode !=0) SQLError(s, "execute()");
tran.commit();
</server>
The value of 0 is inserted into the FLOAT_BASIC field. No error
message
of an invalid data input is generated.
Error status check functions:
<server>
function SQLError (stmt,func) {
atp.print ("\nSQL error.. stmt=" + func + ";\n" +
"cursor=" + stmt.cursor + "; " +
"sqlcode=" + stmt.sqlcode + "; " +
"file system error=" + stmt.filesystem_error + ";\n " +
stmt.sqlca + "\n" );
}
function TMFError (stmt, func) {
atp.print ("TMF " + func + ": NSK error=" + stmt.error + "; "+
"status=" + stmt.status + "\n");
}
</server>
Tuxedo 6.5 Support
If you have selected Tuxedo 6.5 support at configuration, be sure to set the
environmental variable ATP_TUXEDO_VERSION = 65. See Environment Variables for
further details.
If you want to use the banking examples file with Tuxedo 6.5, take note of the following:
•
•
In the /usr/tandem/atp/examples/tuxedo/bankapp/transfer.atp file, change the name
‘bank.flds’ to ‘bankflds’; that is, remove the period.
Change the following line in the atp-tuxedo.config:
From this - AddCGI FIELDTBLS Usysflds,bank.flds
To this - AddCGI FIELDTBLS Usysflds,bankflds
In other words, remove the period.
General Considerations
•
The saveabend option is enabled in ATP V21. Therefore ATP will create a large
number of ZZSA files under normal CGI connection abort conditions.
If this is unacceptable, you must set the environment variable
TANDEM_CGI_CONNECTION_ABORT=NO.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
G- 4
Glossary
This glossary defines terms used both in this manual and in other Compaq manuals.
Both industry-standard terms and Compaq-specific terms are included.
application program interface (API). The set of functions or procedures that permits a
user’s programs to communicate with the NonStop Kernel operating system kernel and
services.
attribute. An item of descriptive data associated with an XML element. An attribute has a
name and a value.
attribute type. A type of data that can be contained in the value of an attribute, such as ID,
IDREF, ENTITY, CDATA, and so on.
browser. A graphical user interface (GUI) used to access sites on the World Wide Web.
Netscape, Internet Explorer, Mosaic, and Lynx are commonly used browsers.
CCITT (International Telegraph and Telephone Consultative Committee). A division of
the United Nations International Telecommunications Union that coordinates standardssetting activities.
CGI. See Common Gateway Interface (CGI)
CERN. The European Laboratory for particle physics. The originators of the HyperText
Transport Protocol (HTTP) and HyperText Markup Language (HTML) concepts.
character data (CDATA). The text in an XML document that is not part of the document’s
mark up and that is not parsed by the XML parser.
CommerceNet. A consortium that was formed in Silicon Valley to promote electronic
commerce over the Internet.
Common Gateway Interface (CGI). A standard protocol used as the interface between web
servers and the programs these servers use to process requests from web clients.
Compaq NonStop Kernel. The Compaq operating system, which consists of core and
system services. The operating system does not include any application program
interfaces (APIs).
connection. The path between two protocol modules that provides reliable stream delivery
service. In the Internet, a connection extends from a Transmission Control Protocol
(TCP) module on one machine to a TCP module on another machine.
Data Definition Language (DDL). A A mechanism, proprietary to Compaq, for describing
data structures, such as request and response formats supported by a NonStop TS/MP
application.
deployment descriptor. The web.xml file that contain resource definitions such as MIME
types, mapping of requests to servlets, access control and servlet initialization
parameters.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 1
Glossary
DNS
DNS. See Domain Name Server (DNS).
disk files. Standard POSIX or Guardian style disk files. The file names of POSIX disk files
comply with the POSIX specifications.
distinguished name (DN). The complete name of a directory entry, consisting of the Relative
Distinguished Name (RDN) of the entry and the RDNs of its superior entries.
Distributed Systems Management (DSM). An architecture and standard interfaces that
enable you to build new applications and subsystems. DSM provides a number or
products, many of which are standard on the NonStop™ Kernel and others of which are
optional.
DN. See distinguished name (DN)
DOCTYPE. Document type declaration at the beginning of an XML document that
associates a document type definition with the document.
Document Objects Model (DOM). An API that serves as a bridge between applications and
XML documents, enabling applications to work with XML document structures and
information as program structures rather than as text streams.
Document Type Definition (DTD). A specification of valid syntax for a class of XML
documents. A DTD specifies required elements and attributes, and permissible and
default values of attributes.
document type specification. A general term for a grammar or syntax specification such as
an XML DTD.
Domain Name Server (DNS). A method for naming resources. The basic function of the
DNS is to provide information about network objects by answering queries.
domain. In the Internet, a part of the naming hierarchy. Syntactically, a domain name consists
of a sequence of names (labels) separated by periods (dots).
element. The basic unit of information in an XML document. An element has a name and can
have content and attributes.
Ethernet. A popular local area network (LAN) technology invented at the Xerox Corporation
Palo Alto Research Center. An Ethernet itself is a passive coaxial cable; the
interconnections all contain active components. Ethernet is a best-effort delivery system
that uses CSMA/CD technology. Xerox Corporation, Digital Equipment Corporation,
and Intel Corporation developed and published the standard for 10 Mbps Ethernet.
File Transfer Protocol (FTP). The Internet standard, high-level protocol for transferring
files from one machine to another. Usually implemented as application-level programs,
FTP uses the TELNET and Transmission Control Protocol (TCP) protocols. The server
side requires a web client to supply a login identifier and password before it will honor
requests.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 2
Glossary
FTP
FTP. See File Transfer Protocol (FTP).
gateway. A special-purpose, dedicated computer that attaches to two or more networks and
routes packets from one to the other. In particular, an Internet gateway routes Internet
Protocol (IP) datagrams among the networks to which it is connected. Gateways route
packets to other gateways until they can be delivered to the final destination directly
across one physical network. The term is loosely applied to any machine that transfers
information from one network to another, as in mail gateway.
Guardian. The original application program interface (API) to the NonStop™ Kernel
operating system.
hierarchical routing. Routing based on a hierarchical addressing scheme. Most Internet
routing is based on a two-level hierarchy in which an Internet address is divided into a
network portion and a host portion. Gateways use only the network portion until the
datagram reaches a gateway that can deliver it directly. Subnetting introduces additional
levels of hierarchical routing
HyperText Markup Language (HTML). The tagging language used to format HyperText
documents on the World Wide Web. It is built on top of Standard Generalized Markup
Language (SGML).
HyperText Transport Protocol (HTTP). The communications protocol used for
transmitting data between servers and web clients (browsers) on the World Wide Web.
IEEE. See Institute of Electrical and Electronics Engineers (IEEE).
Institute of Electrical and Electronics Engineers (IEEE). An international industry group
that develops standards for many areas of electrical engineering and computers.
Internet address. The 32-bit address assigned to hosts that want to participate in the Internet
using TCP/IP. Internet addresses are the abstraction of physical hardware addresses, just
as the Internet is an abstraction of physical networks. Actually assigned to the
interconnection of a host to a physical network, an Internet address consists of a network
portion and a host portion. The partition makes routing efficient.
Internet Protocol (IP). The Internet standard protocol that defines the Internet datagram as
the unit of information passed across the Internet and that provides the basis for the
Internet connectionless, best-effort packet delivery service.
Internet. Physically, a collection of packet-switching networks interconnected by gateways,
along with protocols that allow them to function logically as a single, large, virtual
network. When written in uppercase, INTERNET refers specifically to the DARPA
Internet and the TCP/IP protocols it uses.
interoperability. The ability of software and hardware on multiple machines from multiple
vendors to communicate meaningfully.
IP.
See Internet Protocol (IP).
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 3
Glossary
Joint Photographic Expert Group (JPEG)
Joint Photographic Expert Group (JPEG). An image format used to transmit graphics on
the World Wide Web (WWW).
JPEG. See Joint Photographic Expert Group (JPEG).
key database file. The file in which you maintain keys you generated using the keyadmin
command with either the -mkpair or -keydb argument. These are the keys you use to
generate certificates for software encryption. Compare WID keyfile.
Key Exchange Key (KEK). An encryption key used to encrypt other keys.
local area network (LAN). Any physical network technology that operates at high speed
(usually from tens of megabits per second to several gigabits per second) over short
distances (up to a few thousand meters).
Mosaic. See browser.
namespace. A context for resolving names, used to prevent ambiguity (or “collisions”) where
a name is can have different meanings in different situations. To qualify a name by
identifying the namespace expresses the idea that the name is used as defined in that
namespace.
Netscape. See browser.
nowait mode. In Guardian file-system operations and in some APS operations, the mode in
which the called procedure initiates an input/output (I/O) operation but does not wait for
it to complete before returning control to the caller. In order to make the called
procedure wait for the completion of the operation, the application calls a separate
procedure. Compare wait mode.
Open System Services (OSS). An open system environment available for interactive or
programmatic use with the NonStop Kernel operating system. Processes that run in the
OSS environment use the OSS application program interface (API); interactive users of
the OSS environment use the OSS shell for their command interpreter.
OSS applications. POSIX compliant applications.
OSS. See Open System Services (OSS).
packet. The unit of data sent across a packet-switching network. While some Internet
literature uses it to refer specifically to data sent across a physical network, other
literature views the Internet as a packet-switching network and describes IP datagrams
as packets.
PATHMON. The central controlling process for a NonStop TS/MP application.
Pathway. The former name of NonStop TS/MP, a product providing transaction services for
persistent, scalable, transaction-processing applications.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 4
Glossary
physical layer
physical layer. Layer 1 in the OSI Reference Model. This layer establishes the actual
physical connection between the network and the computer equipment. Protocols at the
Physical Layer include rules for the transmission of bits across the physical medium and
rules for connectors and wiring.
process. A running entity that is managed by the operating system, as opposed to a program,
which is a collection of code and data. When a program is taken from a file on a disk
and run in a processor, the running entity is called a process.
protocol. A formal description of the message formats and rules two or more machines must
follow to exchange messages. Protocols can describe low-level details of machine-tomachine interfaces (for example, the order in which the bits from a byte are sent across a
wire) or high-level exchanges between application programs (for example, the way in
which two programs transfer a file across the Internet). Most protocols include both
intuitive descriptions of the expected interactions and more formal specifications using
finite state-machine models.
QIO subsystem. A product that provides buffers and control blocks for protocol processes,
including TCP/IP, TLAM, and NonStop IPX/SPX running on the same processor.
Request for Comments (RFC). The name of a series of notes that contain surveys,
measurements, ideas, techniques, and observations, along with proposed and accepted
Internet protocol standards. RFCs are edited but not referenced. They are available
across the Internet.
RFC. See Request for Comments (RFC)
Secure Sockets Layer (SSL). A protocol for private communication on the World Wide Web
and authentication of a web server by a web client.
server. A process or set of processes that satisfy requests from web clients in a client-server
environment.
server class. A grouping of duplicate copies of a single server program, all of which execute
the same object program.
server process. A process that implements requests for an application and returns replies to
the requester.
server programs. In NonStop TS/MP, programs that handle the data manipulation and data
output activities for online transaction processing applications. Server programs are
designed to receive request messages from requester programs; perform the desired
operations, such as database inquiries or updates, security verifications, numerical
calculations, or data routing to other computer systems; and return reply messages to
requester programs.
Simple Mail Transfer Protocol (SMTP). The Internet standard protocol for transferring
e-mail messages from one machine to another. SMTP specifies how two mail systems
interact, and specifies the format of control messages the two mail systems exchange to
transfer mail.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 5
Glossary
Simple Object Access Protocol (SOAP)
Simple Object Access Protocol (SOAP). An XML-based protocol used for exchange of
information in a distributed application environment. SOAP defines a basic set of
message components, a way to describe data types, and a way to represent requests and
responses.
SSL. See Secure Sockets Layer (SSL).
subnet address. An extension of the Internet addressing scheme that allows a site to use a
single Internet address for multiple physical networks. Outside of the site using subnet
addressing, routing continues as usual by dividing the destination address into an
Internet portion and local portion. Gateways and hosts inside a site using subnet
addressing interpret the local portion of the address by dividing it into a physical
network portion and host portion.
subsystem. The software and/or hardware facilities that provide users with access to a set of
communications services.
Transmission Control Protocol (TCP). The Internet standard transport-level protocol that
provides the reliable, full-duplex stream service on which many application protocols
depend. TCP allows a process on one machine to send a stream of data to a process on
another. It is connection-oriented, in the sense that before transmitting data participants
must establish a connection. Software implementing TCP usually resides on the
operating system and uses the Internet Protocol (IP) to transmit information across the
Internet. It is possible to terminate (shut down) one direction of flow across a TCP
connection, leaving a one-way (simplex) connection. The Internet protocol suite is often
referred to as TCP/IP because TCP is one of the two most fundamental protocols.
TELNET. The Internet standard protocol for remote terminal connection service. TELNET
allows a user at one site to interact with remote timesharing systems at another site just
as if the user’s terminal is connected directly to the remote machine. That is, the user
invokes a TELNET application program that connects to a remote machine, prompts for
a login ID and password, and then passes keystrokes from the user’s terminal to the
remote machine and displays output from the remote machine on the user’s terminal.
Unicode. The 16-bit character encoding used by Java for the char and java.lang.String data
types.
URL. Uniform Resource Locator.
wait mode. In the NonStop Kernel operating system, the mode in which the called procedure
waits for the completion of an input/output (I/O) operation before returning a condition
code to the caller. Compare nowait mode.
Web Container. a Java runtime environment that manages the lifecycle of servlets and JSP.
Web clients. Programs that execute on IBM-compatible PC, Apple Macintosh, or Unix
platforms, among others. They provide a graphic user interface (GUI) for access to
documents and programs on the Web. A web browser is the most familiar example of a
web client.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 6
Glossary
Web server
Web server. Web servers are programs that execute on a variety of server platforms. These
include IBM-compatible servers, Apple Macintosh servers, Unix servers, and a large
number of proprietary hosts. Web server functions can be divided into two parts. A file
server part performs normal file server functions such as file transfer and buffering. A
message switching facility allows messages from web clients to be forwarded to
application programs.
WID keyfile. The file in which you maintain keys you generated using the keyadmin
command with the -websafegen argument. These are the keys you use to generate
certificates for hardware encryption. Compare key database file.
World Wide Web (WWW) protocols. The WWW protocols were first defined by the CERN
project in Switzerland and were later extended by a number of groups, most notably by
the National Center for SuperComputing Applications (NCSA) at the University of
Illinois. These WWW protocols were originally developed to improve communications
over the Internet by providing the ability to access and display web-client
hardware-independent documents that not only contained ASCII text but that also
contained pictures, graphics, and voice and video elements. In addition to accessing
documents, the WWW protocols can also be used to provide document searching
facilities and also interaction with user-written or vendor-provided servers.
WWW. See World Wide Web (WWW) protocols.
XML. Extensible Markup Language, a standard for tagging data in an HTML document so as
to provide semantic information about content elements.
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 7
Glossary
XML
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Glossary- 8
Index
A
accessCheck method F-5
accessing a web site from a page F-2
active content 3-2
AddCGI command 2-11
Administration Server 2-8
appearance accessories C-3
appendChild method 5-11
appendData method 5-64
architecture, ATP 1-3
array, printing contents of 6-4
ATP
acronym expanded 1-1
architecture 1-3
components 1-4
environment variables 2-12
home page 2-14, F-1
HTML parser 1-4
installing 2-1
JavaScript interpreter 1-4
NonStop TS/MP interface 1-4, 3-8
page processing 3-2
Pathway interface 1-4, 3-8
running 2-14
sockets interface 1-4, 3-15
SQL interface 1-4, 3-4
TCP/IP interface 1-4, 3-15
tools overview 1-5
TUXEDO interface 1-4, 3-10
atp
file extension 1-3, 3-1
server class 1-3, A-2
defining 2-9
ATPException object 4-14
atp-tuxedo.config file 2-11
atp.blob object, defined 4-34
atp.buffer object
defined 4-34
in Pathway script 3-9
atp.config file 2-8
atp.dictionary object
defined 4-25
in Pathway script 3-9
performance issues for 6-1
usage considerations 4-26
atp.escape function 4-51
atp.execute 4-50
atp.field constructors C-3
atp.field object
data types 4-30
defined 4-27
dview creation of 4-26, B-1
atp.fml_buffer object
defined 4-43
in TUXEDO script 3-14
atp.fml_field object, defined 4-40
atp.fml_table object
in TUXEDO script 3-13
performance issues 6-1
usage considerations 4-42
atp.formatMoney function, defined 4-51
atp.freeMemory function
defined 4-51
managing loops 6-2
atp.print function
defined 4-50
displaying variables with 6-4
minimizing use of 6-2
performance issues for 6-2
atp.println function
defined 4-50
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 1
B
Index
atp.quit function
defined 4-51
setting breakpoints with 6-5
atp.request object
defined 4-32
printing variables for debugging 6-4
atp.socket object
defined 4-47
in socket script 3-18
atp.SQL object
defined 4-16
in SQL script 3-7
usage considerations 4-20
used by query tool and catalog
explorer A-1
atp.sqlvar object
defined 4-23
used by query tool and catalog
explorer A-1
atp.SQL_object parameter, defined 4-23
atp.transaction object
defined 4-39
displaying for debugging 6-4
in Pathway script 3-9
in SQL script 3-7
in TUXEDO script 3-14
ATP_COMPILE environment variable 2-13
ATP_COMPILED_PAGE_CACHE_SIZE
environment variable 2-12
ATP_DISABLE_BACKQUOTE 4-52
ATP_PAGE_CACHE_SIGNAL
environment variable 2-13
ATP_PAGE_CACHE_SIZE environment
variable 2-12, C-4
ATP_RESTART_PAGE environment
variable 2-12
ATP_SCRIPT_RUNTIME_SIZE
environment variable 2-13
ATP_SCRIPT_STACKSIZE environment
variable 2-13
atp_sql_query filename extension A-2
ATP_TUXEDO_VERSION environment
variable 2-14
attributes property 5-3
authoring tool 1-1
B
base
parameter 4-40
property 4-40
specification 4-40
binary data, object to contain 4-34
bit_length
parameter 4-28
property 4-29
bit_offset
parameter 4-28
property 4-29
blob object
defined 4-34
used for file upload F-2
bookmarking
message layouts C-4
queries A-4
braces in if statements 6-3
breakpoints 6-5
browser
requirements for catalog explorer A-1
version checking F-2
buffer_size parameter 4-43
C
C functions, when desirable 6-2
cache
dumping the 6-5
field table 2-14
page 2-12
performance benefits of 6-1
pseudo-code 2-13
SQL statement 2-13
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 2
D
Index
cache (continued)
usage considerations C-4
catalog
viewing contents of A-1
Catalog Explorer
features A-3
installing A-1
overview 1-5
running A-3
CGI 1-3
character_set_id property 4-24
childNodes property 5-4
classes, declaring and using F-2
clear HTML 3-3, 4-50
client name D-1
client-side JavaScript
distinguishing from server-side 6-3
example F-2
cloneNode method 5-12
close method
atp.SQL object 4-19
socket object 4-49
closing
socket 4-49
tag, printing to force display of data 6-4
COBOL C-4
coding guidelines for JavaScript 6-3
column or variable_index parameter 4-23
column_name property 4-16
column_value array
defined 4-16
usage example F-4
commas in print statements 6-2
commit method 4-39
committing changes explicitly 6-5
Common Gateway Interface (CGI) 1-3
concatenating strings 6-2
configuring ATP 2-8
connection, object to represent 4-47
constructor, definition of 3-7
createAttributes method 5-20
createCDATASection method 5-21
createComment method 5-22
createDocumentFragment method 5-23
createElement method 5-23
createEntityReference method 5-24
createNode method 5-25
createProcessingInstruction method 5-26
createTextNodes method 5-27
cursor, updateable 4-21
cursor_name property 4-17
customizing, configuration of ATP 2-8
D
Data Definition Language (DDL) 1-4, 3-9,
4-25
Data Management Language (DML) 4-21
data property 5-61
data types
atp.field object 4-30
printing to debug 6-4
data validation 4-19
data_length property 4-35
data_type_code property 4-24
date and time representation in SQL 4-22
date_time_interval_fraction_precision
property 4-24
date_time_interval_leading_precision
property 4-24
date_time_interval_range property 4-24
DDL Dictionary Viewer (dview) 1-5, 3-9,
4-26, 6-1, B-1
DDL dictionary, MapDefine for 2-10
DDL (Data Definition Language) 1-4, 2-10,
3-9, 4-25
debugging
applications 6-1
general guidelines for 6-3
SQL 6-5
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 3
E
Index
debugging (continued)
table displays 6-3
watch feature 6-4, F-2
decimals
parameter 4-28
property 4-29
declaring procedures and functions 6-3
delete operator 6-2
deleteData method 5-65
dictddf file 4-25, B-2, C-2
dictionary
browsing 1-5
choosing a B-2, C-2
object 4-25
directory
examples F-1
DML 4-21
Do NonStop TUXEDO tpcall D-3
doAddVariable method F-5
docType property 5-18
document
has no data 6-6
source, displaying 6-3
Document Object Model (DOM) 5-1
Document type definition (DTD) file 5-2
documentElement property 5-18
doDump method 6-4
DOMDocument object 5-16
doSocketError method F-5
doSQLClose method F-4
doSQLColumnValue method F-4
doSQLError method F-4
doSQLGetSQLcode method F-4
doSQLNext method F-4
doSQLPrintColumnValue method F-4
doTMFcommit method F-4
doTMFrollback method F-4
doURLClose method F-5
doURLOpen method F-5
doURLPrint method F-5
doURLPrintHeaders method F-5
doURLRead method F-5
DO_SQL_SELECT_ONLY environment
variable A-3
dumping cache 6-5
dumpSQL method 6-5
dview B-1
and atp.dcitionary object 3-9
installing B-1
limiting use of dictionary 6-1
overview 1-5
running B-1
dynamic dictionary access B-3
E
element
parameter 4-25
property 4-26
element.DEF property 4-26
entering a query A-4
entities property 5-56
Env command 2-9
environment variables
ATP_COMPILE 2-13
ATP_COMPILED_PAGE_CACHE_SIZ
E 2-12
ATP_PAGE_CACHE_SIGNAL 2-13
ATP_PAGE_CACHE_SIZE 2-12, C-4
ATP_SCRIPT_RUNTIME_SIZE 2-13
ATP_SCRIPT_STACKSIZE 2-13
ATP_TUXEDO_VERSION 2-14
DO_SQL_SELECT_ONLY A-3
echoing F-2
Env subcommands of the Server
directive 2-9
iterating through 4-32
Region directive 2-11
represented in atp.request object 4-32
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 4
F
Index
environment variables (continued)
SQL_STATEMENT_CACHE_SIZE 213
TANDEM_PATHMON_NAME 2-10
TUXEDO 4-44
TUXEDO_FTBL_CACHE_SIZE 2-14
error
handling 6-4
log, WebServer 6-3
property
atp.buffer object 4-35
atp.fml_buffer object 4-44
atp.transaction object 4-39, 6-5
socket object 4-48
errorCode property 5-31
error_detail property 4-35
error_text property
atp.fml_buffer object 4-44
socket object 4-48
eval operator, minimizing use of 6-1
event log 6-3
examples
directory F-1
index
by object and function name F-4
by programming task F-2
NonStop TS/MP 3-8
Pathway 3-8
TCP/IP sockets 3-15
TUXEDO 3-10
Excel A-4
execute method
for atp.SQL object 4-18
use in debugging 6-5
explorer directory A-1
extension
mapping to server class 2-9
use to run tools in separate PATHMON
environment A-2
.atp 1-3, 3-1
F
field
object constructors created by
dview B-2
property 4-42
table 1-4, 4-40
cache 2-14
paths to find 4-41
types in TUXEDO 4-40
fields property
atp.field object 4-29
atp.fml_table object 4-41
field_id
parameter 4-41
property 4-41
field_name parameter 4-41
field_table parameter 4-41
file upload 4-33, 4-37, F-2
Filemap directive 2-9
filesystem_error property 4-17
firstChild property 5-4
FML 1-4, 4-40, 4-43, D-2
table 4-40, F-3
FML32 4-43
fml_type
parameter 4-43
property 4-44
forms
dynamic creation
from DDL dictionary F-2
from SQL catalog F-2
generator 1-5, C-1
installing the C-1
performance issues C-2
running the C-1
forms-based application F-2
frames F-2
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 5
G
Index
Fstrerror 4-44
functions
atp.escape 4-51
atp.formatMoney 4-51
atp.freeMemory 4-51, 6-2
atp.print 4-50
displaying variables with 6-4
minimizing use of 6-2
performance issues for 6-2
atp.println 4-50
atp.quit 4-51, 6-5
general-purpose F-4
global 4-50
printing definitions of 6-4
special character conversion 4-51
unescape 4-51
G
generating
script from a script F-2
getAttribute method 5-49
getAttributeNode method 5-49
getBinary method 4-38
getData method 3-14
atp.buffer object 4-37
atp.fml_buffer object 4-46
getElementsByTagName method 5-28, 5-50
getMap method 4-47
getNamedItem method 5-38
getOccurs method 4-46
getQualifiedItem method 5-39
global functions 4-50
H
hasChildNodes method 5-13
hasFeature method 5-59
header, using meta tag to change 3-2
heap size 2-13, 6-2
home page 2-14, F-1
HTML
forms generator 1-5, C-1
generation from SQL database F-2
in the clear 3-3, 4-50
parser 1-4
tags 1-4, 3-1
within server-side script 3-3
HTTP
class library 4-47
data communications 1-2
header 3-2
request 1-4
httpd.config file 2-8, A-2
I
if statements, braces in 6-3
Imbedded definitions C-3
implementation property 5-18
include file
defined 1-4
pros and cons 3-12
syntax conventions 3-2
index, column or variable 4-23
input output flag 4-23
insertBefore method 5-13
insertData method 5-65
installing
ATP 2-1
Catalog Explorer and Query Tool A-1
dview B-1
Forms Generator C-1
jud D-1
Internet Explorer 1-2, C-3
interpreter, JavaScript 1-4
IP address 4-48
iqy file A-4
isDigit method F-5
isMoney method F-6
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 6
J
Index
isPositiveInteger method F-6
item method 5-34, 5-38
iTP Secure Webserver, required
software 2-1
J
JavaScript
client-side F-2
coding guidelines 6-3
environment 1-1
interpreter 1-4
objects 1-4
server-side F-2
Utility Driver (jud) 1-5, D-1
JavaScript Utility Driver (jud) 1-5
Javascript_expression parameter 4-50
jud
function of D-1
installing D-1
overview 1-5
running D-1
K
Korn shell 6-6
L
lastChild property 5-5
length
parameter 4-27
property
atp.field object 4-29
atp.sqlvar object 4-24
length property 5-34, 5-37, 5-64
level
parameter 4-27
property 4-28
line property 5-32
linepos property 5-32
links to server class 2-10
ln command 4-25, B-2, C-2
load method 5-29
loadXML method 5-29
local_IP_address parameter 4-48
local_port parameter 4-48
loopback server class 4-36
loops around constructors 6-2
M
map class define 4-20, B-2, C-2
MapDefine command 2-10, 4-20, B-2, C-2
Maxlinks parameter 2-10
Maxservers parameter 2-10
memory management 4-51, 6-2
message
buffer for Pathway servers 4-34
fields in 4-27
layout
choosing a B-2
definitions in DDL file 4-25, B-1
details B-2
iterating through layouts F-3
names, specifying 6-1
meta tag
saved by ATP 3-2
script not permitted in 3-2
methods
accessCheck F-5
appendChild 5-11
appendData 5-64
cloneNode 5-12
close 4-19, 4-49
commit 4-39
createAttributes 5-20
createCDATASection 5-21
createComment 5-22
createDocumentFragment 5-23
createElement 5-23
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 7
M
Index
methods (continued)
createEntityReference 5-24
createNode 5-25
createProcessingInstruction 5-26
createTextNodes 5-27
deleteData 5-65
doAddVariable F-5
doDump 6-4
doSocketError F-5
doSQLClose F-4
doSQLColumnValue F-4
doSQLError F-4
doSQLGetSQLcode F-4
doSQLNext F-4
doSQLPrintColumnValue F-4
doTMFcommit F-4
doTMFrollback F-4
doURLClose F-5
doURLOpen F-5
doURLPrint F-5
doURLPrintHeaders F-5
doURLRead F-5
dumpSQL 6-5
execute 4-18
getAttribute 5-49
getAttributeNode 5-49
getBinary 4-38
getData
atp.buffer object 4-37
atp.fml_buffer object 4-46
getElementsByTagName 5-28, 5-50
getMap 4-47
getNamedItem 5-38
getOccurs 4-46
getQualifiedItem 5-39
hasChildNodes 5-13
hasFeature 5-59
insertBefore 5-13
insertData 5-65
isDigit F-5
isMoney F-6
isPositiveInteger F-6
item 5-34, 5-38
load 5-29
loadXML 5-29
next 4-19
nextNode 5-35, 5-39
nodeFromID 5-30
normalize 5-51
read 4-49
removeAttribute 5-51
removeAttributeNode 5-52
removeChild 5-14
removeNamedItem 5-41
removeQualifiedItem 5-42
RemoveSpaces F-6
replaceChild 5-15
replaceData 5-66
reset 5-36, 5-40
rollback 4-39
save 5-30
send 4-36
sendMail F-6
sendToServer F-6
setAttribute 5-53
setAttributeNode 5-54
setBinary 4-37
setData
atp.buffer object 4-36
atp.fml_buffer object 4-45
setNamedItem 5-43
setSoKeepAlive 4-49
setSoTimeout 4-49
setTcpNoDelay 4-49
splitText 5-68
SQLBuildExecute F-4
SQLError F-4
SQLQueryCreate F-5
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 8
N
Index
methods (continued)
substringData 5-67
tpcall 4-44
write 4-49
Microsoft
Excel A-4
Internet Explorer 1-2
Mimetype directive 2-9
N
name
parameter
of atp.dictionary constructor 4-25
of atp.field constructor 4-27
of atp.fml_field constructor 4-40
property
atp.dictionary object 4-26
atp.field object 4-28
atp.fml_field object 4-40
atp.fml_table object 4-41
name property 5-45, 5-56
nesting level 4-27/4-29
Netscape Navigator 1-2
next method 4-19
nextNode method 5-35, 5-39
nextSibling property 5-5
nld utility 2-13
nodeFromID method 5-30
nodeName property 5-6
nodeType property 5-7
nodeValue property 5-8
NonStop Kernel 2-1
NonStop SQL
ATP interface 1-4, 3-4
Catalog Explorer A-3
Query Tool A-4
support for 1-1
table, MapDefine for 2-10
NonStop TM/MP 1-4
NonStop TS/MP
ATP interface 1-4, 3-8
automatic forms generation for C-1
sending to server 4-34, F-3
support for 1-1
NonStop TUXEDO
and SQL in one script F-3
ATP interface 1-4, 3-10
environment variables 2-11
support for 1-1
T client connectivity 2-7
WS client connectivity 2-7
non-repeating field 4-29
normalize method 5-51
notations property 5-57
null 4-21
null_permitted property 4-24
numeric_precision property 4-24
numeric_scale property 4-24
Numstatic parameter 2-10
O
objects
ATP 1-4
ATPException 4-14
atp.blob, defined 4-34
atp.buffer, defined 4-34
atp.dictionary
defined 4-25
performance 6-1
usage considerations 4-26
atp.field
data types 4-30
defined 4-27
dview creation of 4-26
atp.fml_buffer, defined 4-43
atp.fml_field, defined 4-40
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index- 9
P
Index
atp.fml_table
performance issues 6-1
usage considerations 4-42
atp.request, defined 4-32
atp.socket, defined 4-47
atp.SQL
defined 4-16
usage considerations 4-20
used by query tool and catalog
explorer A-1
atp.sqlvar
defined 4-23
used by query tool and catalog
explorer A-1
atp.transaction
defined 4-39
used in debugging 6-4
DOMDocument 5-16
NonStop SQL 4-16
NonStop TM/MP (TMF) 4-39
NonStop TS/MP (Pathway) 4-25
NonStop TUXEDO 4-40
SQLQuery F-4/F-5
TCP/IP sockets 4-47
URL F-5
variablesObject F-5
watchlogObject 6-4
XMLDOMAttribute 5-44
XMLDOMCDATASection 5-69
XMLDOMCharacterData 5-62
XMLDOMComment 5-68
XMLDOMDocumentFragment 5-55
XMLDOMDocumentType 5-55
XMLDOMElement 5-48
XMLDOMEntity 5-57
XMLDOMEntityReference 5-58
XMLDOMImplementation 5-59
XMLDOMNamedNodeMap 5-36
XMLDOMNode 5-2
XMLDOMNodeList 5-33
XMLDOMNotation 5-59
XMLDOMParseError 5-31
XMLDOMText 5-68
occurrences of field
in data field 4-29
in FML buffer 4-46
occurs_max
property 4-29
offset
parameter 4-27
property 4-29
Open System Services (OSS)
required software 2-1
running ATP from shell 6-6
running script from shell 3-15
OSS
required software 2-1
running script from shell 3-15
output of script 3-2
ownerDocument property 5-9
ownerElement property 5-46
P
parameters in SQL statements 4-21
parentNode property 5-9
parseError property 5-19
parser, HTML 1-4
passive content 3-2
password D-2
pathmon parameter 4-36
PATHMON, running Query Tool and
Catalog Explorer in separate A-2
Pathsend
and atp.buffer object 4-34
communication 1-4
error number 4-35
example 3-8, F-6
pathsend_error_text property 4-35
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -10
Q
Index
pathsend_timeout property 4-35
Pathway
ATP interface 1-4, 3-8
automatic forms generation for C-1
sending to server F-3
support for 1-1
pathway directory 3-8
PathwayMimeMap directive 2-9, A-2
pathway_tools directory 3-8
performance
considerations for FML tables 4-41
DDL dictionary use 4-26
designing scripts for optimal 6-1
of forms generator C-2
SQL 4-21
PFS space 2-13
plus signs in print statements 6-2
preserveWhiteSpace property 5-19
previousSibling property 5-10
properties
array subscript notation 4-32
atp.blob object 4-34
atp.buffer object 4-35
atp.field object 4-28
atp.fml_buffer object 4-44
atp.fml_table object 4-41
atp.SQL object 4-16
atp.sqlvar object 4-24
atp.transaction object 4-39
attributes 5-3
childNodes 5-4
data 5-61/5-63
docType 5-18
documentElement 5-18
entities 5-56
errorCode 5-31
firstChild 5-4
implementation 5-18
lastChild 5-5
length 5-34, 5-37, 5-64
line 5-32
linepos 5-32
name 5-45, 5-56
nextSibling 5-5
nodeName 5-6
nodeType 5-7
nodeValue 5-8
notations 5-57
ownerDocument 5-9
ownerElement 5-46
parentNode 5-9
parseError 5-19
preserveWhiteSpace 5-19
previousSibling 5-10
printing 6-4
publicId 5-60
reason 5-33
socket object 4-48
specified 5-46
syntax for referring to 6-1
systemId 5-60
tagName 5-48
target 5-61
url 5-33
validateOnParse 5-20
value 5-47
xml 5-11
publicId property 5-60
Q
query
entering a A-4
generating a 1-5, A-1
options for displaying results A-4
submitting a A-4
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -11
R
Index
Query Tool
function of A-1
overview 1-5
running the A-4
R
read method 4-49
reading from a socket 4-49
read-only access A-3
reason property 5-33
record management F-3
records_accessed property 4-18
records_used property 4-18
recursion F-3
Redraw for Field Selection D-2
Redraw Showing All Fields D-2
Redraw Showing Selected Fields D-2
Region directive 2-11
remote_host parameter 4-48
remote_port parameter 4-48
removeAttribute method 5-51
removeAttributeNode method 5-52
removeChild method 5-14
removeNamedItem method 5-41
removeQualifiedItem method 5-42
RemoveSpaces method F-6
replaceChild method 5-15
replaceData method 5-66
reply property
atp.buffer object 4-35
atp.fml_buffer object 4-44
request
object to represent 4-32
specifying in forms generator C-2
TUXEDO D-2
request/response server 1-4
reset method 5-36, 5-40
restarting the WebServer 2-8
return
getBinary results 4-38
getData results 4-37/4-38
return statement 6-3
robust scripts 6-3
rollback method 4-39
row, retrieving first 6-5
row_print_format property 4-17
running
ATP 2-14
Catalog Explorer A-3
Forms Generator C-1
jud D-1
Query Tool A-4
S
save method 5-30
script
generating from script F-2
output location 3-2
structure 3-4
security
considerations for ATP 6-3
considerations for query tool and catalog
explorer A-2
example scripts F-3
SELECT statement
read-only access A-3
SQL usage considerations 4-20
use in debugging 6-5
semicolon to end statement 6-3
send method 4-36
sendMail method F-6
sendmail.atp file 3-17
sendToServer method F-6
send_to_server 3-8/3-9
server class, atp A-2
Server directive 2-9
serverclass_send call 4-35
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -12
S
Index
server-side
include 1-4, 3-2, B-3
JavaScript
distinguishing from client-side 6-3
environment 1-1
example F-2
within HTML 3-3
script structure 3-4
server_class parameter 4-36
service name D-1
sessions not supported 6-3
Set statement 2-9
setAttribute method 5-53
setAttributeNode method 5-54
setBinary method 4-37
setData method
atp.buffer object 4-36
atp.fml_buffer object 4-45
in Pathway script 3-9
in TUXEDO script 3-14
setNamedItem method 5-43
setSoKeepAlive method 4-49
setSoTimeout method 4-49
setTcpNoDelay method 4-49
shell, running ATP from 6-6
signal 2-13
SMTP
error checking 3-15
example F-6
sending a message from a script F-3
support for 1-4
sockets
ATP interface 1-4, 3-15
directory 3-15
support for 1-1
software requirements for ATP 2-1
special character conversion functions 4-51
specified property 5-46
splitText method 5-68
SQL
and TUXEDO in one script F-3
cache size 2-13
Catalog Explorer 1-5, A-1, A-3
cursor F-3
debugging techniques 6-5
error code 3-7
error handling 6-4
null 4-21
Query Tool 1-5, A-1
select F-3
support for 1-1
table, MapDefine for 2-10
update and delete F-3
SQLBuildExecute method F-4
sqlca property 4-17
sqlcode property 4-17, 6-5
SQLDA structure 4-24
SQLError method F-4
SQLQuery object F-4/F-5
SQLQueryCreate method F-5
SQL_STATEMENT_CACHE_SIZE
environment variable 2-13
stack size 2-13
statement
parameter 4-16
property 4-16
statement_type property 4-18
static field object constructors B-3
STATLIN 3-14
status property 4-39
stopping a script 4-51, 6-5
string, concatenation before printing 6-2
string_data parameter 4-34
string_filename parameter 4-34
string_name parameter 4-34
string_type parameter
atp.blob constructor 4-34
atp.buffer constructor 4-34
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -13
T
Index
string_type property 4-35
structure
parameter 4-27
property 4-28
submitting a query A-4
subscripts
notation 6-1
use to access object properties 4-32
subscript_multipliers
parameter 4-28
property 4-29
substringData method 5-67
symbolic link 4-25, B-2, C-2
symlink 4-25, B-2, C-2
systemId property 5-60
T
table
debugging issues 6-3
retrieving first row 6-5
tagName property 5-48
tags
explicit printing to force display 6-4
HTML 1-4, 3-1
TANDEM_PATHMON_NAME 2-10
target property 5-61
tcpip_process parameter 4-48
TCP/IP
ATP interface 1-4, 3-15
connection 4-47
support for 1-1
Telnet 1-4
testing a query A-1
timeout property 4-48
TMF
error handling 6-4
use with TUXEDO D-2
tools, overview 1-5
tpcall method 3-14, 4-44, D-3
TPINIT man page 2-11
tpstrerror 4-44
tpurcode 4-44
tracing web page output 6-6
transaction
boundaries 1-4
protection 4-39
rolled back by default 6-5
status 4-39, 6-4
transid property
defined 4-39
use in debugging 6-4
TUXEDO
configuration file D-2
directory D-1
environment variables 2-11
field types 4-40
objects 4-40
sending message to 4-44
support for 1-1
T client connectivity 2-7
ud implementation in JavaScript D-1
WS client connectivity 2-7
Tuxedo 6.5 Support 2-7, 2-14
tuxedo directory 3-10
TUXEDO_FTBL_CACHE_SIZE
environment variable 2-14
tuxedo_tools directory 3-10
type
parameter
of atp.field constructor 4-27
of atp.fml_field constructor 4-40
property
atp.field object 4-28
atp.fml_field object 4-40
type_text
parameter 4-40
property 4-40
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -14
U
Index
U
X
unescape function 4-51
uploading a file 4-33, 4-37/4-38, F-2
URL object F-5
url property 5-33
Use dictionary at runtime C-3
user name D-2
user_return_code property 4-44
Usysflds D-2
XML for ATP 5-1
xml property 5-11
XML schema 5-2
XMLDOMAttribute object 5-44
XMLDOMCDATASection object 5-69
XMLDOMCharacterData object 5-62
XMLDOMComment object 5-68
XMLDOMDocumentFragment object 5-55
XMLDOMDocumentType object 5-55
XMLDOMElement object 5-48
XMLDOMEntity object 5-57
XMLDOMEntityReference object 5-58
XMLDOMImplementation object 5-59
XMLDOMNamedNodeMap object 5-36
XMLDOMNode object 5-2
XMLDOMNodeList object 5-33
XMLDOMNotation object 5-59
XMLDOMParseError object 5-31
XMLDOMText object 5-68
V
validateOnParse property 5-20
validating application data 4-19
validation, client-side F-2
value property 5-47
variable property 4-33
variables
displaying 6-4
initializing in client-side or server-side
environment 6-3
logging changes in 6-4
property
atp.request object 4-32, 6-4
atp.SQL object 4-17
variablesObject object F-5
view
FML D-2
property 4-44
W
watch class F-2
watchlogObject object 6-4
WebServer, iTP
error log 6-3
required software 2-1
write method 4-49
writing to a socket 4-49
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -15
X
Index
iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002
Index -16