IMS as a Client to New Systems - IMS Phoenix UG - June 19th, 2014
An overview of the ims connect client interface
Transcript of An overview of the ims connect client interface
©2012 IBM Corporation
An Overview of the IMS Connect Client Interface
IMS User Group
Steve [email protected]
2
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Disclaimer
© 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 IBM’S 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 Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate 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 IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml
3
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Agenda
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
4
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
5
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
6
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
7
IMS Regional User Group
An Overview of the IMS Connect Client Interface
SERVERz/OS,WIN,
AIX, SUN, …
SNA
z/OS
TCP/IP
ICON
OTMA
IMS
VTAM
IMS BRIDGE
MQSeries
LU1LU2
LU 6.1LU 6.2
XCF
AnyTCP/IP
App
RYOClient
TN3270
Websphere
MWS
PC
ICON
IMS BRIDGE
MQSeries
z/OS
XCF
XCF
ITRA
Websphere
PC
MQSeries
TCP/IP
Websphere
IMS TMResourceAdapter
End User
TCP/IPApplication
SCI
OM
IMS ControlCenter
BTAM <V10
VTAM
MFS WebServices
ITRA
IMS SOAPGateway
8
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 ICON’s– ICON and IMS can be on different LPARs in the same Sysplex
9
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 ID’s 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
10
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 ID’s will be ignored
11
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
12
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
13
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
• C’Z’ – no wait
– ICON may override
• x’FF’ – wait forever
• X’00’ – Use the default
– .25 seconds for Resume TPIPE and ACK
– HWSCFG TCPIP TIMEOUT parameter for messages
14
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Flow
IMS Connect Timeout– IMS Connect will only allow NOWAIT (c’Z’) for:
• SEND-ONLY message
• ACK/NAK for CM0 message
• ACK/NAK for Resume TPIPE option of SINGLE or SINGLE AUTO
– c’Z’ will be changed to x’00’ (use the default) for:• ACK/NAK for a conversational transaction
• Data (continue conversation)
• Transaction
• Resume TPIPE – Auto or NoAuto
– c’Z’ will be changed to x’19’ (.25 seconds) for:• ACK/NAK for CM1 SL1 message
• ACK/NAK for Resume TPIPE option of AUTO or NOAUTO
15
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Flow
IMS Connect Timeout– There are several Return Codes and Reason Codes passed to the
ICON Client after a timeout
• RC=x’20’ – A valid time has expired for a transaction socket
– The reason code is the value of the timer
– The socket is disconnected
• RC=x’24’ – An invalid or x’00’ timer has expired for a transaction socket
– The reason code contains the invalid value or x’00’
– The socket is disconnected
• RC=x’28’ – A timer has expired for a persistent socket
– The reason code is the value of the timer
– The socket is NOT disconnected
• RC=x’2C’ – A datastore has ended or a Client cancelled the timer
– The reason code is the value of the timer
16
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
17
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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)
18
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect FlowIMSA
OTMANM=IMSAOTMA
IMSBOTMANM=IMSBOTMA
XCF GROUPGR1
XCF GROUPGR2
DS1
DS2
DS3
ICON1
DS1
DS2
DS3
ICON2
MB1
MB2
MB3
MB4MB5
MB6
19
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
20
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
21
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 x’00’ 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
22
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Message Formats
The format of the input message from the ICON Client to
ICON is LLLLllzzPrefixDataSuffix
– Suffix
• X’00040000’
• 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
23
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 x’40’ 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
24
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
25
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
26
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
27
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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!!!
28
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
29
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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”
30
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
31
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 X'80' ASYNCH MSG Q'D IN IMS CSM_CONV EQU X'40' CONVERSATIONAL OUTPUT CSM_ACK_NAK EQU X'20' ACK/NAK REQUIRED CSM_PRLVLFLG EQU X'10' PROTOCOL LEVEL AVAILABLE CSM_PROTOLVL DS X IMS CONNECT PROTOCOL LEVEL CSM_PR00 EQU X'00' 00 - BASE PROTOCOL LEVEL CSM_PR01 EQU X'01' 01 - NOT USED CSM_PR02 EQU X'02' 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
32
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 X'80' ASYNCH MSG Q'D IN IMS RSM_CONV EQU X'40' CONVERSATIONAL OUTPUT RSM_ACK_NAK EQU X'20' 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
33
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect User Message Exits
IMS Connect User Message Exits
– Each exit gets control during ICON initialization and passes
ICON two 8 character ID’s 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
34
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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?
35
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
36
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect User Message Exits
IMS Connect supports “OTMA Degraded System Monitoring”– OTMA sends x’3C’ 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
37
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 CL4'XIB' 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 X'01' Arch Level 1 @PK70960 00280200 XIB_ARCH2 EQU X'02' 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 X'0A0100'=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
38
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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• X’00’ – Datastore is inactive and will require a STARTDS command to
connect• X’01’ - Datastore is active• X’02’ – 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 X'00' Data store not active in ICON * OPENDS command is required XIBDS_ACTIVE EQU X'01' Data store active in ICON * And IMS is active in XCF groupXIBDS_DISC EQU X'02' Data store disconnected * No OPENDS command is required XIBDS_FLAG DS X Data store entry flags XIBDS_LAST_ENTRY EQU X'80' Last entry in list DS XL2 Reserved XIBDS_USER DS XL4 User field
39
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 X'01' 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 X'80' Global flood warning XIBDS_ST_W1MTP EQU X'40' 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 X'08' Member TPIPE reached 100% XIBDS_ST_W4MTP EQU X'04' Member TPIPE reached 80% XIBDS_ST_AWE EQU X'02' Msg AWE reaches 80% flood XIBDS_ST_W4FLOOD EQU X'01' Member 80%+ flood XIBDS_ST_UTC DS CL12 UTC time for this status XIBDS_ST_LEN EQU *-XIBDS_ST_STATUS Length of OTMA Status
40
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
41
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
42
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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*
43
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
44
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
45
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
46
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
47
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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)
48
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
49
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
50
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 x’01’ input record
• It is the x’87’ 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
51
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect User Message Exits Saving and passing correlation data from/to the IMS
Connect client– This is the start of the x’01’ log record– The x’87’ APPC segment item starts a x’0090’ with the ll (x’026A’)– The OTMA prefix (DFSYMSG) starts at offset x’0128’
01 RECORD - 2008-08-11 13:41:34.744955 UTC00000000 03E00000 01D18194 04000016 04000016 03D01001 C9D4E2F1 40404040 C2D3F991 *.....JAM............IMS1 BL9J*00000020 0F3BFC2B C9D4E2F1 40404040 C2D3F991 0F3BFC2B 80000100 00000000 00000000 *....IMS1 BL9J................*00000040 00408100 88000000 00000000 00000000 00010000 00000000 00000000 00000001 *. A.H...........................*00000060 FDFFFFFF 262CE060 E3D9C1D5 F0F0F0F1 00000000 00000000 00000000 00000000 *.......-TRAN0001................*00000080 00108600 0350F400 00000000 00000000 026A8700 0040D580 85C60040 F9F9F9F9 *..F..&4...........G.. N.EF. 9999*000000A0 40404040 E3D9C1D5 F0F0F0F1 C2D3F991 0C334224 00000000 262CE060 C8E6E2E3 * TRAN0001BL9J...........-HWST*000000C0 F1E34040 40404040 40404040 C9D4E2F1 40404040 00000000 00000000 09100098 *1T IMS1 ...........Q*000000E0 00000000 00000000 00000000 00000000 00000000 00000000 262CE060 00000000 *...........................-....*00000100 00000000 C9D4E2F1 C8E6E2D4 E3C5E2E3 40404040 40404040 D7D3C5E7 00000000 *....IMS1HWSMTEST PLEX....*00000120 00000000 00000000 01400000 0000F9F9 F9F94040 4040A0F0 00000001 00000708 *......... ....9999 .0........*00000140 00000000 00010000 00481020 00400000 00000000 00000000 00000000 00000000 *............. ..................*00000160 00000000 00000000 00000000 0000C2D3 F99109E5 1DEE0000 00000000 00000000 *..............BL9J.V............*00000180 00000000 00004040 40404040 40400000 006AC614 0902E4E2 C5D9F0F0 F0F10903 *...... ....F...USER0001..*000001A0 40404040 40404040 51005001 80555555 55555555 55555555 55555555 55555555 * ..&.....................*000001C0 55555555 55555555 55555555 55555555 55555555 55555555 55555555 55555555 *................................*000001E0 55555555 55555555 555594A4 A0A2ADA1 A7155555 55555555 55550100 0000C9D4 *..........MU.S..X.............IM*00000200 E2C4C5E2 E3F1C3D3 D5E3F0F0 F0F1F9F0 F0F14040 4040C2D3 F99109C1 652E0000 *SDEST1CLNT00019001 BL9J.A....*00000220 00000000 00000000 00002754 CD480000 00000000 00001000 20000000 00004040 *.............................. *00000240 40404040 40400000 00000200 00000000 00000000 00004040 40404040 40400000 * ................ ..*00000260 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *................................*00000280 0000280 TO 000002C0 0002C0 SAME AS ABOVE000002E0 00000000 00000000 00000000 00000000 00000000 00000000 00000016 8800C1F1 *............................H.A1*
52
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
53
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
54
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 ACEE’s– Code STAT=NO for performance
• Use RACF LLA caching for performance
55
IMS Regional User Group
An Overview of the IMS Connect Client Interface
OTMA 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
56
IMS Regional User Group
An Overview of the IMS Connect Client Interface
OTMA 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
57
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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?
58
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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?
59
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
60
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
61
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
62
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS TM Resource Adapter
JEE/JCA Architecture
Application Contract
EIS-specific interface
ApplicationComponent
Security Management
ResourceAdapter(ITMRA)
Transaction Management
Connection Management
JEE Application Server(WAS)
EIS
System Contracts
Container-ComponentContract
SPI
CCI
63
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
64
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS TM Resource Adapter
ITRA Architecture
z/OS1
z/OS2
Linux for System z
Windows / AIX / Solaris / Linux
WebSphereApplication
ServerIMS Resource
Adapter
WebSphereApplication
Server
IMS ResourceAdapter
WebSphereApplication
ServerIMS Resource
Adapter
IMS
TCP/IP
XCF
XCF
IMS
IMS
IMS Connect
IMS Connect
IMS Connect
Local
65
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
66
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
67
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 application’s 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 user’s userID or password not used for SSL security
68
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS TM Resource Adapter ITRA is supported by RDz
PL/I is also supported by RDz
69
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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)
70
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
71
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
72
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
73
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect APIs Major Functionality from User’s 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
74
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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.*;
75
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
76
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
77
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
78
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
79
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
– Format is documented in IMS 12 Diagnosis manual
//S1 EXEC PGM=IDCAMS,REGION=4096K //SYSPRINT DD SYSOUT=* //SYSIN DD * PRINT IDS(USER1.RECORDER.TRACE) /*
80
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace– The first 96 bytes is the prefix
–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
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*
81
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
82
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace– The first 96 bytes is the prefix
–The time of the record is at offset x’10• X’HHMMSSTT’ local time
–The date of the record is at offset x’14’• x’CCYYDDDF’
– CC – Century – x’01’ = 21st century
– YY – Year
– DDD – Julian day
– F – Packed sign
–The Clientid is at offset x’20’
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*
83
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace–The first 96 bytes is the prefix
–The *IPB at offset x’003C’ indicates the Input Buffer follows
–The *OPB at offset x’02FC’ indicates that the Output Buffer follows
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*
0002E0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 5CD6D7C2 *............................*OPB*
84
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace–This is the input buffer for a message from the IMS Connect Client
–The format is LLLLLLZZirmLLZZtrancode datasuffix–The ‘********’ at offset x’00AC’ 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
000060 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 *................................* ...
85
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace IMS Connect Recorder Trace
–This is the output buffer to OTMA in the ITOCRC record
–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
000300 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*
86
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace–This is the input buffer from OTMA in the ITOCSN message
–The format is OTMALLZZreply–The IMS Connect OTMA User Data is now complete
000060 01800000 0000F9F9 F9F94040 4040A0F0 00000001 00000000 00000000 00010000 *......9999 .0................* 000080 00481020 00404040 40404040 40400000 00000000 00000000 00000000 00000000 *..... ..................* 0000A0 00000000 0000C2D3 F99109E5 1DEE0000 00000000 00000000 00000000 00004040 *......BL9..V.................. * 0000C0 40404040 40400000 006AC614 0902E4E2 C5D9F0F0 F0F10903 40404040 40404040 * ....F...USER0001.. * 0000E0 51005001 80555555 55555555 55555555 55555555 55555555 55555555 55555555 *..&.............................* 000100 55555555 55555555 55555555 55555555 55555555 55555555 55555555 55555555 *................................* 000120 555594A4 A0A2ADA1 A7155555 55555555 55550100 0000C9D4 E2C4C5E2 E3F1C8E6 *......................IMSDEST1HW* 000140 E2E3C5E2 E3F1F9F0 F0F14040 4040C2D3 F99109C1 652E0000 00000000 00000000 *STEST19001 BL9..A............* 000160 00002754 CD480000 00000000 00001000 20000000 00004040 40404040 40400000 *...................... ..* 000180 00000200 00000000 00000000 00004040 40404040 40400000 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 *................................* 000200 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *................................* 000220 00000000 00000000 00000000 00000000 00000054 0300C940 D3D6E5C5 40C9D4E2 *......................I LOVE IMS* 000240 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 * * 000260 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 * * 000280 40404040 40400000 00000000 00000000 00000000 00000000 00000000 00000000 * ..........................* 0002A0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *................................* 0002C0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *................................*
87
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace–This is the output buffer to the IMS Connect Client in the ITOCSN
message
–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
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*
88
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace–This is the prefix and input buffer from the ICON Client for a Resume
TPIPE
–This is the output buffer to OTMA for the Resume TPIPE
• The x’01’ at offset x’0301’ indicates a command
• The x’28’ at offset x’0304’ is the Resume TPIPE on HOLDQ command
• The TPIPE name is in the State data – offset x’0324’
00000 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 * .... *
002E0 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 *
89
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect Recorder Trace–This is the prefix and start of the input buffer for a Duplicate Client
–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 x’0C’ in the output
message
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 *.. ............\................*
002E0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 5CD6D7C2 *............................*OPB*00300 00140000 5CD9C5D8 E2E3E25C 00000008 00000038 00000000 00000000 00000000 *....*REQSTS*....................*
90
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
91
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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))//
92
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect 11 BPE Recorder
– Define the External Trace using the EXTTRACE statement in the
BPECFGxx member
– There are other parameters
• They are documented in the System Definition manual
EXTTRACE(GDGDEF( DSN(IMSTESTL.RCTR.GDG01) UNIT(SYSDA) VOLSER(000000) SPACE(1) SPACEUNIT(CYL) BLKSIZE(32760) ) COMP(HWS) )
93
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect 11 BPE Recorder
– Define the RCTR Trace using the TRCLVL statement in the
BPECFGxx member
– 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
TRCLEV=(RCTR,NONE,HWS,EXTERNAL=YES)
94
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect 11 BPE Recorder
– Start the BPE Recorder Trace using the MVS modify (F)
command
– Stop the BPE Recorder Trace using the MVS modify (F)
command
– Display the status of the trace using the MVS modify (F)
command
F icon,UPDATE TRACETABLE NAME(RCTR) OWNER(HWS) LEVEL(MEDIUM) EXTERNAL(YES)
F icon,UPDATE TRACETABLE NAME(RCTR) OWNER(HWS) LEVEL(NONE) EXTERNAL(YES)
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
95
IMS Regional User Group
An Overview of the IMS Connect Client Interface
ICONRC
TCP/IP
Client
IMS Connect IMS
SendTran
RecvResponse
UserMsgExit
Tran
Response
ICONSN
XCF
2
5
New IMS Connect Recorder Trace Points
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
F HWS1,UPDATE TRACETABLE NAME(RCTR) OWNER(HWS) LEVEL(HIGH) EXTERNAL(YES)
ICONTR ICONIS
ICONTS ICONIR
ICONTR – Receive from TCP/IP ICONRC – User Msg Exit Receive ICONIS – Send to IMS
ICONTS – TCP/IP Send to Client ICONSN – User Msg Exit XMIT ICONIR – Receive from IMS
1 3
46
1 2 3
456
No ICONIS/ICONIR support for the SCI interface (type-2 commands and ODBM)
96
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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 //
97
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS 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
98
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect 11 BPE Recorder
– Print the RCTR Recorder Trace using IPCS
• Physical record header (ETHD)
• These fields are not documented
----------------------------- --- HWS RCTR Trace Table --- ----------------------------- ETHD: 00000000 +0000 LL....... 7FA0 ZZ....... 0000 TYPE..... 01 SUBTYPE.. 02 VERSION.. 0001 RESERVED. 00000000 +000C NAME..... RCTR LENGTH... 00000080 UDATALEN. 00000000 TDATALEN. 00007F10 NUMPGS... 0014 ENTLEN... 0010 +0020 ENTSKPD.. 00000050 BVERS.... 010800 RESERVED. 00 UTYPE.... HWS UVERS.... 0C0100 RESERVED. 00 +0030 USYSNAME. UTRMOD... 00000000 00000000 FLG1..... 0A FLG2..... 00 LEVEL.... 04 +0043 IDX...... 13 CYCLECT.. 00000000 OFFSET... 00000000 BYTELOST. 000113D0 LDTO..... FFFFA21F 68400000 +0058 LSO...... 00000000 00000000 STCK..... C9F3719D 2B37DFA8 RESERVED. 00000000 NEXT..... 00000000 +0070 FIRST.... 44C2A390 TOKVAL... 00000000 ID....... ETHD END Flag analysis for ethd_flg1: ethd_f1_var (08x) - Trace type creates variable length entries ethd_f1_det (02x) - Trace type employs Direct Ext Trace Facility Trace level for this table is: HIGH ETSF: 00007F90 +0000 STCK..... C9F3719D 2B53E680 SEQNUM... 00000000 00041EB2 Variable trace table entries follow with oldest entry printed first
99
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect 11 BPE Recorder
– Print the RCTR Recorder Trace using IPCS
• Trace Record Header – one per trace record in the physical record
• These fields are not documented
RCTR trace table entry: Code: 00 Record #: 9921460 Subcode: 8B Continue: 0 TimeStmp: 213 142525.784445 TTVE: 00000000 Variable entry prefix: LL....... 05C0 REC#..... 009763B4 ZZ....... 05C0 CONT..... 00000000 VLEN..... 000005A0 TTE: 00000010 Variable entry fixed section: CODE..... 00 SCDE..... 8B B1B2..... 0000 WD01..... 000F0050 STCK..... C9F3719D 2B37DFA8 Data +00: |.......&I3.....y| Data: 00000020 Length: 1440
100
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace IMS Connect 11 BPE Recorder
– Print the RCTR Recorder Trace using IPCS
Variable entry variable section: Offset 0 4 8 C 0 4 8 C EBCDIC Data ------ ----------------------------------- ----------------------------------- ----------------------------------+000000 00000000 C9C3D6D5 E2D50052 00000877 14252578 0112213F 00000000 00000000 |....ICONSN......................|+000020 D6E3D4F0 F0F0F6F6 C9F3719D 2B36F6B6 00000000 00000000 C9F3719D 2B36FEB6 |OTM00066I3....6.........I3......|+000040 00000000 00000000 00000000 00000000 00010000 00000000 00000000 5CC9D7C2 |............................*IPB|+000060 01800000 0000F9F9 F9F14040 4040A0F0 00BF5A48 00000000 00000000 00010000 |......9991 .0..!.............|+000080 00481020 00004040 40404040 40400000 00000000 00000000 00000000 00000000 |...... ..................|+0000A0 00000000 0000C9F3 719D2A55 72B20000 00000000 00000000 00000000 00004040 |......I3...................... |+0000C0 40404040 40400000 006AC614 0902D6E3 D4F0F0F0 F6F60903 C8E6E2F1 D4C5D440 | ....F...OTM00066..HWS1MEM |+0000E0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +000100 TO +00011F SAME AS ABOVE +000120 00000000 00000000 00000000 00000000 00000100 0000C9D4 E9F14040 4040D6E3 |......................IMZ1 OT|+000140 D4F0F0F0 F6F6F9F9 F9F14040 4040C9F3 6DB1809D 8AB40000 00000000 00000000 |M000669991 I3_...............|+000160 0000453D A3480000 00000000 00001010 20000000 00004040 40404040 40400000 |....t................. ..|+000180 00000203 00000000 00000000 00004040 40404040 40400000 00000000 00000000 |.............. ..........|+0001A0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0001C0 TO +00021F SAME AS ABOVE +000220 00000000 00000000 00000000 00000000 00000053 0000C3D9 C5C4C9E3 40D3C9D4 |......................CREDIT LIM|+000240 C9E340D6 D2404040 40404040 40404040 40404040 40404040 40404040 40404040 |IT OK |+000260 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 | |+000280 40404040 40000000 00000000 00000000 00000000 00000000 00000000 00000000 | ...........................|+0002A0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0002C0 TO +0002DF SAME AS ABOVE +0002E0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 5CD6D7C2 |............................*OPB|+000300 00000063 00530000 C3D9C5C4 C9E340D3 C9D4C9E3 40D6D240 40404040 40404040 |........CREDIT LIMIT OK |+000320 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 | |+000340 40404040 40404040 40404040 40404040 40404040 40404000 0C10025C C3E2D4D6 | ....*CSMO|+000360 D2E85C00 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |KY*.............................|+000380 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0003A0 TO +00057F SAME AS ABOVE +000580 00000000 00000000 00000000 00000000 00000000 00000000 00000000 5CC5D5C4 |............................*END|
101
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace IMS Connect 11 BPE Recorder
– The ICONTR (TCP/IP Receive) record is variable length and has only an input buffer
– The prefix is only 64 bytes long– It shows the message exactly as it was received from TCP/IP
Variable entry variable section: Offset 0 4 8 C 0 4 8 C EBCDIC Data ------ ----------------------------------- ----------------------------------- ----------------------------------+000000 000000E8 C9C3D6D5 E3D94040 00000000 00000000 00000000 00000000 00000000 |...YICONTR ....................|+000020 00000000 00000000 C9F3719D 2B3C72B1 00000000 00000000 00000000 5CC9D7C2 |........I3..................*IPB|+000040 000000A8 00500000 5CE2C1D4 D7D3F15C 00000000 00001000 D6E3D4F0 F0F0F6F4 |...y.&..*SAMPL1*........OTM00064|+000060 00200040 C3D3C3D2 40404040 C9D4E9F1 40404040 40404040 40404040 D6E3D4F0 |... CLCK IMZ1 OTM0|+000080 F0F0F6F4 C8E6E2F1 D4C5D440 D6E3D4F0 F0F0F6F4 00500000 C3D3C3D2 40404040 |0064HWS1MEM OTM00064.&..CLCK |+0000A0 40E3F0F0 F0F0F0F5 F1F0F0F0 F4F1F6F9 F2404040 40404040 40404040 F1F8F6F4 | T000005100041692 1864|+0000C0 F6F5F340 40404040 40404040 40404040 40404040 40404040 40404040 40404040 |653 |+0000E0 40404040 00040000 | .... |
102
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace
IMS Connect 11 BPE Recorder– The ICONIS (IMS Send) record is variable length and has only an output
buffer
– The prefix is only 64 bytes long
– It shows the message exactly as it was sent to IMS
Variable entry variable section: Offset 0 4 8 C 0 4 8 C EBCDIC Data ------ ----------------------------------- ----------------------------------- ----------------------------------+000000 000002DA C9C3D6D5 C9E24040 00000000 00000000 00000000 00000000 00000000 |....ICONIS ....................|+000020 F9F9F9F1 40404040 C9F3719D 2B3D3732 00000000 00000000 00000000 5CD6D7C2 |9991 I3..................*OPB|+000040 01400000 0000F9F9 F9F14040 4040A0F0 00BF5A7B 00000000 00000000 00010000 |. ....9991 .0..!#............|+000060 00480020 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................|+000080 00000000 0000C9F3 719D2B3C ACB10000 00000000 00000000 00000000 00004040 |......I3...................... |+0000A0 40404040 40400000 006AC614 0902D6E3 D4F0F0F0 F6F40903 C8E6E2F1 D4C5D440 | ....F...OTM00064..HWS1MEM |+0000C0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0000E0 TO +0000FF SAME AS ABOVE +000100 00000000 00000000 00000000 00000000 00000100 0000C9D4 E9F14040 4040D6E3 |......................IMZ1 OT|+000120 D4F0F0F0 F6F4F9F9 F9F14040 4040C9F3 6DFDCBF2 94B60000 00000000 00000000 |M000649991 I3_..2m...........|+000140 0000455F 56400000 00000000 00001010 20000000 00004040 40404040 40400000 |...¬. ................ ..|+000160 00000203 00000000 00000000 00004040 40404040 40400000 00000000 00000000 |.............. ..........|+000180 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0001A0 TO +0001FF SAME AS ABOVE +000200 00000000 00000000 00000000 00000000 00000050 0000C3D3 C3D24040 404040E3 |...................&..CLCK T|+000220 F0F0F0F0 F0F5F1F0 F0F0F4F1 F6F9F240 40404040 40404040 4040F1F8 F6F4F6F5 |000005100041692 186465|+000240 F3404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 |3 |+000260 40400000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 | ..............................|+000280 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0002A0 TO +0002BF SAME AS ABOVE +0002C0 00000000 00000000 00000000 00000000 00000000 00000000 0000 |.......................... |
103
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace IMS Connect 11 BPE Recorder
– The ICONIR (IMS Receive) record is variable length and has only an input buffer
– The prefix is only 64 bytes long– It shows the message exactly as it was received from IMS
Variable entry variable section: Offset 0 4 8 C 0 4 8 C EBCDIC Data ------ ----------------------------------- ----------------------------------- ----------------------------------+000000 000002FC C9C3D6D5 C9D94040 00000000 00000000 00000000 00000000 00000000 |....ICONIR ....................|+000020 00000000 00000000 C9F3719D 2B55CA31 00000000 00000000 00000000 5CC9D7C2 |........I3..................*IPB|+000040 01800000 0000F9F9 F9F14040 4040A0F0 00BF5A79 00000000 00000000 00010000 |......9991 .0..!.............|+000060 00481020 00004040 40404040 40400000 00000000 00000000 00000000 00000000 |...... ..................|+000080 00000000 0000C9F3 719D2B3E 5DB10000 00000000 00000000 00000000 00004040 |......I3....)................. |+0000A0 40404040 40400000 006AC614 0902D6E3 D4F0F0F0 F3F60903 C8E6E2F1 D4C5D440 | ....F...OTM00036..HWS1MEM |+0000C0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0000E0 TO +0000FF SAME AS ABOVE +000100 00000000 00000000 00000000 00000000 00000100 0000C9D4 E9F14040 4040D6E3 |......................IMZ1 OT|+000120 D4F0F0F0 F3F6F9F9 F9F14040 4040C9F3 6DB1808C D6340000 00000000 00000000 |M000369991 I3_...O...........|+000140 0000453A 26400000 00000000 00001010 20000000 00004040 40404040 40400000 |..... ................ ..|+000160 00000203 00000000 00000000 00004040 40404040 40400000 00000000 00000000 |.............. ..........|+000180 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0001A0 TO +0001FF SAME AS ABOVE +000200 00000000 00000000 00000000 00000000 00000053 0000C3D9 C5C4C9E3 40D3C9D4 |......................CREDIT LIM|+000220 C9E340D6 D2404040 40404040 40404040 40404040 40404040 40404040 40404040 |IT OK |+000240 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 | |+000260 40404040 40000000 00000000 00000000 00000000 00000000 00000000 00000000 | ...........................|+000280 00000000 00000000 00000000 00000000 00000000 00000000 00000100 0000C9D4 |..............................IM|+0002A0 E9F14040 4040D6E3 D4F0F0F0 F3F1F9F9 F9F14040 4040C9F3 6DD7A67D B5B10000 |Z1 OTM000319991 I3_Pw'....|+0002C0 00000000 00000000 00004557 E0500000 00000000 00001010 20000000 00004040 |.............&................ |+0002E0 40404040 40400000 00000203 00000000 00000000 00004040 40404040 | ................ |
104
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Recorder Trace IMS Connect 11 BPE Recorder
– The ICONTS (TCP/IP Send) record is variable length and has only an output buffer
– The prefix is only 64 bytes long– It shows the message exactly as it was sent to TCP/IP
Variable entry variable section: Offset 0 4 8 C 0 4 8 C EBCDIC Data ------ ----------------------------------- ----------------------------------- ----------------------------------+000000 00000265 C9C3D6D5 E3E24040 00000000 00000000 00000000 00000000 00000000 |....ICONTS ....................|+000020 D6E3D4F0 F0F0F0F1 C9F3719D 2B56B130 00000000 00000000 00000000 5CD6D7C2 |OTM00001I3..................*OPB|+000040 00000063 00530000 C3D9C5C4 C9E340D3 C9D4C9E3 40D6D240 40404040 40404040 |........CREDIT LIMIT OK |+000060 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 | |+000080 40404040 40404040 40404040 40404040 40404040 40404000 0C10025C C3E2D4D6 | ....*CSMO|+0000A0 D2E85C00 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |KY*.............................|+0000C0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |................................| LINES +0000E0 TO +00025F SAME AS ABOVE +000260 00000000 00 |..... |
105
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Synchronous Callout
IMS Connect will support OTMA synchronous callout
via APARs PK70330 and PK74168
– IMS TM Resource Adapter support is APAR PK75460
– IMS Connect Extensions support is APAR PK74985
– APAR PM20541 (IMS 10) and PM20543 (IMS 11) has IMS
Connect notify OTMA if there is an error in the XML translation
instead of just discarding the message
• OTMA will notify the ICAL transaction immediately instead of waiting
for the timeout
106
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Synchronous Callout
IMS Connect will support OTMA synchronous callout
via APARs PK70330 and PK74168
– APARs PK75209 (IMS 10) and PK85023 (IMS 11) add support
for issuing ICAL from Java programs
– APAR PM39569 (IMS 12) will support Send-Only with ACK for a
Synchronous Callout Response Message
107
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Synchronous Callout
The IMS Connect Client is responsible for
maintaining the correlation token
– WAS/IMS TM Resource adapter
– IMS SOAP Gateway
– Roll-Your-Own (RYO) client
108
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Transaction Expiration
Input Message Expiration– Input message expiration = input message timeout
• Allows OTMA input messages to expire and be deleted prior to processing
• OTMA input messages can specify a timeout value in the OTMA header in one of two ways
– An expiration STCK time• Supported by IMS Connect
– An elapsed time value
• Implemented in IMS Connect via APAR PK74024 • IMS TM Resource Adapter support is provided by APARs PM01727
(IMS 10) and PM01822 (IMS 11)– A new transExpiration property is added to the interactionSpec class
109
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Transaction Expiration IMS Connect Clients using sample exits set x’01’ on
in flag IRM_F1– IRM_F1_TRNEXP– RYO exits will have their own method
IMS Connect User Message Exit sets flag OMHDRXP1 (x’01’) on in flag OMHDRIST
IMS Connect calculates the transaction expiry time based on the OTMA timeout value for the message– You can not explicitly specify the expiration time
IMS Connect passes a STCK Expiry time to OTMA
110
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Resume TPIPE No Message Notification
Resume TPIPE NoAuto
– TMAMCRHQ_NOAUTO – x’00’
• OTMA will send all the messages that are on the Asynchronous
output queue one at a time and then will stop when the queue is
empty
– It will take another Resume TPIPE to get more messages
• If there are no messages when the Resume TPIPE is issued nothing
happens
– The Resume TPIPE is ignored – there is no reply to the OTMA Client
that there are no messages – but this is now fixed – PK80756 will send
a protocol command indicating there are no more messages
– IMS Connect (PK80758) will issue an immediate timeout to the IMS
Connect Client
111
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Resume TPIPE No Message Notification
Resume TPIPE ONE
– TMAMCRHQ_ONE – x’01’
– OTMA will send one message from the Asynchronous output
queue and then will stop
• It will take another Resume TPIPE to get more messages
– If there are no messages when the Resume TPIPE is issued
nothing happens
– The Resume TPIPE is ignored – there is no reply to the OTMA Client
that there are no messages – but this is now fixed – PK80756 will send
a protocol command indicating there are no more messages
– IMS Connect (PK80758) will issue an immediate timeout to the IMS
Connect Client
112
IMS Regional User Group
An Overview of the IMS Connect Client Interface
Cancel Resume TPIPE
Cancel Resume TPIPE
– OTMA added a new command to allow an OTMA client to cancel
a Resume TPIPE (PK80756)
– IMS Connect (PK80758) will send in this command when an IMS
Connect Client waiting on a Resume TPIPE times out in IMS
Connect or when ICON notices that the Client has disconnected
– This allows a queued Resume TPIPE to be activated or allows
the TPIPE to be cleaned up
113
IMS Regional User Group
An Overview of the IMS Connect Client Interface
IMS Connect Client Considerations
There are MANY considerations when writing IMS
Connect clients