Transcript 2001 Fall UNITE AS4037

Using the WEBPCM
Paul Kimpel
Session AS4026
2002 UNITE Conference
Copyright © 2002, All Rights Reserved
Paradigm Corporation
Topics
 Background: Web Transactions
 Overview of the WEBPCM
 Configuring the WEBPCM
 Programming for the WEBPCM
 Resources
Paradigm
AS4026
2
Overview
 What are we trying to do?
 Connect web browsers directly to MCP apps
 Leverage existing applications, software, and skills
 What do you need to know?





Paradigm
Standard COMS programming techniques
A reasonable amount of HTML
A little about HTTP
Configuration of Web Transaction Server (Atlas)
Configuration of Custom Connect Facility (CCF)
AS4026
3
Other Ways to Web Enable MCP Apps
 MCP-based solutions






Web Enabler Java applet
Java applets and servlets with Atlas
Java Server Pages (JSP) with Atlas
Custom programs with CCF TCP/IP ports
Custom programs with direct TCP/IP ports
Third-party screen scrapers
 Using external web servers




Paradigm
Microsoft IIS/ASP/ADO with OLE DB or ODBC
Microsoft IS/ASP with COMTI or OPENTI
Apache with Screen Object Modeling Studio (SOMS)
Lots of others…
AS4026
4
Background:
Web Transactions
How Web Servers and Browsers Work
 The web uses a request/response
mechanism – HTML over HTTP
 Browsers send requests
 Servers send responses
 Hypertext Transport Protocol (HTTP)




Rules for the request/response interchange
Generally operates on top of TCP/IP
Consists of line-oriented ASCII text
Defines message headers and optional body
 Hypertext Markup Language (HTML)
 Defines the content and layout of web pages
 Typically used as the body of an HTTP response
Paradigm
AS4026
6
Sample HTTP Request From Browser
Request Line
URI abs_path
Protocol level
Method
Headers
Cr-Lf
GET /myvdir/hello.html HTTP/1.1¬‡
Connection: Keep-Alive¬‡
User-Agent: Mozilla/4.5 (Win98; I)¬‡
Host: www.corp.com¬‡
Accept: image/gif, image/x-bitmap,¬‡
image/jpeg, */*¬‡
¬‡
Empty line terminates header
Content (body) may follow
Paradigm
AS4026
7
Sample HTTP Response From Server
Response Status Code
Headers
Content
Paradigm
HTTP/1.1 200 OK¬‡
Date: Monday, 25-Feb-02 11:15:33 GMT¬‡
Server: OurHost/2¬‡
Connection: Keep-Alive¬‡
Content-Type: text/html¬‡
Cr-Lf
Content-Length: 128¬‡
¬‡
<html><head><title>Sample Page</title>
</head>
<body>
Empty line terminates header
Hello World!
</body>
</html>
AS4026
8
Static vs. Dynamic Content
 Static Content




Server's response is prepared in advance
Typically stored in a file
HTML text describes page layout to the browser
Other files may be referenced by HTML
– Other HTML pages
– Images
– Active objects (Java applets, etc.)
 Dynamic Content
 Server's response is custom built to the request
 Generated at run time and sent to browser
 Typically involves data base transactions
Paradigm
AS4026
9
URLs and URI paths
 A Uniform Resource Locator (URL) is a complete
web address
 A Uniform Resource Indicator (URI) absolute
path locates a resource within a server
URL
Host & port
URI abs_path
Path
Query string
http://my.corp.com:80/my/pages/home.html?A=1&B=req
Scheme
Paradigm
Port
Virtual directory
AS4026 10
HTTP Query Strings
 Used with GET requests to pass
name/value parameters to the server
 Uses "URL encoding" method of
representation




Delimited from the URI path by a "?"
Name/value pairs delimited by "&"
Embedded spaces translated to "+"
Special characters (including "&" and "+") translated
to ASCII hex equivalent using "%xx" notation
http://www.corp.com/stock?class=Class+A&
date=11%2F02%2F01&
your+name=&type=6
Paradigm
AS4026 11
HTML Forms
 Very powerful facility for soliciting input
from end users
 <FORM> … </FORM> tags in HTML
 When the form is "submitted," the contents
of its fields are sent to the web server as
name/value pairs
 Format determined by METHOD attribute
 METHOD=GET – Form data is transmitted in the query
string of the request URI path
 METHOD=POST – Form data is transmitted in the
"content" of the request
Paradigm
AS4026 12
A Simple HTML Form
<form action="/demo/upd" method=post>
First Name
<input type=text size=12 name="First Name">
Last Name
<input type=text size=12 name="Last Name">
<p>Gender
<select name=Gender size=1>
<option value=" " selected>
<option value=F>Female
<option value=M>Male
</select>
Approved
<input type=checkbox name=Approved value=1>
<p><input type=submit name=Fcn value=Go>
</form>
Paradigm
AS4026 13
The Simple HTML Form as Displayed
Paradigm
AS4026 14
HTTP Request Using POST Method
POST /demo/upd HTTP/1.1¬‡
Connection: Keep-Alive¬‡
User-Agent: Mozilla/4.5 (Win98; I)¬‡
Host: www.corp.com¬‡
Accept: image/gif, image/x-bitmap,¬‡
image/jpeg, */*¬‡
Content-Length: 65
¬‡
First+Name=John&Last+Name=Rhyes+Davies&
Gender=M&Approved=1&Fcn=Go
Paradigm
AS4026 15
HTTP Request Using GET Method
GET /demo/upd?First+Name=John&
Last+Name=Rhyes+Davies&Gender=M&
Approved=1&Fcn=Go HTTP/1.1¬‡
Connection: Keep-Alive¬‡
User-Agent: Mozilla/4.5 (Win98; I)¬‡
Host: www.corp.com¬‡
Accept: image/gif, image/x-bitmap,¬‡
image/jpeg, */*¬‡
¬‡
Paradigm
AS4026 16
Overview of
the WEBPCM
Web Transaction Server (Atlas)
 HTTP server for the MCP environment
 Operates as one or more Distributed
Systems Services (DSS)
 Supports static and dynamic content
 AAPI – Atlas API
 High performance application programming interface
 Based on connection libraries
 Requires Algol or NEWP programming
Paradigm
AS4026 18
The WEBPCM
 Provides a bridge between Atlas AAPI and
the MCP Transaction Server (COMS)
 Part of Custom Connect Facility (CCF)
 A CCF PCM (Protocol Converter Module)
 Basic building block of CCF
 Translates HTTP messages to a COMS interface
 Available since MCP 5.0 (SSR 46.1)
 Includes the WEBAPPSUPPORT library
 Called by application programs
 Parses HTTP requests and formats HTTP replies
Paradigm
AS4026 19
WEBPCM Features
 Bundled with the ClearPath IOE
 No per-seat license charges
 Use with Algol, COBOL, C, Pascal, and NEWP
 Supports standard COMS features




Direct and Remote File window interfaces
COMS Security
Processing Items
Synchronized recovery (with a few limitations)
 Supports special HTTP/HTML needs
 Character code translation
 HTTP header and cookie support
 HTML templates and data merging
Paradigm
AS4026 20
Custom Connect Facility (CCF)
CCF
Term
PCM
CUCI
PCM
COMS
Pgm
Pgm
CCF
Router
Pipes
PCM
Pgm
WEB
PCM
Port
PCM
Atlas
Client
Network
Paradigm
AS4026 21
COMS Programs and the WEBPCM
COMS
COMS Program
CCF
WEBPCM
Atlas
AAPI
DMSII
WEBAPPSUPPORT
HTML
HTTP
Paradigm
AS4026 22
Adding WEBPCM to a COMS Program
COMS Program
T27
COMS
Telnet
T27
Biz
DB
Interface
Rules
Protocol
DMSII
Web Interface
CCF
WEBPCM
Atlas
AAPI
WEBAPPSUPPORT
HTML
HTTP
Paradigm
AS4026 23
WEBPCM Session Control
 HTTP is a "stateless" protocol
 Each request is considered independent
 No session management or user authentication
 WEBPCM provides several options for
 Creation and duration of COMS stations
 Maintaining COMS sessions
 User authentication
 None (anonymous users)
 Passed through to and handled by application
 Require MCP usercode and password
– PW visible to the application
– PW hidden from the application
Paradigm
AS4026 24
WEBPCM Station Control Methods
 NONE
 Each HTTP request creates separate COMS dialog
 Station closed at end of application response
 PERMANENT
 Single COMS station for all web users of app
 User authentication typically handled by app
 COOKIE
 Each web user of app has own station and session
 WEBPCM generates HTTP cookies to identify dialog
 HTML
 Like COOKIE, but uses HTML hidden form fields
 Best to use only if browser will not handle cookies
Paradigm
AS4026 25
Configuring
the WEBPCM
WEBPCM Linkage
 WEBPCM is organized around "services"
 First node of URI path maps to an Atlas "Virtual
Directory"
 Atlas Virtual Directory maps to a WEBPCM "Service"
 WEBPCM Service maps to a COMS Window, and
optionally one or more Trancodes
 CCF automatically creates COMS stations
as necessary for dialogs with web users
 CCF stations can be dynamic (temporary)
or permanent in the COMS CFILE
Paradigm
AS4026 27
URLs and the WEBPCM
http://my.corp.com/payroll/hire/exempt?name=…
• First node of URI path
• Atlas Virtual Directory name
• WEBPCM Service path value
Paradigm
Second node can be
optionally used as the
COMS Trancode
AS4026 28
Implementing a WEBPCM Application
 Define the Virtual Directory in Atlas
 Define the WEBPCM Service in CCF
 Define the associated COMS entities
(if not already present)
 Create or modify the COMS application
programs
Paradigm
AS4026 29
Configuring Atlas
 Sign on to the ATLASADMIN provider
 http://my.clearpath.com:2488
 Requires a privileged MCP usercode
 Click Site Manager link on the home page
 Loads Java applet
 Must log on again with privileged MCP usercode
 Select the web site node and click New
 Enter the Virtual Directory name
 Change the type to "An application"
 Change the Application to "WEBPCM"
 Click Apply and restart the Atlas provider
Paradigm
AS4026 30
Go to the ATLASADMIN Site
Paradigm
AS4026 31
Sign on to the Atlas Provider
Must be privileged
Normally use
"atlassupport"
Paradigm
AS4026 32
Select Web Site Node and Click "New"
Paradigm
AS4026 33
Define the Virtual Directory Name
Paradigm
AS4026 34
Change Virtual Directory Type
Paradigm
AS4026 35
Change Application Name to WEBPCM
Paradigm
AS4026 36
Configuring CCF for WEBPCM
 Update the CCF configuration file
  MCP 6.0: *SYSTEM/COMS/CCF/PARAMS
  MCP 7.0: *SYSTEM/CCF/PARAMS
 Insure base WEBPCM configuration is
present (first time, only)
 Configure the WEBPCM Service(s)
 Reload the CCF configuration file
 You can also configure services
temporarily from ODT or MARC:
NA CCF WEBPCM ADD SERVICE …
Paradigm
AS4026 37
Base WEBPCM Configuration
 [ROUTER] Section
 ADD PCM WEBPCM
CODEFILE=*SYSTEM/CCF/PCM/WEB;
 ENABLE PCM WEBPCM;
as of
MCP
7.0
 [CUCIPCM] Section
 ADD SERVICE CUCIWEBSERVICE;
 ENABLE SERVICE CUCIWEBSERVICE;
 [WEBPCM] Section




Paradigm
ADD PROVIDER ATLASSUPPORT;
ENABLE PROVIDER ATLASSUPPORT;
Needed only
ADD PROVIDER ATLASADMIN;
for running
ENABLE PROVIDER ATLASADMIN;
demos
AS4026 38
Add a WEBPCM Service
[WEBPCM]
ADD SERVICE UNITEDEMO
PATH =
"/UNITEDEMO/",
SERVICE =
CUCIWEBSERVICE,
CHECKUSERAUTH =
FALSE,
USERCODE =
DEMO,
SHOWPW =
TRUE,
STATIONCONTROL = PERMANENT,
STATIONNAME =
UNITE/WEBPCM/DEMO,
DYNAMIC =
FALSE,
INACTIVITYTIMEOUT=4:00:00,
STRINGTERMINATE = FALSE,
TRANSLATE =
TRUE,
WINDOW =
W_UNITE_DEMO,
TRANCODE =
"UDEMO";
ENABLE SERVICE UNITEDEMO;
Paradigm
AS4026 39
Basic WEBPCM Attributes
 PATH
 Identifies the Atlas Virtual Directory name
 SERVICE
 Identifies the destination CCF PCM service
 Normally CUCIWEBSERVICE
 WINDOW
 Identifies the destination COMS Window
 TRANCODE
 Literal string for the COMS Trancode
 *URL
= taken from second node of URI path
 *DEFAULT
= constant ATLAS-HTTP
Paradigm
AS4026 40
Data Representation Attributes
 STRINGTERMINATE
 Determines WEBAPPSUPPORT parameter mode
 FALSE
fields are padded to full length with spaces
 TRUE
fields are terminated with NULL (hex 00)
 TRANSLATE
 FALSE
 TRUE
application sees raw data (ASCII)
application sees translated data (EBCDIC)
 APPLICATIONCCS
 Character set used by the MCP system
 CLIENTCCS
 Character set of the client (browser)
Paradigm
AS4026 41
User Authentication Attributes
 CHECKUSERAUTH
 FALSE
 TRUE
allow anonymous connections
require valid MCP usercode/pw from user
 SHOWPW
 FALSE
 TRUE
user's password not visible to application
password in $REMOTE-USER header
 USERCODE
 Constant usercode for the COMS session
 Overrides end-user supplied usercode
 ACCESSCODE
 CHARGECODE
Paradigm
AS4026 42
COMS Station Control Attributes
 STATIONCONTROL




NONE
PERMANENT
COOKIE
HTML
session closed after each request
single station/session for all users
session maintained by a cookie
session maintained by HTML fields
 STATIONNAME (see next slide)
 DYNAMIC
 FALSE
 TRUE
station remains in COMS CFILE
station removed from CFILE when closed
 SESSIONID
 String appended to station control cookie value
Paradigm
AS4026 43
WEBPCM Station Naming
 COMS station name "macro"
 Multiple fields separated by slashes
 Field elements









Paradigm
Literal text
#
$OPENTIME
$REMOTEHOST
$REMOTEIPADDR
$SERVERHOST
$SERVERPORT
$USERCODE
$WINDOW
unique number
connection open time, hhmmss
client host name
client IP address
MCP host name
MCP HTTP port number
MCP usercode
COMS window name
AS4026 44
Miscellaneous WEBPCM Attributes
 INACTIVITYTIMEOUT
 Maximum connection idle time
 HH:MM:SS or MM:SS or SS
 Default is 12:00:00
 PROGRAMID
 Prefix string for CCF error messages
Paradigm
AS4026 45
A Single-Session-for-All Service
ADD SERVICE UNITEDEMO
PATH =
"/UNITEDEMO/",
SERVICE =
CUCIWEBSERVICE,
CHECKUSERAUTH =
FALSE,
USERCODE =
DEMO,
SHOWPW =
TRUE,
STATIONCONTROL = PERMANENT,
STATIONNAME =
UNITE/WEBPCM/DEMO,
DYNAMIC =
FALSE,
INACTIVITYTIMEOUT=4:00:00,
STRINGTERMINATE = FALSE,
TRANSLATE =
TRUE,
WINDOW =
W_UNITE_DEMO,
TRANCODE =
"UDEMO";
ENABLE SERVICE UNITEDEMO;
Paradigm
AS4026 46
A Session-per-User Service
ADD SERVICE DEMO2
PATH =
"/DEMO-2/",
SERVICE =
CUCIWEBSERVICE,
CHECKUSERAUTH =
TRUE,
%--NO USERCODE SPECIFIED-SHOWPW =
FALSE,
STATIONCONTROL = COOKIE,
STATIONNAME =
DEMO/$REMOTEIPADDR/#,
DYNAMIC =
TRUE,
INACTIVITYTIMEOUT=15:00,
STRINGTERMINATE = TRUE,
TRANSLATE =
FALSE,
WINDOW =
W_DEMO_2,
TRANCODE =
*URL;
ENABLE SERVICE DEMO2;
Paradigm
AS4026 47
COMS Configuration
 Same as for non-WEBPCM applications
 Need at least a Window and a Program
 For Direct Window programs
 Need at least one Agenda
 Perhaps Trancodes
 Perhaps a Database for synchronized recovery
 Optionally,




Paradigm
Users
Stations
Security entities
Processing Items
AS4026 48
Programming for
the WEBPCM
Paradigm
AS4026 49
COMS Program Interfaces
 WEBPCM supports both Direct Window
and Remote File programs
 COMS is not aware it's handling web data
 Message content is transparent to COMS
 Programs use SEND/RECEIVE or READ/WRITE in
the normal manner
 HTTP and HTML issues are handled by
convention between application programs
and the WEBPCM
Paradigm
AS4026 50
Choice of Programming Language
 Elements of HTTP/HTML messages are
 Case insensitive
 Variable length
 WEBPCM has good support for COBOL




Header and field parsing
Optional ASCII/EBCDIC translation
Optional fixed-length, blank-filled data fields
HTML templates with data merging
 COBOL-85 has better facilities than -74
 Algol has much better string parsing and
formatting facilities than COBOL
Paradigm
AS4026 51
WEBPCM Message Format
 WEBPCM uses a special data format
called a Message Object
 Characters 1-17
 Characters 18-n
COMS Trancode
used by WEBAPPSUPPORT
 Programs should not manipulate the
message object directly
 Trancode field is the only useful portion to examine
 Rest is manipulated through WEBAPPSUPPORT
Paradigm
Trancode
Private to WEBAPPSUPPORT
17
Rest of message
AS4026 52
General Transaction Flow
 Receive the Message Object from COMS
 Extract headers of interest
 Extract cookies, if desired
 Parse data fields from query string or body
 Perform internal processing
 Format response




Generate or merge HTML text
Set values of headers and cookies
Set response text in message object
Obtain length of resulting message object
 Send the Message Object back to COMS
Paradigm
AS4026 53
WEBAPPSUPPORT Library
 Part of CCF WEBPCM
 Operates on the Message Object
 Implemented as a temporary, Shared-by-All library
 Programs link by SL function name
 Two forms of entry points
 COBOL-style
 Algol/C-style
PARSE_POST_DATA
parsePostData
 The two forms function identically




Paradigm
Same result values
Similar parameters
COBOL style passes arrays without lower bound
Algol style passes arrays with lower bound: A[*]
AS4026 54
WEBAPPSUPPORT String Parameters
 Format of string values controlled by two
WEBPCM Service attributes
 STRINGTERMINATE
 FALSE
fields are padded to full length with spaces
 TRUE
fields are terminated with NULL (hex 00)
 COBOL usually works best with FALSE
 TRANSLATE
 FALSE
application sees raw data
 TRUE
application sees data translated
 COBOL usually works best with TRUE (will see data
translated to EBCDIC)
Paradigm
AS4026 55
WEBAPPSUPPORT Result Codes
1
0
-1
-2
-3
-4
-15
-16
-17
Successful
No-op (no data to return)
Invalid transaction ID (client closed conn)
Response not allowed
Software error (corrupt Message Object,
internal fault)
Service unavailable (lib linkage problem)
Character set not available
File character set not available
Translation not available
(plus additional codes for certain routines)
Paradigm
AS4026 56
Sample WEBAPPSUPPORT Call
01
01
01
01
MSG-OBJECT
W-NAME
W-VALUE
W-RESULT
PIC
PIC
PIC
PIC
X(15000).
X(18).
X(90).
S9(11) BINARY.
RECEIVE COMS-IN MESSAGE INTO MSG-OBJECT.
...
MOVE "User-Agent" TO W-NAME.
CALL "GET_HEADER IN WEBAPPSUPPORT" USING
MSG-OBJECT, W-NAME, W-VALUE
GIVING W-RESULT.
IF W-RESULT = 1
MOVE W-VALUE TO WIP-DOTTED-DECIMAL
PERFORM PARSE-IP-ADDRESS
ELSE
PERFORM MISSING-IP-ADDRESS.
Paradigm
AS4026 57
WEBAPPSUPPORT Routine Classes
 Header management routines
 Request parsing routines
 Response formatting routines
 Data/HTML merging routines
 Time routines
 Text escape routines
 Miscellaneous routines
Paradigm
AS4026 58
Header Management Routines
 GET_HEADER
 GET_n_HEADERS (n = 2-8)
 PARSE_HEADERS
 PARSE_COOKIES
 SET_HEADER
 SET_COOKIE
Paradigm
AS4026 59
Read-only "Pseudo" Headers
$APPLICATION-PATH
$QUERY-STRING
$AUTH-TYPE
$REMOTE-ADDRESS
$CONTENT-TYPE
$REMOTE-HOST
$METHOD
$REMOTE-USER
$PATH-INFO
$REQUEST-LINE
$PATH-TRANSLATED
$REQUEST-PATH
$PROTOCOL
$REQUEST-URI
$SERVER-NAME
Paradigm
AS4026 60
Request Parsing Routines
 GET_REQUEST_INFO
 GET_POSTED_DATA
 PARSE_QUERY_STRING
 PARSE_POST_DATA
Paradigm
AS4026 61
Response Formatting Routines
 SET_STATUS_CODE
 SET_CONTENT_TYPE
 SET_CONTENT
 GET_MESSAGE_LENGTH
 SET_REDIRECT
 SET_TRANSLATION
Paradigm
AS4026 62
Data/HTML Merging Routines
 MERGE_DATA
 MERGE_FILE_AND_DATA
 MERGE_I18NFILE_AND_DATA
Name/value
table
F1
F2
JANE
10/17
HTML template
<form action="/demo/txn" method=post>
<input name=fn type=text value="$REPLACE=F1">
<input name=dt type=text $REPLACE-VALUE=F2>
<input name=submit type=submit value=Go>
</form>
Paradigm
AS4026 63
Time Routines
 CURRENT_UTIME [Time(57) format]
 HTTP_DATE_TO_INT
 HTTP_DATE_TO_TIME57
 INT_TO_HTTP_DATE
 INT_TO_TIME57
 TIME57_TO_HTTP_DATE
 TIME57_TO_INT
Paradigm
AS4026 64
Text Escape Routines
 HTML_ESCAPE
 HTML_UNESCAPE
 HTTP_ESCAPE
 HTTP_UNESCAPE
HTML escape:
This is a <tag> symbol
This is a &lt;tag&gt; symbol
HTTP escape (URL encoding):
COMS station/session entry
COMS+station%2Fsession+entry
Paradigm
AS4026 65
Miscellaneous Routines
 GET_USER_AUTHORIZED
 GET_USER_PRIVILEGED
 GET_DIALOG_ID
 GET_SERVER_PORT
 GET_REAL_PATH
 GET_MIME_TYPE
 SET_TRACING
 TRACE_WEB_MSG
Paradigm
AS4026 66
Issues with the WEBPCM
 Documentation could be better
 WinHelp format
 Sketchy in some areas
 Very long input fields
 PARSE_QUERY_STRING & PARSE_POSTED_DATA
 Require all names and values to have same length
 Arbitrarily long output text
 Length of response is often highly variable and
unknown at the beginning
 WEBPCM just about requires you to generate the
complete response text before sending any of it
 Can fake out the WEBPCM using chunked content
Paradigm
AS4026 67
Sample Programs
 This presentation
http://www.digm.com/Unite/2002
 Bundled WEBPCM examples
*SYSTEM/CCF/WEBPCM/DEMOS/=
WEBPCMDEMO1/SYMBOL (COBOL)
WEBPCMDEMO2/SYMBOL (Algol)
 Integration Expert (PathMate)
Paradigm
AS4026 68
Resources
 Custom Connect Facility Administration
and Programming Guide (WinHelp file)
 Web Transaction Server (Atlas)
Administration and Programming Guide
(HTLMhelp file)
 HTTP and HTML specifications available
at http://www.w3c.org
 Request for Comments (RFC) documents
available at http://www.ietf.org
Paradigm
AS4026 69
End
Using the WEBPCM
Session AS4026
2002 UNITE Conference
Paradigm
AS4026 70