1. technology and computing
2. programming languages

CICS Transaction Server for z/OS
BigCommareas: How to bypass the
32k Commarea restriction in CICS
Transaction Server
Robert Harris,
CICS Technical Strategy,
IBM Hursley.
Issued:
01 March
2003
Revision Date:
01 March
2003
Previous Revision Date:
01 March
2003
Review Date:
As Required
Take Note!
Before using this document be sure to read the general information under "Notices".
First Edition, March 2003.
© Copyright International Business Machines Corporation 2002. All rights reserved. Note to
US Government Users -- Documentation related to restricted rights -- Use, duplication or
disclosure is subject to restrictions set forth in GSA ADP Schedule contract with IBM Corp.
Page ii
Notices:
The following paragraph does not apply in any country where such provisions are inconsistent with local law.
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement
may not apply to you.
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these
available in all countries in which IBM operates.
Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply
that only IBM's program or other product may be used. Any functionally equivalent program that does not infringe
any of the intellectual property rights may be used instead of the IBM product.
Evaluation and verification of operation in conjunction with other products, except those expressly designated by
IBM, is the user's responsibility.
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, 500 Columbus Avenue, Thornwood, New York 10594, USA.
The information contained in this document has not be submitted to any formal IBM test and is distributed AS-IS.
The use of the 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
has 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.
Page iii
Trademarks:
The following are Trademarks of International Business Machines Corporation in the United States, in
other countries, or both:
3090
AFP
Application System/400
AT
C/370
CBPDO
CICS/6000
CICS OS/2
CICS/VSE
COBOL/370
CUA
DFSMS
DFSMSdss
DXT
Enterprise Systems Architecture/390
ESA/390
GDDM
InfoWindow
IMS
MQ
MVS/DFP
MVS/SP
NetView
OS/390
Parallel Sysplex
RACF
RISC System/6000
S/370
SQL/DS
System/38
System/390
VisualAge
WebExplorer
ACF/VTAM
AIX
APPN
BookManager
C/MVS
CICS
CICS/ESA
CICS TS
CICSPlex
COBOL/2
DATABASE 2
DFSMS/MVS
DFSMShsm
eNetwork
ES/3090
ES/9000
HiperBatch
IBM
IMS/ESA
MQSeries
MVS/ESA
MVS/XA
OpenEdition
OS/400
PR/SM
Resource Measurement Facility
RMF
S/390
SP
System/360
SystemView
VSE/ESA
z/OS
AD/Cycle
AnyNet
AS/400
C Set++
CBIPO
CICS/400
CICS/MVS
CICS/VM
CICSPlex SM
Common User Access
DB2
DFSMSdfp
DFSORT
Enterprise Systems Architecture/370
ESA/370
ESCON
Hiperspace
IBMLink
Language Environment
MVS
MVS Parallel Sysplex
Multiprise
OS/2
Processor Resource/Systems Manager
Presentation Manager
RETAIN
RT
SAA
System/36
System/370
Systems Application Architecture
VTAM
UNIX is a registered Trademark in the United States and other countries licensed exclusively through
X/Open Company Limited
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.
INTEL is a registered trademark of Intel Corporation, in the United States, or other countries, or both.
Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, or
other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.
Page iv
Summary of amendments
Date Of Change
Change made to document
01/03/2003
Creation
Reference Material and Bibliography:
This document uses a short reference to the following documentation:
Short reference
Book Title
CICS RDO Book
CICS Resource Definition Guide
SC34-5722
CICS SDG
CICS System Definition Guide
SC34-5725
CICS CG
CICS Customization Guide
SC34-5706
CICS EXT
CICS External Interfaces Guide
SC33-1944
CICS JAVA
Java™ Applications in CICS
SC34-6000-0
CICS APR
CICS Application Programming Reference
SC34-5702
CICS SPR
CICS System Programming Reference
SC34-5726
CICS RG
CICS Transaction Server for z/OS Release Guide
GC34-5983
CICS BTS
CICS Business Transaction Services
SC34-5268
CICS MG
CICS Transaction Server for z/OS Migration Guide
GC34-5984
JVM Book
New IBM Technology featuring Persistent Reusable
Java Virtual Machines
SC34-5881
LDAP Red Book
Understanding LDAP
SG24-4986
Relevant SupportPacs:
CA1J
A MVS BatchPipes stage interface to
CICS using EXCI
Information for Batch deletion of
BigCommareas
CA1L
A WLM-enabled large request handler
for CICS
BTS in a CICSPlex environment
Page v
Preface:
This document is aimed at CICS Application Programmers who need to use Commareas bigger than the
maximum 32k size supported by CICS Transaction Server for OS/390 version 1.3 or CICS Transaction
Server for z/OS version 2.2. It describes a programming technique using CICS’ Business Transaction
Services’ Containers to manipulate and handle data bigger than 32k bytes. This technique is referred to as
BigCommarea processing.
You do not need a detailed knowledge of CICS configuration to get the best out of this document, but are
probably a CICS Systems Programmer, an Application Programmer or a Designer of CICS Applications.
This document is structured in a less formal fashion than the CICS Transaction Server product
documentation. You should always consider the latest official CICS TS publications as being correct in the
cases where this document implies a mismatch.
The information and code in this document is only applicable to CICS Transaction Server for OS/390
version 1.3 and CICS Transaction Server for z/OS version 2.2. It is not applicable to earlier CICS releases.
This document uses Colour to highlight items of interest, so access to the PDF as well as the hard copy in
the absence of a colour print is desirable.
To save space, the abbreviation of XC means EXEC CICS when describing CICS API and SPI commands.
Page vi
Table of Contents
How to use BigCommareas in CICS Transaction Server .....................................................1
Introduction .........................................................................................................................1
Some BTS Concepts ...........................................................................................................2
Units Of Work ..................................................................................................................2
Process ..............................................................................................................................2
Containers .........................................................................................................................2
Process and Container Scope ...........................................................................................2
System Definitions ................................................................................................................3
DFHLRQ ............................................................................................................................3
VSAM Repository Files .....................................................................................................4
Sharing BigCommarea Repository files with a CICSPlex ...............................................5
Sharing BigCommarea Repository file with general BTS access ....................................5
Clearing Repository Files .................................................................................................5
RDO ....................................................................................................................................6
VSAM Repository Files ...................................................................................................6
BTS PROCESSTYPEs .....................................................................................................8
The BigCommarea design .....................................................................................................9
General Overview ...............................................................................................................9
Creating the BigCommarea ................................................................................................9
Process Naming Conventions .........................................................................................10
Container Naming Conventions .....................................................................................10
Accessing the BigCommarea ............................................................................................11
Length Considerations ......................................................................................................12
Writing to the BigCommarea ............................................................................................13
Reading the BigCommarea ...............................................................................................14
Reading and Writing the BigCommarea ...........................................................................15
Releasing the BigCommarea ............................................................................................15
Deleting the BigCommarea ..............................................................................................16
Deleting the Container ...................................................................................................16
Deleting the Process and the Container ..........................................................................16
Passing a BigCommarea around .........................................................................................17
Just like a Commarea? ......................................................................................................17
Acting like a Commarea ...................................................................................................18
Passing the BigCommarea down to the next program ...................................................18
Global Storage ..................................................................................................................20
Storage between a sequence of Transactions ....................................................................20
Items aimed at specific programs .....................................................................................20
Automated Cleanup of Dead BTS Processes ....................................................................21
Scheduling a specific deletion ........................................................................................21
Scheduling a Global Cleanup .........................................................................................22
Using BTS facilities to delete the BTS Process .............................................................23
Investigating the VSAM Repository Files ..........................................................................24
The CBAM Transaction ...................................................................................................24
Running DFHBARUP ......................................................................................................26
Removing Dead Processes from the VSAM Repository file ..............................................29
Getting a list of BTS Processes with AMS and Pipes ......................................................30
Page vii
Selecting the Dead Processes ............................................................................................31
Deleting via EXCI ............................................................................................................32
Sample Assembler program for BigCommarea processing ................................................33
Usage ................................................................................................................................33
Usage examples ..............................................................................................................34
The Code ...........................................................................................................................37
Page viii
List of Figures
DFHLRQ definition .........................................................................................................................3
Repository definition .......................................................................................................................4
RDO Definition for an unique VSAM Repository file....................................................................6
RDO Definition for a shared VSAM Repository file ......................................................................7
PROCESSTYPE RDO definition ....................................................................................................8
Avoiding Length exceptions when reading a BigCommarea ........................................................12
BigCommarea as a flowing Commarea with distinct UnitOfWorks .............................................18
BigCommarea as a flowing Commarea with a single UnitOfWork ..............................................19
Deleting hanging BigCommareas by scheduled Transaction ........................................................21
Deleting hanging BigCommareas via Browsing ...........................................................................22
DFHBARUP JCL to print a BTS Repository file..........................................................................26
DFHBARUP output for an Activity ..............................................................................................27
DFHBARUP output for a Process .................................................................................................28
Getting the Processes from the BTS Repository VSAM file.........................................................30
Deletion of BigCommarea Processes via EXCI and MVS Pipes ..................................................32
Sample Program: Creating the Process and BigCommarea...........................................................45
Sample Program: Reading the BigCommarea ...............................................................................47
Sample Program: Writing the BigCommarea ................................................................................48
Sample Program: Reading and Writing the BigCommarea...........................................................49
Sample Program: BigCommarea Usage via a Link .......................................................................52
Sample Program: BigCommarea Deletion via EXCI ....................................................................54
Sample Program: BigCommarea behavour on a failure ................................................................55
Sample Program: BigCommarea Exit processing .........................................................................56
Page ix
How to use BigCommareas in
CICS Transaction Server
Introduction
This document describes how to bypass the 32k Commarea size limit in
CICS Transaction Server for OS/390 version 1.3 and CICS Transaction Server for z/OS
version 2.2. I call this technique BigCommarea processing.
This approach uses the Container facilities of the Business Transaction
Services (BTS) component of CICS. The documentation for this is in the CICS BTS
manual: you will need to have SC34-5268: CICS Business Transaction Services to hand
whilst reading this document.
I am assuming that you, my reader, are a CICS Application Programmer
or a CICS Application Designer and are familiar with RDO.
Instead of using a Commarea to pass data around, this BigCommarea
design uses a BTS Container. This mechanism also engenders some interesting
designs which remove the program-program association used by Commareas.
I have also included some information about the CICS-supplied tools that
manipulate BTS facilities.
Some sample code is included in this document illustrating the
BigCommarea technique. You can use these code fragments as the basis for your own
code.
How to use BigCommareas in CICS Transaction Server
Page 1 of 63
Some BTS Concepts
You need to read the BTS Book - but do not take too much notice of the
sections dealing with Activities and Events as these are not used by this BigCommarea
design.
Units Of Work
A basic concept for BTS: it is uses a VSAM file (called the Repository).
This means that BTS operations are not hardened until the next UnitOfWork boundary
(set explicitly by the next EXEC CICS SYNCPOINT command) or EndOfTask. This
means that BTS applications have to consider the effect of additional EXEC CICS
SYNCPOINT commands upon other accessed Recoverable Resources.
Process
BTS functionality is associated with a Process. In general CICS use, a
Process' execution proceeds through Activities which are triggered by Events. When a
Process is created, it is inactive, awaiting running of the Initial Activity (formally: the
activation of the Root Activity). When a Process is used for BigCommarea processing,
this Initial Activity is never run and so the Process is dormant throughout its lifetime.
Containers
BTS refers to items called Data Containers, but I'm just going to call them
Containers. Data Containers can be associated with Activities (which are irrelevant to
this design) or Processes (which are crucially used in this BigCommarea design).
Whenever I use the term Container, I really mean 'Data Container at the Process level'.
Containers are hardened by writing their contents to a VSAM File when an
EXEC CICS SYNCPOINT command (or implicit equivalent) is executed.
In this BigCommarea design, the owning Process is just used as an
anchor point for Containers containing more than 32k of data.
Process and Container Scope
The scope of the Process and associated Containers are governed by the
availability of the VSAM Repository file. If this is defined to a single CICS region, the
Process will only exist in that specific region. If the VSAM file is known in many CICS
regions, the Process is visible in all those CICS regions. So a Process can start
executing in one CICS region and continue in another, with information passed around
in Containers.
How to use BigCommareas in CICS Transaction Server
Page 2 of 63
System Definitions
DFHLRQ
You may already have a DFHLRQ file defined for your CICS region. BTS
requests get logged in this file. You should increase its size to cope with the quantity of
BigCommarea processing.
If DFHLRQ does not exist, define it along the lines of Figure 1 and add to
the CICS JCL.
//LRQ
EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//AMSDUMP DD SYSOUT=*
//SYSIN
DD *
DEFINE CLUSTER (
NAME ( RHARRI1.IYCKRAH6.LRQ )
CYL(15 15)
VOLUME(SYSDAV)
CONTROLINTERVALSIZE( 8192 ) BUFFERSPACE ( 11468 )
SHAREOPTIONS( 2 3 )
REUSE
LOG(UNDO)
)
DATA (
NAME( RHARRI1.IYCKRAH6.LRQ.DATA )
KEYS (40 0 )
RECORDSIZE( 400 2048 )
CONTROLINTERVALSIZE( 8192 ) )
INDEX (
NAME ( RHARRI1.IYCKRAH6.LRQ.INDEX )
CONTROLINTERVALSIZE( 4096 ) IMBED
REPLICATE
)
/*
-
-
Figure 1: DFHLRQ definition
You need one of these DFHLRQ files per CICS region that will be using
the BigCommarea design (or BTS in general). This file is not shared between CICS
regions.
System Definitions
Page 3 of 63
VSAM Repository Files
The BTS Repository files are merely VSAM files which are defined to
CICS in the normal way. They should be created with variable length spanned records
(BTS will split things up into manageable chunks). The JCL should look something like
Figure 2 .
//BIGCOMM EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//AMSDUMP DD SYSOUT=*
//SYSIN
DD *
DEFINE CLUSTER (
NAME ( RHARRI1.IYCKRAH6.BIGCOMM )
CYL( 25 25 )
VOLUME( SYSDAV )
KEYS ( 50 0 )
RECORDSIZE( 8192 16384 )
CONTROLINTERVALSIZE( 8192 ) FREESPACE( 5 5 )
SHAREOPTIONS( 2 3 )
REUSE
SPANNED
INDEXED
LOG(UNDO)
)
DATA (
NAME( RHARRI1.IYCKRAH6.BIGCOMM.DATA ) CONTROLINTERVALSIZE( 8192 ) )
INDEX (
NAME ( RHARRI1.IYCKRAH6.BIGCOMM.INDEX ) IMBED
REPLICATE
)
/*
Figure 2: Repository definition
You should define one of these files per CICS region that will be using
BigCommareas - these files should not be shared between CICS regions.
You may want to define another distinct file that is shared between CICS
regions (see “Sharing BigCommarea Repository files with a CICSPlex” on page 5).
It is important that these files are created with sufficient space for the
BigCommareas. Size the file according to the maximum number of BigCommareas
concurrently active and their maximum expected length. It will be an unpleasant
experience to take them offline and increase the space whilst being used by CICS!
System Definitions
Page 4 of 63
Sharing BigCommarea Repository files with a CICSPlex
If your Application (which wants to use BigCommareas) will be executing
across many CICS regions, the VSAM Respository file must be shared between all
these regions. I suggest that you create another VSAM file specifically for sharing
between CICS regions.
Thus, your JCL will contain an unique VSAM file to contain
BigCommareas that are specific to that Region and another VSAM file that is shared
between all CICS regions.
Sharing BigCommarea Repository file with general BTS access
I recommend that you only use a given VSAM Repository file for
BigCommarea usage. If you additionally put 'proper' BTS operational data in this VSAM
file, you will have problems clearing it as you do not know whether or not the BTS
activity has become stuck or is still active.
Clearing Repository Files
A Respository file that is unique to a CICS region should be cleared on a
Cold Start. You could delete and recreate the file or use an utility to empty the file.
A Shared Repository File is more difficult to manage. You can only empty
it when all CICS regions are not using it.
Ensure these Respository Files are created with sufficient space. The last
thing you want to happen is that they fill up and have to be extended whilst CICS is
using them.
You can use operations described in “Deleting via EXCI” on page 32 to
assist in the retirement of dangling processes.
System Definitions
Page 5 of 63
RDO
Before you can use BTS for BigCommarea operations, you have to define
the VSAM Repository files to RDO and create some PROCESSTYPE definitions which
map these VSAM files to a BTS function.
VSAM Repository Files
VSAM Repository files that are unique to a specific CICS region should be
RDO defined as a variable length VSAM file in the usual fashion as shown in Figure 3 .
CEDA View File( BIGCOMM )
File
: BIGCOMM
Group
: RAHBTS
DEScription
: BTS REPOSITORY FOR
VSAM PARAMETERS
DSNAme
: BIGCOMM
Password
:
RLsaccess
: No
LSrpoolid
: 1
READInteg
: Uncommitted
DSNSharing
: Allreqs
STRings
: 010
Nsrgroup
:
REMOTE ATTRIBUTES
REMOTESystem
:
REMOTEName
:
REMOTE AND CFDATATABLE PARAMETERS
RECORDSize
:
Keylength
:
INITIAL STATUS
STAtus
: Enabled
Opentime
: Startup
DIsposition
: Share
BUFFERS
DAtabuffers
: 00011
Indexbuffers
: 00010
DATATABLE PARAMETERS
TABLE
: No
Maxnumrecs
: Nolimit
CFDATATABLE PARAMETERS
Cfdtpool
:
TABLEName
:
UPDATEModel
: Locking
LOad
: No
DATA FORMAT
RECORDFormat
: V
OPERATIONS
Add
: Yes
BRowse
: Yes
DELete
: Yes
READ
: Yes
UPDATE
: Yes
AUTO JOURNALLING
JOurnal
: No
JNLRead
: None
JNLSYNCRead
: No
JNLUpdate
: No
JNLAdd
: None
JNLSYNCWrite
: Yes
RECOVERY PARAMETERS
RECOVery
: None
Fwdrecovlog
: No
BAckuptype
: Static
SECURITY
RESsecnum
: 00
BIG COMMAREAS
PASSWORD NOT SPECIFIED
Yes | No
1-8 | None
Uncommitted | Consistent | Repeatable
Allreqs | Modifyreqs
1-255
1-32767
1-255 (1-16 For CF Datatable)
Enabled | Disabled | Unenabled
Firstref | Startup
Share | Old
2-32767
1-32767
No | CIcs | User | CF
Nolimit | 1-99999999
Contention | Locking
No | Yes
V | F
No | Yes
No | Yes
No | Yes
Yes | No
No | Yes
No | 1-99
None | Updateonly | Readonly | All
No | Yes
No | Yes
None | Before | AFter | ALl
Yes | No
None | Backoutonly | All
No | 1-99
Static | Dynamic
0-24 | Public
Figure 3: RDO Definition for an unique VSAM Repository file
System Definitions
Page 6 of 63
VSAM Repository files that are shared betwen CICS regions (the
BigCommarea will be used within a CICSPlex environment) should be RDO defined as
a variable length VSAM RLS file as shown in Figure 4 .
CEDA View File( BIGCOMMS )
File
: BIGCOMMS
Group
: RAHBTS
DEScription
: BTS REPOSITORY FOR
VSAM PARAMETERS
DSNAme
: BIGCOMMS
Password
:
RLsaccess
: Yes
LSrpoolid
: 1
READInteg
: Uncommitted
DSNSharing
: Allreqs
STRings
: 010
Nsrgroup
:
REMOTE ATTRIBUTES
REMOTESystem
:
REMOTEName
:
REMOTE AND CFDATATABLE PARAMETERS
RECORDSize
:
Keylength
:
INITIAL STATUS
STAtus
: Enabled
Opentime
: Startup
DIsposition
: Share
BUFFERS
DAtabuffers
: 00011
Indexbuffers
: 00010
DATATABLE PARAMETERS
TABLE
: No
Maxnumrecs
: Nolimit
CFDATATABLE PARAMETERS
Cfdtpool
:
TABLEName
:
UPDATEModel
: Locking
LOad
: No
DATA FORMAT
RECORDFormat
: V
OPERATIONS
Add
: Yes
BRowse
: Yes
DELete
: Yes
READ
: Yes
UPDATE
: Yes
AUTO JOURNALLING
JOurnal
: No
JNLRead
: None
JNLSYNCRead
: No
JNLUpdate
: No
JNLAdd
: None
JNLSYNCWrite
: Yes
RECOVERY PARAMETERS
RECOVery
: None
Fwdrecovlog
: No
BAckuptype
: Static
SECURITY
RESsecnum
: 00
BIG COMMAREAS SHARED
PASSWORD NOT SPECIFIED
Yes | No
1-8 | None
Uncommitted | Consistent | Repeatable
Allreqs | Modifyreqs
1-255
1-32767
1-255 (1-16 For CF Datatable)
Enabled | Disabled | Unenabled
Firstref | Startup
Share | Old
2-32767
1-32767
No | CIcs | User | CF
Nolimit | 1-99999999
Contention | Locking
No | Yes
V | F
No | Yes
No | Yes
No | Yes
Yes | No
No | Yes
No | 1-99
None | Updateonly | Readonly | All
No | Yes
No | Yes
None | Before | AFter | ALl
Yes | No
None | Backoutonly | All
No | 1-99
Static | Dynamic
0-24 | Public
Figure 4: RDO Definition for a shared VSAM Repository file
In both cases, I have assumed that 10 Transactions will be accessing the
BTS VSAM repository file concurrently. Thus I have set STRINGS & INDEXBUFFERS to
10 and DATABUFFERS to 11.
You can use all the usual actions to improve performance for these BTS
VSAM repository files.
System Definitions
Page 7 of 63
BTS PROCESSTYPEs
The PROCESSTYPE RDO definition links the BTS VSAM Repository file
to a BTS ProcessType. It also controls auditing options, but these should be ignored in
the BigCommarea design. A given VSAM Repository file can be accessible through
more than one ProcessType.
Figure 5 shows a definition linking up to the BIGCOMM file (where I have
decided that the VSAM Repository file name is to be the same as the ProcessType).
CEDA View PROCesstype( BIGCOMM )
PROCesstype
: BIGCOMM
Group
: RAHBTS
Description
: RAH BTS DEFINITION FOR BIG COMMAREAS
INITIAL STATUS
Status
: Enabled
Enabled | Disabled
DATA SET PARAMETERS
File
: BIGCOMM
AUDIT TRAIL
AUDITLOg
:
AUDITLEvel
: Off
Off | Process | Activity | Full
Figure 5: PROCESSTYPE RDO definition
You have define a PROCESSTYPE for each ProcessType that you use
with the XC BTS API.
In the BigCommarea sample program in this document, I use a fixed name
of BIGCOMM for the ProcessType parameter. I expect that you will usually use fixed
names: one definition for BigCommareas that will only ever be accessed from within the
specific CICS region and another definition for BigCommareas that will be accessed
throughout the CICSPlex.
System Definitions
Page 8 of 63
The BigCommarea design
General Overview
The general idea of this BigCommarea design is to permit
Commarea-equivalents to cope with more than 32k of data. A BTS Container provides
this function.
One creates the named Container at the start of a Transaction and then
passes the name of it (along with the ProcessName and ProcessType) in a Commarea
to where-ever it is required. The Container is subsequently read and written as required
throughout the lifetime of both the current Transaction and any other Transactions (that
know the aforementioned three-part identification). The Container exists until it is
physically deleted (there is no automatic deletion by CICS).
As BTS services rely on the VSAM Repository file, BTS operations are not
hardened until the next UnitOfWork boundary. This is why the BigCommarea design
uses lots of EXEC CICS SYNCPOINT commands.
Creating the BigCommarea
The BigCommarea will usually be created in the first transaction of a
sequence. This involves:
O
Creating a BTS Process
EXEC CICS DEFINE PROCESS
O
Creating a BTS Container
EXEC CICS PUT CONTAINER
O
Ending the UnitOfWork
EXEC CICS SYNCPOINT
as shown in the code fragment on page 45.
The name of the BTS Process consists of a variable ProcessName and a
fixed ProcessType. This ProcessType has to be RDO defined (see “BTS
PROCESSTYPEs” on page 8) and implies the scope of the Process. This scope will
either be local to the current CICS region or visible to all CICS regions in a CICSPlex
(more specifically, those regions which have that ProcessType RDO defined and
associated with a shared VSAM BTS Repository file).
To complete the Process and Container creation, you have to commit the
current CICS UnitOfWork with an EXEC CICS SYNCPOINT command.
The BigCommarea design
Page 9 of 63
Process Naming Conventions
The ProcessName must be unique (within the scope of the associated
VSAM file) and is 36 bytes long. I would suggest using a combination of SYSID,
TRANSID, Task Number (converted to numbers) and some sort of Data/Time stamp.
The sample program in this document uses a STCK value (converted into characters)
as this data/time stamp. You may want to use a YYMMDDHHMMSS format as this
could be used to easily select redundant Processes for deletion (see “Automated
Cleanup of Dead BTS Processes” on page 21 and “Removing Dead Processes from the
VSAM Repository file” on page 29).
The ProcessType will be fixed, and should either be the region specific
name or the shared name (see “BTS PROCESSTYPEs” on page 8).
Container Naming Conventions
If you are only going to use this BigCommarea design in a strict
Commarea-type of fashion, then you will probably want to use a fixed name for the
single BTS Container that you are going to use.
If you are sharing the BTS VSAM file with real BTS operations (which I do
not recommend, see “Sharing BigCommarea Repository file with general BTS access”
on page 5), then you want a name that can easily show that you are using the Container
(and so the associated Process) as a BigCommarea.
Why not call it 'BIGCOMM'?
Other design techniques are possible - see “Passing a BigCommarea
around” on page 17.
The BigCommarea design
Page 10 of 63
Accessing the BigCommarea
Before you can access the BigCommarea you have to know the name of
the BTS Process that owns the BTS Container. You can only access a BTS Container
once you have gained control of the BTS Process that owns the Container.
Consequently, before the BigCommarea can be accessed, the BTS
Process that owns the Container has to be associated with the current CICS
UnitOfWork. I mean UnitOfWork not Transaction - so if the Transaction issues an EXEC
CICS SYNCPOINT command, the Process will again have to be associated with the
(new) UnitOfWork.
This association, and so access to the BigCommarea, lasts until the next
EXEC CICS SYNCPOINT command (or Transaction Abend). Only one UnitOfWork can
have control (use) of the Process - double access is not allowed by CICS.
The Process and, hence, the BigCommarea, exists until some action is
taken to delete it. The BigCommarea, therefore, will survive over a Transaction
boundary.
The command sequence is:
O
Associating the BTS Process
EXEC CICS ACQUIRE PROCESS
O
Accessing the BTS Container
EXEC CICS GET/PUT CONTAINER
O
Ending the UnitOfWork
EXEC CICS SYNCPOINT
as shown in the code fragments on page 47 and page 48.
Access to the BigCommarea is via move-mode (a chunk of storage is
copied to/from the BigCommarea) not locate-mode (access via a Pointer). The initial
EXEC CICS ACQUIRE PROCESS and the final EXEC CICS SYNCPOINT can be in
different modules.
The BigCommarea design
Page 11 of 63
Length Considerations
The EXEC CICS GET CONTAINER command will return a Length error if
the area that is to contain the obtained information is not exactly the same size as the
BigCommarea (too big as well as the normal too small). You may know the size by
design or do not care about the Length Exception. However, in general, you will want to
determine the length of the BigCommarea to avoid this Length exception.
The way to do this is to issue an EXEC CICS GET CONTAINER(name)
ACQPROCESS INTO(s) FLENGTH(v) NOHANDLE with the length variable v set to
zero. This will not cause data to be read from the BigCommarea, but will return its
length in v (you will also get the Length exception which is why the NOHANDLE is
present to ignore this expected error).
Once you have got the length of the BigCommarea you can then get a
correctly sized area via EXEC CICS GETMAIN SET(p) FLENGTH(v) command and
then issue the EXEC CICS GET CONTAINER(name) ACQPROCESS INTO(area
pointed to by p) FLENGTH(v) to read the BigCommarea.
Therefore, if you want to access a BigCommarea in a generic fashion you
should use a design like Figure 6 :
declare l fixed bin(31) ;
declare p pointer(31)
;
declare 1 bc
3 bcdata char(...)
,
;
l = 0 ;
XC GET
CONTAINER() ACQPROCESS INTO(l)
FLENGTH(l) NOHANDLE ;
XC GETMAIN SET(p)
FLENGTH(l)
;
XC GET
CONTAINER() ACQPROCESS INTO(p->bc) FLENGTH(l)
;
Figure 6: Avoiding Length exceptions when reading a BigCommarea
The BigCommarea design
Page 12 of 63
Writing to the BigCommarea
Before the BigCommarea can be accessed, the BTS Process that owns
the Container has to be associated with the current CICS UnitOfWork. After this
association, the Container acting as the BigCommarea can be simply written. An area is
merely copied into the Container. The size of the Container (diminished or increased) is
adjusted to the size of the data.
To harden the data in the Container, an EXEC CICS SYNCPOINT is
issued. If the Transaction abends (or an EXEC CICS SYNCPOINT ROLLBACK issued),
the (new) information will be lost from the Container - and any data that was there
before the Container was written to will still be present.
The command sequence is:
O
Associating the BTS Process
EXEC CICS ACQUIRE PROCESS
O
Writing to the BigCommarea
EXEC CICS PUT CONTAINER
O
Ending the UnitOfWork
EXEC CICS SYNCPOINT
as shown in the code fragment on page 48. The initial EXEC CICS
ACQUIRE PROCESS and the final EXEC CICS SYNCPOINT can be in different modules.
The BigCommarea design
Page 13 of 63
Reading the BigCommarea
Before the BigCommarea can be accessed, the BTS Process that owns
the Container has to be associated with the current CICS UnitOfWork. After this
association, the Container acting as the BigCommarea can be simply read. The
contents of the BigCommarea Container are simply copied to an area related to the
Transaction. Reading the BigCommarea Container does not delete the information in it this is still available.
It is advisable to inquire upon the length of data held in the BigCommarea
before reading it, as Length Exceptions can be generated if there is a mismatch
between the area length and the Container data length (oddly, if the area length is
bigger than the Container data length as well as the more usual Container_
data_will_not_fit_into_the_area error). See “Length Considerations” on page 12 for code
to obtain the length of the BigCommarea.
You would probably want to do this length inquiry anyway in order to get
the data length to be passed into an EXEC CICS GETMAIN FLENGTH() command to
obtain an area for the Containers data.
The command sequence is:
O
Associating the BTS Process
EXEC CICS ACQUIRE PROCESS
O
Getting the length of BTS Container
EXEC CICS GET CONTAINER
(with zero length supplied)
O
Getting the data area
EXEC CICS GETMAIN FLENGTH()
O
Reading the BigCommarea
EXEC CICS GET CONTAINER
O
Ending the UnitOfWork
EXEC CICS SYNCPOINT
as shown in the code fragment on page 47. The EXEC CICS GETMAIN
FLENGTH() is omitted from this fragment for clarity. The initial EXEC CICS ACQUIRE
PROCESS and the final EXEC CICS SYNCPOINT can be in different modules.
The BigCommarea design
Page 14 of 63
Reading and Writing the BigCommarea
As long as you have associated the Process with the current CICS
UnitOfWork, you can read and write the Container without any problems. However, if
you Abend (or issue an EXEC CICS SYNCPOINT ROLLBACK command), the contents
of the BigCommarea Container will be that when the association is made. Any updates
will be lost (all of them, not just the last one).
The command sequence is:
O
Associating the BTS Process
EXEC CICS ACQUIRE PROCESS
O
Getting the length of BTS Container
EXEC CICS GET CONTAINER
(with zero length supplied)
O
Getting the data area
EXEC CICS GETMAIN FLENGTH()
O
Reading the BigCommarea
EXEC CICS GET CONTAINER
O
Writing the BigCommarea
EXEC CICS PUT CONTAINER
O
Ending the UnitOfWork
EXEC CICS SYNCPOINT
as shown in the code fragment on page 49. The EXEC CICS GETMAIN
FLENGTH() is omitted from this fragment for clarity. The initial EXEC CICS ACQUIRE
PROCESS and the final EXEC CICS SYNCPOINT can be in different modules.
Refer to “Length Considerations”
BigCommareas in a generic fashion.
on
page 12
for
accessing
Releasing the BigCommarea
This happens as a side effect on the EXEC CICS SYNCPOINT command.
There is no explicit command to loose access to the BTS Container or the BTS Process.
The BigCommarea design
Page 15 of 63
Deleting the BigCommarea
Deleting the Container
This BigCommarea design does not consider that a deletion of a BTS
Container acting as a BigCommarea is necessary. However, the extended designs (see
“Passing a BigCommarea around” on page 17) could use this technique.
However, in general, if you do want to release resource associated with a
BigCommarea, the most efficient thing to do is just set its length to zero.
Deleting the Process and the Container
The BTS Process which is used as the anchor for the BTS Container
acting as a BigCommarea will never be automatically deleted by CICS. It will stay
around until the relevant BTS Command is issued.
Consequently, you must ensure that somewhere in the application the
BTS Process is deleted. All Abend handling routines should contain this deletion (create
some if they are absent!). See “Scheduling a specific deletion” on page 21 for
information about CICS-related processing to avoid an hanging BigCommarea.
If a BigCommarea (and the associated BTS Process) is left around, the
relevant BTS Repository file (see “Clearing Repository Files” on page 5) will fill up. You
will have to manually clean up the BTS Repository file (see “Deleting via EXCI” on
page 32).
The command sequence is:
O
Associating the BTS Process
EXEC CICS ACQUIRE PROCESS
O
Deleting the Process and Container
EXEC CICS CANCEL ACQPROCESS
O
Ending the UnitOfWork
EXEC CICS SYNCPOINT
as shown in the code fragment on page 56.
The BigCommarea design
Page 16 of 63
Passing a BigCommarea around
Just like a Commarea?
The BigCommarea, being based on the contents of the VSAM BTS
Repository file, does not have the same operational characteristics as a Commarea. In
particular, one is not restricted to:
Q creating in a program at level n
Q reading and writing in the next program at level n+1
Q reading the updates back at level n
As a Commarea is in local transaction-related storage for a program, it is
automatically deleted when control returns to the invoking level.
None of these considerations apply to a BigCommarea:
Q A BigCommarea can be accessed outside of the current transaction
Q A BigCommarea can be accessed at any level in the program stack
Q A BigCommarea is never automatically deleted by CICS
Do not restrict your use of the BigCommarea design to Commarea
characteristics.
When you create your design, remember that a BigCommarea is not
accessed via locate-mode operations (Pointers), but by move-mode operations (via API
into/outof the BTS Container). Recall that the BigCommarea is associated with an
owning BTS Process (see “Containers” on page 2) and that this can have many
associated BTS Containers (see “General Overview” on page 9).
Consequently, you can have many BigCommareas available and
accessible at any time.
However, when constructing your design, the most crucial point is the
association of BigCommarea activity with the current CICS UnitOfWork. This will affect
your treatment of CICS Recoverable Resources. Recall that a UnitOfWork can last over
a program boundary (the same UnitOfWork exists in program A and the XC LINKed to
program B).
Passing a BigCommarea around
Page 17 of 63
Acting like a Commarea
A BigCommarea can be accessed in a Commarea-equivalent fashion.
Passing the BigCommarea down to the next program
You know the name of the program in which the BigCommarea is to be
accessed (which you must know to do the EXEC CICS LINK). Thus, name the
BigCommarea to be that of the program within which it is to be read (at the next level
down the stack).
When you update the BigCommarea and return to the invoking module,
this higher-level module must similarly know its name (as it created it).
In the most specialised case, each program looks after its own
UnitOfWork, so a calling sequence will be akin to Figure 7 .
Prog1
XC
XC
XC
XC
DEFINE PROCESS(P)
PUT CONTAINER(PROG2)
SYNCPOINT
LINK PROGRAM(PROG2)
XC
XC
XC
XC
XC
ACQUIRE PROCESS(P)
GET CONTAINER() FLENGTH(zerovar)
GET CONTAINER(PROG2)
CANCEL ACQPROCESS
SYNCPOINT
Prog2
XC ACQUIRE PROCESS(P)
XC GET CONTAINER() FLENGTH(zerovar)
XC GET CONTAINER(PROG2)
....
XC PUT CONTAINER(PROG2)
XC SYNCPOINT
XC RETURN
Figure 7: BigCommarea as a flowing Commarea with distinct UnitOfWorks
Be aware that, according to “Length Considerations” on page 12,
zerovar is set to zero before issuing the EXEC
CICS
GET
CONTAINER
FLENGTH(zerovar) command to obtain the length of the BigCommarea.
Passing a BigCommarea around
Page 18 of 63
A more common case is where the UnitOfWork covers more than one
program. Figure 8 shows the code required.
Prog2
Prog1
declare L fixed bin(31)
declare P pointer
declare 1 bc
3 bcdat char(n)
declare Somedata char(n)
declare L fixed bin(31)
declare P pointer
declare 1 bc
3 bcdat char(n)
declare Otherdata char(m)
;
;
,
;
;
;
;
,
;
;
XC PUT CONTAINER('PROG2')
FROM(Somedata)
FLENGTH(Length(Somedata))
;
L = 0 ;
XC GET CONTAINER('PROG2')
INTO(L)
FLENGTH(L)
NOHANDLE
XC LINK PROGRAM('PROG2')
;
XC GETMAIN SET(P) FLENGTH(L) ;
XC DEFINE PROCESS('P') ;
L = 0 ;
XC GET CONTAINER('PROG2')
INTO(L)
FLENGTH(L)
NOHANDLE
;
XC GETMAIN SET(P) FLENGTH(L) ;
XC GET CONTAINER('PROG2')
INTO(P->bc)
FLENGTH(L)
;
XC GET CONTAINER('PROG2')
INTO(P->bc)
FLENGTH(L)
;
....
XC PUT CONTAINER('PROG2')
FROM(Otherdata)
FLENGTH(Length(Otherdata)) ;
XC RETURN
;
;
XC CANCEL ACQPROCESS ;
XC SYNCPOINT
;
Figure 8: BigCommarea as a flowing Commarea with a single UnitOfWork
This example shows that the BigCommarea does not exist outside of the
UnitOfWork that created it. This will be a common arrangement for your code. Don’t
forget to include the EXEC CICS CANCEL ACQPROCESS command in the Abend
Handling routine to ensure that things are tidied up on an Abend.
When using EXEC CICS XCTL you are not returning a BigCommarea to
the higher level (as there is no higher level), so you have the possibility of immediately
deleting the Process (EXEC CICS CANCEL ACQPROCESS) if it it not subsequently
needed.
Passing a BigCommarea around
Page 19 of 63
Global Storage
You can use a BigCommarea to hold Global information between CICS
Transactions (things like a last-used stamp or a last-accessed record key). As the
BigCommarea can only be used by a single Transaction (or more precisely, a single
UnitOfWork) you do not have to worry about double access (the classic double update
problem cannot occur).
You do not need to use facilities like Temporary Storage Queues, specific
records in files or a chunk of Global User Exit anchored storage (all of which have to be
protected against double access) to hold persistent information - just use a fixed name
BigCommarea.
Storage between a sequence of Transactions
A BigCommarea can be used to save information between Transaction
Instances. Here, the design challenge is to ensure that the name of the BigCommarea is
known and not improperly used. All the usual techniques are available to pass the name
around (such as hidden fields in BMS maps).
Items aimed at specific programs
Access to a BigCommarea is not restricted to the next program level.
Consequently, a program at, say, level 5 can construct a BigCommarea for use by a
named program somewhen else in the access stack. You do not have to continually
copy bits out of a Commarea into a new one.
Name the BigCommarea to be the program it is to be accessed within.
Take care in deciding where the BigCommarea is to be emptied (if necessary) if it is not
clear where the owning BTS Process is deleted.
Passing a BigCommarea around
Page 20 of 63
Automated Cleanup of Dead BTS Processes
A BTS Process, and thus any associated Containers, is never
automatically deleted by CICS. This means that a BigCommarea can be left hanging in
the Repository VSAM file. Consequently, this VSAM file will fill up or get fragmented to
inhibit performance (or actual activity!).
“Removing Dead Processes from the VSAM Repository file” on page 29
shows how the VSAM file is cleaned up through Batch processing.
However, there are some techniques that you can use within CICS to do
the deletion automatically. These techniques come at a risk of removing information that
is still active.
Scheduling a specific deletion
You can specifically schedule a cleanup transaction whenever you create
the BTS Process (at XC DEFINE PROCESS time). Just pass in the ProcessName and
the ProcessType as the Startdata for an XC STARTed transaction. This transaction is
very simple, as shown in Figure 9 :
XC
XC
XC
XC
XC
RETRIEVE INTO(ProcessName and ProcessType)
ACQUIRE PROCESS(ProcessName) PROCESSTYPE(ProcessType)
CANCEL ACQPROCESS
SYNCPOINT
RETURN
Figure 9: Deleting hanging BigCommareas by scheduled Transaction
The skill is in deciding how long the BigCommarea is to exist before it is
deamed to be hanging. Consequently, you may want to schedule this transaction to
occur at a specific quiet time as an alternative to scheduling it after a longish delay.
Passing a BigCommarea around
Page 21 of 63
Scheduling a Global Cleanup
You can schedule a CICS Transaction (to run at Startup, Shutdown or
some suitable quiet time) which can scan a given BTS Repository file for
BigCommareas and delete those which are deamed to be left hanging.
How you make the decision as to whether or not a given item is deleteable
is upto you. This criteria will undoubtably have an impact of your structuring of the
unique BTS Process names (see “Process Naming Conventions” on page 10).
You must know the ProcessType being used for the BigCommarea
processing, and the tidyup code will look something like Figure 10 :
loop:
k = 0
XC STARTBROWSE PROCESS
PROCESSTYPE(<<name>>) BROWSETOKEN(k)
XC GETNEXT
PROCESS(p) BROWSETOKEN(k) RESP(rc)
XC ENDBROWSE
PROCESS
BROWSETOKEN(k)
if ( rc <> 0 ) then endloop
if (
( p is has a BigCommarea naming Convention )
& ( p should be deleted
) ) then do
XC ACQUIRE PROCESS(p) PROCESSTYPE(<<name>>) ;
XC CANCEL ACQPROCESS
;
XC SYNCPOINT
;
XC DELAY
FOR SECONDS(1)
;
end
end
;
;
;
;
Figure 10: Deleting hanging BigCommareas via Browsing
This code will, undoubtably, look strange to you (it did to me when I
finalised it!). Here are the reasons why:
O
O
O
O
You have to Acquire a Process in order to delete it
You cannot Acquire a Process that is currently being Browsed
A given UnitOfWork can only be associated with a single Process
Some asynchronous work occurs on Process deletion, so you have to
allow a pause for this to complete before obtaining the next Process
Change to the BTS code within CICS may result in a more-standard
browse situation; however, this way works now!
Passing a BigCommarea around
Page 22 of 63
Using BTS facilities to delete the BTS Process
Deletion using BTS facilities is much more complex than the previous
ways of deleting an hanging BigCommarea. You have to be very familar with BTS
Processing (and understand all of the CICS BTS book).
Consequently, I am not going to describe how you can use BTS facilities
to schedule an automatic deletion, because using this functionality takes you firmly into
the full scope of BTS functionality, and so is outside of the scope of this document.
But briefly:
X
X
X
the BTS Process has to become active and contain real
code
you must construct a Timer event and an associated activity
when the Timer event fires, the associated activity should
delete the Process.
Passing a BigCommarea around
Page 23 of 63
Investigating the VSAM Repository Files
The CBAM Transaction
CBAM can be used to display the contents of a VSAM Repository file. The
example displays shown in this section relate to the function of the UTPROGC sample
program.
CBAM initially shows which VSAM files are being used as BTS
Repositories:
Pressing Enter on this Line shows what is in the selected VSAM
Repository File:
The Completion Status should always be Incomplete and the Mode
Initial for BTS Processes being used as BigCommareas (because there are no
Activities associated with the Process which never runs).
Investigating the VSAM Repository Files
Page 24 of 63
Tabbing over to the Conts field and pressing Enter, displays the
Containers associated with the Process (this is where BigCommarea Containers are
indicated):
You can see that my sample program has created the required Container
with its rather obvious name.
If, on the previous panel, one hits Enter on the Process field, you would
get a display showing the BTS Activities associated with the Process:
You should always see that a BigCommarea Process is Incomplete,
awaiting the Initial event to fire (which never happens).
You can examine the Activity by pressing Enter on it:
You can use this display to see what BTS components are associated with
the Activity, but there are none for BigCommarea processing (the Containers are
associated with the Process).
Investigating the VSAM Repository Files
Page 25 of 63
Running DFHBARUP
You can print the contents of a BTS VSAM Repository file using the
DFHBARUP utility. The JCL should be something like Figure 11 :
//PRTBTS
EXEC PGM=DFHBARUP,REGION=0M
//STEPLIB DD DSN=<<CICS>>.SDFHLOAD,DISP=SHR
//BIGCOMM DD DSN=RHARRI1.IYCKRAH6.BIGCOMM,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSIN
DD *
REPOSITORY(BIGCOMM)
/*
Figure 11: DFHBARUP JCL to print a BTS Repository file
The listing will interpret items in VSAM key order. Consequently, you
should first see all Activities that are associated with BigCommarea processing. All
these will be Incomplete and not own Containers or Events (see Figure 12,
‘DFHBARUP output for an Activity,’ on page 27).
Next, all Processes being used as Anchor Points for the BTS Containers
used as BigCommareas will appear (see Figure 13, ‘DFHBARUP output for a Process,’
on page 28). It is at this point that the BigCommareas will appear as BTS Containers.
If the BTS VSAM Repository file being processed is only used for
BigCommarea processing, then you are really only interested in the Process part of the
Listing.
Investigating the VSAM Repository Files
Page 26 of 63
Figure 12: DFHBARUP output for an Activity
Investigating the VSAM Repository Files
Page 27 of 63
000000
C1401A11 C7C2C9C2 D4C9E8C1 4BC9E8C3 E6E3C3F0 F8C51399 CCB00C00
000020
D9D6D6E3 40404040 40404040 40400000 00000000 00004000 000001CC
000040
6EC4C6C8 C2C1C1C3 E3C9E5C9 00000000 00000000 01500001 00000000
000060
C7C3D6D4 D440D9C1 C8F64BD9 C1C8C34B F0F0F0F0 F0F0F5F4 4BC2F8C3
000080
F9F7C3F7 C6C6F4C3 F34B0000 00000000 00000000 00000000 00000000
0000A0
00000000 00000000 00000000 00000000 00000000 00000000 00000000
0000C0
1A11C7C2 C9C2D4C9 E8C14BC9 E8C3E6E3 C3F0F8C5 1399CCB0 0C000101
0000E0
00000000 00000000 00000000 00000000 00000000 00000000 00000000
000100
00000001 00000000 00000000 00000000 00000000 00000000 00000000
000120
00000000 13D617F0 13D617F0 00000000 00000000 13D61800 13D61800
000140
D6C7C340 00000000 00000000 D9C1C8C3 C3C9C3E2 E4E2C5D9 40404040
000160
40404040 40404040 01404040 40404040 40404040 40004040 40404040
000180
00000000 00000000 00000000 00000000 00000000 00000000 00000000
0001A0
00000000 00000000 00000000 00000000 00000000 00000000 00000000
0001C0
00000000 00000000 00000000
Related BTS Objects
Process Type : BIGCOMM Name : RAH6.RAHC.00000054.B8C513997C7FF4C3.
No Parent
No Children
Containers
No Containers
01C4C6C8
01500000
D740C2C9
F5F1F3F9
00000000
00000000
00000000
00000000
00000000
E4E3D7D9
40404040
40400000
00000000
00000000
*A ..GBIBMIYA.IYCWTC08E.r.....DFH*
*ROOT
........ ......&..*
*>DFHBAACTIVI.........&......P BI*
*GCOMM RAH6.RAHC.00000054.B8C5139*
*97C7FF4C3.......................*
*................................*
*..GBIBMIYA.IYCWTC08E.r..........*
*................................*
*................................*
*.....O.0.O.0.........O...O..UTPR*
*OGC ........RAHCCICSUSER
*
*
.
.
..*
*................................*
*................................*
*............
*
Activity Name : DFHROOT
Process : RAH6.RAHC.00000054.B8C513997C7FF4C3. Process Type : BIGCOMM
Activity Id
: ..GBIBMIYA.IYCWTC08E.r.....DFHROOT
Generation : 0000001
11CCCCDCEC4CECEECFFC19CB000CCCDDDE4444444444
A172924981B98363308539C0C0146896630000000000
Definitional Attributes
Program
: UTPROGC
Transid
: RAHC
Userid : CICSUSER
Comp Event :
Current State
Mode
: Initial
(Initial, Active, Dormant, Cancelling, Complete)
Suspended
: No (Yes, No)
Generation : 0000001
Child Count : 0000000
Completion Status
Completion Response : Incomplete
Figure 13: DFHBARUP output for a Process
Investigating the VSAM Repository Files
Page 28 of 63
000000
F1F1F1F1 F1F1F1F1
Process : RAH6.RAHC.00000054.B8C513997C7FF4C3. Process Type : BIGCOMM
Root Id : ..GBIBMIYA.IYCWTC08E.r.....DFHROOT
11CCCCDCEC4CECEECFFC19CB000CCCDDDE4444444444
A172924981B98363308539C0C0146896630000000000
Audit Level : Off (Off, Pro, Act, Full)
Audit Log
:
000000
D740C2C9 C7C3D6D4 D440D9C1 C8F64BD9 C1C8C34B F0F0F0F0 F0F0F5F4
000020
F5F1F3F9 F9F7C3F7 C6C6F4C3 F34B0000 00000000 00004000 00000144
000040
6EC4C6C8 C2C1D7D9 D6C3C5E2 000100A0 00000000 00000000 00000000
000060
C7C2C9C2 D4C9E8C1 4BC9E8C3 E6E3C3F0 F8C51399 CCB00C00 01C4C6C8
000080
40404040 40404040 40400000 00000000 13D61710 00000001 00000038
0000A0
00000000 00000000 00000000 00000000 00000000 13D616B0 13D616B0
0000C0
00000000 13D61910 13D61910 00404040 40404040 40000000 00000000
0000E0
00000000 00000000 00000000 00000000 00000000 00000000 00000000
000100
00000001
Containers
Container Name : COMMAREA
Container Length : x'00000008'
4BC2F8C3
00A00000
C1401A11
D9D6D6E3
00000000
00000000
00000000
00000000
*11111111
*
*P BIGCOMM RAH6.RAHC.00000054.B8C*
*513997C7FF4C3......... .........*
*>DFHBAPROCES................A ..*
*GBIBMIYA.IYCWTC08E.r.....DFHROOT*
*
.......O..............*
*.....................O...O......*
*.....O...O...
...........*
*................................*
*....
*
Removing Dead Processes from the VSAM Repository file
If a Transaction Abends whilst processing BigCommareas, and an Abend
Handling routine has not issued the appropriate EXEC CICS CANCEL ACQPROCESS
command, the BigCommarea will be held in the associated VSAM Repository file for
ever.
This will eventually cause the VSAM file to get fragmented or fill up. Both
of which are bad news. The techniques described in “Automated Cleanup of Dead BTS
Processes” on page 21 may not be sufficient to clean things up, so some Batch
Processing may be required.
You will need to do some manual operations in order to get rid of the dead
processes. Write a little utility program that Acquires the redundant Process and then
Cancels it. A suitable code fragment exists on page 54.
Removing Dead Processes from the VSAM Repository file
Page 29 of 63
Getting a list of BTS Processes with AMS and Pipes
Those of you who are familiar the authors SupportPacs or User Group
Presentations will know that he likes doing things with Rexx or MVS Pipes. You will not
be disappointed as he continues with some suggestions for using these tools!
You can read the BTS Repository file and extract the names of the
Processes - these are records whose key starts with 'P ' (the letter P followed by a
space). After this comes the ProcessType (8 bytes) and the ProcessName (36 bytes)
which is followed by other (irrelevant) information.
The easiest way to get the Record Keys from the BTS VSAM repository
file is to use AMS to print the records. Next, use a MVS Pipe to reformat the relevant
lines so that the ProcessName appears before the ProcessType. Figure 14 shows the
code required.
//DOBTS
EXEC PGM=IDCAMS,REGION=0M
//BIGCOMM DD DSN=RHARRI1.IYCKRAH6.BIGCOMM,DISP=SHR
//SYSPRINT DD DSN=&&TEMP,DISP=(MOD,PASS),
//
UNIT=SYSDA,
//
SPACE=(CYL,(15,15))
//SYSIN
DD *
PRINT IFILE(BIGCOMM) CHARACTER
/*
//RUN1
EXEC PGM=PIPE,
//
PARM='(SEP ; end ? ) < dd=PIPEIN ; join * ;
//
runpipe ; > dd=PIPEPOUT coerce'
//BARUP
DD DSN=&&TEMP,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//PIPEPOUT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132,BLKSIZE=132)
//PIPEOUT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132,BLKSIZE=132)
//SYSTSPRX DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132,BLKSIZE=132)
//PIPEIN
DD *
(SEP ; end ?)
<mvs ddname=BARUP
;
strfind /0KEY OF RECORD - P /
;
specs 20-* 1
;
specs 1-44 1
;
specs 9-44 1 1-8 38
;
pad
45
;
sort unique
;
> dd=PIPEOUT coerce
/*
Figure 14: Getting the Processes from the BTS Repository VSAM file
Removing Dead Processes from the VSAM Repository file
Page 30 of 63
You get output showing the BTS ProcessName and ProcessType in
columns 1-36 (word1) and 38-45 (word2):
....-....1....-....2....-....3....-....4....RAH6.RAHC.00000211.B8CA15B181A5690A. BIGCOMM
RAH6.RAHC.00000214.B8CA15B9B098A5C7. BIGCOMM
RAH6.RAHC.00000215.B8CA15BBD3EB6445. BIGCOMM
RAH6.RAHC.00000216.B8CA15BDB6B585C1. BIGCOMM
RAH6.RAHC.00000217.B8CA15BFF5FF7E80. BIGCOMM
Observe the space padding: you should access fields using column
notation.
Selecting the Dead Processes
Once you have this list of BTS Processes being used as BigCommareas,
you will have to decide which you want to delete. This will be dependant upon how you
are structuring the ProcessNames for BigCommarea processing.
You might just want to cut-and-paste selected names into your deletion
utility.
Removing Dead Processes from the VSAM Repository file
Page 31 of 63
Deleting via EXCI
The authors CA1J SupportPac (available on the CICS Web site at
http://www.ibm.com/software/ts/cics/txppacs/ca1j.html) can be used to drive a CICS
program through EXCI facilities from a MVS Pipe. Consequently, after selection, you
can automatically delete the relevant BTS Processes using the program included in this
document (see page 54) being driven through CA1J.
The JCL and Pipe is shown in Figure 15 :
/DOBTS
EXEC PGM=IDCAMS,REGION=0M
//BIGCOMM DD DSN=RHARRI1.IYCKRAH6.BIGCOMM,DISP=SHR
//SYSPRINT DD DSN=&&TEMP,DISP=(MOD,PASS),
//
UNIT=SYSDA,
//
SPACE=(CYL,(15,15))
//SYSIN
DD *
PRINT IFILE(BIGCOMM) CHARACTER
/*
//RUN2
EXEC PGM=PIPE,
//
PARM='(SEP ; end ? ) < dd=PIPEIN ; join * ;
//
runpipe ; > dd=PIPEPOUT coerce'
//BARUP
DD DSN=&&TEMP,DISP=SHR
//STEPLIB DD DSN=UTL.RHARRI1.LOAD,DISP=SHR,DCB=BLKSIZE=3276
//
DD DSN=RHARRI1.CA1ILOAD,DISP=SHR
//
DD DSN=<<CICS>>.SDFHEXCI,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//PIPEPOUT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132,BLKSIZE=132)
//PIPEOUT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132,BLKSIZE=132)
//SYSTSPRX DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132,BLKSIZE=132)
//PIPEIN
DD *
(SEP ; end ?)
<mvs ddname=BARUP
;
strfind /0KEY OF RECORD - P /
;
specs 20-* 1
;
specs 1-44 1
;
specs 9-44 1 1-8 38
;
pad
45
;
sort unique
;
specs 1-36 1 38-45 37
;
specs X000000070000 1 1-* next
;
ss: RXDPLP (W2) (C1) * *
/ notrace retain abend/;
specs /1->/ 1 1-* next ; > dd=PIPEOUT coerce
?
literal utprogc iyckrah6 ; ss:
;
specs /2->/ 1 1-* next ; > dd=PIPEOUT coerce
?
ss: ;
specs /3->/ 1 1-* next ; > dd=PIPEOUT coerce
/*
Figure 15: Deletion of BigCommarea Processes via EXCI and MVS Pipes
The literal stage controls the flow: UTPROGC is the sample program
included in this document and IYCKRAH6 is the Applid of the authors CICS region
(which has been configured to accept EXCI activity).
Removing Dead Processes from the VSAM Repository file
Page 32 of 63
Sample Assembler program for BigCommarea processing
Usage
To use this sample program, assemble & RDO define it, and associate a
CICS TransId with the program.
The usage is ttttFnnnnnnnnnnnnnnnnn
where:
tttt
is the four Character CICS TransId for the
program
F
is the function code
nnnnnnnnn
I ->
Initialise, create the BTS Process and
Container acting as the BigCommarea
page 45
1 ->
Read the BigCommarea
page 47
2 ->
Write to the BigCommarea
page 48
3 ->
Read and Write the BigCommarea
page 49
4 ->
Access BigCommmarea via a LINK
page 52
A ->
Write BigCommarea and Abend
page 55
E ->
Delete BigCommarea and Exit
page 56
is the ProcessName (which should be cut and
pasted from the I operation)
There is also a code fragment showing BigCommarea deletion via EXCI
(page 54) from a Batch job.
You must create and RDO define a BTS Repository file (see “VSAM
Repository Files” on page 6) and associate it to a RDO PROCESSTYPE of BIGCOMM
(see “BTS PROCESSTYPEs” on page 8) before running this program.
Sample Assembler program for BigCommarea processing
Page 33 of 63
Usage examples
These panels show output from the sample program code fragments:
The BigCommarea is
created by first creating the
owning BTS Process and
then creating the BTS
Process-level Container
(page 45)
The BigCommarea
is read (page 47)
The BigCommarea
is written to, and
the change
committed
(page 48)
Sample Assembler program for BigCommarea processing
Page 34 of 63
This shows normal
access - the
BigCommarea is read
and then written, with
the new contents
hardened (page 49)
The BigCommarea is
accessed from
another level
(page 52)....
...and this updating
from another level
has actually
happened
Sample Assembler program for BigCommarea processing
Page 35 of 63
The BigCommarea
contents are lost if the
UnitOfWork does not
complete (page 55)...
...and this proves it
The BigCommarea is
deleted at the end of
the logical transaction
(page 56)...
...so it cannot be
accessed any
more
Sample Assembler program for BigCommarea processing
Page 36 of 63
The Code
This section contains source of a program which demonstrates usage of
this BigCommarea design. You can use the code fragments as a basis for your own
processing. It is not supported in any way by IBM.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
TITLE 'UTPROGC - Big Commareas'
space 2
===================================================================
=
=
=
UTPROGC - Show how BTS can be used for Big Commareas
=
=
=====================================================
=
=
=
=
=
=
This program contains examples of CICS BTS functions
=
=
that can be used to support usage of Big Commareas.
=
=
=
=
It is very crude, and should only be used as a
=
=
conceptual example of function required.
=
=
=
=
By Big Commareas I mean areas that can be passed between
=
=
CICS Application programs (within a CICSPlex) that are
=
=
bigger than 32k.
=
=
=
=
This function is based on BTS Containers, and these
=
=
last over a UnitOfWork or Transaction boundary.
=
=
=
=
You will need to configure BTS and understand its API
=
=
and operational characteristics as defined in :
=
=
=
=
SC24-5268: CICS Business Transaction Services
=
=
=
=
=
=
The basic idea is that one:
=
=
=
=
* Creates a BTS process (without any Events or)
=
=
(activities
)
=
=
=
=
* Uses this Process to provide an anchor point
=
=
for Containers
=
=
=
=
* Deletes the Process at the relevant point
=
=
=
=
=
=
Initially one creates the process via
=
=
=
=
=
=
* XC CREATE PROCESS
=
=
* XC SYNCPOINT
=
=
=
=
=
=
The Big Commarea (Container) is created via
=
=
=
=
* XC ACQUIRE PROCESS
=
=
* XC PUT CONTAINER
=
=
* XC SYNCPOINT
=
=
=
=
=
=
The Big Commarea (Container) is accessed via
=
=
=
=
* XC ACQUIRE PROCESS
=
=
* XC INQUIRE CONTAINER
=
=
* XC GET CONTAINER
=
=
* XC SYNCPOINT
=
=
=
=
=
=
Finally, one deletes the process via
=
=
=
=
* XC CANCEL PROCESS
=
=
* XC SYNCPOINT
=
=
=
Sample Assembler program for BigCommarea processing
Page 37 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
=
=
=
=
= Register usage
=
= -------------=
=
=
=
R0
->
=
=
R1
->
=
=
R2
-> Commarea
=
=
R3
->
=
=
R4
->
=
=
R5
-> Routine Linkage
=
=
R6
->
=
=
R7
-> Data 1
=
=
R8
-> Base 1
=
=
R9
-> Base 2
=
=
R9
-> Base 2
=
=
R10 -> Parm area
=
=
R11 -> LIFO area
=
=
R12 -> (if needed) TCA
=
=
R13 -> (if needed) CSA
=
=
R14 -> (Main only) Exit address
=
=
R15 -> (Main only) Base, then RC
=
=
=
=
=
=
Copyright and Support
=
=
=====================
=
=
=
=
This program is not supported by any way by IBM. It is
=
=
distributed only to show techniques for CICS usage. It may
=
=
be freely modified and adapted by your installation.
=
=
=
=
=
=
Author:
Robert Harris,
=
=
CICS Technical Strategy,
=
=
IBM Hursley Park,
=
=
England.
=
=
=
=
(C) Copyright IBM UK Limited, 2003.
=
=
=
=
Licensed Materials - Property of IBM
=
=
US Government Users Restricted Rights - Use, duplication or
=
=
disclosure restricted by GSA ADP Schedule Contract with IBM
=
=
Corp.
=
=
=
===================================================================
space 2
eject
space 2
* ===================================================================
* =
=
* =
Registers
=
* =
=
* ===================================================================
space 2
R0
EQU
0
R1
EQU
1
R2
EQU
2
R3
EQU
3
R4
EQU
4
R5
EQU
5
R6
EQU
6
R7
EQU
7
R8
EQU
8
R9
EQU
9
R10
EQU
10
R11
EQU
11
R12
EQU
12
R13
EQU
13
R14
EQU
14
R15
EQU
15
space 2
eject
Sample Assembler program for BigCommarea processing
Page 38 of 63
*
*
*
*
*
*
*
*
*
*
space 2
===================================================================
=
=
=
Standard CICS Areas
=
=
=
===================================================================
space 2
space 2
eject
space 2
===================================================================
=
=
=
Includes
=
=
=
===================================================================
space 2
space 2
eject
space 2
Sample Assembler program for BigCommarea processing
Page 39 of 63
*
*
*
*
*
===================================================================
=
=
=
Map the LIFO
=
=
=
===================================================================
space 2
DFHEISTG DSECT
space 2
RESP
DS
F
General Return Code
RESP2
DS
F
Reason
ACOMM
DS
AL4
Address of Commarea
LCOMM
DS
F
Length of Commarea
STARTBY DS
CL2
How Program got going
STARTPR DS
CL8
Program that called me
CURPROG DS
CL8
Current Program name
space 2
DS
0F
INAREAL DS
H
Area for input processing
INAREAF DS
F
INAREA
DS
CL80
INPROC
DS
CL36
Passed in BTS Process Name
INPROCT DS
CL8
Passed in BTS Process Type
space 2
DS
0D
TIMED
DS
D
STCK Value
space 2
DS
0F
PN
DS
CL36
BTS Process Name
ORG
PN
PN1
DS
CL4
Sysid
PN2
DS
CL1
PN3
DS
CL4
Transid
PN4
DS
CL1
PN5
DS
CL8
Task Number
PN6
DS
CL1
PN7
DS
CL16
STCK
PN8
DS
CL1
ORG
space 2
DS
0F
INCONL
DS
F
Container Length
INCON
DS
CL200
Data
space 2
DS
0F
COMM
DS
XL100
ORG
COMM
Commarea access
COMM1
DS
F
Action
COMM2
DS
H
Line Count
COMM3
DS
CL36
Process Name
COMM4
DS
CL8
Process Type
ORG
space 2
DS
0F
PLINEP
DS
H
Print Lines - Screen Pos
PLINEL
DS
H
Length
PLINE
DS
CL80
Data
DS
0F
Save area
SAYSAVE DS
F
space 2
PH2
DS
XL2
Conversion areas
DS
0F
VALU2TO4 DS
XL4
WORK2TO4 DS
CL8
PACK2TO4 DS
CL16
OUTP2TO4 DS
CL4
PH4
DS
XL4
DS
0F
VALU4TO8 DS
XL4
WORK4TO8 DS
CL8
PACK4TO8 DS
CL16
OUTP4TO8 DS
CL8
DS
0F
VALU4PO8 DS
XL4
WORK4PO8 DS
CL8
PACK4PO8 DS
CL16
OUTP4PO8 DS
CL8
space 1
DS
0D
WTOSAVE DS
XL64
SAVE1
DS
XL64
Save Areas
space 1
eject
Sample Assembler program for BigCommarea processing
Page 40 of 63
space 2
===================================================================
=
=
=
Start of Program CSECT
=
=
=
===================================================================
space 2
UTPROGC DFHEIENT CODEREG=(R8,R9),DATAREG=(R7)
UTPROGC AMODE 31
space 2
START
DS
0H
space 2
MVC
PLINEP,=H'1'
2nd Line on the Screen
MVC
INAREA,=CL80' '
Clear Input area
MVC
INPROC,=CL36' '
No BTS Process name
XC
INAREAL,INAREAL
Clear input lengths
XC
INAREAF,INAREAF
space 2
eject
space 2
*
*
*
*
*
Sample Assembler program for BigCommarea processing
Page 41 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
Initial actions
=
=
=
=
=
=
Determine whether or not this module was invoked by
=
=
Terminal activity or via a Link.
=
=
=
=
If it is a terminal transaction, continue by getting
=
=
the input after the TransId and analysing it.
=
=
=
=
For an XC LINK invocation, look at the 1st word of the
=
=
Commarea to determine the action required:
=
=
=
=
5 -> Internal reusage to show function working
=
=
as part of a linked program
=
=
=
=
7 -> Use externally via EXCI to delete a given
=
=
Process (which is assumed to have been
=
=
left around and needs to be got rid of)
=
=
=
====================================================================
INIT
space
DS
space
EXEC
space
EXEC
space
ST
LH
ST
space
C
BE
*
INIT0
INIT1
space
MVC
space
CLC
BE
CLC
BE
space
EXEC
space
DS
space
EXEC
space
LH
ST
space
CLC
BL
MVC
space
DS
space
MVC
MVC
MVC
space
BAL
space
2
0H
2
CICS ASSIGN STARTCODE(STARTBY) INVOKINGPROG(STARTPR)
>
PROGRAM(CURPROG)
1
CICS ADDRESS COMMAREA(R2)
1
R2,ACOMM
Save Commarea address
R15,EIBCALEN
Get Commarea Length
R15,LCOMM
2
R15,=F'0'
Done by a link?
INIT0
No - Do Terminal started
Yes - determine action
1
COMM,0(R2)
and copy it
1
COMM1,=F'5'
Internal Link action
DOBTS5
COMM1,=F'7'
EXCI deletion
DOBTS7
1
CICS RETURN
2
0H
2
CICS RECEIVE INTO(INAREA) LENGTH(INAREAL)
>
MAXLENGTH(80)
1
R14,INAREAL
Save Input length
R14,INAREAF
1
INAREAF,=F'6'
Is there a PN?
INIT1
no - skip
INPROC,INAREAF+9
yes - save it
1
0H
1
PLINE,=CL80' '
PLINE,=CL80'Input PN XXXXXXXX ****/'
PLINE+9(L'INPROC),INPROC
1
R5,SAYNORM
2
Sample Assembler program for BigCommarea processing
Page 42 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
Check what action is required
=
=
----------------------------=
=
=
=
The Process Name (which is generated by the I function)
=
=
must be passed in after the action code
=
=
=
=
So, the input is:
=
=
=
=
tranI
Generate PN & set init container
=
=
tran1<<PN>>
Read the Container
=
=
tran2<<PN>>
Set contents of the Container
=
=
tran3<<PN>>
Read & Write the Container
=
=
tran4<<PN>>
Read & Write Container via a LINK
=
=
tranA<<PN>>
Write Container and Abend
=
=
tranX<<PN>>
Delete the Process (inc container)
=
=
=
=
=
=
First of all do the I function and then use the screen copy =
=
facility to Copy the PN. Use Paste to insert this into
=
=
all subsequent usages.
=
=
=
====================================================================
space
LA
L
C
BL
space
CLC
BE
CLC
BE
CLC
BE
CLC
BE
CLC
BE
CLC
BE
CLC
BE
CLC
BE
space
B
space
eject
space
2
R14,INAREA
R15,INAREAF
R15,=F'5'
EXIT
1
4(1,R14),=CL1'I'
DOBTSI
4(1,R14),=CL1'1'
DOBTS1
4(1,R14),=CL1'2'
DOBTS2
4(1,R14),=CL1'3'
DOBTS3
4(1,R14),=CL1'4'
DOBTS4
4(1,R14),=CL1'A'
DOBTSA
4(1,R14),=CL1'E'
DOBTSE
4(1,R14),=CL1'X'
DOBTSE
1
EXIT
2
Ensure a request is around
after the 4byte TransId
Select on Function
2
Sample Assembler program for BigCommarea processing
Page 43 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
Init : Create the Process and setup Container
=
=
---=
=
=
=
One first has to create the BTS Process to which the
=
=
Container is associated. You do not have to bother with
=
=
any of the BTS Event or Activity function as this Process
=
=
will never get run. Consequently, just use the current
=
=
Transaction Name.
=
=
=
=
The Process Name has to be unique across the SysPlex
=
=
(more properly, the scope of the VSAM file used through
=
=
the ProcessType definition). I have used
=
=
=
=
SYSID.TransId.TaskNumber.STCK.
=
=
=
=
for this name which should be unique enough whilst
=
=
providing sufficient info for offline tidying up.
=
=
You might want to change the code to use a readable date.
=
=
The main thing is to ensure that this generated name
=
=
is unique over the scope of the VSAM file.
=
=
=
=
The ProcessType is the name of the RDO entry (which
=
=
basically indirects to the VSAM file used to hold the
=
=
Container data). This will usually be fixed, so you will
=
=
need to modify the PROCTYPE setting at the bottom of this
=
=
program.
=
=
=
=
In this program, a fixed BTS Container name is used. You
=
=
can change this, if required, by altering the CONNAME
=
=
field.
=
=
=
=
After the Process has been defined, the Container
=
=
is generated via a PUT operation. ACQPROCESS is used to
=
=
associate the Container with the current Process (which
=
=
is that which was just defined).
=
=
=
=
The Container acts as the Big Commarea - I am only using
=
=
a small area to illustrate concepts. The size of the
=
=
Container is not fixed at 1st usage, and is not limited
=
=
by the RECSZ of the associated VSAM file.
=
=
=
=
Note the SYNCPOINT - BTS depends on this comand to
=
=
commit all its You should not regard the Process as defined =
=
or the Container around (or hardened) until this is
=
=
done. In a real program, you will have to consider
=
=
where this is done in relation to updates to Recoverable
=
=
CICS resources.
=
=
=
====================================================================
space 2
Sample Assembler program for BigCommarea processing
Page 44 of 63
DOBTSI
* =>
* =>
* =>
* =>
* =>
DS
0H
space 2
MVC
PLINE,=CL80'Doing Act I (Init)'
BAL
R5,SAYNORM
space 2
Generate an unique process name based on current transid
space 2
MVC
PN,=CL36' '
STCK TIMED
Get Unique Timestamp
EXEC CICS ASSIGN SYSID(PN1)
Space 1
MVC
PN2,=CL1'.'
sysid.
MVC
PN3,EIBTRNID
MVC
PN4,=CL1'.'
tranid.
LA
R14,EIBTASKN
LA
R15,PN5
BAL
R5,CONV4PO8
taskno.
MVC
PN6,=CL1'.'
LA
R14,TIMED
LA
R15,PN7
BAL
R5,CONV4TO8
LA
R14,TIMED+4
LA
R15,PN7+8
BAL
R5,CONV4TO8
time.
MVC
PN8,=CL1'.'
space 1
MVC
PLINE,=CL80'PN *******************/'
MVC
PLINE+3(L'PN),PN
BAL
R5,SAYNORM
MVC
PLINE,=CL80'PT '
MVC
PLINE+3(L'PROCTYPE),PROCTYPE
BAL
R5,SAYNORM
space 2
Define the BTS Process to use - fixed Processtype
space 2
EXEC CICS DEFINE PROCESS(PN)
PROCESSTYPE(PROCTYPE)
TRANSID(EIBTRNID)
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'DP
'
BAL
R5,SAYRESP
space 2
Put some data into a fixed named container
space 2
MVC
PLINE,=CL80'Putting into Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
EXEC CICS PUT CONTAINER(CONNAME) ACQPROCESS
FROM(DATA1) FLENGTH(=AL4(L'DATA1))
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'PC
'
BAL
R5,SAYRESP
space 2
Syncpoint to tidy up BTS
space 2
MVC
PLINE,=CL80'Syncpointing '
BAL
R5,SAYNORM
space 1
EXEC CICS SYNCPOINT
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'SP
'
BAL
R5,SAYRESP
space 2
Exit Initial function
space 2
B
EXIT
space 2
eject
space 2
>
>
>
>
>
>
*
Figure 16: Sample Program: Creating the Process and BigCommarea
Sample Assembler program for BigCommarea processing
Page 45 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - 1 : Read the Container
=
=
--------=
=
=
=
This action shows what is to be done to read the contents
=
=
of a BTS Container when it is being used to convay Big
=
=
Commarea information.
=
=
=
=
Reading the Container does not delete it, and so the
=
=
contents can be reread elsewhere.
=
=
=
=
In order to read the Container, it is best to inquire
=
=
about the length of data before reading it. This is to
=
=
avoid an incorrect length exception (which occurs both
=
=
if the area is too small for the Container and also,
=
=
rather annoyingly, if the area is too big).
=
=
=
=
This is done via XC GET CONTAINER ACQPROCESS FLENGTH(v)
=
=
with v initially set to zero. On return, you get a Length
=
=
Exception and the real length of the Container set in v.
=
=
=
=
You should get an area for the received BigCommarea data
=
=
using this length (via XC GETMAIN FLENGTH() ), but this
=
=
has been omitted for clarity.
=
=
=
=
The Container is associated with a Process (and
=
=
ProcessType) and this has to be associated with the
=
=
current transaction before the Container is accessed.
=
=
This is done with the XC ACQUIRE PROCESS command.
=
=
=
=
Once the Process has been acquired by the Transaction,
=
=
it (and all its associated Containers) are locked and
=
=
so unavailable for use in another CICS Transaction.
=
=
=
=
There is no equivalent XC RELEASE PROCESS and so
=
=
this lock lasts until the next XC SYNCPOINT command.
=
=
=
=
If you wanted to use the Container after the next XC
=
=
SYNCPOINT, you have have to re-acquire it, but that
=
=
could fail if another task intervened and grabbed it.
=
=
=
=
Consequently, do not design an application which
=
=
falls into this trap.
=
=
=
=
=
====================================================================
space 2
Sample Assembler program for BigCommarea processing
Page 46 of 63
DOBTS1
DS
space
MVC
BAL
space
MVC
MVC
BAL
MVC
MVC
BAL
space
* => Reacquire
space
EXEC
* =>
* =>
* =>
* =>
0H
2
PLINE,=CL80'Doing Act 1 (Get)'
R5,SAYNORM
1
PLINE,=CL80'PN ****************************************'
PLINE+3(L'INPROC),INPROC
R5,SAYNORM
PLINE,=CL80'PT '
PLINE+3(L'PROCTYPE),PROCTYPE
R5,SAYNORM
2
the BTS Process being used
2
CICS ACQUIRE PROCESS(INPROC)
>
PROCESSTYPE(PROCTYPE)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'AP
'
BAL
R5,SAYRESP
space 2
Get the Container Length
space 2
MVC
PLINE,=CL80'Getting Leng Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
MVC
INCONL,=F'0'
XC
INCON,INCON
space 1
EXEC CICS GET CONTAINER(CONNAME) ACQPROCESS
>
INTO(INCON)
FLENGTH(INCONL)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'GL
'
BAL
R5,SAYRESP
space 2
MVC
PLINE,=CL80'LEN
'
LA
R14,INCONL
LA
R15,PLINE+5
BAL
R5,CONV4TO8
BAL
R5,SAYNORM
space 2
Get some data from a fixed named container
space 2
MVC
PLINE,=CL80'Getting from Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
XC
INCON,INCON
space 1
EXEC CICS GET CONTAINER(CONNAME) ACQPROCESS
>
INTO(INCON)
FLENGTH(INCONL)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'GC
'
BAL
R5,SAYRESP
space 2
MVC
PLINE,=CL80'DAT
'
MVC
PLINE+5(50),INCON
BAL
R5,SAYNORM
space 2
Syncpoint to tidy up BTS
space 2
MVC
PLINE,=CL80'Syncpointing '
BAL
R5,SAYNORM
space 1
EXEC CICS SYNCPOINT
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'SP
'
BAL
R5,SAYRESP
space 2
Exit function
space 2
B
EXIT
space 2
eject
space 2
Figure 17: Sample Program: Reading the BigCommarea
Sample Assembler program for BigCommarea processing
Page 47 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - 2 : Update Container
=
=
--------=
=
=
=
This routine shows how the Container (Big Commarea) is
=
=
updated with new data.
=
=
=
=
Again, as the Container is associated with a Process
=
=
(and ProcessType), the relevant Process has to be
=
=
Acquired before any further action.
=
=
=
=
Then, the Container is simply updated (or created)
=
=
by the XC PUT CONTAINER command. The ACQPROCESS option
=
=
is used to say that the Container belongs to the
=
=
currently acquired BTS process.
=
=
=
=
As before, the data will not actually be hardened into
=
=
the Container until the next XC SYNCPOINT command.
=
=
=
=
Consequently, use of the XC SYNCPOINT command is vital
=
=
when using BTS Processing to handle Big Commareas - you
=
=
have to be aware of the BTS implications as well as the
=
=
Recoverable resource processing.
=
=
=
=
=
====================================================================
space
DS
space
MVC
BAL
space
MVC
MVC
BAL
MVC
MVC
BAL
space
* => Reacquire
space
EXEC
2
0H
2
PLINE,=CL80'Doing Act 2 (Put)'
R5,SAYNORM
2
PLINE,=CL80'PN ****************************************'
PLINE+3(L'INPROC),INPROC
R5,SAYNORM
PLINE,=CL80'PT '
PLINE+3(L'PROCTYPE),PROCTYPE
R5,SAYNORM
2
the BTS Process being used
2
CICS ACQUIRE PROCESS(INPROC)
>
PROCESSTYPE(PROCTYPE)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'AP
'
BAL
R5,SAYRESP
space 2
* => Put some data into a fixed named container
space 2
MVC
PLINE,=CL80'Putting into Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
EXEC CICS PUT CONTAINER(CONNAME) ACQPROCESS
>
FROM(DATA2) FLENGTH(=AL4(L'DATA2))
>
RESP(RESP) RESP2(RESP2)
DOBTS2
space 1
MVC
BAL
space
* => Syncpoint
space
MVC
BAL
space
EXEC
PLINE,=CL80'PC
R5,SAYRESP
2
to tidy up BTS
2
PLINE,=CL80'Syncpointing '
R5,SAYNORM
1
CICS SYNCPOINT
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'SP
BAL
R5,SAYRESP
space 2
* => Exit function
space 2
B
EXIT
space 2
eject
space 2
'
>
'
Figure 18: Sample Program: Writing the BigCommarea
Sample Assembler program for BigCommarea processing
Page 48 of 63
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - 3 : Get & Put Container in a single go
=
=
--------=
=
=
=
This action merely shows that the Container can be
=
=
Read and Written to in the same chunk of function.
=
=
=
=
=
====================================================================
space
DS
space
MVC
BAL
space
MVC
MVC
BAL
MVC
MVC
BAL
space
* => Reacquire
space
EXEC
2
0H
2
PLINE,=CL80'Doing Act 3 (Get and Put)'
R5,SAYNORM
2
PLINE,=CL80'PN ****************************************'
PLINE+3(L'INPROC),INPROC
R5,SAYNORM
PLINE,=CL80'PT '
PLINE+3(L'PROCTYPE),PROCTYPE
R5,SAYNORM
2
the BTS Process being used
2
CICS ACQUIRE PROCESS(INPROC)
>
PROCESSTYPE(PROCTYPE)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'AP
'
BAL
R5,SAYRESP
space 2
* => Get the Container Length
space 2
MVC
PLINE,=CL80'Getting Leng Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
MVC
INCONL,=F'0'
XC
INCON,INCON
space 1
EXEC CICS GET CONTAINER(CONNAME) ACQPROCESS
>
INTO(INCON)
FLENGTH(INCONL)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'GL
'
BAL
R5,SAYRESP
space 2
MVC
PLINE,=CL80'LEN
'
LA
R14,INCONL
LA
R15,PLINE+5
BAL
R5,CONV4TO8
BAL
R5,SAYNORM
space 2
* => Get some data from a fixed named container
space 2
MVC
PLINE,=CL80'Getting from Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
XC
INCON,INCON
space 1
EXEC CICS GET CONTAINER(CONNAME) ACQPROCESS
>
INTO(INCON)
FLENGTH(INCONL)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'GC
'
BAL
R5,SAYRESP
space 2
MVC
PLINE,=CL80'DAT
'
MVC
PLINE+5(50),INCON
BAL
R5,SAYNORM
DOBTS3
Figure 19: Sample Program: Reading and Writing the BigCommarea
Sample Assembler program for BigCommarea processing
Page 49 of 63
space 2
* => Put some data into a fixed named container
space 2
MVC
PLINE,=CL80'Putting into Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
EXEC CICS PUT CONTAINER(CONNAME) ACQPROCESS
FROM(DATA3) FLENGTH(=AL4(L'DATA3))
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'PC
'
BAL
R5,SAYRESP
space 2
* => Syncpoint to tidy up BTS
space 2
MVC
PLINE,=CL80'Syncpointing '
BAL
R5,SAYNORM
space 1
EXEC CICS SYNCPOINT
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'SP
'
BAL
R5,SAYRESP
space 2
* => Exit function
space 2
B
EXIT
space 2
eject
space 2
*
>
>
>
Sample Assembler program for BigCommarea processing
Page 50 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - 4 : Get & Put Container via a link
=
=
--------=
=
=
=
BTS activity for Big Commarea processing will usually
=
=
proceed via an XC LINK to anoher program. This action
=
=
merely shows that this is supported.
=
=
=
=
=
=
The only thing to note is that the Process is Acquired
=
=
in this (higher level) code, so the details of it do
=
=
not need to be passed in the Commarea (as the same Unit
=
=
Of Work is active).
=
=
=
====================================================================
space
DS
space
MVC
BAL
space
MVC
MVC
BAL
MVC
MVC
BAL
space
* => Reacquire
space
EXEC
2
0H
2
PLINE,=CL80'Doing Act 4 (Create Link)'
R5,SAYNORM
2
PLINE,=CL80'PN ****************************************'
PLINE+3(L'INPROC),INPROC
R5,SAYNORM
PLINE,=CL80'PT '
PLINE+3(L'PROCTYPE),PROCTYPE
R5,SAYNORM
2
the BTS Process being used
2
CICS ACQUIRE PROCESS(INPROC)
>
PROCESSTYPE(PROCTYPE)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'AP
'
BAL
R5,SAYRESP
space 2
MVC
COMM1,=F'5'
Set New Function
MVC
COMM2,PLINEP
Set Line Position
MVC
COMM3,INPROC
Set Process Name
space 1
EXEC CICS LINK PROGRAM(CURPROG)
>
COMMAREA(COMM)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINEP,COMM2
Update Line Number
space 1
MVC
PLINE,=CL80'LK
'
BAL
R5,SAYRESP
space 2
* => Exit function
space 2
B
EXIT
space 2
eject
space 2
DOBTS4
Sample Assembler program for BigCommarea processing
Page 51 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - 5 : Link function for updating a container
=
=
--------=
=
=
=
This action merely shows how the BTS Big Commarea
=
=
function works for an XC LINKed program.
=
=
=
=
As an earlier function/module/transaction will have
=
=
created the Process (or have Acquired it) you do not
=
=
need details of the Process to be passed into this code
=
=
through the Commarea (but I have done it anyway!).
=
=
=
====================================================================
space 2
DS
0H
space 2
MVC
PLINEP,COMM2
Zap Line Number
MVC
INPROC,COMM3
Get PN from Commarea
space 2
MVC
PLINE,=CL80'Doing Act 5 (do link)'
BAL
R5,SAYNORM
space 2
space 2
MVC
PLINE,=CL80'PN ****************************************'
MVC
PLINE+3(L'INPROC),INPROC
BAL
R5,SAYNORM
MVC
PLINE,=CL80'PT '
MVC
PLINE+3(L'PROCTYPE),PROCTYPE
BAL
R5,SAYNORM
space 2
* => Process already acive for the UnitOfWork
space 2
space 2
* => Get the Container Length
space 2
MVC
PLINE,=CL80'Getting Leng Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
MVC
INCONL,=F'0'
XC
INCON,INCON
space 1
EXEC CICS GET CONTAINER(CONNAME) ACQPROCESS
>
INTO(INCON)
FLENGTH(INCONL)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'GL
'
BAL
R5,SAYRESP
space 2
MVC
PLINE,=CL80'LEN
'
LA
R14,INCONL
LA
R15,PLINE+5
BAL
R5,CONV4TO8
BAL
R5,SAYNORM
space 2
DOBTS5
Figure 20: Sample Program: BigCommarea Usage via a Link
Sample Assembler program for BigCommarea processing
Page 52 of 63
* => Get some data from a fixed named container
space 2
MVC
PLINE,=CL80'Getting from Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
XC
INCON,INCON
space 1
EXEC CICS GET CONTAINER(CONNAME) ACQPROCESS
INTO(INCON)
FLENGTH(INCONL)
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'GC
'
BAL
R5,SAYRESP
space 2
MVC
PLINE,=CL80'DAT
'
MVC
PLINE+5(50),INCON
BAL
R5,SAYNORM
space 2
* => Put some data into a fixed named container
space 2
MVC
PLINE,=CL80'Putting into Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
EXEC CICS PUT CONTAINER(CONNAME) ACQPROCESS
FROM(DATA5) FLENGTH(=AL4(L'DATA5))
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'PC
'
BAL
R5,SAYRESP
space 2
* => Syncpoint to tidy up BTS
space 2
MVC
PLINE,=CL80'Syncpointing '
BAL
R5,SAYNORM
space 1
EXEC CICS SYNCPOINT
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'SP
'
BAL
R5,SAYRESP
space 2
* => Exit function
space 2
MVC
PLINE,=CL80'End of Linking '
BAL
R5,SAYNORM
space 1
L
R2,ACOMM
Address the Commarea
MVC
COMM1,=F'4'
Update Function
MVC
COMM2,PLINEP
Update Line Number
MVC
0(L'COMM,R2),COMM
Update the Commarea
space 2
EXEC CICS RETURN
space 2
B
EXIT
space 2
eject
space 2
>
>
>
>
>
Sample Assembler program for BigCommarea processing
Page 53 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - 7 : EXCI Deletion
=
=
--------=
=
=
=
This routine shows what is needed to be done to remove
=
=
from the BTS VSAM Repository file a BigCommarea process
=
=
that has been left hanging (as a result of an Abend
=
=
not properly cleaning things up).
=
=
=
=
The relevant ProcessType (fixed in the rest of this
=
=
example) and ProcessName are taken from the Commarea, the
=
=
dangling Process Reacquired and then Cancelled.
=
=
=
====================================================================
space
DS
space
MVC
MVC
space
* => Reacquire
space
EXEC
2
0H
2
INPROC,COMM3
Get PN from Commarea
INPROCT,COMM4
Get PT from Commarea
2
the BTS Process being used
2
CICS ACQUIRE PROCESS(INPROC)
PROCESSTYPE(INPROCT)
RESP(RESP) RESP2(RESP2)
space 2
* => Cancel this current process
space 2
EXEC CICS CANCEL ACQPROCESS
RESP(RESP) RESP2(RESP2)
space 2
* => Syncpoint to tidy up BTS
space 2
EXEC CICS SYNCPOINT
RESP(RESP) RESP2(RESP2)
space 2
* => Exit function
space 2
EXEC CICS RETURN
space 2
eject
space 2
DOBTS7
>
>
>
>
Figure 21: Sample Program: BigCommarea Deletion via EXCI
Sample Assembler program for BigCommarea processing
Page 54 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - A : Update Container and Rollback
=
=
--------=
=
=
=
This routine updates the Container (Big Commarea) and then =
=
does an XC SYNCPOINT ROLLBACK to show that this update is
=
=
lost when the UnitOfWork fails (as occurs on an Abend).
=
=
=
=
Use Action 1 to confirm that the update has not happened!
=
=
=
====================================================================
space
DS
space
MVC
BAL
space
MVC
MVC
BAL
MVC
MVC
BAL
space
* => Reacquire
space
EXEC
2
0H
2
PLINE,=CL80'Doing Act A (Put and Rollback)'
R5,SAYNORM
2
PLINE,=CL80'PN ****************************************'
PLINE+3(L'INPROC),INPROC
R5,SAYNORM
PLINE,=CL80'PT '
PLINE+3(L'PROCTYPE),PROCTYPE
R5,SAYNORM
2
the BTS Process being used
2
CICS ACQUIRE PROCESS(INPROC)
>
PROCESSTYPE(PROCTYPE)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'AP
'
BAL
R5,SAYRESP
space 2
* => Put some data into a fixed named container
space 2
MVC
PLINE,=CL80'Putting into Container *'
MVC
PLINE+23(L'CONNAME),CONNAME
BAL
R5,SAYNORM
space 1
EXEC CICS PUT CONTAINER(CONNAME) ACQPROCESS
>
FROM(DATAA) FLENGTH(=AL4(L'DATAA))
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'PC
'
BAL
R5,SAYRESP
space 2
* => Rollback to leave the Container unaltered
space 2
MVC
PLINE,=CL80'Rolling Back '
BAL
R5,SAYNORM
space 1
EXEC CICS SYNCPOINT ROLLBACK
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'RB
'
BAL
R5,SAYRESP
space 2
* => Exit function
space 2
B
EXIT
space 2
eject
space 2
DOBTSA
Figure 22: Sample Program: BigCommarea behavour on a failure
Sample Assembler program for BigCommarea processing
Page 55 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
BTS - E : Exit
=
=
--------=
=
=
=
End of function
=
=
=
=
This routine shows what is needed to remove the
=
=
Process and assocaited Containers. If this XC CANCEL
=
=
PROCESS is not executed, then the Process and
=
=
any relevant Containers will be left in the VSAM file
=
=
forever.
=
=
=
=
So, ensure that you include Abend Handlers in production
=
=
code to tidy things up.
=
=
=
=
Orphaned processes will eventually cause the VSAM file
=
=
to be filled up. Which means that some manual operation
=
=
will have to be done to remove these records. The key
=
=
used for the Process Name will help in this operation
=
=
(which is why I have used the SYSID and a Timestamp
=
=
as the Process Name).
=
=
=
=
If the VSAM file for the Process is not shared between
=
=
CICS regions, then you can merely delete everything
=
=
in it (or delete and recreate) as part of COLD
=
=
startup processing.
=
=
=
=
A Shared VSAM file (for Big Commarea being used to
=
=
pass information betweenm CICS regions) will be more of
=
=
a problem to offline tidyup, as the file will have to be
=
=
unused in all regions.
=
=
=
====================================================================
space 2
DOBTSE
DS
0H
space 2
MVC
PLINE,=CL80'Doing Act E (Exit)'
BAL
R5,SAYNORM
space 2
MVC
PLINE,=CL80'PN ****************************************'
MVC
PLINE+3(L'INPROC),INPROC
BAL
R5,SAYNORM
MVC
PLINE,=CL80'PT '
MVC
PLINE+3(L'PROCTYPE),PROCTYPE
BAL
R5,SAYNORM
space 2
* => Reacquire the BTS Process being used
space 2
EXEC CICS ACQUIRE PROCESS(INPROC)
>
PROCESSTYPE(PROCTYPE)
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'AP
'
BAL
R5,SAYRESP
space 2
* => Cancel this current process
space 2
MVC
PLINE,=CL80'Cancelling the process *'
BAL
R5,SAYNORM
space 1
EXEC CICS CANCEL ACQPROCESS
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'CP
'
BAL
R5,SAYRESP
space 2
* => Syncpoint to tidy up BTS
space 2
MVC
PLINE,=CL80'Syncpointing '
BAL
R5,SAYNORM
space 1
EXEC CICS SYNCPOINT
>
RESP(RESP) RESP2(RESP2)
space 1
MVC
PLINE,=CL80'SP
'
BAL
R5,SAYRESP
space 2
* => Exit function
space 2
B
EXIT
Figure 23: Sample Program: BigCommarea Exit processing
Sample Assembler program for BigCommarea processing
Page 56 of 63
space 2
eject
space 2
* ===================================================================
* =
=
* =
End of program
=
* =
=
* ===================================================================
space 2
space 2
EXIT
DS
0H
space 2
MVC
PLINEL,=H'80'
MVC
PLINE,=CL80' '
MVC
PLINE,=CL80'*** Exit *** '
BAL
R5,SAYNORM
space 2
EXEC CICS SEND PAGE
space 2
EXEC CICS RETURN
space 2
eject
space 2
*
Sample Assembler program for BigCommarea processing
Page 57 of 63
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
Build a WTO for an ordinary text line
=
=
------------------------------------=
=
=
=
Linked on R5
=
=
=
====================================================================
SAYNORM
*
SN1
*
*
*
*
*
*
*
*
*
*
space
DS
space
ST
space
LH
LA
STH
space
STM
WTO
EXEC
LM
space
CLC
BNH
EXEC
space
MVC
space
DS
space
L
BR
space
2
0H
1
R5,SAYSAVE
1
R15,PLINEP
R15,1(,R15)
R15,PLINEP
1
R0,R15,WTOSAVE
TEXT=PLINEL
CICS SEND TEXT ACCUM JUSTIFY(PLINEP)
FROM(PLINE) LENGTH(79)
R0,R15,WTOSAVE
2
PLINEP,=H'24'
SN1
CICS SEND PAGE
1
PLINEP,=H'1'
1
0H
2
R5,SAYSAVE
R5
2
>
====================================================================
=
=
=
Build a WTO for Reason & Response Codes
=
=
--------------------------------------=
=
=
=
Linked on R5
=
=
=
====================================================================
SAYRESP
*
SR1
space
DS
space
ST
space
LH
LA
STH
space
LA
LA
BAL
space
LA
LA
BAL
space
STM
WTO
EXEC
CLC
BNH
EXEC
space
MVC
space
DS
space
LM
space
L
BR
space
2
0H
1
R5,SAYSAVE
1
R15,PLINEP
R15,1(,R15)
R15,PLINEP
1
R14,RESP
R15,PLINE+5
R5,CONV4TO8
1
R14,RESP2
R15,PLINE+20
R5,CONV4TO8
2
R0,R15,WTOSAVE
TEXT=PLINEL
CICS SEND TEXT ACCUM JUSTIFY(PLINEP)
FROM(PLINE) LENGTH(79)
PLINEP,=H'24'
SR1
CICS SEND PAGE
1
PLINEP,=H'1'
1
0H
2
R0,R15,WTOSAVE
2
R5,SAYSAVE
R5
2
>
Page 58 of 63
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
====================================================================
=
=
=
Conversion Subroutines
=
=
---------------------=
=
=
=
These are general conversion routines. They are all linked
=
=
on R5 and use SAVE1 as their savearea
=
=
=
=
R14-> Input
R15->Output
=
=
=
= CONV1TO2 = XL1 -> CL2
=
= CONV2TO4 = XL2 -> CL4
=
= CONV4TO8 = XL4 -> CL8
=
= CONV4PO8 = PL4 -> CL8
=
=
=
====================================================================
space 2
*
* =====> Convert XL1->CL2 (R14->XL1, R15->CL2)
*
space 2
CONV1TO2 DS
0H
space 2
STM
R0,R15,SAVE1
Save regs
space 1
XC
VALU2TO4,VALU2TO4
Clear
XL4
MVC
VALU2TO4+3(1),0(R14)
Get Input XL2
space 1
MVC
OUTP2TO4,=CL4'00000000'
Clear return area
space 1
XR
R14,R14
Clear Work Reg
IC
R14,VALU2TO4+3
Load Source Byte
N
R14,=XL4'000000F0'
Set the Nibble
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' Address Pattern
AR
R15,R14
Point to Printable char
MVC
OUTP2TO4+0(1),0(R15)
Save the Printable char
space 1
XR
R14,R14
IC
R14,VALU2TO4+3
..x.
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP2TO4+1(1),0(R15)
x...
space 1
LM
R0,R15,SAVE1
Restore regs
MVC
0(2,R15),OUTP2TO4
Copy Converted CL4
space 1
BR
R5
Return
space 2
Sample Assembler program for BigCommarea processing
Page 59 of 63
*
* =====> Convert XL2->CL4 (R14->XL2, R15->CL4)
*
space 2
CONV2TO4 DS
0H
space 2
STM
R0,R15,SAVE1
Save regs
space 1
XC
VALU2TO4,VALU2TO4
Clear
XL4
MVC
VALU2TO4+2(2),0(R14)
Get Input XL2
space 1
MVC
OUTP2TO4,=CL4'00000000'
Clear return area
space 1
XR
R14,R14
Clear Work Reg
IC
R14,VALU2TO4+2
Load Source Byte
N
R14,=XL4'000000F0'
Set the Nibble
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' Address Pattern
AR
R15,R14
Point to Printable char
MVC
OUTP2TO4+0(1),0(R15)
Save the Printable char
space 1
XR
R14,R14
IC
R14,VALU2TO4+2
..x.
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP2TO4+1(1),0(R15)
x...
space 1
XR
R14,R14
IC
R14,VALU2TO4+3
N
R14,=XL4'000000F0'
..x.
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' x.
AR
R15,R14
MVC
OUTP2TO4+2(1),0(R15)
..x.
space 1
XR
R14,R14
IC
R14,VALU2TO4+3
...x
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP2TO4+3(1),0(R15)
...x
space 1
LM
R0,R15,SAVE1
Restore regs
MVC
0(4,R15),OUTP2TO4
Copy Converted CL4
space 1
BR
R5
Return
space 2
Sample Assembler program for BigCommarea processing
Page 60 of 63
*
* =====> Convert XL4->CL8 (R14->XL4, R15->CL8)
*
space 2
CONV4TO8 DS
0H
space 2
STM
R0,R15,SAVE1
Save regs
space 1
MVC
VALU4TO8,0(R14)
Get Input XL4
space 1
MVC
OUTP4TO8,=CL8'00000000'
Clear return area
space 1
XR
R14,R14
Clear Work Reg
IC
R14,VALU4TO8+0
Load Source Byte
N
R14,=XL4'000000F0'
Set the Nibble
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' Address Pattern
AR
R15,R14
Point to Printable char
MVC
OUTP4TO8+0(1),0(R15)
Save the Printable char
space 1
XR
R14,R14
IC
R14,VALU4TO8+0
x...
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP4TO8+1(1),0(R15)
.x......
space 1
XR
R14,R14
IC
R14,VALU4TO8+1
N
R14,=XL4'000000F0'
.x..
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' x.
AR
R15,R14
MVC
OUTP4TO8+2(1),0(R15)
..x.....
space 1
XR
R14,R14
IC
R14,VALU4TO8+1
.x..
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP4TO8+3(1),0(R15)
...x....
space 1
XR
R14,R14
IC
R14,VALU4TO8+2
N
R14,=XL4'000000F0'
..x.
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' x.
AR
R15,R14
MVC
OUTP4TO8+4(1),0(R15)
....x...
space 1
XR
R14,R14
IC
R14,VALU4TO8+2
..x.
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP4TO8+5(1),0(R15)
.....x..
space 1
XR
R14,R14
IC
R14,VALU4TO8+3
N
R14,=XL4'000000F0'
...x
SRA
R14,4
000000x0 -> 0000000x
LA
R15,=CL16'0123456789ABCDEF' x.
AR
R15,R14
MVC
OUTP4TO8+6(1),0(R15)
......x.
space 1
XR
R14,R14
IC
R14,VALU4TO8+3
...x
N
R14,=XL4'0000000F'
.x
LA
R15,=CL16'0123456789ABCDEF'
AR
R15,R14
MVC
OUTP4TO8+7(1),0(R15)
.......x
space 1
LM
R0,R15,SAVE1
Restore regs
MVC
0(8,R15),OUTP4TO8
Copy Converted CL8
BR
R5
Return
space 2
eject
Sample Assembler program for BigCommarea processing
Page 61 of 63
*
* =====> Convert PL4->CL8 (R14->PL4, R15->CL8)
*
space 2
CONV4PO8 DS
0H
space 2
STM
R0,R15,SAVE1
Save regs
space 1
MVC
VALU4PO8,0(R14)
Get Input PL4
space 1
MVC
OUTP4PO8,=CL8'00000000'
Clear return area
space 1
ZAP
WORK4PO8,VALU4PO8
Save as PL8
UNPK PACK4PO8,WORK4PO8
Put into Character format
OC
PACK4PO8,=CL16'0000000000000000' Make Readable
MVC
OUTP4PO8,PACK4PO8+8
Set Return Value
space 1
LM
R0,R15,SAVE1
Restore regs
MVC
0(8,R15),OUTP4PO8
Copy Converted CL8
BR
R5
Return
space 2
eject
space 2
* ===================================================================
* =
=
* =
Constants and Literals
=
* =
=
* =
PROCTYPE is the name of the BTS RDO entry (which basically
=
* =
indirects to a VSAM file name used to hold the
=
* =
Container data)
=
* =
=
* =
Change this definition as required.
=
* =
=
* =
CONNAME is the Container name used by this program: this
=
* =
does not have any external dependencies.
=
* =
=
* =
=
* =
=
* ===================================================================
space 2
PROCTYPE DC
CL8'BIGCOMM '
BTS Process Type
CONNAME DC
CL16'COMMAREA
'
BTS Fixed Container Name
space 2
DATA1
DC
CL8'11111111'
Data for Action 1
DATA2
DC
CL8'22222222'
Data for Action 2
DATA3
DC
CL8'33333333'
Data for Action 3
DATA4
DC
CL8'44444444'
Data for Action 4
DATA5
DC
CL8'55555555'
Data for Action 5
DATAA
DC
CL8'AAAAAAAA'
Data for Action A
space 2
LTORG
space 2
* ===================================================================
* =
=
* =
End of processing
=
* =
=
* ===================================================================
space 2
eject
space 2
* ===================================================================
* =
=
* =
End of UTPROGC program
=
* =
=
* ===================================================================
space 2
END
space 2
Sample Assembler program for BigCommarea processing
Page 62 of 63
>>>>>>>>>>>>>>>END of document<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Page 63 of 63