This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
An Overview of the IMS Connect Client Interface IMS User
GroupSteve [email protected] 2012 IBM Corporation
IMS Regional User GroupDisclaimer Copyright IBM Corporation
[current year]. All rights reserved. U.S. Government Users
Restricted Rights - Use, duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp. THE INFORMATION CONTAINED
IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY.
WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF
THE INFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED AS
IS WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION,
THIS INFORMATION IS BASED ON IBMS CURRENT PRODUCT PLANS AND
STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. IBM
SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF,
OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER
DOCUMENTATION. NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED
TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR
REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR
ALTERING THE TERMS AND CONDITIONS OF ANY AGREEMENT OR LICENSE
GOVERNING THE USE OF IBM PRODUCTS AND/OR SOFTWARE.IBM, the IBM
logo, ibm.com, and IMS are trademarks or registered trademarks of
International BusinessMachines Corporation in the United States,
other countries, or both. If these and other IBM trademarked
termsare marked on their first occurrence in this information with
a trademark symbol ( or ), these symbolsindicate U.S. registered or
common law trademarks owned by IBM at the time this information was
published.Such trademarks may also be registered or common law
trademarks in other countries. A current list of IBMtrademarks is
available on the Web at Copyright and trademark information
atwww.ibm.com/legal/copytrade.shtml An Overview of the IMS Connect
Client Interface 2
IMS Regional User GroupAgenda IMS Connect Flow IMS Connect
Message Formats IMS Connect User Message Exits OTMA Destination
Resolution Exit IMS Connect Client Flows IMS TM Resource Adapter
IMS Connect APIs IMS Connect Recorder Trace IMS Connect New
Enhancements An Overview of the IMS Connect Client Interface 3
IMS Regional User GroupIMS Connect Flow IMS Connect IMS Connect
is an IBM provided IMS OTMA client Comes with IMS not an additional
product Runs in a separate address space IMS Connect is also a
TCP/IP Server The user TCP/IP applications are IMS Connect Clients
An Overview of the IMS Connect Client Interface 4
IMS Regional User GroupIMS Connect Flow IMS Connect ICON
accepts input messages from and sends output messages to the IMS
Connect Client Could be the IMS TM Resource Adapter (ITRA) IBM
supplied JEE IMS Connect Client Used to be called IMS Connect for
Java (IC4J) Could be any TCP/IP Socket application Could be a Java
Application, Bean, Applet, or Servlet Could be using the IMS
Connect APIs for Java and C/C++ Can also send IMS Commands to and
receive output from the IMS Operations Manager (OM) via the
Structured Call Interface (SCI) Some vendors provide IMS Connect
Clients An Overview of the IMS Connect Client Interface 5
IMS Regional User GroupIMS Connect Flow IMS Connect ICON
accepts input messages from and sends output messages to the IMS
Connect Client IMS Connect 11 is the DRDA interface for remote DL/I
calls The Type-4 Universal Drivers are the IMS Connect clients IMS
Connect 12 is the interface for MSC over TCP/IP The remote IMS
Connect is the IMS Connect client IMS Connect 12 is the interface
for application remote message switching The remote IMS Connect is
the IMS Connect client IMS Connect 13 is the interface for ISC over
TCP/IP An Overview of the IMS Connect Client Interface 6
IMS Regional User Group SERVER z/OS,WIN, AIX, SUN, z/OS z/OSIMS
Control Center Any Websphere TCP/IP ITRA SCI Websphere App
Websphere IMS TM MWS Resource OM Adapter PC ITRA MFS Web XCF IMS
Services PC ICON XCF TCP/IP ICON IMS SOAP Gateway RYO TCP/IP Client
OTMA XCF TCP/IP Application IMS BRIDGE IMS BRIDGE MQSeries
SNAMQSeries TN3270 MQSeries BTAM
IMS Regional User GroupIMS Connect Flow Connections One IMS
Connect can connect to multiple IMS Control Regions in multiple XCF
groups One IMS Connect can have multiple connections to the same
IMS copy Each connection is a separate OTMA client One IMS Connect
connection can have multiple TPIPEs One per Port for CM1 messages
One per Client for CM0 messages this could be MANY TPIPEs!!! TPIPE
HWS$DLQ is used when IMS Connect rejects OTMA output due to an
incorrect OTMA prefix in the message (one $ is correct) One IMS
Control Region can connect to multiple ICONs ICON and IMS can be on
different LPARs in the same Sysplex An Overview of the IMS Connect
Client Interface 8
IMS Regional User GroupIMS Connect Flow IMS Connect Client ID
Each input to IMS Connect must have a Client ID associated with it
It is usually passed by the IMS Connect Client It can be
overridden/set/generated by the IMS Connect User Message Exit Each
IMS Connect Client must have a unique ID There is one exception if
ICON is listening on multiple Ports These Client IDs are used are
used in many ways in IMS Connect These will be explained during
this presentation and the IMS Connect Client Considerations
presentation You need to plan the Client ID naming scheme for your
installation An Overview of the IMS Connect Client Interface 9
IMS Regional User GroupIMS Connect Client Flows There are three
types of connections that determine how these verbs are used
Non-Persistent socket Close (Disconnect) after each send to the
ICON Client This includes iterations of an IMS conversation Never
use this except maybe for long running (all day) IMS conversations
with little traffic per conversation Transaction socket Close
(Disconnect) after each transaction or complete conversation This
is the default Persistent socket Connect once then multiple
write/read iterations for multiple transactions before Close
(Disconnect) Only the FIRST Client ID is used for all messages Any
other Client IDs will be ignored An Overview of the IMS Connect
Client Interface 10
IMS Regional User GroupIMS Connect Flow IMS Connect Flow
Receives the input message from the ICON Client via TCP/IP Passes
the input message to the Port exit if it exists Passes the input
message to a User Message Exit for formatting to OTMA input format
Sends the input message to IMS OTMA Receives the response message
from IMS OTMA Passes the response message to the same User Message
Exit for formatting to IMS Connect Client output format Passes the
response message to the Port exit if it exists Sends the response
message to the ICON Client via TCP/IP An Overview of the IMS
Connect Client Interface 11
IMS Regional User GroupIMS Connect Flow IMS Connect Timeout The
ICON Client can set a timeout value for each input message, Resume
TPIPE, and ACK This tells IMS Connect how long to wait for a
response from IMS Sometimes OTMA will send the next message after
the ACK for the current message The default value can be set in the
TIMEOUT parameter in the TCPIP control card in the HWSCFG parameter
file This value will also be used to timeout a user that Connects
to ICON but never sends in a message DELDUMMY Client in displays An
Overview of the IMS Connect Client Interface 12
IMS Regional User GroupIMS Connect Flow IMS Connect Timeout
Timeout values can be .01 to .25 seconds by .01 second increments
.25 to 1 second by .05 second increments 1 to 60 seconds by 1
second increments 1 to 60 minutes by 1 minute increments CZ no wait
ICON may override xFF wait forever X00 Use the default .25 seconds
for Resume TPIPE and ACK HWSCFG TCPIP TIMEOUT parameter for
messages An Overview of the IMS Connect Client Interface 13
IMS Regional User GroupIMS Connect Flow IMS Connect Timeout IMS
Connect will only allow NOWAIT (cZ) for: SEND-ONLY message ACK/NAK
for CM0 message ACK/NAK for Resume TPIPE option of SINGLE or SINGLE
AUTO cZ will be changed to x00 (use the default) for: ACK/NAK for a
conversational transaction Data (continue conversation) Transaction
Resume TPIPE Auto or NoAuto cZ will be changed to x19 (.25 seconds)
for: ACK/NAK for CM1 SL1 message ACK/NAK for Resume TPIPE option of
AUTO or NOAUTO An Overview of the IMS Connect Client Interface
14
IMS Regional User GroupIMS Connect Flow IMS Connect Timeout
There are several Return Codes and Reason Codes passed to the ICON
Client after a timeout RC=x20 A valid time has expired for a
transaction socket The reason code is the value of the timer The
socket is disconnected RC=x24 An invalid or x00 timer has expired
for a transaction socket The reason code contains the invalid value
or x00 The socket is disconnected RC=x28 A timer has expired for a
persistent socket The reason code is the value of the timer The
socket is NOT disconnected RC=x2C A datastore has ended or a Client
cancelled the timer The reason code is the value of the timer An
Overview of the IMS Connect Client Interface 15
IMS Regional User GroupIMS Connect Flow IMS Connect Datastores
Identifies a connection to an IMS There can be multiple DATASTOREs
Translates a logical datastore name passed by the ICON client into
the IMS XCF member name and therefore IMS Control Region This
allows for reconfiguring IMS applications without changing IMS
Connect Client code An Overview of the IMS Connect Client Interface
16
IMS Regional User GroupIMS Connect Flow IMS Connect
DatastoresHWS (ID=ICON1,RACF=N,RRS=N,XIBAREA=100,SMEMBER=SM01)TCPIP
(ECB=Y,EXIT=(HWSSMPL1,MYUSERX1),IPV6=Y,MAXSOC=2000,PORTID=5000,TIMEOUT=500)DATASTORE
(ID=DS1,GROUP=GR1,MEMBER=MB1,TMEMBER=IMSAOTMA,DRU=ICONDRUX,ACKTO=5)DATASTORE
(ID=DS2,GROUP=GR1,MEMBER=MB2,TMEMBER=IMSAOTMA,DRU=ICONDRUX,ACKTO=5)DATASTORE
(ID=DS3,GROUP=GR2,MEMBER=MB3,TMEMBER=IMSBOTMA,DRU=ICONDRUY,ACKTO=10)HWS
(ID=ICON2,RACF=N,RRS=N,XIBAREA=100,SMEMBER=SM01)TCPIP
(ECB=Y,EXIT=(HWSSMPL1,MYUSERX1),IPV6=Y,MAXSOC=2000,PORTID=5001,TIMEOUT=500)DATASTORE
(ID=DS1,GROUP=GR1,MEMBER=MB4,TMEMBER=IMSAOTMA,DRU=ICONDRUX,ACKTO=5)DATASTORE
(ID=DS2,GROUP=GR1,MEMBER=MB5,TMEMBER=IMSAOTMA,DRU=ICONDRUX,ACKTO=5)DATASTORE
(ID=DS3,GROUP=GR2,MEMBER=MB6,TMEMBER=IMSBOTMA,DRU=ICONDRUY,ACKTO=10)
An Overview of the IMS Connect Client Interface 17
IMS Regional User GroupIMS Connect Flow XCF GROUP ICON1 GR1
IMSA OTMANM=IMSAOTMA DS1 MB1 DS2 MB2 MB4 MB5 DS3 XCF GROUP GR2
ICON2 IMSB OTMANM=IMSBOTMA DS1 MB3 DS2 DS3 MB6 An Overview of the
IMS Connect Client Interface 18
IMS Regional User GroupIMS Connect Flow /DIS OTMA GROUP/MEMBER
XCF-STATUS USER-STATUS SECURITY TIB INPT SMEM DRUEXIT T/O GR1
-IMSAOTMA ACTIVE SERVER FULL -IMSAOTMA N/A 0 -MB1 ACTIVE ACCEPT
TRAFFIC NONE 150 200 SM01 -MB1 ICONDRUX 5 -MB2 ACTIVE ACCEPT
TRAFFIC CHECK 0 5000 SM01 -MB2 ICONDRUX 5 -MB4 ACTIVE ACCEPT
TRAFFIC CHECK 0 5000 SM01 -MB4 ICONDRUX 5 -MB5 ACTIVE ACCEPT
TRAFFIC CHECK 0 5000 SM01 -MB5 ICONDRUX 5 An Overview of the IMS
Connect Client Interface 19
IMS Regional User GroupIMS Connect Message Formats The format
of the input message from the ICON Client to ICON is
LLLLllzzPrefixDataSuffix LLLL Total length of the message including
the LLLL and Suffix This must be exactly correct or unpredictable
(but bad) results will happen If LLLL is greater than the number of
bytes actually sent ICON will do a read for the extra bytes and
wait (forever) This will show as READ status in VIEWHWS in IMS 12
The MAXSIZE parameter was added to the HWSCFG TCPIP control card to
try to help this It does not It may help reject garbage LLLL It
will not help reject miscalculated LLLL If LLLL is less than the
number of bytes sent then IMS Connect will not read all of the data
An Overview of the IMS Connect Client Interface 20
IMS Regional User GroupIMS Connect Message Formats The format
of the input message from the ICON Client to ICON is
LLLLllzzPrefixDataSuffix llzzPrefix ll length of the prefix zz must
be x00 if not using the IMS Connect Sample exits The zz is used by
the IMS Connect Sample exits The zz is used internally by IMS
Connect The start of the prefix contains required ICON data 8-bytes
- identifier of the ICON User Message Exit to invoke 8-bytes
reserved The rest of the prefix can contain any other information
the ICON Client wants to pass to the ICON User Exit such as Client
ID, Commit Mode, Resume TPIPE, unique identifier, IOPCB LTERM
override, IOPCB MODNAME override, etc. Data An Overview of the IMS
Connect Client Interface 21
IMS Regional User GroupIMS Connect Message Formats The format
of the input message from the ICON Client to ICON is
LLLLllzzPrefixDataSuffix Suffix X00040000 This is not required by
IMS Connect This is required by the sample IMS Connect User Message
Exits HWSSMPL0, HWSSMPL1, HWSIMSO0, HWSIMSO1 This may be required
by user written IMS Connect User Message Exits An Overview of the
IMS Connect Client Interface 22
IMS Regional User GroupIMS Connect Message Formats If you use
the IMS Connect Sample User Message Exits the input prefix (IRM) is
mapped in macro HWSIMSCB IMS Request Message Warning flag IRM_F5
has value x40 defined as IRM_F5_TRANS Translation (ASCII/EBCDIC)
performed by the IMS Connect Client This flag is ignored by the
sample exits Pass the IRM__ID in EBCDIC to indicate that the IMS
Connect Client has already translated the message to EBCDIC An
Overview of the IMS Connect Client Interface 23
IMS Regional User GroupIMS Connect Message Formats The format
of the input message from the ICON User Message Exit to ICON to
send to OTMA is INTFOTMAllzzTrancode DatallzzData INTF - 32-bytes
Interface header Documentation says BPE header which is incorrect
OTMA The OTMA prefix (CTL, State, Security, User) llzzTrancode Data
As IMS and the application would expect it llzzData As IMS and the
application would expect it The maximum size for this is 32K For
greater than 32K you need a new INTFOTMACTLllzzDatallzzData for
each 32K An Overview of the IMS Connect Client Interface 24
IMS Regional User GroupIMS Connect Message Formats OTMA Prefix
The prefix has 4 sections mapped by macro DFSYMSG (or HWSOMPFX for
ICON): Control: TPIPE name and type, message type, chaining, etc.
State Data: Commit mode, Sync Level, IOPCB LTERM and MODNAME
override, etc. Security: Security scope, Userid, Group, Utoken, no
password User: Client specific maximum of 1,024 bytes ICON shares
with the application ICON portion defined in HWSOMPFX (256 bytes)
Application portion can be used to save info to pass back to the
ICON Client An Overview of the IMS Connect Client Interface 25
IMS Regional User GroupIMS Connect Message Formats IMS Connect
User Message Exits The exit passes message length and client name
override to ICON in the HWSEXPRM parameter list The exit passes
other information to ICON in the OTMA headers Flag EXPREA_UFLAG1
can be valued when the exit is invoked for READ for an input
message from an ICON Client The flag will be passed to the exit
again (EXPXMT_UFLAG1) when it is invoked for XMIT to send the reply
back to the same ICON Client Can be used to signal debugging This
exit MUST be 100% reentrant An Overview of the IMS Connect Client
Interface 26
IMS Regional User GroupIMS Connect Message Formats The format
of the output message from OTMA to ICON is OTMAllzzDatallzzData
OTMA The OTMA prefix llzzData As the application inserted it
llzzData As the application inserted it Even though MFS is not
invoked for the output message the application may have included
MFS attribute bytes in the datastream that the ICON client will
want to interpret These do not translate well from EBCDIC to
ASCII!!! An Overview of the IMS Connect Client Interface 27
IMS Regional User GroupIMS Connect Message Formats The format
of the output message from ICON to the ICON Client is This can be
any format that is agreed upon to by the ICON User Message Exit and
the ICON Client It is usually LLLLllzzPrefixllzzdata The prefix can
be the same prefix that was passed for the input message so that
the ICON Client can correlate input and output It was stored in and
retrieved from the OTMA user data ALTPCB output may not have this
prefix The OTMA DRU exit and/or the ICON User exit may have to
build it Return code and reason code can be added to the prefix And
if you are really nice error message text The MFS output modname
was passed by OTMA and can be passed to the ICON Client so that the
ICON Client knows how to interpret and format the output message
The IMS Connect sample User Message Exits do NOT send llzzPrefix
There is no correlation of output to input An Overview of the IMS
Connect Client Interface 28
IMS Regional User GroupIMS Connect Message Formats If you use
the IMS Connect Sample User Message Exits the output suffixes are
mapped in macro HWSIMSCB RMM Request Mod Message Output MODNAME
from IMS ISRT call CSM Complete status message Eyecatcher is CSMOKY
Transaction was successful RSM Request status message Eyecatcher is
REQSTS Error in processing return code and reason code are included
RACF Return Code is also returned (IMS 12) COR Synchronous Callout
Correlator Token Eyecatcher is CORTKN An Overview of the IMS
Connect Client Interface 29
IMS Regional User GroupIMS Connect Message Formats If you use
the IMS Connect Sample User Message Exits the output suffixes are
mapped in macro HWSIMSCB The CSM and RSM have a flag to relay
information to the IMS Connect Client There are asynchronous
messages waiting on the Hold Queue for this client This output
message is for an ongoing IMS Conversation An ACK or NACK is
required for this message Protocol level is available (IMS 12) The
sample exits DO NOT return the input prefix (IRM) or any other
correlation data An Overview of the IMS Connect Client Interface
30
IMS Regional User GroupIMS Connect Message Formats This is the
DSECT for the CSM (Complete Status Message) for IMS 12
***********************************************************************
* CSM Complete Status Message
***********************************************************************
CSMMask DSECT Complete status message dsect CSM_Len DS H Length of
CSM CSM_FLGS DS 0H CMS FLAG BYTES CSM_FLG1 DS X FLAG BYTE CSM_AMSG
EQU X80 ASYNCH MSG QD IN IMS CSM_CONV EQU X40 CONVERSATIONAL OUTPUT
CSM_ACK_NAK EQU X20 ACK/NAK REQUIRED CSM_PRLVLFLG EQU X10 PROTOCOL
LEVEL AVAILABLE CSM_PROTOLVL DS X IMS CONNECT PROTOCOL LEVEL
CSM_PR00 EQU X00 00 - BASE PROTOCOL LEVEL CSM_PR01 EQU X01 01 - NOT
USED CSM_PR02 EQU X02 02 - CM0 ACK NOWAIT SUPPORT CSM_PRMAX EQU
CSM_PR02 MAXIMUM PROTOCOL LEVEL CSM_Id DS CL8 CSM id *CSMOKY*
ascii/ebcdic CSMMask_Len EQU *-CSMMask Size of CSM An Overview of
the IMS Connect Client Interface 31
IMS Regional User GroupIMS Connect Message Formats This is the
DSECT for the RSM (Request Status Message) for IMS 12
***********************************************************************
* RSM Request Status Message
***********************************************************************
RSMMask DSECT Request status message dsect RSM_Len DS H Length of
RSM RSM_FLGS DS 0H RSM FLAG BYTES RSM_FLG1 DS X FLAG BYTE RSM_AMSG
EQU X80 ASYNCH MSG QD IN IMS RSM_CONV EQU X40 CONVERSATIONAL OUTPUT
RSM_ACK_NAK EQU X20 ACK/NAK REQUIRED RSM_RACFRC DS 0X RETURN CODE
FROM RACF RSM_OTMARSN DS X REASON CODE FROM OTMA RSM_Id DS CL8 RSM
id *REQSTS* ascii/ebcdic RSM_RetCod DS F Return code RSM_RsnCod DS
F Reason code RSMMask_Len EQU *-RSMMask Size of RSM An Overview of
the IMS Connect Client Interface 32
IMS Regional User GroupIMS Connect User Message Exits IMS
Connect User Message Exits Each exit gets control during ICON
initialization and passes ICON two 8 character IDs that ICON Client
applications can use to identify it One is usually EBCDIC One is
usually ASCII If two exits pass the same ID ICON will issue
HWSP1480E The ICON Client must pass a valid exit ID in the prefix
of the input message A bad ID will terminate the connection An
Overview of the IMS Connect Client Interface 33
IMS Regional User GroupIMS Connect User Message Exits The IMS
Connect Client has to work very closely with the IMS Connect User
Message Exit Who will build the INTF header and OTMA headers? Who
will build the IMS segments? What ASCII/EBCDIC translation will be
done? If the exit ID in the prefix is ASCII the exit usually
assumes that the data is ASCII and should be translated to EBCDIC
going to IMS and back to ASCII going to the ICON client You can
also use a flag set by the client in the message prefix to
determine if translation is required But the exit can do anything
it wants What security parameters will be passed? Will they be
encrypted? What will the input prefix look like? What will the
output message look like? An Overview of the IMS Connect Client
Interface 34
IMS Regional User GroupIMS Connect User Message Exits The IMS
Connect Client has to work very closely with the IMS Connect User
Message Exit Who will determine the Client ID? Each Client must
have a unique ID It can be sent with the input message If can be
determined/overridden by the User Message Exit Who will determine
the datastore which will receive the message It can be sent with
the input message It can be determined/overridden by the User
Message Exit An Overview of the IMS Connect Client Interface
35
IMS Regional User GroupIMS Connect User Message Exits IMS
Connect supports OTMA Degraded System Monitoring OTMA sends x3C
protocol messages to OTMA clients At Client Bid with initial status
Immediately when status changes Stopped, Started, Flood Warn,
Flood, Flood Relieved Heartbeat once every 60 seconds IMS Connect
externalizes the OTMA status Expanded XIBDS table for ICON User
Message Exits Event 45 issued when XIBDS status updated Not for
heartbeat only the XIBDS timestamp is updated IMS Connect
Extensions supports Degraded System Monitoring An Overview of the
IMS Connect Client Interface 36
IMS Regional User GroupIMS Connect User Message Exits The IMS
Connect Client has to work very closely with the IMS Connect User
Message Exit This is a header with information about IMS Connect
and a pointer to the XIBDS datastore control blocks HWSXIB DSECT
Exit Interface Block 00200000
***********************************************************************
00210000 * XIB Header * 00220000
***********************************************************************
00230000 XIB_HEADER DS 0D 00240000 XIB_EYE DS CL4XIB EYECATCHER
00250000 XIB_DATASTORES DS A DataStore list address 00260000
XIB_UFLD_CNT DS F User field count 00270000 XIB_XIBDS_LEN DS H
Length of XIBDS Entry @PK70960 00280000 XIB_ARCHLVL DS X
Architecture Level @PK70960 00280100 XIB_ARCH1 EQU X01 Arch Level 1
@PK70960 00280200 XIB_ARCH2 EQU X02 Arch Level 2 @PM05993 00280250
XIB_ARCHMAX EQU XIB_ARCH2 Highest Arch Level @PM05993 00280300 *
Set Arch Level to 2 @PM05993 00280310 DS X Reserved for IMS Connect
@PK70960 00280400 XIB_VERSION DS F Version X0A0100=V10.1.0 @PM05993
00280450 DS F Aligned with V11 @PM17288 00280470 DS 3F Reserved for
IMS Connect @PM05993 00280500 * @PM05993 00280600 XIB_HDR_LEN EQU
*-HWSXIB XIB header fixed length 00290000 An Overview of the IMS
Connect Client Interface 37
IMS Regional User GroupIMS Connect User Message Exits The IMS
Connect Client has to work very closely with the IMS Connect User
Message Exit The User Message Exit is passed XIBDS control blocks
This is a list of datastores and the status of the IMS they
represent X00 Datastore is inactive and will require a STARTDS
command to connect X01 - Datastore is active X02 Datastore was
active and is now disconnected IMS Connect will automatically
reconnect when OTMA becomes active Can be used route messages to
available IMS copies HWSXIBDS DSECT Exit Interface Block Data Store
entry XIBDS_NAME DS CL8 Data store name XIBDS_STATUS DS X Data
store status XIBDS_INACTIVE EQU X00 Data store not active in ICON *
OPENDS command is required XIBDS_ACTIVE EQU X01 Data store active
in ICON * And IMS is active in XCF group XIBDS_DISC EQU X02 Data
store disconnected * No OPENDS command is required XIBDS_FLAG DS X
Data store entry flags XIBDS_LAST_ENTRY EQU X80 Last entry in list
DS XL2 Reserved XIBDS_USER DS XL4 User field An Overview of the IMS
Connect Client Interface 38
IMS Regional User GroupIMS Connect User Message Exits The ICON
Client has to work very closely with the ICON User Message Exit The
XIBDS also has degraded status and a last heartbeat timestamp
XIBDS_USER DS XL4 User field * OTMA Status Section Follows
XIBDS_ST_STATUS DS H Overall Status Code 3, 2, or 1 * 3 - Available
for work * 2 - Warning, partly degraded * 1 - Severe, no work
possible * 0 - N/A no status available XIBDS_ST_SVRSTT DS 0XL4
Unavailable resource info XIBDS_ST_SVRFLG1 DS X Group 1 unavail
resources XIBDS_ST_SVRFLG2 DS X Group 2 unavail resources
XIBDS_ST_SVRFLG3 DS X Group 3 unavail resources XIBDS_ST_SVRFLG4 DS
X Group 4 unavail resources XIBDS_ST_S4FLOOD EQU X01 Member reaches
100% flood XIBDS_ST_WRNSTT DS 0XL4 Degraded resource info
XIBDS_ST_WRNFLG1 DS X Group 1 degraded resources XIBDS_ST_W1FLOOD
EQU X80 Global flood warning XIBDS_ST_W1MTP EQU X40 Global tpipe
warning XIBDS_ST_WRNFLG2 DS X Group 2 degraded resources
XIBDS_ST_WRNFLG3 DS X Group 3 degraded resources XIBDS_ST_WRNFLG4
DS X Group 4 degraded resources XIBDS_ST_W5MTP EQU X08 Member TPIPE
reached 100% XIBDS_ST_W4MTP EQU X04 Member TPIPE reached 80%
XIBDS_ST_AWE EQU X02 Msg AWE reaches 80% flood XIBDS_ST_W4FLOOD EQU
X01 Member 80%+ flood XIBDS_ST_UTC DS CL12 UTC time for this status
XIBDS_ST_LEN EQU *-XIBDS_ST_STATUS Length of OTMA Status An
Overview of the IMS Connect Client Interface 39
IMS Regional User GroupIMS Connect User Message Exits Which
ICON User Message Exit should you use? IBM Supplied HWSIMSO0 and
HWSIMSO1 See next foil HWSSMPL0 and HWSSMPL1 Source code versions
of IMS Connect Sample User Exits The only difference is that
HWSSMPL1 has a 4-byte length in the output message These exits
build the INTF and OTMA headers These exits will translate ASCII to
EBCDIC and back again These exits are difficult to modify Even
though these are samples they are used in production by many
installations HWSJAVA0 Source code version of the exit used by IMS
TM Resource Adapter The IMS Connect Client builds and removes the
INTF and OTMA headers The IMS Connect Client translates ASCII to
EBCDIC and back again An Overview of the IMS Connect Client
Interface 40
IMS Regional User GroupIMS Connect User Message Exits Which
ICON User Message Exit should you use? HWSIMSO0 and HWSIMSO1 These
are object code only versions of IMS Connect User Message Exits
HWSSMPL0 and HWSSMPL1 As new features were added to HWSSMPL0/1 they
were not all added to HWSIMSO0/1 so they are out of date These
exits are not supported as of IMS 11 Do not try to keep a copy of
the IMS 9/10 load module and use it in IMS 11 It will not work
HWSEXPRM has changed and the load modules are not compatible with
the new DSECT An Overview of the IMS Connect Client Interface
41
IMS Regional User GroupIMS Connect User Message Exits Which
ICON User Message Exit should you use? HWSIMSO0 and HWSIMSO1 The
message IDs for these exits are *IRMREQ*, *IRMRE1*, and their ASCII
equivalents This is what the IMS Connect Client is passing to IMS
Connect There are three ways to fix this in IMS 11 Use HWSSMPL0/1
and have the IMS Connect Client change the exit ID they are passing
It is hard to get all of the Clients to change Use HWSSMPL0/1 and
use a Port Edit Exit to change the exit ID I have such an exit and
will share it Make a copy of HWSSMPL0/1 and create new modules
Change the exit IDs to *IRMREQ* and *IRMRE1* An Overview of the IMS
Connect Client Interface 42
IMS Regional User GroupIMS Connect User Message Exits
Restructure of HWSEXPRM HWSEXPRM is the control block passed from
IMS Connect to the IMS Connect User Message Exit This has changed
for IMS 11 All IMS Connect User Message Exits must be re-assembled
using the IMS 11 macro library This includes HWSSMPL0/HWSSMPL1 and
HWSJAVA0 The re-assembled exits will not work in prior versions of
IMS Connect You must ALWAYS re-assemble ALL exits for each new
release of IMS An Overview of the IMS Connect Client Interface
43
IMS Regional User GroupIMS Connect User Message Exits Returning
error messages If the IMS Connect User Message Exit does not like
the input message for any reason it can ask IMS Connect to return
it to the ICON Client rather than passing it to IMS It can pass
error return codes and reason codes and error text Prior to IMS 11
this would close a Persistent socket After IMS 11 the Persistent
socket stays open IMS Connect may also reject the message The IMS
Connect User Message Exit will be called again to process the
rejection and format the error message for the ICON Client An
Overview of the IMS Connect Client Interface 44
IMS Regional User GroupIMS Connect User Message Exits Prior to
IMS 12 IMS Connect sample User Message Exits returned RSM RC=08
RSN=40 for any and all security violations No indication of
specific reason E.g. invalid userid, incorrect password, password
expired, etc. With IMS 12, enhancements to RACF Return Codes: In
the Request Status Message (RSM) for RYO and the IMS SOAP Gateway
RSM_RACFRC In the OTMA User Data section for the IMS TM Resource
Adapter OMUSR_RACF_RC New IMS Connect Protocol level indicates
support OMUSR_PROLEV = OMUSR_PR03 An Overview of the IMS Connect
Client Interface 45
IMS Regional User GroupIMS Connect User Message Exits Prior to
IMS 12 sample exits HWSSMPL0 and HWSSMPL1 were only shipped as
source The customer had to assemble and link these modules even if
they were not modified IMS 12 ships object code for HWSUNIT0,
HWSJAVA0, HWSSMPL0, HWSSMPL1 in addition to the source code An
Overview of the IMS Connect Client Interface 46
IMS Regional User GroupIMS Connect User Message Exits Which
ICON User Message Exit should you use? You can write your own IMS
Connect User Message Exit(s) This is what I recommend Start with
HWSSMPL1 as a guide This will allow you to: Define your own user
prefix Use your own ASCII/EDBDIC translate tables Implement field
level ASCII/EBCDIC conversion Enforce installation standards Route
messages to available datastores Save and return client data in the
OTMA user prefix Return Error Message Text Do security in the exit
or call a common user written security exit Write uppercase only
Assembler language With 8-character variable names (no underscores)
An Overview of the IMS Connect Client Interface 47
IMS Regional User GroupIMS Connect User Message Exits Saving
and passing correlation data from/to the IMS Connect client The
OTMA User Data prefix is 1,024 bytes IMS Connect uses the first 256
bytes The last 768 bytes can be used to save the correlation data
Move the input prefix (IRM) to the user data on input The entire
OTMA prefix is saved in the message prefix on input to OTMA The
entire OTMA prefix is returned with the reply message from OTMA
Move the input prefix from the OTMA user data to the reply message
An Overview of the IMS Connect Client Interface 48
IMS Regional User GroupIMS Connect User Message Exits Saving
and passing correlation data from/to the IMS Connect client LLLL
llzzPrefix llzzTrancode Data INTF CTL STATE SECURITY USER
llzzTrancode Data 256+llzzprefix CTL STATE SECURITY USER
llzzDatallzzData 256+llzzprefix LLLL llzzPrefix llzzDatallzzData An
Overview of the IMS Connect Client Interface 49
IMS Regional User GroupIMS Connect User Message Exits Saving
and passing correlation data from/to the IMS Connect client The
OTMA prefix is stored in the IMS message prefix as shown in the x01
input record It is the x87 message segment item It is mapped by two
macros DFSYPRE for the first part of the segment item DSFYMSG for
the second part of the segment item An Overview of the IMS Connect
Client Interface 50
IMS Regional User GroupIMS Connect User Message Exits Which
Security User exit should you use (if any) IBM supplied All of the
IBM supplied ICON User Message Exits will call security exit
IMSLSECX if defined This exit is only supplied in object code It
does not validate passwords It will not create UTOKENs to pass to
OTMA An Overview of the IMS Connect Client Interface 52
IMS Regional User GroupIMS Connect User Message Exits Which
Security User exit should you use (if any) IMS Connect V10 supports
changing a password Supported by IMS Connect exits HWSSMPL0,
HWSSMPL1, and HWSJAVA0 Linked with object module HWSPWCH0 Input
message is: LLLL|IRM|LLzzHWSPWCH oldpw/newpw/newpw|EOM Passwords
are in plain text It is safer to do it yourself or with vendor
tools An Overview of the IMS Connect Client Interface 53
IMS Regional User GroupIMS Connect User Message Exits Which
Security User exit should you use (if any) User written security
exit This will allow you to: Validate passwords Update passwords
Pass error message text Create UTOKENs Use hidden and encrypted
Userids and Passwords You can build and delete the ACEE for every
request If you do not delete the ACEE you will run out of storage
Be careful NOT to delete the ACEE if the RACF return code is not
zero People get upset when ICON abends Or you can try to get fancy
and cache the ACEEs Code STAT=NO for performance Use RACF LLA
caching for performance An Overview of the IMS Connect Client
Interface 54
IMS Regional User GroupOTMA Destination Resolution Exit This
exit receives control for ALTPCB output and has to format the OTMA
User Data as the OTMA Client (IMS Connect) expects it The ICON OTMA
User Data is mapped in macro HWSOMPFX The first part of the OTMA
User Data is specified by IMS Connect (256 bytes) The second part
of the OTMA User Data may be used by the IMS Connect Client The DRU
exit must build it as the client expects it or build a dummy area
so that the client knows it is receiving ALTPCB output For IOPCB
input and output it was probably passed by the IMS Connect User
Exit An Overview of the IMS Connect Client Interface 55
IMS Regional User GroupOTMA Destination Resolution Exit The DRU
exit must specify the Port ID on which the ICON Client is waiting
If you specify the characters ICONNECT in the Port ID field IMS
Connect will search all ports for the Client Remember the TCPIP
PORTAFF parameter There is a sample exit shipped with ICON HWSYDRU0
It is confusing It is not straightforward to maintain I have a
better sample exit An Overview of the IMS Connect Client Interface
56
IMS Regional User GroupIMS Connect Client Flows The hardest
thing you have to do when writing your own TCP/IP ICON Client is to
determine what your applications do Always and only 1 IOPCB input
and output? Sometimes IOPCB output and sometimes not? Multiple
message IOPCB output? No output at all (Send-Only)? Only ALTPCB
output? IOPCB and ALTPCB output? An Overview of the IMS Connect
Client Interface 57
IMS Regional User GroupIMS Connect Client Flows The next
hardest thing you have to do when writing your own TCP/IP ICON
Client is to determine the flows There are a number of questions to
be answered CM0 messages or CM1 messages? If CM1 messages SL0 or
SL1? Transaction socket or Persistent socket? What should the ICON
Client to IMS Connect timeout be? This is TCP/IP traffic can get
lost in the network What should the IMS Connect to OTMA timeout be?
The message may be waiting to be scheduled in IMS Send-Only?
Send-Only with ACK? Send-Only Ordered? Resume TPIPE type? An
Overview of the IMS Connect Client Interface 58
IMS Regional User GroupIMS Connect Client Flows Send Only
Resume TPIPE One way to architect an IMS Connect application when
you are not sure what the IMS application is going to do
(IOPCB/ALTPCB output) is to send in all messages with Send-Only and
retrieve all output with Resume TPIPE If there is IOPCB output it
will go to the Hold Queue If there is ALTPCB output it will go to
the Hold Queue Resume TPIPE retrieves messages from the Hold Queue
This solution may require having correlation data in the IMS
Connect prefix and OTMA User data. IMS Connect sample User Message
Exits do not support this An Overview of the IMS Connect Client
Interface 59
IMS Regional User GroupIMS Connect Client Application
Interfaces There are several ways to have IMS Connect Client
Applications interface with IMS Write your own TCP/IP applications
Use the IMS TM Resource Adapter (ITRA) in a JEE environment Use the
new IMS Connect APIs for Java and C/C++ Use a vendor IMS Connect
API Search the web An Overview of the IMS Connect Client Interface
60
IMS Regional User GroupIMS TM Resource Adapter Formerly known
as IMS Connector for Java (IC4J) Standards-based JEE Connector
Architecture Interface to send transactions to IMS via IMS Connect
Easy-to-use Graphical and source editors Generate application code
JSPs Web Services EJBs An Overview of the IMS Connect Client
Interface 61
IMS Regional User GroupIMS TM Resource Adapter JEE/JCA
Architecture Container-Component JEE Application Server Contract
Application (WAS) Component Application Contract CCI Connection
Management Resource System Contracts Transaction Adapter Management
SPI (ITMRA) Security Management EIS-specific interface EIS An
Overview of the IMS Connect Client Interface 62
IMS Regional User GroupIMS TM Resource Adapter Supports JEE
Connector Architecture (JCA) Connection Management Connection
pooling TCP/IP and Local Option connections Handles execution or
socket timeouts Transaction Management Global z/OS RRS transaction
support and Distributed XA transaction support with Two Phase
Commit (i.e. SyncLevel Syncpt) Security Management JEE EIS Sign-on
SSL, RACF key ring Lifecycle Management An Overview of the IMS
Connect Client Interface 63
IMS Regional User GroupIMS TM Resource Adapter ITRA
Architecture z/OS1 IMS XCF Windows / AIX / Solaris / IMS Linux
Connect WebSphere IMS Application IMS Connect Server IMS Resource
z/OS2 Adapter WebSphere Application IMS IMS Server Connect IMS
Resource Adapter Linux for System z TCP/IP WebSphere Application
Server XCF IMS Resource Adapter Local An Overview of the IMS
Connect Client Interface 64
IMS Regional User GroupIMS TM Resource Adapter Supports various
types of interactions and programming models with IMS Invokes IMS
transactions or commands Conversational and non-Conversational MFS,
COBOL, C, PLI, Java Send Receive, Send Only Retrieve Asynchronous
output Options for handling undelivered output messages: purge or
reroute Single, Single Wait Alternate Client ID Commit Mode 0 or 1
processing SyncLevel None or Confirm or Syncpoint for CM1 Complex
environment support Sysplex Distributor environment zWAS 64 bit
support An Overview of the IMS Connect Client Interface 65
IMS Regional User GroupIMS TM Resource Adapter Transaction
Management Supports Global transaction, 2-Phase Commit for
distributed and z/OS environments WebSphere Application Server
Transaction Manager supports 2-Phase Commit protocol Enables
consistent changes to one or more protected resources in single
unit of work (transaction) - All changes are either fully completed
or fully rolled back Uses XA protocol to support coordination of
changes in distributed resources Uses RRS to support coordination
of changes in z/OS resources Two options for setting transaction
boundaries in an application - Bean-Managed - Container-Managed An
Overview of the IMS Connect Client Interface 66
IMS Regional User GroupIMS TM Resource Adapter Security
Management JEE and JCA provide end-to-end security model for secure
EIS access IMS TM Resource Adapter supports Authentication: User ID
and Password - Application Server - Container-Managed EIS Sign-on
RunAs Thread Identity JAAS alias specified in applications resource
reference - Application Component - Component-Managed EIS Sign-on
IMSConnectionSpec properties need to be exposed for
component-managed security Instructions for exposing properties can
be found in the RAD online help Encryption using SSL - Provides
reliable, secure communication between IMS TM Resource Adapter and
IMS Connect End users userID or password not used for SSL security
An Overview of the IMS Connect Client Interface 67
IMS Regional User GroupIMS TM Resource Adapter ITRA is
supported by RDz PL/I is also supported by RDz An Overview of the
IMS Connect Client Interface 68
IMS Regional User GroupIMS Connect APIs If you want to write
you own IMS Connect Clients but you do not want to know the details
of TCP/IP and the IMS Connect interface and protocols you can use
the new IMS Connect APIs Simplifies interactions with IMS Connect
by handling: IMS Connect message header IMS Connect interaction
protocols TCP/IP socket connections Initially supported Java
(Connect API for Java) C and C++ are now available (Connect API for
C) C# is a well known requirement No tooling is required (e.g RDz)
An Overview of the IMS Connect Client Interface 69
IMS Regional User GroupIMS Connect APIs IMS Connect APIs Client
applications will be able to use the full functionality available
to RYO applications (those that use exits HWSSMPL0/1) in IMS
Connect Complexity of following IMS Connect protocol will be
contained within the APIs and not exposed to the client application
Connections between the APIs (on behalf of the client application)
and IMS Connect will be managed inside the APIs and their use will
be transparent to the user An Overview of the IMS Connect Client
Interface 70
IMS Regional User GroupIMS Connect APIs The IMS Connect APIs
support: IMS Transactions Resume TPIPE for asynchronous output PING
and RACF password change commands IMS commands supported by OTMA
SSL connections API runtime tracing The IMS Connect APIs will not
initially support: Two-phase commit Synchronous callout Unicode An
Overview of the IMS Connect Client Interface 71
IMS Regional User GroupIMS Connect APIs Other important
features Require IMS Connect V10 Uses the IMS Connect sample User
Message Exit HWSSMPL0 or HWSSMPL1 Can be downloaded from the web
IMS Connect APIs are also SMP installable on System z Can be
installed as part of the IMS Enterprise Suite Sample client
applications are provided Java and C/C++ documentation are
available on the IMS Info Center Navigable per
class/interface/method Searchable An Overview of the IMS Connect
Client Interface 72
IMS Regional User GroupIMS Connect APIs Major Functionality
from Users Point-of-View Configure input - Execute interaction -
Process response paradigm Connections configured using setter
methods of Connection object Interactions configured using setter
methods of TmInteraction object Input can be provided as a one or
two-dimensional byte array, a Java String or an array of Java
Strings Configured interactions executed using execute interaction
Output (response message) can be retrieved as a one or
two-dimensional byte array, a Java String or an array of Java
Strings An Overview of the IMS Connect Client Interface 73
IMS Regional User GroupIMS Connect APIs The Connect API for
Java is provided as a Java JAR archive At runtime, API requires
that JRE 1.5 or later be installed and accessible to client Java
application API must be deployed to location that is accessible to
client Java application Import statement required in client Java
application for API classes import com.ibm.connect.api.*; An
Overview of the IMS Connect Client Interface 74
IMS Regional User GroupIMS Connect APIs Java Classes and
Interfaces ApiLoggingConfiguration.java - Used to set up tracing
for API ApiProperties.java - Contains constants to be used with API
Connection.java - Interface used by client to configure connections
to IMS Connect ConnectionAttributes.java - Contains properties
which can optionally be used by a client application to populate
properties of a Connection object ConnectionImpl.java - Implements
the methods declared in the Connection interface An Overview of the
IMS Connect Client Interface 75
IMS Regional User GroupIMS Connect APIs Java Classes and
Interfaces (continued) ImsConnectApiException.java - Encapsulates
errors detected in API ImsCommunicationApiException.java -
Encapsulates errors detected in communications between API and IMS
Connect ImsConnectErrorMessage.java - Main exception processing
class used by API ImsConnectErrorMessageResourceBundle.java -
Contains the text of the API exceptions declared in
IMSConnectErrorMessage.java. Currently, only the English language
version of the resource bundle is available. InputMessage.java -
Interface which encapsulates the input request message to be sent
to IMS Connect An Overview of the IMS Connect Client Interface
76
IMS Regional User GroupIMS Connect APIs Java Classes and
Interfaces (continued) InputMessageImpl.java - Internal class which
implements the methods declared in the InputMessage interface
InputMessageProperties.java - Defines constants used in
InputMessage OutputMessage.java - Interface which encapsulates the
output response message received from IMS Connect
OutputMessageImpl.java - Internal class which implements the
methods declared in the OutputMessage interface
OutputMessageProperties.java - Defines constants used in
OutputMessage An Overview of the IMS Connect Client Interface
77
IMS Regional User GroupIMS Connect APIs Java Classes and
Interfaces (continued) PropertiesFileLoader.java - Contains methods
used to populate property values from a text file containing
name-value pairs TmInteraction.java - Interface used by client to
configure interactions with IMS Connect
TmInteractionAttributes.java - Contains properties which can
optionally be used by a client application to populate properties
of a TmInteraction object TmInteractionImpl.java - Implements the
methods declared in the TmInteraction interface An Overview of the
IMS Connect Client Interface 78
IMS Regional User GroupIMS Connect Recorder Trace The IMS
Recorder Trace can be used to trace messages to and from IMS
Connect Activated by R xx,RECORDER OPEN F icon, UPDATE MEMBER
TYPE(IMSCON) START(TRACE) Events are written to a sequential data
set Allocate with IEFBR14 Format and print with IDCAMS //S1 EXEC
PGM=IDCAMS,REGION=4096K //SYSPRINT DD SYSOUT=* //SYSIN DD * PRINT
IDS(USER1.RECORDER.TRACE) /* Format is documented in IMS 12
Diagnosis manual An Overview of the IMS Connect Client Interface
79
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace The first 96 bytes is the prefix 000000 00000000
C9C3D6D5 D9C30052 00000877 15413472 0108224F 00000000 00000000
*....ICONRC.............|........* 000020 C8E6E2E3 C5E2E3F1
C2D3F991 09C5646E C2D3F991 09E57CEE 00000000 00000000
*HWSTEST1BL9..E.>BL9..V@.........* 000040 00000000 00000000
00000000 00000000 00000000 00000000 00000000 5CC9D7C2
*............................*IPB* The eyecatcher is ICONxx where
xx= RC message received from ICON Client SN message sent to ICON
Client TO timeout sent to ICON Client ER error in processing AR
input message from Client processed by XML adapter AE input message
from Client rejected by XML adapter AX output message to Client
processed by XML adapter An Overview of the IMS Connect Client
Interface 80
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace IMS Connect 12 adds the following types: ME MSC
error in processing MR MSC receive MS MSC send OE ODBM error in
processing OR ODBM receive OX ODBM send RE OTMA remote ALTPCB error
RR OTMA remote ALTPCB receive RS OTMA remote ALTPCB send An
Overview of the IMS Connect Client Interface 81
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace The first 96 bytes is the prefix000000 00000000
C9C3D6D5 D9C30052 00000877 15413472 0108224F 00000000 00000000
*....ICONRC.............|........*000020 C8E6E2E3 C5E2E3F1 C2D3F991
09C5646E C2D3F991 09E57CEE 00000000 00000000
*HWSTEST1BL9..E.>BL9..V@.........*000040 00000000 00000000
00000000 00000000 00000000 00000000 00000000 5CC9D7C2
*............................*IPB* The time of the record is at
offset x10 XHHMMSSTT local time The date of the record is at offset
x14 xCCYYDDDF CC Century x01 = 21st century YY Year DDD Julian day
F Packed sign The Clientid is at offset x20 An Overview of the IMS
Connect Client Interface 82
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace The first 96 bytes is the prefix000000 00000000
C9C3D6D5 D9C30052 00000877 15413472 0108224F 00000000 00000000
*....ICONRC.............|........*000020 C8E6E2E3 C5E2E3F1 C2D3F991
09C5646E C2D3F991 09E57CEE 00000000 00000000
*HWSTEST1BL9..E.>BL9..V@.........*000040 00000000 00000000
00000000 00000000 00000000 00000000 00000000 5CC9D7C2
*............................*IPB* The *IPB at offset x003C
indicates the Input Buffer follows0002E0 00000000 00000000 00000000
00000000 00000000 00000000 00000000 5CD6D7C2
*............................*OPB* The *OPB at offset x02FC
indicates that the Output Buffer follows An Overview of the IMS
Connect Client Interface 83
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace This is the input buffer for a message from the IMS
Connect Client000060 000000B2 00500000 5CE2C1D4 D7D3E55C 00000000
00001000 C8E6E2E3 C5E2E3F1
*.....&..*SAMPLE*........HWSTEST1*000080 00200040 E3D9C1D5
F0F0F0F1 C9C4E2C4 C5E2E3F1 40404040 40404040 E4E2C3D9 *...
TRAN0001IMSDEST1 USER*0000A0 F0F0F0F1 40404040 40404040 5C5C5C5C
5C5C5C5C 005A0000 E3D9C1D5 F0F0F0F1 *0001
********.!..TRAN0001*0000C0 40839389 A2A34040 40404040 40404040
40404040 40404040 40404040 40404040 * ..... *0000E0 40404040
40404040 40404040 40404040 40404040 40404040 40404040 40404040 *
*000100 40404040 40404040 40404040 40400004 00000000 00000000
00000000 00000000 * ..................*000120 00000000 00000000
00000000 00000000 00000000 00000000 00000000 00000000
*................................*000140 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*000160 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*000180 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*0001A0 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*0001C0 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*0001E0 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*... The format is
LLLLLLZZirmLLZZtrancode datasuffix The ******** at offset x00AC is
IMS Connect overlaying the input password This occurs even if the
prefix is not an IRM If this was input from ITRA the OTMA prefix
would have been pre- built An Overview of the IMS Connect Client
Interface 84
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace This is the output buffer to OTMA in the ITOCRC
record000300 01400000 00000000 00000000 0000A0F0 00000000 00000708
00000000 00010000 *. .............0................*000320 00480020
00400000 00000000 00000000 00000000 00000000 00000000 00000000
*..... ..........................*000340 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00004040
*.............................. *000360 40404040 40400000 006AC614
0902E4E2 C5D9F0F0 F0F10903 40404040 40404040 * ....F...USER0001..
*000380 00000000 00000000 00000000 00000000 00000000 00000000
00000000 00000000 *................................*0003A0 00000000
00000000 00000000 00000000 00000000 00000000 00000000 00000000
*................................*0003C0 00000000 00000000 00000000
00000000 00000100 0000C9C4 E2C4C5E2 E3F10000
*......................IMSDEST1..*0003E0 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*000400 00000000 00005C5C 5C5C5C5C
5C5C1000 00000000 00004040 40404040 40400000
*......********........ ..*000420 00000200 00000000 00000000
00004040 40404040 40400000 00000000 00000000 *..............
..........*000440 00000000 00000000 00000000 00000000 00000000
00000000 00000000 00000000 *................................*000460
00000000 00000000 00000000 00000000 00000000 00000000 00000000
00000000 *................................*000480 00000000 00000000
00000000 00000000 00000000 00000000 00000000 00000000
*................................*0004A0 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*0004C0 00000000 00000000 00000000
00000000 0000005A 0000E3D9 C1D5F0F0 F0F140C4
*...................!..TRAN0001 D*0004E0 C1E2C140 40404040 40404040
40404040 40404040 40404040 40404040 40404040 *ATA *000500 40404040
40404040 40404040 40404040 40404040 40404040 40404040 40404040 *
*000520 40404040 40404040 40404040 00000000 00000000 00000000
00000000 00000000 * ....................*000540 00000000 00000000
00000000 00000000 00000000 00000000 00000000 00000000
*................................*000560 00000000 00000000 00000000
00000000 00000000 00000000 00000000 00000000
*................................*000580 00000000 00000000 00000000
00000000 00000000 00000000 00000000 5CC5D5C4
*............................*END* The format is OTMALLZZtrancode
data The ICON OTMA User Data is mapped in macro HWSOMPFX Record is
written before key fields are been valued by IMS Connect You will
have to look in the ITOCSN record or OTMA TPIPE trace to see them
An Overview of the IMS Connect Client Interface 85
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace This is the output buffer to the IMS Connect Client
in the ITOCSN message 000300 00540300 C940D3D6 E5C540C9 D4E24040
40404040 40404040 40404040 40404040 *....I LOVE IMS * 000320
40404040 40404040 40404040 40404040 40404040 40404040 40404040
40404040 * * 000340 40404040 40404040 40404040 40404040 40404040
000C0000 5CC3E2D4 D6D2E85C * ....*CSMOKY** 000360 00000000 00000000
00000000 00000000 00000000 00000000 00000000 00000000
*................................* 000380 00000000 00000000
00000000 00000000 00000000 00000000 00000000 00000000
*................................* ... 000580 00000000 00000000
00000000 00000000 00000000 00000000 00000000 5CC5D5C4
*............................*END* The format is LLZZreplyCSMOKY
This is what is sent from the IMS Connect sample user message exit
HWSSMPL0 There is no LLLL The output could be anything the client
understands It would be nice to pass back the input prefix for
correlation An Overview of the IMS Connect Client Interface 87
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace This is the prefix and input buffer from the ICON
Client for a Resume TPIPE00000 00000000 C9E3D6C3 D9C30052 00000877
14485764 0104212F 00000000 00000000
*....ITOCRC......................*00020 C3D3C9C5 D5E3F0F1 BB980D5C
B650B241 BB980D61 7CCA4E80 00000000 00000000
*CLIENT01...*.&...../@.+.........*00040 00000000 00000000
00000000 00000000 00000000 00000000 00000000 5CC9D7C2
*............................*IPB*00060 0000006C 00500000 5CE2C1D4
D7D3C55C 00000000 42FF0000 C3D3C9C5 D5E3F0F1
*...%.&..*SAMPLE*........CLIENT01*00080 004001D9 40404040
40404040 C4E2F140 40404040 C3D3C9C5 D5E3F0F1 40404040 *. .R DS1
CLIENT01 *000A0 40404040 40404040 40404040 40404040 40404040
00140000 40404040 40404040 * .... * This is the output buffer to
OTMA for the Resume TPIPE002E0 00000000 00000000 00000000 00000000
00000000 00000000 00000000 5CD6D7C2
*............................*OPB*00300 01100000 28000000 00000000
0000A0E0 00000000 00000000 00000000 00010000
*...............................*00320 000C0240 C3D3C9C5 D5E3F0F1
006AC614 09024040 40404040 40400903 40404040 *... CLIENT01..F... ..
*00340 40404040 00000000 00000000 00000000 00000000 00000000
00000000 00000000 * ............................*00360 00000000
00000000 00000000 00000000 00000000 00000000 00000000 00000000
*................................*00380 00000000 00000000 00000000
00000000 00000000 00000100 0000C4E2 F1404040
*..........................DS1 * The x01 at offset x0301 indicates
a command The x28 at offset x0304 is the Resume TPIPE on HOLDQ
command The TPIPE name is in the State data offset x0324 An
Overview of the IMS Connect Client Interface 88
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
Recorder Trace This is the prefix and start of the input buffer for
a Duplicate Client 00000 00000000 C9E3D6C3 E2D50052 00000877
14485757 0104212F 00000000 00000000
*....ITOCSN......................* 00020 C4C5D3C4 E4D4D4E8 BB980D5C
A3D50A62 00000000 00000000 BB980D5C A3D52C82
*DELDUMMY...*.N.............*.N..* 00040 00000000 00000000 BB980D5C
A4031B02 00010000 00000000 00000000 5CC9D7C2
*...........*................*IPB* 00060 01204000 28010000 00000000
0000A0E0 00000000 00000000 00000000 00010000 *..
............................* This is the output buffer for the
Duplicate Client As sent by the IMS Connect sample user message
exits The Return Code and Reason Code are at offset x0C in the
output message002E0 00000000 00000000 00000000 00000000 00000000
00000000 00000000 5CD6D7C2 *............................*OPB*00300
00140000 5CD9C5D8 E2E3E25C 00000008 00000038 00000000 00000000
00000000 *....*REQSTS*....................* An Overview of the IMS
Connect Client Interface 89
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 allows the Recorder Trace to optionally be run a BPE external
trace Out put goes to GDG data sets Old Record trace stopped when
the data set was full Requires additional setup Uses new commands
Uses new print facilities An Overview of the IMS Connect Client
Interface 90
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 BPE Recorder Define the GDG //STEP1 EXEC PGM=IDCAMS //SYSPRINT
DD SYSOUT=A //SYSIN DD * DEFINE GENERATIONDATAGROUP -
(NAME(IMSTESTL.RCTR.GDG01) - NOEMPTY - SCRATCH - LIMIT(255)) // An
Overview of the IMS Connect Client Interface 91
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 BPE Recorder Define the External Trace using the EXTTRACE
statement in the BPECFGxx member EXTTRACE(GDGDEF(
DSN(IMSTESTL.RCTR.GDG01) UNIT(SYSDA) VOLSER(000000) SPACE(1)
SPACEUNIT(CYL) BLKSIZE(32760) ) COMP(HWS) ) There are other
parameters They are documented in the System Definition manual An
Overview of the IMS Connect Client Interface 92
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 BPE Recorder Define the RCTR Trace using the TRCLVL statement in
the BPECFGxx member TRCLEV=(RCTR,NONE,HWS,EXTERNAL=YES) If you
specify NONE the trace will not be automatically started when IMS
Connect starts If specify LOW or MEDIUM or HIGH the trace will
automatically started every time IMS Connect is started You
probably do not want to do this If you do not specify EXTERNAL=YES
the trace will only be written to in-core trace tables An Overview
of the IMS Connect Client Interface 93
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 BPE Recorder Start the BPE Recorder Trace using the MVS modify
(F) commandF icon,UPDATE TRACETABLE NAME(RCTR) OWNER(HWS)
LEVEL(MEDIUM) EXTERNAL(YES) Stop the BPE Recorder Trace using the
MVS modify (F) command F icon,UPDATE TRACETABLE NAME(RCTR)
OWNER(HWS) LEVEL(NONE) EXTERNAL(YES) Display the status of the
trace using the MVS modify (F) command F HWS1,DISPLAY TRACETABLE
NAME(RCTR) BPE0030I TABLE OWNER LEVEL #PAGES EXT #ENTRIES #CYCLES
BPE0000I RCTR HWS MEDIUM 300 YES 4 0 BPE0032I DISPLAY TRACETABLE
COMMAND COMPLETED An Overview of the IMS Connect Client Interface
94
IMS Regional User GroupNew IMS Connect Recorder Trace Points F
HWS1,UPDATE TRACETABLE NAME(RCTR) OWNER(HWS) LEVEL(HIGH)
EXTERNAL(YES) IMS Client Connect IMS ICONTR ICONIS ICONRC Send 2 3
Tran Tran 1 No ICONIS/ICONIR TCP/IP User support for the SCI Msg
XCF interface (type-2 commands and Exit ODBM) Recv 5 Response
Response 6 ICONSN 4 ICONTS ICONIR 1 ICONTR Receive from TCP/IP 2
ICONRC User Msg Exit Receive 3 ICONIS Send to IMS 6 ICONTS TCP/IP
Send to Client 5 ICONSN User Msg Exit XMIT 4 ICONIR Receive from
IMS Benefit Additional trace points provide the ability to capture
client errors for improved problem determination and analysis The
use of BPE external tracing allows large amounts of data to be
captured An Overview of the IMS Connect Client Interface 95
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 BPE Recorder Print the RCTR Recorder Trace using IPCS //STEP01
EXEC PGM=IKJEFT01,REGION=0M,COND=(0,LT) //STEPLIB DD
DISP=SHR,DSN=IMSVS.ADFSRES //SYSTSPRT DD SYSOUT=* //IPCSPRNT DD
SYSOUT=* //IPCSPARM DD DISP=SHR,DSN=SYS1.PARMLIB //SYSTSIN DD *
ALLOC F(IPCSDDIR) DA(IMSTESTL.DDIR) SHR REUSE ALLOC F(INFILE)
DA(IMSTESTL.RCTR.GDG01.G0001V00) SHR REUSE IPCS NOPARM SETDEF
DSN(IMSTESTL.RCTR.GDG01.G0001V00) SETDEF NOPROBLEM PRINT NOTERMINAL
VERBX BPETRFM0 TRACE(TYPE(ALL)) END // An Overview of the IMS
Connect Client Interface 96
IMS Regional User GroupIMS Connect Recorder Trace IMS Connect
11 BPE Recorder Print the RCTR Recorder Trace using IPCS Each
physical record in the RCTR Recorder data set has a header (ETHD)
and multiple trace records Each trace record has a header followed
by the record The record itself is the same 1440 byte record as for
the non-BPE recorder trace Except for the IR, IS, TR, and TS
records which are variable length The print utility prints all of
the headers and the data An Overview of the IMS Connect Client
Interface 97