iTP Active Transaction Pages (iTP ATP) Programmer's Guide

Manuals Brands HP Manuals Server HP NonStop G-Series

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

Summary of content (258 pages)

PAGE 1

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.
PAGE 2

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.
PAGE 3

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.
PAGE 4

2. Installing and Running ATP Contents 2.
PAGE 5

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.
PAGE 6

5. XML for ATP Add-On Module (continued) Contents 5.
PAGE 7

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.
PAGE 8

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.
PAGE 9

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.
PAGE 10

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.
PAGE 11

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.
PAGE 12

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.
PAGE 13

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.
PAGE 14

What’s New in This Guide New and Changed Information iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 xii
PAGE 15

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.
PAGE 16

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.
PAGE 17

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.
PAGE 18

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.
PAGE 19

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.
PAGE 20

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.
PAGE 21

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.
PAGE 22

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.
PAGE 23

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 ]...
PAGE 24

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.
PAGE 25

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.
PAGE 26

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.
PAGE 27

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.
PAGE 28

Abbreviations About This Guide XML.
PAGE 29

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).
PAGE 30

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.
PAGE 31

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.
PAGE 32

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.
PAGE 33

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.
PAGE 34

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.
PAGE 35

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.
PAGE 36

Introduction Pathway Data Buffer iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 1 -8
PAGE 37

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.
PAGE 38

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 /atp files.
PAGE 39

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.
PAGE 40

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/ where is the vproc of the package (for example, T0345V21_31JAN02_BASE_V210_5) 2. Run the .
PAGE 41

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// ...
PAGE 42

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 ...
PAGE 43

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.
PAGE 44

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.
PAGE 45

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.
PAGE 46

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.
PAGE 47

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.
PAGE 48

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.
PAGE 49

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.
PAGE 50

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.
PAGE 51

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.
PAGE 52

Installing and Running ATP Uninstall Cleanup Steps iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 2- 16
PAGE 53

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.
PAGE 54

ATP Web Page and Script Structure Web Page Processing Server-side includes also follow Netscape conventions. For example: * Script is not permitted within a meta tag (such as ) 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.
PAGE 55

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.
PAGE 56

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.
PAGE 57

ATP Web Page and Script Structure Using NonStop SQL from JavaScript Example 3-2. NonStop SQL Definitions and Includes
PAGE 58

ATP Web Page and Script Structure Using NonStop SQL from JavaScript Example 3-3. NonStop SQL Includes and Server-Side JavaScript createDocumentFragment Creates an empty XMLDOMDocumentFragment Object node.
PAGE 146

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.
PAGE 147

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.
PAGE 148

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.
PAGE 149

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.
PAGE 150

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.
PAGE 151

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.
PAGE 152

XML for ATP Add-On Module Methods Example var doc = new XML.DOMDocument; doc.loadXML("0001Joe "); println(doc.xml); Output 0001Joe 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.
PAGE 153

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.
PAGE 154

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.
PAGE 155

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.
PAGE 156

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.
PAGE 157

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.
PAGE 158

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).
PAGE 159

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.
PAGE 160

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.
PAGE 161

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.
PAGE 162

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.
PAGE 163

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().
PAGE 164

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.
PAGE 165

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.
PAGE 166

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; iPAGE 167
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.
PAGE 168

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.
PAGE 169

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.
PAGE 170

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.
PAGE 171

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.
PAGE 172

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").
PAGE 173

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.
PAGE 174

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.
PAGE 175

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.
PAGE 176

XML for ATP Add-On Module Methods Output Jenny Mabry 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.
PAGE 177

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.
PAGE 178

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.
PAGE 179

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.
PAGE 180

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.
PAGE 181

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.
PAGE 182

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.
PAGE 183

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.
PAGE 184

XMLDOMCharacterData Object XML for ATP Add-On Module Output 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.
PAGE 185

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.
PAGE 186

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.
PAGE 187

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.
PAGE 188

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.
PAGE 189

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.
PAGE 190

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 ‘’.
PAGE 191

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.
PAGE 192

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.
PAGE 193

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.
PAGE 194

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.
PAGE 195

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)
PAGE 196

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.
PAGE 197

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.
PAGE 198

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.
PAGE 199

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.
PAGE 200

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.
PAGE 201

Designing and Debugging ATP Applications Setting Breakpoints Example 6-3. Function to Print Values of Request Variables function doDump() { for (i=0; i'); } 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.
PAGE 202

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.
PAGE 203

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.
PAGE 204

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.
PAGE 205

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 /*.
PAGE 206

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.
PAGE 207

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.
PAGE 208

SQL Query Tool and Catalog Explorer Usage Techniques iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 A- 6
PAGE 209

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.
PAGE 210

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.
PAGE 211

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.
PAGE 212

DDL Dictionary Viewer (dview) Using the Field Object Constructors iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 B- 4
PAGE 213

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.
PAGE 214

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.
PAGE 215

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).
PAGE 216

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.
PAGE 217

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.
PAGE 218

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.
PAGE 219

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.
PAGE 220

JavaScript Utility Driver (jud) Displaying the Reply Message iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 D- 4
PAGE 221

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.
PAGE 222

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.
PAGE 223

F ATP Examples The /usr/tandem/atp//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.
PAGE 224

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.
PAGE 225

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.
PAGE 226

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.
PAGE 227

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.
PAGE 228

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.
PAGE 229

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.
PAGE 230

ATP Examples Objects Defined in the XML for ATP SOAP Library iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 F-8
PAGE 231

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.
PAGE 232

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).
PAGE 233

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.
PAGE 234

Migration Considerations Tuxedo 6.5 Support Example G-1. Checking the Validity of Your Data Conversions 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(); The value of 0 is inserted into the FLOAT_BASIC field.
PAGE 235

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.
PAGE 236

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.
PAGE 237

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.
PAGE 238

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).
PAGE 239

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.
PAGE 240

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.
PAGE 241

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.
PAGE 242

Glossary XML iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 Glossary- 8
PAGE 243

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
PAGE 244

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.
PAGE 245

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.
PAGE 246

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 docume
PAGE 247

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.
PAGE 248

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.
PAGE 249

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.
PAGE 250

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.
PAGE 251

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.
PAGE 252

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.
PAGE 253

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 notati
PAGE 254

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 removeN
PAGE 255

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.
PAGE 256

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 parame
PAGE 257

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
PAGE 258

X Index iTP Active Transaction Pages (iTP ATP) Programmer’s Guide —522292-002 Index -16