unisys ClearPath Web Enablement Solutions Web Transaction Server for ClearPath OS 2200 Programming Guide imagine it. done. ClearPath OS 2200 IPv6 1.

unisys imagine it. done. ClearPath Web Enablement Solutions Web Transaction Server for ClearPath OS 2200 Programming Guide ClearPath OS 2200 IPv6 1.0 December 2008 7850 4248 010

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses. Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries. All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.

ClearPath Web Enablement Solutions Web Transaction Server for ClearPath OS 2200 Programming Guide ClearPath OS 2200 IPv6 1.0 ClearPath Web Enablement Solutions Web Transaction Server for ClearPath OS 2200 Programming Guide ClearPath OS 2200 IPv6 1.0 7850 4248 010 7850 4248 010 Bend here, peel upwards and apply to spine.

.

Contents Section 1. Getting Started 1.1. Documentation Updates... 1 1 1.2. Topic Overview... 1 5 1.3. Requirements... 1 5 1.4. User Interfaces... 1 5 1.4.1. End-User Interface... 1 6 1.4.2. Administrator Interface... 1 6 1.5. Capabilities... 1 8 1.6. URL... 1 10 1.6.1. URL Format... 1 11 1.6.2. Using Relative URLs... 1 12 1.7. SSL Security... 1 13 1.7.1. Sequence of Actions in a Simple Secure Transaction... 1 14 1.7.2. SSL Protocol... 1 15 1.7.3. Servers and SSL Security... 1 15 1.7.4. SSL Security Encryption Suites... 1 15 1.8. Support, Restrictions, and Operational Considerations... 1 16 1.8.1. Functions Not Supported... 1 16 1.8.2. Server Support... 1 16 1.8.3. Restriction... 1 16 1.8.4. Exec Dependencies... 1 17 1.9. General Sequence of Events... 1 18 Section 2. Static Pages 2.1. Topic Overview... 2 1 2.2. Using Open File Names... 2 2 2.3. Reading Static Pages (Pages Function)... 2 3 2.4. Storing (Updating) Static Pages... 2 6 2.4.1. Updating an Offline File... 2 10 2.4.2. Updating an Online File... 2 10 2.4.3. FTP Transfer Without the Administration Program... 2 11 Section 3. Calling Transactions (txn Function) Section 4. TIP/HVTIP Transactions 4.1. Web Enabler for Display Processing System... 4 1 4.2. Topic Overview... 4 3 7850 4248 010 iii

Contents 4.3. Processing Dynamic Pages with TIP/HVTIP Transactions (txn Function)... 4 5 4.4. Input to a Transaction... 4 6 4.5. Output from a Transaction... 4 7 4.6. Transaction Duration... 4 10 4.7. Error Processing... 4 11 4.8. Troubleshooting TIP/HVTIP Transactions Problems... 4 12 Section 5. Secure Sessions 5.1. Topic Overview... 5 1 5.2. Key Concepts... 5 2 5.2.1. Secure Sessions... 5 2 5.2.2. Terminating Secure Sessions... 5 4 5.3. Administration... 5 5 5.4. Log-On Processing... 5 5 5.5. Security Default Definition... 5 9 5.6. Log-Off Processing... 5 13 5.7. Web Enabler for Display Processing System Considerations... 5 14 5.8. Single Server and Non-SSL Support... 5 14 5.9. Systems That Do Not Support TIP Session Control... 5 16 5.10. Secure Sessions Log Entries... 5 16 Section 6. Kerberos/NTLM Sessions 6.1. Topic Overview... 6 1 6.2. Key Concepts... 6 2 6.2.1. Kerberos/NTLM Sessions... 6 3 6.2.2. Terminating Kerberos/NTLM Sessions... 6 4 6.3. Administration... 6 4 6.4. Log-On Processing... 6 5 6.5. Log-Off Processing... 6 6 6.6. Mixed Kerberos/NTLM Sessions and Secure Sessions... 6 6 6.7. Web Enabler for Display Processing System Considerations... 6 7 6.8. Systems That Do Not Support TIP Session Control... 6 7 6.9. Kerberos/NTLM Sessions Log Entries... 6 7 Section 7. CGI Routines 7.1. CGI General Information... 7 1 7.2. Topic Overview... 7 5 7.3. CGI Advisory... 7 6 7.4. COBOL Interface CGI Routines... 7 6 7.4.1. CGI$INIT... 7 7 7.4.2. CGI$OPEN... 7 8 7.4.3. CGI$GETVAR... 7 9 7.4.4. CGI$GETFIELDVALUE... 7 10 7.4.5. CGI$SENDBUFR... 7 12 iv 7850 4248 010

Contents 7.4.6. CGI$TERM... 7 13 7.4.7. CGI$COMMIT... 7 14 7.4.8. CGI$ROLLBACK... 7 15 7.4.9. CGI$GETAUXSTATUS... 7 16 7.4.10. CGI$GETPID... 7 17 7.4.11. CGI$PASSOFF... 7 18 7.4.12. CGI$GETCONTENT... 7 19 7.4.13. CGI$SETNODE... 7 20 7.4.14. CGI$SETDEBUG... 7 21 7.4.15. CGI$CCS2CCS... 7 22 7.4.16. CGI$LOGOFF... 7 23 7.5. Input from an HTML Document... 7 24 7.5.1. CPYGEN Processor... 7 24 7.5.2. CGI$GETFORM... 7 28 7.6. Output to an HTML Document... 7 30 7.6.1. Substitution List... 7 30 7.6.2. Include Directive (#include)... 7 36 7.6.3. CGI$SENDHTML... 7 38 7.7. C Interface CGI Routines... 7 39 7.7.1. CGIInit... 7 39 7.7.2. CGIRead... 7 40 7.7.3. CGIGetVar... 7 41 7.7.4. CGIGetFieldValue... 7 42 7.7.5. CGIGetOutBufr... 7 43 7.7.6. CGISend... 7 43 7.7.7. CGITerm... 7 45 7.7.8. CGICommit... 7 46 7.7.9. CGIRollback... 7 47 7.7.10. CGIGetAuxStatus... 7 48 7.7.11. CGIGetPID... 7 48 7.7.12. CGIGetBodyPtr... 7 49 7.7.13. CGILogoff... 7 50 7.8. Environmental Variables... 7 50 7.9. Static Linking of CGI Transaction Programs... 7 53 7.10. Collecting ASCII COBOL CGI Transaction Programs... 7 54 7.11. CGI Examples... 7 54 7.11.1. Example 1... 7 54 7.11.2. Example 2... 7 56 Section 8. TransIT Open/OLTP Transactions 8.1. Topic Overview... 8 1 8.2. Processing Dynamic Pages with Open/OLTP Transactions (txn Function)... 8 2 8.3. Setting Up the OLTPTx Gateway Transaction... 8 3 8.4. Mapping Between HTML-Formatted Data and Open/OLTP Formatted-Data... 8 4 8.5. Storing Output from the WebViewC Compiler... 8 7 8.6. Input to a Transaction... 8 7 8.7. Output from a Transaction... 8 8 7850 4248 010 v

Contents Section 9. Web-Enabling Enterprise Application Environment Applications 9.1. Procedure... 9 2 9.2. Security... 9 3 9.3. Prototype... 9 3 9.4. Example Program... 9 4 9.4.1. Source Code... 9 4 9.4.2. Defining the HVTIP Entry Points for the Enterprise Application Environment Subroutine... 9 10 9.4.3. LINK Statements... 9 10 Glossary... 1 Index... 1 vi 7850 4248 010

Figures 1 1. Web Transaction Server and Related Software Components... 1 4 1 2. Software and Hardware Components, Connections, and Relationships... 1 7 1 3. SSL Transaction Sequence... 1 14 4 1. Using the OS 2200 TIP/HVTIP Transactions... 4 4 5 1. Basic Steps for Using Secure Sessions... 5 3 5 2. Secure Session Log-On Window... 5 6 5 3. Security Session Defaults Window... 5 9 6 1. Components of Kerberos/NTLM Authentication... 6 3 7 1. COBOL Common Gateway Interface (CGI)... 7 2 7 2. HTML Preprocessing... 7 3 7850 4248 010 vii

Figures viii 7850 4248 010

Examples 2 1. An Administration Transfer Files Window... 2 7 2 2. A Linkbot Window... 2 8 2 3. Enabling the Access State of the Production File... 2 9 5 1. Example Entries for a Sample Set... 5 10 5 2. Example of a Current Session Set... 5 11 5 3. Example of Available Session Definition Sets... 5 12 7 1. A Log Viewer Results Window... 7 56 7 2. An Error Log Window... 7 57 7 3. Options Window Pages Tab... 7 62 7 4. Options Window Txns Tab... 7 63 7850 4248 010 ix

Examples x 7850 4248 010

Section 1 Getting Started 1.1. Documentation Updates This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) 18650177. To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site: http://www.support.unisys.com/all/ple/18650177 Note: If you are not logged into the Product Support site, you will be asked to do so. The Web Transaction Server software product provides Web-based access to mission-critical transactions. This software provides a modern, Web-compatible interface directly to the Unisys 2200 Series large-scale transaction-processing environment without requiring a front-end gateway system. This reduces the number of software layers used per transaction. Web Transaction Server is available on OS 2200 Series servers and ClearPath IX servers. Web Transaction Server provides fundamental Web processing access specifically for OS 2200 transaction environments and is compatible with existing shrink-wrapped Web browsers. It supports most standard Web server features that help implement complete Web applications, including Static or dynamic Web pages Forms Graphics Java applets You can use information from a Web-page link or input form to initiate Transaction Processing (TIP) and High-Volume Transaction Processing (HVTIP) transactions. Results of the transaction are passed back to the Web browser in standard Web output page form. On 2200 Series servers, Web Transaction Server can initiate Open/OLTP services locally. On ClearPath IX servers, Web Transaction Server can initiate Open/OLTP services in both the OS 2200 operating environment and the Intel operating environment. Both standard Open/OLTP and Heritage Access (HAA) services are supported. Web Transaction Server supports Secure Socket Layer (SSL) 3.0 that provides security while transmitting information between servers and browsers. 7850 4248 010 1 1

Getting Started Web Transaction Server also supports the Web Enabler for Display Processing System mechanism. This enables users (clients) to access existing OS 2200 transactions that use the OS 2200 Display Processing System from a Web browser without changing the Display Processing System transactions. See the Web Enabler for Display Processing System User s Guide for more information. Since Web Transaction Server supports IPv6 protocol, it can handle requests from IPv6 clients. This guide introduces the Web Transaction Server. It describes the software and what can be accomplished with it. It also describes how application programmers use the common gateway interface (CGI) routines included with the software. This guide contains information that was available at the time of publication. Technical changes that were not available at the time of publication are supplied in PLE 17988981. You can obtain a copy of this PLE by accessing the Unisys Support Online (USO) Web page at http://www.service.unisys.com This guide uses the following notation conventions: Item Variable names Function names in text Symbolic constants (keywords, error codes, and flags) Command names and symbolic constants (option letters, file names, directory paths, processor names, and so forth) Description Variable names represent information that you must supply, or that is information that can change. Variable names are to be replaced by actual names. They appear in italic type as follows: COBOL language example: value-buffer output-buffer C language example: CGI_work_area *work_area ws_auxstatus Causes lowercase, parentheses, and possibly underscores in function names. Example: tx_commit(). Causes uppercase and underscores in symbolic constants. Example: TX_COMMITTED. Command names and symbolic constants appear in uppercase as a rule (but they can be entered in either uppercase or lowercase). Example: The @LINK command The xcopy program The INCLUDE file 1 2 7850 4248 010

Getting Started Syntax Syntax represents command names, system variable names, system function names, and so forth. These statements appear in a fixed-character-width format. Syntax can include variable names. Example: ws_status CGIGetVar... error-file-name The when-return value... Omitted code Optional parameters HTML delimiters An ellipsis (... ) indicates data that is not pertinent to the discussion is omitted. The ellipsis can be horizontal or vertical. Example: Key-string1... key-stringn Optional data is enclosed in brackets ([ ]). Example: [,h]. Beginning and ending delimiters in HTML data (< >). Example: <INPUT TYPE=HIDDEN VALUE=viewname>. ClearPath IX and OS 2200 server Web Transaction Server software and other software components provide the gateways for connecting internal and external Web sites to transactions running in the OS 2200 operating environment. This capability enables users at a client workstation running Web browser software to request service from the OS 2200 operating environment. Web pages can be static (data that is preformatted) or dynamic (data that is retrieved and processed by transaction programs). If a request requires reading a static page (document), the data is read and passed back to the Web browser for display. If a request requires the processing of data, the targeted transaction processes the data and generates an output message formatted as an HTML dynamic page. The output message (results data or output data) is transferred back to the Web browser as a standard Web output page. Web Transaction Server and all other Web servers comply with the HyperText Transfer Protocol (HTTP). File transfer protocol (FTP) servers complement Web servers. FTP servers are often used to transfer very large objects. The FTP Services for ClearPath OS 2200 software is an open networking application. The FTP Services for a ClearPath OS 2200 application can transfer files between ClearPath IX and OS 2200 servers and almost any other computing system that runs the TCP/IP environment. TCP/IP governs the transfer of data between a client workstation and ClearPath IX and OS 2200 servers. FTP Services for ClearPath OS 2200 provides higher transfer rates than traditional OS 2200 FTP servers. Web Transaction Server does not require FTP Services for ClearPath OS 2200, but an FTP server must be resident on the OS 2200 system running Web Transaction Server if the Administration program is used to transfer Web data from client workstations to the OS 2200 system running Web Transaction Server. If FTP Services for ClearPath OS 2200 and Web Transaction Server are used at a site to complement each other, the site can be more productive. Transaction requests and associated information transferred between the workstation running the Web browser software and ClearPath IX and OS 2200 servers use HTTP. 7850 4248 010 1 3

Getting Started This is the primary protocol for distributing information on the Web. Web Transaction Server supports the HTTP Specification. To see an example of how to set up a large static Web site with Web Transaction Server, see the documentation section of either of the following Web Transaction Server support Web sites: http://www.support.unisys.com/2200/webts/ http://epas1.rsvl.unisys.com/2200/webts/ Figure 1 1 shows a high-level view of related software components. Figure 1 1. Web Transaction Server and Related Software Components 1 4 7850 4248 010

Getting Started 1.2. Topic Overview This section discusses the following topics: Requirements User interfaces Capabilities Uniform Resource Locator (URL) Secure Sockets Layer (SSL) security Support and operational considerations General sequence of events 1.3. Requirements The information in this guide is meant primarily for applications programmers. Before you can accomplish the tasks described in this guide, you must ensure the following: That you have a functioning ClearPath IX or OS 2200 server with associated software that is loaded, configured, and executing. That the Message Control Bank (MCB) Error Notification Program (ENP) software is loaded and functioning. The ENP software enables the MCB to notify the application system of certain conditions (see the MCB Programming Reference Manual for additional information). That the network communications path between the workstation client and ClearPath IX and OS 2200 servers is functional. That the Web Transaction Server is installed and configured (see the Web Transaction Server Administration Guide for installation and configuration information). 1.4. User Interfaces The user interfaces to ClearPath IX and OS 2200 servers use standard commercially available products. There are two separate user interfaces: End-user (Web browser) interface from a client workstation Administrator interface from an administration workstation Figure 1 2 shows the interconnection and relationship of the client workstation running Web browser software, the administration workstation running the Administration program, CMS 1100 software, Web Transaction Server software, and other software components. The client workstation can be connected directly to the server or it can be connected through a Web service software agent, such as America Online (AOL). 7850 4248 010 1 5

Getting Started 1.4.1. End-User Interface The end-user interface is between Web browser software running on a client workstation and Web Transaction Server software running on ClearPath IX and OS 2200 servers. The end-user interface is made up of several parts: Web browser software, such as Microsoft Internet Explorer or Netscape Navigator, running on a client workstation. This software is used to view documents on the Web and to navigate hyperlinks to other documents. A physical and logical network that connects a client workstation and ClearPath IX or OS 2200 servers. The network must meet the requirements of the TCP/IP standard. Web Transaction Server and other OS 2200 operating environment software supporting the server. The CMS 1100 Programming Reference Manual describes some of the internal software interfaces and provides other information that can be useful. The Web Transaction Server Administration Guide provides specific configuration and administration information. 1.4.2. Administrator Interface The administrator interface is between the Administration program running on an administration workstation and Web Transaction Server software running on ClearPath IX or OS 2200 servers. System administrators use the interface to enable and control configuration, administration, and monitoring activities. These activities are defined in the Web Transaction Server Administration Guide. The administrator interface is comprised of the following: A physical and logical network that must meet the requirements of the TCP/IP standard connecting an administration workstation and the TSAM/Communications Platform software on ClearPath IX or OS 2200 servers. A software interface from the TSAM/Communications Platform software through a socket interface on port 40000 (default) to the Web Transaction Server. Use the Administration program to specify the port. The administration workstation requires Windows 2000 or Windows XP software. Figure 1 2 shows the hardware components, connections, and relationships. 1 6 7850 4248 010

Getting Started Figure 1 2. Software and Hardware Components, Connections, and Relationships 7850 4248 010 1 7

Getting Started 1.5. Capabilities To support Web Transaction Server capabilities, you must follow these guidelines: See the Web Transaction Server Administration Guide for information about setting up a Web site. Store the Web pages in standard OS 2200 program files or in CIFS files. Web Transaction Server supports the following types of processing: Access to static pages in the OS 2200 operating environment This capability enables you to read data stored in static pages on ClearPath IX and OS 2200 servers. Static pages are stored in symbolic (ASCII data) or omnibus (binary data) elements in standard OS 2200 files. The files can contain different types of data, such as Text VBscript Java script Graphic images Video Audio See Section 2.3 for a description of how to read data stored in static pages. Access to dynamic pages with TIP/HVTIP transaction programs This capability enables you to execute TIP and HVTIP transaction programs to access your databases from the Web. The transactions read the input data through the Web Transaction Server and associated CGI routines. Input to and output from the TIP/HVTIP transactions that use the MCB must meet HTTP specifications. See Section 4.3 for a description of how to use TIP/HVTIP transactions to read data stored in dynamic pages. Access to dynamic pages with OS 2200 TransIT Open/OLTP transaction programs This capability enables you to execute Open/OLTP transaction programs locally in the OS 2200 operating environment (including Heritage Application Access [HAA] transaction programs) and remotely in the Intel operating environment to access your databases from the Web. Web Transaction Server includes the OLTPTx software, which serves as a gateway between to Open/OLTP transactions. See Section 7.2 for a description of how to use Open/OLTP transactions to read data stored in dynamic pages. Web Transaction Server also supports Visual Basic scripts, Java scripts, and Java applets. 1 8 7850 4248 010

Getting Started Scripts Scripts are byte streams that are included in HTML pages, as shown below. All the data is contained in the HTML page and there is no need to read files at another location. The Web browser software reads the byte stream from the HTML pages and compiles and interprets it directly. Start of HTML home page byte stream... byte stream End of HTML home page Java applets Java applets are included in HTML pages and reference files at another location in the OS 2200 operating environment. These files contain byte streams and other parameter data. This reference is required because all the data is not included in the HTML page, as shown below. Start of HTML home page... Java applet (points to another location containing a byte stream)... End of HTML home page To support Web Transaction Server capabilities, you must follow these guidelines: See the Web Transaction Server Administration Guide for information about setting up a Web site. Web pages must be stored in standard OS 2200 program files. System administrators must register the program files containing the Web pages, transactions, and program application groups with the Web Transaction Server. 7850 4248 010 1 9

Getting Started 1.6. URL TIP, HVTIP, and Open/OLTP transactions that are to be used with Web Transaction Server must be modified so that their input and output data streams support the server. For these transactions to be enabled, they must be assigned an alias that can be specified in a URL. The alias is a symbolic name defined by the administrator and must be used in place of an OS 2200 transaction code. The alias can be the same as the transaction code or it can be different. Aliases must be defined and registered using the Administration program. Aliases control access to transactions and prohibit access to transactions that are not registered. Aliases can also be used to access static pages, but they are not required. If an alias is used, it represents the entire OS 2200 program file name. Aliases must be defined and registered by the site administrator using the Administration program. Aliases control access to static page files and prohibit access to files that are not registered. The data exchanged between the Web browser and Web Transaction Server must conform to HTTP specifications. The Uniform Resource Locator (URL) is one form of the uniform resource identifier (URI). A URL is basically the physical address of objects that can be retrieved with protocols such as HTTP and FTP that are deployed on the network. A URL is a formatted string that identifies a resource. Web Transaction Server typically receives requests and associated information from a location on an intranet or the Internet. A URL is used by a Web browser to target a server. The format of the URL depends on the scheme used to access a resource (in this case, ClearPath IX and OS 2200 servers). Since, we are using HTTP, the format of the URL must follow the format standards compatible with HTTP. A URL server address must be set up by an administrator as described in the Web Transaction Server Administration Guide. 1 10 7850 4248 010

Getting Started 1.6.1. URL Format A URL has the following syntax (data enclosed in brackets ( [ ] ) is optional): http://host[:port]/resource or, for SSL protected pages and transactions https://host[:port]/resource where: http or https (https instructs the server to switch to a secure mode) host port The URL protocol that is being used (for example, HTTP). The addressing scheme is separated from the rest of the URL by a colon ( : ). URL schemes referring to Internet protocols, like HTTP, generally use a common syntax for the rest of the object name. This part of a URL begins with a double slash ( // ) and ends before the first single slash ( / ). The double slash indicates that the following syntax complies with the common Internet scheme. A legal Internet host domain name or an IP address in dotted-decimal format (for example; 192.61.222.6) indicating the site where the server is running. The IP address can be an IPv4 address specified in the dotted-decimal format or an IPv6 address specified as groups of hexadecimal numbers separated by colons. The IPv6 address must be enclosed in square brackets. For example [1234::5678] The following is the format for an HTTP URL to be used with IPv6 address: http://<[host]>[:port]/resource Example: http://[1234::5678]/txn/choice The port that the server is using to provide access to Web browsers. The first instance of Web Transaction Server uses 80 for the service port number for http: requests and 443 for https: requests. The service port number for each instance must be unique. By default, if ":port" is omitted, port number 80 is assumed. 7850 4248 010 1 11

Getting Started resource Web Transaction Server can access both static pages and gateway programs (OS 2200 transactions). A /txn/ in the resource (path) field indicates that an OS 2200 transaction is to be scheduled. By default, a URL without /txn/ in the resource (path) field indicates that the request is for a static page. Following is an example of a URL: http://www.cpix22.unisys.com/pages/adminhelp/welcome.htm 1.6.2. Using Relative URLs You can use HTML to specify partial URLs for hypertext reference (HREF) anchor tags, images, and so forth. Web browser clients like Microsoft Internet Explorer and Netscape Navigator resolve partial URL references from the containing document base (document currently displayed). A fully specified URL or an absolute URL contains information that can already be known from the context of the base HTML documents retrieved. This includes the scheme, network location, and parts of the URL path. When the base URL is well-defined and well -known, it is useful to embed a URL reference in the HTML document. Then the HTML document that is referenced inherits the context of the HTML document containing the reference and you do not have to redefine the context in each instance of the document. Relative addressing of URLs with partial or relative URL references enables document trees to be partially independent of their location and access scheme. Relative addressing enables you to move entire HTML document trees without changing any of the embedded URL references. The Web browser resolves partial URL references. Web Transaction Server does not control this action. This has the following implications: All hyperlink references in the default Web Transaction Server home page, as defined by the DefaultPage Settings configuration parameter, must be fully specified. If the displayed Web browser document is from a pages request, a partial URL is resolved to another static pages request. For example, assume that the static page document at http://www.server.com/pages/mypage.htm contains the following partial URL hyperlink: <A HREF="mypage1.htm">My page 1</A> Clicking the "mypage1" hyperlink causes the request to be resolved to http://www.server.com/pages/mypage1.htm 1 12 7850 4248 010

Getting Started If the displayed Web browser document is from a txn request, a partial URL is resolved to another txn request. For example, assume that the dynamic document at http://server/txn/trans1/hello contains the following partial URL hyperlink: <A HREF="trans2/goodbye">Goodbye</A> Clicking the "Goodbye" hyperlink causes the request to be resolved to http://www.server.com/txn/trans2/goodbye To include a static page document like a GIF image within a dynamic document, the hyperlink must be either relative or fully specified. For example, you can use a relative or fully specified URL to include a GIF image in the trans1 dynamic document shown in the previous discussion: or <IMG SRC="/pages/myself.gif"> 1.7. SSL Security <IMG SRC="http://www.server.com/pages/myself.gif"> Web Transaction Server supports Secure Socket Layer (SSL) 3.0 protocol, as supported by Microsoft Internet Explorer and most other Web browsers, to provide security while transmitting information between servers running Web Transaction Server and browsers. Users can call a secure page or transaction by entering a URL directly into the browser address field, or by an embedded URL in a hyperlink reference. The SSL security protocol supports server authentication, message data encryption, and optional client authentication. Server authentication enables a browser user to verify that messages go to the intended server. Message encryption protects the entire HTTP message against unauthorized reading or modifying during transmission between a server and a browser. All SSL protocol and messages are routed through a dedicated port. Client authentication enables the server to identify a client like a credit card identifies a customer to a retailer. Web Transaction Server includes interfaces to generate public key/ private key pairs, generate certificate requests, and install server security certificates. SSL security supports a mechanism called certificates for identifying or authenticating clients and servers. Identification is automatic and transparent and is performed at the beginning of each SSL session. 7850 4248 010 1 13

Getting Started SSL security supports easy switching in and out of secure mode operation. For example, the information that enables you to view products can be transmitted with no encryption while the payment transaction is encrypted. 1.7.1. Sequence of Actions in a Simple Secure Transaction Figure 1 3 shows the sequence of actions for a simple request and reply transaction. Figure 1 3. SSL Transaction Sequence Following is a description of the actions shown in the figure: 1. The first action shows the client (browser user) requesting a static page containing a form from the server. The https prefix instructs the server to switch to a secure mode. The key in the upper left is broken, indicating that the browser is in the nonsecure mode. Note: Most browsers indicate the state of SSL security by displaying a similar key or padlock icon somewhere in the browser window. 2. The server switches to the secure mode and sends the requested page to the browser. The key in the browser is unbroken, indicating that the browser is in the secure mode. 3. The browser displays the form. The client fills in the fields on the form and transfers the form back to the server. 4. The server calls a transaction and processes the data on the form. When processing is complete, the server transfers the results back to the browser. 5. The next client request to the browser includes the http prefix, which instructs the server to switch back to the nonsecure mode. 1 14 7850 4248 010

Getting Started 1.7.2. SSL Protocol SSL protocol supports server authentication, message data encryption, and optional client authentication. Server authentication enables a browser user to verify that messages go to the intended server. Message encryption protects the entire HTTP protocol message against unauthorized reading or modifying during transmission between a server and a browser. All SSL protocol and messages are routed through a dedicated port. Client authentication enables the server to identify a client. 1.7.3. Servers and SSL Security A server running Web Transaction Server software must be designated SSL protected or Non-SSL. The same server cannot run both protected and unprotected transactions. If your site uses both SSL-protected and Non-SSL pages and transactions, you must have a separate server installation for each. Initially, Web Transaction Server software is installed on a server using the standard installation procedures and the server is Non-SSL. Use the Administration program to turn SSL protection on. Client Certificates are not required to establish and operate an SSL server. They are an optional feature that can be used if it is appropriate for your system. 1.7.4. SSL Security Encryption Suites The design of the SSL security protocol enables server systems to select from different encryption suites. This means that you can select the desired level of security that enhances the interoperability between servers and clients. Also, new and better encryption suites can be added to servers and browsers supporting SSL security when they become available. Encryptions are assigned in the following suites: Combinations of a public key method (for session initiation) Private key method (for message encryption) Message digest method (for additional protection against message alteration) Web Transaction Server supports the most common cipher suites available on the Web (RSA-based 40-bit and 128-bit encryption suites). The cipher suites use the following algorithms: RSA patented Public Key encryption algorithm RSA RC4 secret key algorithm MD5 message digest algorithm Web Transaction Server also supports a variation that uses the RSA Public Key algorithm and the MD5 algorithm, but not the RSA RC4 secret key algorithm. This provides a reasonable level of protection but does not encrypt message text. 7850 4248 010 1 15

Getting Started 1.8. Support, Restrictions, and Operational Considerations This subsection contains information defining support and other considerations that can impact the use of this product. 1.8.1. Functions Not Supported Web Transaction Server does not support the following HTTP methods or commands: DELETE OPTIONS PUT TRACE 1.8.2. Server Support Web Transaction Server can function as an origin server, but not as a proxy, gateway, or tunnel server. 1.8.3. Restriction For each browser input, there can be only one output. As an example, output is sent by the first transaction (for example, SCREEN-POLICE-12). When the first transaction terminates (D$TERM), this output is sent through Web Transaction Server to the browser. At that point, the browser does not accept any more output. Meanwhile, the first transaction schedules another transaction for execution through PASSOFF (for example, WELCOM). The WELCOM transaction also attempts to send output to the browser. The session with the browser is no longer open so Web Transaction Server captures the orphaned output and generates the following error log entry: Message-id in output pkt (526313045704) doesn't matchid set on input ( 0), output discarded for connection 0. 1 16 7850 4248 010

Getting Started 1.8.4. Exec Dependencies Web Transaction Server can run under TIP session control. Currently, an output-only TIP session is opened for each PID. Transactions scheduled by Web Transaction Server can receive input and send output, but are limited to those files/exec requests (ER) that can be accessed with minimum security capabilities. Typically, the following set of generic user profile attributes are inherited:. User-id TIPOUTPUT Account number 000000 Project-id Q$Q$Q$ Clearance level 0 NULL compartment set NULL privilege set No secured ERs The TIP session is run with a user-id of TIPOUTPUT, which has the default security profile listed. A particular transaction can or cannot run, depending on whether it can operate within this generic security environment. The most common problem area is that the transaction can attempt to directly or indirectly (through a database call, for example) reference files privately cataloged under a specific user-id or with ACR controls limited to certain user-ids. The easiest way to handle this is to catalog the files as public and restrict access to them by applying an ACR with access/update permission only for TIPOUTPUT and any other legitimate users. If a site makes extensive use of clearance levels or compartment sets, more extensive adjustments might be required. Typical transactions do not exceed the limits on privileged operating system requests as provided in an Output-Only (OO) session. However, there might be some special purpose system-oriented transactions requiring use of protected system functions that could fail in this environment. It might be possible to handle these transactions by granting the TIPOUTPUT user-id suitable privileges. Changing privileges for TIPOUTPUT makes the same privileges available to output-only sessions that do not use Web Transaction Server as well. This can or cannot be an issue. Unless a site extensively exceeds the default security settings, file access is the main area of concern. Some customer applications use the user-id to enforce application level security. In this case, the transactions check the user-id they are run under and act accordingly. These transactions do not operate correctly under the current Web Transaction Server release. Calling the CGI routines from ASCII COBOL cause a transition from basic mode to extended mode. It is strongly recommended that sites set the Exec NEWCON configuration tag TIPABSCALLSS to a value of 2 or 3. If you set it to 3, the N option must be set in the VALTAB entry of any program that calls the CGI. 7850 4248 010 1 17

Getting Started 1.9. General Sequence of Events When a user enters a request at a Web browser, the following actions take place: 1. Web browser software running on a client workstation connects to the ClearPath IX or OS 2200 servers and sends an input message (URL and data) that conforms to HTTP specifications. 2. Web Transaction Server software running on the server receives the HTTP-formatted message on its configured port (default is 80). 3. For requests that call a transaction, Web Transaction Server performs minimal processing to determine where to send the message and to add HTTP header information. Web Transaction Server passes the input to the MCB, which initiates scheduling the transaction. All other processing is performed by the transaction. 4. For TIP/HVTIP transactions, the transaction reads the input message data using the common gateway interface (CGI) routines. The transaction processes the input data, produces an HTTP-formatted message (typically an HTML-type Web page built with CGI routines), and sends the results back to the Web Transaction Server. For Open/OLTP transactions, the HTTP-formatted input message is translated to native OLTP format using the WebViewC libraries. The transaction processes the input data and produces a native OLTP-formatted output message. The output message is translated back into an HTTP-formatted output message using the WebViewC libraries and sent back to the Web Transaction Server. 5. Web Transaction Server transfers the message to the client workstation where the browser software displays the results of the request. 1 18 7850 4248 010

Section 2 Static Pages A static page is a document object in the form of a file. A static page does not mean it is a display that does not change. For example, a movie clip or a Java applet is a static page. Static pages are stored in symbolic (ASCII) or omnibus (binary) elements in standard OS 2200 files. A site administrator specifies OS 2200 file version names and corresponding Multipurpose Internet Mail Extensions (MIME) data types in a Web Transaction Server configuration file named FILETYPES. Typically, symbolic elements with a version of HTML contain HTML data. Omnibus elements with a version of GIF or JPEG contain GIF or JPEG data, respectively. Other formats can also be stored. The site administrator must register files containing static pages with Web Transaction Server. An alias is defined for each file containing static pages. Aliases are used in URLs to reference the files. 2.1. Topic Overview This section discusses the following topics: Using open file names Reading static pages (pages function) Storing (updating) static pages 7850 4248 010 2 1

Static Pages 2.2. Using Open File Names Web Transaction Server provides an automatic mapping mechanism for using Windows style open file names. You must use the Administration program to transfer these file names to Web Transaction Server page files in order for this mapping to work correctly. The long file name is stored under a specially encoded OS 2200-compliant element name in the static page file. When this long file name is used to request the file from the Web Transaction Server through a browser, the server translates the file name to the encoded form and retrieves the correct OS 2200 file element. If a file name contains any non-os 2200 characters or it contains more than 12 characters, it is encoded (hashed). If a file name contains all OS 2200 compliant characters and it is 12 characters or less, it is not encoded. The encoded element names are of the form ABHHHHHHHHYZ where: AB The first 2 characters of the long file name. HHHHHHHH Represents a special hash code that uniquely identifies the long file name. YZ The last 2 characters of the long file name. If a file name contains any non-os 2200 characters, the AB and YZ characters may differ from the original long file name. When you use the Administration program to transfer files, the encoding is transparent except to the user. The Web browser user accessing the Web object does not see the encoded name. Under no circumstances should you change the encoded element names in the OS 2200 environment. If you do, it may make it impossible to access the element. The only time the hashed name is seen is when the user of the Administration program is requested to verify the FTP output results in the DOS edit window following the FTP transfer or when using @XCOPY on the 2200 to transfer the elements between files. See the Web Transaction Server Administration Guide for more details about transferring files to the OS 2200 environment. This encoding assumes a workstation file name of the following form: <file name>.<extension> 2 2 7850 4248 010

Static Pages The <extension> is not part of the encoding. It is used as the OS 2200 element version name as it is currently. If more than one period (. ) occurs in the file name string, the <extension> is assumed to start after the last period. Any path name preceding the file name is not included in the encoding. You must use the enhanced static page file alias capability if you want to simulate multilevel directory style path names. See the Web Transaction Server Administration Guide for more details on registering and supporting aliases. 2.3. Reading Static Pages (Pages Function) The pages function reads data stored in static pages from an OS 2200 file or a CIFS directory and returns the associated Multipurpose Internet Mail Extensions (MIME) header information according to the file's version (HTML, JPEG, GIF, and so forth) and the FILETYPES configuration file. The Web browser uses the MIME header information to properly display the page. Uniform resource locators (URL) sent to Web Transaction Server must conform to the syntax defined by Web Transaction Server in order to properly read static pages (see 1.5 for more information about URLs). Any URL resource path that does not begin with /txn, by default, references a static page. URLs for static pages that must map to an OS 2200 program file element or a CIFS file have the following syntax (data enclosed in brackets ( [ ] ) is optional): http://host[:port]/[[pages/]path/] [file[.extension]] where: host port A legal internet host domain name or an IP address either in dotted-decimal format (for example: 192.61.222.6) or as an IPv6 address that is specified as groups of hexadecimal numbers are separated by colons. These IP addresses indicate the site from where the server is running. The IPv6 address must be enclosed in square brackets. For example [1234::5678] pages path A port on the server. An optional string that maintains compatibility with level 2R1 and earlier releases that required all requests to static pages to have this string. Identifies the OS 2200 program file or CIFS directory that contains the target static page. If path matches a registered static page alias name (which could be a zerolength string), the program file or CIFS directory associated with that alias name is identified as the resource location. 7850 4248 010 2 3

Static Pages file Otherwise, the resource location is assumed to be a program file with a qualifier matching the configured default static page qualifier (PagesQualifer) and a file name of path. Maps directly to the target program file element name or CIFS filename. If file and extension are both omitted, Web Transaction Server inserts index for file and html for extension. Web Transaction Server program file access does not support large element program files (CHG,E). extension If extension is included, it maps directly to the version name of the target program file element or CIFS file. If file is included but extension and the preceding period are omitted, the resource is assumed to be an element name or CIFS filename without a version name. The following examples show how static page URLs maps to OS 2200 program file elements: http://www.somewhere.com/home/welcome.htm The instance of Web Transaction Server that is servicing port 80 on the host identified by www.somewhere.com locates and returns the contents of element welcome.htm from the program file identified by home. If home is an alias for a configured static page, the program file associated with that alias name is targeted. Otherwise, the qualifier for the configured default static page and the name home are used as the complete program file name. http://www.somewhere.com/home/index.html or http://www.somewhere.com/home/ Both URLs cause Web Transaction Server to locate and return the contents of element index/html from the program file identified by home. The server automatically searches for the element index/html when path is terminated with a forward slash ( / ) and neither file nor extension are specified. http://www.somewhere.com/pub/www/documents/html-guide.txt This URL causes Web Transaction Server to locate and return the contents of element html-guide/txt from the program file identified by the static page pub/www/documents. In this case, the path portion of the resource must be an alias since it could not otherwise be mapped to a program file. http://www.somewhere.com/robots.txt This URL causes Web Transaction Server to locate and return the contents of element robots/txt from the program file identified by a static page alias name with a length of zero (static page alias name is empty). 2 4 7850 4248 010

Static Pages http://www.somewhere.com/ This URL causes Web Transaction Server to locate and return the contents of the resource identified by the configuration parameter DefaultPage. Typically, this would be a static page, but it could be configured to be the output of a gateway program. Following is an example of a pages function: http://www.cpix22.unisys.com/pages/adminhelp/wtsondoc.htm Assuming that "adminhelp" is an alias for "webts$*adminhelp," this statement accesses data in a file named webts$*adminhelp/wtsondoc.htm. The page is displayed by the Web browser according to the HTML specification for the MIME header information in the FILETYPES configuration file for the HTML version. Following are examples of CIFS pages functions: http:/my.site.com/website1/home.htm http:/my.site.com/website1/images/mypic.jpg Assuming that " website1" is an alias for ": /OS2200/prodinfo", the first statement accesses data in a file named /OS2200/prodinfo/home.htm. The page is displayed by the Web browser according to the HTML specification for the MIME header information in the FILETYPES configuration file for the HTML version. The second statement also uses the same alias to access the file /OS2200/prodinfo/images/mypic.jpg in the images subdirectory of the specified CIFS directory. A single alias entry can be used to provide access to all sub-directories of its specified CIFS directory within the constraints of CIFS security. 7850 4248 010 2 5

Static Pages 2.4. Storing (Updating) Static Pages PC based files can be easily transferred to OS 2200 Common Internet File System (CIFS) files using the Server Messages Block (SMB) capability. Simply map the Web Transaction Server configured CIFS directory to the PC and use standard Windows store/copy mechanisms to move the files into the CIFS directory. You can copy into CIFS files on an active Web Transaction Server, although on busy systems it is preferable to wait for a time of relatively low use to avoid any potential conflicts between users that may be accessing the files. If the files are to be transferred into a Web Transaction Server configured 2200 program file, use the Administration program and Form Assistant to FTP files from Web development environments to OS 2200 or ClearPath IX systems. Static page objects reside in OS 2200 program files. The OS 2200 version name of the object must match one of the FILETYPES configuration parameters maintained by the system administrator using the Administration program. The format of the OS 2200 static objects can be either omnibus (binary) or symbolic (ASCII). The omnibus format is recommended, because it accommodates both ASCII and non-ascii objects and it provides faster access. Note: It is always best to use the Administration program to transfer (FTP) files from a workstation to an OS 2200 system. Following is the recommended procedure for transferring new or updated Web content to a staging file, verifying the updated data, and then replacing the contents of the production file with the updated data. Generally, it is not a good practice to overwrite the contents of the production file. 2 6 7850 4248 010

Static Pages The following steps define a recommended, good practice procedure: 1. Catalog the staging file using the following statement: @CAT,P PUBLIC-HTML*STAGING.,F//TRK/100000 2. Copy the contents of the current production file to the staging file using the following statement: @COPY PUBLIC-HTML*LIBRARY.,PUBLIC-HTML*STAGING. 3. Use the Administration program to transfer the new or updated content to the staging file using the Administration Transfer File window. An example of this window is shown in Example 2 1. Example 2 1. An Administration Transfer Files Window 7850 4248 010 2 7

Static Pages 4. Verify the contents of the staging file. Web robots are commonly used to verify links. Example 2-2 shows an example of a window used to verify links. Example 2 2. A Linkbot Window 5. Pack the staging file to remove deleted and updated program elements using the following statement: @PACK PUBLIC-HTML*STAGING. 6. Copy the staging file to the file that will become the production file using the following statements: @ASG,UPR @COPY @FREE PUBLIC-HTML*LIBRARY(+1).,F//TRK/100000 PUBLIC-HTML*STAGING.,PUBLIC-HTML*LIBRARY(+1). PUBLIC-HTML*LIBRARY(+1). At this time, you might want to secure the new file. 2 8 7850 4248 010

Static Pages 7. Example 2 3 shows an example of an Administration window that you use to disable and then enable the Access State of the production file. This ensures that the next time Web Transaction Server references the Web content, the data will come from the updated file (in other words, the +1 cycle of the file). Example 2 3. Enabling the Access State of the Production on File When a file is offline to Web Transaction Server, the procedure for updating a file containing static objects is different than when the file is online (production file). The Administration program controls whether a file containing static objects is offline or online. It is recommended that you update pages only when they are offline. 7850 4248 010 2 9

Static Pages 2.4.1. Updating an Offline File When a file is offline to Web Transaction Server, update the file containing the static object using an editor supported by ClearPath IX and OS 2200 servers or use the Administration program and FTP to transfer the new page from a workstation to the OS 2200 file. Perform these steps: 1. Take the assigned page file offline. 2. Use the Administration program to invoke an FTP transfer of the new page to the page file. 3. Bring the updated page file back online. 2.4.2. Updating an Online File Directly updating the Web content in a production file is not recommended. See 2.4. When a file is online to Web Transaction Server (assigned by Web Transaction Server), you cannot use standard ClearPath IX or OS 2200 server utilities to replace or to update the data. This is because the utilities and FTP require that the files be exclusively assigned while the file is being updated. To update a file that is being used for current production, perform the following steps: 1. Update a copy of the data in a separate location (for example, on PC workstation). 2. Transfer the data to a temporary OS 2200 file (use the Administration program to transfer the file with FTP from the workstation). 3. Execute the xcopy utility to copy the updated elements from the temporary file into the production file. Note: For security reasons, the Administration program cannot start the xcopy program. Call the xcopy program with the following statement: @file.xcopy, options source.elt, destination.elt where: @file xcopy File where Web Transaction Server is installed, typically SYS$LIB$*WEBTS. Program name. options source.elt, destination.elt Same as for the FURPUR COPY command (see the ECL and FURPUR Reference Manual). 2 10 7850 4248 010

Static Pages 2.4.3. FTP Transfer Without the Administration Program If you use a product other than the Administration program to store workstation-formatted GIF, JPEG, or any binary formatted data as omnibus (binary) elements in OS 2200 file format, you must issue the correct commands to the FTP client and FTP server. The Administration program issues the following client workstation FTP commands to transfer omnibus elements to and from the OS 2200 operating environment: type binary quote type iow If you use the OS 2200-based FTP program TCP/IP Application Services (TAS) to transfer omnibus elements (such as GIF and JPEG), you must issue these commands before executing the PUT or GET commands or the data will not be transferred correctly. If you use the OS 2200-based FTP Services for ClearPath OS 2200 program, neither the server nor the client supports the type iow command and it is not required to correctly transfer files from a workstation to the OS 2200 environment. If you do not know which FTP program, TAS or FTP Services for ClearPath OS 2200, is installed on your ClearPath IX or OS 2200 server, include the quote command as the default. Using it with FTP Services for ClearPath OS 2200 does not cause any problems. If you use FTP Services for ClearPath OS 2200 to GET or retrieve omnibus files, you must add the following statement: quote site ftyp omn IF you use FTP Services for ClearPath OS 2200 to GET or retrieve symbolic files, you must add the following statement: quote site ftyp sym Note: Some 16-bit FTP clients may not support the quote type iow command. In this case, you must know which FTP program, TAS or FTP Services for ClearPath OS 2200, is installed on your ClearPath IX or OS 2200 server, because TAS will not transfer omnibus elements correctly. See the TCP/IP TAS Implementation and Administration Guide for additional information. If you use the OS 2200-based OPE FTP server to transfer ASCII or binary files, you must use different type statements with your FTP client than with the TAS or FTP Services for ClearPath OS 2200 servers. In addition, you must use the OPE u-driver facility to store directly into OS 2200 program files. Web Transaction Server cannot access data stored in OPE files. 7850 4248 010 2 11

Static Pages To perform a symbolic transfer of a workstation or UNIX file named c:\main.htm to an OS 2200 program file element named webts$*apppages.main/htm, enter the following FTP commands: type ascii put c:\main.htm /u/webts$*apppages.main/htm To perform an omnibus transfer of a workstation or UNIX file named c:\intro.jpg to an OS 2200 program file element named webts$*apppages.intro/jpg, enter the following FTP commands: type tenex put c:\intro.jpg /u/webts$*apppages.intro/jpg,ou Do not use the type binary option because the bits will be improperly stored in the destination element. The same type statements are used to GET or Retrieve files from an OS 2200 to a workstation using OPE FTP servers. If you are using an FTP server other than FTP Services for ClearPath OS 2200, OPE, or TAS, see the description of Transferring Files to the OS 2200 Environment in the Web Transaction Server Administration Guide. 2 12 7850 4248 010

Section 3 Calling Transactions (txn Function) Web Transaction Server enables you to execute Transaction Processing (TIP), High-Volume Transaction Processing (HVTIP), and OS 2200 TransIT Open/OLTP transactions to access your databases from the Web. Based on the information in the uniform resource locator (URL) sent to Web Transaction Server, it retrieves the attributes required to schedule the target transaction. Input data to the transaction and output message data (result data or output data) from the transaction must comply with the HTTP specifications for proper displaying by the Web browser. The txn function schedules a TIP/HVTIP or Open/OLTP transaction using the standard capabilities of OS 2200 TIP. URLs sent to Web Transaction Server must conform to the syntax defined by Web Transaction Server in order to schedule transactions. See Section 1.5 for more information about URLs. To schedule a transaction, the url-path field of a URL calls the txn function. This field provides additional information specifying the transaction to schedule. The syntax of the url-path field is the same for TIP/HVTIP and Open/OLTP transactions. To schedule a TIP/HVTIP or Open/OLTP transaction, the url-path field must contain the following fields: /function/param1/param2 where: function param1 Function name (txn). Alias name for an OS 2200 TIP/HVTIP or Open/OLTP transaction to schedule. The system administrator uses the Administration program to define, register, and enable the aliases. Aliases control and prohibit access to transactions that are not registered and enabled. 7850 4248 010 3 1

Calling Transactions (txn Function) param2 Contains input data specific to the transaction. If the transaction does not require input, you can omit this field. If the transaction requires input, this field contains the input data. A slash ( / ) or question mark (? ) must be the first character as follows: /path_info Corresponds to the CGI PATH_INFO environment variable for the TIP/HVTIP or OLTPTx transaction. For the OLTPTx transaction, PATH_INFO is interpreted as the name of the Open/OLTP service being requested. The transaction can retrieve this value with the CGIGetVar routine described in Section 7.7.3.?query_string Corresponds to the CGI QUERY_STRING environment variable. The transaction can retrieve this value with the CGIGetVar routine described in Section 7.7.3. A /txn/ in the resource (path) field indicates to Web Transaction Server that an OS 2200 transaction is to be scheduled. The following examples illustrate how URLs are used to schedule OS 2200 transactions with Web Transaction Server: http://www.somewhere.com/txn/cgi-example The instance of Web Transaction Server that is servicing port 80 on the host identified by www.somewhere.com schedules the transaction with an alias name of cgi-example. Aliases must be defined and registered by the site administrator using the Administration program (see the Web Transaction Server Administration Guide). http://www.somewhere.com:81/txn/cgi-example/extra/path?query_stuff The instance that is servicing port 81 on the host identified by www.somewhere.com schedules the transaction with an alias name of cgi-example. The extra path information extra/path and the query information query_stuff are passed to the transaction. Following is an example of a txn function: http://www.cpix22.unisys.com/txn/webts_coe_demo_txn?a=v&w=10 3 2 7850 4248 010

Section 4 TIP/HVTIP Transactions If you are interested in Web-enabling enabling your Display Processing System transactions, see the Web Enabler for Display Processing System User s Guide. 4.1. Web Enabler for Display Processing System Web Transaction Server also supports the Web Enabler for Display Processing System mechanism. This enables users (clients) to access existing OS 2200 transactions that use the OS 2200 Display Processing System from a Web browser without changing the Display Processing System transactions. See the Web Enabler for Display Processing System User s Guide for more information. With the Web Enabler for Display Processing System, you can convert this screen 7850 4248 010 4 1

TIP/HVTIP Transactions To this screen Using the Web Transaction Server and the Web Enabler for Display Processing System, you can easily adapt your existing Display Processing System transaction processing systems to be Web accessible without having to make any changes in the transaction programs themselves. In addition to making access easier and less expensive, the Web Enabler for Display Processing System allows you to improve the appearance and usability of application interfaces. Without changing the transaction programs, you can enhance the applications interface and even add additional functionality by making use of modern Web-browsers browsers capabilities such as graphics, fonts, color, multimedia, and so forth. These enhancements can significantly improve the efficiency and accuracy of the work activities that your applications support. 4 2 7850 4248 010

TIP/HVTIP Transactions 4.2. Topic Overview With Web Transaction Server, you can execute Transaction Processing (TIP) and High-Volume Transaction Processing (HVTIP) transactions from the Web. TIP/HVTIP transactions read the input data using the common gateway interface (CGI) routines. Programmers should use the CGI routines included because The programmer does not have to parse the HyperText Transfer Protocol (HTTP) header in the input message for required information. The resulting transaction programs are independent of the message delivery mechanism, in this case, the Message Control Bank (MCB). Web Transaction Server-enabled transaction programs call the CGI routines because they present a standard CGI view of the information contained in an HTTP message that must meet the CGI standard. For example, when a transaction program calls for the contents of the CGI environment variable CONTENT_LENGTH, it receives the value from the content-length field in the HTTP header. The transaction program is unaware of the underlying message format. Figure 4 1 shows a high-level view of the message data transferred between a Web browser and OS 2200 TIP/HVTIP transactions. This section discusses the following topics: Processing dynamic pages with TIP/HVTIP transactions (txn function) Input to a transaction Output from a transaction Transaction duration Error processing Troubleshooting problems 7850 4248 010 4 3

TIP/HVTIP Transactions OS 2200 TIP/HVTIP Transactions CGI Routines MCB HTTP Message (HTML-Formatted Data) Web Transaction Server HTTP Message (URL and Data) Internet Service Provider (ISP) URL (scheme://server/url-path) Web Browser Client Workstation Figure 4 1. Using the OS 2200 TIP/HVTIP Transactions 4 4 7850 4248 010

TIP/HVTIP Transactions 4.3. Processing Dynamic Pages with TIP/HVTIP Transactions (txn Function) The txn function can schedule TIP/HVTIP transactions to retrieve data stored in an OS 2200 application for output as a dynamic page. The param2 field is part of the url-path field described in Section 3 and contains data specific to TIP/HVTIP transactions. If the transaction does not require input, you can omit this field. If the transaction does require input, this field contains the input message data. A slash ( / ) or question mark (? ) must be the first character as follows: /path_info Corresponds to the CGI PATH_INFO environment variable. The transaction can retrieve this value with the CGI$GETVAR routine (see Section 7.4.3) or the CGIGetVar routine (see Section 7.7.3).?query_string Corresponds to the CGI QUERY_STRING environment variable. The transaction can retrieve this value with the CGI$GETVAR routine (see Section 7.4.3) or the CGIGetVar routine (see Section 7.7.3). The following example schedules a transaction with an alias of "alais1" and a PATH_INFO value of "hello": http://www.cpix22.unisys.com/txn/alias1/hello 7850 4248 010 4 5

TIP/HVTIP Transactions 4.4. Input to a Transaction A TIP/HVTIP transaction receives all its input in an HTML message with the following format: HTTP Header blank line message body blank line auxiliary information The HTTP Header and message body fields contain the HTTP header information and message body information sent by the client's Web browser. Data in the auxiliary information field is added by Web Transaction Server and contains additional information. For all input data from Web Transaction Server, octal 0200 is set in the P$TTYP field of the MCB packet. The format of the information in the auxiliary information field is compatible with the information in the HTTP Header field. See Section 7.8 for additional descriptions. Following is the format of the auxiliary information field: where: REMOTE-ADDR: agent-ip-address SERVER-SOFTWARE: WebTS/version SERVER-NAME: server-ip-address SERVER-PORT: ip-port REMOTE-HOST: domain-name nnnn agent-ip-address IP address of the agent sending the request to the server. If the client workstation is connected directly to the ClearPath IX or OS 2200 server, the client Web browser and agent are the same and there is only one IP address involved with the input request. If the client workstation is connected through an Internet service provider (ISP) such as America Online (http://www.aol.com), the client Web browser and agent are not the same and the IP address of the client Web browser is not necessarily the same as the IP address of the agent. WebTS/version Version currently running on the ClearPath IX or OS 2200 server. server-ip-address IP address of the server where Web Transaction Server is executing. 4 6 7850 4248 010

TIP/HVTIP Transactions ip-port Port on the server where Web Transaction Server is executing. domain-name nnnn Fully qualified domain name of the client, if remote look-up is specified in the transaction table. A 4-digit decimal number containing the length of the auxiliary information field. This field is always the last 4 characters in the message. By backing up nnnn characters from the end of the message, you can locate the beginning of the auxiliary information field (address of the auxiliary information field=message address + message length - nnnn). Note: The format of this message might change in future levels of Web Transaction Server. Please use the CGI routines instead of reading data directly from the MCB because the resulting transaction programs will be independent of the message delivery mechanism, in this case, MCB. 4.5. Output from a Transaction When a transaction finishes processing, it generates an output message in HTML format and transfers it to the Web Transaction Server. Web Transaction Server transfers the ASCII output data to a Web browser, which inserts the data into the appropriate outputonly fields in an HTML document. When a message is sent to a client workstation for display, the Web browser must know what type of information is in the message (text, graphics, video, or information for a specific application). This enables the Web browser to display the message itself or call another application if necessary. The multipurpose Internet mail extension (MIME) standard defines the means for including this information with the message. Following are the formats, types of output, and decimal values set in the P$FORMAT field of the MCB packet: Plain text (0) Unformatted message of ASCII characters (MIME type=text/plain). HTML (1) ASCII characters in HTML format (MIME type=text/html). 7850 4248 010 4 7

TIP/HVTIP Transactions Parsed headers (2) This output type can be used to add additional headers or replace standard headers in a message. The program must provide the message in the following form: Substitute header 1 LF... Substitute header n LF LF body LF is the standard line feed character (octal 012). One or more headers can be provided. No blanks are required other than those within the header and body entries. Carriage returns should occur only in the body part of the message. Note that this is different from the HTTP standard output message format that uses a carriage return line feed sequence to separate header fields. Web Transaction Server generates those when it produces and sends the final output to the browser. Following is a sample parsed header string that sends a 401 unauthorized response: status: 401 Access Denied LF WWW-Authenticate: Basic realm=unitown LF Connection: Close LF LF <HTML><HEAD><TITLE>Access Denied</TITLE></HEAD> <BODY><H1>You are not authorized to view this page.</h1> </BODY></HTML> The header fields are either CGI header fields which are to be interpreted by Web Transaction Server, or HTTP header fields which are to be included in the response returned to the workstation client. Do not repeat a CGI header field using the same field-name. If an HTTP Content-Type header field is not supplied, Web Transaction Server assumes a Content-Type of text/html. The CGI header fields have the following generic syntax: header-name: field-value where: header-name Contains one of the following header field definitions. This field is not case sensitive. Content-Type The Internet media type of the entity body (see the HTTP Protocol Specification for a description of media types). The parameters in this field are sent to the client without any changes. 4 8 7850 4248 010

TIP/HVTIP Transactions Location Status Specifies to Web Transaction Server that the script is returning a reference to a document instead of the document itself. The location value is a URL specifying the location of the document. Web Transaction Server in turn generates an HTTP response message indicating a redirected reference. If the transaction does not supply an entity body, the server generates one. Indicates to Web Transaction Server the status code (such as 200 OK or 401 Access Denied) that it will use in the response message. It should not be sent if the script returns a Location header field. The valid status codes are listed in the HTTP Specification. If the transaction does not return a Status header field, the server assumes a value of 200 (OK) HTTP status. HTTP headers field-value The script might return any other header fields defined by the HTTP Specification. The Server, MIME-version, and Content-Length header fields are always constructed by Web Transaction Server and are ignored if they already exist in the header field of the response message sent by the transaction. Other header fields dealing with client/server interaction might also be ignored if they could possibly interfere with correct client/server functions. The value to assign to the header field. Nonparsed headers (3) The transaction must supply the complete HTTP-formatted message including header and body. Web Transaction Server does not change the message before sending it to the client. Parsed headers close (4) Same as Parsed headers, except a connection close occurs after the message is sent. Nonparsed headers close (5) Same as Nonparsed headers, except a connection close occurs after the message is sent. 7850 4248 010 4 9

TIP/HVTIP Transactions Parsed and nonparsed headers do not support persistent PIDs, Secure Sessions, or static PID mechanisms since those functions require special cookie maintenance. Parsed and nonparsed headers are designed so that the application can provide its own cookie handling which overrides the Web Transaction Server PID life cookie. All transactions using these modes for output are treated by Web Transaction Server as SHORT PID Life transactions. 4.6. Transaction Duration Web Transaction Server terminates transaction requests if they do not receive a reply within a specified period of time. This helps detect transaction errors and prevents communications connections from being indefinitely taken out of service due to an individual malfunctioning request. When a transaction execution times out, Web Transaction Server returns a 504 Gateway Timeout Error to the browser and closes the connection making it available for use by other users. If the transaction is still running, it might continue to run depending on the OS 2200 system resource limits, but Web Transaction Server ignores it and there will not be any output returned to the browser. This transaction timeout is controlled by the Administration program setting maxconnectiontime. If your transactions are timing out with the configured value, you can increase it for your application. 4 10 7850 4248 010

TIP/HVTIP Transactions 4.7. Error Processing In general, a transaction receiving an error status from a CGI routine has little recourse but to roll back database updates. The exact error processing that a transaction performs varies greatly, depending on the design of an application. But, the same approach currently used to recover from MCB and Display Processing System errors should be followed for CGI routines. The MCB provides a sample Error Notification Program (ENP) called EXAMPLE?ENP to handle errors, but you must replace this ENP program (or a similar ENP program that you might have developed) for use with transactions scheduled by Web Transaction Server. Without an ENP designed to handle errors in transactions scheduled by Web Transaction Server, failed transactions do not return any error message to the browser, the user request will eventually timeout, and the browser displays the "504 - Gateway Timeout" error rather than a specific transaction error message. This occurs because each transaction scheduled by Web Transaction Server has a unique message identifier in the MCB AUX area. When a Web Transaction Server reads the output from a transaction, a check ensures that the message identifier in the output matches the expected message identifier. If it does not, the output is discarded. Therefore, it is important to ensure that the message identifier in the MCB AUX area is returned in any error message generated by the ENP program. The current standard MCB-supplied EXAMPLE-ENP does not return the AUX area of the original message, which means that Web Transaction Server discards EXAMPLE-ENP generated error messages. Web Transaction Server provides a replacement for the standard MCB supplied EXAMPLE-ENP in the server*proddoc file created when Web Transaction Server is installed. This ENP is called WEBTS-ENP. It is also included on the Web Transaction Server CD-ROM in the PRODDOC directory. The WEBTS-ENP can be used as is or it can be used as a guide for updating your ENPs to work correctly with Web Transaction Server. See the Message Control Bank (MCB) Programming Reference Manual for more information on the ENP facility. When you convert an existing application with an MCB ENP, you must make changes similar to those made when the WEBTS-ENP is updated from the MCB supplied EXAMPLE-ENP. In addition, you m want to modify your ENP to enhance the appearance of error messages used with Web Transaction Server. If the application supports both Universal Terminal Systems (UTS) terminals and Web browser access, your ENP can check the terminal type in the MCB AUX area (P$TTYP) to determine if the terminal is a Web browser. When the ENP executes, messages received from the MCB contain the original MCB input packet with the P$TTYP field set to octal 0200 when the input is from a Web Transaction Server. The ENP can use this information to determine the appropriate format for error responses sent to users. Be sure to include the complete Web Transaction Server-built AUX area in your output and set the P$FORMAT field during output to indicate the format of your message. For example, plain-text, HTML, and so forth as described in Section 4.5. Output messages to browsers should not contain any control characters. If they do, the browser usually displays the control characters as "box" characters. 7850 4248 010 4 11

TIP/HVTIP Transactions 4.8. Troubleshooting TIP/HVTIP Transactions Problems Following are some hints and things to check for if problems develop when trying to run transactions with Web Transaction Server: Have you verified that your transaction works in a non-web Transaction Server environment? Have you checked the server ERROR$LOG file for possible error messages indicating problems with transaction related configurations? Incorrect AGS and/or Txns entries can often cause problems. 4 12 7850 4248 010

Section 5 Secure Sessions This section explains how to set up the server that is running Web Transaction Server to support the Secure Sessions facility. This enhances transaction handling by integrating it with TIP session control security. Note: An SSL session is not the same as a Secure Session, but they are compatible and can be used at the same time. 5.1. Topic Overview This section discusses the following topics: Key concepts Basic steps in a Secure Session Terminating Secure Sessions Log on processing Security Default Definition Log off processing Web Enabler for Display Processing System considerations Single server SSL and Non-SSL support Systems not supporting TIP session control Secure Sessions log entries 7850 4248 010 5 1

Secure Sessions 5.2. Key Concepts A Secure Session is a mechanism that allows a series of transaction requests from the same browser to be processed according to the security attributes of a specific OS 2200 user-id. Secure Sessions are implemented using the Web Transaction Server persistent PID facility and features of the TIP session control mechanism. TIP session control, among other things, determines the security environment in which transactions operate. When a user initially requests a Secure Session, Web Transaction Server validates the user's user-id and password. If the user-id and password are ok, Web Transaction Server initiates a TIP session under the specified user-id. All subsequent transactions from this user are processed under control of this TIP session until a Secure Session logoff or TIP session time-out occurs. This means that all transactions are run under the security limits and privileges configured under OS 2200 for that specific user-id. Do not confuse Secure Sessions with SSL sessions. See the following table for some of the differences and similarities between Secure Sessions and SSL: Secure Sessions Applies only to transactions. Provides user identification and high security access control and protection of server resident data and services. Secure Socket Layer (SSL) Sessions Applies to static pages as well as transactions. Provides message encryption and authentication for the network connection between a browser and a Web Transaction Server. An independent mechanism whose lifetime does not necessarily conform to the length of a Secure Session or a TIP session. See the Web Transaction Server Administration Guide for a description of SSL security. 5.2.1. Secure Sessions In preparation for using Secure Sessions, site administrators must define user-ids, passwords, and other attributes on OS 2200 servers with system administrator tools (for example, SIMAN). Web Transaction Server only supports SIMAN authentication type 0. See the TeamQuest SIMAN Administration and End Use Reference Guide for additional information. 5 2 7850 4248 010

Secure Sessions Figure 5 1 shows a high-level view of the steps in a Secure Session. Figure 5 1. Basic Steps for Using Secure Sessions The following is an overview of the steps in a Secure Session: A user initiates a Secure Session by submitting a user-id and a password on a special log-on form. A Secure Session can take place entirely or partially within an SSL session or it can function properly when no SSL session is active. When a Secure Session is active, references to Non-SSL transactions, static pages, and graphics are still honored and the related messages are transmitted in unencrypted form. Web Transaction Server verifies the user-id/password using the same authentication code as that used when a user logs onto a ClearPath server. When a session opens successfully, a TIP session is based on that user-id. The persistent PID mechanism ensures that subsequent transactions originating at the same workstation use the same PID and as a result, run in the same TIP session. This means that TIP session control ensures that ClearPath server security restrictions are automatically enforced by the OS 2200 environment on all transactions within a Secure Session. 7850 4248 010 5 3

Secure Sessions The REQUIRE_SECURE_SESSION transaction attribute enables users to configure individual transactions so that that they must be executed only within a Secure Session. If a transaction that is configured to run only within a Secure Session is requested and a Secure Session is not active, Web Transaction Server rejects the request and displays a Secure Session log-on form. If a transaction that is not configured to execute only within a Secure Session is requested and a Secure Session is active, Web Transaction Server runs the transaction under the Secure Session. If a Secure Session is not active, Web Transaction Server executes the transaction according to the standard PID assignment process. See the Web Transaction Server Administration Guide for a description of the REQUIRE_SECURE_SESSION transaction attribute. Static pages can also be loaded during a Secure Session, but they are loaded by the Web Transaction Server static page handler and are not protected by TIP session control. 5.2.2. Terminating Secure Sessions A Secure Session and the related TIP session, can be terminated in several ways as follows: A CGI transaction can initiate a request to terminate the current Secure Session when the transaction is complete. A Display Processing System transaction operating under Web Enabler for Display Processing System can be modified to request that the CGI function terminate a Secure Session. This enables a transaction to conditionally terminate a session based on program logic. A user can submit a request from a browser to execute a log-off specific transaction. This is a specific case where a transaction unconditionally submits a request that the CGI function terminate a Secure Session. Certain underlying TIP session, persistent PID time-out, or other Secure Session related errors can cause a Secure Session to be terminated. Whenever possible, an error message is sent to the browser user. Note: The persistent PID time-out period is determined during configuration. The TIP session time-out period is determined by the OS 2200 TIP session configuration and cannot be configured using the Administration program. If the WebTS CookieExpireDays setting is set to the default 0 value, the connection to a Secure Session (or Kerberos/NTLM session) is lost if you exit from the browser. The orphaned session will eventually time out, and you will not be able to access the session by restarting the browser. This standard action may be preferable for security reasons, but it can be changed. If you set CookieExpireDays to 1 or more, you can restart the browser and reconnect to the session without re-authentication as long as the TIP session time-out period has not lapsed. 5 4 7850 4248 010

Secure Sessions Within Secure Sessions, a PID Life of Short is ignored. This means that transactions with a PID Life of Short are treated the same as transactions with a PID Life of Long. This enables transactions with a PID Life of Short to run without terminating the Secure Session. See the Web Transaction Server Administration Guide for a description of PID Life. 5.3. Administration User-IDs and passwords must be defined so that the user-id and password provide all the information that the system needs to run a Secure Session. Do not define user-ids so that alternate account numbers or any additional information can be input into the system. 5.4. Log-On Processing A user initiates a Secure Session by submitting an HTML input form (see Figure 5 2) that invokes a special Web Transaction Server function named Logon. This special transaction-like request includes the user-id, password, and other information that Web Transaction Server uses to authenticate the user and to initiate a Secure Session and its related TIP session. After the session starts, Web Transaction Server processes the initial page or transaction request which is also part of the Logon information. This enables an application developer to customize the appearance of the log-on screen for the application and to display the initial screen during a successful log-on. If the user-id/password verification fails, Web Transaction Server ignores the request and displays an error message. Optional parameters enable a user to change passwords. When a password is changed, Web Transaction Server performs the steps necessary to change the OS 2200 password for the next log-on. Figure 5 2 shows a sample log-on screen. The HTML code for the screen immediately follows the figure. 7850 4248 010 5 5

Secure Sessions Figure 5 2. Secure Session Log-On Window 5 6 7850 4248 010

Secure Sessions Following is the HTML code, including embedded comments, that defines the Secure Session log-on for application group 1. <HTML> <HEAD> <TITLE>Secure Session Log-On</TITLE> </HEAD> <BODY> <CENTER> <H2>Secure Session Log-On</H2> <FORM ACTION="/logon" METHOD="POST"> <! Define logon for application group 1> <INPUT TYPE=HIDDEN NAME=WSAG VALUE=1> <! Define URL to start after a successful logon. This VALUE should be replaced with the start up page of your transaction. If this VALUE is changed to a transaction (txn), ensure that the transaction is an application group 1 transaction.> <INPUT TYPE=HIDDEN NAME=WSSTARTURL VALUE="/pages/proddoc/LogOnOK.htm"> <TABLE> <TR><TD>UserID</TD> <TD><INPUT TYPE=TEXT NAME=WSUSERID VALUE="" SIZE=12 MAXLENGTH=12></TD></TR> <TR><TD>Password</TD> <TD><INPUT TYPE=PASSWORD NAME=WSPASSWORD VALUE="" SIZE=12 MAXLENGTH=12> </TD></TR> <TR><TD>New Password</TD> <TD><INPUT TYPE=PASSWORD NAME=WSNEWPASS VALUE="" SIZE=12 MAXLENGTH=12> </TD></TR> <TR><TD>Re-Enter Password</TD> <TD><INPUT TYPE=PASSWORD NAME=WSRENEWPASS VALUE="" SIZE=12 MAXLENGTH=12> </TD></TR> </TABLE> <P><INPUT TYPE=SUBMIT VALUE=Submit></P> </FORM> </CENTER> </BODY> </HTML> 7850 4248 010 5 7

Secure Sessions Default log-on HTML forms are included in the server*proddoc file as part of a release for each application group. The log-on HTML forms can be customized with graphics or redesigned as long as the URL request that the form generates conforms to the Logon function requirements. The Logon function should be called with the POST method to avoid a browser displaying the password parameter. The GET method can be used, but then parameters are visible under certain conditions. The following Web Transaction Server names are reserved and must be used to ensure proper recognition of log-on URL parameters: WSUSERID User-ID WSPASSWORD Password WSNEWPASS New password (to change password) WSRENEWPASS Repeat new password (to verify a new password) WSAG Application group WSSTARTURL URL for first application screen In Figure 5 2, the application group field (WSAG) and starting URL field (WSSTARTURL) contain predefined values, but they are hidden. They could be made visible. When you change a password, the WSNEWPASS and WSRENEWPASS values must be identical. The output from a successful log-on operation consists of the output from the initial transaction or static page specified by the WSSTARTURL parameter. This parameter must be provided and must call an installed page or transaction. The previous example displays a "Logon Ok" page named /pages/proddoc/logonok-htm. Web Transaction Server opens a new session with each logon request. When a logon attempt fails, Web Transaction Server closes the session and frees the resources allocated to the user. As a consequence, each new logon request opens a new session and resets the MAXATMP parameter (defines the maximum number of times login requests can be attempted before a session is disabled). As a result, users are blocked when the numbers of their requests exceed the value in the MAXATMP parameter. 5 8 7850 4248 010

Secure Sessions 5.5. Security Default Definition Both Secure Sessions and Kerberos/NTLM authentication mechanisms use the 2200 logon mechanism to connect to TIP Session control. The initial implementation of these features requires that the user-id be configured so that extra solicitation options during logon are not supported. This means that if users need to operate with multiple projects, accounts, clearance levels, or compartment sets, they must configure separate user-ids s for all combinations of solicitation responses that they plan to use. The Security Default Definition mechanism enables users to interactively specify the different options that they wish to use. They can dynamically switch between sign-on options as needed. The Security Default Definition mechanism is based on user-defined sets of logon responses that can be defined via the HTML form provided with Web Transaction Server (see Figure 5 3). Figure 5 3. Security Session Defaults Window To define a user set, use the Define a New Set section of this form. You must enter an alphanumeric Set Name to identify the combination of logon responses you are configuring. Then, fill in only the answer fields (Project, Account, Clearance Level, or Compartment Sets) that are associated with the solicit requests you expect your user-id logon to display during sign on. You do not need to enter anything into any unused options. Note that you can enter either the Project Index or Account Index directly or by index selection responses depending on how your user-id is configured. 7850 4248 010 5 9

Secure Sessions Example 5 1 shows an example of the entries for a sample set. Example 5 1. Example Entries for a Sample Set On this form, you can also enter the number of days that you want a set to be saved after its most recent use. Anytime you use a default set, the expiration date is extended by the number of days that you specified. When you define a new Definition Set, it automatically becomes the Current Set. The Current Set is the set of values that is used when you attempt to log on through either the Secure Sessions or Kerberos/NTLM authorization mechanisms. These values are handled automatically by Web Transaction Server. Web Transaction Server stores the Definition Set information in a cookie on your workstation and retains it for the specified number of days. You do not need to redefine or reselect the Current Set during subsequent sessions unless you need to change the responses required during logon. Use this same form to enter multiple Definitions Sets. Remember that the last Definition Set defined is the current effective set. 5 10 7850 4248 010

Secure Sessions You can determine your Current Set at anytime by clicking Display Current Set on the form in Example 5 1. When you do, Web Transaction Server displays the current definition in a form similar to the example in Example 5 2. Example 5 2. Example of a Current Session Set 7850 4248 010 5 11

Secure Sessions To view all of the sets you have defined, click Select Another Existing Set on the Security Session Defaults window. This displays a form like that in Example 5 3. On this form, you can change the Current Set by clicking Select on the desired set and you can delete a set you no longer need by clicking Delete on the set. Example 5 3. Example of Available Session Definition Sets Remember that when you log on with either Secure Sessions or Kerberos/NTLM mechanisms, Web Transaction Server remembers and reuses the same TIP Session for successive requests. Therefore, if you need to change security options to access a different application, you must enter an explicit LOGOFF request to close the current TIP Session and then sign on again after switching to the new Definition Set. The Security Sessions Default form is a standard ard HTML page form and can be customized at the site if desired. Entry boxes for security parameters that are not used on the system can be removed. All other Security Definitions forms are automatically generated internally by Web Transaction Server. The location of the Security Sessions Default form depends on your local site configuration. Check with your security administrator for the proper URL link to access this screen. 5 12 7850 4248 010

Secure Sessions 5.6. Log-Off Processing Secure Sessions can be closed in several ways as follows: Explicit log-off request Explicit log-off requests can be executed from either a browser or a transaction. Web Transaction Server closes the Secure Session when a user enters the following URL: http://server-name/logoff After this URL is executed, the Secure Session is terminated. If you want to run new Secure Session transactions, you must log in again. All future requests require a new log-on sequence. Log-off return from a transaction As an alternative, a transaction can call the CGI$LOGOFF (COBOL) or CGILogoff (C) functions. These functions cause Web Transaction Server to close the current Secure Session and release all user-id related privileges before sending the transaction output back to the browser. Normally, Web Enabler for Display Processing System transactions can execute a Display Processing System logoff. But this is not a session logoff, it is a logoff of the Display Processing System session and not the Secure Session. If desired, a Web Enabler for Display Processing System transaction can log off of a Secure Session by doing a passoff to a CGI transaction that executes a CGI$LOGOFF function. In that case, output that is to be returned to the browser should come from the CGI transaction because a browser can only get one output from each request. Following is the format of the Display Processing System output message: <HTML><HEAD><TITLE>Message</TITLE></HEAD><BODY><H1>Your message text</h1></body></html> or <HTML><HEAD><TITLE>End Message</TITLE></HEAD><BODY><H1>Your message text</h1></body></html> Both formats display the message text (Your message text) in a dialog box. The "End Message" version also blanks the screen. Secure Session timeout If an explicit log-off is not performed, the TIP session time-out eventually closes all inactive Secure Sessions. 7850 4248 010 5 13

Secure Sessions 5.7. Web Enabler for Display Processing System Considerations Existing Display Processing System applications often use TIP session security to control application user privileges based on user-ids and passwords. Because of the tight linkage between Secure Sessions and TIP sessions, Web Enabler for Display Processing System applications can support the Display Processing System applications by operating within Secure Sessions. If you want to, you can modify the Secure Session log-on HTML for an application to call the first application screen after the user-id/password is accepted. Web Enabler for Display Processing System developers can add a user-selectable link to application screens that directly calls a CGI style log-off transaction in order to perform a Secure Session log-off. Calling the CGI$LOGOFF or CGILogoff function from within a Web Enabler for Display Processing System transaction cannot cause a log-off because of the way Display Processing System handles the output. Transactions can log-off by using a transaction pass-off message to schedule a standard CGI style log-off transaction. 5.8. Single Server and Non-SSL Support Currently, both SSL and Non-SSL requests (mixed-mode SSL) can be processed by the same server. This capability is required in order to maintain a continuous Secure Session when processing both SSL and Non-SSL requests since the persistent PID mechanism requires that all transaction references be handled by the same server. Mixed-mode SSL does not require Secure Sessions applications and can be used with non-secure Session applications. The REQUIRE_SSL_CONNECTION attribute enables an administrator using the Administration program to mark individual pages (PAGES list) and transactions (TXN list) as to whether or not they require an SSL connection to access them. The default setting of the REQUIRE_SSL_CONNECTION attribute for new PAGES and TXNS entries is Off. When the attribute is set to On, the page or transaction can only be accessed when an SSL session (secure mode) is established through an HTTPS request from a browser. When the attribute is set to Off, the page or transaction can be accessed during either an SSL session or a Non-SSL session. See the Web Transaction Server Administration Guide for a description of the REQUIRE_SSL_ CONNECTION attribute. Do not select this attribute for AdminHelp files. 5 14 7850 4248 010

Secure Sessions The SSLEnabled security option indicates the desired SSL state of the server. The possible values are On, Off, and Required. This option enables a site to override the secure connection setting for individual transactions with a global setting. When the option is set to Required (entire server is SSL protected), all pages and transactions on the server require SSL access regardless of the setting of the REQUIRE_SSL_CONNECTION attribute in the PAGES and TXN entries. HTTP requests cannot be accepted. When the option is set to On, the REQUIRE_SSL_CONNECTION attribute in the PAGES and TXN entries control the processing of SSL and Non-SSL requests. When the option is set to Off, only non-ssl requests are processed. HTTPS requests are not accepted. See the Web Transaction Server Administration Guide for a description of the SSLEnabled security option. Multiple aliases can be mapped to a single page file or a single transaction. The REQUIRE_SSL_CONNECTION attribute for a page file or transaction corresponding to the alias specified in the requesting URL determines whether they can be accessed during an SSL session or a non-ssl session, unless overridden by the SSLEnabled security option. This means a page file or a transaction might be accessible in either an SSL session or non-ssl session if multiple aliases with differing REQUIRE_SSL_CONNECTION attribute values are configured for the page file and transaction. Client Certificates are optional and are assigned on a server wide basis. They are used only during SSL sessions. It may not be possible to sustain a continuous Secure Session for both HTTP and HTTPS requests from the same instance of Netscape browsers that use nonstandard port numbers (other than 80 and 443). This is because of the way Netscape manages cookies for explicitly specified ports. 7850 4248 010 5 15

Secure Sessions 5.9. Systems That Do Not Support TIP Session Control Secure Sessions require successful OS 2200 installation, configuration, and integration of Web Transaction Server transaction handling with TIP session control. Secure Session functions are not available on systems that do not have fully operational TIP session control. On these systems, Secure Session log-on requests are rejected with a Status Code of 403 and a reason-phrase of "Secure Session Log-On Not Available." Web Transaction Server displays a "Not Found" for the REQUIRE_SECURE_SESSION transactions on these systems. The CGILogoff functions can be used on systems that do not support TIP session control, but their only action is to close the current persistent PID session if one exists. 5.10. Secure Sessions Log Entries Exec and TIP session control provide a variety of relevant OS 2200 log entries. Transaction calls are currently logged by Web Transaction Server in the server log. Secure Session log-on failures are logged along with the specified user-id and the requesters IP address. 5 16 7850 4248 010

Section 6 Kerberos/NTLM Sessions This section explains how to use the Web Transaction Server Kerberos/NTLM feature to support Kerberos or NTLM authentication linked to Microsoft network security. This facility is similar in operation to Secure Sessions except that the Microsoft network sign-on is used to provide automatic authentication for Web Transaction Server access. Like Secure Sessions, this mechanism integrates with TIP session control security to control the security environment of called transactions. This feature also provides access control for static pages in CIFS files. Access control is not provided for static pages in 2200 format program files. 6.1. Topic Overview This section discusses the following topics: Key concepts Basic steps in a Kerberos/NTLM Session Terminating Kerberos/NTLM Sessions Log-on processing Log-off processing Mixed Kerberos/NTLM Sessions and Secure Sessions Web Enabler for Display Processing System considerations Systems not supporting TIP session control Kerberos/NTLM Sessions log entries 7850 4248 010 6 1

Kerberos/NTLM Sessions 6.2. Key Concepts The Web Transaction Server Kerberos/NTLM feature uses the Flexible User Authentication (FLEX) facility of the 2200 Operating System integrated with Windows network security to provide high security and single sign-on for OS 2200 based servers running Web Transaction Server in Microsoft networks. The Kerberos/NTLM feature supports the same capability to control transaction file access on an individual user-id basis as that provided in Secure Sessions. When authenticating transactions, this feature links to the TIP session mechanism in the same manner as Secure Sessions. See the Flexible User Authentication Administration Guide for more information about FLEX. The most significant difference between Secure Sessions and Kerberos/NTLM sessions is during the initial authentication process while starting the related TIP session. Secure Sessions uses an explicit log-on command and log-on forms for collecting the authentication information (user-id and password). Kerberos/NTLM sessions use built-in Windows authentication protocol and interfaces into the Windows security system to retrieve the authentication information and to verify its authenticity. Once access to a transaction is authenticated, the Kerberos/NTLM session operates like a standard Secure Session. See Section 5.2 for more information on the security controlled transaction execution environment. Kerberos/NTLM authenticated static page access does not use TIP session control. Instead, Web Transaction Server directly accesses the 2200 Kerberos/NTLM authentication module to authenticate the user submitted credential. In this release, page access authentication only checks to see that a user has valid credentials to access the Web Transaction Server 2200 host. This can prevent any attempted access by clients that do not have valid sign-ons for the 2200, but cannot distinguish between individual authenticated users in terms of file access control. In a later release, Web Transaction Server takes advantage of a planned 2200 Operating System feature, which allows Web Transaction Server to do its page access under the specific 2200 user- ID associated with the network identity of the user. This permits selective access control by an individual user through the use of ACRs on Web Transaction Server page files. When it is activated, the Kerberos/NTLM feature always requests Kerberos authentication, but Microsoft Internet Explorer automatically defaults to NTLM authentication if Kerberos authentication is not configured in the Windows network security setting for the Web Transaction Server host. It is possible to configure Web Transaction Server page and txn entries for both Secure Sessions and Kerberos NTLM sessions to handle situations where some terminals accessing the system are not part of the Kerberos/NTLM protected portion of the network configuration. It s also possible to configure a network to use only NTLM authentication without using Kerberos authentication. Using this feature requires Microsoft Internet Explorer level 6.0 or higher. There are also minimum operating system level requirements for the server and client systems on the network that is using authentication. See the Web Transaction Server Administration Guide for more information. 6 2 7850 4248 010

Kerberos/NTLM Sessions 6.2.1. Kerberos/NTLM Sessions Figure 6 1 shows a high-level schematic of the components involved in Kerberos/NTLM authentication. Figure 6 1. Components of Kerberos/NTLM Authentication The following is an overview of the steps in a Kerberos/NTLM Authentication: The first step is for Web Transaction Server to receive a request from a Microsoft Internet Explorer (IE) browser user for a transaction or Web page that is marked in the Web Transaction Server configuration as protected by Kerberos or NTLM authentication. Web Transaction Server does not distinguish between the two types of authentication; that differentiation occurs in the EXEC/Windows authentication process. If Web Transaction Server determines that a Kerberos/NTLM session is not in force for this user, it responds with a special HTTP protocol response indicating that it wants authentication from the browser user. The IE browser recognizes this protocol response and transparently passes the request for authentication to the Windows network security system. The request for authentication requests the user s credentials for accessing the server identified by the Domain Name Server (DNS) name specified in the original HTTP request. Windows network security responds to IE with either a digital credential (in other words, a Kerberos ticket or NTLM challenge phrase) or a Fail indication. IE responds to a Fail indication by aborting the original TXN/Page request. Otherwise, IE sends a special protocol message, including the credential, back to Web Transaction Server. 7850 4248 010 6 3

Kerberos/NTLM Sessions When Web Transaction Server receives the request with the credential, it attempts to start a TIP session control session using the credential for authentication. This uses the same TIP session control interfaces currently used for Secure Sessions. The principal significant difference is that a ticket or challenge phrase is passed instead of the user- ID and password. The 2200 Operating System passes the credential to the NTLM/Kerberos Authentication Module, which is part of the Flexible User Authentication (FLEX) product. This Authentication Module interacts using the network with Windows Network Security authority which controls the 2200 Kerberos authentication. If the authentication fails, Web Transaction Server receives a message similar to the message generated when a user- ID/password is bad. In this case, Web Transaction Server aborts the entire request the same as it would when a bad password is detected during a Secure Session. If authentication succeeds, TIP session initiation completes, Web Transaction Server processes the original TXN/page request, and sends the output back to IE. Kerberos sessions stay open just like Secure Sessions, subject to the same session and PID related timeouts. This means that authentication will not be required on subsequent protected transaction requests as long as the session is still open. Often Kerberos/ NTLM authentications require multiple security context authorizations to succeed. In this case, Web Transaction Server might initially receive another security context credential request back from the 2200 Authentication Module instead of an immediate authentication approval. Web Transaction Server passes the new request back to IE in the same special HTTP protocol format used initially. IE again requests credentials for this new security context from Windows network security and the entire process repeats until either IE receives a Success or Fail response from Windows network security or Web Transaction Server receives a Success or Fail response from the 2200 Authentication Module. 6.2.2. Terminating Kerberos/NTLM Sessions Kerberos/NTLM sessions can be terminated in the same way as standard Secure Sessions (see Section 5.2.2). 6.3. Administration In order to use Kerberos/NTLM authentication, the Windows network, the 2200, and Web Transaction Server must be correctly configured. See the Web Transaction Server Administration Guide for details. 6 4 7850 4248 010

Kerberos/NTLM Sessions 6.4. Log-On Processing Since Web Transaction Server automatically initiates the log-on process at the first reference to a Kerberos/NTLM protected transaction or page file, no logon screen or LOGON function call is required. If authentication is successful, there is normal output from the transaction or page. If authentication fails, an error message is returned. If the IE Windows session is not logged onto a Windows network domain supporting Kerberos authentication of the target server running Web Transaction Server, Kerberos authentication requests fails. If this happens, an attempt is made to do an NTLM authentication request. Additionally, if NTLM credentials for the browser Windows domain are not available, IE might (depending on the configuration) display a Windows log-on window. This gives a user an opportunity to input an alternate user-id, password, and domain name for a domain that supports NTLM authentication to the target server. Once the user is authenticated with a currently valid Kerberos ticket, the length of the user s authorization to call protected Web Transaction Server transactions is determined by the TIP session control timeout period and not the expiration time specified in the authenticated Kerberos ticket. If the TIP session times out, authentication is automatically reinitiated on the next reference to a protected transaction. Unless this authentication fails, the timeout will be transparent to the user. The NTLM challenge phrase lifetime is the same as the lifetime of the connection. If the TIP session times out, further attempts to access a protected transaction results in Web Transaction Server reinitiating the authentication procedure. References to static pages with expired Kerberos tickets or new or reopened NTLM-style connections, will also automatically reinitiate authentication and will be transparent to the user. The Kerberos/NTLM logon feature supports the same Security Default Definition mechanism as that provided by Secure Sessions logon. See Section 5 for details. 7850 4248 010 6 5

Kerberos/NTLM Sessions 6.5. Log-Off Processing A Kerberos/NTLM Session can be closed in the same way as standard Secure Sessions (see Section 5.5). 6.6. Mixed Kerberos/NTLM Sessions and Secure Sessions For simplicity of administration, it is usually best to select either Kerberos/NTLM sessions or Secure Sessions authentication for your entire network. Once authentication is done, both systems operate in the same way to provide transaction security. Transactions configured to require only Secure Sessions runs without challenge after Kerberos/NTLM authentication is completed. Similarly, transactions configured to require only Kerberos/NTLM runs without challenge after Secure Sessions authentication is completed. It is possible to configure a single transaction to require both types of security. This makes sense in networks were some users do not use Internet Explorer browsers. Using both authentication schemes might be appropriate where only part of the network has access to a Kerberos authentication service. Using only the NTLM support of Kerberos authentication might also be an alternative. If Internet Explorer is unable to authenticate with Kerberos, it tries to authenticate with NTLM. The 2200 Kerberos Authentication Module also supports NTLM, so this works on a properly configured Windows network. There is no additional configuration required to specify NTLM-only authentication. Internet Explorer automatically tries to authenticate using the NTLM credentials for the domain the workstation is operating in. This might fail if the workstation and the server are in different domains with different sign-ons. In this case, Internet Explorer displays a Windows log-on window so the user can enter the correct user-id, sign-on and domain name for the target domain. 6 6 7850 4248 010

Kerberos/NTLM Sessions 6.7. Web Enabler for Display Processing System Considerations Except for the fact that a Kerberos/NTLM Session does not use log-on screens, the same considerations that apply to Secure Sessions also apply to Kerberos/NTLM sessions (see Section 5.6). 6.8. Systems That Do Not Support TIP Session Control Kerberos/NTLM authentication of transactions requires that TIP session control on the system enforce the file access protection authenticated by this mechanism. Page access protection does not use TIP Session control and can be used on non-tip session control systems. 6.9. Kerberos/NTLM Sessions Log Entries The Kerberos/NTLM Session logging policy is the same as for standard Secure Sessions (see Section 5.9). 7850 4248 010 6 7

Kerberos/NTLM Sessions 6 8 7850 4248 010

Section 7 CGI Routines TIP and HVTIP OS 2200 Series transactions written in ASCII COBOL, UCS C or UCS COBOL can be called using a special Web Transaction Server interface based on the Web-standard Common Gateway Interface (CGI). This implementation is a high-performance interface. The COBOL CGI interface has enhanced capabilities including the automatic formatting of transaction output pages. Web Transaction Server reads standard browser transaction requests and extracts the information needed to schedule the target OS 2200 Series transaction. Input data supplied to the transaction and output message data (result data or output data) generated by the transaction must comply with HTTP standards in order to be properly displayed by a Web browser. The CGI standard governs the transfer of data between Web servers and executable programs. In the ClearPath IX and OS 2200 server s environment, CGI software routines are part of Web Transaction Server and provide library functions for the target transactions. The CGI routines included with Web Transaction Server simplify adapting transactions to the Web by providing a high-level language interface to the OS 2200 Series transaction system. This interface interacts with the MCB to handle Web messages and provides a variety of services to the transaction program including parsing HTTP headers to obtain input parameter values, cookies, and other Web message information. 7.1. CGI General Information A CGI routine performs the following actions: 1. It passes information received from Web Transaction Server to an TIP/HVTIP transaction in a form acceptable to the transaction. 2. After the transaction processes the data, it normally generates an HTML-formatted output message and transfers it to Web Transaction Server. The server returns the message back to a browser for display. CGI routines are called using a conventional URL in the following form: http://domainname/txn/aliasname/path-info?query-string See Section 3 for more details about using URLs to call CGI transactions. 7850 4248 010 7 1

CGI Routines The CGI interface is located between the MCB and the transaction in the Web Transaction Server environment (see Figure 7 1). The transaction uses the CGI routines to read the input URL and any parameters and header information associated with it. The transaction processes the data and then calls a CGI output routine to return HTML data back to the browser. Figure 7 1. COBOL Common Gateway Interface (CGI) The CGI mechanism provides a built-in page template mechanism that simplifies creating and processing Web compatible input and output. Both input and output for this mechanism are based on the template concept. This includes additional extensions to support HTML templates. HTML templates can be stored in a Web Transaction Server page file for use during input and output operations. The basic Web page HTML data is separated from the data that can change with each use. The transaction handles just the data in a page and the CGI facility coordinates with the corresponding page template. The developer designs the basic input and output HTML screens using a standard HTML authoring product. Some annotations are added during this process to indicate to Web Transaction Server where in the HTML form the input-variables are read from and where output variables are to be displayed. A CGI utility processes these HTML screens to generate a COBOL COPY PROC (or in the C language, an #INCLUDE file) that is used in the transaction program. Both the original HTML templates and the COPY PROCs are required to perform the CGI operation. Figure 7 2 shows a simplified view of these actions. 7 2 7850 4248 010

CGI Routines Annotated HTML Form CGI-COBCGI Utility HTML form is annotated using standard HTML authoring tools to mark variables to be read. CGI Utility provides a COBOL COPY PROC from this information. COBOL COPY PROC Figure 7 2. HTML Preprocessing The following table summarizes the key CGI routines: Routine Name CGIInit CGIRead CGIGetVar CGIGetFieldValue CGISend CGIGetPID Description Initializes CGI routines for a transaction. Reads the input message (HTTP header, URL, and so forth). Retrieves the following CGI environmental variables, including AUTH_TYPE CONTENT_LENGTH CONTENT_TYPE GATEWAY_INTERFACE HTTP_variable PATH_INFO QUERY_STRING REMOTE_ADDR REMOTE_HOST REQUEST_METHOD SCRIPT_NAME SERVER_NAME SERVER_PORT SERVER_PROTOCOL SERVER_SOFTWARE. Retrieves the field/value pairs for input parameters. Sends output message from transaction. Obtains the 2200 Series PID value in use for this transaction. 7850 4248 010 7 3

CGI Routines A transaction can generate a message in several different formats and types of output applicable to the CGISend routine. See Section 4.5 for more information on MIME types. Following are some of the formats and types of output supported: Plain text HTML Unformatted message of ASCII characters (MIME type=text/plain). ASCII characters in HTML format (MIME type=text/html). Parsed headers A message in which the HTTP header parameters and the output message body (content) can be set. Nonparsed headers Complete HTTP-formatted message including header and body. Web Transaction Server does not change the message before sending it to the browser. 7 4 7850 4248 010

CGI Routines 7.2. Topic Overview The CGI routines described in the following subsections are included with Web Transaction Server and installed as a subsystem. An object module version of the CGI subsystem is installed with Web Transaction Server into element SYS$LIB$*WEBTS.CGI/MCB-OM. The CGI-C/H and WTS-PARAMS elements are installed with Web Transaction Server into the SYS$LIB$*PROC$ system file so that they are easily accessible by the transactions. The SYS$LIB$*PROC$ file is created and maintained by COMUS to contain system procedures that the compiler references to satisfy COPY requests. If this file is not assigned, the compiler dynamically assigns it. The following topics are discussed in this section: COBOL Interface CGI Routines CGI$INIT (see Section 7.4.1) CGI$OPEN (see Section 7.4.2) CGI$GETVAR (see Section 7.4.3) CGI$GETFIELDVALUE (see Section 7.4.4) CGI$SENDBUFR (see Section 7.4.5) CGI$TERM (see Section 7.4.6) CGI$COMMIT (see Section 7.4.7) CGI$ROLLBACK (see Section 7.4.8) CGI$GETAUXSTATUS (see Section 7.4.9) CGI$GETPID (see Section 7.4.10) CGI$PASSOFF (see Section 7.4.11) CGI$GETCONTENT (see Section 7.4.12) CGI$SETNODE (see Section 7.4.13) CGI$SETDEBUG (see Section 7.4.14) CGI$CCS2CCS (see Section 7.4.15) CGI$LOGOFF(see Section 7.4.16) Input from an HTML Document CPYGEN Processor (see Section 7.5.1) CGI$GETFORM (see Section 7.5.2) Output to an HTML Document Substitution List (see Section 7.6.1) Include Directive (#include) (see Section 7.6.2) CGI$SENDHTML (see Section 7.6.3) C Interface CGI Routines CGIInit (see Section 7.7.1) CGIRead (see Section 7.7.2) CGIGetVar (see Section 7.7.3) CGIGetFieldValue (see Section 7.7.4) CGIGetOutBufr (see Section 7.7.5) CGISend (see Section 7.7.6) 7850 4248 010 7 5

CGI Routines CGITerm (see Section 7.7.7) CGICommit (see Section 7.7.8) CGIRollback (see Section 7.7.9) CGIGetAuxStatus (see Section 7.7.10) CGIGetPID (see Section 7.7.11) CGIGetBodyPtr (see Section 7.7.12) CGILogoff (see Section 7.7.13) Environmental variables (see Section 7.8) Static Linking of CGI Transaction Programs (see Section 7.9) Collecting ASCII COBOL CGI Transaction Programs (see Section 7.10) CGI Example Program (see Section 7.11) 7.3. CGI Advisory When Web-enabling 2200 transactions using the CGI feature, do not include self-replacing Java Scripts in the HTML pages that are to be served by the CGI routines. Web Transaction Server CGI uses a "document.write" function to perform the substitution replacement. If an HTML page also contains a "document.write" function, a race condition can occur that some Web browsers cannot be able to properly process. 7.4. COBOL Interface CGI Routines Most of the routines can be divided into the following five categories, listed in the order in which a typical transaction program would use them: 1. Initialization Performed by CGI$INIT. 2. Obtaining the first or next message Performed by CGI$OPEN. A call to CGI$OPEN makes the message available for processing by the other CGI routines. 3. Retrieving message content Performed by CGI$GETVAR, CGI$GETFIELDVALUE, CGI$GETPID, CGI$GETCONTENT, and CGI$GETFORM. 4. Sending a response to the client Performed by CGI$SENDBUFR and CGI$SENDHTML. 5. Termination Performed by CGI$TERM. The calling sequence for ASCII COBOL is identical to that for UCS COBOL, except that CGI routine entry-point names longer than 12 characters are truncated to 12 characters for the CGI$GETFIELD, CGI$GETAUXST, and CGI$GETCONTE routines. Note: These COBOL routines can also be called from the C language. The definitions required to call the routines from C are in the CGI-C/H element located in the SYS$LIB$*PROC$ system file. The uppercase parameters beginning with the letters WTS are defined in the PROC named WTS-PARAMS for UCS COBOL and WTS-PARAMS-ACOB for ASCII COBOL located in the file named SYS$LIB$*PROC$. This file is created and maintained by COMUS and contains the system procedures that the compiler references when it processes COPY requests. 7 6 7850 4248 010

CGI Routines Uppercase parameters with a limited set of defined values, such as WTS-STATUS, are defined with condition-names (88-level entry) corresponding to the defined set of allowable values (88-level names begin with WTS-). All lowercase parameters represent variable values that must be defined. 7.4.1. CGI$INIT When a transaction is scheduled, it initially calls the CGI$INIT routine to initialize the work area. This must be the first routine called. Multiple INITAL transactions must call the CGI$INIT routine before entering the read loop. The following statement calls the CGI$INIT routine: CALL 'CGI$INIT' USING WTS-STATUS, WTS-WORK-AREA, WTS-TERMINATOR where: WTS-STATUS (status of the request) wts-good Normal status. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-TERMINATOR Indicates how the data strings that are passed to and received from the CGI routines are terminated. wts-nullterminated Strings are terminated by an ASCII null character (decimal 0). This is compatible with string termination in the C language. wts-blankfilled Strings are filled with blanks and the last nonblank character terminates the string. This is compatible with string termination in the COBOL language. In either case, there must be enough storage reserved for at least 1 character more than the maximum number of characters in the string so that you can store the null or blank termination character. 7850 4248 010 7 7

CGI Routines 7.4.2. CGI$OPEN To read a message sent from a client, a transaction calls the CGI$OPEN routine to read the input data from Web Transaction Server through MCB and pass it to the transaction. Multiple INITAL transactions must call the CGI$OPEN routine to obtain the next input message. The following statement calls the CGI$OPEN routine: CALL 'CGI$OPEN' USING WTS-STATUS, WTS-WORK-AREA where: WTS-STATUS (status of the request) wts-good Normal status. wts-nomsg No input message to retrieve. wts-inputerror An error occurred during an attempt to read the input message from MCB. wts-nothttp Input message is not from Web Transaction Server. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. 7 8 7850 4248 010

CGI Routines 7.4.3. CGI$GETVAR The CGI specification defines environment variable values that can be used to pass data between software components. With Web Transaction Server, the CGI routines use environment variables to pass information between Web Transaction Server and OS 2200 TIP/HVTIP transactions. The CGI$GETVAR routine requests the environment variable containing the desired data. A variable can contain multiple values, which are separated by commas. Note: A transaction that is started by a pass-off message cannot access the original HTTP-formatted input message from Web Transaction Server. Only the initial transaction can access the original HTTP-formatted input. The CGI$GETVAR routine parses the original HTTP-formatted input message. Therefore, it must not be called in a transaction that was started by a pass-off message. The following statement calls the CGI$GETVAR routine: CALL 'CGI$GETVAR' USING WTS-STATUS, WTS-WORK-AREA, WTS-VARIABLE, value buffer, WTS-VALUE-BUFFER-LENGTH where: WTS-STATUS (status of the request) wts-good Normal status. wts-notfound Variable not found. wts-buffertoosmall WTS-VALUE-BUFFER-LENGTH specifies a value too small to hold the environment variable. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-VARIABLE Buffer containing the name of the variable that contains the desired data. This data string is terminated by either a null or a single ASCII space, depending on the string termination (WTS-TERMINATOR) defined when the CGI$INIT routine was called (see Section 7.4.1). See Section 7.8 for a list of environment variables. 7850 4248 010 7 9

CGI Routines value-buffer Contains the value of the environment variable. The value is stored as ASCII characters. This data string is terminated either by a null character or it is filled with blanks, depending on the string termination (WTS-TERMINATOR) defined when the CGI$INIT routine is called (see Section 7.4.1). The length of the returned string is zero if the variable in the WTS-VARIABLE field does not exist for the current input message. WTS-VALUE-BUFFER-LENGTH Length in characters (bytes) of the value-buffer. See Section 7.8 for a description of the variables that can be requested with CGI$GETVAR. 7.4.4. CGI$GETFIELDVALUE Use the CGI$GETFIELDVALUE routine to read the variable values in the field/value pairs in an HTTP-formatted message input from Web Transaction Server. A variable can contain multiple values, which are separated by commas. Note: A transaction that is started by a pass-off message cannot access the original HTTP-formatted input message from Web Transaction Server. Only the initial transaction can access the original HTTP-formatted input. The CGI$GETFIELDVALUE routine parses the original HTTP-formatted input message. Therefore, it must not be called in a transaction that was started by a pass-off message. For UCS COBOL, the following statement calls the CGI$GETFIELDVALUE routine: CALL 'CGI$GETFIELDVALUE' USING WTS-STATUS, WTS-WORK-AREA, WTS-FIELD-NAME, value-buffer, WTS-VALUE-BUFFER-LENGTH For ASCII COBOL, the following statement calls the equivalent routine: CALL 'CGI$GETFIELD' USING WTS-STATUS, WTS-WORK-AREA, WTS-FIELD-NAME, value-buffer, WTS-VALUE-BUFFER-LENGTH where: WTS-STATUS (status of the request) wts-good Normal status. wts-notfound Name of the variable not found. 7 10 7850 4248 010

CGI Routines wts-buffertoosmall WTS-VALUE-BUFFER-LENGTH specifies a value too small to hold the name of the variable. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-FIELD-NAME Buffer containing the name of the variable that contains the desired data. This data string is terminated by either a null or a single ASCII space, depending on the string termination (WTS-TERMINATOR) defined when the CGI$INIT routine was called (see Section 7.4.1). value-buffer Contains the value of the environment variable. The value is stored as ASCII characters. This data string is terminated either by a null character or it is filled with blanks, depending on the string termination (WTS-TERMINATOR) defined when the CGI$INIT routine is called (see Section 7.4.1). The length of the returned string is zero if the variable in the WTS-FIELD-NAME field does not exist for the current input message. Current value of the variable. This value is stored as ASCII characters. This data string is either terminated by a null or is filled with blanks, depending on the string termination (WTS-TERMINATOR) defined when the CGI$INIT routine was called (see Section 7.4.1). WTS-VALUE-BUFFER-LENGTH Length in characters (bytes) of the value-buffer. All values are URL decoded. This CGI routine is available for both the GET and POST methods. 7850 4248 010 7 11

CGI Routines 7.4.5. CGI$SENDBUFR To transfer a message back to a client from an output buffer prepared by the transaction, a transaction calls the CGI$SENDBUFR routine. The following statement calls the CGI$SENDBUFR routine: CALL 'CGI$SENDBUFR' USING WTS-STATUS, WTS-WORK-AREA, output-buffer, WTS-OUTPUT-BUFFER-LENGTH, WTS-OUTPUT-TYPE where: WTS-STATUS (status of the request) wts-good Normal status. wts-senderror Error occurred during an attempt to send the response message. wts_outputtoolarge The output message length exceeds the default MCB maximum output message length (262,143 characters). You can configure the MCB to permit fewer characters in an output message (see MCB configuration parameter MAXMSGCHARS). If the output message length is greater than the MCB configured size, an MCB error occurs on the output. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. output-buffer Buffer containing the response. WTS-OUTOUT-BUFFER-LENGTH Length in characters (bytes) of the output-buffer. The maximum size of the output buffer is 262,143 bytes because of implementing the CGI routines with the MCB. WTS-OUTPUT-TYPE (types of output) wts-plaintext Unformatted message of ASCII characters. wts-html Formatted ASCII characters in HTML format. 7 12 7850 4248 010

CGI Routines wts-parsed Header This output can be used to add additional headers or replace standard headers in a message. wts-nonparsed Header Complete HTTP-formatted message including header and body. Web Transaction Server does not change the message before sending it to the client. wts-parsed HeaderClose Same as wts-parsedheader, except that a connection close occurs after the message is sent. wts-nonparsed HeaderClose Same as wts-nonparsedheader, except that a connection close occurs after the message is sent. See Section 4.5 for more information about types of output. 7.4.6. CGI$TERM When a transaction finishes using the CGI routines, it calls the CGI$TERM routine. The following statement calls the CGI$TERM routine: CALL 'CGI$TERM' USING WTS-STATUS, WTS-WORK-AREA where: WTS-STATUS (status of the request) wts-good Normal status. wts-termerror Error detected. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. Multiple INITAL transactions call this routine only when they want to terminate. 7850 4248 010 7 13

CGI Routines 7.4.7. CGI$COMMIT Transactions accessed by Web Transaction Server can run with OS 2200 integrated recovery software in place. If there is an error, the transaction must use the CGI integrated recovery routines (CGI$COMMIT and CGI$ROLLBACK) to recover the results generated by the transaction. Usually a resource manager like Universal Data System (UDS) and Open/OLTP Two-Phase Commit software commits the steps when those steps participate in global transactions. However, when the results generated by an integrated recovery transaction are not communicated to UDS, the transaction itself must independently commit the results of the transaction. See the Integrated Recovery Utility Operations Guide for more detailed information about system recovery. When a transaction commits the database and outputs message results generated by the transaction, the current step is terminated and the input message is released. Whether the current step is terminated or advanced is determined by the default program recover options in effect for the program step. Execute the following command to commit the results of a transaction: CALL 'CGI$COMMIT' USING WTS-STATUS, WTS-WORK-AREA where: WTS-STATUS (status of the request) wts-good Normal status. wts-commiterror Error detected. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. 7 14 7850 4248 010

CGI Routines 7.4.8. CGI$ROLLBACK Transactions accessed by Web Transaction Server can run with OS 2200 integrated recovery software in place. If there is an error, the transaction must use the CGI integrated recovery routines (CGI$COMMIT and CGI$ROLLBACK) to recover the results generated by the transaction. Usually a resource manager like Universal Data System (UDS) and Open/OLTP Two-Phase Commit software rolls back the steps when those steps participate in global transactions. However, when the results generated by an integrated recovery transaction are not communicated to UDS, the transaction itself must independently roll back the results of the transaction. See the Integrated Recovery Utility Operations Guide for more detailed information about system recovery. When a transaction commits the database and outputs message results generated by the transaction, the current step is terminated and the input message is released. Whether the current step is terminated or advanced is determined by the default program recovery options in effect for the program step. Execute the following command to roll back the results of a transaction: CALL 'CGI$ROLLBACK' USING WTS-STATUS, WTS-WORK-AREA where: WTS-STATUS (status of the request) wts-good Normal status. wts-rollbackerror Error detected. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. 7850 4248 010 7 15

CGI Routines 7.4.9. CGI$GETAUXSTATUS If a CGI routine returns an error status, there can be additional information available about the error. Currently, an MCB error code is returned. The error code is described in the MCB Programming Reference Manual. For UCS COBOL, the following statement calls the CGI$GETAUXSTATUS routine: CALL 'CGI$GETAUXSTATUS' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS For ASCII COBOL, the following statement calls the equivalent routine: CALL 'CGI$GETAUXST' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS where: WTS-STATUS (status of the request) wts-good Normal status. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-AUX-STATUS MCB error code. 7 16 7850 4248 010

CGI Routines 7.4.10. CGI$GETPID For Web Transaction Server, position identifier (PID) numbers are not associated with a client workstation. Instead, they are associated with a TCP connection. Therefore, the PID number is normally different for each message sent by a client workstation and is assigned by Web Transaction Server from a pool of PID numbers. The CGI$GETPID routine enables you to determine the PID number for the input message. The PID number is important because with it you can perform some MCB functions that are not specifically supported by the CGI routines. The following statement calls the CGI$GETPID routine: CALL 'CGI$GETPID' USING WTS-STATUS, WTS-WORK-AREA, WTS-PID, WTS-PID-STATE where: WTS-STATUS (status of the request) wts-good WTS-WORK-AREA Normal status. Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-PID Returns the PID number. WTS-PID-STATE Indicates the state of the PID in relation to previous transactions executed on the same workstation. wts-newpid A new PID was allocated to this transaction from the available set of pool PIDs maintained by Web Transaction Server. wts-oldpid The PID was inherited from a previous transaction executed on the same workstation. 7850 4248 010 7 17

CGI Routines 7.4.11. CGI$PASSOFF The CGI$PASSOFF routine enables a transaction to schedule another transaction. The calling program specifies the transaction code of the transaction to be scheduled. Note: A transaction that is started by a pass-off message cannot access the original HTTP-formatted input message from Web Transaction Server. Only the initial transaction can access the original HTTP-formatted input. The CGI$GETVAR and CGI$GETFIELDVALUE routines parse the original HTTP-formatted input message. Therefore, it must not be called in a transaction that was started by a pass-off message. The following statement calls the CGI$PASSOFF routine: CALL 'CGI$PASSOFF' USING WTS-STATUS, WTS-WORK-AREA, output-buffer, WTS-OUTPUT-BUFFER-LENGTH, WTS-TXN-CODE where: WTS-STATUS (status of the request) wts-good Normal status. wts-passofferror Error detected during an attempt to send the pass-off message. wts_outputtoolarge The output message length exceeds the default MCB maximum output message length (262,143 characters). You can configure the MCB to permit fewer characters in an output message (see MCB configuration parameter MAXMSGCHARS). If the output message length is greater than the MCB configured size, an MCB error occurs on the output. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. output-buffer Buffer containing the pass-off message. WTS-OUTPUT-BUFFER-LENGTH Length in characters (bytes) of the pass-off message. The maximum size of the output buffer is 262,143 bytes because of implementing the CGI routines with the MCB. 7 18 7850 4248 010

CGI Routines WTS-TXN-CODE Transaction code (ASCII) of the transaction to be scheduled. 7.4.12. CGI$GETCONTENT A transaction can examine the body of an HTTP-formatted message received from a client by obtaining a copy of the message using the CGI$GETCONTENT routine. If the transaction was started as a result of a pass-off message from another transaction, the CGI$GETCONTENT routine must be used to retrieve the pass-off message. For UCS COBOL, the following statement calls the CGI$GETCONTENT routine: CALL 'CGI$GETCONTENT' USING WTS-STATUS, WTS-WORK-AREA, input-buffer, WTS-INPUT-BUFFER-LENGTH, WTS-CONTENT-LENGTH For ASCII COBOL, the following statement calls the equivalent routine: CALL 'CGI$GETCONTE' USING WTS-STATUS, WTS-WORK-AREA, input-buffer, WTS-INPUT-BUFFER-LENGTH, WTS-CONTENT-LENGTH where: WTS-STATUS (status of the request) wts-good Normal status. wts-buffertoosmall WTS-VALUE-BUFFER-LENGTH specifies a value too small to hold the name of the variable. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. input-buffer Buffer containing the pass-off message. WTS-INPUT-BUFFER-LENGTH Length in characters (bytes) of the input buffer. WTS-CONTENT-LENGTH Number of characters returned to the calling transaction in the input-buffer. This value is returned by the CGI$GETCONTENT routine. 7850 4248 010 7 19

CGI Routines 7.4.13. CGI$SETNODE The CGI$SETNODE routine enables a transaction to retrieve an input message from a specific terminating node or priority in an input queue. You must call the CGI$SETNODE routine before calling the CGI$OPEN routine, which reads the input message (see Section 7.4.2). The following statement calls the CGI$SETNODE routine: CALL 'CGI$SETNODE' USING WTS-STATUS, WTS-WORK-AREA, WTS-INPUT-NODE, WTS-WAIT-TIME where: WTS-STATUS (status of the request) wts-good Normal status. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-INPUT-NODE Priority of the terminating node on the input queue tree. WTS-WAIT-TIME Time in seconds to wait for an input message to be read. The maximum value is 63. This parameter is used only if the program is executing in batch or demand mode. 7 20 7850 4248 010

CGI Routines 7.4.14. CGI$SETDEBUG The CGI$SETDEBUG routine enables you to print debug output with the CGI$GETFORM (see Section 7.5.2) and CGI$SENDHTML (see Section 7.6.3) routines. The CGI$SETDEBUG routine can be called anytime after the CGI$INIT routine is called (see Section 7.4.1). All debug output is printed on the print device set for the transaction in the validation table (VALTAB). If WTS-DEBUG-LEVEL... Then... Equals 0 Equals 1 Equals 2 Printing debug output is disabled. CGI$GETFORM prints the values of all entries in the INPUT PROC received from the Web. CGI$SENDHTML prints the values of all entries in the OUTPUT PROC sent to the Web. CGI$GETFORM prints the values of all entries in the INPUT PROC received from the Web. CGI$SENDHTML prints the values of all entries in the OUTPUT PROC sent to the Web. All CGI routines that call MCB print the MCB function code and the status returned on each MCB call. The following statement calls the CGI$SETDEBUG routine: CALL 'CGI$SETDEBUG' USING WTS-STATUS, WTS-WORK-AREA, WTS-DEBUG-LEVEL where: WTS-STATUS (status of the request) wts-good Normal status. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-DEBUG-LEVEL (value to be set) 0 1 Disable printing debug output. Enable printing debug output. 7850 4248 010 7 21

CGI Routines 7.4.15. CGI$CCS2CCS The CGI$CCS2CCS routine enables the transliteration from one coded character set to another during input and output. This routine must be called after CGI$INIT (see Section 7.4.1) or CGIInit (see Section 7.7.1). The following statement calls the CGI$CCS2CCS routine: CALL 'CGI$CCS2CCS' USING WTS-STATUS, WTS-WORK-AREA, WTS-INTERNAL-CCS, WTS-EXTERNAL-CCS where: WTS-STATUS (status of the request) wts-good Normal status. wts-xliterror An error occurred while attempting to create the conversion tables. Either WTS-INTERNAL-CCS or WTS-EXTERNAL-CCS is probably in error. In this case, calling CGI$GETAUXSTATUS retrieves the I18NLIB error status. WTS-WORK-AREA points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. WTS-INTERNAL-CCS The decimal number of the coded character set used by the transaction. This number is expressed as a string and is defined in the I18NLIB assistant documentation. For example, 1 indicates the ASCII coded character set. WTS-EXTERNAL-CCS The decimal number of the coded character set used by the Web client software (browser). This number is expressed as a string and is defined in the I18NLIB assistant documentation. Data input from the browser with CGI routines CGIGetFIeldValue, CGI$GETFIELDVALUE, or CGI$GETFORM is converted from the character set defined by WTS-EXTERNAL-CCS to the character set defined by WTS-INTERNAL-CCS. Data output with CGI routines CGISend, CGI$SENDBUFR, or CGI$SENDHTML is converted from the character set defined by WTS-INTERNAL-CCS to the character set defined by WTS-EXTERNAL-CCS. The transliteration can be canceled by calling CGI$CCS2CCS with WTS-INTERNAL-CCS equal to WTS-EXTERNAL-CCS, or by calling CGITerm or CGI$TERM. 7 22 7850 4248 010

CGI Routines 7.4.16. CGI$LOGOFF When a transaction is operating in a Secure Session and wants to close the session, it calls the CGI$LOGOFF routine. When the transaction returns an output message, Web Transaction Server terminates the Secure Session and sends the output message to the requester. The logoff is not performed until the send function is executed. The following statement calls the CGI$LOGOFF routine: CALL 'CGI$LOGOFF' USING WTS-STATUS, WTS-WORK-AREA where: WTS-STATUS (status of the request) wts-good Normal status. wts-termerror Error detected. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. 7850 4248 010 7 23

CGI Routines 7.5. Input from an HTML Document During input, transactions retrieve the data from each field displayed in an input HTML form. Following is an overview of the steps executed to read data from an HTML form and transform it into COBOL statements that are the input to a transaction: 1. A user generates an HTML input form and modifies it with an HTML editor. The Display Processing System Form Language Manipulation Utility (FLMU) can be used to generate HTML coding for existing Display Processing System forms. 2. The CPYGEN processor reads the input HTML source code and generates data definition statements that are copied into a COBOL program as a COBOL COPY PROC. The COPY PROC defines the COBOL structures. These structures hold each HTML input field value for use by the COBOL program. 3. The data definition statements are stored as an OS 2200 element and are the source data for the Procedure Definition Processor (PDP). 4. The PDP processes the data definition statements and generates a COBOL PROC. 5. The COBOL COPY statement copies the statements from the COBOL PROC into a COBOL source program. 6. The COBOL copy proc compiles the COBOL transaction program. 7.5.1. CPYGEN Processor The following statement calls the CPYGEN processor: @CPYGEN,options htmlfile.sielt/siver,outfile.soelt/sover,alias where: options O A Generates UCS COBOL working storage (default). COBOL data items are declared with the BINARY attribute. Generates ASCII COBOL working storage. COBOL data items are declared with the COMP attribute. htmlfile.sielt/siver The name of the OS 2200 element containing the HTML source code. Lines in the input HTML source cannot exceed 256 characters. Characters beyond the 256-character limit are ignored. This limitation exists because the UCS C library function currently used by CPYGEN to read the HTML input has an internal buffer that is limited to 256 characters per line. 7 24 7850 4248 010

CGI Routines outfile.soelt/sover alias The name of the OS 2200 element that contains the COBOL data definition statements. The name of the Web Transaction Server page alias that can be used to retrieve the HTML source when the transaction executes. You must be able to read the HTML source using the following URL: http://server-name/pages/alias/sielt.siver where server-name is the name used to reference the server running Web Transaction Server. Note: The CPYGEN processor generates a warning message if an output variable in the substitution list is declared with a replication count greater than 1 and an initial value is specified. ASCII COBOL does not allow a VALUE clause on a data item with an OCCURS clause. CPYGEN ignores the initial value specified in the substitution list and does not place a VALUE clause on a data item that requires an OCCURS clause. Process the COBOL data definition statements in outfile.soelt/sover with PDP and copy the COBOL statements into the COBOL source program with the COBOL COPY statement. CPYGEN creates two COBOL PROCS in the outfile.soelt/sover element: sielt-input and sielt-output. The INPUT PROC is used to input data from an HTML form. The OUTPUT PROC is used to transfer ASCII text into an HTML template (see Section 7.6). The input and output procedures have the following general structure, if sielt equals AFORM. AFORM-INPUT PROC. 01 AFORM-INPUT. 05 HEADER-AREA.... 05 CONTROL-AREA.... 05 DATA-AREA.... END 7850 4248 010 7 25

CGI Routines AFORM-OUTPUT PROC. 01 AFORM-OUTPUT. 05 HEADER-AREA.... 05 CONTROL-AREA.... 05 DATA-AREA.... END CPYGEN generates COBOL data structures for each input field in an HTML form defined with the following HTML tags and places the corresponding data items in the CONTROL-AREA and DATA-AREA group items: <INPUT> <SELECT> <OPTION> <TEXTAREA> A good reference site for HTML is http://www.w3c.org. Following is the segment of code produced in the CONTROL-AREA group item: 05 CONTROL-AREA 10 fieldname-cntrl. 15 CGI-USE.... 15 FIELD-COUNT PIC S9(10) BINARY VALUE 0. When the input field in an HTML form has only one value, the segment of code produced in the DATA-AREA group item has the following format: 10 fieldname PIC X(varsize) VALUE SPACES. 7 26 7850 4248 010

CGI Routines An input field in an HTML form sent by a browser can have multiple values. For example: In the HTML <SELECT> tag, the MULTIPLE attribute is set. This specifies that a user can make a selection from multiple values displayed in a pull-down menu on an HTML form. Each selection generates a separate name/value pair in the data received from the HTML form. In the HTML <INPUT> tag, the TYPE attribute is set to checkbox. This specifies that a user can make a selection from multiple values displayed in check boxes displayed in an HTML form. The check boxes might have the same name, but a different value is assigned to each box. Each selection generates a separate name/value pair in the data received from the HTML form. With multiple input values, the value in fieldname is indexed so that all the possible values are retrieved. The segment of code produced in the DATA-AREA group item has the following format: fieldname count 10 fieldname PIC X(varsize) VALUE SPACES OCCURS count TIMES INDEXED BY fieldname-index. The name of the HTML input field specified in the NAME=fieldname attribute in the HTML tag. The name of the input field can be a maximum of 24 characters. The name must follow the rules in the COBOL standard for identifier names, except that underscores in the HTML fieldname are converted to dashes in the COBOL PROCs. The number of possible selections (pull-down menu items, check boxes, and so forth) that are visible on the HTML form. 7850 4248 010 7 27

CGI Routines varsize The value of this field depends on the type of input field defined in the HTML tag, defined in the following table: Input type TEXT PASSWORD HIDDEN CHECKBOX RADIO TEXTAREA SELECT/OPTION Value of varsize Specified in the MAXLENGTH attribute. If no MAXLENGTH attribute is specified, the value in the SIZE attribute is used. If neither the MAXLENGTH nor the SIZE attribute is specified, a default length of 80 is used. The largest value of the VALUE attributes for all the HTML INPUT tags that have the same name (value of the NAME attribute is the same). There is no way to determine varsize using the standard HTML definition. In this case, the CPYGEN processor uses the value of the MAXLENGTH attribute in the HTML <TEXTAREA> tag. If the MAXLENGTH attribute is not specified, the arithmetic product of the value in the ROWS attribute and the value in the COLS attribute is used. If the MAXLENGTH attribute and the ROWS and COLS attributes are not specified, it is an error and the CPYGEN processor does not include the field in the PROC. The <SELECT> tag defines the name of the variable. Inside the <SELECT> tag, multiple <OPTION> tags define each menu choice. The varsize field is set to the length of the largest value that can be returned for the variable when the form is submitted. The length of each menu choice is determined from the length of the value of the VALUE attribute in the <OPTION> tag or the length of the contents of the <OPTION> tag, whichever is longest. Now, the varsize field is set to the length of the largest menu item defined in the <SELECT> tag. Example 1 (varsize is set to 7). In this case, KLMNOPQ is the longest field. <SELECT NAME="parm"> <OPTION VALUE="a">BC <OPTION VALUE="def">GHIJ <OPTION>KLMNOPQ </SELECT> Example 2 (varsize is set to 4): <SELECT NAME="month"> <OPTION>May <OPTION>June <OPTION>July </SELECT> 7.5.2. CGI$GETFORM The value of FIELD-COUNT and the value of fieldname in the fieldname-cntrl group item in the DATA-AREA group item are filled with data retrieved from the HTTP message with the CGI$GETFORM CGI routine. 7 28 7850 4248 010

CGI Routines The following statement calls the CGI$GETFORM routine: CALL 'CGI$GETFORM' USING WTS-STATUS, WTS-WORK-AREA, element-name where: WTS-STATUS (status of the request) wts-good Normal status. wts-structurecorrupt The structure referenced by element-name has been corrupted, possibly by being accidentally overwritten by the transaction program. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. element-name The name of the 01 level structure created by CPYGEN and copied (COPY PROC) into the program. After the CGI$GETFORM routine finishes processing, the value of FIELD-COUNT in each fieldname-cntrl group item contains the actual number of values set into each fieldname in the DATA-AREA group item. If fieldname... Then FIELD-COUNT... Is repeated Is not repeated Contains no value Can equal any value from zero to the number of times fieldname is repeated. Equals one when any value is found in fieldname. Equals zero. 7850 4248 010 7 29

CGI Routines 7.6. Output to an HTML Document During output, transactions transfer ASCII output data to a Web browser that inserts the data into the appropriate output-only fields in an output HTML form. The fields in the HTML form where the data is to be inserted are defined by substitution strings. A comment in the HTML document defines where data in the substitution strings appears in the HTML template. Similar to the input process, the CPYGEN processor creates COBOL data structures in the OUTPUT PROC for each variable in the substitution list. The CGI$SENDHTML CGI routine is used to send the HTML output document to the client workstation (see Section 7.6.3). To use the output process described in the following subsections, including sending an HTML document to a client workstation, the Web browser must support and have enabled Java language specified by the Sun Microsystems Java Development Kit (JDK) level 1.0 JavaScript language in Netscape Navigator level 2.0, commonly known as JavaScript 1.0 Microsoft Internet Explorer and most other Web browsers support this combination on the Microsoft Windows or Windows XP workstation. 7.6.1. Substitution List A comment in the HTML document defines the characteristics of the data. The substitution strings indicate the strings that have the actual output data substituted for them throughout the HTML template document. This comment must appear before the <HEAD> tag and has the following format: <--#WEBTS-SUBSTITUTION-LIST(delimiter) varname1(varsize1,repcount1,initialvalue1)=keystring1; varname2(varsize2,repcount2,initialvalue2)=keystring2;... --> where: delimiter A single character delimiting the string in the HTML document, which is replaced by the value in the varname field before the HTML document, is displayed on the client workstation. varname The name of the variable used by the COBOL program. All trailing spaces in the varname field are truncated as the substitution is made in an HTML document. 7 30 7850 4248 010

CGI Routines varsize repcount The maximum size of the variable value, in characters. The number of times this variable value will be replicated in the generated COBOL structure. If not specified, 1 is assumed. initialvalue The value that the variable is set to in the COBOL PROC. If not specified, ASCII spaces are assumed. Must be enclosed in double quotes. keystring The substitution string, when it is enclosed by the delimiter character, will be replaced by the value in the varname field wherever keystring occurs in the HTML document. Following is an example of what a substitution list might look like: <!--#WEBTS-SUBSTITUTION-LIST(^) lastname(11,1,"wilson")=lastname; firstname(1,1,"wilson")=firstname; address(3,5,home)=address; phone-1(1,3)=xxxx-1; phone-2(1,3)=xxxx-2; --> The CPYGEN processor creates COBOL data structures in the OUTPUT PROC for each variable in the substitution list and places the corresponding data items in the CONTROL-AREA group item. The segment of code produced follows: 10 varname-cntrl. 15 CGI-USE.... 15 FIELD-COUNT PIC S9(10) BINARY VALUE repcount. If the input field is not replicated, the segment of code produced in the DATA-AREA group item for each input field has the following format: 10 varname PIC X(varsize) VALUE SPACES. 7850 4248 010 7 31

CGI Routines When the field is replicated, the value in varname is indexed so that all possible values are used. The segment of code produced in the DATA-AREA group item for each input field has the following format: 10 varname PIC X(varsize) VALUE SPACES OCCURS count TIMES INDEXED BY varname-index. When the varname field is replicated, the first instance of keystring in the substitution list is replaced by the value in varname-1, the second instance of keystring is replaced by the value in varname-2, and so forth. When the number of keystring fields in the substitution list exceeds the number of varname fields, the values in the varname fields are used more than once. In other words, when the value in the last varname field listed is used, the next replication uses the value in the first varname field a second time. This sequence occurs when the last valid value indicated by the value in FIELD-COUNT is used. For each variable used, the value of FIELD-COUNT in the CONTROL-AREA group item is initially set to the number of times that the variable is replicated. This can be changed so that it equals the number of replications for which there are valid values. For the following discussion, the HTML document is named EXAMPLE1/HTML. Observe the substitution list. <HTML> <!--#WEBTS-SUBSTITUTION-LIST(_) firstname(32,1,"don")=name; --> <HEAD> <TITLE>Hello _name_ window</title> </HEAD> <BODY> <P>Hello _name_, welcome to the Web.</P> </BODY> </HTML> Using this substitution list, the CPYGEN processor produces the following OUTPUT PROC. All references to the string "_name_" are replaced by the current value of firstname before the HTML document is displayed on the client workstation by the Web browser. 7 32 7850 4248 010

CGI Routines EXAMPLE-OUTPUT PROC. 01 EXAMPLE-OUTPUT. 05 HEADER-AREA.... 05 CONTROL-AREA. 10 firstname-cntrl. 15 CGI-USE... 15 FIELD-COUNT PIC S9(10) BINARY VALUE 1. 05 DATA-AREA. 10 firstname PIC X(32) VALUE 'Don'. END Two adjacent delimiter characters indicate that the following commands control the generation of a portion of an output HTML document. The only commands currently defined are REPEAT and ENDREPEAT. The REPEAT command indicates the beginning of a portion of an HTML document that is to be repeated. The ENDREPEAT command indicates the end of the portion of an HTML document that is to be repeated. In this example, 2 delimiter characters ( ^^ ) indicate the beginning and end of a portion that is to be repeated. <!--^^REPEAT(count)-->... section of document to be repeated... <!--^^ENDREPEAT--> The count field in the REPEAT command defines the number of times that a part of the document is to be repeated. This number is based on the value of some variable in the transaction program. This capability is useful if the value in the count field references a keystring, as previously defined. Repeating sections of a document can be nested. If the value in the count field is zero, the section is skipped. The REPEAT and ENDREPREAT commands must be placed inside a comment element. The portion of the document to be repeated begins with the first character immediately following the end comment sequence ( --> ) of the REPEAT command. The last character of the portion to be repeated is the character immediately preceding the begin comment sequence ( <!-- ) of the ENDREPEAT command. 7850 4248 010 7 33

CGI Routines For the following discussion, the HTML document is named EXAMPLE2/HTML. Observe the substitution list. <HTML> <!--#WEBTS-SUBSTITUTION-LIST(~) repcount(32,1,"0")=count; names(32,5,)=firstname; site(10,1,"unisys")=site; --> <HEAD> <TITLE>Hello Window for ~count~ people.</title> </HEAD> <BODY> <!--~~REPEAT(~count~)--> <P>Hello ~firstname~, welcome to the Web at ~site~.</p> <!--~~ENDREPEAT--> </BODY> </HTML> Using this substitution list, the CPYGEN processor produces the following OUTPUT PROC: EXAMPLE2-OUTPUT PROC. 01 EXAMPLE2-OUTPUT. 05 HEADER-AREA.... 05 CONTROL-AREA. 10 repcount-cntrl. 15 CGI-USE.... 15 FIELD-COUNT PIC S9(10) BINARY VALUE 1. 10 names-cntrl. 15 CGI-USE.... 15 FIELD-COUNT PIC S9(10) BINARY VALUE 5. 10 site-cntrl. 15 CGI-USE.... 15 FIELD-COUNT PIC S9(10) VALUE 1. 7 34 7850 4248 010

CGI Routines 05 DATA-AREA. 10 repcount PIC X(32) VALUE '0'. 10 names PIC X(32) VALUE SPACES OCCURS 5 TIMES. 10 site PIC X(10) VALUE 'UNISYS'. Continuing this discussion, if the variable values are count='5' names(1)='don' names(2)='dave' names(3)='darrel' names(4)='tom' names(5)='elmer' site='unisys' then the HTML document sent to the client workstation Web browser is <HTML> <!--#WEBTS-SUBSTITUTION-LIST(~) repcount(32,1,"0")=count; names(32,5)=firstname; site(10,1,"unisys")=site; --> <HEAD> <TITLE>Hello Window for 5 people.</title> </HEAD> <BODY> <!--~~REPEAT(5)--> <P>Hello Don, welcome to the Web at UNISYS.</P> <P>Hello Dave, welcome to the Web at UNISYS.</P> <P>Hello Darrel, welcome to the Web at UNISYS.</P> <P>Hello Tom, welcome to the Web at UNISYS.</P> <P>Hello Elmer, welcome to the Web at UNISYS.</P> <!--~~ENDREPEAT--> </BODY> </HTML> Substituting for keystring fields and the processing of REPEAT and ENDREPEAT commands can begin following the <HEAD> tag in the HTML source element. 7850 4248 010 7 35

CGI Routines 7.6.2. Include Directive (#include) The #include directive commands the preprocessor to replace the #include control line with the contents of the specified file. The included text can be any text. It can also contain HTML tags that will be displayed properly. The include command can be called from anyplace in the output HTML. An included file can include another file (nested includes). An included file can also include a substitution assuming the substitution has a valid value in the substitution list and uses the same delimiter as the rest of the output HTML. The syntax of the include command has two different formats. One format specifies an absolute path for the file. The other format uses a relative path based upon the location of the output HTML file. Following is the format of the absolute path: <!--#include "/absolutepath/filename.extension"--> Following is the format of the relative path: <!--#include "relativepath/filename.extension"--> Following are some examples of relative paths: <!--#include "/net/header.html"--> If the file you want to include is named header.html and it is located in a page with an alias of /net, the preceding command includes the contents of the file. <!--#include "footer.txt"--> If you want to include a file named footer.txt and it is located in the page with the same alias as the output HTML, use the preceding command. <!--#include "xyz/test.htm"--> or <!--#include "/abc/xyz/test.htm"--> In this example, assume that the output HTML is located in a page with an alias of /abc and the file you want to include is located in a page with an alias of /abc/xyz. If the name of the file that you want to include is test.htm, you can use either of the preceding commands. 7 36 7850 4248 010

CGI Routines Notes: The included file can only be text. Binary includes are not possible. If a substitution is made, the new value cannot make a call to include a file. You must use both quotation marks when specifying the path and file name in the include command. The <!--#include must appear exactly as <!--#include or the file will not be included. Caution Web Transaction Server does not monitor how a file is included. It is possible to include files in an infinite loop as follows: 1. The output HTML includes file A 2. File A includes file B 3. File B includes file C 4. File C includes file A This sequence leads to a situation where a browser cannot respond. 7850 4248 010 7 37

CGI Routines 7.6.3. CGI$SENDHTML To send an HTML document to a client workstation using the process described in 7.6, use the CGI$SENDHTML CGI routine. The following statement calls the CGI$SENDHTML routine: CALL 'CGI$SENDHTML' USING WTS-STATUS, WTS-WORK-AREA, element-name, http-headers, WTS-HTTP-HEADERS-LENGTH where: WTS-STATUS (status of the request) wts-good Normal status. wts-senderror Detected an error during an attempt to send the response. wts-notfound HTML template could not be found. WTS-WORK-AREA Points to the work area used by the CGI routines. A pointer to this same WTS-WORK-AREA must be included each time a subsequent CGI routine is called. element-name Name of the 01 level structure created by CPYGEN and copied into the program. http-headers Buffer containing HTTP headers that are to be sent to the client as part of the response. Example headers are Status, Set-Cookie, and Pragma (see Section 4 for additional information). This header has the same format as the header for the wts-parsedheader output type used by the CGI$SENDBUFR CGI routine (see Section 7.4.5). If no headers need to be sent, set this parameter to zero. WTS-HTTP-HEADERS-LENGTH Length in characters of the HTTP-headers area. If no headers need to be sent, set this parameter to zero. 7 38 7850 4248 010

CGI Routines 7.7. C Interface CGI Routines The UCS C declarations for the CGI routines are contained in the CGI-C/H header element in the Web Transaction Server installation file named SYS$LIB$*WEBTS. See the Web Transaction Server Administration Guide. A sample transaction named WEBEDIT is supplied on the product installation tape in the SYS$LIB$*WEBTS.WEBEDIT file. This transaction uses the CGI routines. Use the sample static HTML page in the adminhelp file (WEBTS$*ADMINHELP.WEBEDIT/HTM) to call the WEBEDIT transaction. Use this transaction to become familiar with Web Transaction Server. It provides a way to read and write symbolic and omnibus elements to and from OS 2200 program files. You can also use the sample transaction to convert between symbolic and omnibus elements. Make sure that the transaction can access the program file. 7.7.1. CGIInit When a transaction is scheduled, it initially calls the CGI initiate (CGIInit) routine. This must be the first CGI routine called. The following statement calls the CGIInit routine: ws_status CGIInit(CGI_work_area *work_area) where: ws_status (status of the request) ws_good *work_area Normal status. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a subsequent CGI routine is called. 7850 4248 010 7 39

CGI Routines 7.7.2. CGIRead When a transaction is scheduled that requires data from Web Transaction Server, the transaction calls the CGIRead routine to read the data. The following statement calls the CGIRead routine: ws_status CGIRead(CGI_work_area *work_area) where: ws_status (status of the request) ws_good Normal status. ws_nomsg No input message to retrieve (Multiple-INITAL programs must terminate if they receive this status). ws_inputerror Indicates an error occurred during an attempt to read the input message. The exact MCB error can be retrieved with the routine described in Section 7.7.10. ws_nothttp *work_area Input message is not from *work_area Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. 7 40 7850 4248 010

CGI Routines 7.7.3. CGIGetVar The CGI specification defines environment variables that can be used to pass data between software components. In Web Transaction Server, the CGI routines use environment variables to pass information between Web Transaction Server and OS 2200 TIP/HVTIP transactions. Note: A transaction that is started by a pass-off message cannot access the original HTTP-formatted input message from Web Transaction Server. Only the initial transaction can access the original HTTP-formatted input. The CGIGetVar routine parses the original HTTP-formatted input message. Therefore, it must not be called in a transaction that was started by a pass-off message. The following statement calls the CGIGetVar routine: ws_status CGIGetVar(CGI_work_area *work_area, char *variable, char *value_buffer,int value_buffer_length) where: ws_status (status of the request) ws_good Normal status. ws_notfound Variable not found. ws_buffertoosmall *work_area value_buffer_length is too small to hold the environment variable. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. *variable Buffer containing the name of the variable that contains the desired data. The name is a null-terminated string. *value_buffer Current value of the environment variable. The value is stored as ASCII characters and is terminated with null characters. A zero in this field indicates a null or no value. A variable can contain multiple values separated by commas (, ). value_buffer_length Length in characters (bytes) of the char* value_buffer. 7850 4248 010 7 41

CGI Routines 7.7.4. CGIGetFieldValue Use the following statement to retrieve the field/value pairs: ws_status CGIGetFieldValue(CGI_work_area *work_area, char *field_name,char *value_buffer, int value_buffer_length) where: ws_status (status of the request) ws_good Normal status. ws_notfound Variable not found. ws_buffertoosmall *work_area value_buffer_length is too small to hold the environment variable. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. *field_name Points to a null-terminated string that specifies the CGI variable. This field contains the name of the variable. *value_buffer Current value of the variable. The value is stored as ASCII characters and is terminated with null characters. A variable can contain multiple values which are separated by commas (, ). value_buffer_length Length in characters of the *value_buffer. Note: A transaction that is started by a pass-off message cannot access the original HTTP-formatted input message from Web Transaction Server. Only the initial transaction can access the original HTTP-formatted input. The CGIGetFieldValue routine parses the original HTTP-formatted input message. Therefore, it must not be called in a transaction that was started by a pass-off message. 7 42 7850 4248 010

CGI Routines 7.7.5. CGIGetOutBufr Before a transaction can send a message back to a workstation client, it must acquire an output buffer where it can transfer the message data. Only one buffer can be acquired and it is released when either CGISend or CGITerm are called. To acquire an output buffer for transferring the message data, execute the following command: char * CGIGetOutBufr(CGI_work_area *work area, int length) where: CGIGetOutBufr Returns the address of the output buffer. If the value is null, a buffer could not be acquired. *work_area length 7.7.6. CGISend Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. Length in characters of the buffer that the transaction is trying to acquire. To transfer a message to the output buffer previously acquired by the transaction, execute the following command: ws_status CGISend(cgi_work_area *work_area, int output_type, int length) where: ws_status (status of the request) ws_good Normal status. ws_senderror Error occurred during an attempt to send a response message. The exact MCB error can be retrieved with the routine described in Section 7.7.10. 7850 4248 010 7 43

CGI Routines wts_outputtoolarge *work_area The output message length exceeds the default MCB maximum output message length (262,143 characters). You can configure the MCB to permit fewer characters in an output message (see MCB configuration parameter MAXMSGCHARS). If the output message length is greater than the MCB configured size, an MCB error occurs on the output. See ws_senderror described previously. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. output_type length Specifies the format of the output message. See Section 4.5 for a description of the output message format. ws_plaintext Unformatted message of ASCII characters. wts_html Formatted ASCII characters in HTML format. ws_parsed Header This output type can be used to add additional headers or replace standard headers in a message. See Section 4.5 for more information. ws_parsedheaderclose Same as ws_parsedheader, except a connection close occurs after the message is sent. ws_nonparsed Header Complete HTTP-formatted message including header and body. Web Transaction Server does not change the message before sending it to the client. ws_nonparsedheaderclose Same as ws_nonparsedheader, except a connection close occurs after the message is sent. Length in characters (bytes) of the message. 7 44 7850 4248 010

CGI Routines 7.7.7. CGITerm The maximum size of the output buffer is 262,143 bytes because of implementing the CGI routines with MCB. When a transaction finishes using the CGI routines, it executes the following command: ws_status CGITerm(CGI_work_area *work_area) where: ws_status (status of the request) ws_good Normal status. ws_termerror *work_area Error detected. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. 7850 4248 010 7 45

CGI Routines 7.7.8. CGICommit Transactions accessed by Web Transaction Server can run with OS 2200 integrated recovery software in place. If there is an error, the transaction must use the CGI integrated recovery routines to recover the results generated by the transaction. Usually a resource manager like Universal Data System (UDS) and Open/OLTP Two-Phase Commit software commits the steps when those steps participate in global transactions. However, when the results generated by an integrated recovery transaction are not communicated to UDS, the transaction itself must independently commit the results of the transaction. See the Integrated Recovery Utility Operations Guide for more detailed information about system recovery. When a transaction commits the database and outputs message results generated by the transaction, the current step is terminated and the input message is released. Whether the current step is terminated or advanced is determined by the default program recover options in effect for the program step. Execute the following command to commit the results: ws_status CGICommit(CGI_work_area *work_area) where: ws_status (status of the request) ws_good Normal status. ws_commiterror *work_area Error detected. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. 7 46 7850 4248 010

CGI Routines 7.7.9. CGIRollback Transactions accessed by Web Transaction Server can run with OS 2200 Integrated Recovery software in place. If there is an error, the transaction must use the CGI Integrated Recovery routines to recover the results generated by the transaction. Usually a resource manager like Universal Data System (UDS) and Open/OLTP Two-Phase Commit software rolls back the steps when those steps participate in global transactions. However, when the results generated by an Integrated Recovery transaction are not communicated to UDS, the transaction itself must independently roll back the results of the transaction. See the Integrated Recovery Utility Operations Guide for more detailed information about system recovery. When a transaction executes a rollback of the database updates generated by that transaction, the current step is terminated and the database updates are not applied (input message is released). The transaction must create an appropriate output error message. Whether the current step is resumed or terminated is determined by the default program recover options in effect for the program step. Execute the following command to roll back the results: ws_status CGIRollback(CGI_work_area *work_area) where: ws_status (status of the request) ws_good Normal status. ws_rollbackerror *work_area Error detected. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. 7850 4248 010 7 47

CGI Routines 7.7.10. CGIGetAuxStatus If a CGI routine returns an error status, there can be additional information available about the error. Currently, an MCB error code is returned. The error code is described in the MCB Programming Reference Manual. Execute the following routine to return an MCB error code: ws_auxstatus CGIGetAuxStatus(CGI_work_area *work_area) where: ws_auxstatus MCB error code. *work_area 7.7.11. CGIGetPID Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. For Web Transaction Server, PID numbers are not associated with a client workstation. Instead, they are associated with a TCP connection. Therefore, the PID number is normally different for each message sent by a client workstation. A PID number is assigned by Web Transaction Server from a pool of PID numbers. This routine enables you to determine the PID number for the input message. The PID number is important because with it you can perform some MCB functions that are not specifically supported by the CGI routines. Execute the following command to return a PID number: int CGIGetPID(CGI_work_area *work_area) where: CGIGetPID Returns the PID number. *work_area Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. 7 48 7850 4248 010

CGI Routines 7.7.12. CGIGetBodyPtr This routine enables you to read and examine the input message. To do this, you need to return a pointer to the message so that you can access the text in the message. Execute the following routine to return a pointer to the input message: char * CGIGetBodyPtr(CGI_work_area *work_area) where: CGIGetBodyPtr Points to the start of the message body. *work_area Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a CGI routine is called. Notes: This routine replaces the CGIGetBody routine, which is now obsolete. The CGIGetBody routine returned only the word portion of the character pointer, so the pointer returned might point to 1, 2, or 3 characters before the actual start of the message body. The CGIGetBody entry point still exists for compatibility. It is recommended that you use the new CGIGetBodyPtr routine instead of CGIGetBody. This routine should be used instead of CGIGetFieldValue. For performance reasons, CGIGetFieldValue modifies the body of the HTTP message when it is received from a client. Therefore, calling the CGIGetBody interface routine to examine the body of a message cannot be meaningful if it is called after CGIGetFieldValue. 7850 4248 010 7 49

CGI Routines 7.7.13. CGILogoff When a transaction is operating in a Secure Session and wants to close the session, it calls the CGILogoff routine. When the transaction returns an output message, Web Transaction Server terminates the Secure Session and sends the output message to the requester. The following statement calls the CGILogoff routine: ws_status CGILogoff(CGI_work_area *work_area) where: ws_status (status of the request) wts_good Normal status. wts-termerror *work_area Error detected. Points to the work area used by the CGI routines. A pointer to this same work_area must be included each time a subsequent CGI routine is called. 7.8. Environmental Variables This subsection contains a description of each of the environment variable values. These values are described in the HyperText Transfer Protocol Specification. AUTH_TYPE Defines authentication for external access requests. The value of this variable is acquired from the auth-scheme token in the request, if the URL requires authentication to make external access requests. Otherwise, the value is null. See 7.5 for additional information about decoding input data. CONTENT_LENGTH The size of the body part, if any, of the request is a string of decimal characters. If there is no body attached, an empty string is returned. CONTENT_TYPE Defines the Internet media type of the attached entity. The syntax is the same as that in the HTTP Content-Type header field. The type, subtype, and parameter attribute names are not case sensitive. Parameter values can be case sensitive. Media types and their use in HTTP are described in media types in the HyperText Transfer Protocol specification. 7 50 7850 4248 010

CGI Routines Following is an example: application/x-www-form-urlencoded GATEWAY_INTERFACE Specifies the version of the CGI specification that the server supports. This interface supports version 1.1. HTTP_variable text HTTP variable values with names beginning with "HTTP_" are used to retrieve header data read from the client. This format enables you to retrieve header data for headers that do not have standard environmental variables defined for them. The header designation (in other words, the variable text) must be provided in a special format to permit using these as parameters in functions like CGI$GETVAR in COBOL and CGIGetVar in C. To convert the header name to the appropriate format, make the following changes: Change all alphabetic characters to uppercase. Change all hyphens ( - ) to underscores( _ ). Prefix the header name with HTTP_. To retrieve the MIME-Version header from a message, use a CGIGetVar parameter of HTTP_MIME_VERSION. The availability and meaning of the field values returned for these variables can depend on the HTTP protocol level which can be determined by retrieving the SERVER_PROTOCOL environment variable. Note that this has no effect on the format of the actual headers passed between Web Transaction Server and the browser. PATH_INFO The part of the URL that follows the specification of the transaction program. In other words, the part that follows /txn/transaction-code. QUERY_STRING Information following the question mark (? ) in the URL. This can be the string of data that you are searching for. 7850 4248 010 7 51

CGI Routines REMOTE_ADDR IP address of the agent sending the request to the server. If the client workstation is connected directly to the ClearPath IX or OS 2200 server, the client Web browser and agent are the same and there is only one IP address involved with the input request. If the client workstation is connected through a Web service software agent, like America Online, then the client Web browser and agent are not the same and the IP address of the client Web browser is not necessarily the same as the IP address of the agent. REMOTE_HOST The fully qualified domain name of the agent sending the request, if remote lookup is enabled for the transaction. REQUEST_METHOD Defines the method that was used when the request was made. The HTTP request methods are described in the description of Method in the HyperText Transfer Protocol specification. SCRIPT_NAME Specifies the path for the transaction currently being executed. This is the string /txn/alias. SERVER_NAME Specifies the IP address of the server. SERVER_PORT Specifies the port on which this request was received. SERVER_PROTOCOL Specifies the name and version of HTTP used with this request. This variable is the same as the HTTP Version field in the HTTP Request headers including the format. The format is HTTP/version, where version is the version of HTTP. SERVER_SOFTWARE Specifies the name and version of the Web Transaction Server responding to the request and running the CGI routines. The format is WebTS/version, where version is the version of the Web Transaction Server responding to the request. 7 52 7850 4248 010

CGI Routines 7.9. Static Linking of CGI Transaction Programs You must link transactions that use integrated recovery application-group-dependent system software to the system software in the related application group. These transactions execute only within that application group. To link the transactions to the applicable application group, use a library search chain that accesses the application group. This ensures that the system uses the MCB interface software appropriate for that application group. Use the following statement to specify use of a library search chain: @USE LINK$PF,SYS$LIB$*APP$n where n represents the application group number. As an example, use the following runstream to statically link to application group 7: @USE LINK$PF,SYS$LIB$*APP$7. @LINK,S,qual*file.zoom INCLUDE YOUR*FILE.OM.. (@LINK commands). OUTPUT ZOOM @EOF where: qual*file.zoom User program to be produced by static linking, using the software in application group 7. YOUR*FILE.OM Your transaction program object module. 7850 4248 010 7 53

CGI Routines 7.10. Collecting ASCII COBOL CGI Transaction Programs Since the CGI routines use the MCB to access the transaction message, the collection of an ASCII COBOL transaction must include the relocatable element that defines the MCB entry points for the application group with which the transaction is associated. Typically, this element is located in the file SYS$*MCB and is named CBEP$$MCBx, where x is the application group number. Include this element in the collection using the IN collector directive. Existing ASCII COBOL programs using the MCB must already have the necessary directives in their collection runstreams. 7.11. CGI Examples This subsection describes how to execute sample CGI transactions that are included with Web Transaction Server. These two examples provide CGI transactions that customers can use to begin learning the capabilities and how to use Web Transaction Server. 7.11.1. Example 1 The WEBTS$*PRODDOC$ file is installed when Web Transaction Server is installed and contains an example UCS COBOL transaction program that uses the CGI (Common Gateway Interface). This transaction is executed by Web Transaction Server in response to an HTML form being submitted at a browser. The transaction creates an HTML response message which echoes the data submitted in the form. The WEBTS$*PRODDOC file contains the following elements used by the example: CGIEXAMFORM/HTM is the HTML form that displays the example transaction when the form is submitted. This form provides the input data to the transaction. The CPYGEN processor processes this element to create the CGIEXAMFORM-INPUT PROC used by the CGI transaction. CGIEXAMOUT/HTM is the HTML form that is the basis of the output from the transaction. This skeleton HTML form is filled with data from the input form. The CPYGEN processor processes this element to create the CGIEXAMOUT-OUTPUT PROC used by the CGI transaction. CGIEXAMTXN/TXT contains the code for the CGI transaction. CGIEXAMMAKE/TXT is a runstream which, when you modify it for your site, compiles, links, and registers the CGI example transaction with TIP. 7 54 7850 4248 010

CGI Routines To set up the CGI example on your system, perform the following steps: 1. Choose a transaction code and an application group where the example transaction runs. The MCB for the application group must have the extended mode interface enabled. The CGIEXAMFORM/HTM form assumes the transaction alias is cgiexample. 2. Set up the application group using the Administration program. The PIDs chosen must be configured in the MCB but not by any other product, including CMS 1100. 3. Set up the transaction alias cgiexample using the Administration program. Set the application group and transaction code to the values you have chosen. Set the Lookup Remote Host attribute to ON. Note: With the Lookup Remote Host attribute set to ON, Web Transaction Server can return the following error message: Transaction Not Available: Required domain name unavailable for scheduling transaction <txn name>. This error occurs if the domain name used in the transaction URL (in other words, http://domain-name/txn/...) is not listed with your Domain Name Server (DNS). In this case, you must set the Lookup Remote Host attribute to OFF in order to execute the CGIEXAMPLE transaction. Remote users might experience a similar problem if they are not using the same DNS that is local to the Web Transaction Server running the transaction. 4. Modify the CGIEXAMMAKE/TXT runstream to suit your configuration. In particular, the transaction code, VALTAB numbers, SUPUR file name and number, and application group will probably need to be modified. 5. Execute the modified CGIEXMMAKE/TXT runstream. This creates the PUBLIC-HTML*CGIEXAMPLE file. To start the example, enter http://your-servers-id/proddoc/cgiexamform.htm to execute the element in the PUBLIC-HTML*CGIEXAMPLE file. Submit the form and the transaction must execute and echo the data that was input from the HTML form. You must see the browser access http://your-servers-id/txn/cgiexample and your PC workstation s IP address and host name must appear in the Environmental Variable section of the form. 7850 4248 010 7 55

CGI Routines 7.11.2. Example 2 This example provides a sample CGI transaction for Web Transaction Server that customers can use as an example. The transaction is written in C and uses some of the basic functionality. One version of the example executes in a Secure Session and one does not. This CGI transaction is used as a log viewer. The transaction takes the input from one HTML page and creates another HTML page to display the information. It enables a client to view either the access or error log for a particular Web Transaction Server. The transaction also has the ability to specify a particular file-cycle, display particular entries from the log, and format the display of the log. See Example 7 1 for an example of a log viewer results window. Example 7 1. A Log Viewer Results Window 7 56 7850 4248 010

CGI Routines Before the results window is displayed, clients select the four items that they want displayed. Clients make these selections on the input page shown in Example 7 2. Example 7 2. An Error Log Window Following are the four items that you can select to be displayed: File Name Log file name. This will be different for every server. Therefore, you might need to make some alterations to allow the user to select the correct file name. Several file names are included to help you choose or add more. File-Cycle Log file-cycle. A client can currently choose a file-cycle from the current cycle to (-5). If you need more cycles, you can add them. Some file-cycles are included to help you understand how to add more. 7850 4248 010 7 57

CGI Routines Display Entries Log display format. A client can choose one of the following: No blank line between entries One blank line between entries One horizontal line between entries Formatted for a log analyzer You can also add to the choices. Entries from the log file to display. A client can choose the most recent 20, most recent 100, oldest 20, oldest 100, or all. After a client selects the information they want displayed, click on View Log to display the log results (see Example 7 1). This information is common to both the Secure Sessions and the non-secure version of the transaction. The Secure Session version includes additional information. Setting Up the Log Viewer Transaction for Non-Secure Sessions Before clients can select what to view or the results, they must first log in. If they log in successfully, the window in Example 7 2 is displayed and they can select the log they would like to view. If the log in is not successful, a message stating that the log in was rejected is displayed. The client can try to log in again, or quit. Perform the following steps to set up either version of the log viewer: 1. Log into Web Transaction Server through a demand session. 2. Use the @prt,t command to confirm that all of the following files, except cgi-c/h, are in webts$*proddoc. The file named cgi-c/h is in SYS$LIB$*WEBTS. log/h log/c The header file for the non-secure log viewer transaction. This file can be altered to change the heading on the output page of the transaction. The actual code behind the non-secure transaction. This file must provide a good base for alterations to use for your own transactions. This is also where options can be added so the client can choose different kinds of displays and different numbers of entries to display. 7 58 7850 4248 010

CGI Routines log/txt The runstream to set up the non-secure transaction. This might require some alteration to get the transaction to work with your specific configuration. log/htm This is the initial HTML page the client will see. Some alterations might be done here to add options for the user to choose different file names or cycles. secure-log/h Identical to log/h except for one difference that makes it usable with Secure Sessions. secure-log/c Identical to log/c, except that it calls secure-log/h instead of log/h. secure-log/txt The runstream that sets up a Secure Sessions version of the log viewer. It creates a different directory as well as a different transaction so you can have both the non-secure version and Secure Sessions version running at the same time. secure-log/htm Identical to log/htm except that it calls the Secure Sessions transaction instead of the non-secure version. logon1s/htm cgi-c/h This file is used only with the Secure Sessions version of the log viewer. When this file is used, it is the first HTML page a client sees. This is where clients log in. If they log in successfully, the secure-log.htm file is called. The logon1s/htm file can also help you understand Secure Sessions and can be altered to make your own logon pages. Provides the CGI functionality for your transactions. If you write a transaction in C, include this element from SYS$LIB$*WEBTS., but do NOT modify it. 3. Copy the files and modify them as needed. When you are sure that you have all the required files and that they have been copied from their original location, you can begin making changes. Copy the nine files from webts$*proddoc to webts$*sample. Perform all editing and other operations in webts$*sample so that you do not destroy the original copies in webts$*proddoc. Make the crucial changes first to get the transaction working, and then make more options or expand the example. We will set up the non-secure transaction first and then the Secure Sessions transaction, which is only slightly different. 7850 4248 010 7 59

CGI Routines a. Modify the log/txt file. There are five changes you might need to make. Before you begin, you need to know A usable VALTAB number for your transaction A Supur number for your transaction An Application Group If you are unfamiliar with these terms, please see your TIP administrator or system administrator. This part of the procedure refers to comment blocks. Comment blocks are any group of lines that all begin with "@. " and where the first two lines of the block have only "@. " on each line. This type of comment block is found only in the log/txt and secure-log/txt files. First Comment Block Find the first comment block in the log/txt file. The three lines following this comment block are @TIP$*TIPRUN$.SUPUR,PX DELETE ONLY LOG FROM 275 PACK 275 Change the two instances of 275 to the Supur number for your transaction. Second Comment Block Find the second comment block. The six lines following this comment block are @XQT,IUXMZ TIP$*TIPRUN$.VTBUTL *VALCHG M 215 ACT,LOG DEL *VALCHG M 215 ACT,LOG NAME,LOG RUN,4095 PRI,G PRG,2 OPT,KLP COP,30 STF,0 215 PRT,junkpr IND,NONE STA,IJKLMN PCT,8 REC,NONE AUD,0 LEV,1 Change the three instances of 215 to the VALTAB number for your transaction. Third Comment Block Find the third comment block. The line following this comment is @USE LINK$PF,SYS$LIB$*APP$1. Change the 1 at the end of this line to your Application Group number. 7 60 7850 4248 010

CGI Routines Fourth Comment Block Find the fourth comment block. The three lines following this comment block are @TIP$*TIPRUN$.SUPUR,PX PACK 275 COPY ONLY LOG FROM ZZZ TO 275 Change the two instances of 275 to the Supur number for your transaction. b. Modify the log/htm file This part of the procedure also refers to comment blocks. However, these comment blocks are different from the comment blocks in the log/txt file. These comment blocks begin with "<!--" and end with "-->". This type of comment blocks is found only in the log/htm and secure-log/htm files. First Comment Block This comment block is just before the select box for the file name of the log. There are six options in the selection box, three access logs and three error logs. The selection box might not require any alteration. The file name you need may already be there. If it is, go to the next step. Otherwise, there must be enough examples to add more file names if you need to. Or, you can modify a current option. Second Comment Block This comment block is just before the file-cycle selection box. A client can currently choose a file cycle from the current cycle to (-5). You might not need any more file cycles. If you do, there are enough examples so you can add more cycles. Third and Fourth Comment Blocks The third and fourth comment blocks are before the radio button group for the displays and the radio button group for the entries. These cannot be changed or added to without changing the code behind the actual program. Continue setting up the rest of the example and make additional changes when the transaction is running. 4. Start the runstream to set up the non-secure log viewer transaction. This runstream creates a public-html*log directory and places the required log/htm file in the directory. It also compiles the code and links the transaction. Type the following statement to start the runstream: @add webts$*sample.log/txt 5. Log on to the server running Web Transaction Server through the Administration program. From the main Administration window, click the Options button to display the Options window. 7850 4248 010 7 61

CGI Routines 6. On the Options window, click the AGs tab. Make sure the Application Group number you used in log/txt is still usable. 7. Click the Pages tab and a window like that in Example 7 3 is displayed. Click the Add button. The value in the Alias field is the name used to reference the page when you view it on a Web browser. For example, if the server name is server-name,, and the alias for the page is log, you would go to http://www.server-name.com/log/log.htm to access the page. The value in the 2200 File Name field must be public-html*log.. When the values are correct, click OK. Example 7 3. Options Window Pages Tab 7 62 7850 4248 010

CGI Routines 8. In the Options window, click the Txns tab and a window like that in Example 7 4 is displayed. Click the Add button. The value in the Alias field is the name the HTML page uses to find the transaction. The alias must be log.. The value in the Code field should also be log.. The value in the App field is the Application Group number. When the values are correct, click OK. Example 7 4. Options Window Txns Tab This completes setting up the non-secure log viewer transaction. Please make sure this version works before attempting to set up the Secure Sessions version. If the page is set up correctly, its location is: http://www.server-name.com/log/log.htm Depending on the security of the logs, this version will not display the log. However, if you receive the following message, the transaction is working: ERROR: Unable to open file name for viewing In this case, either the file name is incorrect or security will not allow viewing the logs without Secure Sessions. If you get this error, please try to set up the Secure Sessions of the log viewer to see if that resolves the problem. If not, double-check your file names. 7850 4248 010 7 63

CGI Routines Setting Up the Log Viewer Transaction for Secure Sessions Repeat the setup procedures described in steps 2 and 3 in 7.11.2, except modify the secure-log/txt and secure-log/htm files. You need a different VALTAB number, so that the non-secure version and the Secure Sessions version can run at the same time. 1. Start the runstream to set up the secure log viewer transaction. This runstream creates a public-html*secure-log directory and places the required secure-log/htm and logon1s/htm files in the directory. It also compiles the code and links the transaction. Type the following statement to start the runstream: @add webts$*sample.secure-log/txt 2. Log on to the server running Web Transaction Server through the Administration program. From the main Administration window, click the Options button to display the Options window. 3. In the Options window, click the AGs tab. Make sure the Application Group number used in secure-log/txt is still usable. 4. Click the Pages tab and a window like that in Example 7 3 is displayed. Click the Add button. The value in the Alias field is the name used to reference the page when you view it on a Web browser. Make sure that the alias for the Secure Session is different than it is for the non-secure session. For example, if the server name is server-name and the alias for the page is secure-log, you would go to http://www.server-name.com/secure-log/logon1s.htm to access the page. The value in the 2200 File Name field should be public-html*secure-log. When the values are correct, click OK. 5. In the Options window, click the Txns tab and a window like that in Example 7 4 is displayed. Click the Add button. The value in the Alias field is the name the HTML page uses to find the transaction. The alias should be seclog. The value in the Code field should also be seclog. The value in the App field is the Application Group number. The value in the Require Secure Session should be set to On. When the values are correct, click OK. 6. This completes setting up the Secure log viewer transaction. The Secure Sessions transaction must resolve any earlier errors. If not, double-check your user-id and password. Also, check the status of the ACR on the log files. If this does not resolve the error, run the entire setup again to make sure you did not miss a step. If the setup is correct, the page must be at http://www.server-name.com/secure-log/logon1s.htm 7 64 7850 4248 010

CGI Routines Using the Log Analyzer If you would like the output of the transaction to be used as input to a log analyzer, open up a Web browser and display the log. You can choose any file name, file cycle, or entry. Also, you must choose select Formatted for Log Analyzer on the window shown in Example 7 2. Then click View Log. To create a file that you can import into a log analyzer, perform the following steps: 1. Open up a text editor (for example, Notepad or Wordpad). 2. Make sure that the log is displayed in the browser. In the Edit menu on the browser, click Select All. 3. Click Copy in the Edit menu on the browser. 4. Return to the text editor. Click the Edit menu in the text editor and click Paste. 5. Save the file in the text editor as a text file. You can then import it into your log analyzer. 7850 4248 010 7 65

CGI Routines 7 66 7850 4248 010

Section 8 TransIT Open/OLTP Transactions With Web Transaction Server, you can execute OS 2200 TransIT Open/OLTP transactions from the Web. All existing Open/OLTP transactions can be used without modification. This includes transactions supported by the Open/OLTP Heritage Application Access (HAA) facility. Web Transaction Server includes software that serves as a gateway between the server and existing Open/OLTP transactions (OLTPTx gateway transaction). The OLTPTx software provides the gateway functionality only in the OS 2200 operating environment of a ClearPath IX server. 8.1. Topic Overview This section discusses the following topics: Processing dynamic pages with Open/OLTP transactions Setting up the OLTPTx Gateway Transaction Mapping between HTML-formatted data and Open/OLTP-formatted data Storing the output from the WebViewC compiler Input to a transaction Output from a transaction 7850 4248 010 8 1

TransIT Open/OLTP Transactions 8.2. Processing Dynamic Pages with Open/OLTP Transactions (txn Function) The txn function can schedule an Open/OLTP transaction to retrieve data stored in an OS 2200 application for output as a dynamic page. The param2 field is part of the url-path field described in Section 3 and contains data specific to Open/OLTP transactions. This data is the input service name for the OLTPTx transaction. A slash ( / ) must be the first character as follows: /path_info Corresponds to the CGI PATH_INFO environment variable. The OLTPTx gateway software can retrieve this value with the CGIGetVar routine described in Section 7.7.3. Following is an example of a txn function for scheduling a transaction alias: http://www.cpix22.unisys.com/txn/alias2/service 8 2 7850 4248 010

TransIT Open/OLTP Transactions 8.3. Setting Up the OLTPTx Gateway Transaction The OLTPTx transaction is a multiple INITAL transaction that must be linked at the site. In the following example, WWOLTP is the transaction code. Multiple transactions with different names can exist for different application groups or for the same application group. Note that the AUD number (audit trail number) is 0, but the transaction must specify use of the library search chain that accesses the application group in which the transaction executes. The record specifier (REC) option Y must be supplied to imply commit at step terminate so that the transaction functions as a multiple-initial transaction. @. @ASG,T yourtempfile.,f///1000 @BRKPT PRINT$/yourtempfile @ASG,A TIP$*TIPRUN$. @. @. SET UP THE VALTAB @. @XQT,IUXMZ TIP$*TIPRUN$.VTBUTL *VALCHG M yourprogramnumber ACT,wwoltp NAME,wwoltp RUN,4095 PRI,G PRG,2 OPT,KLP yourprogramnumber COP,5 STF,0 PRT,pr3 IND,NONE STA,IJKLMN PCT,8 REC,Y yourprogramnumber AUD,0 LEV,1 @EOF @. @. CREATE THE OBJECT MODULE @. @USE LINK$PF,sys$lib$*app$1. @USE TM$LIB,otm$*tm$lib. @LINK,s,yourfile.wwoltp INCLUDE sys$lib$*webts.wwoltp/om INCLUDE otm$*tm$util.ap$name/o RESOLVE ALL REFERENCES USING TM$LIB,LCN OUTPUT ZOOM @EOF @. @. COPY THE ZOOM TO YOUR SUPUR FILE @. @TIP$*TIPRUN$.SUPUR,PX PACK yoursupurfilenumber COPY ONLY wwoltp FROM yourfile TO yoursupurfilenumber EXIT @. @. OPTIONALLY MAKE RTPS--IT IS MULTI-INITAL @. @BRKPT PRINT$ 7850 4248 010 8 3

TransIT Open/OLTP Transactions The system administrator must define an alias so that the WWOLTP transaction can be scheduled from the server. See the Web Transaction Server Administration Guide for additional information about aliases. 8.4. Mapping Between HTML-Formatted Data and Open/OLTP Formatted-Data The url-path field in a uniform resource locator (URL) received by the Web Transaction Server that targets an Open/OLTP transaction has the following format: /txn/oltptx/servicename where: OLTPTx Specifies the transaction code alias set up by the site to process Open/OLTP transactions. The system administrator must define an alias for each transaction that you want to call. The alias is how a transaction is referenced in the URL information that is passed from the Web browser to the Web Transaction Server. See the Web Transaction Server Administration Guide for additional information. servicename Name of the Open/OLTP transaction service to initiate. The HTML-formatted data received from a URL must be translated into a format the Open/OLTP transaction can use before it is transferred into an Open/OLTP buffer. For the translations to work, the OLTPTx gateway software must know how to map the field names in the HTML form to the fields in the Open/OLTP buffer. The definition of the format (rules for translation) of the data in the Open/OLTP buffers is contained in an Open/OLTP VIEW buffer definition. The WebViewC compiler uses the rules in the Open/OLTP VIEW buffer definition to set up the structure for controlling the mapping between the HTML-formatted data and the Open/OLTP-formatted data. The output from the WebViewC compiler is an omnibus element (binary data) named viewname/wv and optionally an element containing an HTML document (template) named viewname/html, as follows: The omnibus element is a representation of the Open/OLTP VIEW buffer definition containing the structure names and type, their location and length in the Open/OLTP buffer, and the default view values. The optional element is an HTML template that can be used to display the contents of the Open/OLTP buffer according to the rules in the VIEW buffer definition. All field names defined in the HTML form must match the name of a structure defined in the VIEW buffer definition in order for the data in the field to be supplied to an Open/OLTP transaction or returned from an Open/OLTP transaction. For a detailed explanation of a VIEW definition and buffer subtypes, see the Open Distributed Transaction Processing Programming Guide. 8 4 7850 4248 010

TransIT Open/OLTP Transactions The following are valid buffer types: X_C_TYPE X_C_COMMON VIEW Call the WebViewC compiler with the following statement: @webviewc[,h] inputfile.elt [outputfile] where: inputfile.elt Name of the element containing the Open/OLTP VIEW buffer definition. outputfile Name of the OS 2200 program file (WEBTS$*VIEWFILE) where the output elements are stored. Output consists of an omnibus element (binary data) named viewname/wv and, if you select the h option, an element named viewname/html containing an HTML document (template). The HTML template is created in an element named viewname/html and can be used as an input form. This template consists of the name of each field followed by the value in the field. You can modify the data in the viewname/html element to produce a more elaborate template. Following is an example of a VIEW buffer definition: VIEW employee #type cname fbname count flag size null #----- ------ ------- ------ ----- ----- ----- char last_name Last-Name 30 T - - char first_name First-Name 30 T - - char mi Middle-Initial 1 - - - int emp_no Employee-no 1 - - - string ssno SSN 1-12 "000-00-0000" string anniv_date Anniv-date 1-9 - short plant Plant 1 - - - float pay Pay 2 - - - END 7850 4248 010 8 5

TransIT Open/OLTP Transactions Using the WebViewC compiler, the previous VIEW buffer definition would be converted into the following HTML template: <HTML> <HEAD> <TITLE>employee</TITLE> </HEAD> <BODY> <FORM METHOD=POST ACTION="/txn/OLTPTx/servicename"> <INPUT TYPE=HIDDEN NAME="View" VALUE="employee"> <PRE> Last-Name <INPUT SIZE=30 NAME=Last-Name VALUE=" "> First-Name <INPUT SIZE=30 NAME=First-Name VALUE=" "> Middle-Initial <INPUT SIZE=1 NAME=Middle-Initial VALUE=" "> Employee-no <INPUT SIZE=10 NAME=Employee-no VALUE="-"> SSN <INPUT SIZE=12 NAME=SSN VALUE="000-00-0000"> Anniv-date <INPUT SIZE=9 NAME=Anniv-date VALUE=" "> Plant <INPUT SIZE=5 NAME=Plant VALUE="-"> Pay <INPUT SIZE=20 NAME=Pay VALUE="-"> </PRE> <CENTER><INPUT TYPE=SUBMIT VALUE=Transmit></CENTER> </FORM> </BODY> </HTML> The values in the fbname column in the VIEW buffer definition become the name of the input field in the HTML template, for example, Last-Name, First-Name, or SSN. 8 6 7850 4248 010

TransIT Open/OLTP Transactions 8.5. Storing Output from the WebViewC Compiler The output from the WebViewC compiler is stored in an OS 2200 program file named WEBTS$*VIEWFILE. The site administrator must catalog this file with system-low security attributes so that the OLTPTx gateway software can assign it. See the Web Transaction Server Administration Guide for additional information. Since the WEBTS$*VIEWFILE file is assigned by the OLTPTx gateway software, it might not be possible to have exclusive use of the file while scheduling Open/OLTP transactions. To copy elements to a file without having the file exclusively assigned, use the xcopy utility. Call the xcopy program with the following statement: @file.xcopy,options source.elt,destination.elt where: @file xcopy File where Web Transaction Server is installed, typically SYS$LIB$*WEBTS. Program name. options source.elt, destination.elt Same as for the FURPUR COPY command (see the ECL and FURPUR Reference Manual). 8.6. Input to a Transaction To initiate an Open/OLTP transaction, Web Transaction Server receives input data in HTML format in an HTML input element. The data must be translated into a format an Open/OLTP transaction can use. To translate input data, the OLTPTx gateway software maps the field names defined in the HTML input element to the structure names defined in the viewname/wv element and places the field values in the Open/OLTP buffer. The appropriate Open/OLTP transaction is then called with the tpcall() function. An HTML element identifies a specific part of an object and can specify many different things. HTML elements have optional or required attributes that can be used to specify the exact meaning and use of the data. The element and attribute names are case insensitive while the values assigned to the attributes are normally case sensitive. 7850 4248 010 8 7

TransIT Open/OLTP Transactions Following is the format of the data and the attributes and respective values in an HTML input element: <INPUT TYPE=HIDDEN NAME=View VALUE=viewname> where: TYPE NAME HIDDEN (commonly used to store information in a field that is used for processing and must not be changed). View. VALUE viewname is the same as the subtype of the buffer supplied to an Open/OLTP transaction. The hidden field NAME=TYPE is optional and specifies the type of buffer to be passed to the Open/OLTP transaction. If this attribute is not used, the type of buffer defaults to "X_C_TYPE. " The hidden field <INPUT TYPE=HIDDEN NAME=SPACEFILL VALUE=ON> might be used for UCOB services. This causes the character arrays in an OLTP buffer to be filled with spaces, rather than terminated with null characters. It also terminates the value with null characters when inserting it into the HTML template. The hidden field <INPUT TYPE=HIDDEN NAME=DEBUG VALUE=ON> can be used to command the OLTPTx gateway software to print an error message if an error occurs while processing a request to schedule Open/OLTP transactions. Use this only during development and testing, because it creates a print file each time an Open/OLTP transaction is scheduled which severely impacts transaction throughput. 8.7. Output from a Transaction When the Open/OLTP transaction finishes processing the input data, the output message (result) is placed in an Open/OLTP output buffer. The OLTPTx gateway software reads the output viewname/wv and viewname/html elements and translates the data from the Open/OLTP output buffer into an HTML formatted message so that it can be returned to the Web browser. 8 8 7850 4248 010

Section 9 Web-Enabling Enterprise Application Environment Applications At least four options exist for Web-enabling Enterprise Application Environment applications: Internet Commerce Enabler Graphical Interface Workbench Web Transaction Server Transaction Integrator The following URL contains information about each option: http://www.support.unisys.com/2200/webts/marketplace.html Each option has advantages and disadvantages. The combination of Web Transaction Server and Enterprise Application Environment subroutines might not be the best choice for Web-enabling your Enterprise Application Environment applications. Web Transaction Server provides the interface to the browser and controls the scheduling of a selected transaction for a Web request. Web Transaction Server supports both static and dynamic Web pages. The static Web pages can be used for welcome pages, manuals, procedures, phone lists, and so forth. The dynamic pages are used to insert data from an application into a Web page. The data usually depends on input from a user. Web pages must conform to HTTP 1.0 rules so they can be developed using any popular Web authoring tool, for example, Microsoft FrontPage. The Enterprise Application Environment subroutine provides the required access to the Enterprise Application Environment application. A Enterprise Application Environment subroutine is an encapsulated object that maintains business rules and data access. Once generated, the Enterprise Application Environment subroutine object can be called from any program that is connected to the same application group. This can be an Ispec or Report in the same Enterprise Application Environment system or another Enterprise Application Environment system, a non-enterprise Application Environment HVTIP or TIP transaction, or a non-enterprise Application Environment batch program. Information on Enterprise Application Environment subroutines can be found in the Enterprise Application Runtime for ClearPath OS 2200 Administration Guide. 7850 4248 010 9 1

Web-Enabling Enterprise Application Environment Applications Web Transaction Server and Enterprise Application Environment subroutines provide a flexible approach to Web-enabling a Enterprise Application Environment application. Multiple Enterprise Application Environment and non-enterprise Application Environment applications can be accessed from the same transaction. Web Transaction Server supports both static and dynamic pages, so supporting documents like procedures can be stored as static pages. Web Transaction Server is very scalable and secure. Enterprise Application Environment subroutines provide an encapsulated object that can be reused in many different places. Sites that already use Enterprise Application Environment subroutines might require no application changes to provide Web access. 9.1. Procedure You first need to develop a transaction that interfaces with Web Transaction Server. The transaction can be developed in COBOL or C and can be HVTIP or TIP. Web Transaction Server provides facilities to convert dynamic Web pages into COBOL copy procedures or C include files. Programmable interfaces to the CGI routines are available. These are similar to the Display Processing System programmable interfaces. The sample programs that come with Web Transaction Server can be used as a template for developing your own transactions. Once the basic Web program has been developed to read a Web page from a browser and send out a Web page (same HTML form or a different form), logic to access the application can be added. For Enterprise Application Environment applications, this is provided by a call to the appropriate Enterprise Application Environment subroutine. Enterprise Application Environment uses a single parameter, GLB.PARAM, for receiving data from the caller and returning data to the caller. See the Enterprise Application Runtime for ClearPath OS 2200 Administration Guide for more information. The layout of the GLB.PARAM parameter is often defined as an insertable GLG in Enterprise Application Environment. This is converted to a COBOL copy procedure or C include file for including in the Web transaction source. Before the call, the program moves the appropriate data to the parameter list using the copy procedure. After the call, the program accesses the parameter list using the copy procedure. If the transaction is developed as HVTIP, the program could also CANCEL the subroutine to release D-bank space. Many Enterprise Application Environment subroutines from the same or different Enterprise Application Environment applications can be called. There could also be calls to non-enterprise Application Environment subroutines. Eventually, the program constructs the Web page from the various data collected and then call a CGI routine to send the HTML form as output. 9 2 7850 4248 010

Web-Enabling Enterprise Application Environment Applications 9.2. Security Using a Enterprise Application Environment subroutine means that you can restrict the information that is returned to the calling Web transaction. The Web program can further restrict what is sent in the HTML form back to the user. Because Web Transaction Server supports cookies, some form of Web security can be implemented. Security requirements depend on the site s requirement. The site might only want to send data over the Web that does not have critical security requirements. For example, DHL and FedEx can provide the status of a shipment if you have the AWB number, but they do not include details such as contents or costs. Web Transaction Server supports two security mechanisms. Each mechanism is listed, along with a URL where you can get additional information. Secure Sockets Layer (SSL) http://www.cpix22.unisys.com/pages/adminhelp/tech1.htm#ssl Secure Sessions http://www.cpix22.unisys.com/pages/adminhelp/tech1.htm#securesessions For an overview of Web Transaction Server Security, see http://www.cpix22.unisys.com/pages/adminhelp/wtssecur.htm Further information regarding security can be found in the Web Transaction Server Administration Guide and in subsection 1.6 and Section 5 of this manual. 9.3. Prototype Unisys successfully developed a prototype based on Web Transaction Server and Enterprise Application Environment subroutines at a Enterprise Application Environment site. In a few days, an employee produced an operational Web transaction that called an existing Enterprise Application Environment subroutine. The employee had no previous experience with Web Transaction Server, HTML programming, or the use of any Web page authoring tool. The employee s experience related to 2200 technical skills plus writing 3GL transactions in COBOL/DPS over 10 years ago. A couple of Web transactions were developed in COBOL as HVTIP ICPs. The programs called an existing Enterprise Application Environment subroutine and sent out the results in different HTML forms. The Enterprise Application Environment subroutines were CANCELLED after each call, although this was not necessary. To design the Web page, a combination of Web authoring tools plus low-level HTML programming using the OS 2200-based IPF editor was used. 7850 4248 010 9 3

Web-Enabling Enterprise Application Environment Applications 9.4. Example Program The following example program was provided following the prototype. The source code can be downloaded from the Internet at http://www.support.unisys.com/2200/webts/examples/linc/wbm12.txt 9.4.1. Source Code Following is the source code: WebTS - LINC Example * -------------------- * * The following program was used to prototype how access to * LINC applications can be accomplished using WebTS. The main * component from the LINC system is the use of a LINC subroutine. * * The environment was a 2200/500 with 4 processors and 128MW * memory. SB6M1 was the SB release and CMS was used. LINC 16R2 * was used for the LINC applications. WebTS was level 1R2. This * was the free download from the Web. The prototype was conducted * during October-November, 1997. * * This program has been developed as a HVTIP ICP program but * it would only require a different set of LINK statements to * create a normal TIP transaction. * * Description: * The Web user, through a URL, is presented with a blank HTML * form. This form has 2 fields: * * 1. Currency code. * Input field for a currency code e.g. AUD, USD * 2. Currency code name. * Output field with the currency name e.g. Australian Dollar * * The same HTML form is used for input and output. * * The program will call the necessary CGI routines (from WebTS) * to initialise with MCB and get the input message which is the * HTML form buffer. * * Then the program retrieves the contents of the currency code * field from the HTML buffer using a CGI routine. The program * stores this code in a field that is part of the LINC subroutine * parameter area. * The program then calls the LINC subroutine, RFCUC0. Note that * this subroutine is currently used extensively in LINC * applications. 9 4 7850 4248 010

Web-Enabling Enterprise Application Environment Applications * NO CHANGES WERE MADE TO THE SUBROUTINE OR LINC APPLICATION. * * The LINC subroutine will return the results of the call in the * parameter area. The program checks the status of the call. If * successful, the name of the currency code is moved to the HTML * form buffer. * * The program then calls the necessary CGI routines to send the * form and terminate from MCB etc. * * Note that the LINC subroutine, RFCUC0, is a HVTIP library/bank. * Therefore changes to the subroutine can be made without change * or relink of this program provided the parameter list remains * the same. * * Caveat: * I think that further work needs to be done with this program * to ensure correct CGI initialisation and termination * processing occurs. The code in this program does not handle * all error situations correctly. However the program did work * as proof of concept. * IDENTIFICATION DIVISION. PROGRAM-ID. WBM12. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. UNISYS-2200. OBJECT-COMPUTER. UNISYS-2200. SPECIAL-NAMES. CONSOLE IS CONSOLE PRINTER IS PRT. DATA DIVISION. WORKING-STORAGE SECTION. COPY WTS-PARAMS. * * Insert the copy procs for the HTML forms. This is the output * of the CPYGEN processor. * COPY rtccuc-input. COPY rtccuc-output. * * Define some work fields * 01 subscript PIC S9(10). 01 textarea1-field PIC X(1000) VALUE SPACES. 01 scrtch PIC X(1000) VALUE SPACES. 01 cookie PIC X(1000) VALUE SPACES. 7850 4248 010 9 5

Web-Enabling Enterprise Application Environment Applications *============================================================ * Parameter interfaces to LINC subroutines follow *----------------------------------------------------------- * * RFCUC0 * ------ * Define buffer for the LINC subroutine: RFCUC0 * Ideally this would be another COBOL COPY proc. Would be * even better if LINC could create this from the insertable * global logic. * 01 sg-rfcucprm. 03 sa-cucsts pic x(5). 03 sa-cuc pic X(3). 03 sa-cucnme pic x(35). 03 sn-cucdtecte pic 9(8). 03 sa-cucmaint pic x(1). 03 sn-cuctemcte pic 9(8). 03 sn-cucuidcte pic x(6). 03 sn-cucdtestr pic 9(8). 03 sn-cucdtefin pic 9(8). 03 filler pic x(3924). * PROCEDURE DIVISION. BEGIN. * Initialise with CGI, set debug mode and get message * from input form. * Note: Some of the following CGI calls are not required but * are included for example only. Call 'CGI$INIT' USING WTS-STATUS, WTS-WORK-AREA, WTS-TERMINATOR. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$INIT bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT END-IF. MOVE 1 TO WTS-DEBUG-LEVEL. Call 'CGI$SETDEBUG' USING WTS-STATUS, WTS-WORK-AREA, WTS-DEBUG-LEVEL. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$SETDEBUG bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT END-IF. 9 6 7850 4248 010

Web-Enabling Enterprise Application Environment Applications MOVE 0 TO WTS-INPUT-NODE. MOVE 10 TO WTS-WAIT-TIME. Call 'CGI$SETNODE' USING WTS-STATUS, WTS-WORK-AREA, WTS-INPUT-NODE, WTS-WAIT-TIME. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$SETNODE bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT END-IF. Call 'CGI$OPEN' USING WTS-STATUS, WTS-WORK-AREA. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$OPEN bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT CALL 'CGI$GETAUXSTATUS' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS DISPLAY 'MCB Aux status = ' WTS-AUX-STATUS END-IF. MOVE 'REMOTE_ADDR' TO WTS-VARIABLE. MOVE 13 TO WTS-VALUE-BUFFER-LENGTH. CALL 'CGI$GETVAR' USING WTS-STATUS, WTS-WORK-AREA, WTS-VARIABLE, remoteaddr, WTS-VALUE-BUFFER-LENGTH. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$GETVAR bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT END-IF. MOVE 'REMOTE_HOST' TO WTS-VARIABLE. MOVE 100 TO WTS-VALUE-BUFFER-LENGTH. CALL 'CGI$GETVAR' USING WTS-STATUS, WTS-WORK-AREA, WTS-VARIABLE, remotehost, WTS-VALUE-BUFFER-LENGTH. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$GETVAR bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT END-IF. 7850 4248 010 9 7

Web-Enabling Enterprise Application Environment Applications * Here we prepare to call the LINC subroutine. Get the * necessary data from the input form and move to the LINC * subroutine parameter field. MOVE 'cuc' TO WTS-FIELD-NAME. MOVE 1000 TO WTS-VALUE-BUFFER-LENGTH. CALL 'CGI$GETFIELDVALUE' USING WTS-STATUS, WTS-WORK-AREA, WTS-FIELD-NAME, sa-cuc, WTS-VALUE-BUFFER-LENGTH. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$GETFIELDVALUE bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT END-IF. * We should really do some thread control stuff here. This * should be a begin thread to the correct application group. * It appears the LINC subroutine does the begin thread if not * performed before. * Now do the call to the LINC subroutine: RFCUC0. * Note that LINC subroutines only have one parameter which * has a length of GLB.PARAM in the LINC specification. * The LINC II Installation and Operations Guide has more * information describing LINC subroutines. MOVE SPACES TO SA-CUCSTS. CALL 'RFCUC0' USING SG-RFCUCPRM. * Note we could code a CANCEL 'RFCUC0' if we want to release * HVTIP dbank space. Probably only needed if calling a lot of * subroutines. HVTIP-II would avoid this. * Check the call result. If the status is not spaces then assume * the currency code was invalid. Otherwise move the name of the * currency code to the output HTML form buffer. IF SA-CUCSTS = SPACES MOVE SA-CUCNME TO cucnme-output ELSE MOVE '*** Invalid currency code ***' TO cucnme-output END-IF. MOVE sa-cuc TO cuc-output. * Now call the various CGI routines to send the output HTML * buffer to the user. 9 8 7850 4248 010

Web-Enabling Enterprise Application Environment Applications * Note: This area probably needs changes for better error * handling etc. Call 'CGI$SENDHTML' USING WTS-STATUS, WTS-WORK-AREA, rtccuc-output, WTS-HTTP-HEADERS-LENGTH. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$SENDHTML bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT CALL 'CGI$GETAUXSTATUS' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS DISPLAY 'MCB Aux status = ' WTS-AUX-STATUS END-IF. Call 'CGI$COMMIT' USING WTS-STATUS, WTS-WORK-AREA. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$COMMIT bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT CALL 'CGI$GETAUXSTATUS' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS DISPLAY 'MCB Aux status = ' WTS-AUX-STATUS END-IF. Call 'CGI$ROLLBACK' USING WTS-STATUS, WTS-WORK-AREA. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$ROLLBACK bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT CALL 'CGI$GETAUXSTATUS' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS DISPLAY 'MCB Aux status = ' WTS-AUX-STATUS END-IF. Call 'CGI$TERM' USING WTS-STATUS, WTS-WORK-AREA. IF wts-good THEN CONTINUE ELSE DISPLAY 'CGI$TERM bad status' UPON PRT DISPLAY WTS-STATUS UPON PRT CALL 'CGI$GETAUXSTATUS' USING WTS-STATUS, WTS-WORK-AREA, WTS-AUX-STATUS DISPLAY 'MCB Aux status = ' WTS-AUX-STATUS END-IF. STOP RUN. 7850 4248 010 9 9

Web-Enabling Enterprise Application Environment Applications 9.4.2. Defining the HVTIP Entry Points for the Enterprise Application Environment Subroutine The MASM routines that defines the HVTIP entry points for the Enterprise Application Environment subroutine might be downloaded from the Internet at http://www.support.unisys.com/2200/webts/examples/linc/wbm12lnk.txt @break @MASM,E linc*rob.hvcalls,tpf$.hvcalls @ucob,s w.wbm12,tpf$.wbm12om @LINK$.LINK,l,tpf$.wbm12 OUTPUT HVTIP INCLUDE tpf$.hvcalls INCLUDE tpf$.wbm12om SET MERGED_CODE_UL = 262000 MERGE ALL CODE BANKS INTO CODE_BANKS_GROUP AS WEB_CODE_BANK SET MERGE_ORDER = LAST FOR WEB_CODE_BANK RESOLVE ALL REFERENCES USING LOCAL_DEFS,LCN INDEX COMMON BANKS $BLANK$COMMON$ SET LOWADR = 0100000 FOR HVTIP$$DBANK SET SIZE = 130000 FOR HVTIP$$DBANK SET ALS_INIT_SIZE = 050000 DELETE ALL DEFINITIONS EXCEPT START$ @EOF @send,e 9.4.3. LINK Statements The LINK statements might be downloaded from the Internet at http://www.support.unisys.com/2200/webts/examples/linc/hvcalls.txt $INCLUDE 'MAXR$' $INCLUDE 'sys$*rlib$.cbep$$emcall' $INCLUDE 'OM$DEF' $INCLUDE 'SYS$LIB$*LINK.HVTIP$CALLS' $EXTEND $OBJ HV$CALL,1 52,9,0 'RFCUC0' $END 9 10 7850 4248 010

Glossary A addressing scheme The mapping of URIs onto existing standard or experimental protocols. The scheme is the first field in the browser's address or location line. Examples of addressing schemes are HTTP, FTP, MAILTO, and FILE. alias A symbolic name defined by a user that can be used in place of an OS 2200 transaction code. The alias can be the same as the transaction code or it can be different. Also, an alias can be used in place of a file name. A file alias is different from a transaction alias. C CERN CIFS client Abbreviation for Conseil Europeen pour la Recherche Nucleaire (European Laboratory for Particle Physics), the origin of the World Wide Web. CERN is where much of the original Web software was developed, including the first Web server and Web browser software. See Common Internet File System Typically, a desktop personal computer that communicates with other PCs, a server, or a host computer. CMS 1100 See Communications Management System (CMS 1100). commitment (X/Open) The event that ends a transaction and makes permanent all changes that were made to resources (such as databases) during that transaction. See also rollback. common gateway interface (CGI) (1) A standard that defines the mechanism by which Web server software communicates with executable programs on the Web server. This enables Web server software to call executables to help fulfill requests. (2) A standard that defines the use of environment variables set by a server program before it transfers data to an executable program. The environment variables are available to both the server program and the executable program and govern how data is transferred between the programs. 7850 4248 010 Glossary 1

Glossary Common Internet File System (CIFS) A standard remote file access system that enables transferring file structures between OS 2200 and IX servers and the Internet. Communications Management System (CMS 1100) The software that manages all data communications between the OS 2200 operating environment of a ClearPath IX server and application programs in a data communications network. The Transport Service Access Method (TSAM) software provides a TCP/IP interface between CMS 1100 and a data communications network. See also TCP/IP, Transport Service Access Method. D datagram The basic unit of information passed across an Internet. A datagram contains a source and a destination, as well as the data packet. directory service agent (DSA) The server component defined in the X.500 standard for global directories. The DSA executes requests from directory user agents (DUA) to read and update the directory entries on the global directory server. directory user agent (DUA) The client component defined in the X.500 standard for global directories. An application on a client workstation uses a local DUA to read and update the directory entries on a global directory server. DLL DNS domain See dynamic link library. See domain name system. A logical grouping of network servers and other computers that share common security and user account information. Users have only one account in the domain, thus simplifying sign-on and administration. Users log on to the domain, not to individual servers in the domain. domain controller A Windows NT server that maintains a database of security and user account information for a Windows NT domain. domain name See fully qualified domain name. domain name system (DNS) (Also domain name server) The mechanism that implements a hierarchical naming scheme known as domain names for TCP/IP networks. A domain name consists of a sequence of subnames separated by periods that identify successive levels in directory structure. This system maps host names to IP addresses. Glossary 2 7850 4248 010

Glossary DSA DUA See directory service agent. See directory user agent. dynamic link library (DLL) An executable routine that is stored as a separate file and loaded into memory only when called by a program. DLLs are used for common functions that are needed by more than one program. DLLs are used in the Windows and OS/2 operating systems. dynamic page A document object in the form of a file, typically accessed over the Web or an Internet. The data in the file can be changed or modified during a transaction. E ENP Abbreviation for Error Notification Program. F file transfer protocol (FTP) A program that enables you to transfer data between two computers on a network. FTP Services for ClearPath OS 2200 This software is an open networking application and runs on ClearPath IX and OS 2200 servers. The FTP Services for ClearPath OS 2200 application can transfer files between ClearPath IX and OS 2200 servers and almost any other computing system that runs the TCP/IP environment. fully qualified domain name (FQDN) The full Internet name of a system consisting of its local host name and its Internet domain name. For example, "venera" is a host name and "venera.isi.edu" is an FQDN. G gateway server A server that is an intermediary for other severs. It receives requests for services as if it were an origin server. Therefore, a client requesting service may not be aware that it is communicating with a gateway server. See also proxy server. GET method Requests an object identified by the URL from a server. If the object is a document or a file, GET requests the contents. If the object is a program, GET requests the results of executing the program. If the object is a database query, GET requests the results of the query. Each time you follow a link on the Web, the Web browser uses GET to retrieve the information you requested. 7850 4248 010 Glossary 3

Glossary H HAA Abbreviation for Heritage Application Access. High-Volume Transaction Processing (HVTIP) A specialized technique used for applications requiring a high rate of throughput, and whose processing of a transaction may pass through an arbitrary sequence of subprograms. hosts file The TCP/IP network configuration file (typically in the directory /etc on a UnixWare system) that identifies the network addresses (IP addresses) of other hosts on the network. HREF A hypertext reference that specifies the universal resource identifier (URI) of the resource to which to link. HyperText Markup Language (HTML) The primary language used to define documents accessed over the WWW. As a markup language, HTML uses tags to identify how the text is used (for example, first-level heading, paragraph, list), as opposed to how the text should be presented. This leaves it up to the Web browsers to determine how to present the text (for example, font, type size, indention, and justification). HTML also allows authors to define hypertext links between locations in the same document and between documents and multimedia objects. HyperText Transfer Protocol (HTTP) The primary protocol for transferring data over the WWW. I integrated operating environment (IOE) The foundation software bundled with ClearPath Series servers. The IOE includes operating systems, a database manager, Online Transaction Processing (OLTP) software, integrated administration and operations software, integrated printing software, and application development software. Internet Protocol The protocol suite that defines the IP datagram as the unit of information passed across an Internet and is the basis for the packet delivery service. IP includes the Internet Control Message Protocol (ICMP) control and error message protocol. The complete communications protocol suite is referred to as TCP/IP because TCP and IP are the two most fundamental protocols in the protocol suite. intranet IOE A private, enterprise-wide network that uses TCP/IP and WWW technologies. See integrated operating environment. Glossary 4 7850 4248 010

Glossary IP See TCP/IP. IP address This can either be IPv4 address or IPv6 address. The 32-bit address assigned to hosts in a TCP/IP Internet. An IP address identifies the network to which a host is attached, as well as a specific host on that network. The IP address usually is represented in dotted decimal notation (for example, xxx.xxx.xxx.xxx) with each part (xxx) being a decimal number from 0 to 255 (represented by 8 bits). The IPv6 address is represented as groups of hexadecimal numbers separated by colon. (For example, yyyy:yyyy:yyyy:yyyy:yyyy:yyyy:yyyy:yyyy) with each part (yyyy) being a hexadecimal number from 0 to 4095. These addresses are 128-bit records. K Kerberos A network authentication protocol. It is designed to provide strong authentication for client/server applications by using secret-key cryptography. Part of the Kerberos/NTLM feature. L local area network (LAN) A data communications network that enables computers, terminals, and other data processing resources, typically at one location, to communicate with each other. M Message Control Bank (MCB) A common bank that interfaces with the Communications Management System (CMS 1100) and transaction programs to provide message recovery and transaction scheduling. CMS 1100, TIP file control, and Exec step control use the MCB to interface message recovery and transaction scheduling information. message store The software component of an X.400 mail system that accepts messages from message transfer agents (MTA) and stores them until they are retrieved by remote user agents (RUA). message transfer agent (MTA) The software component of an X.400 mail system that cooperates with other MTAs to perform store-and-forward message delivery. Microsoft Internet Explorer A Web browser program developed by Microsoft Corporation. MIME Abbreviation for multipurpose mail extension. 7850 4248 010 Glossary 5

Glossary Mosaic MTA A Web browser program developed at the National Center for Supercomputing Application (NCSA). As the first Web browser program with a graphical user interface, Mosaic helped popularize the World Wide Web. See message transfer agent. multiple heterogeneous environments Up to two partitions of a single 2200 system are supported. Enables connecting to a maximum of four Intel nodes, with each node running either Windows NT or UnixWare. Any operating system combination among the four Intel nodes is allowable. N NTLM A connection authentication scheme that uses http status codes and headers. Part of the Kerberos/NTLM feature. O online transaction processing (OLTP) A high-performance type of application characterized by a service request from a user immediately followed by an action and response from a server system. A complete request-response cycle is called a transaction. OLTP systems must meet certain criteria, called ACID properties (atomicity, consistency, isolation, and durability), to maintain the integrity of the data and ensure that transactions are executed correctly. Open/OLTP Pathway A TransIT Open/OLTP middleware component that provides applications in the Intel (UnixWare or Windows NT) environment of a ClearPath IX server with a gateway to the Open/OLTP Transaction Manager in the OS 2200 environment. This allows UnixWare or Windows NT applications to execute transactions against OS 2200 databases. P partial URL (PURL) See relative URL. PDP PERL PID Abbreviation for Procedure Definition Processor. Abbreviation for Practical Extraction and Report Language. A scripting language that makes it easy to perform string-manipulation and parsing tasks. Common gateway interface (CGI) scripts are often written in PERL. Abbreviation for position identifier. Glossary 6 7850 4248 010

Glossary PKCS Abbreviation for Public Key Cryptography Standard. POST method Method used to transfer data from a client to a server when the client needs the server to process the data. protocol A set of rules or standards describing methods to achieve compatible transmission and receipt of data (for example, message packets) over a network. protocol port The abstraction that transport protocols use to distinguish between multiple destinations within a host computer. TCP/IP protocols identify ports using small positive integers. Usually, the operating system allows an application program to specify which ports it wants to use. Some ports are used for standard services (for example, electronic mail). proxy server A server that is both a server and a client for the purpose of making requests on behalf of other clients. Requests for services are handled internally or by passing them, with possible translation, to other servers. A proxy server must be able to interpret and, if necessary, rewrite a client message before forwarding it to another server. See also gateway server. R relative URL (PURL) Relative addressing enables you to move entire HTML document trees as a whole without changing any of the embedded URL references. Enables document trees to be partially independent of their location and access scheme. remote user agent (RUA) The client software of an X.400 mail system that provides remote users with access to a message store. rollback (X/Open) The event that ends a transaction and nullifies or undoes all changes to resources specified during that transaction. See also commitment. S schemes See addressing scheme. Server Messages Block (SMB) A client/server request/response protocol for sharing files, printers, serial ports, and communications. 7850 4248 010 Glossary 7

Glossary simple network management protocol (SNMP) A Transmission Control Protocol/Internet Protocol (TCP/IP) that provides basic network management in TCP/IP-based networks, which typically include hardware and software from a variety of vendors. See also SNMP agent. SNMP agent A software component on a network node that collects information and performs network management functions on behalf of authorized SNMP managers. Communications Management System (CMS 1100) includes SNMP agent software, which allows OS 2200 hosts to respond to requests for managed information by SNMP network managers. socket A software abstraction that provides the interface between application programs and communications software. static page A document object in the form of a file. The file can contain any type of data, such as text, graphic images, video, or audio. It is not an executable program file. SYS$LIB$*PROC$ A file created and maintained by COMUS to contain system procedures that the compiler references to satisfy COPY requests. If this file is not assigned, the compiler dynamically assigns it. T TCP/IP Abbreviation for Transmission Control Protocol/Internet Protocol. A set of communication rules that specifies how data is transferred among computers on the Internet. TIP session control A security feature that validates the user security identity (user sign-on and security record) as a communications path is opened to a terminal through CMS 1100. This feature also identifies all work done by a user in the TIP system. This feature is available with all levels of security. Transaction Processing (TIP) A modular extension of the OS 2200 Exec system that provides a high-performance system for real-time processing in which a user causes the execution of a predefined transaction program by entering an input message from a remote terminal. The program accesses the application database and returns a response to the user. Transport Service Access Method (TSAM) The software that provides a TCP/IP interface between CMS 1100, a TCP/IP data communications network, and Web browser software. See also TCP/IP, Communications Management System. Glossary 8 7850 4248 010

Glossary U uniform resource identifier (URI) The generic set of names/addresses are short strings and refer to resources. uniform resource locator (URL) The set of URI schemes containing explicit instructions on how to access a resource on the Internet or intranet. user datagram protocol (UDP) The TCP/IP standard transport level protocol that enables an application program on one machine to send a datagram to an application program on another machine. UDP uses the Internet Protocol (IP) to send the datagram. The datagram includes a port number enabling the sender to distinguish between multiple destinations (application programs) on another machine. UTS Abbreviation for Universal Terminal System. W Web browser Client software for viewing documents on the World Wide Web and navigating hyperlinks to other documents. Used with a ClearPath IX server to access the SysAdmin software on the Web. Windows NT node The portion of the ClearPath IX server on which the Windows NT operating environment executes. World Wide Web (WWW) A world-wide network (a subset of the Internet) that is populated by hyperlinked documents. Web browsers such as Navigator and Internet Explorer hide much of the complexity of the WWW and allow users to view multimedia documents and easily jump from one document to another and from one Web site to another. Also referred to as the Web. X X.400 X.500 A standard for electronic mail developed by the International Organization for Standardization (ISO). Products implementing the X.400 standard provide a mail backbone across which users can send e-mail, faxes, images, and EDI documents. See also message store, message transfer agent (MTA), remote user agent (RUA). A standard for global directory services developed by the International Organization for Standardization (ISO). The X.500 standard defines protocols and interfaces that enable client applications to read and update directory databases on global directory servers. See also directory service agent (DSA), directory user agent (DUA). 7850 4248 010 Glossary 9

Glossary X/Open An international nonprofit consortium dedicated to the advancement of open systems. Its primary activities include defining standards and branding products to ensure interoperability between the products of different vendors. Special Character 2200 node The portion of the ClearPath IX server on which the 2200 operating environment executes. Glossary 10 7850 4248 010

Index A account number for Secure Sessions, 5-5 addressing implication, relative URL, 1-12 alias use in scheduling transaction, 4-5 application group number, 7-53 application group reserved Web Transaction Server name, 5-8 AUTH_TYPE CGI environmental variable, 7-3, 7-50 authentication failure Kerberos/NTLM sessions, 6-5 authentication type 0 for Secure Sessions, 5-2 C C CGI routine CGICommit, 7-46 CGIGetAuxStatus, 7-48 CGIGetBodyPtr, 7-49 CGIGetFieldValue, 7-42 CGIGetOutBufr, 7-43 CGIGetPID, 7-48 CGIGetVar, 7-41 CGIINIT, 7-39 CGILogoff, 7-50 CGIRead, 7-40 CGIRollback, 7-47 CGISend, 7-43 CGITerm, 7-45 CGI environmental variable AUTH_TYPE, 7-3, 7-50 CONTENT_LENGTH, 7-3, 7-50 CONTENT_TYPE, 7-3, 7-50 GATEWAY_INTERFACE, 7-3, 7-50 HTTP_variable, 7-3, 7-50 PATH_INFO, 7-3, 7-50 QUERY_STRING, 7-3, 7-50 REMOTE_ADDR, 7-3, 7-50 REMOTE_HOST, 7-3, 7-50 REQUEST_METHOD, 7-3, 7-50 SCRIPT_NAME, 7-3, 7-50 SERVER_NAME, 7-3, 7-50 SERVER_PORT, 7-3, 7-50 SERVER_PROTOCOL, 7-3, 7-50 SERVER_SOFTWARE, 7-3, 7-50 CGI transaction example, 7-54 CGI$CCS2CCS COBOL CGI routine, 7-22 CGI$COMMIT COBOL CGI routine, 7-14 CGI$GETAUXSTATUS COBOL CGI routine, 7-16 CGI$GETCONTENT COBOL CGI routine, 7-19 CGI$GETFORM COBOL CGI routine, 7-28 CGI$GETPID COBOL CGI routine, 7-17 CGI$GETVAR COBOL CGI routine, 7-9 CGI$INIT COBOL CGI routine, 7-7 CGI$LOGOFF COBOL CGI routine, 7-23 CGI$OPEN COBOL CGI routine, 7-8 CGI$PASSOFF COBOL CGI routine, 7-18 CGI$ROLLBACK COBOL CGI routine, 7-15 CGI$SENDBUFR COBOL CGI routine, 7-12 CGI$SENDHTML COBOL CGI routine, 7-38 CGI$SETDEBUG COBOL CGI routine, 7-21 CGI$SETNODE COBOL CGI routine, 7-20 CGI$TERM COBOL CGI routine, 7-13 CGICommit C CGI routine, 7-46 CGIGetAuxStatus C CGI routine, 7-48 CGIGetBodyPtr C CGI routine, 7-49 CGIGetFieldValue C CGI routine, 7-42 CGIGetFieldValue, CGI routine, 7-3 CGIGetOutBufr C CGI routine, 7-43 CGIGetPID C CGI routine, 7-48 CGIGetPID, CGI routine, 7-3 CGIGetVar C CGI routine, 7-41 CGIGetVar, CGI routine, 7-3 CGIINIT C CGI routine, 7-39 CGIInit, CGI routine, 7-3 CGILogoff C CGI routine, 7-50 CGIRead C CGI routine, 7-40 CGIRead, CGI routine, 7-3 CGIRollback C CGI routine, 7-47 CGISend C CGI routine, 7-43 CGISend, CGI routine, 7-3 CGITerm C CGI routine, 7-45 cipher suite 7850 4248 010 Index 1

Index MD5 message digest, 1-15 RSA Public Key, 1-15 RSA RC4 secret key, 1-15 COBOL CGI routine CGI$CCS2CCS, 7-22 CGI$COMMIT, 7-14 CGI$GETAUXSTATUS, 7-16 CGI$GETCONTENT, 7-19 CGI$GETFIELDVALUE, 7-10 CGI$GETFORM, 7-28 CGI$GETPID, 7-17 CGI$GETVAR, 7-9 CGI$INIT, 7-7 CGI$LOGOFF, 7-23 CGI$OPEN, 7-8 CGI$PASSOFF, 7-18 CGI$ROLLBACK, 7-15 CGI$SEDNHTML, 7-38 CGI$SENDBUFR, 7-12 CGI$SETDEBUG, 7-21 CGI$SETNODE, 7-20 CGI$TERM, 7-13 CONTENT_LENGTH CGI environmental variable, 7-3, 7-50 CONTENT_TYPE CGI environmental variable, 7-3, 7-50 CPYGEN processor example, 7-25 current set, Security Default Definition, 5-10 D define attributes for Secure Sessions, 5-2, 5-5 passwords for Secure Sessions, 5-2, 5-5 user-ids for Secure Sessions, 5-2, 5-5 deleting user set, Security Default Definition, 5-12 destination file, xcopy program, 2-10, 8-7 E ENP terminal type check, 4-11 error 504 transaction timeout, 4-10 example CGI transaction, 7-54 CPYGEN processor, 7-25 FTP command, 2-11 HTML template, 8-6 OLTPTx transaction, 8-3 schedule OS 2200 transaction, 3-2 F schedule transaction using an alias, 4-5 static page URL, 2-4 substitution list, 7-31 URL, 1-12 URL partial addressing, 1-12 VIEW buffer definition, 8-5 failed logon request MAXATMP parameter, 5-8 resources released, 5-8 session closed, 5-8 Flexible User Authentication (FLEX) Kerberos/NTLM sessions, 6-2 FTP command example, 2-11 FTP Services for ClearPath OS 2200, 1-3, 2-11 G GATEWAY_INTERFACE CGI environmental variable, 7-3, 7-50 H HTML template example, 8-6 HTML TIP/HVTIP transaction output, 4-7 HTTP, 1-3, 2-3, 3-1, 4-3, 5-13, 7-1, 8-2 HTTP header, TIP/HVTIP transaction input, 4-6 HTTP_variable CGI environmental variable, 7-3, 7-50 I implication, relative URL addressing, 1-12 initialize, typical transaction operation, 7-6 IP address, 0-5 IPv6, 1-2 IPv6 address, 2-3 K Kerberos/NTLM overview of steps, 6-3 Kerberos/NTLM sessions Index 2 7850 4248 010

Index access control for static pages in CIFS files, 6-1 authentication failure, 6-5 Flexible User Authentication (FLEX), 6-2 logon screen or LOGON function, 6-5 Microsoft network sign-on, 6-1 minimum requirements, 6-2 NTLM-only authentication, 6-6 Secure Sessions differences, 6-2 Secure Sessions similarities, 6-1 TIP session control, 6-1, 6-2 TIP session mechanism, 6-2 using with Secure Sessions, 6-6 Windows authentication protocol, 6-2 key CGI routine CGIGetFieldValue, 7-3 CGIGetPID, 7-3 CGIGetVar, 7-3 CGIInit, 7-3 CGIRead, 7-3 CGISend, 7-3 L learn Web Transaction Server, 7-54 line feed (NL) TIP/HVTIP transaction output, 4-7 link transactions, 7-53 logon request failed MAXATMP parameter, 5-8 resources released, 5-8 session closed, 5-8 logon screen or LOGON function Kerberos/NTLM sessions, 6-5 M MAXATMP parameter, failed logon request, 5-8 MD5 message digest cipher suite, 1-15 message body, TIP/HVTIP transaction input, 4-6 message digest SSL encryption suite, 1-15 minimum requirements Kerberos/NTLM sessions, 6-2 mixed-mode SSL, 5-14 N new definition set, Security Default Definition, 5-10 new password reserved Web Transaction Server name, 5-8 nonparsed header TIP/HVTIP transaction output, 4-7 O obtain first or next message, typical transaction operation, 7-6 OLTPTx transaction example, 8-3 omnibus element (binary), store static page, 1-8, 2-6 Open/OLTP transaction, 3-1 option, xcopy program, 2-10, 8-7 overview of steps Kerberos/NTLM sessions, 6-3 P parsed header TIP/HVTIP transaction output, 4-7 PATH_INFO CGI environmental variable, 7-3, 7-50 plain text TIP/HVTIP transaction output, 4-7 private key SSL encryption suite, 1-15 public key SSL encryption suite, 1-15 Q QUERY_STRING CGI environmental variable, 7-3, 7-50 R relative addressing implication, URL, 1-12 REMOTE_ADDR CGI environmental variable, 7-3, 7-50 REMOTE_HOST CGI environmental variable, 7-3, 7-50 REMOTE-ADDR Web Transaction Server auxiliary information format, 4-6 REMOTE-HOST Web Transaction Server auxiliary information format, 4-6 7850 4248 010 Index 3

Index repeat new password reserved Web Transaction Server name, 5-8 REQUEST_METHOD CGI environmental variable, 7-3, 7-50 REQUIRE_SSL_CONNECTION attribute, 5-14 retrieve message content, typical transaction operation, 7-6 RSA Public Key cipher suite, 1-15 RSA RC4 secret key cipher suite, 1-15 S schedule Open/OLTP transaction, 3-1 OS 2200 transaction example, 3-2 TIP/HVTIP transaction, 3-1, 4-5 transaction using an alias example, 4-5 SCRIPT_NAME CGI environmental variable, 7-3, 7-50 Secure Sessions account numbers, 5-5 authentication type 0, 5-2 define attributes, 5-5 define attributes, 5-2 define passwords, 5-2, 5-5 define user-ids, 5-2, 5-5 SIMAN, 5-2 using with Kerberos/NTLM sessions, 6-6 versus SSL sessions, 5-2 Secure Sessions Kerberos/NTLM sessions differences, 6-1, 6-2 Security Default Definition current set, 5-10 deleting user set, 5-12 new definition set, 5-10 selecting user set, 5-12 user set, 5-9 selecting user set, Security Default Definition, 5-12 send response to client, typical transaction operation, 7-6 SERVER_NAME CGI environmental variable, 7-3, 7-50 SERVER_PORT CGI environmental variable, 7-3, 7-50 SERVER_PROTOCOL CGI environmental variable, 7-3, 7-50 SERVER_SOFTWARE CGI environmental variable, 7-3, 7-50 SERVER-NAME Web Transaction Server auxiliary information format, 4-6 SERVER-PORT Web Transaction Server auxiliary information format, 4-6 SERVER-SOFTWARE Web Transaction Server auxiliary information format, 4-6 SIMAN, Secure Sessions, 5-2 source file, xcopy program, 2-10, 8-7 SSL encryption suite message digest, 1-15 private key, 1-15 public key, 1-15 SSL sessions versus Secure Sessions, 5-2 SSLEnabled security option, 5-15 starting URL variable name reserved Web Transaction Server name, 5-8 static page stored in omnibus element (binary), 1-8, 2-6 symbolic element (ASCII), 1-8, 2-6 static page URL example, 2-4 substitution list example, 7-31 symbolic element (ASCII), store static page, 1-8, 2-6 T terminal type check, ENP, 4-11 terminate, typical transaction operation, 7-6 TIP session control Kerberos/NTLM sessions, 6-1, 6-2 TIP session mechanism Kerberos/NTLM sessions, 6-2 TIP/HVTIP transaction input HTTP header, 4-6 message body, 4-6 Web Transaction Server auxiliary information, 4-6 transaction output field-value, 4-7 HTML, 4-7 line feed (NL), 4-7 nonparsed header, 4-7 parsed header, 4-7 plain text, 4-7 TIP/HVTIP transaction, 3-1, 4-5 transaction timeout, error 504, 4-10 typical transaction operation initialize, 7-6 obtain first or next message, 7-6 retrieve message content, 7-6 send response to client, 7-6 Index 4 7850 4248 010

Index U terminate, 7-6 update file, xcopy program, 2-10 URL example, 1-12 format, 1-11 relative addressing implication, 1-12 user set, Security Default Definition, 5-9 user-id password reserved Web Transaction Server name, 5-8 V valid buffer type VIEW, 8-5 X_C_COMMON, 8-5 X_C_TYPE, 8-5 VIEW buffer definition example, 8-5 VIEW valid buffer type, 8-5 W Web Transaction Server auxiliary information format REMOTE-ADDR, 4-6 REMOTE-HOST, 4-6 SERVER-NAME, 4-6 SERVER-PORT, 4-6 SERVER-SOFTWARE, 4-6 auxiliary information, TIP/HVTIP transaction input, 4-6 CGI example transaction, 7-54 reserved name application group, 5-8 new password, 5-8 repeat new password, 5-8 starting URL variable name, 5-8 user-id password, 5-8 use and learn, 7-56 Windows authentication protocol Kerberos/NTLM sessions, 6-2 X X_C_COMMON valid buffer type, 8-5 X_C_TYPE valid buffer type, 8-5 xcopy program destination, 2-10, 8-7 option, 2-10, 8-7 source, 2-10, 8-7 update file, 2-10 7850 4248 010 Index 5

Index Index 6 7850 4248 010

.

2008 Unisys Corporation. All rights reserved. *78504248-010* 7850 4248 010