47 A2 39UT REV02 - TDS-WEB User`s Guide

Transcription

Transaction Processing
TDS-Web
TDS-Web for GCOS 7 User's Guide
Subject:
This manual gives guidelines for administrators and application
developers who use the TDS-Web software.
Special Instructions:
Software Supported:
GCOS 7- V9 (TA) from TS 9764
Software/Hardware required: GCOS 7-V9 (see above), IDS/II, Web browser,
MainWay HTTP-DSA Gateway
Date:
Bull S.A.
CEDOC
Atelier de reprographie
357, Avenue Patton BP 20845
49008 ANGERS Cedex 01
FRANCE
47 A2 39UT Rev02
June 2000
Bull HN Information Systems Inc.
Publication Order Entry
FAX: (800) 611-6030
MA30/415
300 Concord Rd.
Billerica, MA 01821
U.S.A.
Copyright © Bull S.A., 1999, 2000
Bull acknowledges the rights of proprietors of trademarks mentioned herein.
Your suggestions and criticisms concerning the form, contents and presentation of this manual are invited.
A form is provided at the end of this manual for this purpose.
No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any
means, electronic, mechanical or otherwise without the prior written permission of the publisher.
Bull disclaims the implied warranties of merchantability and fitness for a particular purpose and makes no
express warranties except as may be stated in its written agreement with and for its customer. In no event is Bull
liable to anyone for any indirect, special, or consequential damages.
The information and specifications in this document are subject to change without notice.
Consult your Bull Marketing Representative for product or service availability.
47 A2 39UT Rev02
Preface
Scope and
Objectives
This User’s Guide provides information about the TDS-Web environment and how
to use the TDS-Web software.
Intended
Readers
The information in this document is designed for use by developers of TDS-Web
applications and by system/database administrators who are responsible for
managing a TDS-Web environment, including the associated TDS environment.
Prerequisites
Administrators who use this guide are assumed to be familiar with the
transaction-processing environment on GCOS 7, and to be generally familiar with
the use of the World Wide Web (the Web).
Application developers who use this guide to develop TDS-Web transaction
processing routines (TPRs) are assumed to be familiar with TDS.
Additional information about both topics is available in documents that are
referenced in Chapter 1 of this guide.
Structure
The information in this document is structures as follows:
Chapter 1
General presentation of TDS-Web and introduction to
World Wide Web.
Chapter 2
Introduces TDS-Web Processing Concepts, URL,
Document Base, Context Management.
Chapter 3
Summarizes the activities required to plan for the
installation of the TDS-Web environment.
Chapter 4
Describes the installation of TDS-Web, from the
delivery medium.
Chapter 5
Explains the relationship between TDS and TDS-Web,
and describes how to establish the TDS environment
required to support TDS-Web applications.
Chapter 6
Documents the IDS/II structure of the HTML Template
Database, which is used to store HTML pages (Web
pages) on GCOS 7.
47 A2 39UT Rev02
iii
Bibliography
Chapter 7
Explains in detail how to develop TDS-Web
applications to operate as TPRs.
Chapter 8
Contains the specifications for each of the APIs used to
call the TDS-Web runtime routines from TDS-Web
applications, and provides context information that
explains how the runtime routines operate.
Chapter 9
Describes the routines used by the developer to
retrieve in a TPR the records making up an HTML
page stored in HTML Template Database.
Chapter 10
Explains what to do in the event of an error.
Appendix A
Contains the IDS/II Status Keys.
Appendix B
Contains the File Status Keys.
Appendix C
Contains the C and COBOL error codes.
Appendix D
Contains the C language constants.
The following list of related documentation is subdivided into:
• GCOS 7 documentation
• MainWay documentation
• World Wide Web and HTML documentation
GCOS 7 Documentation
The related GCOS 7 software documentation listed below can be ordered through a
Marketing and Sales Order Entry. Contact your Marketing representative for
further information.
For Using TDS
TDS Concepts .......................................................................................... 47 A2 01UT
TDS Administrator’s Guide ..................................................................... 47 A2 32UT
TDS COBOL Programmer’s Guide ......................................................... 47 A2 33UT
TDS C Programmer’s Guide.................................................................... 47 A2 07UT
For COBOL Syntax and Use
COBOL 85 Reference Manual................................................................. 47 A2 05UL
COBOL 85 User’s Guide ......................................................................... 47 A2 06UL
iv
47 A2 39UT Rev02
Preface
For File Access and Data Management
IDS/II Reference Manual.........................................................................47 A2 11UD
IDS/II Administrator’s Guide ................................................................. 47 A2 13UD
IDS/II User’s Guide ................................................................................ 47 A2 12UD
Full IDS/II Reference Manual Volume1.................................................. 47 A2 05UD
Full IDS/II Reference Manual Volume 2................................................. 47 A2 06UD
Full IDS/II User’s Guide ........................................................................ 47 A2 07UD
Database Reorganization (DBREORG) User’s Guide ........................... 47 A2 15UD
For Network Generation
Network Generation Language Reference manual.................................. 39 A2 10EB
MainWay Documentation
The related MainWay software documentation listed below can be ordered through
a Marketing and Sales Order Entry. Contact your Marketing representative for
further information.
MainWay DNS-E Software Release Bulletin............................................ 39 A2 17EB
MainWay System Generation Guide ........................................................ 39 A2 09EB
MainWay Configuration Application Guide ............................................ 39 A2 15EB
World Wide Web and HTML Documentation
Online documentation for the complete HTTP and HTML specifications is located
on the World Wide Web via the following URL:
http://www.w3.org/
Online documentation for the Common Gateway Interface (CGI) is located on the
World Wide Web via the following URL:
http://hoohoo.ncsa.uiuc.edu/
47 A2 39UT Rev02
v
vi
47 A2 39UT Rev02
Table of Contents
1.
2.
3.
Introduction
1.1
World Wide Web Overview ............................................................................................. 1-2
1.2
TDS-Web Overview ........................................................................................................ 1-4
1.2.1 The Connection Chain ....................................................................................... 1-5
1.2.2 The Exchange Protocol ..................................................................................... 1-6
1.3
TDS-Web Components ................................................................................................... 1-7
TDS-Web Processing Concepts
2.1
Uniform Resource Locators (URLs)................................................................................ 2-2
2.1.1 Absolute URLs................................................................................................... 2-3
2.1.2 Server-Relative URLs ........................................................................................ 2-5
2.1.3 Document-Relative URLs .................................................................................. 2-7
2.2
Document Base............................................................................................................... 2-9
2.3
TDS-Web URLs ............................................................................................................ 2-12
2.4
Context Management.................................................................................................... 2-15
TDS-Web Environment
3.1
The Browser.................................................................................................................... 3-2
3.2
HTTP-DSA Gateway ....................................................................................................... 3-3
3.2.1 Configuring MainWay ........................................................................................ 3-3
3.2.2 Configuring MainWay for Use With the MainWay HTTP-DSA Gateway........... 3-4
3.3
GCOS 7 System Environment ........................................................................................ 3-7
3.4
Configuring TDS-Web-Related GCOS 7 Software ......................................................... 3-8
3.4.1 Purpose of JPPC ............................................................................................... 3-8
3.4.2 Choosing JPPC ................................................................................................. 3-8
3.4.3 Using JPPC ....................................................................................................... 3-9
47 A2 39UT Rev02
vii
4.
5.
6.
Preparation of the TDS-Web Product
4.1
Contents of the System Libraries.................................................................................... 4-2
4.2
Environment Configuration Procedure............................................................................ 4-3
4.3
Installation of a TDS-Web TDS....................................................................................... 4-4
4.3.1 Installation Modes.............................................................................................. 4-4
4.3.2 Starting the Procedure....................................................................................... 4-5
4.3.3 Description of the Procedure ............................................................................. 4-6
4.3.4 The Demonstration TDS .................................................................................. 4-10
4.3.5 Following the Installation ................................................................................. 4-11
4.4
TDS-Web Update Procedure ........................................................................................ 4-12
4.5
Installation for an Existing TDS..................................................................................... 4-13
4.6
Sharing the HTML Template Database ........................................................................ 4-15
4.7
TDS-Web TDS AppIication Access............................................................................... 4-16
TDS Considerations When Using TDS-Web
5.1
Administration of the TDS ............................................................................................... 5-2
5.1.1 HTML Template Database................................................................................. 5-2
5.1.2 TDS Generation................................................................................................. 5-2
5.1.3 The TDS Start-up JCL ....................................................................................... 5-6
5.1.4 Adapting an Existing TDS.................................................................................. 5-6
5.2
The Specific TPRs .......................................................................................................... 5-7
5.2.1 Logout TPR........................................................................................................ 5-7
5.2.2 Disconnect TPR................................................................................................. 5-8
5.2.3 Abort TPR .......................................................................................................... 5-8
5.3
Programming the TPRs .................................................................................................. 5-9
5.3.1 TDS-Web TPR................................................................................................... 5-9
5.3.2 TPR Other Than TDS-Web................................................................................ 5-9
5.4
End User ....................................................................................................................... 5-10
5.4.1 Welcome Page ................................................................................................ 5-10
5.4.2 Specific Features of TDS-Web Transactions .................................................. 5-10
HTML Template Database
6.1
viii
Management of the HTML Template Database.............................................................. 6-1
6.1.1 Management...................................................................................................... 6-1
6.1.2 Database access ............................................................................................... 6-1
6.1.3 Monitoring .......................................................................................................... 6-2
47 A2 39UT Rev02
6.1.4
7.
Enlargement of the Database............................................................................ 6-3
6.1.4.1 Parameter entry and UFAS file allocation ......................................... 6-3
6.1.4.2 Unloading the database .................................................................... 6-5
6.1.4.3 Creating the new area ....................................................................... 6-7
6.1.4.4 Reloading the area ............................................................................ 6-7
6.1.4.5 Example of database reorganization................................................. 6-8
6.2
Description of the Database.......................................................................................... 6-10
6.2.1 HTML Header .................................................................................................. 6-11
6.2.2 HTML Record .................................................................................................. 6-11
6.2.3 Action Record .................................................................................................. 6-11
6.2.4 Binary Record .................................................................................................. 6-12
6.2.5 Data Description Language (DDL) .................................................................. 6-12
6.2.6 Device Media Control Language (DMCL)........................................................ 6-13
6.3
Loading Web Pages into the HTML Template Database ............................................. 6-14
6.4
Using the HTML Administrative Utility........................................................................... 6-15
6.4.1 The Batch Process LOADHTM........................................................................ 6-16
6.4.1.1 Description of Commands ............................................................... 6-16
6.4.1.2 Syntax of Commands ...................................................................... 6-17
6.4.1.3 Structure of the COMMAND File..................................................... 6-17
6.4.2 Description of the LOCALHOST File ............................................................... 6-18
6.4.2.1 Example of LOCALHOST File......................................................... 6-19
6.4.2.2 Structure of the LOCALHOST File .................................................. 6-19
6.4.2.3 JCL to Run the Utility....................................................................... 6-20
6.4.3 ADMIN Transaction ......................................................................................... 6-21
6.4.3.1 Executing via the Mainway Page .................................................... 6-21
6.4.3.2 Description of the ADMIN Functions ............................................... 6-24
6.4.4 Error Messages ............................................................................................... 6-27
6.4.4.1 The Batch Process LOADHTM Error Messages............................. 6-27
6.4.4.2 ADMIN Error Messages at the MASTER Level .............................. 6-29
6.4.4.3 ADMIN Error Messages at the BROWSER Level........................... 6-32
Developing TDS-Web Applications
7.1
Introduction to Developing a TDS-Web TPR .................................................................. 7-2
7.2
Coordinating TPR Development and Web Page Design ................................................ 7-3
7.3
Creating Web Pages To Be Used as TDS-Web Output ................................................. 7-5
7.4
Designing TDS-Web TPRs ........................................................................................... 7-10
7.4.1 Using TDS-Web Runtime Routines To Receive Input..................................... 7-10
7.4.2 Options for Handling HTML Output ................................................................. 7-10
7.4.3 Using a Base TPR ........................................................................................... 7-11
7.4.4 Using TDS-Web Runtime Routines To Send Output ...................................... 7-11
47 A2 39UT Rev02
ix
8.
x
7.5
Coding TDS-Web TPRs ................................................................................................ 7-12
7.5.1 Basic Coding Requirements ............................................................................ 7-12
7.5.2 TPR Input......................................................................................................... 7-15
7.5.3 TPR Output...................................................................................................... 7-16
7.5.3.1 Minimum TPR Output...................................................................... 7-18
7.5.3.2 Additional TPR Output..................................................................... 7-18
7.5.3.3 Base TPR Output ............................................................................ 7-21
7.5.4 Using TDS-Web Runtime Routines To Analyze/Process HTTP Requests ..... 7-23
7.5.5 HTML Template Database Access Routines................................................... 7-24
7.6
Compiling and Linking TDS-Web TPRs........................................................................ 7-25
7.7
Examples of TPRs ........................................................................................................ 7-26
7.7.1 Example 1 - DOCSTPR1 ................................................................................. 7-26
7.7.2 Example 2 - DOCSTPR2 ................................................................................. 7-29
7.7.3 Example 3 - DOCSTPR3 ................................................................................. 7-36
7.7.4 Example 4 - DOCSTPR4 ................................................................................. 7-43
7.7.5 Example 5 – DOCSTPR5 and DOCSTPR6 .................................................... 7-52
APIs for TDS-Web Runtime Routines
8.1
Using the TDS-Web Runtime Routines .......................................................................... 8-2
8.1.1 Characteristics of the TDS-Web Runtime Routines .......................................... 8-2
8.1.2 Checking for Errors............................................................................................ 8-2
8.1.3 Using the TDS-Web Runtime Routines from COBOL-85.................................. 8-3
8.2
Initializing TDS-Web TPR Environment .......................................................................... 8-5
8.3
Handling TDS-Web TPR Input........................................................................................ 8-6
8.3.1 Format of TDS-Web TPR Input ......................................................................... 8-6
8.3.2 Format of Environment Headers ....................................................................... 8-7
8.3.3 Format of HTTP Headers .................................................................................. 8-7
8.3.4 Format of Form Variables .................................................................................. 8-8
8.3.5 Other TDS-Web Runtime Routines for Input ..................................................... 8-8
8.4
Building TDS-Web TPR Output ...................................................................................... 8-9
8.5
Handling TDS-Web TPR Output ................................................................................... 8-10
8.5.1 TDS-Web Buffers TPR Output ........................................................................ 8-10
8.5.2 Using HTTP_SEND Calls ................................................................................ 8-11
8.6
Syntax Definitions for TDS-Web APIs........................................................................... 8-12
8.6.1 HTML_BASE ................................................................................................... 8-13
8.6.2 HTTP_ABORT ................................................................................................. 8-17
8.6.3 HTTP_COPY_MESSAGE ............................................................................... 8-18
8.6.4 HTTP_DATE.................................................................................................... 8-20
8.6.5 HTTP_EXIT ..................................................................................................... 8-22
47 A2 39UT Rev02
8.6.6
8.6.7
8.6.8
8.6.9
8.6.10
8.6.11
8.6.12
8.6.13
8.6.14
8.6.15
8.6.16
8.6.17
8.6.18
8.6.19
8.6.20
8.6.21
8.6.22
8.6.23
8.6.24
8.6.25
8.6.26
9.
HTTP_EXPIRES.............................................................................................. 8-23
HTTP_FREEWEB7.......................................................................................... 8-25
HTTP_GETCONTEXT..................................................................................... 8-26
HTTP_GETENV............................................................................................... 8-28
HTTP_GETENV_FIRST .................................................................................. 8-31
HTTP_GETENV_NEXT ................................................................................... 8-34
HTTP_GETHDR .............................................................................................. 8-37
HTTP_GETHDR_FIRST.................................................................................. 8-40
HTTP_GETHDR_NEXT................................................................................... 8-43
HTTP_GETMETHOD ...................................................................................... 8-47
HTTP_GETPATH ............................................................................................ 8-49
HTTP_GETVAR............................................................................................... 8-51
HTTP_GETVAR_FIRST .................................................................................. 8-54
HTTP_GETVAR_NEXT ................................................................................... 8-57
HTTP_GETVERSION...................................................................................... 8-61
HTTP_JSQUOTE ............................................................................................ 8-63
HTTP_RECEIVE.............................................................................................. 8-65
HTTP_SEND ................................................................................................... 8-67
HTTP_SENDJSQUOTE .................................................................................. 8-69
HTTP_SENDJSTEXT ...................................................................................... 8-71
HTTP_SENDTEXT .......................................................................................... 8-74
HTML Template Database Access Routines
9.1
H_WEB7_GET_HEADER(I) ........................................................................................... 9-2
9.2
H_WEB7_GET_RECORD(I)........................................................................................... 9-5
9.3
Consequences for the user............................................................................................. 9-7
10. What To Do in the Event of an Error
10.1 Error Messages Displayed via HTML Pages ................................................................ 10-1
10.2 Netscape 3.0 Error Messages ...................................................................................... 10-6
10.3 Errors Due to the Creation of Pages............................................................................. 10-6
10.4 Errors Due to Cache Management by the Browsers .................................................... 10-6
47 A2 39UT Rev02
xi
A.
IDS/II Status Keys
B.
File Status Key
C.
Error Codes
D.
Constants
Glossary
Index
xii
47 A2 39UT Rev02
Table of Graphics
Figures
1-1.
1-2.
1-3.
2-1.
2-2.
3-1.
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
4-9.
4-10.
4-11.
4-12.
6-1.
6-2.
6-3.
6-4.
6-5.
6-6.
6-7.
6-8.
6-9.
6-10.
7-1.
7-2.
7-3.
7-4.
8-1.
TDS-Web Overview ........................................................................................................ 1-4
Exchange Protocol .......................................................................................................... 1-6
Components of the TDS-Web Environment ................................................................... 1-7
Context Management - Summary ................................................................................. 2-18
Help Routines................................................................................................................ 2-19
TDS-Web Network Configuration.................................................................................... 3-3
Installation Questions and Answers................................................................................ 4-5
Installation Report - Directory Creation........................................................................... 4-6
Installation Report - Creation of HTMLAREA ................................................................. 4-6
Installation Report - LOADHTM ...................................................................................... 4-7
Installation Report - TP7PREP ....................................................................................... 4-8
Installation Report - Modifying STDS.............................................................................. 4-8
Installation Report - TP7GEN ......................................................................................... 4-8
Installation Report - Compiling TPRs.............................................................................. 4-9
Installation Report - End of Installation ........................................................................... 4-9
Example of Creation of an HTML Template Database ................................................. 4-14
MainWay Welcome Page.............................................................................................. 4-16
Example of the Top of the MainWay Page ................................................................... 4-17
HTML SCHEMA ............................................................................................................ 6-10
Schema of Loading Pages into the Database .............................................................. 6-14
Structure of the COMMAND file.................................................................................... 6-17
Structure of the LOCALHOST File................................................................................ 6-19
JCL to Run the Utility .................................................................................................... 6-20
Mainway Welcome Page - With Field Values ............................................................... 6-22
ADMIN Transaction Welcome Page ............................................................................. 6-23
List of HTML pages ....................................................................................................... 6-24
List of Inserted HTML Pages ........................................................................................ 6-25
Display of a Page .......................................................................................................... 6-26
TDS-Web Input Format ................................................................................................. 7-15
Example of HTTP Request ........................................................................................... 7-16
Example of Netscape User Page.................................................................................. 7-44
Example of Netscape TPR Page .................................................................................. 7-45
TDS-Web Input Format ................................................................................................... 8-6
47 A2 39UT Rev02
xiii
Tables
7-1.
7-2.
7-3.
7-4.
8-1
C-1.
D-1.
xiv
Overview of TDS-Web TPR Output Contents............................................................... 7-17
TPR Output Items (1/2) ................................................................................................. 7-19
TDS-Web Runtime Routines (1/2) ................................................................................ 7-23
TDS-Web Routines for access to HTML Template Database ...................................... 7-24
TDS-Web APIs.............................................................................................................. 8-12
C and COBOL Error Codes (1/2) ....................................................................................C-1
C Language Constants ...................................................................................................D-1
47 A2 39UT Rev02
1. Introduction
TDS-Web provides an environment in which sites can deploy new or revised
Transaction Processing Routines that allow users of commodity Web browsers to
access data on a GCOS 7 system over a TCP/IP network.
This section of the User’s Guide provides an introduction to TDS-Web processing,
organized as follows:
• World Wide Web Overview.
• TDS-Web Overview.
• TDS-Web Components.
47 A2 39UT Rev02
1-1
1.1
World Wide Web Overview
The Internet and corporate Intranets provide the network infrastructure upon which
World Wide Web (Web) solutions can be built.
A Web browser is the user interface to the Web, providing a rich set of presentation
features defined by the HyperText Markup Language (HTML).
The Web browser sends messages to a HyperText Transfer Protocol (HTTP) server,
also referred to as a Web server, and in response accepts HTML documents, also
known as Web pages.
HTML documents are of two types:
• static HTML documents, in which the content never changes,
• and dynamic HTML documents, which are produced by executing a script or
program.
The Common Gateway Interface (CGI) defines a standard environment for the
execution of scripts that are spawned by Web servers.
Web servers manage the execution of applications that generate Web pages (HTML
documents). A Web server accepts HTTP requests from Web browsers. Each
HTTP request provides the exact name of a resource, usually an HTML document,
that is requested. The name of the resource is expressed as a Uniform Resource
Locator (URL), which is the addressing method used on the Web. If the resource is
a CGI script, the HTTP request also includes parameters that are used by the script.
A URL might look like this example:
http://mainway location:8080/node.mytp/0/CONNECT
The user may have made the above request explicitly by entering the full HTML
document name in the address-input box of the browser, or implicitly by selecting a
link on an existing page or by using a bookmark.
The Web browser uses the protocol information (http:) and the host name
(//mainway location) from the URL to make a connection to the desired HTTP
server (//mainway location). The browser sends the remainder of the URL to the
HTTP server.
1-2
47 A2 39UT Rev02
Introduction
Interaction between the Web browser and the HTTP server is based on standard
protocols — TCP/IP and HTTP.
• Transmission Control Protocol/Internet Protocol (TCP/IP) provides the
infrastructure for communication between computers.
• HTTP is an application-level protocol for distributed, collaborative, hypermedia-
based information systems. HTTP is a stateless protocol; i.e., every HTTP
request submitted by a browser requires a new connection to be made. At the
end of each response, the connection is terminated.
HTTP servers can be deployed on a variety of hardware and software platforms.
Applications can be designed around the use of a single Web server, or can use
several servers in combination to distribute processing and improve scalability.
47 A2 39UT Rev02
1-3
1.2
TDS-Web Overview
The Web is an increasingly important resource for businesses worldwide, and the
use of Web browsers is widespread. Bull provides TDS-Web so that enterprises
can incorporate browsers directly into their transaction processing environments on
GCOS 7.
TDS-Web enables customers to deploy new or revised TDS applications that can
be accessed via commodity Web browsers over a TCP/IP network.
TDS
Internet
Intranet
Customer
Application
TCP/IP
browser
M
A
I
N
W
A
Y
DSA
User’s
Transaction
logic
helper
routines
Document
processing
logic
HTTP-DSA Gateway
production
data
HTML Import Utility
HTTP Protocol + HTML pages
HTML
Template
Database
Figure 1-1.
TP
or
BATCH
Utility
TDS-Web Overview
The minimum environment required for deploying TDS-Web must comprise the
following items:
• A workstation with a browser installed
• a MainWay,
• a TDS,
• HTML pages.
1-4
47 A2 39UT Rev02
Introduction
1.2.1
The Connection Chain
This includes:
• Communication between the browser and the MainWay is a TCP/IP type link.
• Communication between the MainWay and GCOS 7 is a DSA link.
HTTP-DSA Gateway, installed at the level of the MainWay, performs the
adaptation of the various protocols, TCP/IP to DSA and DSA to TCP/IP.
In addition, it provides the link between the Internet and GCOS 7 worlds. Using
contexts, it ensures that the connection between both worlds remains permanent.
A context set to 0, sent by the browser to GCOS 7, is interpreted by the MainWay
as a connection request. Inversely, a context set to 0, sent by GCOS 7 to the
browser, is interpreted by the MainWay as a disconnection. During the connection,
the contexts defined partly by the MainWay and partly by the application, enable
the MainWay to identify this connection and to check that each request sent by the
browser corresponds to what the application expects. See Section 2.4 Context
Management in Chapter 2, TDS-Web Processing Concepts.
47 A2 39UT Rev02
1-5
1.2.2
The Exchange Protocol
The protocol for exchanges between the browser and the TDS is HTTP protocol,
which encapsulates variable data and HTML pages.
Exchanges consist of HTPP messages:
• requests composed by the browser, completed by the MainWay and transmitted
to the TDS,
• replies composed by the TPRs and transmitted to the browser. These replies
contain the description of the HTML pages to be displayed on the browser.
An HTML page is made up of a fixed part (description of texts and formatting),
and an optional part (variables affected by the application). These variables may
be supplied in the form of JavaScripts. Refer to Chapter 7, Developing TDS-Web
Applications. Requests and replies contain the URLs, that is, the access paths to
the necessary resources. See Section 2.1 Uniform Resource Locators in Chapter 2,
TDS-Web Processing Concepts.
DPS7000
Mainway
HTTP/DSA
Gateway
HTTP request
Opening of
DSA session
HTTP request
Session
DSA
HTTP replies + HTML pages
HTTP requests
T
D
S
HTTP replies+ HTML pages
HTTP reply + Page HTML LOGOUT
Closure of
DSA session
Figure 1-2.
1-6
HTML
Template
Database
Exchange Protocol
47 A2 39UT Rev02
Introduction
1.3
TDS-Web Components
The following diagram shows the component elements of the TDS-Web product
offer, installed on GCOS 7.
TDS
Customer
Application
User’s
Transaction
logic
helper
routines
Document
processing
logic
production
data
HTML Administrative Utility
HTML
Template
Database
TP
or
BATCH
Utility
TDS-Web components
Figure 1-3.
Components of the TDS-Web Environment
The main TDS-Web components are:
• A Helper routines library which facilitates transaction processing for analyzing
the HTTP requests originating from the browser and for generating the HTTP
replies sent back to the browser.
• An IDS/II database, HTML Template Database, which stores all the HTML
pages that will be used by the transactions invoked by a browser.
• A batch program, LOADHTM, and a transaction, ADMIN, which together are
used to load the HTML Template Database. In the previous diagram, these
programs are grouped together under the name HTML Administrative Utility.
47 A2 39UT Rev02
1-7
• Examples of transactions are also supplied so that the connection chain can be
validated quickly once TDS-Web has been installed and also to serve as
templates for developing future transactions. These are listed below.
Transactions Supplied
The following examples of transactions are supplied:
1-8
DOC1:
This transaction receives an HTTP request, prepares an
HTML page, sends the reply to the browser and
terminates the transaction and the DSA session.
DOC2:
This transaction displays a series of HTML pages
before terminating the transaction and the DSA
session.
DOC3:
The HTML pages to be displayed on the browser are
sought in the HTML Template Database.
DOC4:
This transaction displays an HTML page, one line of
which must be updated at each call, with the aid of the
ACTIONRECORDs contained in the HTML Template
Database.
47 A2 39UT Rev02
2. TDS-Web Processing Concepts
This section presents some basic Web processing concepts, and also some concepts
that are unique to the TDS-Web environment.
The concepts discussed in this section are:
• Uniform Resource Locators
• Document Base
• TDS-Web URLs
• Context Management
47 A2 39UT Rev02
2-1
2.1
Uniform Resource Locators (URLs)
The Uniform Resource Locator (URL) is a well-defined mechanism for describing
the location of a resource anywhere on the Web. A URL is composed of three
pieces of information:
1.
Protocol name - typically HTTP
2.
Server address
3.
Resource name - typically a file on a Web server
Three types of URLs are defined:
1.
Absolute URL
2.
Server-relative URL
3.
Document-relative URL
Each type of URL is described in the following subsections.
2-2
47 A2 39UT Rev02
2.1.1
Absolute URLs
An absolute URL specifies all of the addressing information - protocol, server
address, and a resource name - that is necessary to locate the desired resource, as in
the following example.
http://www.bull.com/products/GCOS7/software.html
In the above example, the protocol is http, the server address is
www.bull.com, and the resource is /products/GCOS7/software.html.
The requested document can contain hyperlinks to additional resources. A
hyperlink specifies the location of another resource on the same or a different
server, and allows the designer of Web pages to integrate information and resources
from multiple applications and servers.
For example, a document with a URL of:
/products/GCOS7/software.html
might include a list of software categories, such as programming tools,
communications products, and TP products, with a hyperlink for each category.
Each hyperlink would then allow users to retrieve more specific information about
the category referenced by that hyperlink.
The most common way to provide a hyperlink is to include the HTML anchor
element (<A></A>) on the page. An anchor identifies text that the user can select
(typically by clicking on the hyperlink), and specifies the resource that is requested
when the link is selected.
NOTE:
HTML is case-insensitive, so «<A>» and «<a>» are equivalent. Explanatory
text in this document typically presents HTML tags in upper case, which is the
usual practice. However, some HTML tags in examples may appear in lower
case.
47 A2 39UT Rev02
2-3
To continue the preceding example, let us assume that the document at
/products/GCOS7/software.html contains the following sequence of
HTML.
<H1>Product categories</H1><HR>
<A HREF=«http://www.bull.com/products/GCOS7/tools.html»>
Programming Tools
</A><BR>
<A HREF=«http://www.bull.com/products/GCOS7/communications.html»>
Communication Products
</A><BR>
<A HREF=«http://www.bull.com/products/GCOS7/oltp.html»>
</A><BR>>
⇐
⇐
⇐
⇐
⇐
⇐
When displayed by a browser, the text between each opening <A> and the
associated closing </A> (the ⇐ symbols point to these anchor elements) is visible
as a link. When the user clicks on one of these links, the browser uses the
information in the HREF field of the selected anchor to request the desired
resource from the server. If the user selects the «Programming Tools» link in this
example, the browser connects to the server www.bull.com and requests the
document that is located at:
/products/GCOS7/tools.html
This example uses three absolute URLs to define the links to related documents. If
the documents are moved to another server, the absolute URLs are no longer valid,
and as a result, the browser will send all future requests to the wrong server. To
correct this situation, the absolute URLs on every page that is moved must be
modified to reflect the new location. The process of editing each of these files can
be time-consuming and is prone to error. The use of relative URLs, which are
described in the following subsection, eliminates this problem.
2-4
47 A2 39UT Rev02
2.1.2
Server-Relative URLs
A server-relative URL does not include the entire URL, but instead contains a
pathname that is relative to some configured «root» directory on the server.
Note that Web browsers do not have access to the entire file system of the server,
but only to files that are subordinate to a configured «root.».
The following example HTML sequence uses server-relative URLs. Note the
leading slash («/») characters, which indicate that these are server-relative URLs.
<A HREF=«/products/GCOS7/tools.html»>
Programming Tools
</A><BR>
<A HREF=«/products/GCOS7/communications.html»>
</A><BR>
<A HREF=«/products/GCOS7/oltp.html»>
</A><BR>
⇐
⇐
⇐
By removing the protocol and server-address information from the HREF attribute
of each anchor, the Web-page designer has created a Web page that can be moved
to any server without the need to modify any HTML. When a relative URL is
selected, the Web browser detects that the protocol and server address are missing.
The browser sends the request to the same server that delivered the page that
contains the relative URL. In our example, the user originally requested:
http://www.bull.com/products/GCOS7/software.html
Using the revised HTML, the browser detects that the anchors do not contain the
protocol and server address, and therefore obtains these values from the original
URL.
If the user selected the revised link for «Programming Tools», the browser
constructs a new request that uses the protocol and server information:
«http://www.bull.com»
and the relative document path:
«/products/GCOS7/tools.html»
47 A2 39UT Rev02
2-5
to form a new absolute URL as follows:
http://www.bull.com/products/GCOS7/tools.html
If the original document and all referenced documents are moved to a new server,
the links within the documents continue to work as expected. For example, if the
documents are relocated to the server at "www.GCOS7.bull.com", the new
absolute URL for the first document is:
http://www.GCOS7.bull.com/products/GCOS7/products.html
If the user selects the «Programming Tools» link from the "products.html"
document using this new URL, the browser forms the following absolute URL:
http://www.GCOS7.bull.com/products/GCOS7/tools.html
By using relative URLs instead of absolute URLs, the site gains the ability to
relocate documents to new servers without any need to edit the anchors that are
contained within the collection of documents.
However, we also need to consider what happens if the site decides to re-organize
the document directory structure. For example, as a result of several e-mail
messages from users who found the current organization difficult to use, the site
might decide that a new structure is necessary. The site would create a new
directory structure and move the HTML documents. Users can now request
information about products and services using the following URL:
http://www.GCOS7.bull.com/
Users who request this new URL receive a page that offers links to categories of
products and services that are specific to GCOS7. Having learned from previous
experience, the site uses relative URLs on this new page. During the process of
re-organization, the site also decides that the name «GCOS7» is no longer a
necessary part of the resource name, because «GCOS7» is already specified in the
server name. After the re-organization, the pages have been moved to:
http://www.GCOS7.bull.com/products.html
2-6
47 A2 39UT Rev02
Although this URL is more user friendly, the change has made each of the URLs in
the existing document obsolete. Although these URLs are relative to the server,
they also contain complete path information. To correct this problem, the site now
decides to update the documents to use document-relative URLs, as described in
the following subsection.
2.1.3
Document-Relative URLs
A document-relative URL contains only part of the pathname for the requested
document. The pathname supplied is relative to the path or directory of the
referencing document.
1
3 IMPORTANT:
3
When designing documents for use in a TDS-Web environment, use the
document-relative form of URL for all links, for two reasons. First, documents
in a TDS-Web environment are copied into an IDS/II database. The resulting
pathname of the document will usually not be the same as the pathname on the
Web server that was used to design and test the document. Second, the
TDS-Web URL for each user will be unique, because each TDS-Web URL
contains a session identifier after the user has logged onto the application.
The following HTML sequence uses document-relative URLs.
<A HREF=«tools.html»>
Programming Tools
</A><BR>
<A HREF=«communications.html»>
</A><BR>
<A HREF=«oltp.html»>
</A><BR>
⇐
⇐
⇐
Note that the updated HREF attributes of the anchors now contain only a document
name. How is the server now able to return the correct document? In fact, every
request from a browser to a server includes an absolute resource name. The
browser forms the absolute resource name by combining the relative resource name
specified in the HREF with the absolute name of the current document.
47 A2 39UT Rev02
2-7
In our example, the current document is:
http://www.GCOS7.bull.com/products.html
When the user selects one of the links on this page, the browser combines the
document base with the relative resource name from the HREF to form a new
absolute URL. For example, if the user selects «Programming Tools», the browser
forms a new URL of:
http://www.GCOS7.bull.com/tools.html
The above example illustrates the importance of using document-relative URLs
whenever possible.
2-8
47 A2 39UT Rev02
2.2
Document Base
As the examples in the preceding subsections illustrate, browsers combine relative
URLs with the document «base» to form an absolute URL. Users of UNIX
systems are familiar with the concept of base names and relative paths, but the
concepts may be new to other readers.
The base name for any document is the fully qualified document pathname minus
the file-name portion. If the current document is located at:
/books/html/tags/anchor.html
the document base is:
/books/html/tags/
Therefore, if the browser has just retrieved a document from:
http://somehost/books/html/tags/anchor.html
the «base» for any relative links on the page is:
http://somehost/books/html/tags/
When resolving document-relative references, the browser forms absolute URLs by
combining the document base with the HREF field of the selected anchor, as
illustrated in the following example:
Current document; the document base is underlined:
http://www.bull.com/books/html/tags/anchor.html
Anchor:
<A HREF=«head.html»>A list of heading tags.</A>
Target document:
http://www.bull.com/books/html/tags/head.html
47 A2 39UT Rev02
2-9
Every time a browser makes a request for a document, it «remembers» the base
name of the document for use in forming absolute URLs for any HREF that
specifies a relative name.
To continue the example, let us look at two additional relative references.
Anchor:
<A HREF=«anchor.html»>A description of the HTML anchor tag</A>
Target document:
http://www.bull.com/books/html/tags/anchor.html
The above example is similar to the first. The anchor specifies a new file name,
and the browser forms a new absolute reference by combining the document base
name with the new file name.
Anchor:
<A HREF=«../elements/index.html»>A list of elements</A>
⇐
Target document:
http://www.bull.com/books/html/elements/index.html
The above example illustrates a slightly more complex relative reference. The
anchor uses a special notation to indicate that a new subdirectory name is being
specified. In previous examples, the browser replaced the file-name portion of the
absolute reference with the file name that was specified in the relative reference.
In this example, the leading «../» indicates that the relative name should be
formed by replacing the file name and the directory name in which it resides. The
browser therefore substitutes «elements» for «tags» in the base URL, and then
replaces the filename «anchor.html» with «index.html».
Any number of directory levels can be specified using this method.
2-10
47 A2 39UT Rev02
Consider the following example.
Anchor:
<A HREF=«../../http/methods/get.html»>Describes HTTP GET method.</A>
Target document:
http://www.bull.com/books/http/methods/get.html
For each leading «../» sequence in the relative HREF of the anchor, the browser
removes one level of subdirectory before performing the replacement. Relative
path information has been substituted into the URL, beginning with the
subdirectory two levels up. The original «html» subdirectory has been replaced
by «http».
CAUTION:
This method of relative reference must be used very carefully in TDS-Web,
because the URL includes a session identifier. “Backing into” the session
identifier via relative referencing can cause the TDS-Web gateway to generate
errors.
For more information about relative pathnames, refer to standard UNIX or DOS
documentation.
47 A2 39UT Rev02
2-11
2.3
TDS-Web URLs
When browsers connect to TDS using the HTTP-DSA gateway a DSA session is
created.
For the browser to re-use the DSA connection and for TPRs to use conversational
transactions, every subsequent message from the browser is required to use the
same DSA session.
To accomplish this, the HTTP-DSA gateway retrieves information from the URL of
each new message and selects a specific DSA connection based on the part of the
URL that contains a session identifier.
Let us examine how TDS-Web uses URLs.
As described in Section 2.1 Uniform Resource Locators, a URL is composed of a
protocol name, server address, and resource name. For TDS-Web applications, the
resource name specifies information that is used by the HTTP-DSA gateway to
execute a specific transaction.
The general format of a TDS-Web URL is as follows:
http://gateway/<node>.<mailbox>/<session id>/<tp7 command>/<options>
where:
http:
is the protocol
gateway
is the server address, including the configured port
number
<rest of URL>
is the resource name
The protocol and host-address portions of a TDS-Web URL are the same as for a
conventional URL that targets any Web server. The format of the rest of the URL
is unique to TDS-Web, as explained in the following paragraphs.
The resource-name portion of the TDS-Web URL consists of four distinct fields:
<node>.<mailbox>/<session id>/<tp7 command>/<options>
field 1
field 2
field 3
field 4
NOTE:
Alternate fields in the preceding two lines are shown in bold only for easy
recognition.
1.
2-12
The first field (field 1) specifies a DSA node name and host mailbox for the
desired TDS.
47 A2 39UT Rev02
2.
The second field (field 2) specifies a DSA session identifier, which will be
unique for each browser occurrence; that is, for each browser window.
The session identifier is assigned by the TDS-Web gateway when the browser
submits a request that contains a zero in this field. That is, when the session
identifier is «/0/», the gateway creates a new DSA connection to the TDS
workstation that is identified by <node>.<mailbox>.
When the connection is established, a unique session identifier is assigned,
and all additional requests from the browser specify the session identifier in
place of the original «/0/».
3.
The third field (field 3) of the resource name specifies a transaction to be
executed.
4.
The fourth field (field 4) is optional and is ignored by the gateway. This field
is used to specify options to be used by the TPR. The TPR uses the
HTTP_GETPATH API to obtain the value of the options field.
For descriptions of this API and the other TDS-Web APIs, refer to Chapter 8
APIs for TDS-Web Runtime Routines.
Note that the transaction name does not appear at the beginning of the input
message. To enable the use of default TP7 command processing, the HTTP-DSA
gateway copies the transaction name to the beginning of the input message.
For example, consider the following URL.
http://gateway/node.mbx/0/logon/12345
When processing this URL, the browser makes a connection to the host at IP
address «gateway» and uses the «http» protocol to submit a «GET» request.
The HTTP request message sent by the browser to the TDS-Web gateway is:
GET /node.mbx/0/logon/12345 HTTP/1.0
The gateway examines this message and copies the Transaction name to the
beginning of the message. The message submitted to TDS is:
logon context=<cid>.<tod><CRLF>
<CRLF>
47 A2 39UT Rev02
2-13
In this example, the gateway copied the «logon» command name to the beginning
of the message. In addition, the gateway detected a session identifier of «/0/»
and established a new session. Because the gateway created a new session, the
new session identifier, composed (as explained in Section 2.4 Context
Management) with the context identifier (cid) and the time of day (tod), is also
passed to the TPR as part of the message prefix.
The information added by the gateway must conform to the HTTP protocol
specification to avoid any ambiguity during the processing of each input message.
Consequently, the line added by the TDS-Web gateway is terminated by a CRLF
sequence. A line that consists of only the CRLF sequence is added to mark the end
of the information in the HTTP-DSA gateway header. The original HTTP request
submitted by the browser follows the gateway header.
The documentation of the TDS-Web runtime library refers to this gateway header
as an “environment”. The HTTP_GETENV family of routines (which are described
in Chapter 7 Developing TDS-Web Applications) are used to process the gateway
header.
1
3 IMPORTANT:
3
Using document-relative URLs in TDS-Web is recommended because using this
form of URL reduces application visibility of the TDS-Web use of the session
identifier in the URL.
Using a server-relative URL requires the HTML document to be aware of
session identifiers and to include some JavaScript code that dynamically creates
links with the full server-relative URL, including the session identifier.
Avoiding server-relative URLs is better practice.
2-14
47 A2 39UT Rev02
2.4
Context Management
For the browser to submit requests using the newly created DSA session, the
browser must be convinced that the base URL contains the newly assigned session
identifier. This persistence of a connection is managed with the help of contexts.
The session identifier is composed with 3 contexts as described below, the two first
contexts are set by the gateway and remain unchanged during a DSA connection,
the third one is set by the application and can be changed during a DSA connection.
The gateway is responsible for checking that a request submitted by the browser
contains the last assigned complete session identifier.
A context set to 0, sent by the browser to GCOS7, is understood by the gateway as
a connection request; inversely, a context set to 0, sent by GCOS7 to the browser, is
understood by the gateway as a disconnection.
Continuing with the previous example, let us assume that the gateway created a
new connection and assigned a session identifier of «1234.abcd». The message
sent by the browser to TDS then is:
txcmd context=1234.abcd<CRLF>
<CRLF>
Usually, if the page returned by the LOGON command contains a relative URL, the
browser forms a new absolute URL using the current document base, which in this
example is:
http://gateway/node.mbx/0/
However, using this document base results in yet another DSA session being
created, and the new message is sent to the new session.
To send messages to the DSA session that was created for the TXCMD request, the
browser must be convinced that the document base is actually:
http://gateway/node.mbx/1234.abcd.5678/
Fortunately, the HTML specification provides a convenient mechanism for this
purpose; the <BASE> tag.
47 A2 39UT Rev02
2-15
The HTML <BASE> tag provides a standard method for an application to
explicitly specify the base for the document that contains the <BASE> tag. Using
the <BASE> tag, the application can use the HREF attribute to specify any
arbitrary document base.
In our example, the application would generate the following sequence of HTML
in response to the original TXCMD request.
<HTML>
<HEAD>
<BASE HREF=«http://gateway/node.mbx/1234.abcd.5678/»>
</HEAD>
<BODY>
Rest of HTML response goes here
</BODY>
</HTML>
When the browser receives a document that contains the <BASE> HTML element,
the browser uses the information provided in the HREF attribute to resolve any
relative references that are contained within the document.
Because every TDS-Web application that operates conversationally needs to
generate <BASE> tags, the TDS-Web software includes the HTML_BASE routine
which can be used to generate the complete <BASE> element. The subroutine
returns the result to the TPR, which can then include the generated <BASE> in
Web pages.
The HTTP-DSA gateway requires the TPR to define an additional applicationspecific suffix for the session identifier. The session identifier generated by the
HTTP-DSA gateway contains two values, shown earlier as <cid>.<tod>. These
two values are:
<cid>
Context identifier, which uniquely identifies a context
block within the gateway
<tod>
Time of day the context block was created
The complete session identifier includes a third field, which contains an
application-specific value. The format of the complete sessions identifier is:
<cid>.<tod>.<appval>
<appval>
an application-context
An application must specify an application-context value whenever the <BASE> is
generated. This context value must be non-zero, and has a maximum size of
32 bits.
2-16
47 A2 39UT Rev02
In addition, an application can specify a new <appval> at any time to provide
additional control over the application. Changing the <appval> portion of the
session identifier prevents the user from submitting requests from bookmarks, thus
providing an additional form of protection against misuse. The application can use
the HTTP_GETCONTEXT routine to determine an application context that is
unique.
Whenever a TPR assigns a new application-context value, the new base
information must be provided to the browser via the <BASE> element. In addition,
the gateway must be notified of the new application context. Communication
between the TPR and the gateway takes place on the HTTP status-response line
using the message portion of the status record (by inserting
CONTEXT=<appval>). If the TPR wants to set the application-context value to
“5678”, then the complete session identifier for our example is:
1234.abcd.5678
The message sent to the browser includes an HTTP response header that identifies
the new application-context value, and an HTML <BASE> element that identifies
the complete session identifier.
HTTP/1.0 200 CONTEXT=5678<NL>
Content-type: text/html<NL>
<NL>
<HTML>
<HEAD>
<BASE HREF=«http://gateway/node.mbx/1234.abcd.5678/»>
</HEAD>
<BODY>
Rest of HTML response goes here
</BODY>
</HTML>
The above example shows an HTTP response header that conforms to the HTTP
version 1.0 specification. The completion code of “200” indicates that the request
was processed successfully. The text that follows the completion code contains the
reserved word “CONTEXT=” and the new application-context value of “5678”.
The gateway copies this value to the context buffer that is associated with the
current DSA session.
NOTE:
The text that follows the completion code is not meaningful to the HTTP
protocol. In TDS-Web, this field is used to communicate with the gateway.
47 A2 39UT Rev02
2-17
Any subsequent input message that specifies the HTTP-DSA gateway context
identifier is validated by the gateway to include the correct time-of-day and
application-context value. Failure to match on either field results in an HTTP
response indicating that the requested resource was not found.
In addition, the <BASE> header element contains the complete session identifier,
including the application-context value. The browser uses this new base
information when constructing absolute URLs for the links that are included in the
current document.
Summary of Context Management
Managing contexts enables the application to avoid receiving the previous request
again.
CTX1=cid CTX2=tod CTX3/4=appval
Opening of
DSA session
HTTP/DSA
Gateway
TPR1
1Request
CTX1.CTX2.xxxx
TXCMD
CONTEXT=CTX1.CTX2
+
Header HTTP
Page 1
CTX3
Account N°: yyyyy
+
BASE HREF=«http://gateway/node.mbx/CTX1.CTX2.CTX3/»
Figure 2-1.
HTTP/1.0 200
CONTEXT=CTX3
Page HTML
Base href=........
Context Management - Summary
TPR1 uses the help routines HTTP_GETCONTEXT in order to get CTX3 and
HTML_BASE to generate the BASE.
2-18
47 A2 39UT Rev02
HTTP/DSA
Gateway
2 Requests
TPR 2
TXCMD
+
Header HTTP
CTX1.CTX2.CTX3
Page 2
CTX4
Account N°: zzzzz
BASE HREF=«http://gateway/node.mbx/CTX1.CTX2.CTX4/»
Figure 2-2.
HTTP/1.0 200
CONTEXT=CTX4
+
Page HTML
Base href=........
Help Routines
TPR2 uses the help routines HTTP_GETCONTEXT in order to get CTX4 and
HTML_BASE to generate the BASE.
In this example (after TPR2), the browser cannot send page 1 again, the validity
control of the contexts is carried out at the MainWay level. The association of
CTX1.CTX2.CTX3 is no longer valid (ERROR 400 Invalid URL)
The DSA session is disconnected by setting the application context to zero.
On reception of context=zero, MainWay initializes the DSA session disconnection.
47 A2 39UT Rev02
2-19
❑
2-20
47 A2 39UT Rev02
3. TDS-Web Environment
Before establishing a TDS-Web processing environment, the site’s TDS-Web
administrator needs to consider the factors described in this section:
• The Browser.
• HTTP-DSA Gateway.
• GCOS 7 System Environment.
• Configuring TDS-Web-related GCOS 7 Software.
47 A2 39UT Rev02
3-1
3.1
The Browser
TDS-Web does not impose a requirement for any specific browser. The TDS-Web
applications developed by the site will have complete control over the level of
HTML and script that is generated by those applications.
Therefore, each site can choose either to standardize on a specific browser or to
develop applications that support features that are common to all browsers.
TDS-Web product was qualified for use with the Microsoft Internet Explorer 3.0
and Netscape Navigator 3.0 browsers. It can operate with subsequent browser
versions.
3-2
47 A2 39UT Rev02
TDS-Web Environment
3.2
HTTP-DSA Gateway
MainWay HTTP-DSA Gateway, which is provided as part of DNS-E Release
V3U1 or later that executes on a MainWay Open Network Processor (ONP).
The MainWay HTTP-DSA Gateway is designed for Internet-based environments,
in which customers or the general public access TDS-Web applications.
This section describes how to configure the networking software that is associated
with a TDS-Web environment.
3.2.1
Configuring MainWay
The browser is connected to a network that is connected to a MainWay that is
running the HTTP-DSA Gateway software.
IDS
GCOS 7
Internet
TCP/IP
HTTP/HTML
MAINWAY
TCP/IP
HTTP/HTML
#8080
TDS
HTTP/DSA
GW
VCAM
SESSION
DSA
FEPS
BROWSER
NetWall
TDS
DSA
HTTP/HTML
TNS
.....
OCS
FCP7
DN
LE
LAN
FDDI
Figure 3-1.
47 A2 39UT Rev02
TDS-Web Network Configuration
3-3
Using MainWay with TDS-Web requires the use of the V3U1 or later version of the
DNS-E software. Complete information about how to configure MainWay is
provided in:
• MainWay System Generation Guide
• Network Generation Language Reference Manual
3.2.2
Configuring MainWay for Use With the MainWay HTTP-DSA Gateway
The MainWay HTTP-DSA Gateway is supported only in the DNS-E V3U1 and
later versions of the MainWay software.
The MainWay Configuration is in the IPS file and in the NGL source file.
• The IPS File
The MainWay Configuration Application for the IPS configuration files now
contains an icon for Web, which allows the site to declare the TCP/IP listen port
for the HTTP-DSA Gateway to TDS-Web. The default for the TCP/IP listen port
is 8080. You can use the Web icon (WEB8) in the Configuration Application to
change this default setting. After defining the TCP/IP listen port, open the SAVE
OPTIONS window and enable TDS-Web. For more information about this
feature, refer to the MainWay Configuration Application Guide.
• The NGL Source File
Configuring the Mailbox (MB) Directive (below), which provides information
about how to define the parameters of the MB directive when using the MainWay
HTTP-DSA Gateway.
Configuring the MainWay for use with TPSM and TDS-Web, which provides
additional information about how to configure the MB directive when the
MainWay HTTP-DSA Gateway is used with the Transaction Processing Session
Monitor (TPSM).
3-4
47 A2 39UT Rev02
TDS-Web Environment
Examples:
The following examples illustrate how to use the MB directive when the MainWay
gateway is connected to TDS-Web.
EXAMPLE 1:
The following simple MB directive supports access from MainWay to TDS-Web
processing on any host:
MB TP7BY0F GWTP -SC BY0F -CT TP01 -DFLT -LTIN 1024 &
-LTOUT 2048 -LEXT TA00 -GKLEXT XANN
❑
In the above example, the –DFLT parameter allows browsers to connect to any
host that is running TDS-Web applications, and to any mailbox on the accessed
host. When a browser enters the following URL:
HTTP://MWAY:8080/SYS2.WEBMB/0/LOGON
the MainWay gateway establishes a connection to host SYS2 and the TDS-Web
mailbox WEBMB.
EXAMPLE 2:
Instead of allowing access to any mailbox, you can choose to limit the connections
that browsers can make by using the -APPL parameter as shown in the following
example:
MB TP7BY0F GWTP -SC BY0F -CT IPS1 –APPL MYTP -LTIN 1024 &
-LTOUT 2048 -LEXT TA00 -GKLEXT XANN
❑
Note that the –DFLT parameter in Example 1 is replaced in Example 2 by the –
APPL parameter, which specifies connection to only the MYTP mailbox.
The –APPL parameter limits access only to the mailbox, not to the host. The
above example would allow access to mailbox MYTP on any host specified in the
URL. You can increase security by ensuring that mailbox names are unique across
all hosts that run TDS-Web applications.
47 A2 39UT Rev02
3-5
When using the MB directive with the –APPL parameter, the URL must contain the
mailbox name of the MB GWTP in the MainWay configuration, instead of the
mailbox name of the TDS-Web application.
In this example, when a browser enters the following URL:
HTTP://MWAY:8080/BY0F.MYTP/0/CONNECT
the MainWay gateway establishes a connection to the host called BY0F and the
TDS-Web mailbox MYTP on that host.
When defining this kind of configuration, using the same name for the MB GWTP
mailbox and the TDS-Web application mailbox can improve ease of use and
minimize potential confusion.
3-6
47 A2 39UT Rev02
TDS-Web Environment
3.3
GCOS 7 System Environment
TDS-Web processing on the GCOS 7 system requires the following environment:
• GCOS 7 TA-V9, TS 9662 or later
• IDS/II Software
The use of TDS-Web is controlled by a Marketing Identifier.
47 A2 39UT Rev02
3-7
3.4
Configuring TDS-Web-Related GCOS 7 Software
3.4.1
Purpose of JPPC
To support a large number of TDS-Web users through a TDS, the system may
require the use of a JPPC segment server.
Without the presence of a JPPC server, a TDS can be accessed by a browser, but
the number of simultaneous TDS-Web users is reduced.
3.4.2
Choosing JPPC
Each TDS-Web user has a dedicated segment to receive the HTTP request.
Therefore, the number of TDS-Web users connected at a given time depends on the
number of available segments that can be accessed by all of the TDS processes.
This number of segments available to a TDS varies according to the TDS, and
mainly depends on the number of files accessed. In any case, it is always less than
250.
When a TDS-Web user connects, and receives the following error message:
"unable to allocate message buffer", this is probably due to a lack of accessible
segments. If the TDS in question does not use JPPC, the system should be
configured with the appropriate JPPC server (see the following section).
If the system has been configured with JPPC, it is not compulsory for all the TDSs
to use the JPPC segments. To avoid using them, simply do not insert the TDS
generation clause described in the following section. Simultaneous TDS-Web
connections to this TDS are then restricted to the number of segments accessible
from all the TDS processes.
3-8
47 A2 39UT Rev02
TDS-Web Environment
3.4.3
Using JPPC
In order to benefit from JPPC, certain action must be taken by the system
administrator and by each TDS administrator who wishes to support a large
number of users.
The system administrator must configure the system and declare a JPPC server,
specifying the following clause in the configuration commands:
JPPCDIM n;
where n is number of the JPPC server selected. This number depends, among other
things, on the number of TDS-Web users connected simultaneously for all the
TDSs. A JPPC segment is dedicated to each user. The number of JPPC segments
used by TDS-Web is therefore added to the number of JPPC segments used for
other applications (IQS, etc.).
The different JPPC service jobs are:
H_JPPC1: for 1,050 segments.
EXAMPLE:
if one TDS accepts 1,000 TDS-Web users and another 250, the number to be taken
into consideration to determine the number of the server is 1,250; therefore, if the
JPPC server is not used by any other devices, the selected server should be
H_JPPC2, declared by “JPPCDIM 2;”.
❑
Once the command has been recorded in the configuration file, the system
administrator should perform the task of configuring the system, then restore it and
restart it in COLD mode.
The administrator of each TDS that is accessible from a browser must also declare
a JPPC use clause in the TDS generation.
NUMBER OF IQS JPPC SEGMENTS IS m.
where m is the expected number of simultaneous TDS-Web users for this TDS
(plus the number of JPPC segments used by IQS, if any).
47 A2 39UT Rev02
3-9
❑
3-10
47 A2 39UT Rev02
4. Preparation of the TDS-Web Product
TDS-Web modules, tools, and elements are located in GCOS 7 system libraries.
This chapter presents the:
• Contents of the System libraries.
• Environment Configuration.
• Installation of a TDS-Web TDS, new TDS or TDS for test or demonstration.
• TDS-Web update procedure.
• Installation for an existing TDS.
• Sharing the HTML Template Database.
• Access TDS-Web TDS applications.
47 A2 39UT Rev02
4-1
4.1
Contents of the System Libraries
Library SYS.HSLLIB
All the source names concerned are prefixed by “WEB7_” in SYS.HSLLIB.
• Specific TPR models: EXITWEB7 for LOGOUT and DISCONNECT,
ABTWEB7 for ON_ABORT_TPR.
• The DOCSTPR, DOCSTPR1, DOCSTPR2, DOCSTPR3, DOCSTPR4,
DOCSTPR5 and DOCTPR6 TPRs are used as programming examples and for
running the installation test transactions, named respectively TEST, DOC1,
DOC2, DOC3, DOC4, DOC5 and DOC6 (Described in Chapter 7 Developing
TDS-Web Applications).
• The STDS (saved with the name WEB7_STDSTEST) including the clauses
required to run the demonstration TDS.
• The members DDLHTML, DMCLHTML, describing the schemas of the IDS/II
HTML page database.
• The sources of the HTML pages for the test TDS (WEB7_HTMLTEST) and for
the administration of the IDS/II database (WEB7_HTMLTEST and
WEB7_HTMLADMIN, respectively).
• The TDS-Web home page, called MAINWAY, that must be installed on a server
if you have a version less than V3U1 of the MainWay HTTP DSA Gateway.
• The JCL for the batch that loads the database (WEB7_LOADHTMEXEC).
• The JCLs for installation (WEB7_INSTALLTEST) and for activation
(WEB7_EXECTEST) of the test TDS.
Library: SYS.HCULIB
• The helper routines (WEB7_HTTPMAINC_C and H_WEB7_MNGW).
• ADMINWEB7 (full IDS) and ADMINWEB7-I (old IDS)
• H_WEB7_GET_HEADER (I) and H_WEB7_GET_RECORD (I)
Library: SYS.HLMLIB
• H_WEB7_LOADHTM to load the HTML page database in full IDS.
• H_WEB7_LOADHTM-I to load the HTML page database in old IDS.
4-2
47 A2 39UT Rev02
4.2
Environment Configuration Procedure
The system administrator must carry out the following actions:
1.
Configure the MainWay HTTP-DSA Gateway by proceeding as indicated in
Section 3.1.2 HTTP-DSA Gateway in Chapter 3 TDS-Web Environment.
2.
Modify the system configuration commands for the use of the JPPC segments
server, if a large number of TDS-Web users is expected for all the TDS. This
operation is described in Section 3.3 Configuring TDS-Web-Related GCOS 7
Software in Chapter 3 TDS-Web Environment. It is not obligatory for running
the demonstration TDS created by the installation procedure. After
modification of the configuration commands, you have to run the
configuration job then; the system must be restored and reloaded in COLD
mode.
3.
Modify the address of the Gateway in the home page delivered.
This home page may be placed on a server accessible to the TDS-Web users
or may be installed on the MainWay itself.
From version V3U1 of MainWay, the TDS-Web home page may also be
installed on the MainWay.
Read Section 4.7 TDS-Web TDS AppIication Access.
47 A2 39UT Rev02
4-3
4.3
Installation of a TDS-Web TDS
The procedure for installation of a TDS-Web TDS consists of two steps:
• Building the HTML page database, in full IDS, and the files necessary for
loading this IDS/II database.
All these files are prefixed by a directory name, <directory>, given by the
administrator and listed in an auto-attachable catalog called
“<directory>.CATALOG”.
• Creating a TDS for test or demonstration purposes; It can either be used as a
model for creating TDSs, or as a basis for an actual TDS. This TDS has the
same name as the directory supplied by the administrator; the name must not be
more than four characters in length.
The preparation and generation of the TDS is performed by the installation
procedure. The two specific TPRs, EXITWEB7 and ABTWEB7, as well as the
ADMINWEB7 database administration TPR, and the DOCSTPRs installation
test TPRs, are linked.
4.3.1
Installation Modes
There are two installation modes:
• First installation: the catalog is built and the files are created, after the old ones
have been destroyed (if they previously existed). Two users with name and
password <directory>1 and <directory>2 are created to test and demonstrate the
installed TDS. All the files are loaded; the IDS/II database is created.
• Update: the presence of the files is verified. If missing, they are re-built and
loaded. The loading of the database does not overwrite HTML pages not
supplied at delivery. The new delivery changes the STDS, after having saved the
old one with the name STDS_yyddd_hhmm where yy indicates the year, ddd
indicates the day in the year, hh indicates the hour, and mm the minutes.
4-4
47 A2 39UT Rev02
4.3.2
Starting the Procedure
The installation procedure JCL is located on the delivered installation media.
Simply enter the following command:
EJR
WEB7_INSTALLTEST LIB=SYS.HSLLIB
Questions are asked concerning:
• Installation medium: name of the disk where the TDS-Web files are created.
• Installation device: disk device where the TDS-Web files are created.
• Directory: name of the catalog directory in which the TDS-Web files will be
cataloged, and used as the name of a TDS created by the installation procedure.
The name of this directory must therefore be limited to 4 characters (default
WEB7).
• First installation or update (default YES, for first installation).
A SYSADMIN project user must activate this procedure.
S: EJR WEB7_INSTALLTEST lib=SYS.HSLLIB
-->10.29 X983 IN WEB7_INS USER=SYSADMIN CLASS=P SPR=7
STATION=BY0F
29/ X983 *** Disk media name where WEB7 libraries locates ***
S: REP 29 FUE2
30/ X983 *** Disk device type (D500 B10 FSA) ? ***
S: REP 30 FSA
31/ X983 *** Directory name [default WEB7 ]
***
S: REP 31 WEB7
32/ X983 *** First installation (YES NO) ? ***
S: REP 32 YES
-->10.31 X983
STARTED
WEB7_INS SYSADMIN P
Figure 4-1.
47 A2 39UT Rev02
Installation Questions and Answers
4-5
4.3.3
Description of the Procedure
Preparation of Files
Creation of the library <directory>.BIN and of the two UFAS files,
<directory>.HTML containing the HTML pages necessary for database
administration, and <directory>.CMD, the command file of the database loading
utility.
The files are cataloged in <directory>.CATALOG, which is created if it does not
exist.
If First Installation:
• deletion of old files, then creation of the files
• creation of the <directory> project in the <directory>.catalog
• Creation of two users <directory>1 and <directory>2, connected to the project
<directory>. The passwords are the user names.
If Update:
• Verification of the existence of the files.
• If a file does not exist, it is created.
-->10.31 X983
-->
FROM
-->
FROM
Figure 4-2.
STARTED
WEB7_INS SYSADMIN P
SYSADMIN X983 : >>> Creation of TDS-Web files >>>>
SYSADMIN X983 : >>> Load TDS-Web files >>>>
Installation Report - Directory Creation
Creating the IDS/II Database
Compiling of the schema from WEB7_DDLHTML and WEB7_DMCLHTML
members of the SYS.HSLLIB library.
CONVERT for use of FULL/IDS.
Creation of the <directory>.HTMLAREA.
-->
FROM
Figure 4-3.
4-6
SYSADMIN X983 : >>>
Creation of HTMLAREA area <<<<
Installation Report - Creation of HTMLAREA
47 A2 39UT Rev02
Loading of the database from the UFAS files by the Load Module
H_WEB7_LOADHTM located in the SYS.HLMLIB library.
-->
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
-->10.33
FROM
SYSADMIN X983 : >>> Loading data base <<<
X983.45
LOADHTM DATE D'EXECUTION : 19980915
X983.45
LOADHTM --------------------------X983.45
LOADHTM
ADD
X983.45
LOADHTM
A-TPRTEST
X983.45
LOADHTM --------------------------X983.45
LOADHTM ADD A-TPRTEST
X983.45
LOADHTM --------------------------X983.45
LOADHTM
ADD
X983.45
LOADHTM
A-LOGOUT7
X983.45
LOADHTM --------------------------X983.45
LOADHTM ADD A-LOGOUT7
X983.45
LOADHTM --------------------------X983.45
LOADHTM
ADD
X983.45
LOADHTM
A-ADMLOGOUT7
X983.45
LOADHTM --------------------------X983.45
LOADHTM ADD A-ADMLOGOUT7
X983.45
LOADHTM --------------------------X983.45
LOADHTM
ADD
X983.45
LOADHTM
A-ADMIN-WEB7
X983.45
LOADHTM --------------------------X983.45
LOADHTM ADD A-ADMIN-WEB7
X983.45
LOADHTM --------------------------X983.45
LOADHTM
ADD
X983.45
LOADHTM
A-ADMIN-WB71
X983.45
LOADHTM --------------------------X983.45
LOADHTM ADD A-ADMIN-WB71
X983.45
LOADHTM *********** END OF FILE ************
X983.45
LOADHTM *************************************
X983.45
LOADHTM *
FIN
*
X983.45
LOADHTM *************************************
Figure 4-4.
47 A2 39UT Rev02
Installation Report - LOADHTM
4-7
Creating a TDS (that of the <directory>)
TDS preparation started with TP7PREP.
--> FROM SYSADMIN X983: >>>
<<<
TP7PREP
<<<
<<<
--> FROM SYSADMIN X983: 1) Release possible catalog
--> FROM SYSADMIN X983: 1-bis) Verify if the auto-attachable
catalog
--> FROM SYSADMIN X983:
WEB7 already exists.
--> FROM SYSADMIN X983: 7) Build a node called WEB7 in the
WEB7.CATALOG
--> FROM SYSADMIN X983: 8) Step H_TP7PREP
--> TV40 TP7PREP COMPLETED FOR TDS: WEB7
--> FROM SYSADMIN X983: 9) Check list from CATALOG
Figure 4-5.
Installation Report - TP7PREP
Modification of the delivered STDS file in the <directory>.SLLIB library.
--> FROM SYSADMIN X983 : >>>
<<<
--> FROM SYSADMIN X983 : >>> Member modification STDS<<<
--> FROM SYSADMIN X983 : >>>
<<<
Figure 4-6.
Installation Report - Modifying STDS
Starting TDS generation with TP7GEN.
--> FROM
SYSADMIN X983 : >>>
<<<
--> FROM
SYSADMIN X983 : >>>
TP7GEN
<<<
--> FROM
SYSADMIN X983 : >>>
<<<
-->10.35 X984 IN
TP7GEN USER=SYSADMIN CLASS=C SPR=7 X0983 BY0F
-->10.35 X984
STARTED
TP7GEN
SYSADMIN C
--> FROM
SYSADMIN X984 : ==> TDS WEB7 GENERATION SUCCESSFUL.
-->10.36 X984.17
COMPLETED TP7GEN
SYSADMIN C
Figure 4-7.
4-8
Installation Report - TP7GEN
47 A2 39UT Rev02
Compiling and linking the TPRs delivered: DOCSTPRs, ADMINWEB7 (link
only), ABTWEB7 and EXITWEB7.
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
-->
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
Figure 4-8.
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
SYSADMIN
X983
X983
X983
X985
X983
X985
X983
X985
X983
X985
X983
X985
X983
X986
X983
X987
X983
X988
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
<<<
TPRs Compilation
<<<
DOCSTPR
<<<
LINK DOCSTPR CORRECT <<<
DOCSTPR1
<<<
LINK DOCSTPR1 CORRECT <<<
DOCSTPR2
<<<
DOCSTPR3
<<<
DOCSTPR4
<<<
ADMINWEB7
<<<
LINK ADMINWEB7 CORRECT <<<
ABTWEB7
<<<
LINK ABTWEB7 CORRECT <<<
EXITWEB7
<<<
LINK EXITWEB7 CORRECT <<<
Installation Report - Compiling TPRs
End of Installation
--> FROM
SYSADMIN X989: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
--> FROM
SYSADMIN X989: >>>
>>>
--> FROM
SYSADMIN X989: >>> Installation WEB7 terminated
>>>
--> FROM
SYSADMIN X989: >>> Check the configuration with
>>>
--> FROM
SYSADMIN X989: >>> appropriate JPPC server
>>>
--> FROM
SYSADMIN X989: >>> You can START your TDS with
>>>
--> FROM
SYSADMIN X989: >>>
>>>
--> FROM
SYSADMIN X989: >>> EJ WEB7_EXECTEST,,SYS.HSLLIB VL=WEB7 >>>
--> FROM
SYSADMIN X989: >>>
>>>
--> FROM
SYSADMIN X989: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-->10.36 X989.0
COMPLETED WEB7_INS
SYSADMIN C
Figure 4-9.
47 A2 39UT Rev02
Installation Report - End of Installation
4-9
4.3.4
The Demonstration TDS
Characteristics
The demonstration TDS has the following characteristics:
• Its name is the name of the directory given at the installation: <directory>.
• Two users <directory>1 and <directory>2, have passwords identical to their
name.
• There is no JPPC clause in the generation.
• It references the database of the HTML pages in Full IDS/II mode.
• Six transactions are generated: the five example transactions TEST, DOC1,
DOC2, DOC3 and DOC4 corresponding respectively to the DOCSTPR,
DOCSTPR1, DOCSTPR2, DOCSTPR3 and DOCSTPR4 TPRs, and the HTML
page database administration transaction, ADMIN.
• It does not contain an ASSIGN H_BJRNL clause, but this can be added;
otherwise, you must answer a JL07 question about the location of the Before
Journal files.
The JCL for running the TDS is called WEB7_EXECTEST and is located in the
SYS.HSLLIB library.
The start-up is performed by giving the name of the TDS as a VALUE, for
example:
EJ WEB7_EXECTEST,,SYS.HSLLIB VL=WEB7
Running the TDS Demonstration Transactions
Once the TDS is running, you can log on to the TDS from the browser by
addressing the home page. This must be completed as indicated in Section 4.7
TDS-Web TDS Application Access. The name of the transaction to be executed
(TEST, DOC1, DOC2, DOC3, DOC4 or ADMIN) must be set in the “TP7
Command” field.
4-10
47 A2 39UT Rev02
4.3.5
Following the Installation
If a demonstration TDS was created by the installation procedure, all the created
files can serve as reference libraries for the product delivered or can be used in
relation to the TDS created.
New TDSs can be created either by:
• running the installation procedure again with a new <directory>, or
• copying in the reference TDS the elements necessary for running the product.
To do this, refer to Chapter 5 TDS Considerations When Using TDS-Web.
The previously existing TDS can also receive TDS-Web transactions. A few
operations are required to make TDS-Web transactions and non-TDS-Web
transactions co-exist. Refer to Chapter 5 TDS Considerations When Using
TDS-Web.
The system administrator can delete the test users created by the installation.
47 A2 39UT Rev02
4-11
4.4
TDS-Web Update Procedure
The update of the product takes place in a similar way to the first installation. In
all cases the libraries, if they exist, are not erased; the same applies to the HTML
page database. The STDS located in the source library of the TDS (.SLLIB) is
saved before modification with the name STDS_yyddd_hhmm where yy indicates
the year, ddd indicates the day in the year, hh indicates the hour, and mm the
minutes.
If changes have been made to the delivered TPRs or the TDS-Web routines, all the
existing TPRs must be re-linked before they are run.
4-12
47 A2 39UT Rev02
4.5
Installation for an Existing TDS
Previously existing TDS can also receive TDS-Web transactions. A few operations
are required to make TDS-Web transactions and non-TDS-Web transactions
co-exist. Refer to Section 5.1.4 Adapting an Existing TDS in Chapter 5 TDS
Considerations When Using TDS-Web.
In addition to these modifications, an HTML Template Database must be created.
This can be done by running the job WEB7_CRDB:
EJR
WEB7_CRDB
LIB=SYS.HSLLIB
A database with the name of <directory>.HTMLAREA is created and loaded with
the help of two files : <directory>.HTML containing HTML pages (needed for
loading and administrate the database) and <directory>.CMD containing the
loading commands. A private binary library named <directory>.BIN is also created
and contains the compiled schema of the database under the chosen format : full
IDS or old IDS.
Questions are asked concerning:
• Installation medium: name of the disk where the TDS-Web libraries are created.
• Installation device: disk device where the TDS-Web libraries are created.
• directory: name of the catalog directory in which the files will be created. The
catalog must previously exist and be auto-attachable.
• Mode in which the database has to be accessed: full IDS or old IDS.
47 A2 39UT Rev02
4-13
S: ejr web7_crdb,,sys.hsllib
S:
-->10.23 X337 IN
WEB7_CRB USER=SYSADMIN CLASS=P SPR=7
STATION=BY0F
34/ X337 *** Disk media name where libraries locates ***
S: rep 34 fue2
35/ X337 *** Disk device type (FSA B10 D500) ? ***
S: rep 35 fsa
36/ X337 *** Directory name [default WEB7 ]
***
S: rep 36 WEB7
37/ X337 *** Full IDS data base (YES or NO) [default YES] ? ***
S: rep 37 no
-->10.24 X337
STARTED
WEB7_CRB SYSADMIN P
-->
FROM
SYSADMIN X337 : >>> Creation of WEB7 files >>>>
-->
FROM
SYSADMIN X337 : >>> Load WEB7 files >>>>
-->
FROM
SYSADMIN X337 : >>> Creation of HTMLAREA area <<<<
-->
FROM
SYSADMIN X337 : >>> Loading data base <<<
-->10.24 X337.17
LOADHTM-I Date: WED, 27 JAN 1999 10:24:25 GMT.
-->10.24 X337.17
LOADHTM-I ---------------------------->10.24 X337.17
LOADHTM-I
DEL
-->10.24 X337.17
LOADHTM-I
*
-->10.24 X337.17
LOADHTM-I ---------------------------->10.24 X337.17
LOADHTM-I PAGE NOT FOUND FOR INSERTION: A-ADMLOGOUT7
-->10.24 X337.17
LOADHTM-I PAGE NOT FOUND FOR INSERTION: A-ADMIN-WEB7
-->10.24 X337.17
LOADHTM-I PAGE NOT FOUND FOR INSERTION: A-ADMIN-WB71
-->10.24 X337.17
LOADHTM-I ************* END OF FILE *************
-->10.24 X337.17
LOADHTM-I ---------------------------->10.24 X337.17
LOADHTM-I
ADD
-->10.24 X337.17
LOADHTM-I
*
-->10.24 X337.17
LOADHTM-I ---------------------------->10.24 X337.17
LOADHTM-I ADD A-ADMLOGOUT7
-->10.24 X337.17
LOADHTM-I ADD A-ADMIN-WEB7
-->10.24 X337.17
LOADHTM-I ADD A-ADMIN-WB71
-->10.24 X337.17
LOADHTM-I ************* END OF FILE *************
-->10.24 X337.17
LOADHTM-I *************************************
-->10.24 X337.17
LOADHTM-I *
FIN
*
-->10.24 X337.17
LOADHTM-I *************************************
-->
FROM
SYSADMIN X337 : >>> Modification access data base <<<
-->10.24 X337.18
COMPLETED WEB7_CRB SYSADMIN P
Figure 4-10.
4-14
Example of Creation of an HTML Template Database
47 A2 39UT Rev02
4.6
Sharing the HTML Template Database
The installation creates a HTML page database in the same directory as the
installed TDS. At each initial installation, a database is created.
The system or TDS administrators are responsible for the choice to create a
database for each TDS or to share the same database between all or some of the
TDSs. You then verify the sharing mode of the database “ .HTMLAREA ” and
change the name of the database in the TDSs execution jobs and the job for loading
the database. The same applies to the LOCALHOST file and the command file
required for loading the database. Read the text related to the loading of the
HTML page database in Chapter 6 HTML Template Database.
47 A2 39UT Rev02
4-15
4.7
TDS-Web TDS AppIication Access
The TDS-Web user connects to a GCOS 7 TDS by means of a home page. This
page is located in the SYS.HSLLIB library with the name WEB7_MAINWAY. It
is presented as follows:
Figure 4-11.
MainWay Welcome Page
The MainWay address must be changed in the home page delivered, then it must be
placed on a server accessible to the TDS-Web users or directly onto the MainWay.
4-16
47 A2 39UT Rev02
The home page can be changed by the administrator, but certain fields of the page
are obligatory and cannot be modified. These are the names of the variable fields
to be completed such as “_NODE”, “_MAILBOX”, “_USER”, “_PROJECT”,
“_BILLING”, “_PASSWORD”, and “_TP8CMD”.
1
2
3
4
5
<HTML>
<HEAD>
<TITLE>MW-Welcome</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#DDCCEE">
6. <BASE HREF="http://mainway location:8080">
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<H1>Welcome to WEB7 welcome page.</H1>
<P ALIGN="CENTER"><HR></P>
<P>Please enter the name of the application you wish
to connect to, along with your user information
Press the LOGON button to connect to
the
application.</P>
<FORM METHOD="POST" ACTION="/0/">
<TABLE CELLSPACING=0 BORDER=0 CELLPADDING=7 WIDTH=499>
<TR><TD WIDTH="30%" VALIGN="TOP">
<P>Node:</TD>
<TD WIDTH="70%" VALIGN="TOP" COLSPAN=2>
<P>
<INPUT TYPE="TEXT" WIDTH="32" NAME="_NODE">
</TD>
</TR>
Figure 4-12.
47 A2 39UT Rev02
Example of the Top of the MainWay Page
4-17
❑
4-18
47 A2 39UT Rev02
5. TDS Considerations When Using
TDS-Web
The implementation of TDS-Web involves the assimilation of concepts specific to
this new environment, compared to the normal use of FORMS. Furthermore, the
TDS administrator has to perform a certain number of operations to allow the TDS
to support TDS-Web users.
The points concerned are:
• TDS administration,
• specific TPRs,
• programming the TPRs,
• the visibility of the end user.
47 A2 39UT Rev02
5-1
5.1
Administration of the TDS
5.1.1
The TDS administrator can choose to use a database of HTML pages specific to
their TDS, or shared between several TDSs. This database is created by installing a
TDS-Web TDS and is called <directory>.HTMLAREA. The TDS administrator
can choose whether or not to change the name, and adapt the TDS start-up JCL as
well as that of the batch that loads the database.
The administrator must also make sure that this IDS/II database containing the
HTML pages is cataloged with the options:
SHARE=MONITOR and JOURNAL={BOTH|BEFORE}.
The use of Before and After Journals depends on the level of integrity the TDS
administrator wishes to ensure. We recommend BOTH, with the use of the Before
and After Journals.
5.1.2
TDS Generation
The TDS administrator may or must include a certain number of clauses in STDS.
Clauses Concerning the Full IDS Database Containing the HTML Pages
Clauses to describe and access the Full IDS/II database must be added to the TDS
generation.
In TDS SECTION.
...
USE IDS-SUB-SCHEMA.
In INPUT-OUTPUT SECTION.
...
IDS-DEFINITION.
DB HTMLSCHEMA.
REALMS ARE HTMLAREA.
In PROCESSING-CONTROL.
...
FILE INTEGRITY FOR HTMLAREA IS {HIGH|MEDIUM}.
5-2
47 A2 39UT Rev02
Clauses Concerning the old IDS Database Containing the HTML Pages
Clauses to describe and access the old IDS/II database must be added to the TDS
generation.
In TDS SECTION.
...
...
In INPUT-OUTPUT SECTION.
FILE-CONTROL.
...
SELECT EXTERNAL FICDOS ASSIGN FICDOS
ORGANIZATION UFF INDEXED
ACCESS DYNAMIC
RECORD KEY IS REC-KEY
FILE STATUS IS FIC-STATUS
FLR.
*END.
...
TDS-FILE-DEFINITION.
FD FICDOS
BLOCK 10 RECORDS
LABEL RECORD STANDARD
RECORD 206.
01 REC-FIC.
02 REC-KEY
PIC X(6).
02 REC-DATA
PIC X(200).
*END
IDS-DEFINITION.
DB HTMLSCHEMA.
REALMS ARE HTMLAREA.
In PROCESSING-CONTROL.
...
PROCESSING-MODE OF FICDOS IS INPUT-OUTPUT.
FILE INTEGRITY FOR HTMLAREA IS {HIGH|MEDIUM}.
FILE-INTEGRITY FOR FICDOS IS MEDIUM.
...
In WORKING-STORAGE.
77 FIC-STATUS PIC XX.
...
In TRANSACTION SECTION.
MESSAGE "ADMIN" ASSIGN TO ADMINWEB7-I
...
47 A2 39UT Rev02
5-3
The FILE INTEGRITY clause causes the use of the Before and After Journals for
HIGH, and of the Before Journal only for MEDIUM. The choice is therefore the
level of integrity the TDS administrator wishes to ensure. We recommend HIGH,
with the use of the Before and After Journals.
Optional JPPC Clause
TDS-Web requires a type 2 segment for each browser logged on. To support a
large number of users, the use of the JPPC segments server is required.
If this server is selected, the TDS administrator must make sure that the system
administrator has allowed the JPPC server in the system configuration. See
Section 3.3 Configuring TDS-Web-Related GCOS 7 Software in Chapter 3
TDS-Web Environment.
In this case, the JPPC server is initiated at system start-up. A generation clause
specifying the number of TDS-Web users simultaneously logged-on must be
included in the STDS. For example, if this number is 400, the following clause
must be inserted:
In the TDS SECTION.
...
NUMBER OF IQS JPPC SEGMENTS IS 400.
If the system has not been configured for JPPC, this clause must be removed. If it
is not present for a TDS, this leads to a restriction of the number of TDS-Web users
for this TDS.
If a TDS is declared using XCP2 and XCP2 has not been properly declared in the
NETGEN, the TDS runs but does not use JPPC and the TDS-Web connections run
in degraded mode (this means that the number of simultaneous connections is
limited).
PRIVATE STORAGE Clause
To manage the messages and data sent or received by the user, TDS-Web requires
structures stored in a reserved part of PRIVATE_STORAGE. This reserved part is
3000 bytes. The TDS administrator must therefore increase the size required by his
or her own transactions by this amount.
If there is no PRIVATE STORAGE specific to this TDS, the following clause must
be inserted:
In the TDS SECTION.
...
PRIVATE-STORAGE IS 3000.
5-4
47 A2 39UT Rev02
If the TDS needs the use of the PRIVATE STORAGE for its TPRs, it will increase
the size of the PRIVATE STORAGE, which will then be made up of
3000 characters for the part reserved to TDS-Web, followed by the part reserved
for the TPRs. For example, if the part specific to the TPRs is 500 characters, the
following clause must be inserted:
In the TDS SECTION.
...
PRIVATE-STORAGE IS 3500.
Similarly, the programmer of the TPRs, whether a TDS-Web TPR or not, must
reserve the first 3,000 characters of the PRIVATE-STORAGE, starting the
TRANSACTION-STORAGE (the third parameter of any TPR including the
PRIVATE-STORAGE) for routines specific to TDS-Web. It is recommended to
use the fourth parameter of all TPRs for transaction-storage.
NOTE:
Here we call the “TRANSACTION-STORAGE” the third parameter of a TPR
that includes the PRIVATE-STORAGE at the beginning, and
“transaction-storage” is the actual transaction storage proper, the fourth
parameter of any TPR.
Declaring the LOGOUT and DISCONNECT TPRs
The TDS administrator must include a MESSAGE ASSIGN clause in the TDS
generation for LOGOUT and DISCNCT transactions, assigning it to the TPR
EXITWEB7, supplied by TDS-Web or to be enhanced and/or renamed from the
TPR supplied.
MESSAGE LOGOUT ASSIGN TO EXITWEB7...
MESSAGE DISCNCT ASSIGN TO EXITWEB7...
47 A2 39UT Rev02
5-5
5.1.3
The TDS Start-up JCL
A model of the TDS start-up JCL, WEB7_EXECTEST is supplied in the
SYS.HSLLIB library.
This JCL must include the assignment of the IDS/II database containing the HTML
pages. Thus, for the TDS called “WEB7”, we have:
$STEP ...
. ..
ASG DDLIB1 WEB7.BIN SHARE=DIR;
ASG HTMLAREA WEB7.HTMLAREA;
. ..
ASG IDSOPT *IDSWEB7;
$ENDSTEP;
$INPUT IDSWEB7 PRINT;
SCHEMA NAME IS HTMLSCHEMA.
IGNORE TRANSIENT STATE OF HTMLAREA.
STATISTICS WITH TIMING.
$ENDINPUT;
5.1.4
Adapting an Existing TDS
To adapt an existing TDS for use with TDS-Web, the TDS administrator must:
• Apply the modifications described above.
• Check that all TPRs have been modified and have an adequate PRIVATE
STORAGE size, so that the first 3000 characters can be reserved for the needs of
TDS-Web.
• Check that all TPRs declaring a transaction-storage use the fourth parameter of
TPR, or have correctly changed the size of the PRIVATE-STORAGE, as
described above.
• Check that all the ON_ABORT_TPR are coded in the same way as the model
supplied.
• Check that the DISCONNECT and LOGOUT TPRs have been changed in
compliance with the model supplied on delivery.
• Check that the TPRs referencing the HTML Template Database have been
compiled with the option DDLIB=<directory>.BIN.
• Create or copy an HTML Template Database. Refer to Section 4.5 Installation
for an Existing TDS.
• Insert an ASSIGN command for this database in TDS startup JCL.
5-6
47 A2 39UT Rev02
5.2
The Specific TPRs
Specific TPRs for abort, LOGOUT, and disconnection, are supplied in source code
and in binary form. It is possible to enhance or rename them, but the delivery
contains the requisite minimum for these three functions to operate properly. The
TDS administrator must make sure that these TPRs are linked with the TDS-Web
routines.
In the case of a TDS that has TDS-Web transactions and other transactions that are
not TDS-Web, the TDS-Web routines to be called must be called with a test for the
type of terminal. The type of terminal is retrieved using the TERMID primitive.
CALL "TERMID" USING ADDRESS OF T-ID.
IF MODEL = 8352
*
8352 = 20A0(Hexa)
CALL "HTTP_...
5.2.1
Logout TPR
A logout TPR is required for TDS-Web. It is supplied with the product under the
name EXITWEB7, and can be renamed and enhanced by the programmer. It must
include a call to a TDS-Web routine, HTTP_FREEWEB7, to free the resources
specific to TDS-Web in the event that the terminal is a browser, coded as follows:
CALL "HTTP_FREEWEB7" USING ADDRESS OF TDS-STORAGE, ADDRESS OF
TRANSACTION-STORAGE.
generation.
47 A2 39UT Rev02
5-7
5.2.2
Disconnect TPR
A disconnect TPR is required for TDS-Web. It is supplied with the product under
the name EXITWEB7, and can be renamed and enhanced by the programmer. It
must include a call to a TDS-Web routine, HTTP_FREEWEB7, to free the
resources specific to TDS-Web, if the terminal is a browser, coded as follows:
CALL "HTTP_FREEWEB7" USING ADDRESS OF TDS-STORAGE, ADDRESS OF
generation.
5.2.3
Abort TPR
An abort TPR is required for TDS-Web. It is supplied with the product under the
name ABTWEB7, and can be renamed and enhanced by the programmer. If the
terminal is a browser, it is mandatory that it includes a call to a TDS-Web routine,
HTTP_ABORT, to send a message to the TDS-Web user and free the resources
specific to TDS-Web, coded as follows:
CALL "HTTP_ABORT" USING ADDRESS OF TDS-STORAGE, ADDRESS OF
The first TPR of each transaction must store the name of the ABORT TPR in the
TDS STORAGE at the beginning of its processing.
5-8
47 A2 39UT Rev02
5.3
Programming the TPRs
5.3.1
TDS-Web TPR
Chapter 7 Developing TDS-Web Applications the way to code the exchanges with a
browser terminal.
To adapt an existing TPR for the use of TDS-Web, the TDS programmer must:
• Change the size of the PRIVATE STORAGE, if there was one.
• Preferably use the fourth parameter of the TPR as transaction-storage, or
otherwise, take account of the modification of the size of the
PRIVATE_STORAGE.
• Declare the ON_ABORT_TPR at the start of the first TPR of a transaction.
• Change the exchange primitives (RECEIVE and SEND) to HTTP call routines.
All exchanges must end with the sending of an EGI message (CALL
“HTTP_SEND” USING ... LEVEL=3...).
• Get the contents of the various fields of the HTTP request.
• Find in the database of HTML pages the page associated with the request.
• Compose the HTTP reply.
During the last TPR of a transaction, the TPR programmer must allow for a field in
the HTML page to link with a new transaction or the possibility of clicking on a
LOGOUT button.
Furthermore, during the same connection of a browser to a TDS, the programmer
may wish to make sure that the request received corresponds to the last HTML
page sent; to do this, an application context can be obtained, that is guaranteed
uniquely by a TDS-Web call routine (HTTP_GETCONTEXT). This context is
kept by the HTTP DSA Gateway which, by controlling the URLs sent by the
browser, checks the consistency between HTTP requests and the running of the
transactions.
5.3.2
TPR Other Than TDS-Web
For an existing TDS which has certain transactions that are non TDS-Web
transactions, the size of the PRIVATE STORAGE of all the TPRs should be
changed, and preferably use the fourth parameter of any TPR to access the
transaction-storage (otherwise, take account of the change in the size of the
PRIVATE-STORAGE). Any TPRs modified as a result must be recompiled.
47 A2 39UT Rev02
5-9
5.4
End User
5.4.1
Welcome Page
The welcome page allows the user of the browser to connect to a TDS located on a
GCOS 7 system. The request must be completed in capitals:
• Node: name of the GCOS 7 machine
• Mailbox: name of the TDS
• PersonID, Project, Billing, Password: user id
• TP7 Command: name of the first transaction to execute.
Then click on the LOGON button. The RESET button is used to clear the entry
fields.
5.4.2
Specific Features of TDS-Web Transactions
TDS manages all the connections coming from a browser as a first connection.
There is no concept of reconnection after incident. Consequently, the browser is
not reconnected nor its transaction restarted following a TDS Reinit, abort or crash.
It has to reconnect itself and re-start the transaction.
Service messages and unsolicited messages sent by the TDS monitor such as those
sent by the SNDTU and MDTMOT commands are not received by a browser.
The TDS master cannot be connected thru a browser.
Access to a TDS from a browser terminal is not controlled by the product SA7
(Secur’Access7).
Breaks are not managed on a browser connection. When a user closes the browser
without first disconnecting, it is impossible for that user to reconnect as long as:
1.
either the master of the TDS has not passed a CTC disconnection command,
2.
or the MainWay has not cut off the connection with the TDS, which happens
after fifteen minutes.
SPAWNING transaction is not supported.
As long as the first connection of a TDS-Web user is not completed, the LSTC
command, which counts, terminated transactions shows a transaction counter at 0.
5-10
47 A2 39UT Rev02
6. HTML Template Database
The HTML Template database is an IDS/II database that is used as the repository
for HTML documents (Web pages) that are generated by the site and used in
TDS-Web.
HTML documents are written to this database by using the HTML Administrative
Utility.
6.1
Management of the HTML Template Database
6.1.1
Management
The TDS-Web installation procedure enables you to allocate and generate a
database serving as a model. The database is loaded from the elements contained
in the LOCALHOST file which is built from delivered elements contained in
system libraries (refer to Chapter 4 Implementing the TDS-Web Product). The
database can be in IDS or Full IDS format.
6.1.2
Database access
To facilitate TPR development, TDS-Web provides routines for easier access to the
IDS/II database. With such routines, accesses to the IDS/II database do not need to
be programmed for accessing pages in HTML Template Database.
For a complete description of each routine and its calling sequence, refer to
Chapter 9 HTML Template Database Access Routines.
47 A2 39UT Rev02
6-1
6.1.3
Monitoring
Monitoring the evolution of HTML Template database can be achieved with the
help of DBUTILITY, which is a standard IDS/II utility.
This tool enables in particular to obtain, with the help of options supplied by the
ANALYZE command, graphs which schematize in a simple way the occupation of
the HTMLAREA area.
An example of JCL, WEB7_ANALYSE, can be found in the SYS.HSLLIB library.
Example of DBUTILITY execution :
10
20
30
40
50
60
70
80
90
100
110
120
130
140
$JOB ANALYSE;
$STEP H_DBUTILITY SYS;
SIZE 200 POOLSIZE=80;
ASG
COMFILE *COM1;
ASG
DDLIB1
WEB7.BINFIDS;
ASG
HTMLAREA WEB7.HTMLAREA
SHARE=MONITOR ACCESS=READ;
DEF
HTMLAREA READLOCK=STAT;
$ENDSTEP;
$INPUT COM1 PRINT;
ANALYSE
AREA NAME IS HTMLAREA
REPORT NPGVUSP
WITH GRAPH
150
NPGVNRC
WITH GRAPH
160
170
180
200
210 $ENDINPUT;
220 $ENDJOB;
NCCVNCR
NCCVNPG
NCRVNIO
NRCVTYPE.
Main options:
NPGVUSP
number of pages corresponding to the space used in
the page
NPGVUSP
number of pages corresponding to the number of
articles in the page
NRCVTYPE
number of articles per type of article
For more information, refer to IDS/II Administrator's Guide
6-2
47 A2 39UT Rev02
6.1.4
Enlargement of the Database
For more information about IDS/II databases, refer to IDS/II Administrator's Guide
and Database Reorganization (DBREORG) User's Guide.
According to the number of HTML documents to store in the database, it may be
necessary to increase the size of the supplied model.
Since GCOS 7 TS 9764, a procedure is supplied with TDS-Web for easier
reorganization, which is carried out from an estimation of the volume by the user.
This estimation is calculated from a number of HTML pages to be stored in the
IDS/II database.
This procedure, WEB7_REORG_HTMLAREA, is located in the SYS.HBINLIB
library; it enables the following operations from two GCL forms:
6.1.4.1
•
entry of the parameters required for allocating the new database,
•
unloading of the database into a sequential UFAS file whose structure and
organization are those of the file used by the HTML page administration
processes supplied with TDS-Web,
•
allocation of the new area according to the user-supplied criteria,
•
reloading of the new database from the previously created UFAS file.
Parameter entry and UFAS file allocation
The following parameters are required for reorganizing the database:
database type, IDS or Full IDS?
Number of HTML pages to be stored in the new database
EFN of the old area
EFN of the binary library including the schema
EFN, media and allocation device of the new area
EFN, media and allocation device of the UFAS file
EFN of the SL library including the schema description
The UFAS file
The UFAS file allocation parameters are as follows:
UFAS
CISIZE
RECSIZE
47 A2 39UT Rev02
= SEQ
= 2048
= 250
6-3
RECFORM
SIZE
INCRSIZE
= F
= 5
= 1
The questionnaire
The parameters are entered via two GCL forms.
1/2
NBPG
IDSTYPE
KDDLIB
SLLIB
HTMLAREA
WEB7_REORG_HTMLAREA
TDS-Web Data Base Reorganization
+ number of HTML pages
+ 1 if Full IDS, 0 else
+ schema library
-->:
1
source library (DDL, DMCL)
+ area assign parameters
SAVENAME
+ save file name
MDSAVE
MEDIA save file
DVCSAVE
DEVICE save file
CATSAVE
+ CAT or UNCAT
------------------------------------------------------------------------------
The SAVENAME file is created if missing. Otherwise its content is overwritten.
6-4
47 A2 39UT Rev02
2/2
WEB7_REORG_HTMLAREA
NEWAREA
MDAREA
DVCAREA
CATAREA
+
+
+
+
-->:
name of the new area
media of the new area
device of the new area
CAT or UNCAT
---------------------------------------------------------------------------
The EFN of the NEWAREA area must not already exist.
After the reorganization, the user can choose between the following solutions to
take the new area into account:
• modify the JCLs referring to the HTMLAREA area,
• or rename the new area with the name of the old area.
6.1.4.2
Unloading the database
The database is unloaded into the UFAS file through the WEB7_SAVEHTM
program. Its activation is transparent to the user.
Description of HTML UFAS file
1
2
3
4
5
6
7
8
47 A2 39UT Rev02
FD HTML LABEL RECORD STANDARD.
01 RECORD-PAGE-HTML.
02 ARTICLE-HTML
PIC X(250).
02 VENTILATION-RECORD REDEFINES ARTICLE-HTML.
03 V-0-CAR
PIC X OCCURS 250.
02 VENTILATION-RECORD-1 REDEFINES ARTICLE-HTML.
03 V-1-HEADER
PIC X(10).
03 FILLER
PIC X.
6-5
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
6-6
02
02
02
02
02
02
02
02
03 V-1-PAGE-NAME
PIC X(195).
03 FILLER
PIC X(44).
VENTILATION-RECORD-2 REDEFINES ARTICLE-HTML.
03 V-2-HTML
PIC X(06).
03 FILLER
PIC X(244).
03 V-3-END-HTML
PIC X(007).
03 FILLER
PIC X(243).
03 V-4-WEB7
PIC X(11).
03 FILLER
PIC X(239).
03 V-5-END-WEB7
PIC X(012).
03 FILLER
PIC X(238).
03 V-6-HTMLDATE
PIC X(12).
03 FILLER
PIC X.
03 V-6-DATECRE
PIC X(10).
03 FILLER
PIC X.
03 V-6-TIMECRE
PIC X(10).
03 FILLER
PIC X.
03 V-6-DATEMOD
PIC X(48).
03 V-6-TRAIL
PIC X(03).
03 FILLER
PIC X(164).
HEADER-RECORD REDEFINES ARTICLE-HTML.
03 FILLER
PIC X(10).
03 HEADER-DATA
PIC X(192).
03 FILLER
PIC X(048).
HTML-RECORD REDEFINES ARTICLE-HTML.
03 HTML-DATA
PIC X(250).
ACTION-RECORD REDEFINES ARTICLE-HTML.
03 ACTION-DATA
PIC X(125).
03 FILLER
PIC X(125).
47 A2 39UT Rev02
6.1.4.3
Creating the new area
The new area creation procedure includes the following steps:
•
Save of the WEB7_DMCLHTML member of the SYS.HSLLIB library in a
member named WEB7_DMCLHTML_yyddd_hhmm.
•
DMCL modification in the WEB7_DMCLHTML member of the SYS.HSLLIB
library. Replacement of the number of pages in the HTMLAREA area by the
number calculated from the number of HTML pages to be stored, as specified
by the user in the initial questionnaire.
1
2
3
4
5
6
7
8
9
•
6.1.4.4
SCHEMA NAME IS HTMLSCHEMA
EXTEND NUMBER OF AREAS TO 4
EXTEND GLOBAL POINTERS TO 4 BYTES
NO LOCAL POINTERS.
PAGE-SIZE IS 4096
NUMBER OF LINES-PER-PAGE IS 40
NUMBER-OF-PAGES IS
2747 OPTIMIZE HIGH .
END-DMCL .
compilation of schema.
Reloading the area
The area is reloaded by the WEB7_LOADHTM or WEB7_LOADHTM-I program,
according to the value of the keyword IDSTYPE. This program is activated
automatically by the reorganizing procedure.
47 A2 39UT Rev02
6-7
6.1.4.5
Example of database reorganization
1/2
WEB7_REORG_HTMLAREA
-->:
NBPG
+ number of HTML pages
IDSTYPE
KDDLIB
WEB7.BIN
SLLIB
SYS.HSLLIB
+ 1 if Full IDS, 0 else
+ schema library
HTMLAREA
WEB7.HTMLAREA
+ area assign parameters
SAVENAME
MDSAVE
DVCSAVE
CATSAVE
+ save file name
MEDIA save file
DEVICE save file
+ CAT or UNCAT
100
1
source library (DDL, DMCL)
WEB7.SAVEHTML
FUE2
MS/FSA
CAT
------------------------------------------------------------------------------
2/2
WEB7_REORG_HTMLAREA
-->:
NEWAREA
MDAREA
DVCAREA
CATAREA
+
+
+
+
name of the new area
media of the new area
device of the new area
CAT or UNCAT
WEB7.NEWHTMLAREA
FUE2
MS/FSA
CAT
------------------------------------------------------------------------------
6-8
47 A2 39UT Rev02
S: WEB7_REORG_HTMLAREA 100
KDDLIB=WEB7.BIN
HTMLAREA=WEB7.HTMLAREA
SAVENAME=WEB7.SAVEHTML
MDSAVE=FUE2
DVCSAVE=MS/FSA
NEWAREA=WEB7.NEWHTMLAREA
MDAREA=FUE2
DVCAREA=MS/FSA;
Save HTMLAREA ...
---> End of save HTMLAREA
Scheme compilation
>>>17:13 DDPROC 50.00
11
C: CONVERT OBJECT=SCHEMA
SCHEMA=HTMLSCHEMA, SUBSCHEMA=HTML-SUBSCHEMA,SCHLIB=DDINLIB1, REPLACE;
C: /;
<<<17:13
*** FILE : WEB7.NEWHTMLAREA HAS NOT BEEN FOUND (H_LH_RD_LAB)
RC=A2421007->DFVLU 2,EFNUNKN (DU1314)
Allocation of area HTMLAREA
Restore the area...
H_WEB7_LOADHTM Date: TUE, 11 MAY 1999 16:14:03 GMT.
H_WEB7_LOADHTM --------------------------H_WEB7_LOADHTM
ADD
H_WEB7_LOADHTM
*
H_WEB7_LOADHTM --------------------------H_WEB7_LOADHTM ADD PAGE_DOC4.1
H_WEB7_LOADHTM ADD PAGE_DOC3.3
H_WEB7_LOADHTM ADD A-ADMIN-WB71
H_WEB7_LOADHTM ADD A-ADMIN-WEB7
H_WEB7_LOADHTM ADD A-ADMLOGOUT7
H_WEB7_LOADHTM ADD A-TPRTEST-LOGOUT
H_WEB7_LOADHTM ADD A-TPRTEST
H_WEB7_LOADHTM ************* END OF FILE *************
----- End of reorganization of the data base. ----S:
47 A2 39UT Rev02
6-9
6.2
Description of the Database
The HTML pages displayed by the browser are stored in an IDS/II database
comprising two sets:
• ENTRYSET containing the HTMLHEADER members enabling you to identify
the different HTML pages used by the TDS,
• HTMLSET containing three types of members enabling you to describe the
contents of each page, HTMLRECORD, ACTIONRECORD and
BINARYRECORD.
Calc
DBKEYFIELD
htmlrecord
htmlrecord
htmlrecord
htmlentry
Entryset
actionrecord
actionrecord
actionrecord
Htmlset
htmlheader
Calc
HTMLPAGENAME
binaryrecord
binaryrecord
binaryrecord
htmlrecord
htmlrecord
htmlrecord
htmlheader
Htmlset
binaryrecord
binaryrecord
binaryrecord
actionrecord
actionrecord
actionrecord
Figure 6-1.
6-10
HTML SCHEMA
47 A2 39UT Rev02
6.2.1
HTML Header
One HTMLHEADER Record (name: HTMLHEADER) is written for each HTML
page that is stored in the database.
The HTMLHEADER is accessed via the CALC field “HTMLPAGENAME”. The
CALC key can be up to 192 bytes in length.
Other fields in the HTMLHEADER Record are:
• The date and time the record is stored.
• The date the record was modified.
6.2.2
HTML Record
The HTML Record (name: HTMLRECORD) contains HTML text, stored in
250-byte chunks.
The HTML Record(s) contain the contents of the HTML page in the HTML
Template database. One HTML record corresponds to a text line of an HTML page
that is not modified by the application.
6.2.3
Action Record
Directives for the TPRs can be embedded within the HTML page permitting you to
define the position of variables on the page, to indicate the next TPR to be
executed, or to indicate its parameters. These variables may be supplied directly by
the TPR or via JavaScripts.
Each directive is stored in an Action Record (name: ACTIONRECORD).
This is done in the page supplied when the database is being loaded, by using
comment characters.
For example, the following action tag, specifying the name of the NEXT-TPR:

<next-tpr-name>

is detected and stored in an Action Record. When this Action Record is processed
by the TPR, the content between the beginning and ending action tags is returned
to the caller.
Each Action Record is 125 bytes long.
47 A2 39UT Rev02
6-11
6.2.4
Binary Record
Not Currently Used
Any Content Type that is not «text/html» is stored as a Binary Record (name:
BINARYRECORD). Binary Records are stored and retrieved sequentially with
Header Records and HTML Records in the «HTMLSet» set.
Typically the Content Type in this case is «image/gif» or «image/jpeg». Another
possibility is Javabyte code, which has a Content Type of «application/octetstream».
Each Binary Record is 500 bytes long.
6.2.5
Data Description Language (DDL)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
6-12
AREA NAME IS HTMLAREA.
RECORD NAME IS HTMLENTRY
LOCATION MODE IS CALC USING DBKEYFIELD
DUPLICATES ARE NOT ALLOWED
WITHIN HTMLAREA.
02 DBKEYFIELD
TYPE IS CHARACTER
10.
RECORD NAME IS HTMLHEADER
LOCATION MODE IS CALC USING HTMLPAGENAME
DUPLICATES ARE NOT ALLOWED
WITHIN HTMLAREA.
02 HTMLPAGENAME
TYPE IS CHARACTER
192.
02 SOURCEURL
TYPE IS CHARACTER
192.
02 DATEMODIFIED
TYPE IS CHARACTER
48.
02 IMPORTDATE
TYPE IS SIGNED BINARY 31.
02 IMPORTTIME
RECORD NAME IS HTMLRECORD
LOCATION MODE IS VIA HTMLSET SET
WITHIN HTMLAREA.
02 HTMLSIZE
02 HTMLDATA
TYPE IS CHARACTER
250.
RECORD NAME IS ACTIONRECORD
WITHIN HTMLAREA.
02 ACTIONSIZE
02 ACTIONDATA
TYPE IS CHARACTER
125.
RECORD NAME IS BINARYRECORD
WITHIN HTMLAREA.
02 IMAGESIZE
47 A2 39UT Rev02
31
02 IMAGE
TYPE IS CHARACTER
32 SET NAME IS ENTRYSET
33
OWNER IS HTMLENTRY
34
ORDER IS PERMANENT
35
INSERTION IS SORTED BY DEFINED KEYS
0
DUPLICATES ARE NOT ALLOWED.
36
MEMBER IS HTMLHEADER
37
INSERTION IS AUTOMATIC
38
RETENTION IS MANDATORY
39
SET SELECTION IS THRU ENTRYSET OWNER
40
IDENTIFIED BY APPLICATION.
41 SET NAME IS HTMLSET
42
OWNER IS HTMLHEADER
43
ORDER IS PERMANENT
44
INSERTION IS LAST.
45
MEMBER IS HTMLRECORD
46
47
48
SET SELECTION IS THRU HTMLSET OWNER
49
50
MEMBER IS ACTIONRECORD
51
52
53
54
55
MEMBER IS BINARYRECORD
56
57
58
59
60 END-SCHEMA.
6.2.6
500.
Device Media Control Language (DMCL)
1
2
3
4
5
6
7
8
9
47 A2 39UT Rev02
SCHEMA NAME IS HTMLSCHEMA
EXTEND NUMBER OF AREAS TO 4
EXTEND GLOBAL POINTERS TO 4 BYTES
NO LOCAL POINTERS.
PAGE-SIZE IS 4096
NUMBER OF LINES-PER-PAGE IS 40
NUMBER-OF-PAGES IS
2747 OPTIMIZE HIGH .
END-DMCL .
6-13
6.3
Loading Web Pages into the HTML Template Database
The TDS-Web software includes a program and a TPR that are used to load the
HTML Template database, and also to delete pages from the database. These are
referred to as the HTML Administrative Utility.
GCOS 7
PC
Command
del *
add ‘page_name’
…
.
The name of the page contained in the header will be that registered in the
database.
After this line, comes the content of the HTML page. After this page, it is possible
to place another page there which should also begin with , and so on until the last page.
All pages should contain an <HTML> line and end with </HTML>. The HTML
Administrative Utility will consider that an error has occurred if the page does not
comply with this rule and will pass to the following operation.
It is possible to insert TPR lines of action in the pages: these paragraphs should
begin with the line  and end with the line .
NOTE:
All the headers (,
) should start in the first column of the page.
Comments (as <!…. >) may be inserted within the page, and/or at its beginning.
The space character is allowed in the name of an HTML page.
6-18
47 A2 39UT Rev02
6.4.2.1
Example of LOCALHOST File

<html>
<head>
<title>PAGE 1 </title>
</head>
<body>
<h2>This is the example 1</h2>
</body>
</html>

<html>
<head>
<title>PAGE 2 </title>
</head>
<body>
<h2>This is the example 2</h2>

Slot for Actions Record
...........Use of actions record is done
in the example of TPR DOCSTPR4

</body>
</html>
6.4.2.2
Structure of the LOCALHOST File
Example of file allocation for LOCALHOST (WEB7.HTML) file:
PREALLOC
&DIR.HTML DVC=MS/&LIVDVC GLOBAL=(MEDIA=&LIVMD SIZE=5000)
UFAS=(SEQ=(CISIZE=2048,RECSIZE=250,RECFORM=F))
INCRSIZE=250, UNIT=BLOCK,
CATNOW,FILESTAT=CAT;
WEB7.HTML
ORG
format =
organiz.=
maxsize =
recsize =
Figure 6-4.
47 A2 39UT Rev02
OWNER : WEB7
UFAS
catalog.= YES
SEQ
recform = F
UNDEFINED
250 +4
cisize = 2048
incrsize= 250
expdate = 98/244
unit
= BLK
Structure of the LOCALHOST File
6-19
6.4.2.3
JCL to Run the Utility
To invoke the HTML Administrative Utility as a batch process, use the JCL
WEB7_LOADHTMEXEC:
EJR WEB7_LOADHTMEXEC LIB=SYS.HSLLIB [VL=={FULLIDS=YES,FULLIDS=NO}]
In FULL IDS mode, the load module H_WEB7_LOADHTM is activated; and in
the OLD IDS mode, it is the load module H_WEB7_LOADHTM_I.
EXAMPLE:
Notes
10 $JOB H_WEB7_LOADHTM;
20 VL WEB7 , FULLIDS=YES;
30 OUTVAL HOLD BANINF = &1;
40 JUMP FIDS&FULLIDS;
50
60 FIDSYES:
70
80 STEP H_WEB7_LOADHTM (SYS.HLMLIB) REPEAT DUMP=DATA;
90 SIZE 500 POOLSIZE=200;
100 ASG PAGEHTML &1.HTML ACCESS=READ ;
4
110 ASG PAGEIND &1.CMD ACCESS=READ;
4
120 ASG HTMLAREA &1.HTMLAREA;
3
130 ASG DDLIB1
&1.BINFIDS SHARE=DIR;
2
140 ASG IDSOPT *OPT;
150 ENDSTEP;
160 $INPUT OPT PRINT;
170 IGNORE TRANSIENT STATE HTMLAREA.
180 SYNCHRO.
190 STATISTICS.
200 $ENDINPUT;
210 JUMP FIN;
220
230 FIDSNO:
240
250 STEP H_WEB7_LOADHTM-I (SYS.HLMLIB) REPEAT DUMP=DATA;
260 SIZE 500 POOLSIZE=200;
270 ASG PAGEHTML &1.HTML ACCESS=READ;
280 ASG PAGEIND &1.CMD ACCESS=READ
290 ASG HTMLAREA &1.HTMLAREA;
300 ASG DDLIB1
&1.BIN SHARE=DIR;
310 ASG IDSOPT *OPT-I;
320 ENDSTEP;
330 $INPUT OPT-I PRINT;
340 IGNORE TRANSIENT STATE HTMLAREA.
350 SYNCHRO.
360 STATISTICS.
370 $ENDINPUT;
380
390 FIN:
400 $ENDJOB;
Figure 6-5.
6-20
JCL to Run the Utility
47 A2 39UT Rev02
NOTES:
1.
The HTML Administrative Utility run unit that is delivered with
TDS-Web.
2.
The database schema file.
For the Full IDS: ASG DDLIB1 &1.BINFIDS SHARE=DIR;
For the Old IDS: ASG DDLIB1 &1.BINIDS SHARE=DIR;
3.
The location of the HTML Template database.
4.
The UFAS SEQUENTIAL files.
❑
6.4.3
ADMIN Transaction
The ADMIN transaction only uses the LOCALHOST file containing the HTML
pages.
6.4.3.1
Executing via the Mainway Page
To execute the ADMIN transaction, it is necessary to connect the TDS from a
browser.
The connection of a TDS-Web user to a TDS of GCOS 7 is done with the help of a
home page. This page called MAINWAY is delivered in the installed source library
(SL).
The user can transfer this page either to his server or to his PC and should modify
in the BASE Mainway's address by addressing the Mainway of the desired
GCOS 7 system.
The administrator can customize the home page by adding images or text but
certain fields of the page are compulsory and cannot be modified. These are the
names of the variable fields to fill in such as « _NODE », « _MAILBOX »,
« _USER », « _PROJECT », « _BILLING », « _PASSWORD » and
« _TP8CMD ».
47 A2 39UT Rev02
6-21
Figure 6-6.
Mainway Welcome Page - With Field Values
The command to execute is the ADMIN transaction.
To establish the connection with the TDS, just click on the Logon button.
The RESET key is used to clear the completed fields.
Once connected to the TDS, the administration page appears, you can make your
selection of one of the proposed options. When you have made your choice, you
just have to click on the ‘Validate’ hypertext link to execute your choice. To
disconnect, you should click on ‘Logout’.
6-22
47 A2 39UT Rev02
Figure 6-7.
47 A2 39UT Rev02
ADMIN Transaction Welcome Page
6-23
6.4.3.2
Description of the ADMIN Functions
List all pages from the base
Displays the list of pages contained in the database with the date and insertion time
in the database as well as the date of the last modification.
Figure 6-8.
6-24
List of HTML pages
47 A2 39UT Rev02
Add all pages in the base
Browses the LOCALHOST file containing all the pages and inserts them in the
database.
Then displays the list of pages added in the database.
Figure 6-9.
47 A2 39UT Rev02
List of Inserted HTML Pages
6-25
Display of a page from the base
Searches for a page in the database and displays its source code. If the page does
not exist in the database, the TPR displays a warning page.
Figure 6-10.
6-26
Display of a Page
47 A2 39UT Rev02
Add a page in the base
Browses the LOCALHOST file, containing all the pages, searching for the
requested page, and once it is found, inserts it in the database. If the page already
exists in the database, it is replaced. If the page does not exist in the file, the TPR
displays a warning page.
Deletes a page in the base
Searches for the requested page in the database, and once it is found deletes it. If
the page does not exist in the database, the TPR displays a warning page.
Validate: execute the selected function.
Logout: disconnect the TDS.
6.4.4
Error Messages
One of the messages described in this section is returned if the TDS-Web software
cannot process a command successfully.
NOTE:
Some error messages include db-status. For the meaning of these database
error status codes, refer to Appendix A IDS/II Status Keys.
Some error messages include COBOL’s f-status. For the meaning of these
File Access error status codes, refer to Appendix B File Status Key.
6.4.4.1
The Batch Process LOADHTM Error Messages
In the messages, the following codes are used:
nnnnnnn
corresponds to the code returned on access to the
database.
xxxxxxxx
corresponds to the name of the HTML page processed
at the time of the error.
ff
corresponds to the status returned on accessing UFAS
files.
ERROR WHILE DELETING PAGE: DB-STATUS=nnnnnnnn
Deletion of a page of the database is impossible (in the case of the deletion of a
page of the database).
47 A2 39UT Rev02
6-27
ERROR WHILE DELETING PAGE FOR INSERTION: DB-STATUS=nnnnnnnn
Deletion of a page of the database is impossible (in the case of insertion of a page,
which already exists in the database).
ERROR IN SEQUENCE 01: xxxxxxxx
The program expected to read  while it did not find <!—WEB7-->
previously.
ERROR IN UFAS FILE: /WEB7 MISSING
The program has come to the end of the WEB (</HTML>) page while it was
recording ACTION RECORD. Therefore, the tag  is missing.
ERROR WHILE WRITING ACTION RECORD: DB-STATUS=nnnnnnn
Recording actions in the database impossible.
6-28
47 A2 39UT Rev02
ERROR WHILE WRITING HTMLENTRY: DB-STATUS=nnnnnnn
Access to the database is impossible.
ERROR WHILE WRITING HTMLHEADER: DB-STATUS=nnnnnnn
Recording the name of the page in the database is impossible.
ERROR WHILE WRITING HTMLRECORD: DB-STATUS=nnnnnnn
Recording the page in the database is impossible.
UNKNOWN COMMAND
The program has not recognized a command in the command file.
PAGE NOT FOUND FOR INSERTION: nnnnnnnn
The page to insert in the database has not been found in the UFAS file.
PAGE NOT FOUND FOR DELETION: nnnnnnnn
The page to be deleted from the database has not been found.
6.4.4.2
ADMIN Error Messages at the MASTER Level
In the messages, the following codes are used:
nnnnnnn
corresponds to the code returned on access to the
database.
xxxxxxxx
corresponds to the name of the HTML page processed
during error.
ff
corresponds to the returned status during access to the
UFAS files.
ERROR WHILE ACCESSING BASE: DB-STATUS=nnnnnnn
Access to the database is impossible.
ERROR WHILE DELETING PAGE: DB-STATUS=nnnnnnnn
Deletion of a page from the database is impossible (in the case of deletion of a page
of the database).
ERROR WHILE DELETING PAGE FOR INSERTION: DB-STATUS=nnnnnnnn
Deletion of a page of the database is impossible (in the case of insertion of a page,
which already exists in the database).
47 A2 39UT Rev02
6-29
ERROR IN EVALUATE OTHER
The name of the function, which received the TPR, is unknown.
ERROR IN SEQUENCE 01: xxxxxxxx
The TPR expected to read  while it did not find the
 previously.
ERROR: /WEB7 MISSING
The TPR has arrived at the end of the WEB (</HTML>) page while it was
recording ACTION RECORDS. Therefore, the  tag is missing.
ERROR: UNSUCCESSFUL DELETION IN BASE
The TPR has not succeeded in deleting a page from the database.
6-30
47 A2 39UT Rev02
ERROR: UNSUCCESSFUL INSERTION IN BASE
The TPR has not succeeded in inserting a page into the database.
ERROR WHILE WRITING ACTION RECORD: DB-STATUS=nnnnnnn
Recording actions in the database is impossible.
ERROR WHILE WRITING HEADER: DB-STATUS=nnnnnnn
Recording page name in the database is impossible.
ERROR WHILE WRITING HTMLRECORD: DB-STATUS=nnnnnnn
Recording page in the database is impossible.
ERROR: BAD FILE STATUS
An error has occurred on reading the LOCALHOST file.
BAD F-STATUS: ff
Status of the error that occurred on reading the LOCALHOST file.
HEADER DELETION ERROR: DB-STATUS=xxxxxxxx
Further to an insertion error in the database, another error occurred during deletion
of the erroneous page.
PROGRAM INTERNAL ERROR: DB-STATUS=nnnnnnn
This is an internal error on the level of the database. See the IDS/II documentation.
NO RECORD FOR HTML PAGE: nnnnnnn
The TPR found the header of the page to manipulate but not its contents.
PAGE NOT FOUND FOR INSERTION: xxxxxxxx
The page that should be inserted in the database has not been found.
PAGE NOT FOUND FOR DELETION: xxxxxxxx
The page that should be deleted from the database has not been found.
47 A2 39UT Rev02
6-31
6.4.4.3
ADMIN Error Messages at the BROWSER Level
ERRONEOUS PAGE
HTML FILE EMPTY
ERRONEOUS PAGE
HEADER MISSING
ERRONEOUS PAGE
HTML MISSING
The TPR expected to read <HTML> in the LOCALHOST file of the HTML pages
ERRONEOUS PAGE
/HTML MISSING
The TPR expected to read </HTML> in the HTML pages but it read something
else.
ERRONEOUS PAGE
WEB7 MISSING
The TPR has found the tag  while it did not find the <!—WEB7-->
previously.
ERRONEOUS PAGE
/WEB7 MISSING
The TPR has arrived at the end of the WEB (</HTML>) page while it was
recording ACTION Records. Therefore, the  tag is missing.
ERRONEOUS PAGE
UNSUCCESSFUL DELETION IN BASE
The TPR did not succeed in deleting a page from the database.
ERRONEOUS PAGE
UNSUCCESSFUL WRITING IN BASE
The TPR did not succeed in inserting a page in the database.
ERROR ff WITH SEQUENTIAL FILE
The use of the LOCALHOST file did not take place correctly.
6-32
47 A2 39UT Rev02
INTERNAL PROGRAM ERROR
IDS/II TEMPLATE DATABASE PROBLEM. DB-STATUS=xxxxxxxx
The use of the database did not take place correctly.
NO RECORD IN HTMLSET
The TPR found the header of the page to manipulate without problems but not its
contents.
404 OBJECT NOT FOUND
The administration page that should be displayed has not been found in the
database.
PAGE CANNOT BE DELETED
The user has attempted to delete an administration page. Use LOADHTM to
delete.
47 A2 39UT Rev02
6-33
❑
6-34
47 A2 39UT Rev02
7. Developing TDS-Web Applications
This section explains how to develop TDS-Web applications. A TDS-Web
application consists of one or more TPRs that operate under TDS on GCOS 7 plus
the Web pages that are used to collect input and display output on the user’s
browser.
• Introduction to Developing a TDS-Web TPR
• Coordinating TPR Development and Web Page Design.
• Creating Web Pages To Be Used as TDS-Web Output.
• Designing TDS-Web TPRs.
• Coding TDS-Web TPRs.
• Compiling and Linking TDS-Web TPRs.
• Invoking a TDS-Web TPR from a Browser.
• Examples of TPR.
NOTE:
All of the examples in this document are intended to be browser-neutral.
However, examples that include JavaScript will not necessarily work the same
when used with all browsers. Consult the specifications for the specific
browser(s) that are used to determine exactly which script features are
supported.
Knowledge of HTTP protocol and JavaScript is necessary for a good
understanding of this chapter.
Using JavaScripts instead of other types of scripts is important because only
JavaScripts are supported by all the types of browsers.
47 A2 39UT Rev02
7-1
7.1
Introduction to Developing a TDS-Web TPR
This section provides some background information about developing a TDS-Web
TPR, and serves as an introduction to the more detailed information in the
following sections.
TDS-Web includes development tools that simplify the implementation of
applications that interact directly with Web browsers. Users of Web browsers can
submit transactions to TDS through the MainWay HTTP-DSA gateway. The
HTTP-DSA gateway maintains persistent connections to GCOS 7, thereby
allowing applications to maintain the transaction state.
In general, a TDS-Web TPR is similar to a terminal-based TPR. The TDS-Web
TPR receives an input message and, based on various input parameters, retrieves
information from a database on the GCOS 7 system and displays an output
message to the user.
The significant differences between terminal-oriented TPRs and TDS-Web TPRs
are:
1.
TDS-Web TPR output can be displayed on a Web browser, such as Netscape
Navigator or Microsoft Internet Explorer, instead of on a terminal or a PC
with terminal-emulation software.
2.
The TPR has the opportunity to generate output that takes advantage of the
powerful features of HTML.
Web browsers generate messages that contain the HTTP specification and rely on
the use of Uniform Resource Locators (URLs) to make connections to servers.
Application programmers and authors of Web pages need to be familiar with the
basic concepts of URLs, as well as the specifics of how TDS-Web uses the URL, to
initiate connections to TDS and manage persistent sessions. Information about
URLs in general and TDS-Web URLs in particular is provided in Chapter 2
TDS-Web Processing Concepts.
7-2
47 A2 39UT Rev02
7.2
Coordinating TPR Development and Web Page Design
TDS-Web developers need to coordinate their activities with the designers of Web
pages that will be used in the TDS-Web environment.
The main requirement is for the TPR developers and Web-page designers to agree
on the field names to be used. Typically, TPR developers are responsible for
defining the field names used in the scripts and in the programs, which must be
valid script-variable names, and for “publishing” these names. However, authors
of Web pages will reference these field names in the HTML documents they create,
and so they must know which field names have been assigned and for what
purposes.
The field names are JavaScript variables, which are generated by TDS-Web TPRs.
Each JavaScript variable is either initialized with data from an application database
or derived (computed) by the TPR based on business rules.
These field names do not necessarily equate directly to database fields. For
example, a JavaScript variable named «address» might be an array of data that
was defined in the database as «STREET1», «STREET2», and «CITY».
The site should establish and publish a data dictionary that defines the JavaScript
variables to be generated by each TPR, with the associated application database
values.
Observing the following recommendations can simplify coordination between TPR
developers and Web-page designers:
1.
Format TPR output to follow the conventions of JavaScript
(ECMAScript)-variable definitions.
2.
Each TPR should first generate a block of script statements that assign values
to a set of JavaScript variables.
3.
Following these variable definitions, the TPR should place the HTML that is
read from the HTML Template database. The HTML includes JavaScript
statements that reference the variables generated by the TPR.
47 A2 39UT Rev02
7-3
EXAMPLE:
The following example illustrates this relationship. Field names are shown in bold
type.
Statements generated by the TPR developer:
<SCRIPT Language=JavaScript>
var field1=value1;
var field2=value2;
</SCRIPT>
Statements generated by the Web page designer:
<BODY>
The result of concatenating field1 and field2 is:
document.write(field1 + field2);
</SCRIPT>
</BODY>
❑
7-4
47 A2 39UT Rev02
7.3
Creating Web Pages To Be Used as TDS-Web Output
This section discusses topics to be considered when beginning the high-level
design of a TDS-Web application.
TDS-Web applications combine data from host databases with HTML to create
Web pages that are then sent to browser clients. The output generated by a
TDS-Web TPR consists of three components:
1.
HTTP header information.
2.
JavaScript variables that make database values available to the browser.
3.
HTML that contains a combination of static information and references to the
JavaScript variables.
The output generated by a TDS-Web TPR might look like Example 1.
EXAMPLE 1:
HTTP/1.0 200 OK
Content-type: text/html
<NL>

var custName=«ABC Corporation»;
</SCRIPT>
<!—- HTML read from database -->
<BODY>
The customer name is:
document.write (custName);
</SCRIPT>
</BODY>
❑
The advantage of the style of output shown in Example 1 is that TPR programmers
do not need to learn HTML. The TPR can copy HTML from the HTML database
without the need for the TPR developer to understand the specifics of HTML or the
JavaScript language, beyond the simple requirements associated with generating
the JavaScript-variable declarations that are used to define the database values.
In Example 1, the TPR has retrieved a record from the application database with
the customer name of «ABC Corporation.» The TPR makes this value available to
the HTML document by generating a JavaScript statement that declares a variable
called custName.
47 A2 39UT Rev02
7-5
When the output is transmitted to the browser, the browser displays this variable
information when it executes the document.write(custName) statement that
appears within the <BODY> of the HTML. For details, refer to the JavaScript text.
Using this style in TDS-Web applications is important because this format allows
the authors of Web pages to develop HTML that includes simulated application
data without the need to execute the associated TPR. In fact, the Web-page author
can develop the entire HTML document before the TPR has been developed.
All that is necessary is for the Web-page author and the TPR developer to agree on
the set of JavaScript variables to be generated by the TPR, as discussed in
Section 7.2 Co-ordinating TPR Development and Web Page Design.
As soon as the list of variables to be generated has been established, the Web-page
author can develop pages using simulated data. Each HTML document that is
developed for use in TDS-Web can include sample script statements to simulate the
results of executing a TDS-Web TPR, as illustrated in Example 2.
EXAMPLE 2:
<BODY>
var custName=«XYZ Corporation»;
</SCRIPT>
document.write(custName);
</SCRIPT>
<BODY>
❑
Including these same script statements in the HTML document enables the HTML
author to view the Web page exactly as it will appear when output by a TDS-Web
TPR.
However, this method could introduce a potential problem. If the TPR generates
JavaScript statements to declare variables, then copies an HTML document that
contains its own version of the same variables, which values will the browser
display?
Consider Example 3.
7-6
47 A2 39UT Rev02
EXAMPLE 3:
HTTP/1.0 200 OK
<NL>

var custName=«Accountants Unlimited»;
</SCRIPT>

<BODY>
</SCRIPT>
</SCRIPT>
<BODY>
❑
The answer to the question posed above is that the last declaration encountered by
the browser is used. Therefore, if the TPR generates a script statement that defines
custName to be «Accountants Unlimited», and then sends an HTML
document that contains sample script statement that defines custName to be «XYZ
Corporation», the sample data will always overlay the variables generated by the
TPR. Therefore, the browser will erroneously display XYZ Corporation instead
of Accountants Unlimited as desired.
This problem of overlaying TPR script statement with sample script statements can
be avoided by using any of the following three methods.
1.
Delete the sample script statements.
An obvious solution is to delete the sample script statement from the HTML
document before it is imported into the HTML Template database on
GCOS 7. However, although this approach solves the problem described
above, it creates other problems. The most significant of these problems is
that the page the HTML author developed will never be identical to the
version of the document that resides in the HTML Template database.
Version-control issues can be extremely difficult to resolve.
2.
Use conditional execution to execute the correct set of script statements.
In this solution, the HTML author encloses the sample variable declarations in
a JavaScript «if» statement that causes these declarations to be executed only
in the Web-page development environment. The required additional
JavaScript statements are shown in bold in Example 4.
47 A2 39UT Rev02
7-7
EXAMPLE 4:
<BODY>
if (typeof(custName)=«undefined») { // begin conditional code
} // end conditional code
</SCRIPT>
</SCRIPT>
<BODY>
❑
The technique shown in Example 4 uses the JavaScript «typeof» operator to
determine if the variable has yet been defined. When a browser reads this
page directly from a file, the custName variable will not be defined, so the
JavaScript statements within the «if» block will be executed. When this
page is sent to the browser by a TPR, the variables that were generated by the
TPR will cause the «if» statement to be false and the sample declarations
will not be executed.
This technique allows the HTML author to keep the sample JavaScript
statement in the file when the file is imported into the HTML Template
database on GCOS 7, thereby eliminating version-synchronization issues.
This technique can be used when the HTML will be stored on GCOS 7, or
when the number of script variables is minimal.
3.
Prevent the TPR from sending sample variables.
TDS-Web provides a third solution to the problem of handling sample
variables. In this solution, the HTML author uses special HTML command
records — which are shown in bold in Example 5 below — to identify HTML
and script statements that should not be sent by a TPR to a browser.
The HTML author inserts an HTML comment that begins with the string
«» to signal the beginning of a sequence of text that should not
be sent to the browser. To mark the end of the block of excluded text, the
HTML author inserts a second HTML command that contains the string
«» The beginning string «» and the ending
string «» must each be on a separate line.
7-8
47 A2 39UT Rev02
When the TDS-Web HTML Administrative utility encounters these comment
records, it diverts the enclosed text to a special record type (Action Record)
within the HTML Template database, as described in Chapter 6 HTML
Template Database. The rest of the HTML is written into HTML Record(s).
When a TPR reads the HTML from the database, it sees two distinct types of
records, which allows the TPR to skip those records that the HTML author
marked for exclusion.
EXAMPLE 5:
<BODY>

if (typeof(custName)==«undefined») {
var custName=«XYZ Corporation»
}
!--/WEB7-->
</SCRIPT>
document.write(custName)
</SCRIPT>
<BODY>
❑
This technique can also be combined with the use of conditional JavaScript logic,
as shown in Example 5 above.
47 A2 39UT Rev02
7-9
7.4
Designing TDS-Web TPRs
This section discusses several aspects of design that are important when developing
TDS-Web TPRs. The topics discussed are:
• Using TDS-Web Runtime Routines To Receive Input.
• Options for Handling HTML Output.
• Using a Base TPR.
• Using TDS-Web Runtime Routines To Send Output.
7.4.1
Using TDS-Web Runtime Routines To Receive Input
The TDS-Web runtime routines provide a variety of functions for a TDS-Web TPR.
One, the HTTP_RECEIVE is mandatory, to receive the message from the browser
and initialize the GCOS 7 environment allowing input handling.
Some other routines facilitate the design and development of TDS-Web TPRs, in
particular:
1.
Use the HTTP_GETENV routines to get the environment header variables.
2.
Use the HTTP_GETHDR routines to get the HTTP header variables.
3.
Use the HTTP_GETVAR routines to get the variables.
Refer to Chapter 2 TDS-Web Processing Concepts for complete descriptions of
these routines and the other TDS-Web runtime routines, including other routines
that can be used to get the whole message or part of it.
7.4.2
Options for Handling HTML Output
Each TDS-Web TPR receives input from Web browsers and then returns an HTTP
response. The HTML that is included in the response can be obtained using any of
these methods:
1.
Read from the HTML Template Database.
2.
Generated by the TPR.
3.
Included in the TPR code.
The TDS-Web software places no restrictions on how the HTML is obtained.
However, TDS-Web does require that the TPR output a minimum set of HTTP
elements. This minimum set is defined in Section 7.5.3.1 Minimum TPR Output.
7-10
47 A2 39UT Rev02
7.4.3
Using a Base TPR
Although the connection between the GCOS 7 system and the MainWay
HTTP-DSA Gateway is persistent — i.e., the DSA session stays open at the end of
the transaction — the connection between the MainWay HTTP-DSA Gateway and
the browser is not persistent.
If the application wishes to reserve a particular DSA session for use by a specific
browser occurrence, the application must generate output that informs the
MainWay HTTP-DSA Gateway and the Web browser of the new base URL that
includes the DSA session identifier. From the browser’s perspective, the
connection is persistent; i.e., the application is re-using the same session.
To accomplish this, you can organize the application to include a Base TPR. The
Base TPR will provide the necessary information to the MainWay HTTP-DSA
Gateway and to the Web browser so that the browser can re-use the DSA session.
For the output elements that are required when a Base TPR is used, refer to
Section 7.5.3.3 Base TPR Output.
7.4.4
Using TDS-Web Runtime Routines To Send Output
Among the TDS-Web runtime routines, two, in particular, facilitate the design and
development of TDS-Web TPRs for sending output:
1.
Use the HTTP_SEND routine to send most output.
2.
Use the HTTP_SENDJSTEXT routine to send database values.
Refer to Chapter 8 APIs for TDS-Web Runtime Routines for complete descriptions
of these routines and the other TDS-Web runtime routines, including other routines
that can be used to send output.
47 A2 39UT Rev02
7-11
7.5
Coding TDS-Web TPRs
This section discusses the following TPR coding considerations:
•
•
•
•
7.5.1
Basic Coding Requirements.
TPR Input.
TPR Output.
Using TDS-Web Runtime Routines to Analyze and Process HTTP Requests.
Basic Coding Requirements
The first TDS-Web TPR of a transaction must begin with a move of the ON
ABORT TPR into the TDS STORAGE.
Then, the following coding requirements apply to all TDS-Web TPRs:
1.
The declaration for TRANSACTION-STORAGE must include the first
3000 characters for WEB7-PRIVATE-STORAGE. This WEB7-PRIVATESTORAGE, mapped on the third parameter of all TPRs, has to be supplied as
an argument for most TDS-Web calls. It is recommended to use the fourth
parameter of all TPRs for the transaction storage. Refer to Chapter 5 TDS
Considerations When Using TDS-Web.
2.
The TPR must begin with a call to the TDS-Web runtime routine
HTTP_RECEIVE, that:
− Initializes the TDS-Web environment.
− Moves the SYMBOLIC-QUEUE of the TDS-STORAGE in input CD.
− Receives the message from the browser.
− Parses the message into separate records and variables.
3.
The TPR can be written in either COBOL-85 or C. Note that a TPR written in
C must call a COBOL-85 subroutine for any access to the HTML Template
Database, because a C application cannot directly access an IDS/II database.
4.
The TPR must include the following logic:
− Call the TDS-Web runtime routines to obtain input parameters. For
information about how to use the TDS-Web routines for this purpose, refer
to Section 7.5.4 Using TDS-Web Runtime Routines To Analyze and Process
HTTP Requests.
− Perform the application logic.
− Generate the HTTP response, which consists of an HTTP response header,
followed by the content that can be processed by the browser.
− Send the HTTP response.
7-12
47 A2 39UT Rev02
5.
The TPR must handle error codes that can be generated by the TDS-Web
runtime routines. These error codes are defined for C in the WEB7LIB_H
subfile and for COBOL-85 in the WEB7LIB-C85 subfile, which are located in
the source library created during the Installation.
A COPY library is available for use in TDS-Web TPRs written in COBOL-85. The
following sample COBOL-85 statements can be used to include this COPY library:
COPY WEB7LIB-C85.
The following include statement is required in each TDS-Web TPR written in C:
#include «WEB7lib.h»
An example of the minimum coding required for the TPR written in COBOL-85 is
shown below. The coding shown in this example TPR causes “Hello World” to
be displayed via a browser.
47 A2 39UT Rev02
7-13
EXAMPLE:
Identification division.
program-id. TPRMAIN.
data division.
working-storage section.
COPY WEB7LIB-C85.
77 msgtxt
pic x(512).
77 msglng
comp-6.
77 NL
pic xx value ""14,38"".
77 Ekout
pic x value "1".
linkage section.
copy TDS-STORAGE.
copy CONSTANT-STORAGE.
01 TRANSACTION-STORAGE.
02 WEB7PS
pic x(3000).
02 TS
pic x(500).
procedure division using TDS-STORAGE
CONSTANT-STORAGE
send-hello.
Move "ABTWEB7" to ON-ABORT-TPR.
call "HTTP_RECEIVE" using address of TDS-STORAGE
address of TRANSACTION-STORAGE.
move 1 to msglng.
string "HTTP/1.0 200 OK" NL
"Content-type: text/html" NL
NL
"<HTML>" NL
"<HEAD><TITLE>Hello World</TITLE></HEAD>" NL
"<BODY><H1>Hello World</H1><HR>" NL
"</BODY></HTML>" NL
delimited by size into msgtxt pointer msglng.
subtract 1 from msglng.
move "3" to Ekout.
call "HTTP_SEND" using address of msgtxt
address of msglng
address of Ekout
exit-startup.
exit.
❑
7-14
47 A2 39UT Rev02
7.5.2
TPR Input
A TDS-Web input message generated by a Web browser consists of an HTTP
request header, followed by optional variables.
A message that is submitted using the HTTP POST or HTTP GET request method
contains both the HTTP request header and variables.
NOTE:
In the TDS-Web environment, the browser submits the input message to a
MainWay HTTP-DSA Gateway, which manages the DSA session connection to
GCOS 7. The gateway passes the input message on to GCOS 7 and TDS.
T ra n saction n am e
E n viro n m e n t H ea d er(s)
ze ro to n
en v ir o n m en t
h ea d er s
CRLF
H T T P r eq u e st:
G E T or P O ST
H T T P H e a d e r(s)
H T T P r eq u est
h ea d e rs
CRLF
H T M L fo rm va ria b les
Figure 7-1.
47 A2 39UT Rev02
ze ro to n
H T M L fo rm
v a ria b les
TDS-Web Input Format
7-15
PHDEMO
CONTEXT=40328fb0.3610ad80..
POST /BY0F.WEB7/0/PHDEMO HTTP/1.0..
Accept: image/gif, image/x-xbitmap,
image/jpeg, image/pjpeg,*/..
Referer: file:C:\httpd\HtDocs\mainway.html..
Accept-Language: fr, en..
Content-Type:application/x-www-form-urlencoded..
UA-pixels: 1024x768..
UA-color: color8..
UA-OS: Windows 95..
UA-CPU: x86..
User-Agent: Mozilla/2.0 (compatible; MSIE 3.0; Windows 95)..
Host: mainway location:8080..
Connection: Keep-Alive..
Content-Length: 14..
Pragma: No-Cache..
btnLogon=Logon..
Figure 7-2.
7.5.3
Example of HTTP Request
TPR Output
A TDS-Web TPR generates output that is processed by a Web browser. The output
generated by the TPR is an HTTP response header followed by the content that can
be processed by the browser.
Typically, the content will be HTML, but the content can be of any type recognized
by the browser — such as plain text or comma-delimited spreadsheet data. When
generating content in formats other than HTML and plain text, the TPR developer
should consult the documentation for the target Web browser for information about
the formats that are supported and how to use these formats. For additional
information about creating output to be sent to browser clients, refer to Section 7.3
Creating Web Pages To Be Used as TDS-Web Output.
7-16
47 A2 39UT Rev02
An overview of the items that a TDS-Web TPR must output is contained in Table
Table 7-1. The notes referenced in the table follow the table.
Table 7-1.
Overview of TDS-Web TPR Output Contents
Description/ Function Contains
HTTP header
HTTP/1.0 200 <NL>
<NL>
Notes
<NL>
1, 2
1, 3
TPR-specific output
<SCRIPT Language=JavaScript><NL> 1, 4
var dataname1=«single value»<NL> 1
var dataname2=new Array(«line 1»,
«line 2»)<NL>
1
</SCRIPT>
Sending HTML
document
Coding statements that:
1. Read the HTML document from HTML
Template Database.
And
5
2. Send the document to the browser.
6
NOTES:
1.
Each line must end with <NL>, where <NL> represents a carriage return
and line feed. In COBOL-85, a carriage return and line feed is coded as
««14,38»». In C, a carriage return and line feed is coded as «\r\n».
You can also use the control characters included in the STANDARD
CONSTANT STORAGE.
2.
The TDS-Web routine HTTP_SEND can be used to send the HTTP header.
3.
Format that is supported by the MainWay HTTP-DSA Gateway. For more
information, see the MainWay System Generation Guide.
4.
Use the TDS-Web routine HTTP_SEND to send the «var dataname1=»
portion of the output. Use the HTTP_SENDJSTEXT routine to send the
quoted portion of the output.
5.
The HTML document references one or more of the TPR-generated
variables.
6. Use the TDS-Web routine HTTP_SEND to send this information.
The following subsections discuss the minimum output that a TDS-Web TPR is
required to produce, additional output that can be generated, and the special output
that a TDS-Web Base TPR must produce.
47 A2 39UT Rev02
7-17
7.5.3.1
Minimum TPR Output
At a minimum, TPR output must include the following:
HTTP/1.0 200 OK <NL>
Content-Type: text/html
<NL>
<BODY>
content
</BODY>
<NL>
The following example illustrates the minimum TPR output requirement.
EXAMPLE:
HTTP/1.0 200 OK <NL>
Content-type: text/html <NL>
<NL>
<BODY>
This output could include any data from the database and/or
dynamically-generated information. Browsers will display
this content using a variable-pitch font that does not
preserve any line and column spacing that may be present.
</BODY>
❑
7.5.3.2
Additional TPR Output
Table 7-2 contains a list of output items, both optional and required, that a
TDS-Web TPR can generate, with a brief description of each item. This table
includes the most commonly used output items.
For information about all possible output items, refer to the HTTP and HTML
specifications at the URL referenced in Chapter 2 TDS-Web Processing Concepts.
Chapter 8 APIs for TDS-Web Runtime Routines contains detailed information about
each of the TDS-Web runtime routines referenced in the table.
7-18
47 A2 39UT Rev02
Table 7-2.
TPR Output Items (1/2)
TPR Output Item
Required
or
Optional
Description
HTTP/1.0 200 OK
Required
For a Base transaction, OK must
be replaced by CONTEXT=xxxx.
For more information, refer to the
description of the HTML_BASE
routine.
Content-Type: text/html Required
Content-Length: ddd
Optional
Refer to the browser
specifications (URL located at
http://www.w3.org/) for
other types of content supported.
ddd must be the exact length
(in bytes) of the content part of
the message.
Date: xxx
Optional
Expires: xxx
optional
Refer to the description of the
HTTP_DATE routine.
Refer to the description of the
HTTP_EXPIRES routine.
Pragma: no-cache
optional
Prevents browser and proxy
servers from saving the HTML
document in cache.
<NL>
required
Empty line consisting only of
CRLF. The value specified in the
Content-Length header includes
only the bytes that follow this
empty line.
Every line in the HTTP header
also ends with <NL>.
47 A2 39UT Rev02
<SCRIPT
Language=JavaScript>
optional
Marks the beginning of script
statements.
script language source
optional
JavaScript variables generated by
the TPR to publish application
data.
7-19
Table 7-2.
TPR Output Items (2/2)
TPR Output Item
Required
or
Optional
Description
</SCRIPT>
Optional
Must be present if <SCRIPT> is
generated. Marks the end of
script statements.
<HTML>
Optional, but should
be generated
Starts an HTML document.
Should be closed by </HTML>.
<HEAD>
Optional
Starts the heading portion of an
HTML document. Should be
closed by </HEAD>.
<TITLE></TITLE> Optional
7-20
Defines the document title.
Allowed only in the <HEAD>
portion of the document.
<BASE>
Optional
Specifies the document base
URL. Refer to the description of
the HTML_BASE routine.
</HEAD>
Optional
Marks the end of the heading
portion of the HTML document.
<BODY>
Required
Starts the body of the document.
The body must be closed by
</BODY>.
Content
Required
HTML elements that the
complete document.
</BODY>
Required
Marks the end of the document.
</HTML>
Optional
Should be included if <HTML>
was generated.
47 A2 39UT Rev02
7.5.3.3
Base TPR Output
If a TDS-Web application wants to reserve a DSA session for use by a specific
browser occurrence, a Base TPR should be used. The Base TPR generates output
that informs the HTTP-DSA gateway and the Web browser of the base URL,
including the context.
You can get a unique application context using the TDS-Web runtime routines
HTTP_GETCONTEXT. Then, this application context is supplied in input for
building the Base TPR.
For the Context Management, refer to Chapter 2 TDS-Web Processing Concepts.
Four output elements are required for a Base TPR:
• The «HTTP/1.0 200 CONTEXT=application-context» response header.
• The «<BASE ...>» element of the HTML document head, which is generated by
the TDS-Web runtime routine HTML_BASE.
• At least one hot link (hyperlink), which allows the user to select a subsequent
transaction using a relative URL.
The following example illustrates the required output. Typically, applications
provide a more complete set of options using links and/or images on the HTML
document.
EXAMPLE:
Notes
HTTP/1.0 200 CONTEXT=1234
<NL>
<HTML>
<HEAD>
<BASE HREF=generated by HTML_BASE>
</HEAD>
<BODY>
You are successfully logged on.
Please <A HREF=«nxtcmd/form.htm»> click here </a> to
continue processing.
</BODY>
1
2
3
4
5
❑
47 A2 39UT Rev02
7-21
NOTES for Example:
7-22
1.
The «HTTP/1.0 200 CONTEXT=1234» response header informs the
MainWay HTTP-DSA Gateway that the connection is being reserved for
further use and that the application context is «1234». The TDS-Web
runtime routine HTTP_GETCONTEXT was used to generate the CONTEXT
value (1234) in the required format.
2.
Value must be «text/html», because the <BASE> HTML must be
processed as HTML by the browser.
3.
The <BASE> tag must appear within the <HEAD> section of the HTML
document.
4.
This HTML statement informs the browser that a new base URL is in
effect, and provides the information necessary to process any relative
URLs that appear in the remainder of the HTML document. The
«<BASE ...>» element of the HTML document head was generated
using the HTML_BASE TDS-Web runtime routine.
5.
Provides a way to invoke the next message for the new permanent session.
The hot link («click here») allows the user to select a subsequent
transaction using a relative URL. The relative URL informs the browser
that the information in the <BASE HREF> should be used in conjunction
with the selected URL to a complete request to the HTTP-DSA Gateway.
For a discussion of how to use relative URLs, refer to Section 2.1 Uniform
Resource Locators (URLs).
47 A2 39UT Rev02
7.5.4
Using TDS-Web Runtime Routines To Analyze/Process HTTP Requests
The TDS-Web Programming Tools include a library of runtime routines to analyze
and process HTTP requests.
A TDS-Web TPR can include calls to these subroutines to perform the needed
functions. These subroutines are linked with a TDS-Web TPR via the link JCL.
Linking is described in Section 7.6 Compiling and Linking TDS-Web TPRs.
Table 7-3 contains a brief description of each TDS-Web routine. For a complete
description of each routine and its calling sequence, refer to Chapter 8 APIs for
TDS-Web Runtime Routines.
Table 7-3.
TDS-Web Runtime Routines (1/2)
TDS-Web
Routine Name
Description
HTML_BASE
Generates the HTML <BASE> tag with an application
context in the required format.
Send an error message and must only be called in
ON-ABORT-TPR.
Obtains a copy of the input message buffer pointer
(used in a non-browser environment).
Generates an HTTP Date entity header.
Abandons a transaction.
Generates an HTTP Expires header.
Release the TDS-Web resources and must only be
called in DISCONNECT and LOGOUT TPRs.
Returns a string that is the application context set as
unique by TDS-Web and without variation during user
connection and returns the hexadecimal value of this
string.
Returns a value for the requested environment-header
variable.
Returns a value for the first environment-header
variable.
Returns a value for the next environment-header
variable.
Returns a value for the requested HTTP header.
Returns a value for the first HTTP header.
Returns a value for the next HTTP header.
Returns the HTTP request method (GET or POST).
Returns the extra pathname information that follows
the transaction name field of the URL.
HTTP_ABORT
HTTP_COPY_MESSAGE
HTTP_DATE
HTTP_EXIT
HTTP_EXPIRES
HTTP_FREEWEB7
HTTP_GETCONTEXT
HTTP_GETENV
HTTP_GETENV_FIRST
HTTP_GETENV_NEXT
HTTP_GETHDR
HTTP_GETHDR_FIRST
HTTP_GETHDR_NEXT
HTTP_GETMETHOD
HTTP_GETPATH
47 A2 39UT Rev02
7-23
Table 7-3.
TDS-Web Runtime Routines (2/2)
TDS-Web
Routine Name
Description
HTTP_GETVAR
HTTP_GETVAR_FIRST
HTTP_GETVAR_NEXT
HTTP_GETVERSION
HTTP_JSQUOTE
Returns the decoded value for the requested variable.
Returns the first requested variable.
Returns the next requested variable.
Returns the HTTP request version (e.g., «1.0»).
Encodes application data into a valid JavaScript
quoted-string literal and returns the result to the calling
program.
Initialize the TDS-Web environment, receives the
message from the browser and parses it into separate
records and variables.
Sends the HTTP response and HTML to the client;
required for COBOL-85 TPRs.
Encodes application data into a JavaScript quotedstring literal and sends the result to the client.
Encodes application data into a JavaScript quotedstring literal and sends the result to the client. HTML
control codes within the text string are converted to
HTML escape sequences.
Encodes and sends text for display by a browser.
HTTP_RECEIVE
HTTP_SEND
HTTP_SENDJSQUOTE
HTTP_SENDJSTEXT
HTTP_SENDTEXT
7.5.5
Table 7-4.
7-24
TDS-Web Routines for Access to HTML Template Database
TDS-Web
Routine Name
Description
H_WEB7_GET_HEADER
H_WEB7_GET_RECORD
Retrieves the content of an HTMLHEADER record.
Retrieves the articles making up an HTML page.
47 A2 39UT Rev02
7.6
Compiling and Linking TDS-Web TPRs
If a TPR written in COBOL-85 uses the COPY for descriptions of the TDS-Web
error codes, the library, which contains the WEB7LIB-C85 subfile, must be set as
input. For a TPR written in C, the library which contains the WEB7LIB_H subfile
must be set as input, and the TPR must be compiled with LEVEL=GANSI.
The TDS-Web TPR must be linked with the TDS-Web runtime CUs, as well as
with the necessary language-specific and system libraries.
A set of sample JCL, that could be used to compile and link a COBOL-85 TPR for
use in the TDS-Web environment is shown in the following example. The
parameters shown in bold are important.
EXAMPLE:
$JOB TPRCOB ;
VL WEB7,DOCSTPR,DIAGIN ;
SEND ‘Compilation of ‘&2’ TDS=’&1’ ‘ ;
LIB SL, INLIB1=&1.SL),INLIB2=(&1.COBOL),INLIB3=(SYS.HSLLIB) ;
COBOL SOURCE=(&2),
CULIB=(&1.CU SHARE=DIR),
CODAPND,LEVEL=L64,OBJLIST,XREF,MAP,&3,OBJA,DDLIST,ILN,
PRTLIB=&1.SL,
DDLIB1=(&1.BIN) ;
JUMP ER-COB SEV GE 3 ;
JUMP OK ;
ER-COB :
SEND ‘*** ERRORS ON COMPILATION ‘&2’ ***’ ;
JUMP FIN ;
OK :
SEND ‘*** COMPILATION ‘&2’ CORRECT ***’ ;
LIB CU,INLIB1=(&1.CU),INLIB2=(SYS.HCULIB) ;
LINKER &2,SM,
OUTLIB=(&1.SMLIB),
COMFILE=&1.SLLIB,SUBFILE=TP7LINKTPR),
PRTLIB=((&1.SL) ;
JUMP ER-LK SEV GE 3 ;
JUMP OK1 ;
ER-LK :
SEND ‘*** ERRORS ON LINK ‘&2’ ***’ ;
JUMP FIN ;
OK1 :
SEND ‘*** LINK ‘&2’ CORRECT ***’ ;
FIN ;
$ENDJOB ;
❑
47 A2 39UT Rev02
7-25
7.7
Examples of TPRs
NOTE:
The code for the four examples below and also the HTML pages used are
delivered with the product. Therefore, it is possible to execute them, and to use
them as inspiration for the creation of your own transactions.
7.7.1
Example 1 - DOCSTPR1
This example is stored under the nameWEB7_DOCSTPR1 in the library
SYS.HSLLIB.
This is a TPR using the minimum functionalities.
This TPR receives the HTTP request, creates its page, and returns the reply by
ending the transaction and the DSA session.
IDENTIFICATION DIVISION.
PROGRAM-ID. DOCSTPR1.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
LEVEL-64.
OBJECT-COMPUTER.
LEVEL-64.
DATA DIVISION.
*
WORKING-STORAGE SECTION.
COPY WEB7LIB-C85.
01 XWORKSIZE
COMP-6.
01 XWORK
PIC X(250).
01 VERSION
PIC X(8).
01 EKOUT
PIC X VALUE "3".
*
LINKAGE SECTION.
COPY TDS-STORAGE.
COPY CONSTANT-STORAGE.
02 TS
PIC X(3500).
*
PROCEDURE DIVISION USING TDS-STORAGE
CONSTANT-STORAGE
TRANSACTION-STORAGE
TX-STORAGE.
*
7-26
47 A2 39UT Rev02
*************************************************
MAINSECTION SECTION.
STARTUP.
This line enables you to call the TPR ABTWEB7 in the case where
the TPR DOC1 is aborted.
MOVE "ABTWEB7" TO ON-ABORT-TPR
The HTTP_RECEIVE routine must be invoked at the beginning of each TPR
in order to retrieve the HTTP request.
CALL "HTTP_RECEIVE" USING ADDRESS OF TDS-STORAGE
ADDRESS OF TRANSACTION-STORAGE.
This routine enables you to retrieve the protocol version of the HTTP used.
CALL "HTTP_GETVERSION" USING ADDRESS OF VERSION
This line enables you to end a transaction.
MOVE SPACE TO NEXT-TPR.
MOVE 1 TO XWORKSIZE.
INITIALIZE XWORK.
STRING
The context at 0 in the HTTP response header indicates to the MAINWAY that
the DSA session should be closed.
"HTTP/" VERSION " 200 CONTEXT=0"
""14,38""
"CONTENT-TYPE: TEXT/HTML"14,38,14,38""
""
""14,38""
DELIMITED BY SIZE INTO XWORK WITH POINTER XWORKSIZE.
COMPUTE XWORKSIZE = XWORKSIZE - 1.
MOVE "1" TO EKOUT.
47 A2 39UT Rev02
7-27
The HTTP_SEND routine enables you to send the HTTP response to the Browser
via the MAINWAY.
CALL "HTTP_SEND" USING ADDRESS
ADDRESS
ADDRESS
ADDRESS
OF
OF
OF
OF
XWORK
XWORKSIZE
EKOUT
INITIALIZE XWORK
MOVE "3" TO EKOUT.
STRING
"<HTML>"
""14,38""
"<TITLE> PAGE 1.1 </TITLE>"
""14,38""
"<BODY>"
""14,38""
"<CENTER><H1>PAGE 1.1</H1></CENTER>"
""14,38""
"<BR>"
""14,38""
"<CENTER>THIS PAGE IS DISPLAYED</CENTER>"
""14,38""
"</BODY>"
""14,38""
"</HTML>"
""14,38""
CALL "HTTP_SEND" USING ADDRESS OF XWORK
ADDRESS OF XWORKSIZE
ADDRESS OF EKOUT
EXIT-STARTUP.
EXIT.
END PROGRAM DOCSTPR1.
7-28
47 A2 39UT Rev02
7.7.2
SYS.HSLLIB.
This is a transaction comprising several TPRs and several HTML pages.
This TPR displays a series of pages before ending the transaction and DSA session.
PROGRAM-ID. DOCSTPR2.
SOURCE-COMPUTER.
LEVEL-64.
OBJECT-COMPUTER.
LEVEL-64.
DATA DIVISION.
COPY WEB7LIB-C85.
77 FIRSTTIME
PIC 9
VALUE 0.
01 APPLCTXT
COMP-6.
01 DOCNAME
PIC X(192).
01 FILLER REDEFINES DOCNAME.
02 FILLER PIC X.
02 ZDOCNAME
PIC X(12).
02 FILLER PIC X(179).
01 DOCNAMESIZE
COMP-6.
01 GCOSCONTEXT
PIC X(8).
01 XWORKSIZE
COMP-6.
01 XWORK
PIC X(250).
01 H-BASEREF
PIC X(250).
01 H-BASEREFSIZE
COMP-6.
01 EKOUT
PIC X VALUE "3".
01 H-HTTPVAR.
02 H-BASE
PIC X(256).
02 H-CBBASE
COMP-6.
02 H-STATUS
COMP-6.
01 H-HTTPCOP.
02 H-TXNAME
PIC X(12) VALUE SPACE.
02 H-TXSIZE
COMP-6.
01 MSGBUF-PTR
POINTER.
01 MSGBUFSIZE
COMP-2.
01 VERSION
PIC X(8).
*
LINKAGE SECTION.
COPY TDS-STORAGE.
02 TS
PIC X(3500).
47 A2 39UT Rev02
7-29
TS-APPLCTXT and TS-GCOSCONTEXT enable you to transmit the context from one TPR to the other.
02 TS-APPLCTXT
COMP-6.
02 TS-GCOSCONTEXT
PIC X(8).
01 BUFFER-COP
PIC X(3000).
*
CONSTANT-STORAGE
TRANSACTION-STORAGE
TX-STORAGE.
************************************************
STARTUP.
*
MOVE "ABTWEB7" TO ON-ABORT-TPR.
This routine enables you to copy the HTTP request in a buffer. In this example, it is used
to retrieve the name of the transaction contained in the request header.
CALL "HTTP_COPY_MESSAGE" USING ADDRESS OF MSGBUF-PTR
ADDRESS OF MSGBUFSIZE
SET ADDRESS OF BUFFER-COP TO MSGBUF-PTR.
INITIALIZE H-TXNAME.
MOVE 1 TO H-TXSIZE.
STRING BUFFER-COP DELIMITED BY SPACES
INTO H-TXNAME WITH POINTER H-TXSIZE.
COMPUTE H-TXSIZE = H-TXSIZE - 1.
*
PERFORM FINDPATH THRU FINDPATHEXIT.
*
PERFORM DOHTTPHEADER.
*
INITIALIZE XWORK.
STRING
"<HTML>"
""14,38""
This line enables you to insert in the code of the HTML page the reference database used by
the Transaction. This base was created by the HTML_BASE routine.
7-30
47 A2 39UT Rev02
H-BASEREF(1:H-BASEREFSIZE)
""14,38""
MOVE "1" TO EKOUT.
ADDRESS OF EKOUT
INITIALIZE XWORK.
MOVE "3" TO EKOUT.
ZDOCNAME contains the name of the page to display.
retrieve the page to be displayed.
The present test enables you to
EVALUATE ZDOCNAME(1:11)
WHEN "PAGE_DOC2.1"
STRING
"<TITLE>PAGE 2.1</TITLE>"
""14,38""
"<BODY>"
""14,38""
""14,38""
"<BR>"
""14,38""
'<A HREF="PAGE_DOC2.2">’
"PAGE 2.2"
"</A> (Next Page)"
""14,38""
"<BR>"
""14,38""
'<A HREF="PAGE_DOC2.3">'
"PAGE 2.3"
"</A> (Last Page)"
""14,38""
"</BODY>"
""14,38""
"</HTML>"
""14,38""
DELIMITED BY SIZE INTO XWORK WITH POINTER XWORKSIZE
47 A2 39UT Rev02
7-31
While the last page is not invoked, a TPR is recalled (in this example, it is the same one).
MOVE "DOCSTPR2" TO NEXT-TPR
WHEN "PAGE_DOC2.2"
STRING
""14,38""
"<BODY>"
""14,38""
"<BR>"
""14,38""
'<A HREF="PAGE_DOC2.1">’
"PAGE 2.1"
"</A> (Next Page)"
""14,38""
"<BR>"
""14,38""
'<A HREF="PAGE_DOC2.3">'
"PAGE 2.3"
"</A> (Last Page)"
""14,38""
"</BODY>"
""14,38""
"</HTML>"
""14,38""
MOVE "DOCSTPR2" TO NEXT-TPR
WHEN "PAGE_DOC2.3"
STRING
""14,38""
"<BODY>"
""14,38""
""14,38""
"<BR>"
""14,38""
"THIS IS THE LAST PAGE :"
""14,38""
"<BR>"
""14,38""
"THE TRANSACTION IS FINISHED,"
" THE DSA SESSION IS CLOSED."
""14,38""
"</BODY>"
""14,38""
7-32
47 A2 39UT Rev02
"</HTML>"
""14,38""
When the last page of the Transaction is evoked, the Transaction is ended
MOVE SPACE TO NEXT-TPR
END-EVALUATE
COMPUTE XWORKSIZE = XWORKSIZE - 1
CALL "HTTP_SEND" USING ADDRESS OF
ADDRESS OF
ADDRESS OF
ADDRESS OF
GO TO EXIT-STARTUP.
XWORK
XWORKSIZE
EKOUT
FINDPATH.
This helper routine returns the URL of the page actually displayed. If the chain is empty,
it concerns a connection; we are therefore in the first TPR of the Transaction.
CALL "HTTP_GETPATH" USING ADDRESS OF DOCNAME
ADDRESS OF DOCNAMESIZE
IF DOCNAMESIZE = 0
MOVE 0 TO FIRSTTIME
MOVE 0 TO TS-APPLCTXT
ELSE
MOVE 1 TO FIRSTTIME
END-IF
IF FIRSTTIME = 0
On connection, the TPR should know the first page to send to the Browser.
MOVE " PAGE_DOC2.1" TO DOCNAME
MOVE 11 TO DOCNAMESIZE
MOVE 0 TO TS-APPLCTXT
END-IF.
FINDPATHEXIT.
EXIT.
DOHTTPHEADER.
IF TS-APPLCTXT = ZERO
47 A2 39UT Rev02
7-33
In the case where no context has been transferred from the previous TPR (when it concerns
the first TPR of the Transaction, for example), this routine helper is used in order
to supply one. Then, this context is saved in the TRANSACTION STORAGE.
CALL "HTTP_GETCONTEXT" USING ADDRESS OF GCOSCONTEXT
ADDRESS OF APPLCTXT
MOVE APPLCTXT TO TS-APPLCTXT
MOVE GCOSCONTEXT TO TS-GCOSCONTEXT
ELSE
In the case, where a context is saved in the TRANSACTION STORAGE, it is retrieved.
MOVE TS-APPLCTXT TO APPLCTXT
MOVE TS-GCOSCONTEXT TO GCOSCONTEXT
END-IF.
PERFORM HTMLBASE THRU HTMLBASEEXIT.
PERFORM GENERATE-APPCONTEXT.
PERFORM OKHEADER.
DOHTTPHEADEREXIT.
EXIT.
*
GENERATE-APPCONTEXT.
IF ZDOCNAME(1:11) = "PAGE_DOC2.3"
If the last page of the Transaction is invoked, the connection is ended by placing
the context at zero.
MOVE ZEROS TO GCOSCONTEXT
END-IF.
GENERATE-APPCONTEXTEXIT.
EXIT.
*
OKHEADER.
INITIALIZE XWORK.
STRING
"HTTP/" VERSION " 200 CONTEXT="
7-34
47 A2 39UT Rev02
This insertion in the message enables you to transmit the context to the MAINWAY.
If it is at zero, the MAINWAY ends the DSA session.
GCOSCONTEXT
""14,38""
""
""14,38""
MOVE "1" TO EKOUT.
ADDRESS OF EKOUT
*
HTMLBASE.
MOVE 256 TO H-CBBASE.
MOVE SPACE TO H-BASE.
This routine enables you to create the reference base, which should be used by the Browser
to seek the HTML pages of the Transaction.
CALL "HTML_BASE" USING ADDRESS OF H-BASE
ADDRESS OF H-CBBASE
ADDRESS OF GCOSCONTEXT
ADDRESS OF APPLCTXT
ADDRESS OF H-STATUS
MOVE 1 TO H-BASEREFSIZE.
INITIALIZE H-BASEREF.
COMPUTE H-CBBASE = H-CBBASE - 2.
STRING
H-BASE(1:H-CBBASE)
H-TXNAME(1:H-TXSIZE)
'/">'
""14,38""
DELIMITED BY SIZE INTO H-BASEREF WITH POINTER H-BASEREFSIZE.
COMPUTE H-BASEREFSIZE = H-BASEREFSIZE - 1.
HTMLBASEEXIT.
EXIT.
EXIT-STARTUP.
EXIT PROGRAM.
47 A2 39UT Rev02
7-35
7.7.3
SYS.HSLLIB.
This transaction is going to search for the pages in the DATA BASE.
This TPR searches the pages to display in the DATA BASE. The pages have been
previously inserted in the database with the help of administration utilities.
PROGRAM-ID.
DOCSTPR3.
SOURCE-COMPUTER.
LEVEL-64.
OBJECT-COMPUTER.
LEVEL-64.
DATA DIVISION.
SUB-SCHEMA SECTION.
DB DB-IFN USING HTML-SUBSCHEMA WITHIN HTMLSCHEMA.
DB-DESCRIPTIONS IN WORKING-STORAGE SECTION.
*
COPY WEB7LIB-C85.
77 FIRSTTIME
PIC 9
VALUE 0.
01 NBRECORD
PIC 99.
01 DOCNAME
PIC X(192).
02 FILLER
PIC X.
02 ZDOCNAME
PIC X(11).
02 FILLER
PIC X(180).
01 DOCNAMESIZE
COMP-6.
01 APPLCTXT
COMP-6.
01 GCOSCONTEXT
PIC X(8).
01 XWORKSIZE
COMP-6.
01 XWORK
PIC X(250).
01 H-BASEREF
PIC X(250).
01 H-BASEREFSIZE
COMP-6.
01 EKOUT
PIC X VALUE "3".
01 H-HTTPVAR.
02 H-BASE
PIC X(256).
02 H-CBBASE
COMP-6.
02 H-STATUS
COMP-6.
01 H-HTTPCOP.
02 H-TXNAME
02 H-TXSIZE
COMP-6.
01 MSGBUF-PTR
POINTER.
01 MSGBUFSIZE
COMP-6.
01 VERSION
PIC X(8).
*
7-36
47 A2 39UT Rev02
LINKAGE SECTION.
COPY TDS-STORAGE.
02 TS
PIC X(3500).
02 TS-APPLCTXT
COMP-6.
02 TS-GCOSCONTEXT
PIC X(8).
01 BUFFER-COP
PIC X(3000).
*
CONSTANT-STORAGE
TRANSACTION-STORAGE
TX-STORAGE.
*
************************************************
*
STARTUP.
*
*
MOVE 1 TO H-TXSIZE.
*
*
*
PERFORM READSET THRU READSETEXIT.
*
MOVE "DOCSTPR3" TO NEXT-TPR.
*
EXIT-STARTUP.
EXIT PROGRAM.
47 A2 39UT Rev02
7-37
*************************
FINDPATH.
*
*
IF DOCNAMESIZE = 0
MOVE 0 TO FIRSTTIME
MOVE ZERO TO TS-APPLCTXT
ELSE
MOVE 1 TO FIRSTTIME
END-IF.
*
INITIALIZE HTMLPAGENAME.
*
IF FIRSTTIME = 0
MOVE "PAGE_DOC3.1" TO DOCNAME
MOVE DOCNAME(1:DOCNAMESIZE) TO
HTMLPAGENAME(1:DOCNAMESIZE)
ELSE
IF DOCNAME(1:1) = "/"
COMPUTE DOCNAMESIZE = DOCNAMESIZE - 1
ELSE
END-IF
END-IF.
Search for the page in the DATA BASE.
FIND ANY HTMLHEADER.
PERFORM STATUS-CHECK.
GET HTMLHEADER.
*
FINDPATHEXIT.
EXIT.
*
7-38
47 A2 39UT Rev02
Search for lines, which make up the page in the DATA BASE.
READSET.
MOVE 0 TO NBRECORD.
FIND FIRST WITHIN HTMLSET.
ADD 1 TO NBRECORD.
PERFORM UNTIL DB-STATUS NOT = ZEROES
PERFORM DOMEMBER
FIND NEXT WITHIN HTMLSET
PERFORM STATUS-CHECK
END-PERFORM.
READSETEXIT.
EXIT.
*
DOMEMBER is the function, which enables display of the HTML pages from the DATA BASE.
In the present example, this function recopies the page line by line.
DOMEMBER.
The three types of RECORD which contain the DATA BASE are the HTML RECORD, the ACTION RECORD
and the BINARY RECORD. Only the HTML RECORD does not interest us for the moment.
EVALUATE DB-RECORD-NAME
WHEN "HTMLRECORD"
MOVE " " TO XWORK
GET HTMLRECORD
MOVE FUNCTION UPPER-CASE(HTMLDATA) TO XWORK
In the case where the page to display already contains a reference base,
it should be replaced by the Transaction one.
Trick: If you wish to retain your reference base, enter a space at the beginning of the line.
IF XWORK(1:11) = "<BASE HREF="
PERFORM HTMLBASE THRU HTMLBASEEXIT
MOVE H-BASEREF TO HTMLDATA
MOVE XWORKSIZE TO HTMLSIZE
END-IF
IF XWORK(1:7) = "</HTML>"
MOVE "3" TO EKOUT
ELSE
MOVE "1" TO EKOUT
END-IF
47 A2 39UT Rev02
7-39
*
*
CALL "HTTP_SEND" USING ADDRESS OF HTMLDATA
ADDRESS OF HTMLSIZE
ADDRESS OF EKOUT
ADDRESS OF TRANSACTION-STORAGE
WHEN "ACTIONRECORD"
NOT USED IN THIS EXAMPLE
GET ACTIONRECORD
WHEN "BINARYRECORD"
THIS IS A FUTURE FEATURE, WILL NOT BE REACHED
GET BINARYRECORD
END-EVALUATE.
*
DOHTTPHEADER.
ADDRESS OF APPLCTXT
ELSE
END-IF
PERFORM OKHEADER.
*
DOHTTPHEADEREXIT.
EXIT.
*
MOVE ZEROES TO GCOSCONTEXT
END-IF.
*
EXIT.
*
OKHEADER.
INITIALIZE XWORK.
STRING
GCOSCONTEXT
""14,38""
""
""14,38""
7-40
47 A2 39UT Rev02
MOVE "1" TO EKOUT.
ADDRESS OF EKOUT
*
This function enables you to manage the STATUSES returned when manipulating the DATA BASE.
In this example, only the 0000000 and 0502100 STATUSES are managed correctly.
Use the ENDSET function as input to manage the others.
STATUS-CHECK.
EVALUATE DB-STATUS
WHEN 0000000
*
EVEYTHING O.K.
CONTINUE
WHEN 0502100
*
END OF SET
PERFORM ENDSET
CONTINUE
WHEN 0502400
*
NOT FOUND
DISPLAY "ERROR 404 DB-STATUS : " DB-STATUS
UPON ALTERNATE CONSOLE
GO TO EXIT-STARTUP
WHEN OTHER
DISPLAY "INTERNAL PROGRAM ERROR DB-STATUS : " DB-STATUS
GO TO EXIT-STARTUP
END-EVALUATE.
*
HTMLBASE.
CALL "HTML_BASE" USING ADDRESS OF H-BASE
ADDRESS OF H-CBBASE
ADDRESS OF GCOSCONTEXT
ADDRESS OF APPLCTXT
ADDRESS OF H-STATUS
47 A2 39UT Rev02
7-41
STRING
H-BASE(1:H-CBBASE)
'/">'
""14,38""
HTMLBASEEXIT.
EXIT.
*
ENDSET.
IF NBRECORD = 0
MOVE 1 TO XWORKSIZE
INITIALIZE XWORK
STRING
"<HTML>"
""14,38""
"<TITLE>NO RECORD</TITLE>"
""14,38""
"<BODY>"
""14,38""
"<H1>NO RECORD IN THE HTMLSET</H1>"
""14,38""
"</BODY></HTML>"
""14,38""
MOVE "3" TO EKOUT
ADDRESS OF EKOUT
END-IF.
7-42
47 A2 39UT Rev02
7.7.4
SYS.HSLLIB.
This transaction uses the ACTION RECORD.
This TPR will display a page whose lines should be updated on each call.
The person who created the page, to insert in his/her page a default value in a
section, that is called ACTION RECORD. This section is delimited by the
comments  and . When inserting this page in
the base, this section shall be saved in a special record.
Here is the page created by the user:

<HTML>
<title>PAGE 4.1</title>
<BODY BGCOLOR="#FFFFFF">
<BASE HREF="C:/">
<CENTER><H1>PAGE 4.1</H1></CENTER>
THE DATE IS :
<BR>
<BR>
<CENTER>
Here is the section of the page, which will be transformed by the TPR.

01/01/00001

</CENTER>
<BR>
<A HREF="PAGE_DOC4.1">page 4.1</A> (Same Page but with different time)
<BR>
<A HREF="PAGE_DOC3.3">page 3.3</A> (Last Page)
</BODY>
</HTML>
47 A2 39UT Rev02
7-43
Figure 7-3.
Example of Netscape User Page
and the one created by the TPR:

<HTML>
<title>PAGE 4.1</title>
<BODY BGCOLOR="#FFFFFF">
<base href="http://mw.loc:8080/BY0F.WEB7/40328fb0.3626eb4c.01ACAF4E/DOC4/">
<CENTER><H1>PAGE 4.1</H1></CENTER>
THE DATE IS :
<BR>
<BR>
<CENTER>
Here is the line added by the TPR.
FRI, 16 OCT 1998 07:48:14 GMT
</CENTER>
<BR>
<A HREF="PAGE_DOC4.1">page 4.1</A> (Same Page but with different time)
<BR>
<A HREF="PAGE_DOC3.3">page 3.3</A> (Last Page)
</BODY>
</HTML>
7-44
47 A2 39UT Rev02
Figure 7-4.
Example of Netscape TPR Page
Finally the TPR code:
PROGRAM-ID.
DOCSTPR4.
SOURCE-COMPUTER.
LEVEL-64.
OBJECT-COMPUTER.
LEVEL-64.
DATA DIVISION.
SUB-SCHEMA SECTION.
DB DB-IFN USING HTML-SUBSCHEMA WITHIN HTMLSCHEMA.
DB-DESCRIPTIONS IN WORKING-STORAGE SECTION.
*
COPY WEB7LIB-C85.
77 FIRSTTIME
PIC 9
VALUE 0.
01 NBRECORD
PIC 99.
01 DOCNAME
PIC X(192).
02 FILLER
PIC X.
02 ZDOCNAME
PIC X(11).
02 FILLER
PIC X(180).
01 DOCNAMESIZE
COMP-6.
01 APPLCTXT
COMP-6.
01 GCOSCONTEXT
PIC X(8).
01 XWORKSIZE
COMP-6.
01 XWORK
PIC X(250).
47 A2 39UT Rev02
7-45
01
01
01
01
01
H-BASEREF
H-BASEREFSIZE
EKOUT
H-HTTPVAR.
02 H-BASE
02 H-CBBASE
02 H-STATUS
H-HTTPCOP.
02 H-TXNAME
02 H-TXSIZE
MSGBUF-PTR
MSGBUFSIZE
VERSION
H-DATE
H-CBDATE
NB-ACTION
PIC X(250).
COMP-6.
PIC X VALUE "3".
PIC X(256).
COMP-6.
COMP-6.
COMP-6.
POINTER.
COMP-6.
PIC X(8).
PIC X(50).
COMP-6.
PIC 99 VALUE ZERO.
01
01
01
01
01
01
*
LINKAGE SECTION.
COPY TDS-STORAGE.
02 TS
PIC X(3500).
02 TS-APPLCTXT
COMP-6.
02 TS-GCOSCONTEXT
PIC X(8).
01 BUFFER-COP
PIC X(3000).
*
CONSTANT-STORAGE
TRANSACTION-STORAGE
TX-STORAGE.
*
************************************************
*
STARTUP.
*
*
7-46
47 A2 39UT Rev02
MOVE 1 TO H-TXSIZE.
*
MOVE 50 TO H-CBDATE.
This helper routine sends back the date and GMT time.
CALL "HTTP_DATE" USING ADDRESS OF H-DATE
ADDRESS OF H-CBDATE.
*
*
*
MOVE "DOCSTPR4" TO NEXT-TPR.
*
EXIT-STARTUP.
EXIT PROGRAM.
*************************
FINDPATH.
*
*
IF DOCNAMESIZE = 0
MOVE 0 TO FIRSTTIME
ELSE
MOVE 1 TO FIRSTTIME
END-IF.
*
INITIALIZE HTMLPAGENAME.
*
IF FIRSTTIME = 0
MOVE "PAGE_DOC4.1" TO DOCNAME
47 A2 39UT Rev02
7-47
ELSE
IF DOCNAME(1:1) = "/"
COMPUTE DOCNAMESIZE = DOCNAMESIZE - 1
ELSE
END-IF
END-IF.
*
FIND ANY HTMLHEADER.
*
GET HTMLHEADER.
*
FINDPATHEXIT.
EXIT.
*
READSET.
MOVE 0 TO NBRECORD.
FIND FIRST WITHIN HTMLSET.
ADD 1 TO NBRECORD.
PERFORM UNTIL DB-STATUS NOT = ZEROES
PERFORM DOMEMBER
FIND NEXT WITHIN HTMLSET
END-PERFORM.
READSETEXIT.
EXIT.
*
DOMEMBER.
EVALUATE DB-RECORD-NAME
WHEN "HTMLRECORD"
MOVE " " TO XWORK
GET HTMLRECORD
MOVE FUNCTION UPPER-CASE(HTMLDATA) TO XWORK
MOVE H-BASEREF TO HTMLDATA
MOVE XWORKSIZE TO HTMLSIZE
END-IF
MOVE "3" TO EKOUT
ELSE
MOVE "1" TO EKOUT
END-IF
7-48
47 A2 39UT Rev02
ADDRESS
ADDRESS
ADDRESS
OF
OF
OF
OF
HTMLDATA
HTMLSIZE
EKOUT
TRANSACTION-STORAGE
The records are placed sequentially in the DATA BASE. By browsing the records to display,
the function will find the ACTION RECORD in exactly the same place as in the original page.
WHEN "ACTIONRECORD"
GET ACTIONRECORD
MOVE FUNCTION UPPER-CASE(ACTIONDATA) TO XWORK
The ACTION Records being regrouped at least by two in the DATA BASE (the two
comments  and ), it is necessary to have a reference point
to insert the new action.
IF XWORK(1:ACTIONSIZE) = ""
ADD 1 TO NB-ACTION
END-IF
If there are several sections of ACTION RECORD in the page, it is necessary to be able to
decide the action to be carried out at the right place. In our example, there is only one
single action: the date and GMT time is displayed.
*
IF NB-ACTION = 1
COMPUTE XWORKSIZE = H-CBDATE - 6
MOVE H-DATE(7:XWORKSIZE) TO XWORK
MOVE "1" TO EKOUT
CALL "HTTP_SEND" USING ADDRESS OF
ADDRESS OF
ADDRESS OF
ADDRESS OF
END-IF
WHEN "BINARYRECORD"
THIS IS A FUTURE FEATURE, WILL NOT
GET BINARYRECORD
END-EVALUATE.
XWORK
XWORKSIZE
EKOUT
TRANSACTION-STORAGE
BE REACHED
*
DOHTTPHEADER.
ADDRESS OF APPLCTXT
47 A2 39UT Rev02
7-49
ELSE
END-IF
PERFORM OKHEADER.
*
DOHTTPHEADEREXIT.
EXIT.
*
MOVE ZEROES TO GCOSCONTEXT
END-IF.
*
EXIT.
*
OKHEADER.
INITIALIZE XWORK.
STRING
GCOSCONTEXT
""14,38""
""
""14,38""
MOVE "1" TO EKOUT.
ADDRESS OF EKOUT
*
STATUS-CHECK.
EVALUATE DB-STATUS
WHEN 0000000
*
EVEYTHING O.K.
CONTINUE
WHEN 0502100
*
END OF SET
PERFORM ENDSET
CONTINUE
7-50
47 A2 39UT Rev02
WHEN 0502400
*
NOT FOUND
DISPLAY "ERROR 404 DB-STATUS : " DB-STATUS
GO TO EXIT-STARTUP
WHEN OTHER
DISPLAY "INTERNAL PROGRAM ERROR DB-STATUS : " DB-STATUS
GO TO EXIT-STARTUP
END-EVALUATE.
*
HTMLBASE.
CALL "HTML_BASE" USING ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
OF
OF
OF
OF
OF
OF
H-BASE
H-CBBASE
GCOSCONTEXT
APPLCTXT
H-STATUS
STRING
H-BASE(1:H-CBBASE)
'/">'
""14,38""
HTMLBASEEXIT.
EXIT.
*
ENDSET.
IF NBRECORD = 0
MOVE 1 TO XWORKSIZE
INITIALIZE XWORK
STRING
"<HTML>"
""14,38""
"<TITLE>NO RECORD</TITLE>"
""14,38""
"<BODY>"
""14,38""
"<H1>NO RECORD IN THE HTMLSET</H1>"
""14,38""
"</BODY></HTML>"
""14,38""
MOVE "3" TO EKOUT
47 A2 39UT Rev02
7-51
ADDRESS
ADDRESS
ADDRESS
END-IF.
7.7.5
OF
OF
OF
OF
XWORK
XWORKSIZE
EKOUT
TRANSACTION-STORAGE
Example 5 – DOCSTPR5 and DOCSTPR6
Two TPRs, WEB7_DOCSTPR5 and WEB7_DOCSTPR6, are provided in the
SYS.HSLLIB library. They show how to use the HTML Template Database access
routines, H_WEB7_GET_HEADER and H_WEB7_GET_RECORD.
The following is an example of use of the "H_WEB7_GET_RECORD" routine.
COPY WEB7LIB-C85.
CONSTANT-STORAGE
*
************************************************
*
Initialisation des champs WS-I-NOMDOC et WS-I-NOMDOCSIZE
*
*
*
*
READSET.
MOVE 0 TO NBRECORD.
MOVE "F" TO WS-IO-NEXT.
PERFORM UNTIL WS-RET-ACCESS NOT = ZEROES
MOVE ZERO TO WS-RET-ACCESS
CALL "H_WEB7_GET_RECORD" USING ADDRESS OF WS-STRUCT-ACCESS
ADDRESS OF WS-RET-ACCESS
ADD 1 TO NBRECORD
7-52
47 A2 39UT Rev02
IF WS-RET-ACCESS = 0
PERFORM DOMEMBER
END-IF
MOVE "N" TO WS-IO-NEXT
END-PERFORM.
READSETEXIT.
EXIT.
*
DOMEMBER.
EVALUATE WS-O-REC-TYPE
WHEN "H"
MOVE " " TO XWORK
MOVE FUNCTION UPPER-CASE(WS-O-REC-DATA) TO XWORK
MOVE H-BASEREF TO WS-O-REC-DATA
MOVE H-BASEREFSIZE TO WS-O-REC-SIZE
END-IF
MOVE "3" TO EKOUT
STATUS-CHECK.
EVALUATE WS-RET-ACCESS
WHEN 0
CONTINUE
WHEN 1
PERFORM ENDSET
CONTINUE
47 A2 39UT Rev02
7-53
❑
7-54
47 A2 39UT Rev02
8. APIs for TDS-Web Runtime Routines
This section describes each of the application programming interfaces (APIs) that
can be used in TDS applications (TPRs) to analyze and process HTTP requests and
create responses. These APIs enable TPR developers to access the TDS-Web
runtime routines that are entry points of the CU named WEB7_HTTPMAIN_C in
the library SYS.HCULIB.
The DOCSTPR example applications written in COBOL-85 that are delivered with
TDS-Web illustrate how to use these APIs to call the TDS-Web runtime routines.
• Using the TDS-Web Runtime Routines.
• Initializing TDS-Web TPR Environment.
• Handling TDS-Web TPR Input.
• Building TDS-Web TPR Output.
• Handling TDS-Web TPR Output.
• Syntax Definitions for TDS-Web APIs.
NOTES:
47 A2 39UT Rev02
1.
The TDS-Web runtime routines that handle HTTP headers and HTML data
are not browser specific. However, variations in handling may occur with
different browser versions. To ensure that specific features work as
expected, consult the HTTP and HTML specifications at the URL listed in
World Wide Web and HTML Documentation in the Preface and the
specifications for the specific browser(s) that are used.
2.
All of the examples in this document are intended to be browser-neutral.
However, examples that include JavaScript will not necessarily work the
same when used with different browsers. Consult the specifications for the
specific browser(s) that are used to determine exactly which script features
are supported.
8-1
8.1
Using the TDS-Web Runtime Routines
This section provides some background information about how to call the
TDS-Web runtime routines.
8.1.1
8.1.2
Characteristics of the TDS-Web Runtime Routines
1.
The TDS-Web runtime routines are designed to be invoked from TPRs written
in either COBOL-85 or C.
2.
All parameters are passed by reference (by the address of the parameter).
3.
None of these routines returns a function value.
Checking for Errors
The TDS-Web runtime routines typically return either a zero to indicate successful
execution or a negative value to indicate that an error occurred during execution. A
few of these routines have no error return. Both COBOL-85 and C programs must
test the error-return parameter (err) to determine whether the called routine
completed execution successfully.
Symbolic definitions of the error values that can be returned are included in:
• WEB7lib.h for C programs
• WEB7lib-c85 for COBOL-85 programs
To include the error definitions in a C program, use:
#include <WEB7lib.h>
To include the error definitions in a COBOL-85 program, use:
copy WEB7lib-c85
You can then test for errors using the symbolic names that are listed in the syntax
descriptions in Section 8.6 Syntax Definitions for TDS-Web APIs.
8-2
47 A2 39UT Rev02
8.1.3
Using the TDS-Web Runtime Routines from COBOL-85
The data returned by these routines is suitable for use in C programs; each string is
terminated by a null byte.
COBOL-85 programs do not recognize the null byte as an end-of-string indicator;
however, COBOL-85 programs can use the following technique for dealing with
these variable-length strings.
Instead of defining fixed-length string variables in the COBOL program, such as
01 MyVariable
pic x(80).
declare the data as variable length, as follows:
77 cbMyVariable
comp-6.
01 MyVariable.
02 bytes pic x occurs 0 to 80 times depending on cbMyVariable.
The declaration shown above causes the COBOL compiler to generate code that
uses the current value of cbMyVariable as the length of MyVariable whenever
data is moved to or from MyVariable.
By passing these two variables to the TDS-Web API, the COBOL program will
automatically use the exact current length of any variable returned by the called
runtime routine.
To use this technique, you must initialize cbMyVariable with the actual
maximum size of the associated MyVariable prior to any call to a TDS-Web API,
as shown in the following example.
MOVE 80 to cbMyVariable.
CALL "HTTP_GETVAR" using address of somename,
address of MyVariable,
address of cbMyVariable,
address of err,
On return from HTTP_GETVAR, any reference in the COBOL source to
MyVariable will use only the number of bytes specified in cbMyVariable. For
information about the parameters shown in this example call, refer to the
description of HTTP_GETVAR.
47 A2 39UT Rev02
8-3
An alternative method for handling the variable-length values returned by the
TDS-Web runtime routines is to use the COBOL-85 variable-string feature. The
following example illustrates this method.
77 cbMyVariable
comp-6.
01 MyVariable
pic X(80).
CALL "HTTP_GETVAR" using address of somename,
address of MyVariable,
address of cbMyVariable,
address of err,
MOVE MyVariable(1:cbMyVariable) to someloc.
8-4
47 A2 39UT Rev02
8.2
Initializing TDS-Web TPR Environment
Before handling input parameters, the TPR must initialize the TDS-Web
environment for the TPR and receive the message from the browser. This is done
by calling the TDS-Web runtime routine HTTP_RECEIVE. This call is
mandatory.
Refer to the description of HTTP_RECEIVE in Section 8.6.22.
47 A2 39UT Rev02
8-5
8.3
Handling TDS-Web TPR Input
This section describes the format in which a TDS-Web TPR receives input, and
provides a brief overview of the TDS-Web runtime routines that are used to handle
input.
8.3.1
Format of TDS-Web TPR Input
The general layout of TDS-Web input message is shown in Figure 8-1. Each of the
input parts is described in the text that follows the figure.
T ra n saction n am e
E n viro n m e n t H ea d er(s)
ze ro to n
en v ir o n m en t
h ea d er s
CRLF
H T T P r eq u e st:
G E T or P O ST
H T T P H e a d e r(s)
H T T P r eq u est
h ea d e rs
CRLF
H T M L fo rm va ria b les
Figure 8-1.
ze ro to n
H T M L fo rm
v a ria b les
TDS-Web Input Format
The HTTP request, HTTP request headers, and any HTML form variables are
generated by the Web browser when the browser user makes a request.
The Web browser sends the message to the MainWay HTTP-DSA Gateway. The
gateway generates a message prefix, which is necessary to satisfy the TDS
requirement that the command name be in the first twelve bytes of the message.
To create the prefix, the gateway copies the transaction name from the URL and
places it at the beginning of the message prefix. The gateway also needs a way to
inform the TPR of the session identifier. The environment header is designed to
deal with this requirement, as well as any as-yet-undefined requirements.
8-6
47 A2 39UT Rev02
8.3.2
Format of Environment Headers
The environment headers are only concerned with the session identifier managed
by the gateway. They have the same format as a DOS or UNIX environment:
<keyword><=><value>
Each environment header is terminated by a CRLF (also known as <NL>). The last
environment header is followed by an empty record that contains only CRLF. The
result is an extendible protocol that allows the gateway to provide any number
(zero or more) environment variables.
The TPR can read the variables in the environment headers by using the
HTTP_GETENV family of TDS-Web APIs. This family consists of the following
APIs:
• HTTP_GETENV
• HTTP_GETENV_FIRST
• HTTP_GETENV_NEXT
8.3.3
Format of HTTP Headers
The next segment of the input message consists of the HTTP headers.
The first record is the HTTP request, which defines the type of request: GET or
POST.
Subsequent records are HTTP request headers, each of which has the following
format:
<keyword><colon><space><value>
Each HTTP header is terminated by a CRLF. The last HTTP header is followed by
an empty record that contains only CRLF.
The TPR can read the HTTP headers by using the HTTP_GETHDR family of
TDS-Web APIs. This family consists of the following APIs:
• HTTP_GETHDR
• HTTP_GETHDR_FIRST
• HTTP_GETHDR_NEXT
47 A2 39UT Rev02
8-7
8.3.4
Format of Form Variables
Each form variable has the following format:
<keyword><=><value>
Each form variable except the last is terminated by an ampersand (&).
The TPR can read the form variables by using the HTTP_GETVAR family of
TDS-Web APIs. This family consists of the following APIs:
• HTTP_GETVAR
• HTTP_GETVAR_FIRST
• HTTP_GETVAR_NEXT
8.3.5
Other TDS-Web Runtime Routines for Input
The TPR may also use:
• HTTP_GETPATH that returns the extra path information.
• HTTP_GETMETHOD that returns the HTTP request method, "GET" or
"POST".
• HTTP_COPY_MESSAGE that copies the input message to caller’s buffer.
8-8
47 A2 39UT Rev02
8.4
Building TDS-Web TPR Output
Among the TDS-Web runtime routines, some can be used to build part of the
TDS-Web TPR Output:
• HTTP_GETVERSION gets the version of the HTTP request.
• HTTP_GETCONTEXT gets the application context set as unique by TDS-Web.
Its output is used as input parameter for building a BASE.
• HTML_BASE generates a <BASE> directive with application context.
47 A2 39UT Rev02
8-9
8.5
Handling TDS-Web TPR Output
This section provides a brief overview of the TDS-Web runtime routines that are
used to send output. A detailed description of the minimum output that a TPR is
required to send, and also a list of additional output items that a TPR can send if
needed, is given later in this chapter.
The TPR can send output by using the HTTP_SEND family of TDS-Web APIs.
This family consists of the following APIs:
• HTTP_SENDJSQUOTE
• HTTP_SENDJSTEXT
• HTTP_SENDTEXT
Each of the HTTP_SEND routines has a specific purpose, which is explained in the
description of each individual APIs.
Typically a TPR will use two or more of the HTTP_SEND routines to create a single
logical output message to be sent to a browser. Refer to corresponding sections for
examples of how to use multiple HTTP_SEND routines to create a single output
message.
8.5.1
TDS-Web Buffers TPR Output
Although these are "SEND" APIs, a call to one of these APIs may not cause an
immediate send of the data associated with the call. Instead, the data is placed in
an output buffer. If another HTTP_SEND family call is executed by the TPR, the
new data is appended to the data already in the buffer.
An actual send occurs, that is, a DSA letter is created and transmitted, only when:
• the output buffer is full, and/or,
• the TPR completes processing and exits.
The level indicator must be supplied to each call of HTTP_SEND and is implicitly
set to 1 (ESI) for HTTP_SEND family routines other than HTTP_SEND:
• ‘1’ for ESI, end of segment indicator: the data is placed in an output buffer.
• ‘2’ for EMI, end of message indicator: the data is placed in an output buffer,
which is released to the correspondent, but the TPR does not release the turn.
• ‘3’ for EGI, end of group indicator: the data is placed in an output buffer, which
is released to the correspondent when the TPR completes processing and exits.
Then, TDS gives the turn to the browser.
The last call must be a call to HTTP_SEND and supply ‘3’ as level indicator.
Generally, the TPR uses at least two calls to HTTP_SEND family routines, one for
the HTML page header, and the other for the page itself.
8-10
47 A2 39UT Rev02
8.5.2
Using HTTP_SEND Calls
COBOL-85 and C programs are required to use the HTTP_SEND family of calls for
all output that is directed to a browser, because using these calls:
• ensures that the HTTP protocol is enforced,
• ensures that the ON_ABORT_TPR, LOGOUT and DISCNCT TPRs run
normally,
• guarantees that COBOL-85 output and C library output are merged into a single
output stream.
Furthermore, using these routines offers two advantages:
• Future changes to the HTTP protocol will be transparent to the programs. These
changes can be handled by the HTTP_SEND routines, instead of directly by the
program.
• Any future enhancements to the HTTP_SEND routines will automatically be
available to the program.
47 A2 39UT Rev02
8-11
8.6
Syntax Definitions for TDS-Web APIs
This section contains the syntax definitions and usage rules for each of the
TDS-Web APIs.
All of the TDS-Web APIs are shown in Table 8-1.
Table 8-1
TDS-Web APIs
HTML_BASE
HTTP_COPY_MESSAGE
HTTP_EXPIRES
HTTP_FREEWEB7
HTTP_GETENV
HTTP_GETENV_NEXT
HTTP_GETHDR_FIRST
HTTP_GETMETHOD
HTTP_GETVAR
HTTP_GETVAR_NEXT
HTTP_JSQUOTE
HTTP_SEND
HTTP_SENDJSTEXT
8-12
HTTP_ABORT
HTTP_DATE
HTTP_EXIT
HTTP_GETCONTEXT
HTTP_GETENV_FIRST
HTTP_GETHDR
HTTP_GETHDR_NEXT
HTTP_GETPATH
HTTP_GETVAR_FIRST
HTTP_GETVERSION
HTTP_RECEIVE
HTTP_SENDJSQUOTE
HTTP_SENDTEXT
47 A2 39UT Rev02
8.6.1
HTML_BASE
Description
Generates an HTML <BASE> element with application context in the form:
<BASE href="http://gateway:port/node.mbx/1234.5678.abcd/">
Also returns the application-context field as a separate string, to be sent by the TPR
in the HTTP response header.
Syntax in C
HTML_BASE(base, &cbBase, gwContext, &appContext, &err, ptxs);
Syntax in COBOL-85
CALL "HTML_BASE" USING base,
address of cbBase,
gwContext,
address of appContext,
address of err,
ptxs.
Parameters
base
Pointer to the character buffer to receive the generated
<BASE> element string. On return, base contains a
null-terminated string that is suitable for use by C
library routines.
cbBase
Integer (comp-6) that contains the maximum size of
the buffer pointed to by base. On return, cbBase
contains the actual size of the generated <BASE>
element. COBOL-85 programs will use cbBase when
processing the resulting base buffer.
gwContext
Pointer to a character buffer to receive the
appContext converted to a hexadecimal string. The
buffer must be eight bytes in length.
appContext
Integer (comp-6) that contains the application-defined
value to be included in the new <BASE> element. It is
an input parameter that can be uniquely defined
through HTTP_GETCONTEXT routine. The value of
appContext becomes the third field of the sessionidentifier portion of the base URL.
47 A2 39UT Rev02
8-13
err
Integer (comp-6) to receive a value that indicates
whether the call was successful. A value of zero
indicates a successful call. A negative value indicates
that an error occurred.
ptxs
Pointer to the TRANSACTION-STORAGE, the third
parameter of each TPR.
NOTES:
1.
HTML_BASE is used to generate an HTTP response message that sets a base
URL for future requests from the browser. In general, a TDS-Web
application will provide a logon transaction that uses this routine to
establish the base URL for each new connection to TDS. After the logon
transaction has established the base URL, all HTML pages generated by
the application can use relative URLs to submit transactions over the same
session connection.
2.
The generated base contains URL elements up to and including the session
identifier.
<BASE HREF="http://gateway:port/node-mbx/ 1234.5678.abcd/">
3.
Relative links that reside on a Web page that contains the <BASE> element
specify the next Transaction name and any optional information. For
example:
You are now logged on.
The <A HREF="nxtcmd/custinfo-htm">Customer Information
<A> form is now available.
When a user selects the Customer Information link in the above example,
the browser appends the relative-link information that is provided in the
<A> tag to the base URL to submit a request for the "nxtcmd" using the
full URL as follows:
http://gateway:port/node.mbx/1234.5678.abcd/nxtcmd/custinfo-htm
4.
Error conditions are indicated by placing a negative value in err:
ERR_HTML_BASE_SIZE
ERR_HTML_BASE_CTXFMT
ERR_HTTP_GETHDR_xxx
8-14
base too small to hold result
invalid context format in URL: The
HTTP request submitted by the browser
any errors returned by HTTP_GETHDR.
47 A2 39UT Rev02
C Example
TRANSACTION_STORAGE *ptxs;
char newbase[256];
int cbBase = sizeof(newbase);
char gwContext[8];
int appContext;
int err;
char buffer[1024];
int cbBuffer;
char level=’1’;
HTTP_GETCONTEXT(gwContext, &appContext) ;
HTML_BASE(newbase, &cbBase, gwContext, &appContext, &err, ptxs);
cbBuffer=sprintf(buffer,"HTTP/1.0 200 CONTEXT=%8.8s\r\n"
"Content-type: text/html\r\n"
"Pragma: no-cache\r\n"
"\r\n"
"<html><HEAD>\r\n"
"<TITLE>WEB7 Logon accepted<TITLE>\r\n"
"%s\r\n"
"</HEAD>\r\n"
"<BODY><H1>Logon Accepted</H1><HR>\r\n"
"You are now logged on. The "
"<A HREF=\"nxtcmd/custinfo-htm\">Customer Information</A>"
" form is now available."
"<BODY>\r\n"
"</html>\r\n"
,gwContext, newbase
);
HTTP_SEND(buffer, &cbBuffer, &level, ptxs);
COBOL-85 Example
data division.
77 gwContext
pointer.
77 gwContextd pic x(8).
77 appContext comp-6.
77 err
comp-6.
77 msgPtr
comp-6.
77 msgText
pic x(1024).
77 NL
pic x(2) value ""14,38"".
77 cbBase
comp-6.
77 level
pic x value "3".
77 ptxs
pointer.
77 base
pointer.
01 bases.
02 basedata pic x occurs 0 to 256 times depending on cbBase.
47 A2 39UT Rev02
8-15
procedure division using TDS-STORAGE, CONSTANT-STORAGE,
Set ptxs to address of TRANSACTION-STORAGE.
Set base to address of bases.
move 256 to cbBase.
move gwContext to address of gwContextd.
call "HTTP_GETCONTEXT" using gwContext
address of appContext ;
call "HTML_BASE" using base
address of cbBase,
gwContext,
address of appContext,
address of err,
ptxs.
move 1 to msgPtr.
string "HTTP/1.0 200 CONTEXT=" gwContextd NL
"Content-type: text/html" NL
"Pragma: no-cache" NL
NL
"<html><HEAD>"
"<TITLE>WEB7 Logon accepted</TITLE>" NL
bases
"</HEAD>" NL
"<BODY><H1>Logon Accepted</H1><HR>"
NL "You are now logged on. The "
"<A HREF=" "nxtcmd/custinfo-htm"">"
"Customer Information</A>" NL
" form is now available."
"</BODY>"
"</html>"
delimited size into msgText pointer msgPtr.
subtract 1 from msgPtr.
call "HTTP_SEND" using address of msgText,
address of msgPtr
address of level,
ptxs.
8-16
47 A2 39UT Rev02
8.6.2
HTTP_ABORT
Description
Called by ON_ABORT_TPR to send an HTTP message about abort and release the
TDS-Web resources used during the transaction.
Syntax in C
HTTP_ABORT(ptds, ptxs);
Syntax in COBOL-85
CALL "HTTP_ABORT" USING ptds, ptxs.
Parameters
ptds
Pointer to the TDS-STORAGE, the first parameter of
each TPR.
ptxs
NOTE:
Sends a HTTP message about the transaction abort TPRs and releases the
TDS-Web resources used during the transaction, and must be only called in
ON_ABORT_TPR, as it is done in the delivered ABTWEB7 TPR.
C Example
TDS_STORAGE *ptds;
HTTP_ABORT(ptds, ptxs);
COBOL-85 Example
data division.
77 ptds
pointer.
77 ptxs
pointer.
Set ptds to address of TDS-STORAGE.
CALL "HTTP_ABORT" USING ptds, ptxs.
47 A2 39UT Rev02
8-17
8.6.3
HTTP_COPY_MESSAGE
Description
Returns a pointer to the input message buffer and the number of bytes received.
Syntax in C
HTTP_COPY_MESSAGE(&buffer_ptr, &cbBuffer, ptxs);
Syntax in COBOL-85
CALL "HTTP_COPY_MESSAGE" USING address of buffer-ptr,
address of cbBuffer,
ptxs.
Parameters
buffer_ptr
Received pointer to a string buffer. The actual buffer
is allocated by the TDS-Web runtime
HTTP_RECEIVE routine.
C programmers must pass the address of a character
pointer. COBOL programmers must pass a POINTER
data type.
cbBuffer
Integer (comp-6) to receive the size of the input
message.
ptxs
NOTE:
When a TPR is invoked by a terminal instead of a browser, no HTTP protocol
information is provided, and the TPR is responsible for all parsing of the input
message. The TPR can call the HTTP_COPY_MESSAGE routine to obtain a
pointer to the input message buffer. Using the pointer to the message buffer, the
TPR can then parse the input message.
This pointer can only be used in the calling TPR.
8-18
47 A2 39UT Rev02
C Example
char *buffer_ptr;
int
cbBuffer;
HTTP_COPY_MESSAGE(&buffer_ptr, &cbBuffer, ptxs);
/* parse the input message pointed to by *buffer_ptr */
COBOL-85 Example
data division.
working-storage section.
77 buffer-ptr pointer.
77 cbBuffer
comp-6.
77 ptxs
pointer.
linkage section.
01 buffer.
02 buffer-data pic x occurs 1 to 32000
depending on cbBuffer.
call "HTTP_COPY_MESSAGE" using address of buffer-ptr,
ptxs.
set address of buffer to buffer-ptr.
* parse the input message using linkage section buffer variable.
47 A2 39UT Rev02
8-19
8.6.4
HTTP_DATE
Description
Generates an HTTP "Date" header in the following form:
Date: Wed, 09 Aug 1998 07:49:32 GMT
Syntax in C
HTTP_DATE(buffer, &cbBuffer);
Syntax in COBOL-85
CALL "HTTP_DATE" USING buffer,
address of cbBuffer.
Parameters
Pointer to a character buffer to receive the generated
HTTP Date header. The buffer is allocated by the
calling program and the size of the buffer is specified
by the cbBuffer parameter.
buffer
Tip: A 48-byte buffer is large enough to hold the result
of Date, Expires, and Last-Modified headers.
cbBuffer
Integer (comp-6) that specifies the maximum size of
buffer. On return, cbBuffer specifies the actual
size of the generated HTTP Date header. cbBuffer is
set to zero if the size specified is not sufficient to hold
the generated Date header.
NOTES:
8-20
1.
HTTP_DATE modifies the cbBuffer parameter. As a result, the
programmer must initialize cbBuffer before every call.
2.
Using a Date header is optional. Refer to the HTTP specifications for
additional details. Using a Date header allows the application to specify
cache-management information to proxy servers and Web browsers.
47 A2 39UT Rev02
C Example
char buffer[48];
int cbBuffer;
cbBuffer = sizeof(buffer);
HTTP_DATE(buffer, &cbBuffer)
COBOL-85 Example
data division.
77 bufferd
pic x(48).
77 cbBuffer comp-6.
77 buffer
pointer.
77 ptxs
pointer.
Set buffer to address of bufferd.
move length of bufferd to cbBuffer.
call "HTTP_DATE" using buffer, address of cbBuffer.
47 A2 39UT Rev02
8-21
8.6.5
HTTP_EXIT
Description
Called by TPR to abandon the current transaction.
Syntax in C
HTTP_EXIT();
Syntax in COBOL-85
CALL "HTTP_EXIT".
Parameters
None.
NOTES:
1.
Normally the application program terminates by exiting from TPR.
However, if a subroutine that has been invoked by TPR wishes to abandon
processing, the subroutine can invoke HTTP_EXIT that aborts the TPR.
2.
The calling subroutine should have sent an HTTP response prior to calling
HTTP_EXIT, because no further processing is possible after this call.
However, the ON_ABORT_TPR is invoked, that sends an " abort " HTTP
response, if not yet done.
C Example
HTTP_EXIT();
COBOL-85 Example
procedure division.
call "HTTP_EXIT".
8-22
47 A2 39UT Rev02
8.6.6
HTTP_EXPIRES
Description
Generates an HTTP "Expires" header in the following form:
Expires: Wed, 09 Aug 1998 07:49:32 GMT
Syntax in C
HTTP_EXPIRES(buffer, &cbBuffer, &expDelta);
Syntax in COBOL-85
CALL "HTTP_EXPIRES" USING buffer,
address of expDelta.
Parameters
buffer
Pointer to a character buffer to receive the generated
HTTP Expires header. The calling program allocates
the buffer and the size of the buffer is specified by the
cbBuffer parameter.
Tip: A 48-byte buffer is large enough to hold the result
of Date, Expires, and Last-Modified headers.
cbBuffer
size of the generated HTTP Expires header.
cbBuffer is set to zero if the size specified is not
sufficient to hold the generated Expires header.
expDelta
Integer (comp-6) that specifies the delta from the
current time to be used to generate the expiration time.
The value is specified as the number of seconds from
the current time, and can be either a positive or a
negative value. A positive value specifies an
expiration time in the future. A negative value
specifies an expiration time in the past.
47 A2 39UT Rev02
8-23
NOTES:
1.
HTTP_EXPIRES modifies the cbBuffer parameter. As a result, the
2.
Using an Expires header is optional. Refer to the HTTP specification for
additional details. Using an Expires header allows the application to
specify cache-management information to proxy servers and Web
browsers.
C Example
char buffer[48];
int cbBuffer;
int expDelta;
expDelta = 24*3600; /* expires 24 hours from now */
HTTP_EXPIRES(buffer, &cbBuffer, &expDelta)
COBOL-85 Example
data division.
77 bufferd
pic x(48).
77 buffer
pointer.
77 cbBuffer comp-6.
77 expDelta comp-6.
77 ptxs
pointer.
move length of buffer to cbBuffer.
compute expDelta = 24 * 3600.
call "HTTP_EXPIRES" using buffer,
address of cbBuffer.
address of expDelta.
8-24
47 A2 39UT Rev02
8.6.7
HTTP_FREEWEB7
Description
Called by DISCNT and LOGOUT TPRs to release the TDS-Web resources used
during a TDS-Web connection.
Syntax in C
HTTP_FREEWEB7(ptds, ptxs);
Syntax in COBOL-85
CALL "HTTP_FREEWEB7" USING ptds, ptxs.
Parameters
ptds
each TPR.
ptxs
NOTE:
Releases the TDS-Web resources used during a TDS-Web connection, and must
be only called in DISCNT and LOGOUT TPRs, as it is done in the delivered
EXITWEB7 TPR.
C Example
TDS_STORAGE *ptds;
HTTP_FREEWEB7(ptds, ptxs);
COBOL-85 Example
data division.
77 ptds
pointer.
77 ptxs
pointer.
CALL "HTTP_FREEWEB7" USING ptds, ptxs.
47 A2 39UT Rev02
8-25
8.6.8
HTTP_GETCONTEXT
Description
Returns the application context set as unique by TDS-Web. This context is
returned under an eight-character field (not a string) and its corresponding
hexadecimal value.
Syntax in C
HTTP_GETCONTEXT (context, &appContext);
Syntax in COBOL-85
CALL "HTTP_GETCONTEXT" USING context,
address of appContext.
Parameters
context
Pointer to a character buffer to receive the
appContext converted to a hexadecimal string. The
buffer must be eight bytes in length. This is not a
character string (it does not end with a zero).
appContext
Integer (comp-6) that receives the application-defined
value to be included in the new <BASE> element. The
value of appContext becomes the third field of the
session-identifier portion of the base URL.
NOTE:
HTTP_CONTEXT is used to fill the <BASE...> element and the CONTEXT
element in HTTP response message.
C Example
char
int
int
int
int
char
newbase[256];
cbBase = sizeof(newbase);
gwContext[8];
appContext = 1;
err;
buffer [1024];
HTTP_GETCONTEXT (gwContext, &appContext);
sprintf(buffer,"HTTP/1.0 200 CONTEXT=%8.8s\r\n", gwContext);
8-26
47 A2 39UT Rev02
COBOL-85 Example
data division.
77 context
pointer.
77 gwContext
pic x(8).
77 appContext comp-6 value 1.
77 msgPtr
comp-6.
77 msgText
pic x(1024).
77 level
pic x value "1".
77 ptxs
pointer.
Set context to address of gwContext.
CALL "HTTP_GETCONTEXT" USING context,
address of appContext.
Move 1 to msgPtr.
string "HTTP/1.0 200 CONTEXT=" gwContext NL"
delimited size into msgText pointer msgPtr.
subtract 1 from msgPtr.
47 A2 39UT Rev02
8-27
8.6.9
HTTP_GETENV
Description
Returns the value of the requested environment-header variable.
Syntax in C
HTTP_GETENV(name, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETENV" USING name,
buffer,
address of err
ptxs.
Parameters
name
Pointer to a character string that contains the name of
the desired environment variable. The string must
contain an equal sign "=" to avoid ambiguous results,
and must contain an end-of-string null byte.
For example, to request the value of the "CONTEXT"
environment variable:
C language: "CONTEXT="
COBOL-85: "CONTEXT="1""
8-28
buffer
Pointer to a character buffer to receive the value of the
requested environment variable. The calling program
allocates the buffer and the size of the buffer is
specified by the cbBuffer parameter.
cbBuffer
size of the returned environment-variable value.
cbBuffer is not set if an error occurs.
err
47 A2 39UT Rev02
ptxs
NOTES:
1.
HTTP_GETENV modifies the cbBuffer parameter. As a result, the
2.
ERR_HTTP_GETENV_NOTFOUND Environment variable not found
ERR_HTTP_GETENV_DELIM
Requested name does not contain "="
ERR_HTTP_GETENV_SIZE
Buffer too small to hold result
3.
Refer to Figure 8-1 for a schema of the TDS-Web input format, including
the environment headers.
C Example
char buffer[256];
int cbBuffer;
int err;
HTTP_GETENV("CONTEXT=", buffer, &cbBuffer, &err, ptxs);
if (!err)
{
/* environment variable found */
}
else
{
/* process error conditions */
}
47 A2 39UT Rev02
8-29
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48) value "CONTEXT="1"".
77 cbBuffer
comp-6.
77 buffer
pointer.
01 bufferd.
02 bytes pic x occurs 0 to 256 times depending on cbBuffer.
77 err
comp-6.
77 ptxs
pointer.
Set name to address of named.
move 256 to cbBuffer.
call "HTTP_GETENV" using name,
buffer,
address of err
ptxs.
if not err then
*
environment variable found
else
*
process error conditions
end if
8-30
47 A2 39UT Rev02
8.6.10
HTTP_GETENV_FIRST
Description
Returns the name and value of the first environment-header variable of the input
message.
Syntax in C
HTTP_GETENV_FIRST(name, &cbName, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETENV_FIRST" USING name,
address of cbName,
buffer,
address of err,
ptxs.
Parameters
name
Pointer to a character buffer to receive the name of the
returned environment variable. The returned name
does not include the equal sign "=".
cbName
name. On return cbName specifies the actual size of
the returned name. cbName is not set if an error
occurs.
buffer
requested environment variable.
cbBuffer
size of the returned value. cbBuffer is not set if an
error occurs.
err
47 A2 39UT Rev02
8-31
ptxs
NOTES:
1.
HTTP_GETENV_FIRST modifies the cbName and cbBuffer parameters. As
a result, the programmer must initialize both parameters before every call.
2.
3.
ERR_HTTP_GETENV_NOTFOUND environment variable not found.
This error occurs when the message
does not contain environment headers.
name or buffer too small to hold the
result.
C Example
char name[48];
char buffer[256];
int cbName, cbBuffer, err;
cbName
= sizeof(name);
HTTP_GETENV_FIRST(name, &cbName, buffer, &cbBuffer, &err, ptxs);
if (!err)
{
}
else
{
}
8-32
47 A2 39UT Rev02
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48).
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbName
comp-6.
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
move length of named to cbName.
move " " to bufferd.
CALL "HTTP_GETENV_FIRST" USING name,
address of cbName,
buffer,
address of err,
ptxs.
if not err then
*
else
*
end if
47 A2 39UT Rev02
8-33
8.6.11
HTTP_GETENV_NEXT
Description
Returns the value of the "next" environment-header variable of the input message.
The meaning of "next" depends on which HTTP call was executed prior to the
HTTP_GETENV_NEXT call.
Syntax in C
HTTP_GETENV_NEXT(name, &cbName, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETENV_NEXT" USING name,
address of cbName,
buffer,
address of err,
ptxs.
Parameters
name
returned environment variable. The returned name
cbName
name. On return, cbName specifies the actual size of
occurs.
8-34
buffer
requested environment variable.
cbBuffer
error occurs.
err
Integer (comp-6) to receive a value that indicates if
the call was successful. A value of zero indicates a
successful call. A negative value indicates that an error
occurred.
47 A2 39UT Rev02
ptxs
NOTES:
1.
HTTP_GETENV_NEXT modifies the cbName and cbBuffer parameters.
As a result, the programmer must initialize both parameters before every
call.
47 A2 39UT Rev02
2.
A program can iterate through the entire list of environment variables by
making a call to HTTP_GETENV_FIRST followed by repeated calls to
HTTP_GETENV_NEXT.
3.
A program can iterate though a list of specific environment variables by
making a call to HTTP_GETENV followed by repeated calls to
HTTP_GETENV_NEXT. In this mode, each call to HTTP_GETENV_NEXT
returns the next environment variable that matches the name specified in
the initial call to HTTP_GETENV.
4.
ERR_HTTP_GETENV_NOTFOUND
environment variable not found,
indicating that no additional variables
remain to be processed.
does not contain environment
headers.
name or buffer too small to hold
result.
ERR_HTTP_GETENV_NOKEY
search key not initialized; must call
HTTP_GETENV or
HTTP_GETENV_FIRST before
calling HTTP_GETENV_NEXT
5.
8-35
C Example
char buffer[48];
char value[256];
cbName
= sizeof(name);
HTTP_GETENV_NEXT(name, &cbName, buffer, &cbBuffer, &err, ptxs);
if (!err)
{
}
else
{
}
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48).
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbName
comp-6.
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
CALL "HTTP_GETENV_NEXT" USING name,
address of cbName,
buffer,
address of err,
ptxs.
if not err then
*
else
*
end if
8-36
47 A2 39UT Rev02
8.6.12
HTTP_GETHDR
Description
Returns the value of the HTTP request header specified in the call.
Syntax in C
HTTP_GETHDR(name, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETHDR" USING name,
buffer,
address of err,
ptxs.
Parameters
name
the desired HTTP header. The string must contain a
colon ":" to avoid ambiguous results, and must
contain an end-of-string null byte.
For example, to request the value of the "Accept"
HTTP header:
C language: "Accept:"
COBOL-85: "Accept:"1""
buffer
requested HTTP header.
cbBuffer
buffer. On return cbBuffer specifies the actual
size of the returned HTTP header string. cbBuffer is
not set if an error occurs.
err
ptxs
47 A2 39UT Rev02
8-37
NOTES:
1.
HTTP_GETHDR modifies the cbBuffer parameter. As a result, the
2.
ERR_HTTP_GETHDR_NOTFOUND
ERR_HTTP_GETHDR_DELIM
ERR_HTTP_GETHDR_SIZE
3.
Requested HTTP header not found
Requested name does not contain ":"
Buffer too small to hold result
the HTTP headers.
C Example
char buffer[256];
int cbBuffer;
int err;
HTTP_GETHDR("Accept:", buffer, &cbBuffer, &err, ptxs);
if (!err)
{
/* header variable found */
}
else
{
}
8-38
47 A2 39UT Rev02
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48) value "Accept:"1"".
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
CALL "HTTP_GETHDR" USING name,
buffer,
address of err,
ptxs.
if not err then
*
header variable found
else
*
end if
47 A2 39UT Rev02
8-39
8.6.13
HTTP_GETHDR_FIRST
Description
Returns the name and value of the first HTTP request header of the input message.
Syntax in C
HTTP_GETHDR_FIRST(name, &cbName, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETHDR_FIRST" USING name,
address of cbName,
buffer,
address of err,
ptxs.
Parameters
name
returned HTTP request header. The returned name
does not include the colon ":".
cbName
occurs.
8-40
buffer
HTTP request header.
cbBuffer
error occurs.
err
Integer (comp-6) to receive a value that indicates if the
call was successful. A value of zero indicates a
occurred.
ptxs
47 A2 39UT Rev02
NOTES:
1.
HTTP_GETHDR_FIRST modifies the cbName and cbBuffer parameters.
call.
2.
3.
requested HTTP header not found
result
the HTTP headers.
C Example
char name[48];
char buffer[256];
cbName = sizeof(name);
if (!err)
{
/* header variable found */
}
else
{
}
47 A2 39UT Rev02
8-41
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48).
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbName
comp-6.
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
move length of name to cbName.
CALL "HTTP_GETHDR_FIRST" USING name,
address of cbName,
buffer,
address of err,
ptxs.
if not err then
*
header variable found
else
*
end if
8-42
47 A2 39UT Rev02
8.6.14
HTTP_GETHDR_NEXT
Description
Returns the name and value of the "next" HTTP request header of the input
message. The meaning of "next" depends on which HTTP call was executed prior
to the HTTP_GETHDR_NEXT call.
Syntax in C
HTTP_GETHDR_NEXT(name, &cbName, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETHDR_NEXT" USING name,
address of cbName,
buffer,
address of err,
ptxs.
Parameters
name
returned HTTP request header. The returned name
does not include the colon ":".
cbName
occurs.
buffer
HTTP request header.
cbBuffer
error occurs.
err
occurred.
47 A2 39UT Rev02
8-43
ptxs
NOTES:
1.
HTTP_GETHDR_NEXT modifies the cbName and cbBuffer parameters.
call.
2.
A program can iterate through all HTTP request headers by making a call
to HTTP_GETHDR_FIRST, followed by repeated calls to
HTTP_GETHDR_NEXT.
3.
A program can iterate though a list of specific HTTP request headers by
making a call to HTTP_GETHDR, followed by repeated calls to
HTTP_GETHDR_NEXT. In this mode, each call to HTTP_GETHDR_NEXT
returns the next HTTP request header that matches the name specified in
the initial call to HTTP_GETHDR.
4.
ERR_HTTP_GETHDR_NOKEY
5.
8-44
requested HTTP request header
not found, indicating that no
additional headers remain to be
processed.
result.
search key not initialized; must
call HTTP_GETHDR or
HTTP_GETHDR_FIRST before
calling HTTP_GETHDR_NEXT.
the HTTP headers are indicated by placing a negative value in err:
47 A2 39UT Rev02
Examples
The following examples iterate through the entire list of HTTP request headers.
C Example
char name[48];
char buffer[256];
while (!err)
{
/* do something with the request header */
/* then retrieve the next header */
HTTP_GETHDR_NEXT(name, &cbName, buffer, &cbBuffer, &err, ptxs);
}
if (err != ERR_HTTP_GETHDR_NOTFOUND)
{
}
47 A2 39UT Rev02
8-45
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48).
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbName
comp-6.
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
call "HTTP_GETHDR_FIRST" using name,
address of cbName,
buffer,
address of err,
ptxs.
*
*
process all of the rest of the HTTP request headers
*
perform until err = 0.
CALL "HTTP_GETHDR_NEXT" USING name,
address of cbName,
buffer,
address of err,
ptxs.
end-perform.
*
8-46
if err then
handle error
end if
47 A2 39UT Rev02
8.6.15
HTTP_GETMETHOD
Description
Returns the HTTP request method; for example, "GET" or "POST".
Syntax in C
HTTP_GETMETHOD(method, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETMETHOD" USING method, ptxs.
Parameters
method
Pointer to a character buffer to receive the method
field of the HTTP request header. The buffer must be
eight bytes and will be returned with blank fill. The
method string contains only upper-case characters and
is not terminated by a null byte.
C programmers should use memcmp() to test the
method.
ptxs
NOTE:
TDS-Web programs should receive only "GET" and "POST" request methods.
When the user clicks on a link, the browser submits a "GET" request. When the
user clicks on a SUBMIT button in a form, the method is determined by the
ACTION attribute of the form. By convention, HTML forms use the "GET"
method to submit requests that do not perform database updates, and use the
"POST" method for requests that do update a database. Note, however, that this
is only a convention and the convention is not enforced by commercial Web
servers or by TDS-Web.
47 A2 39UT Rev02
8-47
C Example
char method[8];
HTTP_GETMETHOD(method, ptxs);
if (memcmp(method, "GET", 3) == 0)
{
/* processing for "GET" method */
}
else if (memcmp(method, "POST", 4) == 0)
{
/* processing for "POST" method */
}
else
{
/* processing for unrecognized methods */
}
COBOL-85 Example
data division.
77 method
pointer.
77 methodd
pic x(8).
77 ptxs
pointer.
Set method to address of methodd.
call "HTTP_GETMETHOD" using method, ptxs.
if methodd = "GET"
*
processing for "GET" method
else if methodd = "POST"
*
processing for "POST" method
else
*
end if
8-48
47 A2 39UT Rev02
8.6.16
HTTP_GETPATH
Description
Returns the extra-path information that follows the Transaction name command
field of the URL.
Syntax in C
HTTP_GETPATH(path, &cbPath, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETPATH" USING path, address of cbPath, ptxs.
Parameters
path
Pointer to a character buffer to receive the extra path
information. The buffer must be large enough to hold
the entire result.
cbPath
Integer (comp-6) to receive the size of path.
ptxs
47 A2 39UT Rev02
8-49
NOTES:
1.
The URL for a TDS-Web application includes several pieces of
information that are used by the TDS-Web gateway to route the message to
a specific connection to TDS. This information includes host node and
mailbox information, a session identifier, and a transaction name, as
illustrated in the following example:
http://gateway/node.mailbox/sessionid/tp7cmd
2.
A TDS-Web application can include additional information as part of the
URL, as illustrated in the following example:
http://gateway/node.mailbox/sessionid/tp7cmd/more/path.htm
The call to HTTP_GETPATH returns any additional path information. For
the example URL shown above, a call to HTTP_GETPATH returns the string
"/more/path.htm" and sets cbPath to "14".
3.
HTTP_GETPATH does not validate cbPath. The programmer must
therefore be sure to provide a buffer that is large enough to hold the
maximum path information that is specified in links on the Web pages.
The maximum does not exceed 256 characters.
C Example
char path[128];
int cbPath
HTTP_GETPATH(path, &cbPath, ptxs);
COBOL-85 Example
data division.
01 cbPath comp-6.
77 path
pointer.
01 pathd.
02 path-data pic x occurs 0 to 128 times
depending on cbPath.
77 ptxs
pointer.
Set path to address of pathd.
call "HTTP_GETPATH" using path, address of cbPath, ptxs.
8-50
47 A2 39UT Rev02
8.6.17
HTTP_GETVAR
Description
Returns the value of the requested HTML form variable.
Syntax in C
HTTP_GETVAR(name, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETVAR" USING name,
buffer,
address of err,
ptxs.
Parameters
name
the requested HTML form variable. The string must
contain an equal sign "=" to avoid ambiguous results,
and must contain an end-of-string null byte.
For example, to request the value for the "CITY" form
variable:
C language: "CITY="
COBOL-85: "CITY="1""
buffer
requested HTML form variable.
cbBuffer
size of the returned form-variable value. cbBuffer is
err
occurred.
ptxs
47 A2 39UT Rev02
8-51
NOTES:
1.
HTTP_GETVAR modifies the cbBuffer parameter. As a result, the
2.
ERR_HTTP_GETVAR_NOTFOUND requested HTML form variable not
found
ERR_HTTP_GETVAR_DELIM
requested name does not contain "="
ERR_HTTP_GETVAR_SIZE
buffer too small to hold result
3.
Refer to Table 8-1 for a schema of the TDS-Web input format, including
the form variables.
C Example
char buffer[256];
int cbBuffer;
int err;
HTTP_GETVAR("CITY=", buffer, &cbBuffer, &err, ptxs);
if (!err)
{
/* HTML form variable found */
}
else
{
}
8-52
47 A2 39UT Rev02
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48) value "CITY="1"".
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
call "HTTP_GETVAR" using name,
buffer,
address of err,
ptxs.
if not err then
*
HTML form variable found
else
*
end if
47 A2 39UT Rev02
8-53
8.6.18
HTTP_GETVAR_FIRST
Description
Returns the name and value of the first HTML form variable of the input message.
Syntax in C
HTTP_GETVAR_FIRST(name, &cbName, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETVAR_FIRST" USING name,
address of cbName,
buffer,
address of err,
ptxs.
Parameters
name
returned HTML form variable. The returned name
cbName
the returned HTML form-variable name. cbName is
8-54
buffer
cbBuffer
size of the returned HTML form-variable value.
err
ptxs
47 A2 39UT Rev02
NOTES:
1.
HTTP_GETVAR_FIRST modifies the cbName and cbBuffer parameters.
call.
2.
ERR_HTTP_GETVAR_NOTFOUND no form variables are present
name or buffer too small to hold result
3.
the form variables.
C Example
char name[48];
char buffer[256];
cbName
= sizeof(name);
if (!err)
{
/* HTML form variable found */
}
else
{
}
47 A2 39UT Rev02
8-55
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48).
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbName
comp-6.
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
CALL "HTTP_GETVAR_FIRST" USING name,
address of cbName,
buffer,
address of err,
ptxs.
if not err then
*
else
*
end if
8-56
47 A2 39UT Rev02
8.6.19
HTTP_GETVAR_NEXT
Description
Returns the name and value of the "next" HTML form variable of the input
message. The meaning of "next" depends on which HTTP call was executed prior
to the HTTP_GETVAR_NEXT call.
Syntax in C
HTTP_GETVAR_NEXT(name, &cbName, buffer, &cbBuffer, &err, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETVAR_NEXT" USING name,
address of cbName,
buffer,
address of err,
ptxs.
Parameters
name
cbName
returned HTML form variable. The returned name
the returned HTML form-variable name. cbName is
buffer
cbBuffer
size of the returned HTML form-variable value.
err
ptxs
47 A2 39UT Rev02
8-57
NOTES:
1.
HTTP_GETVAR_NEXT modifies the cbName and cbBuffer parameters.
call.
2.
A program can iterate through all HTML form variables by making a call
to HTTP_GETVAR_FIRST, followed by repeated calls to
HTTP_GETVAR_NEXT.
3.
A program can iterate though a list of specific HTML form variables by
making a call to HTTP_GETVAR followed by repeated calls to
HTTP_GETVAR_NEXT. In this mode, each call to HTTP_GETVAR_NEXT
returns the next HTML form variable that matches the name specified in
the initial call to HTTP_GETVAR.
4.
ERR_HTTP_GETVAR_NOTFOUND HTML form variable not found,
indicating that no additional form
variables remain to be processed.
result
ERR_HTTP_GETVAR_NOKEY
search key not initialized; must call
HTTP_GETVAR or
HTTP_GETVAR_FIRST before calling
HTTP_GETVAR_NEXT
5.
8-58
the form variables.
47 A2 39UT Rev02
C Example
char name[48];
char buffer[256];
cbName
= sizeof(name);
while (!err)
{
/* do something with the request variable*/
/* then retrieve the next variable */
cbName
= sizeof(name);
HTTP_GETVAR_NEXT(name, &cbName, buffer, &cbBuffer, &err, ptxs);
}
if (err != ERR_HTTP_GETVAR_NOTFOUND)
{
}
47 A2 39UT Rev02
8-59
COBOL-85 Example
data division.
77 name
pointer.
77 named
pic x(48).
77 buffer
pointer.
77 bufferd
pic x(256).
77 cbName
comp-6.
77 cbBuffer comp-6.
77 err
comp-6.
77 ptxs
pointer.
call "HTTP_GETVAR_NEXT" using name,
address of cbName,
buffer,
address of err,
ptxs.
if not err then
*
else
*
end if
8-60
47 A2 39UT Rev02
8.6.20
HTTP_GETVERSION
Description
Returns a string that indicates which version of HTTP is supported by the browser.
Syntax in C
HTTP_GETVERSION(version, ptxs);
Syntax in COBOL-85
CALL "HTTP_GETVERSION" USING version, ptxs.
Parameters
version
Pointer to a character buffer to receive the HTTP
version string as specified by the browser.
ptxs
NOTES:
1.
Each application program should call HTTP_GETVERSION to verify that
the browser can support features that are specific to a particular version of
HTTP. Refer to the HTTP specifications at the URL listed in World Wide
Web and HTML Documentation in the Preface for additional details.
2.
If the browser submits this request:
GET /node.mbx/0/logon HTTP/1.0
then, HTTP_GETVERSION returns the string "1.0".
C Example
char version[12];
HTTP_GETVERSION(version, ptxs);
if (!strcmp(version, "1.0"))
{
/* generate HTTP for version 1.0 browsers */
}
47 A2 39UT Rev02
8-61
COBOL-85 Example
data division.
77 version pointer.
77 versiond
pic x(12).
77 ptxs
pointer.
Set version to address of versiond.
call "HTTP_GETVERSION" using version, ptxs.
if versiond = "1.0" then
*
generate HTTP specific for version 1.0 browsers
end if.
8-62
47 A2 39UT Rev02
8.6.21
HTTP_JSQUOTE
Description
Encodes application data into a JavaScript quoted-string literal, and returns the
result to the calling program.
Syntax in C
HTTP_JSQUOTE(text, &cbText, quotedText, &cbQuotedText,&err);
Syntax in COBOL-85
CALL "HTTP_JSQUOTE" USING text,
address of cbText,
quotedText,
address of cbQuotedText,
address of err.
Parameters
text
Pointer to a character buffer that contains the
application text to be sent.
cbText
Integer (comp-6) that contains the size of the text
buffer.
quotedText
Pointer to a character buffer to receive the result of the
encoding.
cbQuotedText
Integer (comp-6) that contains the maximum size of
the quotedText buffer. On return, this variable
contains the actual size of the encoded string.
err
47 A2 39UT Rev02
8-63
NOTES
1.
HTTP_JSQUOTE converts application data into JavaScript quoted-string
literals, including performing the following encodings:
\
"
2.
becomes
becomes
\\
\"
ERR_HTTP_JSQUOTE_SIZE quotedText buffer too small to hold result
C Example
char
int
char
int
int
empdata[] = "John Doe";
cbEmpdata = strlen(empdata);
quoteddata[80];
cbQuoteddata = sizeof(quoteddata);
err;
HTTP_JSQUOTE(empdata, &cbEmpdata, quoteddata, &cbQuoteddata, &err);
if (err == ERR_HTTP_JSQUOTE_SIZE) {
/* application logic to handle the error */
}
COBOL-85 Example
data division.
77 empdata
77 empdatad
77 cbEmpdata
77 quoteddata
77 quoteddatad
77 cbQuoteddata
01 err
pointer.
pic x(8) value "John Doe".
comp-6.
pointer.
pic x(80).
comp-6.
comp-6.
Set empdata to address of empdatad.
Set quoteddata to address of quoteddatad.
move length of empdatad to cbEmpdata.
move length of quoteddatad to cbQuoteddata.
CALL "HTTP_JSQUOTE" USING empdata,
address of cbEmpdata, quoteddata,
address of cbQuoteddata,
address of err.
if err
*
application logic to handle the error
end if.
8-64
47 A2 39UT Rev02
8.6.22
HTTP_RECEIVE
Description
Initializes the TDS-Web environment for the TPR, Receives the message from the
browser, parses it into separate headers and records.
Syntax in C
HTTP_RECEIVE(ptds, ptxs);
Syntax in COBOL-85
CALL "HTTP_RECEIVE" USING ptds, ptxs.
Parameters
ptds
each TPR.
ptxs
NOTES:
1.
Before calling any other TDS-Web runtime routines, a call to
HTTP_RECEIVE is mandatory
2.
This routine moves the SYMBOLIC-QUEUE of the TDS-STORAGE into
the CD input.
C Example
TDS_STORAGE *ptds;
HTTP_RECEIVE(ptds, ptxs);
47 A2 39UT Rev02
8-65
COBOL-85 Example
data division.
77 ptds
pointer.
77 ptxs
pointer.
CALL "HTTP_RECEIVE" USING ptds, ptxs.
8-66
47 A2 39UT Rev02
8.6.23
HTTP_SEND
Description
Places an HTTP response and its HTML content in an output buffer to be sent to
the browser.
Syntax in C
Syntax in COBOL-85
CALL "HTTP_SEND" USING buffer,
ADDRESS OF cbBuffer,
ADDRESS OF level,
ptxs.
Parameters
buffer
Pointer to a character buffer that contains the message
content to be sent.
cbBuffer
Integer (comp-6) that specifies the number of bytes to
send.
level
Character that indicates the end-of-message indicator.
Valid values are as follows:
1: for ESI, end of segment indicator
2: for EMI, end of message indicator
3: for EGI, end of group indicator.
ptxs
NOTES
47 A2 39UT Rev02
1.
Refer to Section 8.5 Handling TDS-Web TPR Output for information about
how to use this and the other members of the HTTP_SEND family of APIs.
Be sure to review that information before calling any of the HTTP_SEND
routines.
2.
Use HTTP_SEND to output text that includes HTML control tags that are to
be interpreted by the browser.
3.
The last message of a TPR must be sent by HTTP_SEND level=3, in order
to release used ressources.
8-67
Examples
The following examples send data that contains HTML <I> tags to the browser,
causing the data to be displayed using an italic font.
C Example
char *buffer = "<I>Application data to be sent.</I>";
int
cbBuffer;
char
level=’1’;
cbBuffer = strlen(buffer);
COBOL-85 Example
data division.
77 buffer
01 bufferd
77 cbBuffer
77 level
77 ptxs
pointer.
pic x(256).
comp-6.
pic x value “1”.
pointer.
Set buffer to addres of bufferd.
move 1 to cbBuffer.
string "<I>Application data to be sent.</I>"
delimited size
into bufferd
pointer cbBuffer.
subtract 1 from cbBuffer.
CALL "HTTP_SEND" USING buffer,
ADDRESS OF cbBuffer,
ADDRESS OF level,
ptxs.
8-68
47 A2 39UT Rev02
8.6.24
HTTP_SENDJSQUOTE
Description
Encodes application data into a JavaScript quoted-string literal and places the result
in the output buffer to be sent to the browser.
Syntax in C
HTTP_SENDJSQUOTE(text, &cbText, ptxs);
Syntax in COBOL-85
CALL "HTTP_SENDJSQUOTE" USING text, ADDRESS OF cbText, ptxs.
Parameters
text
cbText
buffer.
ptxs
NOTES
1.
Refer to Section 8.5 Handling TDS-Web TPR Output, for information
about how to use this and the other members of the HTTP_SEND family of
APIs. Be sure to review that information before calling any of the
HTTP_SEND routines.
2.
Use HTTP_SENDJSQUOTE to output JavaScript variable declarations that
can be referenced throughout the HTML document.
3.
The following encodings are performed:
\
"
becomes
\\
becomes
\"
Do not use HTTP_SENDJSQUOTE to output text that contains HTML
escape codes; instead, use HTTP_SENDJSTEXT.
This function performs a SEND ESI (level=’1’). A call to HTTP_SEND,
before completing the TPR is mandatory to generate a SEND EGI
(level=‘3’).
47 A2 39UT Rev02
8-69
Examples
The programming examples that follow illustrate how to generate this output:
<script language=JavaScript>
var emp_name="John Doe"
</script>
C Example
char empvar[] = "var emp_name=";
int cbEmpvar = strlen(empvar);
char empdata[] = "John Doe";
int cbEmpdata = strlen(empdata);
char NL[]
= "\r\n";
int cbNL
= strlen(NL);
char
level=’1’;
HTTP_SEND(empvar, &cbEmpvar, &level, ptxs);
HTTP_SENDJSQUOTE(empdata, &cbEmpdata, ptxs);
HTTP_SEND(NL, &cbNL, &level, ptxs);
COBOL-85 Example
data division.
77 empvar
pointer.
77 empdata
pointer.
77 empvard
pic x(13) value "var emp_name=".
77 cbEmpvar comp-6.
77 empdatad pic x(8) value "John Doe".
77 cbEmpdata comp-6.
77 NL
pointer.
77 NLd
pic x(2) value ""14,38"".
77 cbNL
comp-6 value 2.
77 ptxs
pointer.
77 level
pic x value "1".
Set empvar to address of empvard.
Set NL to address of NLd.
move length of empvard to cbEmpvar.
call "HTTP_SEND" using empvar,
address of cbEmpvar,
address of level,
ptxs.
call "HTTP_SENDJSQUOTE" using empdata,
address of cbEmpdata,
ptxs.
call "HTTP_SEND" using NL,
address of cbNL,
address of level,
ptxs.
8-70
47 A2 39UT Rev02
8.6.25
HTTP_SENDJSTEXT
Description
Encodes application data into a JavaScript quoted-string literal, converts HTML
control characters '<>"&' to appropriate escape sequences, and places the result in
the output buffer to be sent to the browser, as text.
Syntax in C
HTTP_SENDJSTEXT(text, &cbText, ptxs);
Syntax in COBOL-85
CALL "HTTP_SENDJSTEXT" USING text, ADDRESS OF cbText, ptxs.
Parameters
text
cbText
buffer.
ptxs
NOTES
1.
HTTP_SEND routines.
2.
Use HTTP_SENDJSTEXT to output JavaScript variable declarations that
can be referenced throughout the HTML document.
3.
HTML control codes "<", ">", and "&" are converted to HTML escape
codes, as follows:
‘\’
‘<’
‘>’
‘"’
‘&’
47 A2 39UT Rev02
becomes
becomes
becomes
becomes
becomes
"\\"
"<"
">"
"""
"&"
8-71
4.
Do not use HTTP_SENDJSTEXT in situations where the text contains
HTML codes that should be processed by the browser; for example, when
the data contains HTML commands. In these situations, use
HTTP_SENDJSQUOTE instead.
5.
(level=‘3’).
Examples
The programming examples that follow illustrate how to generate this output:
<script language=JavaScript>
var emp_name="<*>Employee ID data<*>\"
</script>
C Example
char empvar[] = "var emp_name=";
int cbEmpvar = strlen(empvar);
char empdata[] = "<*>Employee ID data<*>";
int cbEmpdata = strlen(empdata);
char NL[]
= "\r\n";
char cbNL
= strlen(NL);
char level=’1’ ;
HTTP_SEND(empvar, &cbEmpvar, &level, ptxs);
HTTP_SENDJSTEXT(empdata, &cbEmpdata, ptxs);
HTTP_SEND(NL, &cbNL, &level, ptxs);
8-72
47 A2 39UT Rev02
COBOL-85 Example
data division.
77 empvar
pointer.
77 empdata
pointer.
77 empvard
pic x(13) value "var emp_name=".
77 cbEmpvar comp-6.
77 empdatad pic x(22) value "<*>Employee ID data<*>".
77 cbEmpdata comp-6.
77 NL
pointer.
77 NLd
pic x(2) value ""14,38"".
77 cbNL
comp-6 value 2.
77 ptxs
pointer.
77 level
pic x value ‘1’.
Set empvar to address of empvard.
Set NL to address of NLd.
move length of empvard to cbEmpvar.
call "HTTP_SEND" using empvar,
address of cbEmpvar,
address of level,
ptxs.
call "HTTP_SENDJSTEXT" using empdata,
address of cbEmpdata,
ptxs.
call "HTTP_SEND" using NL,
address of cbNL,
address of level,
ptxs.
47 A2 39UT Rev02
8-73
8.6.26
HTTP_SENDTEXT
Description
Encodes HTML control characters in application text and places the result in the
output buffer to be sent to the browser as text.
Syntax in C
HTTP_SENDTEXT(buffer, &cbBuffer, ptxs);
Syntax in COBOL-85
CALL "HTTP_SENDTEXT" USING buffer, ADDRESS OF cbBuffer, ptxs.
Parameters
buffer
Pointer to a character buffer that contains the message
content to be sent.
cbBuffer
Integer (comp-6) that specifies the number of bytes to
be sent.
ptxs
NOTES
8-74
1.
HTTP_SEND routines.
2.
When sending HTML content to a Web browser, certain characters that
have special meaning must be encoded. For example, the browser treats
every "<" character as the beginning of an HTML tag, and attempts to
process the data within the tag. Any text between a beginning "<" and a
terminating ">" is treated as an HTML tag, and is not displayed. A tag that
is not recognized usually is ignored. However, the exact processing of
unrecognized tags is not specified by the HTML standard, and may vary in
different browsers.
These special characters might be embedded in data that is sent from an
application database. If these characters are to be displayed as text, each
special character must be converted to an encoded value as described in
the HTML specifications.
47 A2 39UT Rev02
To avoid possible display problems, use the HTTP_SENDTEXT routine
when sending any database values that might possibly contain any of the
special characters.
3.
Use HTTP_SENDTEXT in both COBOL-85 and C language to encode text
for display by a browser.
4.
The following encodings are performed :
< becomes "<"
> becomes "&gt
" becomes """
& becomes "&"
5.
(level=‘3’).
Examples
The following examples send data that contains HTML control codes to a browser.
The application wants the control codes to be displayed verbatim, without
interpretation by the browser.
C Example
char *buffer = "<I>Application data to be sent.</I>";
int
cbBuffer;
cbBuffer = strlen(buffer);
HTTP_SENDTEXT(buffer, &cbBuffer, ptxs);
COBOL-85 Example
data division.
77 buffer
pointer.
01 bufferd
pic x(256).
77 cbBuffer
comp-6.
77 ptxs
pointer.
move 1 to cbBuffer.
string "<I>Application data to be sent.</I>"
delimited size
into bufferd
pointer cbBuffer.
subtract 1 from cbBuffer.
call "HTTP_SENDTEXT" using buffer, address of cbBuffer, ptxs.
47 A2 39UT Rev02
8-75
❑
8-76
47 A2 39UT Rev02
9. HTML Template Database Access
Routines
This chapter describes the routines which can be called by CALL at user TPR
level, and which enable access to the records making up an HTML page in HTML
Template Database with no need for programming the IDS/II database accesses.
These routines are written in COBOL-85 and supplied as CUs in the SYS.HCULIB
library.
They are available in both IDS versions, IDS and Full, and can be accessed from
TPRs written in Cobol or in C language. The database schema is declared in these
access routines.
The following routines are provided:
H_WEB7_GET_HEADER(I) which can be used for retrieving the content of
an HTMLHEADER record,
H_WEB7_GET_RECORD(I) which can be used for retrieving the records
constituting an HTML page.
The letter I at the end of the procedure name stands for IDS. Otherwise the version
is Full IDS.
47 A2 39UT Rev02
9-1
9.1
H_WEB7_GET_HEADER(I)
This routine is used for retrieving features specific to an HTML page and contained
in the HTMLHEADER record.
After the name of the HTML page has been specified in WS-I-HNOMDOC, the
TPR returns the SOURCEURL, DATEMODIFIED, IMPORTDATE and
IMPORTTIME fields of the record if the search was successful, and a status code
in any case.
Syntax in C
H_WEB7_GET_HEADER(&ws_Struct_Header,&ws_Ret_Header,&Transaction_Storage)
or
H_WEB7_GET_HEADERI(&ws_Struct_Header,&ws_Ret_Header,&Transaction_Storage)
Syntax in COBOL-85
CALL"H_WEB7_GET_HEADER" USING
ADDRESS OF WS-STRUCT-HEADER
ADDRESS OF WS-RET-HEADER
or
CALL"H_WEB7_GET_HEADERI" USING
ADDRESS OF WS-STRUCT-HEADER
ADDRESS OF WS-RET-HEADER
Parameters
The parameters are provided in two forms:
• a COBOL description which can be called with COPY,
• a description in C language.
9-2
47 A2 39UT Rev02
WS-STRUCT-HEADER parameter
The COBOL structure is as follows:
01
WS-STRUCT-HEADER.
02 WS-I-HNOMDOC
02 WS-I-HNOMDOCSIZE
02 WS-O-SOURCEURL
02 WS-O-DATEMODIFIED
02 WS-O-IMPORTDATE
02 WS-O-IMPORTTIME
02 FILLER
PIC X(192).
COMP-2.
PIC X(192).
PIC X(48).
COMP-2.
COMP-2.
PIC X(200).
The C language structure is as follows:
530 typedef struct
540
{
550
char
ws_i_HNomDoc[192];
560
int
ws_i_HNomDocSize;
570
char
ws_o_SourceURL[192];
580
char
ws_o_DateModified[48];
590
int
ws_o_ImportDate;
600
int
ws_o_ImportTime;
610
char
ws_Filler[200];
620
} ws_Struct_Header;
630
With the following input :
= name of the HTML page
= number of characters in the name of the page
WS-I-HNOMDOC
WS-I-HNOMDOCSIZE
With the following output :
WS-O-SOURCEURL
WS-O-DATEMODIFIED
WS-O-IMPORTDATE
WS-O-IMPORTTIME
= SOURCEURL contained in the HTMLHEADER record
= DATEMODIFIED contained in the HTMLHEADER record
= IMPORTDATE contained in the HTMLHEADER record
= IMPORTTIME contained in the HTMLHEADER record
WS-RET-HEADER parameter, a code giving the result of the search
The Cobol structure is as follows:
01
WS-RET-HEADER
COMP-2.
int ws_Ret_header;
47 A2 39UT Rev02
9-3
The possible values for this code are:
0
100
1000
: OK
: page not found
: internal error
In case of internal error, a detailed message is displayed on the master console
and in the TDS JOR. This message will include the DB_STATUS returned by
IDS.
The parameters, WS-STRUCT-HEADER and WS-RET-HEADER, are declared in
the WEB7LIB-C85 member of the SYS.HSLLIB library for the Cobol description.
The C structure, ws_struct_header, is defined in the WEB7LIB_H include file.
9-4
47 A2 39UT Rev02
9.2
H_WEB7_GET_RECORD(I)
This routine can be used for accessing the various records making up the HTML
page in the HTMLSET set.
After the name of the page has been specified in WS-I-NOMDOC, the user TPR
must loop on the procedure call until the status code, WS-RET-ACCESS, is equal
to 1 (end of page), while performing the actions requested by the record type (WSO-REC-TYPE).
Syntax in COBOL-85
CALL"H_WEB7_GET_RECORD" USING
ADDRESS OF WS-STRUCT-ACCESS
or
CALL"H_WEB7_GET_RECORDI" USING
ADDRESS OF WS-STRUCT-ACCESS
Syntax in C
H_WEB7_GET_RECORD(&ws_Struct_Access,&ws_Ret_Access,&Transaction_Storage)
or
H_WEB7_GET_RECORDI(&ws_Struct_Access,&ws_Ret_Access,&Transaction_Storage)
Parameters
The parameters are provided in two forms:
• a Cobol description which can be called through COPY,
• a description in C language.
47 A2 39UT Rev02
9-5
WS-STRUCT-ACCESS parameter
01
WS-STRUCT-ACCESS.
02 WS-I-NOMDOC
02 WS-I-NOMDOCSIZE
02 WS-IO-NEXT
02 WS-IO-REC-KEY
02 WS-O-REC-TYPE
02 WS-O-REC-SIZE
02 WS-O-REC-DATA
02 FILLER
PIC X(192).
COMP-6.
PIC X.
COMP-2.
PIC X.
COMP-2.
PIC X(500).
PIC X(200).
640 typedef struct
650
{
660
char
ws_i_NomDoc[192];
670
int
ws_i_NomDocSize;
680
char
ws_io_Next;
690
char * ws_io_Rec_Key;
700
char
ws_o_Rec_Type;
710
int
ws_o_Rec_Size;
720
char
ws_o_Rec_Data[500];
730
char
ws_Filler[200];
740
} ws_Struct_Access;
750
With the following input :
= name of the HTML page
WS-I-NOMDOC
WS-I-NOMDOCSIZE = name length expressed in number of characters
With the following input-output :
WS-IO-NEXT
WS-IO-REC-KEY
= F for a first call
N for subsequent calls
= DB-KEY of the record just read and which must be
returned for accessing the following record
With the following output :
= type of record read
H for HTMLRECORD
A for ACTIONRECORD
B for BINARYRECORD
= size of record
WS-O-REC-SIZE
= data
WS-O-REC-DATA
WS-RET-ACCESS parameter, a code giving the result of the read action:
WS-O-REC-TYPE
9-6
47 A2 39UT Rev02
01
WS-RET-ACCESS
COMP-2.
int ws_Ret_Access;
The possible values for this code are:
0
1
100
110
1000
:
:
:
:
:
OK
end of page
page not found
page without record
internal error
In case of internal error, a detailed message is displayed on the master console
and in the TDS JOR. This message will include the DB_STATUS returned by
IDS.
The parameters, WS-STRUCT-ACCESS and WS-RET-ACCESS, are declared in
the WEB7LIB-C85 member of the SYS.HSLLIB library for the Cobol description.
The C structure, ws_struct_access, is defined in the WEB7LIB_H include file.
9.3
Consequences for the user
At TPR level :
The database schema does not need to be declared at TPR level, as it is defined in
the access routines.
At TPR compiling level:
The binary library containing the HTMLSCHEMA schema does not need to be
specified.
47 A2 39UT Rev02
9-7
❑
9-8
47 A2 39UT Rev02
10. What To Do in the Event of an Error
Here are several examples of errors that the end user and the programmer may
encounter:
10.1
Error Messages Displayed via HTML Pages
For “internal server errors”, xxxxx corresponds to the line in the TDS-Web helper
routine program where the error occurred.
500 Server Error
The server encountered an internal error or misconfiguration and was unable to
complete your request.
Please contact the server administrator, and inform him/her of the time the error
occurred, and anything you might have done that may have caused the error.
Error: Unable to open a new DSA session.
If this error occurs at a connection:
• Check that the network is running
• Check that the TDS is running.
• Check that you are not already connected (with the LSTC command).
47 A2 39UT Rev02
10-1
404 Not Found
The requested
URL /NODE.MBX/12345678.12345678.12345678/TRANSACTION/PAGE
was not found on this server.
• Check that you are connected to the TDS (with the LSTC command).
• Check that the URL is valid.
• Check that the name of the action or page is correct.
• Check that there is no parameter forgotten when calling a TDS-Web routine.
• Check that the TRANSACTION_STORAGE size is correct for all transactions.
400 Bad Request
Your client sent a query that this gateway could not understand.
Reason: Invalid URL
• Check that you are connected to the TDS (with the LSTC command).
• Check that the URL is valid (particularly the three contexts).
• Check that the name of the action or the page is correct.
Internal Server Error
The server has encountered an internal error at line xxxxx
HttpParseSection error
There is a CRLF missing in the HTTP request received by the TPR.
The server has encountered an internal error at line xxxxx.
HttpParseContent error
The TPR has not successfully understood the request. Check that the right protocol
is being used.
10-2
47 A2 39UT Rev02
What To Do in the Event of an Error
Unable to allocate message buffer
This is a problem with the number of TDS-Web connections to the TDS.
If the JPPC server is not used, the TDS has reached the maximum number of
TDS-Web connections. You then have to declare a JPPC server (see Section 3.3
Configuring TDS-Web Related GCOS7 Software).
If the JPPC server is used, check the total number of connections to the different
TDS and declare a JPPC server supporting a larger number of connections
(cf. Configuring TDS-Web related GCOS7 Software).
HttpReceiveMessage error
An error has occurred with request reception. It is possible that the helper
HTTP_RECEIVE has not been used correctly.
Error during TPR execution
An error has been detected during TPR execution. Check the TPR, specially the
calls to TDS-Web helper routines.
47 A2 39UT Rev02
10-3
Error Codes and Messages Returned by the HTTP-DSA GATEWAY.
400
Bad Request
Invalid or unsupported method
Not a GET or POST request
400
Bad Request
Invalid or unsupported protocol
Unrecognized HTTP version Currently 0.9 and 1.0
400
Bad Request
Invalid URL
Malformed URL
400
Bad Request
Invalid CGI parameters
Malformed CGI parameters
400
Bad Request
The gateway encountered an error
Your request is out of date processing the mainway identifier
404
Not Found
<url>
The requested page cannot be found (DSA session not found)
408
Request
A timeout has occurred
Timeout on DSA side Timeout on the other side of the gateway response
not received
500
Server Error
Unable to open a new DSA session
TP7 not launched or network unreachable
500
Server Error
Invalid response from the server
Response not in HTTP format
500
Server Error
Error during data transfer
Disconnect occurred.
10-4
47 A2 39UT Rev02
What To Do in the Event of an Error
500
Server Error
Unknown mailbox
MB (GWTP) unknown or no default mailbox.
500
Server Error
Connection closed by foreign Host
Network down or session abnormally closed.
500
Server Error
Another TCP connection exists
A request is sent this user from another browser to the same DSA session.
500
Server Error
The gateway has temporarily run out of resources for
your request. Please retry again at a later time.
Self-explanatory
503
Service
The gateway is currently unable to handle your request
due to a temporary overload.
Self-explanatory
47 A2 39UT Rev02
10-5
10.2
Netscape 3.0 Error Messages
This document does not contain any data.
The browser has not received a page. It may be that the TPR run has no pages to be
displayed.
A network error has occurred:xxxxxxxxxxxxxxxxx
Check that the IP address of the connection server is correct.
10.3
Errors Due to the Creation of Pages
If an ERROR in UFAS FILE, or ERRONEOUS PAGE type error appears while
loading the DATA BASE, it is possible that there is one or several spaces before
one of the following headers: ,
. Refer to Section 5.1.1 HTML Template Database.
10.4
Errors Due to Cache Management by the Browsers
In the case of a hypertext line such as <A NAME="#xxxx"> (link on a particular
area of the page), certain browsers will move around in the current page while
others will reload the page. In the second case, a TPR is run at GCOS level. If the
TPR run does not manage this call, it may be that the transaction no longer
functions correctly.
10-6
47 A2 39UT Rev02
A. IDS/II Status Keys
Extract of the IDS2 Status Keys
STATUS
CODE
02100
02300
02400
03100
X
X
03200
03300
X
X
X
04100
X
04300
05100
05200
07200
08100
08300
09100
09200
09300
73630
73640
73650
73660
80200
47 A2 39UT Rev02
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
15 STORE
CONDITION
13 READY
11 MODIFY
09 IF
08 GET
06 FINISH
05 FIND
04 ERASE
03 DISCONNECT
02 CONNECT
01 ACCEPT
INSTRUCTION CODE
End of a set or an area.
X No set satisfying the set selection criteria
No item satisfying the item selection expression.
The current item of the area, type of set or type of item
is null.
The current item of the activity is null.
The current item of the activity, area or type of set is not
the correct item type quoted.
X The value of the IDS key is incompatible with the name
of the area.
X The name of the area is invalid.
X Data features twice in the database.
X Data invalid (clause CHECK).
Deletion of a non-empty set,
The item is already linked to the set,
The item is not currently linked to the set
X Area or database is not at the READY state.
X The area is not in UPDATE mode.
The area is already in the READY state.
Null number in FIND identifier WITHIN set or area
Modification of the CALC key cannot be done without
migration.
The presence of members violates the AREA OF
OWNER clause.
Description of the item missing in WORKINGSTORAGE or LINKAGE SECTION.
X No area space left.
A-1
❑
A-2
47 A2 39UT Rev02
B. File Status Key
READ
WRITE
REWRITE
DELETE
START
OPEN
MEANING
CLOSE
Status Key
Extract of the COBOL File Status Keys for sequential files (1/2)
X
X
X
X
X
X
X
X
X
X
X
X
X
SUCCESS
00
00
00
04
05
07
Correct execution
File not open (2)
File already open (2)
Length inconsistent
File absent (1)
Non reel/unit file
X
X
X
X
X
X
X
X
AT END
10 End of file reached
10 Temporary end of file reached (3)
PERMANENT ERROR
30 No further information
34 Attempt to write beyond file limits
35 File not present
37 File does not support open mode
38 File closed with lock
39 Attributes conflict
LOGICAL ERROR
41 File already open
42 File not open
43 Last statement not successfull READ
44 Boundary violation
46 No valid next record
47 File not opened in input or I-O
48 File not opened in output, extend or I-O
49 File not opened in I-O
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
(1) OPTIONAL files OPENed in INPUT.
(2) EXTERNAL files, SYSIN files, SYSOUT files.
(3) EXTERNAL files.
47 A2 39UT Rev02
B-1
X
X
X
X
X
X
X
X
X
X
X
START
DELETE
X
WRITE
X
READ
CLOSE
DPS 7 SPECIFIC FILE STATUS KEYS
Block serial number error
Wrong block size
Wrong record size
X
File not open
X
File already open
X
Statement disallowed according to open mode
Inconsistency in file description
X
Form recovery
Function not available
X X
Ifn not assigned
X
External file name unknown
X
File organization unexpected
X
JOB card has been read
Incomplete record read at physical end paper tape
Block truncated
Record larger than specified record area
REWRITE
91
92*
95*
96*
97*
99*
9J*
9K
9L
9M
9N
9P
9R
9S
9T
9U
MEANING
OPEN
Status Key
Extract of the COBOL File Status Keys for sequential files (2/2)
X
X
X
X
X
X
* Values which may only appear if the clause COBOL 74 for files is used
B-2
47 A2 39UT Rev02
C. Error Codes
This Appendix contains a description of error codes available in C language and in
COBOL. In COBOL, the « _ » character is transformed into « - » character.
Table C-1.
C and COBOL Error Codes (1/2)
Name
Value Meaning
ERR_HTTP_GETENV_NOTFOUND -201
Environment variable not found.
does not contain environment
headers.
47 A2 39UT Rev02
ERR_HTTP_GETENV_DELIM
-202
Requested name does not contain
"=".
-204
Buffer too small to hold result.
ERR_HTTP_GETENV_NOKEY
-203
The search key is not initialized; you
must call HTTP_GETENV or
HTTP_GETENV_FIRST before
calling HTTP_GETENV_NEXT.
ERR_HTTP_GETHDR_NOTFOUND -301
The requested HTTP request header
was not found, indicating that no
additional headers remain to be
processed.
ERR_HTTP_GETHDR_DELIM
-302
The requested name does not
contain ":".
-304
Buffer too small to hold result.
ERR_HTTP_GETHDR_NOKEY
-303
The search key not initialized; you
must call HTTP_GETHDR or
HTTP_GETHDR_FIRST before
calling HTTP_GETHDR_NEXT.
C-1
Table C-1.
C and COBOL Error Codes (2/2)
Name
C-2
Value Meaning
ERR_HTTP_GETVAR_NOTFOUND -401
HTML form variable not found,
indicating that no additional form
variables remain to be processed.
ERR_HTTP_GETVAR_DELIM
-402
The requested name does not
contain "=".
-404
The name or buffer is too small to
hold result.
ERR_HTTP_GETVAR_NOKEY
-403
The search key is not initialized; you
must call HTTP_GETVAR or
HTTP_GETVAR_FIRST before
calling HTTP_GETVAR_NEXT.
ERR_HTML_BASE_SIZE
-502
The base too small to hold the result.
ERR_HTML_BASE_CTXFMT
-503
Invalid context format in URL: The
HTTP request was submitted by the
browser.
ERR_HTTP_JSQUOTE_SIZE
-601
The QuotedText buffer is too small
to hold result.
47 A2 39UT Rev02
D. Constants
This Appendix contains a description of constants for browser device type and
maximum length definitions for HTTP protocol entities.
They are only available in the C Language.
Table D-1.
C Language Constants
Name
Value
Meaning
HTTP_WEB_BROWSER_DEVICE
0x20A0
Device type for HTTP-DSA Gateway
connections.
HTTP_MAX_METHOD
5
"GET" or "POST"
HTTP_MAX_URL
64
/node.mbx.lid/context/cmd
HTTP_MAX_PATH
256
extra path info following TP7 command
HTTP_MAX_VERSION
8
Ex. 0.9, 1.0, 1.1
HTTP_MAX_CONTEXT
34
room for two fields of 16 hex digits
HTTP_MAX_KEY
64
room for a very large keyword
47 A2 39UT Rev02
D-1
❑
D-2
47 A2 39UT Rev02
Glossary
B
BROWSER
Designates a Web navigation program
C
CGI
Common Gateway Interface
D
DSA
Distributed System Architecture
H
HTML
Hyper Text Markup Language
HTTP
Hyper Text Transport Protocol
J
Java Script
Field in an HTML document used by an application to insert variables.
47 A2 39UT Rev02
g-1
T
TCP/IP
Transmission Control Protocol/Internet Protocol: used between browsers and Mainway.
TDS
Transaction Driven System: transactional product of GCOS 7.
TPR
Transaction Processing Routine: application program of a TDS, generally limited by exchanges.
U
URL
Uniform Resource Locator : address of a resource anywhere in the web and composed of protocol
name, server address and Resource name.
V
VCAM
Virtual Communication Access Method in GCOS 7.
W
WEB
Also called World Wide Web or W3.
g-2
47 A2 39UT Rev02
Index
4
400 Bad Request
message 10-2
404 Not Found
message 10-2
5
500 Server Error
message 10-1
A
ABORT TPR 5-8
absolute URL 2-3
ABTWEB7
installation report 4-9
model 4-2
TPR 5-8
ACTIONRECORD record 6-11
adapting
existing TDS 5-6
add * command 6-16
add page_name command 6-16
ADMIN
error messages 6-29, 6-32
transaction 4-10, 6-21
administration
TDS 5-2
administrative utility
JCL to run 6-20
using 6-15
47 A2 39UT Rev02
ADMINWEB7
analyzing
HTTP requests 7-23
answers
installation 4-5
APIs
HTML_BASE 8-13
HTTP_ABORT 8-17
HTTP_COPY_MESSAGE 8-18
HTTP_DATE 8-20
HTTP_EXIT 8-22
HTTP_EXPIRES 8-23
HTTP_FREEWEB7 8-25
HTTP_GETCONTEXT 8-26
HTTP_GETENV 8-28
HTTP_GETENV_FIRST 8-31
HTTP_GETENV_NEXT 8-34
HTTP_GETHDR 8-37
HTTP_GETHDR_FIRST 8-40
HTTP_GETHDR_NEXT 8-43
HTTP_GETMETHOD 8-47
HTTP_GETPATH 8-49
HTTP_GETVAR 8-51
HTTP_GETVAR_FIRST 8-54
HTTP_GETVAR_NEXT 8-57
HTTP_GETVERSION 8-61
HTTP_JSQUOTE 8-63
HTTP_RECEIVE 8-65
HTTP_SEND 8-67
HTTP_SENDJSQUOTE 8-69
HTTP_SENDJSTEXT 8-71
HTTP_SENDTEXT 8-74
syntax definitions 8-12
application access
TDS-Web 4-16
i-1
B
BINARYRECORD record 6-12
browser
definition 1-2, g-1
requirements 3-2
versions for TDS-Web 3-2
buffers
TDS-Web TPR output 8-10
building
libraries 4-4
C
C
constants D-1
HTML_BASE example 8-15
HTML_BASE syntax 8-13
HTTP_ABORT example 8-17
HTTP_ABORT syntax 8-17
HTTP_COPY_MESSAGE example 8-19
HTTP_COPY_MESSAGE syntax 8-18
HTTP_DATE example 8-21
HTTP_DATE syntax 8-20
HTTP_EXIT example 8-22
HTTP_EXIT syntax 8-22
HTTP_EXPIRES example 8-24
HTTP_EXPIRES syntax 8-23
HTTP_FREEWEB7 example 8-25
HTTP_FREEWEB7 syntax 8-25
HTTP_GETCONTEXT example 8-26
HTTP_GETCONTEXT syntax 8-26
HTTP_GETENV example 8-29
HTTP_GETENV syntax 8-28
HTTP_GETENV_FIRST example 8-32
HTTP_GETENV_FIRST syntax 8-31
HTTP_GETENV_NEXT example 8-36
HTTP_GETENV_NEXT syntax 8-34
HTTP_GETHDR example 8-38
HTTP_GETHDR syntax 8-37
HTTP_GETHDR_FIRST example 8-41
HTTP_GETHDR_FIRST syntax 8-40
HTTP_GETHDR_NEXT example 8-45
HTTP_GETHDR_NEXT syntax 8-43
HTTP_GETMETHOD example 8-48
HTTP_GETMETHOD syntax 8-47
i-2
C (continued)
HTTP_GETPATH example 8-50
HTTP_GETPATH syntax 8-49
HTTP_GETVAR example 8-52
HTTP_GETVAR syntax 8-51
HTTP_GETVAR_FIRST example 8-55
HTTP_GETVAR_FIRST syntax 8-54
HTTP_GETVAR_NEXT example 8-59
HTTP_GETVAR_NEXT syntax 8-57
HTTP_GETVERSION example 8-61
HTTP_GETVERSION syntax 8-61
HTTP_JSQUOTE example 8-64
HTTP_JSQUOTE syntax 8-63
HTTP_RECEIVE example 8-65
HTTP_RECEIVE syntax 8-65
HTTP_SEND calls 8-11
HTTP_SEND example 8-68
HTTP_SEND syntax 8-67
HTTP_SENDJSQUOTE example 8-70
HTTP_SENDJSQUOTE syntax 8-69
HTTP_SENDJSTEXT example 8-72
HTTP_SENDJSTEXT syntax 8-71
HTTP_SENDTEXT example 8-75
HTTP_SENDTEXT syntax 8-74
cache management
error messages 10-6
calls
HTTP_SEND 8-11
CGI
definition 1-2, g-1
characteristics
TDS-Web runtime routines 8-2
clauses
JPPC 5-4
PRIVATE STORAGE 5-4, 5-9
COBOL-85
HTML_BASE example 8-15
HTML_BASE syntax 8-13
HTTP_ABORT example 8-17
HTTP_ABORT syntax 8-17
HTTP_COPY_MESSAGE example 8-19
HTTP_COPY_MESSAGE syntax 8-18
HTTP_DATE example 8-21
HTTP_DATE syntax 8-20
HTTP_EXIT example 8-22
HTTP_EXIT syntax 8-22
47 A2 39UT Rev02
Index
COBOL-85 (continued)
HTTP_EXPIRES example 8-24
HTTP_EXPIRES syntax 8-23
HTTP_FREEWEB7 example 8-25
HTTP_FREEWEB7 syntax 8-25
HTTP_GETCONTEXT example 8-27
HTTP_GETCONTEXT syntax 8-26
HTTP_GETENV example 8-30
HTTP_GETENV syntax 8-28
HTTP_GETENV_FIRST example 8-33
HTTP_GETENV_FIRST syntax 8-31
HTTP_GETENV_NEXT example 8-36
HTTP_GETENV_NEXT syntax 8-34
HTTP_GETHDR example 8-39
HTTP_GETHDR syntax 8-37
HTTP_GETHDR_FIRST example 8-42
HTTP_GETHDR_FIRST syntax 8-40
HTTP_GETHDR_NEXT example 8-46
HTTP_GETHDR_NEXT syntax 8-43
HTTP_GETMETHOD example 8-48
HTTP_GETMETHOD syntax 8-47
HTTP_GETPATH example 8-50
HTTP_GETPATH syntax 8-49
HTTP_GETVAR example 8-53
HTTP_GETVAR syntax 8-51
HTTP_GETVAR_FIRST example 8-56
HTTP_GETVAR_FIRST syntax 8-54
HTTP_GETVAR_NEXT example 8-60
HTTP_GETVAR_NEXT syntax 8-57
HTTP_GETVERSION example 8-62
HTTP_GETVERSION syntax 8-61
HTTP_JSQUOTE example 8-64
HTTP_JSQUOTE syntax 8-63
HTTP_RECEIVE example 8-66
HTTP_RECEIVE syntax 8-65
HTTP_SEND example 8-68
HTTP_SEND syntax 8-67
HTTP_SENDJSQUOTE example 8-70
HTTP_SENDJSQUOTE syntax 8-69
HTTP_SENDJSTEXT example 8-73
HTTP_SENDJSTEXT syntax 8-71
HTTP_SENDTEXT example 8-75
HTTP_SENDTEXT syntax 8-74
using TDS-Web runtime routines 8-3
47 A2 39UT Rev02
codes
error C-1
coding
TPRs for TDS-Web 7-12
commands
add * 6-16
add page_name 6-16
del * 6-16
del page_name 6-16
structure of command file 6-17
syntax 6-17
compiling
completion
components
TDS-Web 1-7
configuring
MainWay 3-3, 3-4
TDS-Web related software 3-8
connection
chain 1-5
constants
C language D-1
context
function 1-5
management 2-15
creating
error while creating pages 10-6
IDS/II database 4-6
TDS 4-4, 4-8
Web pages for TDS-Web output 7-5
CU library 4-2
D
database
description 6-10
enlarging 6-3
HTML template 6-1
HTML template 1-7
loading 4-2
DBREORG utility 6-3
DBUTILITY utility 6-2
DDL 6-12
del * command 6-16
i-3
del page_name command 6-16
delivery
contents 4-2
demonstration
TDS 4-10
description
database 6-10
designing
Web pages 7-3
developing
TPRs for TDS-Web 7-2, 7-3
DISCONNECT TPR 4-2, 5-5, 5-6, 5-8
DMCL 6-13
DNS-E release 3-3
DOC1 transaction 1-8, 4-10
DOCSTPR
TPR 4-2, 4-10
DOCSTPR1
TPR 4-2, 4-10, 7-26
DOCSTPR2
TPR 4-2, 4-10, 7-29
DOCSTPR3
TPR 4-2, 4-10, 7-36
DOCSTPR4
TPR 4-2, 4-10, 7-43
document
base 2-9
document-relative URL 2-7
DSA
definition g-1
dynamic HTML document 1-2
E
enlarging database 6-3
environment
format of headers 8-7
initializing TDS-Web TPR environment
8-5
environments
GCOS 7 3-7
i-4
ERR_HTTP_* error codes C-1
error
codes C-1
error messages
400 Bad Request 10-2
404 Not Found 10-2
500 Server Error 10-1
ADMIN 6-29, 6-32
cache management 10-6
creating pages 10-6
description 6-27
displayed via HTML pages 10-1
HTTP-DSA Gateway 10-4
HttpParseContent 10-2
HttpParseSection 10-2
HttpReceiveMessage 10-3
Internal Server Error 10-2
LOADHTM 6-27
Netscape Navigator 3.0 10-6
TDS-Web runtime routines 8-2
examples
HTML_BASE 8-15
HTTP_ABORT 8-17
HTTP_COPY_MESSAGE 8-19
HTTP_DATE 8-21
HTTP_EXIT 8-22
HTTP_EXPIRES 8-24
HTTP_FREEWEB7 8-25
HTTP_GETCONTEXT 8-26
HTTP_GETENV 8-29
HTTP_GETENV_FIRST 8-32
HTTP_GETENV_NEXT 8-36
HTTP_GETHDR 8-38
HTTP_GETHDR_FIRST 8-41
HTTP_GETHDR_NEXT 8-45
HTTP_GETMETHOD 8-48
HTTP_GETPATH 8-50
HTTP_GETVAR 8-52
HTTP_GETVAR_FIRST 8-55
HTTP_GETVAR_NEXT 8-59
HTTP_GETVERSION 8-61
HTTP_JSQUOTE 8-64
HTTP_RECEIVE 8-65
HTTP_SEND 8-68
HTTP_SENDJSQUOTE 8-70
HTTP_SENDJSTEXT 8-72
47 A2 39UT Rev02
Index
examples (continued)
HTTP_SENDTEXT 8-75
transactions 1-8
exchange protocol 1-6
EXITWEB7
model 4-2
TPR 5-5, 5-7, 5-8
F
files
LOCALHOST 6-18, 6-19
status keys B-1
structure of command file 6-17
form variables
format 8-8
format
environment headers 8-7
form variables 8-8
HTTP headers 8-7
TDS-Web TPR input 8-6
G
GCOS 7
system environment
generating
TDS 5-2
3-7
H
handling
HTML output 7-10
TDS-Web TPR input 8-6
headers
format of environment headers 8-7
format of HTTP headers 8-7
Helper routines
function 1-7
47 A2 39UT Rev02
HTML
Administrative Utility 1-7
definition g-1
dynamic 1-2
JCL to run administrative utility 6-20
loading template database 6-14
page 1-6, 5-9
pages 5-2, 5-3
static 1-2
template database 1-7, 4-15, 5-2, 6-1
using administrative utility 6-15
HTML pages
error messages 10-1
HTML_BASE
C example 8-15
C syntax 8-13
COBOL-85 example 8-15
COBOL-85 syntax 8-13
description 8-13
HTMLAREA
HTMLHEADER record 6-11
HTMLRECORD record 6-11
HTTP
analyzing requests 7-23
definition 1-3, g-1
format of headers 8-7
processing requests 7-23
HTTP_ABORT
C example 8-17
C syntax 8-17
description 8-17
HTTP_COPY_MESSAGE
C example 8-19
C syntax 8-18
description 8-18
HTTP_DATE
C example 8-21
C syntax 8-20
description 8-20
i-5
HTTP_EXIT
C example 8-22
C syntax 8-22
description 8-22
HTTP_EXPIRES
C example 8-24
C syntax 8-23
description 8-23
HTTP_FREEWEB7
C example 8-25
C syntax 8-25
description 8-25
HTTP_GETCONTEXT
C example 8-26
C syntax 8-26
description 8-26
HTTP_GETENV
C example 8-29
C syntax 8-28
description 8-28
HTTP_GETENV_FIRST
C example 8-32
C syntax 8-31
description 8-31
HTTP_GETENV_NEXT
C example 8-36
C syntax 8-34
description 8-34
i-6
HTTP_GETHDR
C example 8-38
C syntax 8-37
description 8-37
HTTP_GETHDR_FIRST
C example 8-41
C syntax 8-40
description 8-40
HTTP_GETHDR_NEXT
C example 8-45
C syntax 8-43
description 8-43
HTTP_GETMETHOD
C example 8-48
C syntax 8-47
description 8-47
HTTP_GETPATH
C example 8-50
C syntax 8-49
description 8-49
HTTP_GETVAR
C example 8-52
C syntax 8-51
description 8-51
HTTP_GETVAR_FIRST
C example 8-55
C syntax 8-54
description 8-54
47 A2 39UT Rev02
Index
HTTP_GETVAR_NEXT
C example 8-59
C syntax 8-57
description 8-57
HTTP_GETVERSION
C example 8-61
C syntax 8-61
description 8-61
HTTP_JSQUOTE
C example 8-64
C syntax 8-63
description 8-63
HTTP_MAX_* constants D-1
HTTP_RECEIVE
C example 8-65
C syntax 8-65
description 8-65
HTTP_SEND
C example 8-68
C syntax 8-67
description 8-67
HTTP_SENDJSQUOTE
C example 8-70
C syntax 8-69
description 8-69
HTTP_SENDJSTEXT
C example 8-72
C syntax 8-71
description 8-71
47 A2 39UT Rev02
HTTP_SENDTEXT
C example 8-75
C syntax 8-74
description 8-74
HTTP-DSA gateway
configuring MainWay 3-4
error messages 10-4
function 1-5
purpose 3-3
HttpParseContent
error message 10-2
HttpParseSection
error message 10-2
HttpReceivedMessage
error message 10-3
I
IDS/II 3-7
creating database 4-6
DBREORG 6-3
DBUTILITY 6-2
DDL 6-12
DMCL 6-13
HTML pages 5-2, 5-3
loading database 4-7
schemas 4-2
Status Keys A-1
initializing
TDS-Web TPR environment 8-5
input
format of TDS-Web TPR 8-6
handling TDS-Web TPR 8-6
other TDS-Web routines 8-8
receiving 7-10
TPR 7-15
installation
answers 4-5
modes 4-4
preparation 4-6
questions 4-5
starting 4-5
i-7
installation report
ABTWEB7 4-9
ADMINWEB7 4-9
DOCSTPR 4-9
end 4-9
EXITWEB7 4-9
HTMLAREA 4-6
LOADHTM 4-7
starting 4-6
STDS modification 4-8
TP7GEN 4-8
TP7PREP 4-8
TPR compilation 4-9
installing
TDS-Web 4-4
message 10-2
IPS file 3-4
M
J
JavaScript
definition g-1
JCL
loading database 4-2
TDS start-up 5-6
to run HTML administrative utility 6-20
JPPC
choosing 3-8
clause 5-4
purpose 3-8
using 3-9
L
libraries
building 4-4
CU 4-2
LM 4-2
loading 4-4
preparing 4-6
SL 4-2
linking
TPRs for TDS-Web
i-8
LM library 4-2
load modules
LOADHTM 4-7
LOADHTM
error messages 6-27
function 1-7
load module 4-7
using 6-15, 6-16
loading
database 4-2
HTML template database 6-14
IDS/II database 4-7
libraries 4-4
Web pages 6-14
LOCALHOST file 6-18, 6-19
LOGOUT TPR 4-2, 5-5, 5-6, 5-7
MainWay
configuration 3-3, 3-4
Welcome Page 4-16, 4-17
management
context 2-15
managing
messages
ADMIN 6-29, 6-32
error 6-27, 10-1
LOADHTM 6-27
Microsoft Internet Explorer 3.0
TDS-Web qualification 3-2
models
ABTWEB7 4-2
EXITWEB7 4-2
modes
installation 4-4
modifying
STDS 4-8
monitoring
7-25
47 A2 39UT Rev02
Index
N
Q
Netscape Navigator 3.0
error messages 10-6
TDS-Web qualification 3-2
NGL file 3-4
qualification
browser versions 3-2
questions
installation 4-5
O
R
ON_ABORT_TPR TPR 4-2, 5-6, 5-9
ONP 3-3
options
handling HTML output 7-10
output
additional TPR 7-18
Base TPR 7-21
building TDS-Web TPR 8-9
handling 7-10
handling TDS-Web TPR 8-10
minimum TPR 7-18
pages as TDS-Web output 7-5
sending 7-11
TDS-Web buffers 8-10
TPR 7-16
receiving input
using TDS-Web runtime routines 7-10
records
ACTIONRECORD 6-11
BINARYRECORD 6-12
HTMLHEADER 6-11
HTMLRECORD 6-11
requirements
browser 3-2
TDS-Web 3-7
running
HTML administrative utility 6-20
runtime routines
building TDS-Web TPR output 8-9
characteristics 8-2
checking for errors 8-2
format of form variables 8-8
format of TPR input 8-6
handling TDS-Web TPR output 8-10
other TDS-Web 8-8
TDS-Web buffers TPR output 8-10
using 8-2
using from COBOL-85 8-3
using to analyze HTTP requests 7-23
using to handle HTML output 7-10
using to receive input 7-10, 8-6
using to send output 7-11
P
pages
as TDS-Web output 7-5
loading in template database 6-14
post-installation
procedure 4-3
preparing
installation 4-6
PRIVATE STORAGE
clause 5-4, 5-9
procedures
post-installation 4-3
TDS-Web update 4-12
processing
HTTP requests 7-23
programming
TPRs 5-9
protocol
exchange 1-6
47 A2 39UT Rev02
i-9
S
SA7 5-10
SECUR’ACCESS7 5-10
sending
output 7-11
server-relative URL 2-5
sharing
SL library 4-2
SPAWNING
transactions 5-10
starting
installation 4-5
static HTML document 1-2
Status Keys
files B-1
IDS/II A-1
STDS
demonstration TDS 4-2
modifying 4-8
syntax
definitions for TDS-Web APIs 8-12
syntax of commands 6-17
SYS.HSLLIB
WEB7_DOCSTPR1 7-26
WEB7_DOCSTPR2 7-29
WEB7_DOCSTPR3 7-36, 7-43
T
TCP/IP
definition 1-3, g-2
TDS
adapting existing 5-6
administration 5-2
application access 4-16
creating 4-4, 4-8
definition g-2
demonstration 4-2, 4-10
generation 5-2
start-up JCL 5-6
i-10
TDS-Web
additional TPR output 7-18
Base TPR output 7-21
browser versions 3-2
building TDS-Web TPR output 8-9
characteristics of runtime routines 8-2
checking runtime routines 8-2
coding TPRs 7-12
compiling TPRs 7-25
components 1-7
creating Web pages 7-5
delivery contents 4-2
designing TPRs 7-10
designing Web pages 7-3
developing TPRs 7-2, 7-3
examples of TPRs 7-26
format of TDS-Web TPR input 8-6
handing TDS-Web TPR input 8-6
handling TDS-Web TPR output 8-10
initializing TPR environment 8-5
installation 4-4
linking TPRs 7-25
minimum TPR output 7-18
other TDS-Web routines 8-8
overview 1-4
requirements 3-7
syntax definitions for APIs 8-12
TDS application access 4-16
TDS-Web buffers TPR output 8-10
TPR 5-9
TPR input 7-15
TPR output 7-16
transactions 5-10
update procedure 4-12
URLs 2-12
using a Base TPR 7-11
using runtime routines 7-10, 7-11, 7-23,
8-2, 8-3
TDS-Web files
installing 4-6
47 A2 39UT Rev02
Index
template database
creating 5-2
loading 6-14
managing 6-1
sharing 4-15
template databaseIDS/II 1-7
TEST transaction 4-10
testing
installation 4-4
TP7GEN
TP7PREP
TPRs
ABORT 5-8
ABTWEB7 5-8
additional output 7-18
Base 7-11
Base TPR output 7-21
coding for TDS-Web 7-12
compilation report 4-9
compiling for TDS-Web 7-25
definition g-2
designing for TDS-Web 7-10
developing for TDS-Web 7-2, 7-3, 7-5
DISCONNECT 4-2, 5-5, 5-6, 5-8
DOCSTPR 4-2, 4-10
DOCSTPR1 4-2, 4-10, 7-26
DOCSTPR2 4-2, 4-10, 7-29
DOCSTPR3 4-2, 4-10, 7-36
DOCSTPR4 4-2, 4-10, 7-43
examples for TDS-Web 7-26
EXITWEB7 5-5, 5-7, 5-8
initializing environment 8-5
input 7-15
linking for TDS-Web 7-25
LOGOUT 4-2, 5-5, 5-6, 5-7
minimum output 7-18
ON_ABORT_TPR 4-2, 5-6, 5-9
other than TDS-Web 5-9
output 7-16
programming 5-9
TDS-Web 5-9
47 A2 39UT Rev02
transactions
ADMIN 4-10, 6-21
DOC1 1-8, 4-10
DOC2 1-8, 4-10
DOC3 1-8, 4-10
DOC4 1-8, 4-10
examples 1-8
SPAWNING 5-10
TDS-Web 5-10
TEST 4-10
U
UFAS
preparing files 4-6
Uniform Resource Locator See URL
update procedure 4-12
URL
absolute 2-3
definition 2-2, g-2
document-relative 2-7
example 1-2
server-relative 2-5
TDS-Web 2-12
using
a Base TPR 7-11
HTML administrative utility 6-15
LOADHTM 6-15, 6-16
TDS-Web runtime routines 8-2, 8-3
utilities
DBREORG 6-3
DBUTILITY 6-2
HTML administrative 6-15, 6-20
HTML Administrative Utility 1-7
V
variables
VCAM
definition g-2
i-11
W
Web
definition g-2
loading pages 6-14
Welcome Page
MainWay 4-16, 4-17
TDS-Web 5-10
World Wide Web
definition g-2
overview 1-2
WWW
definition g-2
overview 1-2
i-12
47 A2 39UT Rev02

47 A2 39UT REV02 - TDS-WEB User`s Guide

Transcription

Similar documents

Pimp my kite sheet

Document Images - Ford Explorer Клуб

Japanese topical patch formulations: What can we learn?

K150 PIC Programmer

Illinois State Police

Setup Guide

Top 10 architectural trends for new Malaysian properties in

Community - Sunday Observer

Automatically generating reading lists

It`s a long, long way to Tipperary