CICS Web Support
CICS Web Support
Erich Amrehn
Gregg Bartowitz
Hans Joachim Ebert
Kenneth Johnsen
Benno Sauer
ibm.com/redbooks
SG24-5997-00
International Technical Support Organization
November 2000
Take Note!
Before using this information and the product it supports, be sure to read the general information in Appendix B,
“Special notices” on page 109.
This edition applies to CICS Transaction Server for VSE/ESA 1.1.1, Program Number 5648-054, for use with
VSE/ESA 2.5
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way
it believes appropriate without incurring any obligation to you.
Appendix A. Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
A.1 Listing of DFHSIT for CWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
A.2 Listing of RDO definitions: CWS parameters highlighted. . . . . . . . . . . . . . . . . 71
A.2.1 Listing defined DOCTEMPLATEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
A.2.2 Listing of RDO TCPIPSERVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
A.3 Listing of TCP/IP IPINIT00 with CWS parameters highlighted. . . . . . . . . . . . .73
A.4 Listing of program samples including JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
A.4.1 All HTML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
A.4.2 All HTML documents for VSAMHTML sample program. . . . . . . . . . . . . . 79
A.4.3 CICS assembler samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
A.4.4 Catalog jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
A.5 Sample listings used with the 3270 bridge support . . . . . . . . . . . . . . . . . . . . . 91
A.6 DFHCNV source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
A.7 Source listing DFHWBEP sample program . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
CWS first became available in OS/390 with CICS TS 1.2, and was enhanced in
release 1.3. This 1.3 functionality was ported to CICS TS for VSE/ESA 1.1.1.
CICS Web Support is an effective solution for the VSE/ESA user community. It is
a powerful 2-tier Web enablement solution that is easy to plan for and simple to
implement. Our goal for this IBM Redbook is to provide you with the information
to use this great e-business connector. CWS unites browser technology with
S/390. This provides tremendous flexibility to the end-user community, while
capitalizing on S/390 performance, reliability, scalability, availability, and data
integrity.
This redbook discusses and positions the new CICS TS for VSE/ESA 1.1.1 CICS
Web Support (CWS) and 3270 bridge. It provides a broad understanding of the
new architecture, together with examples and samples to help customers in their
planning and implementation of CWS. CWS employs a unique approach for using
an e-business connector in the VSE/ESA environment.
This redbook also discusses planning for CWS, installation, and customization. It
provides the guidance you need to design new solutions and upgrade existing
solutions.
There are three new publications available with CICS TS 1.1.1 that provide
detailed information about CWS:
• CICS Transaction Server for VSE/ESA Enhancement Guide Release 1 ,
SC34-5763
• CICS Transaction Server for VSE/ESA Internet Guide Release 1, SC34-5765
• CICS Transaction Server for VSE/ESA CICS External Interface Guide Release
1, SC33-1669
Thanks to the following people for their invaluable contributions to this project:
Comments welcome
Your comments are important to us!
The browser can activate a Java Servlet, which contains the MQ-API commands
to communicate, by way of the middle-tier MQSeries, with the VSE/ESA
MQSeries applications.
Keep these limitations in mind when deciding if CWS is the appropriate connector
for your environment.
VSE/ESA
4 DFHCCNV
1 2 3 (headers)
Web
request TCP/IP Sockets attach 5
from client for Listener processing Analyzer
VSE/ESA task
CWXN 6
CSOL DFHCCNV
(user data)
l
8 Converter
(Decode)
Alias 9 CICS
13 10 program
CWBA
11 Converter
(Encode)
15 14 12
DFHCCNV
reply
to client
Figure 1. Calling a program with CWS: Control flow for COMMAREA solution
You may access your CICS TS application from a Web browser with the following
Universal Resource Locator (URL):
http://ip.address:port/converter/alias/program
For programs that are not BMS, HTML pages are dynamically built from the 3270
data streams. This allows dynamic, two-way translation between 3270 and HTML
data. Users can access their applications from any client that supports a standard
Web browser. This powerful solution requires no application changes. However,
implementation of this CWS feature requires a bridge exit program. A sample
bridge exit program is provided with CWS and may be sufficient in your
environment.
For BMS programs, this solution utilizes HTML templates which can be generated
from existing BMS maps. A second assembly of the BMS map is required with the
parameter: TYPE=TEMPLATE added to the DFHMSD macro. The other option
would be to pass: SYSPARM=TEMPLATE to the assembler. This generates the
HTML code that is presented to the Web browser. The resulting HTML member
may be further tailored as needed. For additional information, go to the URL at:
http://ip.address:port/cics/cwba/dfhwbtta/tran
DFHWBTTA is the program initiating the 3270 bridge operation. It is the “switch”
for CWS to utilize the 3270 bridge code.
You may also need to consider hardware and software planning, depending on
your environment; for example:
• What hardware connections will you use for connectivity to your intranet or to
the Internet?
• Do you have a firewall?
• Do you need one?
• Do you already have an IP address for your VSE/ESA 2.5.0 system?
• Which TCP/IP for VSE/ESA ports, outside of the well-known ports, are you
using today?
• Will you need to code your own analyzer program, converter program, or Web
error program?
• What about security?
• Will you implement the sample security programs, DFH$WBSA, DFH$WBSC,
and DFH$WBSN, which are provided with CWS?
Your planning will take more time than the CICS TS and TCP/IP for VSE/ESA
“system” changes for the basic implementation of CWS in VSE/ESA.
Our environment consisted of VSE/ESA 2.5.0 running under VM. We used virtual
channel-to-channel (VCTCA) connections to VM and TCP/IP. TCP/IP for
VSE/ESA 1.4.0 ran in partition F4. Our CICS TS for testing CWS ran in partition
F8. The partition size for this CICS TS was 50 MB of storage (yes, this was larger
than we needed). From our location, we tested CWS on a system in
Poughkeepsie, NY (local LAN, as well as dial-in), and in Munich, Germany. We
used multiple browsers at different release levels and noticed subtle differences.
If the DOCTEMPLATE does specify a library name, CICS searches the sublibrary
called DFHDOC in the specified library only (CICS does not search the LIBDEF
string) for the member (still with the suffix HTML).
DFHSIT parameters
One parameter change is required: TCPIP=NO is the default and must be
changed to TCPIP=YES.
WEBDELAY=xx defines after what time, in minutes, the 3270 bridge tasks are
purged if they are in a terminal wait state. This will result in a ABRQ transaction
abend code.
DOCCODEPAGE=37 code page specifies the default host code page used by the
Document Domain. If nothing is specified, the default of 37 will be used.
In addition, there are other parameters that you should consider. For example,
another default is GRPLIST=VSELST2. Because up to four CSD lists may be
concatenated, we chose to use GRPLIST=(VSELST2,MYLST2). MYLST2
contains our customizations and is processed after VSELST2.
RDO definitions
For RDO definitions, there is only one modification to do. The entry is in group
DFH$SOT. The type is TCPIPSERVICE. The name is HTTPNSSL.
TCPIPSERVICE is the resource definition used to define which TCP/IP services
are to use CICS TS internal sockets support. The internal CICS TS service is
CWS. By default, the TCPIP listener port number used by HTTPNSSL is 00080.
We recommend that the port number be outside the range of well-known ports, so
you should select a port number that is greater than 1024. This will be the port
address used for communications between CICS TS and TCP/IP.
The RDO group DFH$SOT is not in the default CSD lists. You must copy
HTTPNSSL from DFH$SOT, modify it as needed, and reference it in your startup
list. When you connect to CICS TS without the TCPIPSERVICE definitions, the
following messages will be sent to the VSE console:
IPN598W Socket request rejected due to improper foundation
IPN373W Stalled TCP connection has been Flushed, IP:x.xxx.xxx.xxx
Other CSD groups to be aware of are DFHWEB, TCPIP, and DFHDOC. These
groups are supplied in the default lists VSELIST and VSELST2. These groups are
DOCTEMPLATES
Use the doctemplates resource definition to define document templates to CICS
TS. Document templates are the HTML representations of self-coded information
and your BMS maps which are presented to users that access your CICS TS with
a browser.
Doctemplates are CICS TS resources and are made available to CICS TS with
RDO. The template has to be cataloged into a library according to what we
specified in 3.1.1, “VSE/ESA Library for CICS Web Support templates” on page
11. The members in the library.sublibrary have the extension HTML.
DFHCNV table
DFHCNV is a user-written conversion table that is called by program DFHCCNV.
It is not difficult to code this table. It is used by CWS to convert incoming requests
to EBCDIC and outgoing responses back to ASCII for COMMAREA style and
3270-based programs.
The DFHWBHH template is used to translate the HTTP header information, and
DFHWBUD is used by the default analyzer for user data conversion. The source
code for our DFHCNV table can be found in Appendix A, “Listings” on page 69.
Virtual storage
As a guide, CWS requires 500 KB of DSA (24-bit) storage, and 2 MB of EDSA
(31-bit) storage. In addition, you need to plan for 1 MB EDSA (31-bit) storage per
concurrent user.
These two storage considerations affect the size of your CICS TS partition, so
plan accordingly.
DEFINE NAME,NAME=VSEESA.250.IBM.COM,IPADDR=n.n.n.n
Here, NAME is a meaningful host name, and IPADDR specifies the dotted
decimal address of your VSE/ESA system. If you do not identify the server, CWS
will not initialize successfully and the following error message appears during the
CICS TS startup:
DFHSO0117 applid Unable to determine the TCP/IP host name. Language environment
return code X’00000458’, reason code X’00000000’.TCP/IP services are
unavailable.
DFH$WB1A on system xxxxxxxx successfully invoked through the CICS Web support.
Note that n.n.n.n is replaced by your valid IP address. Also, to send data on the
initial request, use plus signs (+) rather than blanks. CWS interprets a plus (+)
sign as a blank. The first “real” blank space in a URL indicates end of data.
Let us suppose that, in your environment, you want to impose rules about which
clients can use which services. To deny access, you will need to tailor your own
analyzer program.
If you have a need to reformat the inbound or outbound COMMAREA, you will
need to tailor your own converter program.
If you want to tailor the default HTTP error response returned by CICS TS so that
the response is more meaningful to your users, you will need to tailor your own
Web error program.
In the sections that follow, we briefly discuss the analyzer program, the converter
program, and the Web error program. Additional information can be found in:
• CICS Transaction Server for VSE/ESA Internet Guide Release 1, SC34-5765
• CICS Transaction Server for OS/390 Version 1 Release 3: Web Support and
3270 Bridge, SG24-5480
If you use a different analyzer, you must specify this in the RDO TCPIPSERVICE.
The default analyzer is written for HTTP requests in which the absolute path is in
one of the following four forms:
• /converter/alias/program
• /converter/alias/program?token
• /converter/alias/program/<filename>
• /converter/alias/program/<filename><?token>
The default analyzer links to the CICS TS-supplied utility DFHWBUN, to analyze
the user data in the communications area passed by the analyzer.
The default analyzer checks the eye-catcher, and then interprets the contents of
the absolute path as follows:
• converter must be between one and eight characters long. It is converted to
uppercase and interpreted as the name of the converter to be called by the
alias, unless it has the value CICS, in which case the converter name is set to
nulls to show that no converter is to be used.
• alias must be between one and eight characters long. It is converted to
uppercase and interpreted as the transaction ID of the alias transaction to be
used to service the request.
• program is the name of your application program and must be between one
and eight characters long. It is converted to uppercase and interpreted as the
name of the CICS TS program that is to be used to service the request.
• filename is an optional parameter when PROGNAME is regarded as a
directory. It can be any length, but it must not begin with a slash (/) or contain
a question mark(?). It must be made up of the characters allowed in URLs. It is
ignored by the analyzer, but is available to the converter or the CICS TS
program.
• token is an optional 8-character field to be passed in the USER_TOKEN field
to the decode function of the converter program.
• If program is DFHWBTTA, the filename is treated as the ID of the transaction
to be run using the 3270 bridge facility.
Note that CICS TS supports only the HTTP 1.0 Keep-Alive implementation of the
persistent connections, not the HTTP 1.1 implementation.
You might not need to write any converters. If the analyzer or the caller of the
CICS TS business logic interface indicates that a converter is not required, the
first 32 KB of storage of the request is passed to the CICS TS program in its
communication area.
The names of parameters and constants in the communication area are passed
to the converter, translated into appropriate forms for the different programming
languages supported, and defined in copybooks supplied as part of CWS. The
copybook names are listed in Table 1.
Table 1. Copybook parameters and constants
C DFHWBCDH DFHWBUCH
These copybooks give language-specific information about the data types of the
fields in the communication area. If you use these, you must specify
XOPTS(NOLINKAGE) on the translator step; failure to do this causes the compile
to fail. If CICS is entered as the converter name, no encode or decode occurs.
The parameter list passed to the Web error program contains a pointer to a buffer
containing the default HTTP response returned by CICS TS for the error
detected, and the length of the response. The Web error program can:
• Leave the response unchanged
• Modify the response returned, and update the length in
WBEP_RESPONSE_LEN accordingly
• Use the GETMAIN function to create a new buffer, build a new HTTP
response, and pass back the address of the new buffer using the
WEB_RESPONSE_PTR parameter
The default HTTP response is passed to the Web error program in EBCDIC form.
CICS TS assumes that the HTTP response addressed by
WBEP_RESPONSE_PTR on exit from the Web error program is in EBCDIC, and
performs code page conversion on the response to convert it to ASCII before
returning it to the client. The key used for this conversion is that which was
selected by the analyzer user-replaceable module. If none was selected, or if the
analyzer was not selected before the error occurred, the response is assumed to
be in the ISO-8859-1 code page (Latin -1).
The DSECT or copybooks to describe the fields in the COMMAREA are provided
by CICS and have the following names:
• DFHWBEPD: Assembler
• DFHWBEPH: C
• DFHWBEPO: COBOL
• DFHWBEPL: PL/I
Section A.7, “Source listing DFHWBEP sample program” on page 99, contains
the source code we used. The program first checks to see if the HTML tag
</body> is present within the length of the response that is given as input. If yes,
it overwrites this tag with the information that will be added to the buffer, and
writes a new one at the end. If the tag is not present, it starts writing immediately
after the response in the buffer.
Figure 2 shows the output of DFHWBEP for a Program Not Found error.
In order to make decisions about which facilities to use and how to customize
them, you need to understand how data is passed within CICS Web Support.
Figure 4 on page 24 shows the data flow from client through CICS and back, with
the communications area used. Be aware that Figure 4 on page 24 is a different
view than what is described in 2.2, “CICS Web Support logic and flow” on page 7.
The following figure concentrates on communications area handling.
2 DFHCCNV 3 DFHCCNV
Communication area
5 CICS program
Communication area
6 Encode
7 DFHCCNV 8 DFHCCNV
9
Figure 4. Calling a program using the CICS Web Support COMMAREA method-data flow
For a detailed description of these APIs, refer to CICS Transaction Server for
VSE/ESA Internet Guide Release 1, SC34-5765, and CICS Transaction Server
for VSE/ESA Enhancement Guide Release 1, SC34-5763.
It is important to note that sending data to a task, and receiving data from a task,
is a totally new approach for CICS systems.
Prior to CWS, a task that was started received data in two ways:
• Using a terminal input/output area for a terminal-attached task.
• Using mechanisms like COMMAREAs, READQ TD, and RETRIEVE. This
input was provided by CICS programs which run prior to the attached task.
With CWS, all tasks are non-terminal tasks, but data is exchanged with a
“terminal” from a logical point of view, called a “browser”. To cover this new
situation, EXEC CICS WEB was introduced with parameters such as RECEIVE
and SEND, and so on. This means that certain application programming interface
commands cannot be used. Those commands include:
• Terminal control commands that refer to the principal facility
• Options of EXEC CICS ASSIGN that return terminal attributes
• BMS commands
• Signon and signoff commands
Prior to CICS TS, it was not possible to debug non-terminal tasks with CEDF. To
allow CWS tasks to be debugged interactively, the new CICS with CEDX
transaction has been developed. More information about CEDX can be found in
Chapter 7, “Problem determination and application debugging” on page 67.
This section provides two CWS COMMAREA examples and explains how they
work. Table 3 describes the sample (HTML) documents and programs used
throughout this chapter.
All CICS assembler sample programs and the associated HTML documents can
be found in A.4, “Listing of program samples including JCL” on page 75.
Table 3. Our supplied HTML documents and CICS sample programs
Documents/Programs Usage
Note: The screen layout presented by the browser could vary from one browser
to another or even from one browser release to another.
The numbers appearing down the right-hand side of Figure 6 on page 30 and
Figure 7 correspond to the items in the following list:
1 Creates document with the first part of the HTML template (header template
‘EXTRCTH1’).
3 Inserts the HTML tag “<p>Client Name :” into the document. This tag generates
a new paragraph and inserts “Client Name :” as text.
4 Inserts the client name that we received from TCP/IP EXTRACT into the
document. The client name is inserted right after the text “Client Name :”.
5 Inserts the HTML tag “<p>Server Name :” into the document. This tag
generates a new paragraph and inserts “Server Name :” as text.
6 Inserts the server name that we received from TCP/IP EXTRACT into the
document. The server name is inserted right after the text “Server Name :”.
7 Inserts the HTML tag “<p>TCPIPSERVICE name: ” into the document. The tag
generates a new paragraph and inserts “TCPIPSERVICE name:” as text.
8 Inserts the TCP/IP service name that we received from TCP/IP EXTRACT into
the document. The TCP/IP service name is inserted right after the text
“TCPIPSERVICE name:”.
10 Next, the document is sent to the browser and translated with the specified
code page.
Now we are ready to use the EXTRCT1 program. To start EXTRCT1, enter a URL
like the following example on your browser:
http://n.nn.nn.nnn:1080/cics/CWBA/EXTRCT1
As mentioned earlier, an easier way to start our sample programs is to type the
URL http://n.nn.nn.nnn on the browser. This forces the HTTP daemon to look
for the member INDEX.HTML in the ROOT sublibrary, and send it to the browser
(see Figure 9).
At this INDEX page, you can click here to receive the DEMO.HTML page (see
Figure 10 on page 34).
At the DEMO page, you can choose to run the DFH$WB1A sample or the
EXTRCT1 sample. If you click EXTRCT1, you are presented a page with two
additional options as shown in Figure 11.
The first of the additional options is Click here for a Masthead , which starts the
EXTRCT2 program and displays the page shown in Figure 12 on page 35.
The page shown in Figure 13 also allows you to select one of six backdrop boxes
that will start sample program EXTRCT4.
.
.
EXTRCT4 CSECT
EXTRCT4 AMODE 31
EXTRCT4 RMODE ANY
EXEC CICS HANDLE CONDITION INVREQ(DOCINSRT)
EXEC CICS DOCUMENT CREATE DOCTOKEN(doctoken) * 1
TEMPLATE('EXTRCTH4')
.
.
DOCINSRT EXEC CICS WEB READ FORMFIELD(TEXTURE) NAMELENGTH(L'TEXTURE) * 2
VALUE(TEXT) VALUELENGTH(TEXTL) NOHANDLE
CLI TEXT,C'1' 3
BE TEXT1
.
.
CLI TEXT,C'6' 3
BE TEXT6
B ENDBODY
TEXT1 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(doctoken) * 4
TEXT(TEXT1NFO) LENGTH(TEXT1NFL)
B ENDBODY
.
.
TEXT6 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(doctoken) * 4
TEXT(TEXT6NFO) LENGTH(TEXT6NFL)
B ENDBODY
* Close Body
ENDBODY EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(doctoken) * 5
TEXT(BODYINFO) LENGTH(BODYINFL)
* Insert image name
EXEC CICS DOCUMENT INSERT DOCTOKEN(doctoken) * 6
FROM(IMAGINFO) LENGTH(IMAGINFL)
* Insert header
EXEC CICS DOCUMENT INSERT DOCTOKEN(doctoken) * 7
FROM(HEADER) LENGTH(HEADERL)
* Insert client name 8
.
.
* Insert footer for document
EXEC CICS DOCUMENT INSERT DOCTOKEN(doctoken) * 9
TEMPLATE('EXTRCTF4')
* Send complete document
EXEC CICS WEB SEND DOCTOKEN(doctoken) * 10
CLNTCODEPAGE('iso-8859-1')
EXEC CICS RETURN
.
.
IMAGINFO DC C'<img alt="" src="/DFHWBIMG/masthead.gif">'
IMAGINFL DC F'41'
HEADER DC C'<h1>EXTRACT - Running CICS Web Support on VSE/ESA</h1>'
DC C'<p>with a masthead and a background'
DC C'<p><hr>'
HEADERL DC A(*-HEADER)
TEXT1NFO DC C' background="/DFHWBIMG/texture1.jpeg"'
TEXT1NFL DC A(*-TEXT1NFO)
.
.
TEXT6NFO DC C' background="/DFHWBIMG/texture6.jpeg"'
TEXT6NFL DC A(*-TEXT6NFO)
BODYINFO DC C'>'
BODYINFL DC F'1'
TEXTURE DC C'TEXTURE'
END EXTRCT4
1 Creates a document with the first part of the HTML template (header template
EXTRCTH4).
5 Completes the body by adding the greater than (>) sign and inserts it into the
document.
9 Completes the document by inserting the footer template (EXTRCTF4) into the
document.
10 Sends the complete document to the browser with the selected backdrop and
masthead image.
Figure 15 shows you the HTML sent by sample program EXTRCT4, when box 1
was selected as the background. See Figure 54 on page 87 to view the EXTRCT4
source code with the background choices.
Figure 15. HTML sent by sample program EXTRCT4 (backdrop box 1 used)
Figure 16. HTML sent by sample program EXTRC4 (backdrop box 2 used)
By the way, many browsers give you the ability to look at the source code of the
displayed document. In Netscape, select View->Page Source to access the
HTML of the page being displayed.
We did not test the additional record functions Add, Update and Delete. These
additional functions are disabled in the test program VSAMHTML. If you need this
functionality, you must change the source code appropriately and test the results.
Every HTML document should contain certain standard HTML tags. Each
document consists of a head and body section. The head section contains the
title, and the body section contains the actual text that is made up of paragraphs,
lists and other elements.
The required elements are the <html>, <head>, <title>, and <body> tags (and
their corresponding end tags). For validation of your HTML document, go to the
URL:
http://validator.w3.org/
Here is a sample of how to access a GIF file from the CICS home page (Figure 18
on page 41) and transfer it to your VSE/ESA:
1. Enter http://www-4.ibm.com/software/ts/cics/ on your browser.
2. On the CICS home page, right-click the CICS-IMG.gif file, and save it as
CICSTST.gif on your PC.
3. On your PC, open a command prompt, and use the following commands to
transfer the file CICSTST.gif to your VSE/ESA to sublibrary
DFHHTML.DFHDOC:
c:\>ftp n.nn.n.nnn
Connect to n.nn.n.nnn.
220-TCP/IP for VSE -- Version 01.03.00 -- FTP Daemon
Copyright (c) 1995,1999 Connectivity Systems Incorporated
220 Service ready for new user.
User (n.nn.n.nnn:(none)): XXXX
331 User name okay,need password.
Password:
230 User logged in, proceed.
ftp> cd dfhhtml.dfhdoc
250 Requested file action okay, completed.
ftp> bin
200 Command okay.
ftp> put cicstst.gif
200 Command okay.
150-File: DFHHTML.DFHDOC.CICSTST.GIF
Type: Binary Recfm: S Lrecl: 4096
CC:ON UNIX=OFF RECLF=OFF TRCC=OFF CRLF=ON
150 File status okay; about to open data connection
226-Bytes sent: 5,823
Each newly created Web page should be tested with different browsers and
different PCs to verify that the output (Web page) meets your requirements. The
Web page layout presented by the browser may vary depending on the browser.
The switch to the bridge facility takes place when DFHWBTTA has been detected
in the incoming HTTP data stream as the program name followed by the name of
the transaction to be run; see Figure 20.
Alias transaction
Figure 20. Running a transaction with CICS Web Support: 3270 bridge
5.2 DFHWBTTA
DFHWBTTA, the terminal translation program, is a callable CICS-supplied
program that provides an interface between Web browsers and user 3270
CICS transactions using the 3270 bridge facility. DFHWBTTA, and its
associated programs, performs the translation between HTML and 3270 data
streams or BMS maps. DFHWBTTA supports non-conversational,
conversational, and pseudo-conversational transactions.
Note: Before you can run a BMS transaction, you must provide HTML
templates that correspond to the maps you are using in the 3270 transaction.
HTML templates are generated from existing BMS mapset definitions, as
explained in 5.3.1, “Creating HTML templates from BMS definitions” on page
45.
To pass optional data with the request, use plus signs (+) rather than blanks.
CWS interprets a (+) sign as a blank. For example, to invoke a CEMT with INQ
TAS, use the following URL:
http://testcics/cics/cwba/dfhwbtta/cemt+inq+tas
The input to the user transaction ends with the first “real” blank.
Note: Keep in mind that once you have received your response, for example,
to the above URL, you need to use the buttons provided in the browser output
to simulate the various 3270 keys, not the keys on your keyboard. Also note
that it is not a good practice to use the backward or forward buttons of your
browser to move through your application’s output.
Before you can start writing a program that uses a map, you must assemble
these macros twice.
When you define TYPE=MAP on the DFHMSD macro, you can assemble and link
edit a load module called the physical mapset. The physical mapset is loaded by
CICS at execution time and is used to transform the application data to a 3270
data stream or vice versa.
When you specify TYPE=DSECT on the DFHMSD macro, you assemble the
symbolic mapset . This is a series of data structures in the language specified in
the LANG option. A symbolic map is copied into the program and enables you to
refer to the fields in the maps by name, without having to know details about the
physical position on the screen.
Various modifications to existing BMS macros and new tools enable generation of
HTML templates from BMS maps and customization of the BMS maps to make
the output more suitable to the Web browser environment.
For BMS programs that want to use the 3270 bridge facility, their BMS maps must
be reassembled specifying TYPE=TEMPLATE on the DFHMSD macro, or by
specifying SYSPARM=TEMPLATE in the parameters passed to the assembler.
This, in turn, generates an HTML template to be used during the BMS mapping
operation. Note that the label on the DFHMSD macro is used to name the HTML
templates produced for each map in the mapset being processed.
There are no changes required to the application program, nor is there a need to
generate a DOCTEMPLATE RDO definition, unless you want to specify a
VSE/ESA library other than the IBM default library, DFHHTML, in which to store
your templates.
Note: Installations without access to the original source code for BMS mapsets
can re-create the BMS macro statements, with some limitations, using a BMS
The numbers in the following list correspond to the numbers printed on the
right-hand side in the figure.
2 Remove this catalog statement. This allows the proper catalog statement to be
generated for the template name. As mentioned earlier, the HTML template
names consist of the label from the DFHMSD macro, plus one character starting
from A for each map in the mapset. This allows the bridge exit to match the HTML
template with the BMS map when a BMS SEND or RECEIVE is issued by a
program. The library member type is always HTML.
The source for the BMS mapset defined for our program is shown in Figure 22 on
page 49. This is followed by the normal 3270 screen output when transid VSAM is
entered on the 3270 CICS screen. Note that we added additional BMS macros,
DFHMSX and DFHMDX, to customize the output sent to a browser. This
customization is ignored with a regular 3270 data stream generation. These
macros are discussed further in 5.3.2, “Customizing the generated HTML output”
on page 57.
Note: The source for our assembler program and JCL used to define and load the
VSAM file is listed in Appendix A, “Listings” on page 69.
When you generate HTML templates from BMS maps, templates can be larger
than 32k. If this is the case, they cannot be used by the 3270 Web bridge. This
problem is not apparent until a transaction using the map is run using the 3270
bridge. When this happens, message DFHWB0133 is issued and 500 Internal
Server Error is displayed on the browser.
The following example shows the generated HTML for the VSAMSET mapset:
<!doctype html public "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>CICS Web Support BMS screen emulation</title>
<meta name="generator" content="CICS Transaction Server/1.1.1">
<script language="JavaScript">
<!--
function dfhsetcursor(n)
{for (var i=0;i<document.VSAMMAP.elements.length;i++)
{if (document.VSAMMAP.elements[i].name == n)
{document.VSAMMAP.elements[i].focus();
document.VSAMMAP.DFH_CURSOR.value=n;
break}}}
function dfhinqcursor(n)
{document.VSAMMAP.DFH_CURSOR.value=n}
// -->
</script>
</td>
</tr>
<tr>
<td colspan=6 >
</td>
<td colspan=5 nowrap>
VSAM TEST MAP
</td>
</tr>
<tr>
<td colspan=6 >
</td>
<td colspan=5 nowrap>
=============
</td>
</tr>
<tr>
<td colspan=5 >
</td>
<td colspan=6 nowrap>
R READ
</td>
</tr>
<tr>
<td colspan=5 >
</td>
<td colspan=6 nowrap>
U READ FOR UPDATE + REWRITE
</td>
</tr>
<tr>
<td colspan=5 >
</td>
<td colspan=6 nowrap>
A ADD
</td>
</tr>
<tr>
<td colspan=5 >
</td>
<td colspan=6 nowrap>
</td>
<td colspan=6 nowrap>
L LONG BROWSE
</td>
</tr>
<tr>
<td colspan=2 >
</td>
<td colspan=2 nowrap>
FUNCTION
</td>
<td colspan=7 nowrap>
<input type="text" name="FUNC" value="&FUNC;"
onFocus="dfhinqcursor('FUNC')"
size="1" maxlength="1">
</td>
</tr>
<tr>
<td colspan=2 >
</td>
<td colspan=2 nowrap>
RECORDKEY
</td>
<td colspan=7 nowrap>
<input type="text" name="KEY" value="&KEY;"
onFocus="dfhinqcursor('KEY')"
size="6" maxlength="6">
</td>
</tr>
<tr>
<td colspan=2 >
</td>
<td colspan=2 nowrap>
RECORDDATA
</td>
<td colspan=7 nowrap>
<input type="text" name="RECORD" value="&RECORD;"
onFocus="dfhinqcursor('RECORD')"
size="80" maxlength="80">
MACRO
DFHMSX
DFHMDX MAPSET=*,MAP=*, *
BGCOLOR=YELLOW, *
TEXT=BLUE, *
RESET=NO
MEND
When CICS creates the templates for each of your BMS map definitions, it
invokes the DFHMSX customizing macro. Each DFHMDX macro is processed in
sequence, and if applicable, the parameter values are stored. Where a duplicate
parameter is specified for a particular map or mapset, the new value replaces the
previous value for that map or mapset. The first invocation of DFHMDX sets
defaults for the values to be applied to subsequent invocations of DFHMDX by
specifying an asterisk (*) for the mapset name and map name.
5.3.2.2 DFHWBOUT
The DFHWBOUT macro is used to add text to the HTML page generated from a
BMS map only if PARM=TEMPLATE. You can:
• Add Web browser control functions; for example, JavaScript functions, to the
HTML page
• Add text that appears only on the HTML page, but is not part of the BMS map
• Add HTML header information to the HTML page
If the macro is used before the first occurrence of DFHMDF in a macro, the text is
placed in the <head> section of the HTML page. If the macro is used elsewhere
in the map, the text is placed inline in the HTML page, immediately following the
text generated by the preceding DFHMDF macro. Figure 26 shows how the
DFHWBOUT macro is defined.
DFHWBOUT
>>-----DFHWBOUT---’---text ---’----( , SOSI = no / yes )-------------------><
text = The text that is to be inserted into the HTML page.
SOSI = Whether the text contains DBCS characters delimited by shift-out
(X’0E’) and shift-in (X’0F’). The default is SOSI = NO.
For more details about the new BMS macros, see CICS Transaction Server for
VSE/ESA Internet Guide Release 1, SC34-5765.
The first way is to use a converter program where the encode function
customizes the output after the 3270 conversion.
The second way is to use header and footer templates. These templates are
described by an RDO DOCTEMPLATE definition and they are copied in front of,
and appended after, the converted screen, as shown in Figure 27 on page 60.
3270 Display
</pre>
Footer template
You supply one or more of the following templates, whose names are defined in
the TEMPLATENAME fields of DOCTEMPLATE definitions:
• tranHEAD is a template that is inserted at the head of the HTML page being
output for transaction tran, if it is installed.
• CICSHEAD is a template that is inserted at the head of the HTML page being
output for transactions that do not have a corresponding tran HEAD template
installed.
• tranFOOT is a template that is inserted at the foot of the HTML page being
output for transaction tran, if it is installed.
• CICSFOOT is a template that is inserted at the foot of the HTML page being
output for transactions that do not have a corresponding tran FOOT template
installed.
Two sample 3270 bridge exit programs that use the CICS Web Support are
supplied with CICS:
• DFH0CBRE is a bridge exit program supplied in COBOL source that uses
CICS temporary storage (TS) or transient data (TD) queues to pass input and
output from and to the user application (another CICS application). This exit
can be modified. DFH0CBRE is the most general of the supplied exits. To run
a transaction using this exit, you simply issue the following command:
START TRANSID() BRDATA() BREXIT(DFH0CBRE)
OBJECT CHARACTERISTICS
CEDA View TRANSaction( VSAM )
TRANSaction : VSAM
Group : FILEA
DEscription :
PROGram : VSAMTEST
TWasize : 00000 0-32767
PROFile : DFHCICST
PArtitionset :
STAtus : Enabled Enabled | Disabled
PRIMedsize : 00000 0-65520
TASKDATALoc : Below Below | Any
TASKDATAKey : User User | Cics
STOrageclear : No No | Yes
RUnaway : System System | 0 |500-2700000
SHutdown : Disabled Disabled | Enabled
Brexit :
REMOTE ATTRIBUTES
+ DYnamic : No No | Yes
Figure 29. The RDO DEFINE panel for TRANSACTION resource definition
If nothing is entered for BREXIT, the default bridge exit name DFHWBLT is used.
You must ensure that the LOCAL CBRF terminal is defined for default bridge
facility, otherwise you will get a ABRJ abend or even a DFHTF0002 system dump
error code 1715. For example:
DFHTF0002 DBDCCICS A severe error (code X’1715’) has occurred in module DFHTFRF
This terminal is defined in RDO groups DFHTERM and VSETERM. Please do not delete.
Additional information on the supplied bridge exits, and how to write your own, is
documented in the following publications:
• CICS Transaction Server for VSE/ESA Internet Guide Release 1, SC34-5765
• CICS Transaction Server for VSE/ESA CICS External Interface Guide Release
1, SC33-1669
The answers to these questions depend on the type of data being accessed, and
on individual company standards. We feel that in this environment, more security
is better than less. With this in mind, we chose to use this section to point you in
the right direction. The ultimate selections are yours. This is an overview of the
non-SSL facilities available.
To use the security analyzer program, you must specify its name as the Analyzer
Program name in the CICS TS RDO definition TCPIPSERVICE. Multiple
TCPIPSERVICE definitions may be used to allow access through multiple ports.
Each port may have different security criteria established allowing and denying
service.
The security analyzer detects the input and calls the security converter,
DFH$WBSC, again. DFH$WBSC ensures that DFH$WBSN is called.
DFH$WBSN extracts the user ID and password and issues a EXEC CICS
VERIFY PASSWORD command to validate the user ID. The encode function of
DFH$WBSC builds the HTTP response and adds a redirection to it, specifying the
original URL. The browser receives the redirected URL and sends a request for
the original program. Through all of this, the state management program has
maintained a token which must be carried as a query string through the
remainder of the conversation for it to execute under the desired user ID.
For additional information about how to manage this type of access, refer to CICS
Transaction Server for VSE/ESA Internet Guide Release 1, SC34-5765.
These sample programs show how to use the HTTP basic authentication. The
first time the browser attempts to access CICS TS, it prompts for a user ID and
password, which will be encoded, but not encrypted, for transmission. This user
ID and password will be supplied with every request and must be validated by
CICS TS for every HTTP request. The second and subsequent requests are not
sent as prompts to the user at the browser.
DFH$WBAU decodes the user ID and password and issues an EXEC CICS
VERIFY PASSWORD command. If the user ID/password combination is not valid,
or there is no HTTP Authorization header, then an HTTP 401 response is sent
back to the browser, and the result is that the user is prompted for a password. If
the user ID/password combination is valid, the alias transaction that runs the
application program will run under this user ID.
To use this method, DFH$WBSB must be named as the analyzer in your CICS TS
TCPIPSERVICE definition.
In this case, the user ID and password are not encrypted, but are encoded using
a commonly known translation algorithm. The decode algorithm can be found in
the sources of both sample authentication programs.
In addition to the CWS programs, you may also employ a CICS TS security
package or VSE/ESA security package to assist in securing your data.
TCP/IP for VSE/ESA offers a sample security exit that can be found in
PRD1.BASE called SECEXIT.A. This program offers the possibility to establish
your own security exit to allow or deny access to your VSE/ESA system based on
the hardware or IP address. You may also modify the code to check for valid user
IDs and passwords. FTP access to POWER queues can be restricted by
TCP/IP for VSE/ESA also provides a function called basic security. This is done
by specifying SET SECURITY=ON in the IPINITXX.L startup member and the DEFINE
USER,ID=XXXX,PASSWORD=XXXXX. This forces the clients to log on with a valid user ID
and password before they can use the TCP/IP functions. You may also want to
use the SET SECURITY_ARP and SET SECURITY_IP commands to provide
further security.
When using the HTTP server, the parameter SECURE=YES is available for your
use. Review the TCP/IP manuals for the appropriate use of this security feature.
Another parameter, CONFINE=YES, may be used to limit sublibrary access to the
sublibrary specified by the ROOT parameter. In addition, the HTTP server
executes in read-only mode.
TCP/IP for VSE/ESA provides a wealth of functionality. It also provides the ability
to force sign-ons, limit access, limit searches, restrict FTP, and more.
However, you now have more to consider. Discussing performance issues are not
a primary goal of this redbook. It is important, however, to understand the
possible performance issues related to CWS.
Summary
In summary, there is a multitude of performance issues to be concerned with.
However, proper planning in advance of implementation will minimize these
issues. Once you have implemented CWS, monitoring ensures that you can take
appropriate steps in advance of a growing workload.
For more information about performance hints and tips, visit the VSE/ESA home
page at the following address. There you can find many performance-related
articles and sources of information:
http://www.ibm.com/vse
To print the auxiliary trace data set, DFHTU410 is used. The trace can be printed
in abbreviated and full format. A detailed description of the parameters can also
be found in CICS Transaction Server for VSE/ESA Operations and Utilities Guide,
Release 1, SC33-1654.
or
CEDX tranid,OFF
Note: For COMMAREA programs, use CWBA for the tranid. For 3270-based
programs, use xxxx, where xxxx is your tranid.
CICS TS intercepts the transaction specified on the CEDX tranid command, and
displays the EDF diagnostic panels at the terminal on which the EDF command is
issued.
CEDX provides the same function and diagnostic display panels as CEDF, and
the basic rules for CEDF also apply to CEDX.
<<..+....1....+....2....+....3....+....4....+....5....+.. MEM=DFHSITC2>>.
TITLE 'DFHSITC2 -- SIT FOR CICS TS - APPLID PRODCICS'
PUNCH ' CATALOG DFHSITC2.OBJ REP=YES'
DFHSIT TYPE=CSECT, *
AIEXIT=IESZATDX, AUTO INSTALL TERMINALS *
AILDELAY=200, AUTO INSTALL DEL TERM PQ03810*
AIQMAX=100, AUTO INSTALL CONC TERMINALS *
AIRDELAY=700, AUTO INSTALL ELAPS TIME *
AKPFREQ=200, ACTIVITY KEYPOINTING FREQUENCY *
APPLID=PRODCICS, <=== CICS APPLICATION NAME *
AUXTR=OFF, AUXTRACE OFF *
BMS=FULL, FULL BASIC MAPPING SUPPORT *
CLSDSTP=NOTIFY, *
CMDPROT=YES, VALIDATE START ADDRESSES *
CMDSEC=ASIS, CMDSEC WILL BE HONORED *
CONFDATA=SHOW, SHOW USER DATA IN TRACE *
CONFTXT=NO, VTAM SHOW USER DATA *
CSDACC=READWRITE, CSD MAY BE UPDATED *
CSDLSRNO=1, CSD LOCAL SHARED RESOURCE *
CSDSTRNO=4, CSD SIMULTANEOUS ACCESS *
DATFORM=MMDDYY, EXTERNAL DATE DISPLAY *
DBP=1$, DYN. BACKOUT (NO LOCAL DLI I/F)*
DBUFSZ=2000, DYN. ADJUSTED BY CICS *
DCT=C2, FOR SECOND CICS *
DFLTUSER=CICSUSER, DEFAULT USER *
DISMACP=YES, ASRD ABEND IN CASE MACROS I/F *
DLI=NO, NO DL/I SUPPORT *
DOCCODEPAGE=037, <===== CODE PAGE *
DSALIM=5M, UPPER LIMIT OF STORAGE BELOW *
DUMP=YES, IDUMP IN ABEND SITUATIONS *
DUMPDS=AUTO, AUTO SWITCH DUMP DATA SETS *
DUMPSW=NEXT, USERS MAY NOT USE DUMPSW S
EDSALIM=25M, DSA ABOVE THE LINE ENV. B *
FCT=NO, FOR SECOND CICS *
GMTEXT='VSE/ESA CICS/TS', GMM MSG TEXT *
GMTRAN=IEGM, LOGON TRANSACTION ID *
GNTRAN=IEGT, TIME OUT TRANSACTION *
GRPLIST=(VSELST2,MYLST2), <==AUTOINST, TERMS, & MRO *
ICP=COLD, INTERVAL CONTROL PGM *
ICV=1000, INTERVAL CONTROL EXIT TIME-MS *
ICVR=20000, RUNAWAY TASK TIME *
ICVTSD=200, TERMINAL SCAN DELAY *
INTTR=ON, INTERNAL TRACE *
IRCSTRT=NO, START IRC DURING INITIALIZATION*
ISC=YES, INTERSYSTEM COMMUNICATION *
JCT=NO, NO JOURNALLING *
LEVSE=YES, <======== SUPPORT LE ON THIS CICS *
LGNMSG=YES, VTAM LOGON DATA *
MCT=NO, NO MONITOR CONTROL TABLE *
MN=OFF, MONITORING OFF *
MNCONV=NO, NO MONITORING OF CONVERSATIONAL*
MNEXC=OFF, MONITORING EXCEPTION CLASS *
MNFREQ=0, MONITORING FREQUENCY *
MNPER=OFF, MONITORING PERFORMANCE CLASS *
MNSYNC=NO, MONITORING SYNCPOINT *
MNTIME=LOCAL, MONITORING TIME GMT *
MROBTCH=1, MRO BATCHING EVENTS *
MROLRM=YES, MRO LONG RUNNING MIRROR TASK *
MSGLVL=1, MESSAGES ON BOTH SYSLST/SYSLOG *
MXT=50, MAX NO. OF ALL CONCURRENT TASKS*
SYSID=CIC1 APPLID=DBDCCICS
RESULTS: 1 TO 8 OF 8 TIME: 18.45.38 DATE: 00.255
SYSID=CIC1 APPLID=DBDCCICS
Appendix A. Listings 71
A.2.2 Listing of RDO TCPIPSERVICE
SYSID=CIC1 APPLID=DBDCCICS
* *
* Define the constants *
* *
*------------------------------------------*
SET IPADDR = N.NN.NN.NN <---------
SET MASK = 255.255.255.000
*
SET ALL_BOUND = 30000
SET WINDOW = 4096
SET TRANSFER_BUFFERS = 20
SET TELNETD_BUFFERS = 20
SET RETRANSMIT = 100
SET DISPATCH_TIME = 30
SET REDISPATCH = 10
*
SET SECURITY = ON
SET ADDITIONAL_WINDOW = 70000
SET PING_MESSAGE = ON
SET MAX_SEGMENT = 32684
*
GATEWAY ON
*------------------------------------------*
* *
* Wait for VTAM Startup *
* *
*------------------------------------------*
WAIT VTAM
*------------------------------------------*
* *
* Define the Communication Links *
* *
*------------------------------------------*
*
DEFINE LINK,ID=VM_TCPIP,TYPE=CTCA,DEV=C22,MTU=1500, - <---------
HOSTNAME=MYVMVSE,HOSTAPPL=TCPIP
*
*------------------------------------------*
* *
* Define Routine Information *
* *
*------------------------------------------*
DEFINE ROUTE,ID=VMESA,LINKID=VM_TCPIP,IPADDR=0.0.0.0, - <---------
GATEWAY=N.NN.NN.NN
*------------------------------------------*
* *
* Define Names *
* *
*------------------------------------------*
Appendix A. Listings 73
DEFINE NAME,NAME=MYVMVSE,IPADDR=N.NN.NN.NN <---------
DEFINE NAME,NAME=GREG,IPADDR=N.NN.NN.NN
DEFINE NAME,NAME=HANS,IPADDR=N.NN.NN.NN
DEFINE NAME,NAME=BENN,IPADDR=N.NN.NN.NN
DEFINE NAME,NAME=KENN,IPADDR=N.NN.NN.NN
*------------------------------------------*
* *
* Define Name Server Support *
* *
*------------------------------------------*
SET DNS1=N.NN.NN.NN <---------
*------------------------------------------*
* *
* Define HTTPD *
* *
*------------------------------------------*
DEFINE HTTPD,ID=HTTP1,ROOT='DFHHTML.DFHDOC',SECURE=NO,CONFINE=NO
*------------------------------------------*
* *
* Define Telnet Daemons *
* *
*------------------------------------------*
DEFINE TELNETD,ID=LU,TERMNAME=TELNLU,TARGET=DBDCCICS,PORT=23,COUNT=2
*------------------------------------------*
* *
* Define FTP Daemons *
* *
*------------------------------------------*
DEFINE FTPD,ID=FTP,PORT=21,COUNT=2
*------------------------------------------*
* *
* Automated Line Printer Client *
* *
*------------------------------------------*
DEFINE EVENT,ID=LST_LISTEN,TYPE=POWER,CLASS=X,QUEUE=LST,ACTION=LPR
*------------------------------------------*
* *
* Setup the File System *
* *
*------------------------------------------*
DEFINE FILESYS,LOCATION=SYSTEM,TYPE=PERM
*
DEFINE FILE,PUBLIC='IJSYSRS',DLBL=IJSYSRS,TYPE=LIBRARY
DEFINE FILE,PUBLIC='PRD1',DLBL=PRD1,TYPE=LIBRARY
DEFINE FILE,PUBLIC='PRD2',DLBL=PRD2,TYPE=LIBRARY
DEFINE FILE,PUBLIC='DFHHTML',DLBL=DFHHTML,TYPE=LIBRARY
DEFINE FILE,PUBLIC='POWER',DLBL=IJQFILE,TYPE=POWER
Appendix A. Listings 75
CATALOG DEMO.HTML REPLACE=YES
<html>
<head>
<title>ESA250 - CICS Web Support on VSE/ESA</title>
</head>
<body>
<h1>ESA250 - Running CICS Web Support on VSE/ESA</h1>
<p><hr>
<p>
Press
<a href="http://n.nn.nn.nnn:1080/cics/cwba/DFH$WB1A">
DFH$WB1A</a>
to see the CICS Web Support sample application in action.
<p>
What is actually passed to the Web Browser and thus to CICS
Transaction Server for VSE/ESA is:
"http://n.nn.nn.nnn:1080/cics/cwba/DFH$WB1A"
<hr>
<p>
Press
<a href="http://n.nn.nn.nnn:1080/cics/cwba/EXTRCT1">
EXTRCT1</a>
to see the CICS Web Support running an application that will
call the EXEC CICS EXTRACT command to determine exactly what CICS
environment the program is executing in.
<p>
What is actually passed to the Web Browser and thus to CICS
Transaction Server for VSE/ESA is:
"http://n.nn.nn.nnn:1080/cics/cwba/EXTRCT1"
<hr>
<p>
This page updated 11th September 2000.
</body>
</html>
/+
Appendix A. Listings 77
CATALOG EXTRCTH3.HTML REPLACE=YES
<html>
<head>
<title>EXTRACT - CICS Web Support on VSE/ESA</title>
</head>
<body background="/DFHWBIMG/background1.gif">
<img alt="" src="/DFHWBIMG/masthead.gif">
<h1>EXTRACT - Running CICS Web Support on VSE/ESA</h1>
<p>with a masthead and a background
<p><hr>
/+
Appendix A. Listings 79
EXEC CICS ADDRESS COMMAREA(R8)
* analyse function
EXEC CICS WEB READ FORMFIELD(TEXTURE) NAMELENGTH(L'TEXTURE) *
VALUE(FUNCTION) VALUELENGTH(FUNCTIOL) NOHANDLE
* analyse key
EXEC CICS WEB READ FORMFIELD(KEY) NAMELENGTH(L'KEY) *
VALUE(VSAMKEY) VALUELENGTH(VSAMKEYL) NOHANDLE
CLI FUNCTION,C'R' IF FUNCTION IS READ
BE READ
CLI FUNCTION,C'U' IF FUNCTION IS UPDATE
BE SENDHTML (UPDATE DISABLED)
CLI FUNCTION,C'A' IF FUNCTION IS ADD
BE SENDHTML (ADD DISABLED)
CLI FUNCTION,C'D' IF FUNCTION IS DELETE
BE SENDHTML (DELETE DISABLED)
CLI FUNCTION,C'B' IF FUNCTION IS BROWSE
BE BROWSE
CLI FUNCTION,C'L' IF FUNCTION IS LONG BROWSE (10 RECORDS)
BE BROWSE10
* Create document with header template
SENDHTML EXEC CICS DOCUMENT CREATE DOCTOKEN(DOCTOKEN) *
TEMPLATE('VSAMHEAD')
* Insert key
EXEC CICS DOCUMENT SET SYMBOL('KEY') VALUE(MOVEKEY) *
DOCTOKEN(DOCTOKEN) LENGTH(VSAMKEYL)
* Insert data
EXEC CICS DOCUMENT SET SYMBOL('RECORD') VALUE(MOVEDATA) *
DOCTOKEN(DOCTOKEN) LENGTH(ADDRECL)
* Insert body template
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEMPLATE('VSAMBODY')
* Insert footer template
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEMPLATE('VSAMFOOT')
* Send complete document
EXEC CICS WEB SEND DOCTOKEN(DOCTOKEN) *
CLNTCODEPAGE('iso-8859-1')
B RETURN
READ EQU *
EXEC CICS READ DATASET('FILEA') RIDFLD(VSAMKEY) *
INTO(VSAMAREA)
MVC MOVEKEY(6),VSAMKEY
MVC MOVEDATA(73),VSAMAREA+7
B SENDHTML
UPDATE DS 0H DO READ/UPDATE OF RECORD
EXEC CICS READ DATASET('FILEA') RIDFLD(VSAMKEY) *
INTO(VSAMAREA) UPDATE
MVC MOVEKEY(6),VSAMKEY
MVC MOVEDATA(73),VSAMAREA+7
B SENDHTML
REWRITE DS 0H DO ONE REWRITE OF UPDATED RECORD
EXEC CICS REWRITE DATASET('FILEA') FROM(VSAMAREA)
B RETURN
ADD DS 0H ADD ONE RECORD TO THE FILE
EXEC CICS WEB READ FORMFIELD(RECORD) NAMELENGTH(L'RECORD) *
VALUE(ADDREC) VALUELENGTH(ADDRECL) NOHANDLE
MVC VSAMAREA+1(6),VSAMKEY
MVC VSAMAREA+7(73),ADDREC
EXEC CICS WRITE DATASET('FILEA') RIDFLD(VSAMKEY) *
FROM(VSAMAREA)
B SENDHTML
DELETE DS 0H DELETE ONE RECORD FROM THE FILE
EXEC CICS READ DATASET('FILEA') RIDFLD(VSAMKEY) X
INTO(VSAMAREA) UPDATE
EXEC CICS DELETE DATASET('FILEA')
B SENDHTML
BROWSE DS 0H
EXEC CICS STARTBR DATASET('FILEA') RIDFLD(VSAMKEY)
EXEC CICS READNEXT DATASET('FILEA') INTO(VSAMAREA) X
RIDFLD(VSAMKEY)
EXEC CICS ENDBR DATASET('FILEA')
MVC MOVEKEY(6),VSAMKEY
MVC MOVEDATA(73),VSAMAREA+7
B SENDHTML
BROWSE10 DS 0H DO 'LIMIT / 10' CYCLES OF ...
MVC KEYB,VSAMKEY ... STARTBR, 10 READNEXTS, ENDBR
EXEC CICS STARTBR DATASET('FILEA') RIDFLD(KEYB)
LA 8,10 LOAD LOOP COUNTER ...
_______________________________________________________________
_______________________________________________________________
Appendix A. Listings 81
_______________________________________________________________
DFHEISTG DSECT
DOCTOKEN DS CL16
CLNTNAML DS F
CLNTNAME DS CL80
SRVRNAML DS F
SRVRNAME DS CL80
CLNTADRL DS F
CLNTADDR DS CL15
DS 0F
SERVADRL DS F
SERVADDR DS CL15
DS 0F
SSLTYPE DS F
TCPIPSER DS CL8
PRTNUMB DS CL5
DS 0F
EXTRCT1 CSECT
EXTRCT1 AMODE 31 55200000
EXTRCT1 RMODE ANY 56000000
EXEC CICS HANDLE CONDITION INVREQ(DOCINSRT)
EXEC CICS DOCUMENT CREATE DOCTOKEN(DOCTOKEN) *
TEMPLATE('EXTRCTH1')
*
MVC CLNTNAML,=F'80'
MVC SRVRNAML,=F'80'
MVC CLNTADRL,=F'15'
MVC SERVADRL,=F'15'
* Retrieve some TCPIP related information
EXEC CICS EXTRACT TCPIP *
SERVERNAME(SRVRNAME) SNAMELENGTH(SRVRNAML)
EXEC CICS EXTRACT TCPIP *
SERVERADDR(SERVADDR) SADDRLENGTH(SERVADRL)
EXEC CICS EXTRACT TCPIP *
TCPIPSERVICE(TCPIPSER)
EXEC CICS EXTRACT TCPIP *
PORTNUMBER(PRTNUMB)
EXEC CICS EXTRACT TCPIP *
CLIENTADDR(CLNTADDR) CADDRLENGTH(CLNTADRL)
EXEC CICS EXTRACT TCPIP *
CLIENTNAME(CLNTNAME) CNAMELENGTH(CLNTNAML)
* Insert client name
DOCINSRT EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTINFO) LENGTH(CLNTINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTNAME) LENGTH(CLNTNAML)
* Insert client address
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(ADDRINFO) LENGTH(ADDRINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTADDR) LENGTH(CLNTADRL)
* Insert server name
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SRVRINFO) LENGTH(SRVRINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SRVRNAME) LENGTH(SRVRNAML)
* Insert server address
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SDDRINFO) LENGTH(SDDRINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SERVADDR) LENGTH(SERVADRL)
* Insert TCPIPSERVICE being used
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TCPSINFO) LENGTH(TCPSINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TCPIPSER) LENGTH(L'TCPIPSER)
Appendix A. Listings 83
* Insert Port number being used
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(PORTINFO) LENGTH(PORTINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(PRTNUMB) LENGTH(L'PRTNUMB)
* Insert footer for document
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEMPLATE('EXTRCTF1')
* Send complete document
EXEC CICS WEB SEND DOCTOKEN(DOCTOKEN) *
CLNTCODEPAGE('iso-8859-1')
EXEC CICS RETURN
CLNTINFO DC C'<p>Client Name : '
CLNTINFL DC F'17'
SRVRINFO DC C'<p>Server Name : '
SRVRINFL DC F'17'
ADDRINFO DC C'<p>Client Address : '
ADDRINFL DC F'20'
SDDRINFO DC C'<p>Server Address : '
SDDRINFL DC F'20'
TCPSINFO DC C'<p>TCPIPSERVICE name: '
TCPSINFL DC F'22'
PORTINFO DC C' - on Port Number: '
PORTINFL DC F'19'
END EXTRCT1
/*
DFHEISTG DSECT
DOCTOKEN DS CL16
CLNTNAML DS F
CLNTNAME DS CL80
SRVRNAML DS F
SRVRNAME DS CL80
CLNTADRL DS F
CLNTADDR DS CL15
DS 0F
SERVADRL DS F
SERVADDR DS CL15
DS 0F
SSLTYPE DS F
TCPIPSER DS CL8
PRTNUMB DS CL5
DS 0F
EXTRCT2 CSECT
EXTRCT2 AMODE 31 55200000
EXTRCT2 RMODE ANY 56000000
EXEC CICS HANDLE CONDITION INVREQ(DOCINSRT)
EXEC CICS DOCUMENT CREATE DOCTOKEN(DOCTOKEN) *
TEMPLATE('EXTRCTH2')
*
MVC CLNTNAML,=F'80'
MVC SRVRNAML,=F'80'
MVC CLNTADRL,=F'15'
MVC SERVADRL,=F'15'
*
Appendix A. Listings 85
DFHEISTG DSECT
DOCTOKEN DS CL16
CLNTNAML DS F
CLNTNAME DS CL80
SRVRNAML DS F
SRVRNAME DS CL80
CLNTADRL DS F
CLNTADDR DS CL15
DS 0F
SERVADRL DS F
SERVADDR DS CL15
DS 0F
SSLTYPE DS F
TCPIPSER DS CL8
PRTNUMB DS CL5
DS 0F
EXTRCT3 CSECT
EXTRCT3 AMODE 31 55200000
EXTRCT3 RMODE ANY 56000000
EXEC CICS HANDLE CONDITION INVREQ(DOCINSRT)
EXEC CICS DOCUMENT CREATE DOCTOKEN(DOCTOKEN) *
TEMPLATE('EXTRCTH3')
*
MVC CLNTNAML,=F'80'
MVC SRVRNAML,=F'80'
MVC CLNTADRL,=F'15'
MVC SERVADRL,=F'15'
* Retrieve some TCPIP related information
EXEC CICS EXTRACT TCPIP *
SERVERNAME(SRVRNAME) SNAMELENGTH(SRVRNAML)
EXEC CICS EXTRACT TCPIP *
SERVERADDR(SERVADDR) SADDRLENGTH(SERVADRL)
EXEC CICS EXTRACT TCPIP *
TCPIPSERVICE(TCPIPSER)
EXEC CICS EXTRACT TCPIP *
PORTNUMBER(PRTNUMB)
EXEC CICS EXTRACT TCPIP *
CLIENTADDR(CLNTADDR) CADDRLENGTH(CLNTADRL)
EXEC CICS EXTRACT TCPIP *
CLIENTNAME(CLNTNAME) CNAMELENGTH(CLNTNAML)
* Insert client name
DOCINSRT EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTINFO) LENGTH(CLNTINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTNAME) LENGTH(CLNTNAML)
* Insert client address
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(ADDRINFO) LENGTH(ADDRINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTADDR) LENGTH(CLNTADRL)
* Insert server name
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SRVRINFO) LENGTH(SRVRINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SRVRNAME) LENGTH(SRVRNAML)
* Insert server address
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SDDRINFO) LENGTH(SDDRINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(SERVADDR) LENGTH(SERVADRL)
* Insert TCPIPSERVICE being used
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TCPSINFO) LENGTH(TCPSINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TCPIPSER) LENGTH(L'TCPIPSER)
DFHEISTG DSECT
DOCTOKEN DS CL16
CLNTNAML DS F
CLNTNAME DS CL80
SRVRNAML DS F
SRVRNAME DS CL80
CLNTADRL DS F
CLNTADDR DS CL15
DS 0F
SERVADRL DS F
SERVADDR DS CL15
DS 0F
SSLTYPE DS F
TCPIPSER DS CL8
PRTNUMB DS CL5
DS 0F
TEXT ds CL1
TEXTL DS F
EXTRCT4 CSECT
EXTRCT4 AMODE 31 55200000
EXTRCT4 RMODE ANY 56000000
EXEC CICS HANDLE CONDITION INVREQ(DOCINSRT)
EXEC CICS DOCUMENT CREATE DOCTOKEN(DOCTOKEN) *
TEMPLATE('EXTRCTH4')
*
MVC CLNTNAML,=F'80'
MVC SRVRNAML,=F'80'
MVC CLNTADRL,=F'15'
MVC SERVADRL,=F'15'
MVC TEXTL,=F'1'
Appendix A. Listings 87
* Retrieve some TCPIP related information
EXEC CICS EXTRACT TCPIP *
SERVERNAME(SRVRNAME) SNAMELENGTH(SRVRNAML)
EXEC CICS EXTRACT TCPIP *
SERVERADDR(SERVADDR) SADDRLENGTH(SERVADRL)
EXEC CICS EXTRACT TCPIP *
TCPIPSERVICE(TCPIPSER)
EXEC CICS EXTRACT TCPIP *
PORTNUMBER(PRTNUMB)
EXEC CICS EXTRACT TCPIP *
CLIENTADDR(CLNTADDR) CADDRLENGTH(CLNTADRL)
EXEC CICS EXTRACT TCPIP *
CLIENTNAME(CLNTNAME) CNAMELENGTH(CLNTNAML)
* analyse input.
DOCINSRT EXEC CICS WEB READ FORMFIELD(TEXTURE) NAMELENGTH(L'TEXTURE) *
VALUE(TEXT) VALUELENGTH(TEXTL) NOHANDLE
CLI TEXT,C'1'
BE TEXT1
CLI TEXT,C'2'
BE TEXT2
CLI TEXT,C'3'
BE TEXT3
CLI TEXT,C'4'
BE TEXT4
CLI TEXT,C'5'
BE TEXT5
CLI TEXT,C'6'
BE TEXT6
B ENDBODY
TEXT1 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TEXT1NFO) LENGTH(TEXT1NFL)
B ENDBODY
TEXT2 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TEXT2NFO) LENGTH(TEXT2NFL)
B ENDBODY
TEXT3 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TEXT3NFO) LENGTH(TEXT3NFL)
B ENDBODY
TEXT4 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TEXT4NFO) LENGTH(TEXT4NFL)
B ENDBODY
TEXT5 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TEXT5NFO) LENGTH(TEXT5NFL)
B ENDBODY
TEXT6 EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(TEXT6NFO) LENGTH(TEXT6NFL)
B ENDBODY
* Close Body
ENDBODY EQU *
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(BODYINFO) LENGTH(BODYINFL)
* Insert image name
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(IMAGINFO) LENGTH(IMAGINFL)
* Insert header
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(HEADER) LENGTH(HEADERL)
* Insert client name
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTINFO) LENGTH(CLNTINFL)
EXEC CICS DOCUMENT INSERT DOCTOKEN(DOCTOKEN) *
TEXT(CLNTNAME) LENGTH(CLNTNAML)
Appendix A. Listings 89
A.4.4 Catalog jobs
* $$ JOB JNM=&JOBNAME,DISP=D,CLASS=A,NTFY=YES
* $$ LST DISP=D,CLASS=Q,PRI=3
* $$ PUN DISP=I,DEST=*,PRI=9,CLASS=A
// JOB &JOBNAME TRANSLATE PROGRAM &PROGNAME
// ASSGN SYSIPT,SYSRDR
// EXEC IESINSRT
$ $$ LST DISP=D,CLASS=Q,PRI=3
// JOB &JOBNAME COMPILE PROGRAM &PROGNAME
// SETPARM CATALOG=&CATALOG
// IF CATALOG = 1 THEN
// GOTO CAT
// OPTION ERRS,SXREF,SYM,LIST,NODECK
// GOTO ENDCAT
/. CAT
// LIBDEF PHASE,CATALOG=DFHHTML.DFHDOC
// OPTION ERRS,SXREF,SYM,CATAL,NODECK
PHASE &PROGNAME,*
INCLUDE DFHEAI
/. ENDCAT
// EXEC ASMA90,SIZE=(ASMA90,64K),PARM='EXIT(LIBEXIT(EDECKXIT)),SIZE(MAXC
-200K,ABOVE)'
* $$ END
// ON $CANCEL OR $ABEND GOTO ENDJ2
// OPTION NOLIST,NODUMP,DECK
// EXEC DFHEAP1$,SIZE=512K
*ASM XOPTS(CICS)
* $$ SLI ICCF=(&PROGNAME,&PASSWORD),LIB=(&LIBNO)
/*
/. ENDJ2
// EXEC IESINSRT
/*
// IF CATALOG NE 1 OR $MRC GT 4 THEN
// GOTO NOLNK
// EXEC LNKEDT,SIZE=256K
/. NOLNK
#&
$ $$ EOJ
* $$ END
/&
* $$ EOJ
Figure 57. Sample job to compile, link and catalog CICS assembler programs
* $$ JOB JNM=CATMEMB,DISP=D,CLASS=0
// JOB CATMEMB CATALOG MEMBER INTO AF-LIBRARY
// EXEC LIBR,PARM='MSHP'
ACCESS S=DFHHTML.DFHDOC
* $$ SLI ICCF=(xxxxx),LIB=(xx)
/*
/&
* $$ EOJ
Figure 58. Sample job to catalog the HTML documents into sublib DFHHTML.DFHDOC
Figure 59. IDCAMS definitions for user VSAM file to test 3270 bridge
Appendix A. Listings 91
// JOB FILEALOA LOAD FILE FILEA WITH RECORDS FOR TESTING 3270 BRIDGE
// DLBL FILEA,'CICSTS11.SAMPLE.FILEA',,VSAM, X
CAT=VSESPUC
// EXEC IDCAMS,SIZE=AUTO
REPRO INFILE -
(SYSIPT -
ENVIRONMENT -
(BLOCKSIZE(80) -
RECORDFORMAT(FIXUNB) -
RECORDSIZE(80))) -
OUTFILE(FILEA)
000100W. DAVIS SURREY, ENGLAND 3215677826 11 81$0100.11Y
000102F. ALDSON WARWICK, ENGLAND 9835618326 11 81$1111.11Y
000104S. BOWLER LONDON,ENGLAND 1284629326 11 81$0999.99Y
000106B. ADAMS CROYDON, ENGLAND 1948567326 11 81$0087.71Y
000111GENE BARLOWE SARATOGA,CALIFORNIA 4612075301 02 74$0111.11Y
000762GEORGE BURROW SAN JOSE,CALIFORNIA 2231212101 06 74$0000.00Y
000983H. L. L. CALL WASHINGTON, DC 3451212021 04 75$9999.99Y
001222J.R.REYNOLDS BOBLINGEN, GERMANY 7031555110 04 73$3349.99Y
001781HAROLD JAMES SINDELFINGEN,GERMANY7031999021 06 77$0009.99Y
003214HUBERT C HERBERT SUNNYVALE, CAL. 3411212000 06 73$0009.99N
003890PHILIPPE SMITH, JR NICE, FRANCE 0000000028 05 74$0009.99N
004004STAN SMITH DUBLIN, IRELAND 7111212102 11 73$1259.99N
004445DANIEL O'GALWAY SOUTH BEND, S.DAK. 6121212010 10 73$0009.99N
004878D.C. CURRENT SUNNYVALE, CALIF. 3221212010 06 73$5399.99N
005005J. S. LAVERENCE SAN FRANCISCO, CA. 0000000101 08 73$0009.99N
005444JEAN LAWRENCE SARATOGA, CALIF. 6771212020 10 74$0809.99N
005581JOHN ALDEN III BOSTON, MASS. 4131212011 04 74$0259.99N
006016DR W. T. KAR NEW DELHI, INDIA 7033121121 05 74$0009.88Y
006670WILLIAM KAPP NEW YORK, N.Y. 2121212031 01 75$3509.88N
006968D. CONRAD WARWICK, ENGLAND 5671382126 11 81$0009.88Y
007007BRIGITTE EICRN STUTTGART, GERMANY 7031100010 10 75$5009.88N
007248B. C. WILLIAMSON REDWOOD CITY, CALF. 3331212111 10 75$0009.88N
007779MRS. W. WELCH SAN JOSE, CALIF. 4151212003 01 75$0009.88Y
100000G. NEADS TORONTO, ONTARIO 0341512126 11 81$0010.00Y
111111C. MEARS OTTAWA, ONTARIO 5121200326 11 81$0011.00Y
200000A. BONFIELD GLASGOW, SCOTLAND 6373829026 11 81$0020.00Y
222222J. WIEBERS FRANKFURT, GERMANY 2003415126 11 81$0022.00Y
300000K. TRENCHARD NEW YORK, U.S. 6473980126 11 81$0030.00Y
333333D. MYRING CARDIFF, WALES 7849302026 11 81$0033.00Y
400000W. TANNER MILAN, ITALY 2536373826 11 81$0040.00Y
444444A. FISHER CALGARY, ALBERTA 7788982026 11 81$0044.00Y
500000J. DENFORD MADRID, SPAIN 4445464026 11 81$0000.00Y
555555C. JARDINE KINGSTON, N.Y. 3994442026 11 81$0005.00Y
600000F. HUGHES DUBLIN, IRELAND 1239878026 11 81$0010.00Y
666666A. BROOKMAN LA HULPE, BRUSSELS 4298384026 11 81$0016.00Y
700000A. MACALLA DALLAS, TEXAS 5798432026 11 81$0002.00Y
777777D. PRYKE WILLIAMSBURG, VIRG. 9187613126 11 81$0027.00Y
800000H. BRISTOW WESTEND, LONDON 2423338926 11 81$0030.00Y
888888B. HOWARD NORTHAMPTON, ENG. 2369163926 11 81$0038.00Y
900000D. WOODSON TAMPA, FLA. 3566812026 11 81$0040.00Y
999999R. JACKSON RALEIGH, N.Y. 8459163926 11 81$0049.00Y
/*
Figure 60. IDCAMS repro job to load VSAM file for testing 3270 bridge facility
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* VSAMTEST -- PROGRAM FOR VSAMTEST TEST SUITE. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
PRINT GEN
***********************************************************************
DFHEISTG DSECT
COPY VSAMSET
STARTCLK DS D
STOPCLK DS D
WORK DS D
VSAMDATA DS CL80 I/O AREA FOR VSAMDATA-DATASET
SCRATCH DS CL80 SCRATCH INPUT AREA USED FOR UPDATE
***********************************************************************
* PROGRAM START *
***********************************************************************
PRINT NOGEN
VSAMTEST CSECT
B MVC
DC CL8'VSAMTEST'
MVC DS 0H
STCK STARTCLK RECORD START TIME
EXEC CICS HANDLE CONDITION NOTFND(NOTFOUND)
EXEC CICS HANDLE CONDITION DSIDERR(DSIDERR)
EXEC CICS HANDLE CONDITION EOC(REWRITE)
EXEC CICS HANDLE CONDITION ERROR(ERROR)
EXEC CICS HANDLE CONDITION MAPFAIL(MAPFAIL)
RECEIVE DS 0H
EXEC CICS RECEIVE MAP('VSAMMAP') MAPSET('VSAMSET')
MVC RESPONSI(29),BLANK
OI FUNCI,C' ' OR A BLANK TO FORCE UPPERCASE
CLI FUNCI,C'A' IF FUNCTION IS NOT ADD, CLEAR INPUT
BE NOBLANK
MVC RECORDI(244),BLANK
NOBLANK DS 0H
CLI FUNCI,C'R' IF FUNCTION IS READ
BE READ
CLI FUNCI,C'U' IF FUNCTION IS UPDATE
BE UPDATE
CLI FUNCI,C'A' IF FUNCTION IS ADD
BE ADD
CLI FUNCI,C'D' IF FUNCTION IS DELETE
BE DELETE
CLI FUNCI,C'B' IF FUNCTION IS BROWSE
BE BROWSE
CLI FUNCI,C'L' IF FUNCTION IS LONG BROWSE (10 RECORDS)
BE BROWSE10
CLI FUNCI,C'E' IF FUNCTION IS END BROWSE
BE ENDBR
B INVINPUT OTHERWISE, SAY INVALID INPUT
MAPFAIL DS 0H SEND BLANK MAP ON FIRST TIME ENTRY
EXEC CICS SEND MAP('VSAMMAP') MAPSET('VSAMSET') MAPONLY WAIT X
FREEKB
B RETURN
READ DS 0H DO READ OF SPECIFIED RECORD
EXEC CICS READ DATASET('FILEA') RIDFLD(KEYI) X
INTO(VSAMDATA)
MVC KEYI(6),VSAMDATA+1
MVC RECORDI(73),VSAMDATA+7
B SENDNORM WHEN FINISHED, SEND NORMAL RESPONSE
UPDATE DS 0H DO READ/UPDATE OF RECORD
EXEC CICS READ DATASET('FILEA') RIDFLD(KEYI) X
INTO(VSAMDATA) UPDATE
MVC KEYI(6),VSAMDATA+1
MVC RECORDI(73),VSAMDATA+7
MVC RESPONSO,AENDERN
EXEC CICS SEND MAP('VSAMMAP') MAPSET('VSAMSET') X
FREEKB
EXEC CICS RECEIVE MAP('VSAMMAP') MAPSET('VSAMSET')
MVC VSAMDATA+1(6),KEYI
MVC VSAMDATA+7(74),RECORDI
REWRITE DS 0H DO ONE REWRITE OF UPDATED RECORD
EXEC CICS REWRITE DATASET('FILEA') FROM(VSAMDATA)
B SENDNORM WHEN FINISHED, SEND NORMAL RESPONSE
SENDNORM DS 0H SEND NORMAL RESPONSE
MVC RESPONSO,NORMRESP
Appendix A. Listings 93
EXEC CICS READ DATASET('FILEA') RIDFLD(KEYI) X
INTO(VSAMDATA)
MVC KEYI(6),VSAMDATA+1
MVC RECORDI(73),VSAMDATA+7
B SENDNORM WHEN FINISHED, SEND NORMAL RESPONSE
UPDATE DS 0H DO READ/UPDATE OF RECORD
EXEC CICS READ DATASET('FILEA') RIDFLD(KEYI) X
INTO(VSAMDATA) UPDATE
MVC KEYI(6),VSAMDATA+1
MVC RECORDI(73),VSAMDATA+7
MVC RESPONSO,AENDERN
EXEC CICS SEND MAP('VSAMMAP') MAPSET('VSAMSET') X
FREEKB
EXEC CICS RECEIVE MAP('VSAMMAP') MAPSET('VSAMSET')
MVC VSAMDATA+1(6),KEYI
MVC VSAMDATA+7(74),RECORDI
REWRITE DS 0H DO ONE REWRITE OF UPDATED RECORD
EXEC CICS REWRITE DATASET('FILEA') FROM(VSAMDATA)
B SENDNORM WHEN FINISHED, SEND NORMAL RESPONSE
SENDNORM DS 0H SEND NORMAL RESPONSE
MVC RESPONSO,NORMRESP
SENDANY DS 0H SEND RESPONSE ALREADY SET IN MAP
MVC FUNCOUTO,FUNCI
MVC TERMOUTO,EIBTRMID
STCK STOPCLK RECORD STOP TIME
* NOTE: THE FOLLOWING CONVERSION DEPENDS ON ELAPSED TIME FROM
* START TO STOP BEING NOT LONGER THAN 2147 SECONDS (2**31 MICROSEC.)
* THIS IS ABOUT 35 MINUTES...
LM 0,1,STOPCLK GET STOP TIME
SRDL 0,12 SHIFT UNITS TO MICROSECONDS
LM 8,9,STARTCLK GET START TIME
SRDL 8,12 SHIFT UNITS TO MICROSECONDS
SR 1,9 STOP - START IN MICROSECONDS
CVD 1,WORK CONVERT TO DECIMAL
MVC TIMEOUTO,TIMEMASK
ED TIMEOUTO,WORK+3 EDIT TO PRETTY
EXEC CICS SEND MAP('VSAMMAP') MAPSET('VSAMSET') DATAONLY X
FREEKB WAIT
RETURN DS 0H DONE -- RETURN TO CICS
EXEC CICS RETURN
ADD DS 0H ADD ONE RECORD TO THE FILE
MVC VSAMDATA+1(6),KEYI
MVC VSAMDATA+7(74),RECORDI
EXEC CICS WRITE DATASET('FILEA') RIDFLD(KEYI) X
FROM(VSAMDATA)
B SENDNORM SEND NORMAL RESPONSE
DELETE DS 0H DELETE ONE RECORD FROM THE FILE
EXEC CICS READ DATASET('FILEA') RIDFLD(KEYI) X
INTO(VSAMDATA) UPDATE
EXEC CICS DELETE DATASET('FILEA')
MVCBLANK DS 0H
MVC RECORDI(244),BLANK
B SENDNORM SEND NORMAL RESPONSE
BROWSE DS 0H
EXEC CICS STARTBR DATASET('FILEA') RIDFLD(KEYI)
EXEC CICS READNEXT DATASET('FILEA') INTO(VSAMDATA) X
RIDFLD(KEYI)
EXEC CICS ENDBR DATASET('FILEA')
MVC KEYI(6),VSAMDATA+1
MVC RECORDI(73),VSAMDATA+7
MVC VSAMDATA+7(73),BLANK
B SENDNORM SEND NORMAL RESPONSE
BROWSE10 DS 0H DO 'LIMIT / 10' CYCLES OF ...
MVC KEYB,KEYI ... STARTBR, 10 READNEXTS, ENDBR
BROWSE11 DS 0H
MVC KEYB,KEYI
EXEC CICS STARTBR DATASET('FILEA') RIDFLD(KEYB)
LA 8,10 LOAD LOOP COUNTER ...
BROWSE12 DS 0H ... 10 READNEXTS PER CYCLE
EXEC CICS READNEXT DATASET('FILEA') INTO(VSAMDATA) X
RIDFLD(KEYB)
* MVC KEYI(6),VSAMDATA+1
Figure 62. Source listing for program VSAMTEST for testing 3270 bridge (Part 2 of 4)
Figure 63. Source listing for program VSAMTEST for testing 3270 bridge (Part 3 of 4)
Appendix A. Listings 95
ZERO DC PL6'0' PACKED ZERO
ONE DC PL6'1' PACKED ONE
TEN DC PL6'10' PACKED TEN
KEYB DS CL6 FIELD FOR L10 BROWSE
SPACE 2
END VSAMTEST
/*
Figure 64. Source listing for program VSAMTEST for testing 3270 bridge (Part 4 of 4)
We defined both the RDO definitions for file FILEA and transaction VSAM in
Group FILEA.
DI G(FILEA)
ENTER COMMANDS
NAME TYPE GROUP DATE TIME
FILEA FILE FILEA 00.250 15.57.16
VSAM TRANSACTION FILEA 00.250 16.09.11
Figure 66. RDO file definition for our test VSAM file FILEA
Appendix A. Listings 97
OBJECT CHARACTERISTICS CICS R
CEDA View TRANSaction( VSAM )
TRANSaction : VSAM
Group : FILEA
DEscription :
PROGram : VSAMTEST
TWasize : 00000 0-32767
PROFile : DFHCICST
PArtitionset :
STAtus : Enabled Enabled | Disabled
PRIMedsize : 00000 0-65520
TASKDATALoc : Below Below | Any
TASKDATAKey : User User | Cics
STOrageclear : No No | Yes
RUnaway : System System | 0 | 500-2700000
SHutdown : Disabled Disabled | Enabled
Brexit :
REMOTE ATTRIBUTES
+ DYnamic : No No | Yes
CEDA View TRANSaction( VSAM )
+ REMOTESystem :
REMOTEName :
TRProf :
Localq : No | Yes
SCHEDULING
PRIOrity : 001 0-255
TClass : No No | 1-10
TRANClass : DFHTCL00
ALIASES
Alias :
TASKReq :
XTRanid :
TPName :
:
XTPname :
:
+ :
+ RECOVERY
DTimout : No No | 1-6800
Indoubt : Backout Backout | Commit | Wait
RESTart : No No | Yes
SPurge : No No | Yes
TPUrge : No No | Yes
DUmp : Yes Yes | No
TRACe : Yes Yes | No
COnfdata : No No | Yes
SECURITY
RESSec : No No | Yes
CMdsec : No No | Yes
Extsec : No No | Yes
TRANSec : 01 1-64
RSl : 00 0-24 | Public
+ COnfdata : No No | Yes
SECURITY
RESSec : No No | Yes
CMdsec : No No | Yes
Extsec : No No | Yes
TRANSec : 01 1-64
RSl : 00 0-24 | Public
Figure 67. RDO transaction definition for our test transaction VSAM
* $$ JOB JNM=DFHCNV,CLASS=0,DISP=D
// JOB DFHCNV CONVERSION TABLE FOR CICS CLIENT CONNECTIONS
// LIBDEF *,CATALOG=PRD2.CONFIG
// OPTION CATAL,NOXREF,LOG
* THIS DFHCNV INCLUDES THE DEFINITION FOR CICS WEB SUPPORT
* DFHWBHH IS FOR CONVERTING HPPT HEADER DATA.
* DFHWBUD IS FOR CONVERTING HPPT USER DATA.
// EXEC ASSEMBLY,SIZE=2000K
PRINT NOGEN
DFHCNV TYPE=INITIAL
DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=DFHWBHH, *
CLINTCP=8859-1,SRVERCP=037,USREXIT=NO
DFHCNV TYPE=SELECT,OPTION=DEFAULT
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=32767, *
LAST=YES
DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=DFHWBUD, *
CLINTCP=8859-1,SRVERCP=037,USREXIT=NO
DFHCNV TYPE=SELECT,OPTION=DEFAULT
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=32767, *
LAST=YES
DFHCNV TYPE=FINAL
END
/*
// EXEC LNKEDT
/*
/&
* $$ EOJ
***** END OF FILE *****
Appendix A. Listings 99
L R5,WBEP_RESPONSE_PTR no <body> tag found
L R6,WBEP_RESPONSE_LEN add length to pointer and
AR R5,R6 start adding from there
*
* We are going to scan through the COMMAREA that we received and
* append all meaningfull information that we find in there to
* HTTP response.
*
ADDOWN EQU *
MVC 0(MYHEADL,R5),MYHEAD move our header
LA R5,MYHEADL(,R5) adjust pointer
LA R6,MYHEADL(,R6) adjust length
CLC WBEP_ERROR_CODE,=H'0' received an error code ?
BE ABENDCOD no, go check abend code
*
* For the moment there are 43 wbep error codes provided in DFHWBUCD.
* We test on the numeric value of the error code and write the
* corresponding text as given in DFHWBUCD.
*
MVC 0(17,R5),=C'WBEP_ERROR_CODE: ' yes, write field name
LA R5,17(,R5) adjust pointer
LA R6,17(,R6) adjust length
CLC WBEP_ERROR_CODE,=H'1' was it error code 1 ?
BNE ERRCOD2 no, see if it is 2
MVC 0(L'WBERR1,R5),WBERR1 yes, write text
LA R5,L'WBERR1(,R5) adjust pointer
LA R6,L'WBERR1(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD2 EQU *
CLC WBEP_ERROR_CODE,=H'2' was it error code 2 ?
BNE ERRCOD3 no, see if it is 3
MVC 0(L'WBERR2,R5),WBERR2 yes, write text
LA R5,L'WBERR2(,R5) adjust pointer
LA R6,L'WBERR2(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD3 EQU *
CLC WBEP_ERROR_CODE,=H'3' was it error code 3 ?
BNE ERRCOD4 no, see if it is 4
MVC 0(L'WBERR3,R5),WBERR3 yes, write text
LA R5,L'WBERR3(,R5) adjust pointer
LA R6,L'WBERR3(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD4 EQU *
CLC WBEP_ERROR_CODE,=H'4' was it error code 4 ?
BNE ERRCOD5 no, see if it is 5
MVC 0(L'WBERR4,R5),WBERR4 yes, write text
LA R5,L'WBERR4(,R5) adjust pointer
LA R6,L'WBERR4(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD5 EQU *
CLC WBEP_ERROR_CODE,=H'5' was it error code 5 ?
BNE ERRCOD6 no, see if it is 6
MVC 0(L'WBERR5,R5),WBERR5 yes, write text
LA R5,L'WBERR5(,R5) adjust pointer
LA R6,L'WBERR5(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD6 EQU *
CLC WBEP_ERROR_CODE,=H'6' was it error code 6 ?
BNE ERRCOD7 no, see if it is 7
MVC 0(L'WBERR6,R5),WBERR6 yes, write text
LA R5,L'WBERR6(,R5) adjust pointer
LA R6,L'WBERR6(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD7 EQU *
CLC WBEP_ERROR_CODE,=H'7' was it error code 7 ?
BNE ERRCOD8 no, see if it is 8
MVC 0(L'WBERR7,R5),WBERR7 yes, write text
LA R5,L'WBERR7(,R5) adjust pointer
LA R6,L'WBERR7(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD8 EQU *
CLC WBEP_ERROR_CODE,=H'8' was it error code 8 ?
BNE ERRCOD9 no, see if it is 9
MVC 0(L'WBERR8,R5),WBERR8 yes, write text
LA R5,L'WBERR8(,R5) adjust pointer
LA R6,L'WBERR8(,R6) adjust length
B ABENDCOD and test for an abend code
ERRCOD9 EQU *
Information in this book was developed in conjunction with use of the equipment
specified, and is limited in application to those specific hardware and software
products and levels.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact IBM Corporation, Dept.
600A, Mail Drop 1329, Somers, NY 10589 USA.
The information contained in this document has not been submitted to any formal
IBM test and is distributed AS IS. The use of this information or the
implementation of any of these techniques is a customer responsibility and
depends on the customer's ability to evaluate and integrate them into the
customer's operational environment. While each item may have been reviewed by
IBM for accuracy in a specific situation, there is no guarantee that the same or
similar results will be obtained elsewhere. Customers attempting to adapt these
techniques to their own environments do so at their own risk.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of these
Web sites.
C-bus is a trademark of Corollary, Inc. in the United States and/or other countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries licensed
exclusively through The Open Group.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned
by SET Secure Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks
of others.
This information was current at the time of publication, but is continually subject to change. The latest information
may be found at the Redbooks Web site.
Company
Address
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.
D F
FORMFIELD 37
DB2 2
FTP GIF or JPEG 41
debug problems 67
debugging with CEDX 68
Decode function 8, 24, 43
I
inline image 42
insert img tag 37
M
Messages and codes 67
MQSeries 2
O
obtaining graphics 40
P
Page Source 38
port number 32
presentation logic 23
problem determination 67
protocol 32
R
RDO definitions 12
RMODE 28
S
sample programs from your browser 32
screen presented by the browser 28
Secure Socket Layer (SSL) 3, 5
synchronous access 4
T
TASKDATLOC 28
TCP/IP address 32
TCP/IP HTTP deamon 33
TCPIPSERVICE 7, 8, 12, 16
test Web pages 42
traces 67
Review
Questions about IBM’s privacy The following link explains how we protect your personal information.
policy? ibm.com/privacy/yourprivacy/
CICS Transaction
Server for VSE/ESA:
CICS Web Support
e-business connector CICS Web Support (CWS) is a new function in CICS Transaction
Server for VSE/ESA 1.1.1. CWS first became available in OS/390
INTERNATIONAL
solutions for VSE/ESA
with CICS TS 1.2, and was enhanced in Release 1.3. This 1.3 TECHNICAL
functionality was ported to CICS TS for VSE/ESA 1.1.1. SUPPORT
Implementation
guidance for CWS,
ORGANIZATION
including 3270 Bridge CICS Web Support is an effective solution for the VSE/ESA user
community. It is a powerful 2-tier Web enablement solution that
functions
is easy to plan for and simple to implement. Our goal for this IBM
Redbook is to provide you with the information to use this great
CICS Web Support BUILDING TECHNICAL
e-business connector. CWS unites browser technology with INFORMATION BASED ON
samples S/390. This provides tremendous flexibility to the end-user PRACTICAL EXPERIENCE
community while capitalizing on S/390 performance, reliability,
scalability, availability, and data integrity. IBM Redbooks are developed
by the IBM International
This redbook discusses and positions the new CICS TS for Technical Support
VSE/ESA 1.1.1 CICS Web Support (CWS) and 3270 bridge. It Organization. Experts from
IBM, Customers and Partners
provides a broad understanding of the new architecture, together from around the world create
with examples and samples to help customers in their planning timely technical information
and implementation of CWS. CWS employs a unique approach for based on realistic scenarios.
using an e-business connector in the VSE/ESA environment. Specific recommendations
are provided to help you
implement IT solutions more
This redbook also discusses planning for CWS, installation, and effectively in your
customization. It provides the guidance you need to design new environment.
solutions and upgrade existing solutions.