Upload
ibm-ims
View
406
Download
7
Embed Size (px)
Citation preview
®
© 2014 IBM Corporation
IMS Connect Basics
Revision April 2016
2
IMS Connect Basics IMS OTMA Education®
Agenda IMS Connect
– Clients– Connections– Message Types
IMS Connect Parameters IMS ICON-ICON Communication IMS MSC TCP/IP IMS Connect Timeout IMS Connect and TCP/IP IMS Connect Initialization Exit IMS Connect Commands IMS Callout IMS Connect Availability IMS Connect Performance
3
IMS Connect Basics IMS OTMA Education®
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
4
IMS Connect Basics IMS OTMA Education®
IMS Connect Basics
5
IMS Connect Basics IMS OTMA Education®
IMS Connect
IMS Connect runs as an BPE address space
Provides high performance communications between TCP/IP connections and IMS systems
o The user TCP/IP applications are IMS Connect Clients
Support for both IMS TM and IMS DB systems
Support for IMSplex environmentso IMS Intersystem Communication (ISC)
o IMS Multiple Systems Coupling (MSC)
o Open Database Manager (ODBM)
o Operations Manager (OM)
6
IMS Connect Basics IMS OTMA Education®
IMS Connect cont.
IMS Connect
– ICON accepts input messages from and sends output
messages to the IMS Connect Client
• Could be the IMS TM Resource Adapter (TM RA)
• 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)
• Other client options
7
IMS Connect Basics IMS OTMA Education®
IMS Connect cont.
IMS Connect
– Local option allows PC call from another address space
instead of using TCP/IP
• The IMS Connect Client must be on the same LPAR as IMS
Connect
– This is only used by IMS TM RA
• The interface is not published
8
IMS Connect Basics IMS OTMA Education®
IMS Connect Clients cont. There are different types of clients that
communicate with IMS Connect– DataPower
– SOAP Gateway (XML converters)
– IMS Transaction Message Resource Adapter (IMS TM RA)
– IMS Connect API
– Java clients using IMS Universal Drivers (JDBC or DLI)
– IMS Explorer for Administration
– User written TCP/IP clients
– RYO DRDA application
– Remote IMS Connect (ISC or MSC)
9
IMS Connect Basics IMS OTMA Education®
Dis
trib
uted
IMS Connect Clients
IMS TM Resource Adapter
SCI
OM
PC
z/OS 2
z/OS 1
XCF
XCF
XCF
IMS Connect
TCP/IP
SC I
User Written TCP/IP Client
IMS Explorer
IMS TM Resource Adapter
IMS SOAP
Gateway
DataPowerIMS Connect
API Clients
TCP/IP
IMS 1
IMS 2
IMS 3
IMS Connect
SC I
IMS R1
XCF
10
IMS Connect Basics IMS OTMA Education®
IMS Connect IMS Open Database
– IMS Connect is the TCP/IP portal for access to IMS data as well as IMS transactions
Universal
DB Resource
Adapter
J
C
A
1.5
T
C
P
I
P
WAS on Any Platform
S
O
A
P
LPAR Az/OS
Distributed
LPAR B
LPAR C
XCF
IMS DBCTL
IMS
PCSC I
ODBA
DLITCP/IP
JDBCTCP/IP
RYO DRDA Appl.
IMS DBCTL
IMS
PCSC I
ODBA
IMS Universal Drivers
LPAR A
IMS DB
CTL
IMS
PCSC I
ODBA
ODBM
IMS ConnectT
C
P
I
P
SC I
ODBM
ODBM
z/OS WAS Universal
DB Resource
AdapterJ
C
A
1.5
T
C
P
I
P
ODBA
PCSC I
Traditional ODBA
DLI
JDBCIMS Universal Drivers
Traditional ODBA
JEE
Non-JEE
Universal
DB Resource
Adapter
J
C
A
1.5
T
C
P
I
P
WAS on Any Platform
S
O
A
P
LPAR Az/OS
Distributed
LPAR B
LPAR C
XCF
IMS DBCTL
IMS
PCSC I
ODBA
DLITCP/IP
JDBCTCP/IP
RYO DRDA Appl.
IMS DBCTL
IMS
PCSC I
ODBA
IMS Universal Drivers
LPAR A
IMS DB
CTL
IMS
PCSC I
ODBA
ODBM
IMS ConnectT
C
P
I
P
SC I
ODBM
ODBM
z/OS WAS Universal
DB Resource
AdapterJ
C
A
1.5
T
C
P
I
P
ODBA
PCSC I
Traditional ODBA
DLI
JDBCIMS Universal Drivers
Traditional ODBA
JEE
Non-JEE
11
IMS Connect Basics IMS OTMA Education®
IMS Connect
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 IMS Control Region can connect to multiple ICON’s
– ICON and IMS can be on different LPARs in the same Sysplex
12
IMS Connect Basics IMS OTMA Education®
IMS Connect cont.XCF GROUP
GR1
XCF GROUPGR2
DS1
DS2
DS3
ICON1
DS1
DS2
DS3
ICON2
IMSAOTMANM=IMSAOTMA
MB1
MB2MB4MB5
IMSBOTMANM=IMSBOTMA
MB3
MB6
13
IMS Connect Basics IMS OTMA Education®
IMS Connect clientConcepts
14
IMS Connect Basics IMS OTMA Education®
IMS Connect 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 in many ways in IMS Connect
– You need to plan the Client ID naming scheme for your installation
15
IMS Connect Basics IMS OTMA Education®
IMS Connect Socket Types
– Transaction socket• Close (Disconnect) after each transaction or complete conversation
– Persistent socket• Connect once then multiple write/read iterations for multiple
transactions before Close (Disconnect)
16
IMS Connect Basics IMS OTMA Education®
IMS Connect Commit Modes and synchronization level
– Sync levels:• NONE (0)• CONFIRM (1)• SYNCPOINT (2) for use by IMS Transaction Message Resource
Adapter only (IMS TM RA)
– Commit-then-send (CM0) messages• Only has Sync level 1 (confirm)• IMS commits changes to IMS databases before sending a response
back to IMS Connect.• Undelivered messages stay queued in IMS
– Retrieved with a ResumeTPIPE request from client
17
IMS Connect Basics IMS OTMA Education®
IMS Connect Commit Modes and synchronization level
– Send-then-commit (CM1) messages• Sync level 0/1 (none/confirm)• IMS sends the response back to the client before committing the
changes to the IMS databases• Sync_level = none messages are discarded
– ABEND 119 only for IMS Connect failure• Sync_level = confirm messages result in ABEND 119
18
IMS Connect Basics IMS OTMA Education®
IMS Connect Resume TPIPE types for Commit-then-send (CM0)
messages– NOAUTO: Exhaust all the messages in the queue only when
the command is issued
– AUTO: Exhaust all the messages in the queue. After that, automatically deliver messages when they are placed on the queue
– SINGLE: Deliver one message in the queue when the command is issued
– SINGLEWAIT: Deliver one message automatically when a message is available in the queue. If no messages are on the queue, then wait for a message to be put on the queue and deliver it.
19
IMS Connect Basics IMS OTMA Education®
IMS Connect Timeout
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
20
IMS Connect Basics IMS OTMA Education®
IMS Connect Timeout cont.
IMS Connect Timeout– Timeout values can be
• .01 to .25 seconds by .01 second increments (1-25)
• .25 to 1 second by .05 second increments (25-40)
• 1 to 60 seconds by 1 second increments (40-100)
• 1 to 60 minutes by 1 minute increments (100-160)
• 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
21
IMS Connect Basics IMS OTMA Education®
IMS Connect Timeout cont. 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
22
IMS Connect Basics IMS OTMA Education®
IMS Connect Timeout conc.
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
23
IMS Connect Basics IMS OTMA Education®
IMS Connect Basic Message Flow
24
IMS Connect Basics IMS OTMA Education®
Non-conversational transaction, CM=1, sync level=noneClient IMS Connect IMS Application
LLLL IRM TRAN DATA
LLLL* DATA CSM
OTMA Prefix TRAN DATA TRAN DATA
DATAOTMA Prefix DATA
(2)Send
(10) Receive
Receive Send
Receive
Receive
(3)TransactionInserted to SMB
(6)Output Sent
MSGQ (4)GU Call…
ISRT to IOPCB(5)Sync Start
(8)Sync End
*HWSSMPL1 Only
OTMA Prefix Commit Confirmed Transactioncompletes
Note: For CM1, SL=None, IMS Connect does not send the reply message back to the client until IMS has sent the commit confirm message
MSG Q’d
(9)
Connect to Icon IP addr & Port
(1)STATE = RECV
STATE=CONN
STATE=XMIT
(7)
STATE=RECV
25
IMS Connect Basics IMS OTMA Education®
Non-conversational transaction, CM=1, sync level=confirmClient IMS Connect IMS Application
LLLL IRM TRAN DATA
LLLL* DATA CSM
OTMA Prefix TRAN DATA TRAN DATA
DATAOTMA Prefix DATA
(2)Send
(7)Receive
Receive Send
Send Receive
Receive
(3)TransactionInserted to SMB
(6)Output Sent
MSGQ (4)GU Call
ISRT to IOPCB(5)Sync Start
(9)Sync End
*HWSSMPL1 Only
OTMA Prefix Dealloc Confirmed
Transactioncompletes
LLLL IRM ACK
LLLL* RSM Dealloc Confirm
OTMA Prefix ACK
(8)Send Receive Send
Send(11)Receive (10)Dealloc Confirmed
(1), Connect to Icon Ip addr & Port STATE=RECV
STATE=CONN
STATE=XMIT
STATE=RECV
STATE=XMITSTATE=CONN
STATE=RECV
26
IMS Connect Basics IMS OTMA Education®
Conversational Transaction, CM=1, sync level=confirmClient IMS Connect IMS Application
LLLL IRM ACK
LLLL* DATA CSM
LLLL* DATA CSM
LLLL* RSM Commit Confirmed
OTMA Prefix DATALLLL IRM DATA
LLLL IRM ACK
LLLL IRM TRAN DATA OTMA Prefix TRAN DATA
OTMA Prefix DATA
OTMA Prefix ACK
OTMA Prefix DATA
OTMA Prefix ACK
OTMA Prefix Commit Confirmed
TRAN DATA
DATA
DATA
DATA
(1)Send
(6)Receive
(7)Send
(9)Send
(14)Receive
(15)Send
(18)Receive
Receive Send
Receive
Send
(2)Transaction Inserted to SMB
Send
Receive Send
ReceiveSend
SendReceive
Receive
Send
MSGQ
(5)Output sent
(10)Insert message to transaction
MSGQ
(13)Output sent
(17)Commit Confirmed
(3)GU Call…
(4)Sync Start
(8)Sync end
(11)GU Call…
ISRT to IOPCB(12)Sync Start
(16)Sync EndTransaction completes
ISRT to IOPCBReceive
27
IMS Connect Basics IMS OTMA Education®
Non-conversational transaction, CM=0, sync level=confirmClient IMS Connect IMS Application
LLLL IRM TRAN DATA
LLLL* DATA CSM
LLLL IRM ACK
OTMA Prefix TRAN DATA
OTMA Prefix ACK
TRAN DATA
DATAOTMA Prefix DATA
(2 )Send
(8) Receive
(9)Send
Receive Send
Send Receive
Receive Send
(3)TransactionInserted to SMB
(7)Output Sent
MSGQ
(10)Output Dequeued
(4)GU Call…
ISRT to IOPCB(5)Sync Start(6)Sync End
(7)Transaction completes
*HWSSMPL1 Only
MSGQ
(1), Connect to Icon Ip addr & Port
STATE=RECV
STATE=CONN
STATE=XMIT
STATE=RECV
(11) Timer PopsLLLL* RSM STATE=XMIT
STATE=RECV
(12) Receive
28
IMS Connect Basics IMS OTMA Education®
Send-only transaction, CM=0, sync level=confirmClient IMS Connect IMS Application
LLLL IRM TRAN DATA OTMA Prefix TRAN DATA TRAN DATA(2) Send Receive Send
(3)TransactionInserted to SMB
MSGQ (4)GU Call…
(5)Sync Start(6)Sync End
Transactioncompletes
Process
(1) Connect to Icon Ip addr & Port
STATE=RECV
STATE=RECV
Close Connection Close
29
IMS Connect Basics IMS OTMA Education®
Resume TPIPE - AUTOClient IMS Connect IMS
Connect
Send
ReceiveSend
(Receive)*
Resume Tpipe
ResponseACK
DEQ
Send
ReceiveSend
Receive
Response
ACK
Response
ACK
DEQ
DEQ
Asynchronousmessages in the queue
LastAsynchronousMessagein the queue
Connection remainsUntil user-timer supplied inIRM_TIMER value has expired
*Client can wait in RECEIVE status, and can receive anymessages that are placed on the asynchronous queue.
30
IMS Connect Basics IMS OTMA Education®
Resume TPIPE for clientx through IMS Connect for a message in IMS
Resume TPIPE with multiple IMS Connects (shared port)– With supermember support, Resume TPIPE requests can retrieve any of the
queued asynchronous messages regardless of the connection path– But… if multiple IMS systems are involved
• Implement Shared Queues to allow any IMS to deliver the message even if the IMS that originally created the message is unavailable
IMS2
IMS1TCP/IPLoad balancing or distribution mechanisms can pick either IMS Connect (A or B)
TCP/IPLoad balancing or distribution mechanisms can pick either IMS Connect (A or B)
IMS2
Regardless of which IMS Connect is used, the SM01 name is passedto either IMS with a request for messages for clientx and SM01.
IMS Connect A -ICONNA -PORT 9999
(supermember)- SM01
IMS Connect B
- SM01(supermember)
-ICONNB-PORT 9999
Shared msg queues
MSGx forclientx andSM01
clientx
31
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters• BPECFG
• HWSCFG
32
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
IMS Connect– IMS Connect runs as an MVS job or started task
– Controlled by two input files:
• BPECFG– Internal BPE trace parameters
– Special Exit Definitions
– BPE = Base Primitive Environment
– Provides common services such as dispatching, waiting , tracing, and exit manipulation
• HWSCFG– IMS Connect parameters
33
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
BPECFG– Internal trace parameters
• There is a shipped default set of parameters but they are not useful
• For problem determination you will be asked by Level 2 to change the parameters
– This just increases storage use – not CPU
– Use the changed parameters ALL OF THE TIME
• The only way to see these trace records was in an SVC dump
– It was VERY difficult to capture the dump at the exact time of the problem
– IMS Connect supports external trace data sets for internal IMS Connect
traces
• These traces are not documented and can only be used by Level 2
Reference material
34
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
BPECFG– VERY STRONGLY RECOMMEND internal trace parameters
TRCLEV=(*,HIGH,HWS,PAGES=300)TRCLEV=(*,HIGH,BPE,PAGES=300)
Reference material
35
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
BPECFG– Special exit definitions
• The format is – EXITMBR=(xxxxxxxx,HWS)
> xxxxxxxx is the name of a member in the ICON PROCLIB containing the EXITDEF statements
– Exit definition for the XML Adapter
• Member xxxxxxxx– EXITDEF(TYPE=XMLADAP,EXITS=(HWSXMLA0,ABLIM=8,COMP=HWS)
> TYPE=XMLADAP – required
> EXITS=(HWSXMLA0 – required
> ABLIM= Abend limit before the exit is disabled (0=none; 1-32,767=limit)
> COMP=HWS) – required
Reference material
36
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
BPECFG– Special exit definitions
• BPE exits are dynamically refreshable– The Adapater Exit may be refreshed
> F imscon, REFUSRX NAME(xmladap)
• The “XML Adapter” is the ICON exit which invokes the “XML Converters”
• The XML Converters are the application specific modules which convert UNICODE/XML to EBCDIC/MID for input messages and EBCDIC/MOD to UNICODE/XML for output messages
• New XML converters can be added by placing them in the ICON STEPLIB
• XML converters can be dynamically refreshed with a command
Reference material
37
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters HWSCFG
– HWS control card
• ID= Specifies the name of this ICON instance
• CM0ATOQ= Specifies the default name of the TPIPE which will hold messages that have been requeued due to CM0 ACK timeout and no Reroute TPIPE name was specified– This can be overridden at the DATASTORE level
• PSWDMC= (Y/N/R) – specifies if IMS Connect should support passwords in Mixed Case– The default is N
– If Y requires that RACF support mixed case passwords> RACF SETROPTS(MIXEDCASE)
> Use Mixed Case passwords if RACF is configured to use Mixed Case passwords
Reference material
38
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG– HWS control card
• RACF= (Y/N) - Specifies whether or not ICON should do
USERID/Password checking for each input message
– If Y requires USERID and Password in plain text in the input message
– If Y requires USERID and Password in a fixed place in the input prefix
– Much better to set the value to N and do RACF checking yourself in the
ICON User Message Exit
– Even if the value is Y the IMS Connect User Message Exit can set the
“Trusted User” flag and tell IMS Connect not to issue the RACF call
Reference material
39
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG– HWS control card
• RACF= (Y/N) - Specifies whether or not ICON should do
USERID/Password checking for each input message > Limited caching of RACF Utoken
> Consecutive requests on a persistent socket with the same
Userid/Passsword/Group
> Common cache can be used for userids across ALL sessions and ALL ports
Reference material
40
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– HWS control card (continued)
• RRS= Defines if RRS should be enabled
– This enables two-phase commit
– Requires that IMS, IMS Connect, and RRS all be on the same MVS image
– Uses Global Transaction (XA) on remote platforms
– Be VERY update-to-date with maintenance
Reference material
41
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– HWS control card (continued)
• SMEMBER= Specifes the OTMA “Super member” name for this
IMS Connect to join
– More later
• UIDCACHE= Specifies whether (Y) or not (N) IMS Connect should
cache RACF ACEEs The default is N
• UIDAGE= Specifies the aging value for cached RACF ACEEs
Reference material
42
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– HWS control card (continued)
• XIBAREA= Specifies the number of fullwords in the initialization
table
– The default is 20
– The maximum is 500
– This area can be processed by the IMS Connect Initialization Exit
– This area can be processed by the IMS Connect User Message Exits
Reference material
43
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– TCP/IP control card
• ECB= Performance enhancement if TCP/IP >= 3.7 (everyone is)– The default is N– Set it to Y
• EXIT= List of from 1 to 255 User Message Exits– This includes the IMS Connect sample exits and user written exits– Do not specify HWSJAVA0 for use by IMS TM Resource Adapter – it is
automatically loaded• HOSTNAME= TCP/IP Host name (TCP/IP JOBNAME)
– If there is only 1 TCP/IP stack ICON will connect to it and ignore this parameter
– If there are multiple TCP/IP stacks ICON will attempt to connect to the one in HOSTNAME> If that fails it will connect to the default TCP/IP stack
Reference material
44
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– TCP/IP control card
• IPV6= Use IPV6 if available
• Recommend to set this to Y even if you are not on IPV6 – it will improve
performance
• MAXSIZE= This specifies the maximum LLLL that can be specified
for an input message to IMS Connect
– More later
Reference material
45
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– TCP/IP control card (continued)
• MAXSOC= Maximum number of concurrent sessions for all of IMS Connect– This was previously documented as the maximum number of connections
per Port – which is incorrect– The actual number of connections will be less than this number – one
connection per port is used by IMS Connect as a listener connection– The default is 50– The maximum number is 65,535– The MAXSOCKETS parameter in the BPXPRMxx member in
SYS1.PROCLIB sets a limit for the total number of sockets in a system– The MAXFILEPROC parameter in the BPXPRMxx member in
SYS1.PROCLIB sets the maximum number of sockets for any job (e.g. ICON)
Reference material
46
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– TCP/IP control card (continued)
• NODELAY= Specifies (Y) if IMS Connect should use the
TCP_NODELAY option for the USS SETSOCKET interface call
– A value of ‘Y’ will disable the “Nagle Algorithm” which adds a 0.2 second
delay before sending subsequent partially filled packets to the end user
> Disabling the algorithm could result in increased throughput and decrease output
message response time
– The default is ‘N’
Reference material
47
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– TCP/IP control card (continued)
• PORTAFF=
– IMS Connect allows “duplicate” client ID’s if each one is sending in
messages on a different Port
– When CM0 output is received IMS Connect will use the PORTID in the
OTMA User data to find the Client but only if PORTAFF=Y is specified
– The default is PORTAFF=N – IMS Connect will start with the first Port and
sequentially scan them trying to find the Client ID
Reference material
48
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– TCP/IP control card (continued)
• PORTID= List of from 1 to 50 ports for ICON to listen on– To enable the local option you must include “LOCAL” as a port– WARNING: McAFee AntiVirus V8 blocks IRC ports 6666, 6667, 6668,
6669, 6670, 7000, and 8080 by default– TCP/IP says that multiple ports are really not needed for performance
> But they can be useful for availability> IMS Connect has one TCB per port
– Multiple ports can also affect duplicate client ID’s> IMS Connect currently allows the same client ID on different ports
– Multiple ports can also affect asynchronous output> The OTMA DRU exit can specify a specific port for an asynchronous output
message (see the PORTAFF parameter)– Two IMS Connect copies on the same MVS can share a port
Reference material
49
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– TCP/IP control card (continued)
• PORT=(ID=xxxx,KEEPAV=nn,EDIT=xxxxxxxx)– This is an alternate was of defining Ports to ICON– A Port can not be listed in both PORTID and PORT– There can be multiple PORT statements – one for each Port – up to 50– ID is the Port number– KEEPAV is the override value, in seconds, for the TCP/IP default
keepalive value> This is the value that tells TCP/IP how long to wait before telling IMS Connect
that a TCP/IP session has gone away> The TCP/IP default can be very long and IMS Connect will not know that a
session as ended
Reference material
50
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– TCP/IP control card (continued)
• PORT=(ID=xxxx,KEEPAV=nn,EDIT=xxxxxxxx)– EDIT=xxxxxxxx is the name of an exit to edit the input and output
data from this Port before and after it is processed by IMS Connect
– This allows the IMS Connect Client to send in any data stream, e.g. Pure XML (), and not have to conform to IMS Connect format – but LLLL is required> The exit can add LLZZPrefix, LLZZTrancode, etc.
– The exit can also reformat the output data> Remove IMS and IMS Connect artifacts
– The exit can be dynamically refreshed via command
Reference material
51
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters HWSCFG (continued)
– TCP/IP control card (continued) > CEE.SCEERUN
• RACFID= Default RACF ID to assign to messages• SSLENVAR= Member name of the SSL initialization file
– SSL support is based on SSL for z/OS key management– STEPLIB must include:
> SYS1.CSSLIB> GSK.SGSKLOAD> Make sure you are completely up-to-date on maintenance if you are going to use
SSL with IMS Connect– See the RUNOPTS card for additional SSL parameters
• SSLPORT= List of 1 Port for ICON to listen with SSL– It is highly recommended to use the z/OS SSL support for TCP/IP
> “Application Transparent Transport Layer Security” (AT-TLS)> The User Message Exit is allowed to query the AT-TLS socket attributes> Then IMS Connect can listen on multiple ports using SSL
Reference material
52
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– TCP/IP control card (continued)
• TIMEOUT= Default time interval in hundredths of a second after which ICON times out a client if there is no response from IMS– Range = 0 to 2,147,483,647
– The default is 0 (no timeout)
– The default timeout value can be overridden by the IMS Connect client on a message by message basis
– This value will also timeout a client that has connected to IMS Connect but never sent a message> Once a client has connected and sent in a message IMS Connect will not timeout
waiting for new input messages or ACKs
Reference material
53
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters HWSCFG (continued)
– TCP/IP control card (continued) • WARNSOC=nn,WARNINC=nn
• WARNSOC > Decimal value between 50 and 99 (default 80)> Sets a warning level as a % of the MAXSOC limit> New message issued HWSS0772W when the warning value is reached
– WARNINC> Decimal value between 1 and 50 (default 5)> Sets the incremental warning % after WARNSOC has been reached> Re-issues HWSS0772W each time sockets increase by nn%
– Existing message HWSS0771W is issued when MAXSOC is reached– Message HWSS0773I is issued when the number of sockets falls back
below the warning level> The message trigger is the lower of two times the WARNINC value
below the WARNSOC value or 5% below the WARNSOC level
Reference material
54
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters HWSCFG (continued)
– TCP/IP control card (continued)
• IMS Connect will automatically reconnect to TCP/IP when the stack
becomes available after a failure
• There is loop and timer logic for each active Port
– Invoked if Port is terminated due to a failure
– Internally issues an OPENPORT command
– Loops back to timer delay if network is still not available
– Issues message HWSS0780I for each Port that is successfully reactivated
Reference material
55
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters HWSCFG (continued)
– RUNOPTS control card• RUNOPTS=
– 1-255 character string that specifies the Language Environment (LE) runtime options in support of SSL> IMS Connect passes a fixed length string of runtime options to the Language
Environment preinitialization program interface (CEEPIPI) – The default is
POSIX(ON),ALL31(ON),ANYHEAP(1M,1M,ANY,KEEP), BELOWHEAP(256K,512K,FREE),HEAP(1M,1M,ANY,FREE), LIBSTACK(9K,9K,FREE),STACK(256K,128K,ANY,FREE), ENVAR("_CEE_ENVFILE=/SYSTEM/etc/profile"), TRAP(ON,NOSPIE),TERMTHDACT(UAIMM)
Reference material
56
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– DATASTORE control card
• 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
• ID= The logical datastore name
– This is what is passed by the IMS Connect client to identify the IMS copy
to receive the message
– It can be set/overridden by the IMS Connect User Message Exit
Reference material
57
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– DATASTORE control card (continued)
• GROUP= Name of the XCF group to join for this connection
• TMEMBER= XCF member name of the IMS to connect to for this datastore– There can be multiple DATASTORE cards
– Each DATASTORE is an OTMA client (TMEMBER)
• MEMBER= XCF member name of ICON for this connection
– This is the OTMA Client name (TMEMBER)
Reference material
58
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– DATASTORE control card (continued)
• ACKTO=nnnn
– Specifies the default time in seconds (0-255) for OTMA to wait for an
ACK/NAK or syncpoint completion for a CM1 transaction from this
datastore (TMEMBER) before abending the IMS transaction
Reference material
59
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– DATASTORE control card (continued)
• APPL= Default RACF APPL name for PassTickets
– This can also be set on a message by message basis in the IMS Connect
User Exit (OMUSR_APPL_NM)
> It can be passed by the IMS Connect Client (IRM_APPL_NM)
> The IMS Connect sample exits will use this passed value
– This parameter can also be used to verify the User’s authority to access
IMS Connect even if PassTickets are not being used
> It is always passed on the RACROUTE VERIFY by IMS Connect if RACF=Y
> Examples of how to do this are shown in the next few foils
Reference material
60
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– DATASTORE control card (continued)
• APPL= example
– Define Datastore cards
> DATASTORE ID=IMSA,APPL=DFLTREAD...
> DATASTORE ID=IMSB,APPL=DFLTNONE...
> DATASTORE ID=IMSC,APPL=NOPROF
> DATASTORE ID=IMSD... (no default APPL defined)
– The IMS Connect User Exit does not override these values
> Always sets OMUSR_APPL_NM to blanks
Reference material
61
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– DATASTORE control card (continued)
• APPL= example (continued)– Define RACF profiles
> RDEFINE APPL DFLTREAD UACC(READ)> RDEFINE APPL DFLTNONE UACC(NONE)
– For the default UACC(READ) define users who ARE NOT allowed to access this DATASTORE > PERMIT DFLTREAD ID(USERBAD) CLASS(APPL) ACCESS(NONE)
– For the default UACC(NONE) define users who ARE allowed to access this DATASTORE > PERMIT DFLTNONE ID(USERGOOD) CLASS(APPL) ACCESS(READ)
– If no profile is defined or a blank APPL name is passed to RACF the default is that the user is allowed access
Reference material
62
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters HWSCFG (continued)
– DATASTORE control card (continued)• APPL= example (continued)
– Based on the previous example:– USERGOOD
> IMSA – access allowed> IMSB – access allowed> IMSC – access allowed> IMSD – access allowed
– USERBAD> IMSA – access denied> IMSB – access denied> IMSC – access allowed> IMSD – access allowed
– USER123> IMSA – access allowed> IMSB – access denied> IMSC – access allowed> IMSD – access allowed
Reference material
63
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)
– DATASTORE control card (continued)
• CM0ATOQ= Specifies the name of the TPIPE which will hold
messages that have been requeued due to CM0 ACK timeout and
no Reroute TPIPE name was specified
– This overrides the value on the HWS control card for this Datastore
• DRU= Name of the OTMA DRU exit for messages destined for this
OTMA client
• MAXI= Specifies the OTMA Message Flood limit
Reference material
64
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– DATASTORE control card (continued)
• OAAV= specifies the OTMA ACEE timeout value (in seconds) for this datastore (OTMA client)– How long should OTMA keep an ACEE in its cache for a user before
expiring it and reverifying it
– There is one cache for each OTMA client (datastore)> A Userid could have different aging values for different OTMA clients
• The range is from 300 to 2,147,483,647 (68 years)– The maximum is 999,999 (11.5 days)
• The default is the maximum
• If 0 is specified the maximum will be used
• If 1-299 is specified the minimum will be used
Reference material
65
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– DATASTORE control card (continued)
• RRNAME= Default “Reroute” name
Default TPIPE name where OTMA will route undeliverable or NAK’ed CM0 IOPCB output
–This can be overridden on a message by message basis
–See Part 4 for more details
• SMEMBER= Specifes the OTMA “Super member” name for this IMS Connect to join This overrides the value on the HWS control card for this datastore
Reference material
66
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– IMSPLEX control card
• Specifies each IMSPLEX that ICON talks to via SCI• MEMBER= Member name of ICON for this connection• TMEMBER= SCI name for this connection
– Can not be the same as a Datastore ID
• There can be multiple IMSPLEX cards• Used by the IMS Control Center running under DB2 UDB
Administration Client to route IMS Type-2 commands and responses– This is free– DB2 is not required– Include the SDFSRESL library in the IMS Connect STEPLIB
Reference material
67
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– ADAPTER control card
• Specifies which special adapters will be used
• XML= Specifies whether (Y) or not (N) the XML Adapter will be used
• MAXLSSSZ= Specifies the maximum language structure segment size– This value is passed to the XML converter when it is called
– Valid values are from 5 to 32,767
– This parameter is optional and defaults to 32,767
Reference material
68
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)ODACCESS control card
–Specifies the parameters for Open Database Access
• DRDAPORT parameter defines a Port that IMS Connect is listening on for ODBM access – there can be multiple DRDAPORTs– ID= Specifies the Port ID
– KEEPAV= Specifies the TCP/IP keepalive value in seconds for this Port
– PORTTMOT= Specifies the time in 100ths of a second that IMS Connect will wait for a response from ODBM
Reference material
69
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
HWSCFG (continued)– ODACCESS control card (continued)
• IMSPLEX parameter optionally defines the IMSPLEX for ODBM– if it is not defined then the IMSPLEX control card is used
– TMEMBER= Specifies the XCF member name of SCI
– MEMBER= Specifies the XCF name of IMS Connect for this connection
• ODBMAUTOCONN= Specifies whether (Y) or not (N) IMS Connect should automatically connect to new an existing instances of ODBM within an IMSPLEX
• ODBMTIOT= Specifies the time in 100ths of a second that IMS Connect will wait for– A response message on connections with ODBM
– An initial input message after a socket connection is established on connections with a client application
Reference material
70
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
ExampleHWS (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)
71
IMS Connect Basics IMS OTMA Education®
IMS Connect ParametersXCF GROUP
GR1
XCF GROUPGR2
DS1
DS2
DS3
ICON1
DS1
DS2
DS3
ICON2
IMSAOTMANM=IMSAOTMA
MB1
MB2MB4MB5
IMSBOTMANM=IMSBOTMA
MB3
MB6
72
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters /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
73
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters
/DIS OTMA GROUP/MEMBER XCF-STATUS USER-STATUS SECURITY TIB INPT SMEM DRUEXIT T/O GR2 -IMSBOTMA ACTIVE SERVER FULL-IMSBOTMA N/A 0 -MB3 ACTIVE ACCEPT TRAFFIC NONE 150 200 SM01 -MB3 ICONDRUY 10 -MB6 ACTIVE ACCEPT TRAFFIC CHECK 0 5000 SM01-MB6 ICONDRUY 10
74
IMS Connect Basics IMS OTMA Education®
IMS Connect Parameters /DIS TMEMBER MB1 TPIPE ALL (ON IMSA) MEMBER/TPIPE ENQCT DEQCT QCT INPCT STATUS SMEM ICON1 -5000 0 0 0 4956 TRA SM01 (CM1)-CLIENT1 23 22 1 1234 WAIT_A SM01 (CM0)-CLIENT2 15 0 15 45678 SM01 (CM0)
/DIS TMEMBER MB2 TPIPE ALL (ON IMSA) MEMBER/TPIPE ENQCT DEQCT QCT INPCT STATUS SMEM ICON1 -5000 0 0 0 4956 TRA SM01 (CM1)-CLIENT3 12 11 1 1234 WAIT_A SM01 (CM0)-CLIENT4 22 22 0 45678 SM01 (CM0)
/DIS TMEMBER MB3 TPIPE ALL (ON IMSA) MEMBER/TPIPE ENQCT DEQCT QCT INPCT STATUS SMEM ICON1 -5001 0 0 0 4956 TRA SM01 (CM1)-CLIENT02 99 98 1 1234 WAIT_A SM01 (CM0)-CLIENT03 15 0 15 45678 SM01 (CM0)
75
IMS Connect Basics IMS OTMA Education®
IMS Connect to IMS Connect Communications
76
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication
ISRT ALTPCB
IMS1
AppTMEMBER/TPIPE
DescriptorDESC1
TYPE=IMSCON TMEMBER=ICON1 RMTIMSCON= ICON2RMTIMS=IMS2 RMTTRAN=TRANABC USERID=USER01
ICON1
Local IMS Connect
WAIT_R
OTMAHDR | LLZZ | DATA
XCF
HWS=(ID=ICON1,XIBAREA=100,RACF=N)TCPIP=(HOSTNAME=TCPIP,PORTID=(8888), MAXSOC=50,TIMEOUT=5000, EXIT=(HWSSMPL0,HWSSMPL1)DATASTORE=(ID=IMS1,GROUP=XCFGRP1,MEMBER=ICON1,
TMEMBER=IMS1,DRU=HWSYDRU0,APPL=APPLID1)
RMTIMSCON=(ID=ICON2,HOSTNAME=ICON2.IBM.COM, PORT=9999,AUTOCONN=N,PERSISTENT=Y, IDLETO=60000,RESVSOC=10,USERID=USER01, APPL=APPL01)
IMS Connect provides a new configuration statement RMTIMSCON to describe the remote IMS Connect TCP/IP environment
ISRT ALTPCB
77
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication cont.
New RMTIMSCON statement in the local IMS Connect identifies the remote IMS Connect partner information– ID= Identifier for a remote IMS Connect connection – IPADDR= specifies the remote IMS Connect IP address (IPADDR or
HOSTNAME required, but not both) • Accepts a loopback IP address
– Local and remote IMS Connects are on the same TCP/IP stack (same LPAR)
– In the range 127.0.0.0 to 127.255.255.255– Likely used only in test environments
– HOSTNAME= specifies the remote IMS Connect hostname – PORT= specifies the remote IMS Connect port – AUTOCONN= Y|N, specifies whether to automatically make socket
connections to the remote IMS Connect on startup (optional - for OTMA only, MSC requires AUTOCONN=N)
– PERSISTENT= Y|N, specifies whether the socket connections to this remote IMS Connect are persistent (optional - for OTMA only, MSC requires PERSISTENT=Y)
78
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication cont.
New RMTIMSCON statement in the local IMS Connect identifies the remote IMS Connect partner information…
– IDLETO= specifies the amount of time the socket connection is idle before terminating it due to inactivity (Optional, for OTMA only)
– RESVSOC= specifies the number of sockets to reserve for use to this remote IMS Connect
– USERID= specifies user ID for generating RACF Passticket to be use by the remote IMS Connect for authenticating the user (optional – if specified, then APPL must also be specified.)
– APPL= specifies the application name for generating RACF Passticket to be use by the remote IMS Connect for authentication
• optional – if specified, then USERID must also be specified
RMTIMSCON=(ID=ICON2,HOSTNAME=ICON2.IBM.COM, PORT=9999,AUTOCONN=N,PERSISTENT=Y, IDLETO=60000,RESVSOC=10,USERID=USER01,APPL=APPL01)
79
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication cont.
IMS1
DescriptorDESC1
XCF
TCP/IP
ISRTALTPCB
App TMEMBER/TPIPE
Descriptors orDFSYDRU0 exit
D DESC1TMEMBER=ICON1RMTIMSCON=ICON2RMTIMS=IMS2RMTTRAN=TRANABCUSERID=USERXYZ
SendOnly with ACK
ICON1 configRMTIMSCON=(ID=ICON2,HOSTNAME=ICON2.IBM.COM,PORT=9999)
ICON2
WAIT_R
LLLL|IRM|LLZZ|TRANABC |DATA
HWS=(ID=ICON2,XIBAREA=100,RACF=Y)TCPIP=(HOSTNAME=TCPIP,PORTID=(9999),
MAXSOC=50,TIMEOUT=5000,EXIT=(HWSSMPL0,HWSSMPL1)DATASTORE=(ID=IMS2,GROUP=XCFGRP1,MEMBER=ICON2,
TMEMBER=IMS2,DRU=HWSYDRU0,APPL=APPLID1
ICON1
Remote IMS Connect Configuration
80
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication cont.
IMS1
IMS2DescriptorDESC1
XCF
XCF
TCP/IP
ISRTALTPCB
App TMEMBER/TPIPE
Descriptors orDFSYDRU0 exit
D DESC1TMEMBER=ICON1RMTIMSCON=ICON2RMTIMS=IMS2RMTTRAN=TRANABCUSERID=USERXYZ
Msg Q
SendOnly with ACK
ICON1 configRMTIMSCON=(ID=ICON2,HOSTNAME=ICON2.IBM.COM,PORT=9999)
ICON2 configTCPIP=(PORTID=(9999),...)DATASTORE=(TMEMBER=IMS2,...)
Tran AuthICON2
WAIT_R
OTMAHDR|LLZZ|TRANABC |DATA
ICON1
Send to Remote IMS
81
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication cont.
IMS1
ICON1
IMS2DescriptorDESC1
XCF
XCF
TCP/IP
ISRTALTPCB
App TMEMBER/TPIPE
Descriptors orDFSYDRU0 exit
Msg Q
SendOnly with ACK
Tran AuthICON2
ACK / NAK
WAIT_R
IMS2 performs transaction authorization, if necessary, and ACKs or NAKs the message
If a message is NAKed, the OTMA correlator token from the initial request is passed back so that IMS1 can match the NAK to the request
And finally – Return the ACK/NAK
82
IMS Connect Basics IMS OTMA Education®
IMS ICON-ICON Communication cont.
IMS1 IMS2
ICON1 configSMEM=SM01
ICON2 configSMEM=SM01
ICON3 configSMEM=SM01
SM01
Msg1Msg2Msg3
Msg1
Msg2
Msg3 Note: Maximum of 8 IMS ConnectsCan participate in a super memberenvironment
ACK
SM01 - ICON1 - ICON2 - ICON3
Descriptor DESC1:TMEMBER=SM01SMEM=Y
ICON1
ICON2
ICON3
ICON4
(Local IMS) (Local IMS Connect) (Remote IMS Connect) (Remote IMS)
– OTMA dynamically updates the super member list when a member of the group leaves or joins the group
Supermember Support
83
IMS Connect Basics IMS OTMA Education®
IMS MSC TCP/IP
84
IMS Connect Basics IMS OTMA Education®
IMS MSC TCP/IP
Support for MSC communications across a TCP/IP network– MSC TCP/IP leverages IMS Connect and the Common Service
Layer
– A new physical link MSPLINK TYPE=TCPIP • Provides a mechanism to
– Take advantage of TCP/IP networks – Complement or backup existing SNA/VTAM links – Take advantage of potentially higher bandwidths
• Supports operational compatibility with other link types (CTC, MTM, VTAM)– Starting, stopping, updating, displaying, and assigning resources
85
IMS Connect Basics IMS OTMA Education®
IMS MSC TCP/IP cont.
MSC TCP/IP leverages IMS Connect and the Common Service Layer
– IMS Connect sends/receives messages via the TCP/IP network
• IMS Connect manages the TCP/IP communications • IMS MSC manages the message processing
– CSL provides the Structured Call Interface (SCI) for communications between IMS components including IMS Connect (OTMA is not involved)
• Each IMS and its local MSC-routing IMS Connect system must be part of the same IMSplex
– IMSPLEX= plexname parameter in the Common Layer Section of the DFSDFxxx of IMS proclib
• The Operations Manager (OM) is not required but recommended– For type-2 command support
86
IMS Connect Basics IMS OTMA Education®
IMS MSC TCP/IP cont.
IMS to IMS Connect functionality – Isolates TCP/IP from the IMS Control Region
• Uses the existing IMS Connect TCP/IP support– Contains an MSC driver as well as TCP/IP driver for MSC
– Supports communication with IMS via the Structured Call Interface (SCI)
IMS1MSC
IMS3MSC
SCI TCP/IP
IMS2MSC
IMS Connect – ICON1
MSC
Driver
TCP/IPDriver
PLEX1 PLEX2
IMS Connect – ICON2
MSC
DriverTCP/IPDriver
SCI
87
IMS Connect Basics IMS OTMA Education®
IMS MSC TCP/IP cont.
Benefits– Takes advantage of TCP/IP networks for MSC
• Can potentially provide for a higher MSC bandwidth – Supports different configurations
• Coexistence with or backup of VTAM/SNA links • Increases availability
– Logical links can be moved between VTAM and TCPIP• Flexibility
zOS zOS
MSC TCPIP
MSC VTAM
MSC MTMMSC CTCIMSAIMSB
IMSC IMSD
88
IMS Connect Basics IMS OTMA Education®
IMS Connect and TCP/IP Considerations
89
IMS Connect Basics IMS OTMA Education®
IMS Connect and TCP/IP
IMS Connect Side Parameters
– KEEPALIVEOPTIONS
• The time in minutes to send a packet so that a connection does not
time out or to see if a TCP/IP client has gone away
– PORT
• Reserve ports for IMS Connect
– Be sure to include the NODELAYACKS parameter
90
IMS Connect Basics IMS OTMA Education®
IMS Connect and TCP/IP cont.
IMS Connect Side Parameters– SOMAXCONN
• This TCP/IP parameter tells TCP/IP the maximum number of Connect requests that can be queued in TCP/IP– If there are more Connect requests they are rejected– IMS Connect processes one Connect request at a time per Port– The minimum value will be 50
• IMS Connect V13 introduced the TCPIPQ parameter to specify the queue size.
– These parameters are specified in the PROFILE.TCPIP• All of the other options should be reviewed to make sure they are optimized
for the customer environment
91
IMS Connect Basics IMS OTMA Education®
IMS Connect and TCP/IP cont. TCP/IP Traces
– For difficult problems IMS Level 2 may request TCP/IP traces• Packet Trace• CTRACE
– Get to know and be on friendly terms with your TCP/IP systems programmer• Chocolate helps
– Set the trace on for only the IMS Connect ports – The output can be formatted with IPCS
// EXEC PGM=IKJEFT01,DYNAMNBR=100,REGION=3500K //IPCSDDIR DD DSN=USER1.IPCS.DUMPDIR,DISP=SHR //SYSPROC DD DSN=SYS1.SBLSCLI0,DISP=SHR //SYSTSPRT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * PROFILE MSGID IPCS NOPARM SETDEF DSN(‘USER1.PACKET.TRACE') LIST NOCONFIRM CTRACE COMP(SYSTCPDA) LOCAL FULL END /*
Reference material
92
IMS Connect Basics IMS OTMA Education®
IMS Connect and TCP/IP conc.
Automatic Reconnect to TCP/IP– IMS Connect will automatically reconnect to TCP/IP when the
stack becomes available after a failure
• Each active Port– Invoked if the connection to the Port is terminated due to a failure
– Internally issues an OPENPORT command
– Loops back to timer delay if network is still not available
– Issues message HWSS0780I for each Port that is successfully reactivated
93
IMS Connect Basics IMS OTMA Education®
IMS Connect User Exits
94
IMS Connect Basics IMS OTMA Education®
IMS Connect Initialization Exit
IMS Connect Initialization Exit– HWSUINIT
– Receives control during IMS Connect initialization and termination
– Can load modules and obtain storage• e.g. a common Security Exit for all ICON User Exits
– Passed the address of the XIB control block • This exit can set fields in this area for use by the ICON User Exits
– Passed the address of a 1K work area
– Passed the address of the XIBDS control block• This is a list of all datastores and their status• This exit can set fields in this table for use by the ICON User Exits
Reference material
95
IMS Connect Basics IMS OTMA Education®
IMS Connect Message Exits
HWSSMHWSSMPL0 - Provided with IMS Connect
HWSSMPL1 – Provided with IMS Connect
User Supplied Message Exits– Converts Client data to OTMA format on input
– Converts OTMA data to client format on output
– Receives control during IMS Connect input/output messages flow.
– Customizable
96
IMS Connect Basics IMS OTMA Education®
IMS Connect Commands
97
IMS Connect Basics IMS OTMA Education®
IMS Connect Commands
IMS Connect commands can be entered in three ways
1) Reply to the IMS Connect outstanding reply• R xx, VIEWHWS
2) MVS modify command• F icon,command• Command verbs are DELETE, QUERY, UPDATE, and
SHUTDOWN• Wildcard characters are supported
– ‘*’ matches 0 or more characters– ‘%’ matches exactly one character
98
IMS Connect Basics IMS OTMA Education®
IMS Connect Commands cont.
IMS Type-2 commands for IMS Connect resources– QUERY IMSCON
– UPDATE IMSCON
– Conform to the IMS command structure using the OM API• Processed by OM clients, e.g., TSO SPOC, REXX SPOC API, Batch
SPOC, IMS Control Center, etc.– Can coexist with the previous WTOR and z/OS Modify commands
• No changes to the existing command functionality
99
IMS Connect Basics IMS OTMA Education®
IMS Connect Commands
– TYPE = Type of resource in IMS Connect> ALIAS - aliases of associated ODBMs (VIEWIA) > CLIENT – active IMS Connect clients (no equivalent – information in
VIEWPORT) > CONFIG – IMS Connect status and activity (VIEWHWS)> DATASTORE – datastores or IMS systems (VIEWDS)> IMSPLEX – information about the IMSPLEX (VIEWIP)> LINK – MSC logical link (no equivalent)> MSC - MSC physical link (VIEWMSC - new for IMS to IMS TCP/IP
Communications)> ODBM – ODBMs and associated IMS aliases (VIEWOD)> PORT – TCPIP port and associated clients (VIEWPORT)> RMTIMSCON - remote IMS Connect and associated send clients (VIEWRMT -
new for IMS to IMS TCP/IP Communications)> SENDCLNT – send clients (no equivalent - new for IMS to IMS TCP/IP
Communications)> UOR - display unit of recovery identifier (VIEWUOR)
QUERY IMSCON TYPE(type) NAME(name1, name2,...) FILTER(filter)
SHOW(attribute(s))
100
IMS Connect Basics IMS OTMA Education®
IMS Connect Commands
– TYPE = Type of resource in IMS Connect> ALIAS - aliases of associated ODBMs (VIEWIA) > CLIENT – active IMS Connect clients (no equivalent – information in
VIEWPORT) > CONFIG – IMS Connect status and activity (VIEWHWS)> DATASTORE – datastores or IMS systems (VIEWDS)> IMSPLEX – information about the IMSPLEX (VIEWIP)> LINK – MSC logical link (no equivalent)> MSC - MSC physical link (VIEWMSC - new for IMS to IMS TCP/IP
Communications)> ODBM – ODBMs and associated IMS aliases (VIEWOD)> PORT – TCPIP port and associated clients (VIEWPORT)> RMTIMSCON - remote IMS Connect and associated send clients (VIEWRMT -
new for IMS to IMS TCP/IP Communications)> SENDCLNT – send clients (no equivalent - new for IMS to IMS TCP/IP
Communications)> UOR - display unit of recovery identifier (VIEWUOR)
UPDATE IMSCON TYPE(type) NAME(name1, name2,...)START(condition1,condition2,…)STOP(condition1,condition2,…) SET(condition1,condition2,…)
101
IMS Connect Basics IMS OTMA Education®
IMS Connect IMS Callout
.
102
IMS Connect Basics IMS OTMA Education®
IMS Callout Enable IMS applications as Service Requesters
– IMS Application can be an integration focal point in the enterprise– Interoperate with business logic outside the IMS environment
– Callout to Java EE apps (EJB and MDB) and Web Services using WebSphere Application Server and IMS TM Resource Adapter
– Callout to Web services providers (e.g. Microsoft .NET) using SOAP Gateway
– Callout to other applications
Two Flavors– Asynchronous
– Synchronous
103
IMS Connect Basics IMS OTMA Education®
Asynchronous Callout Asynchronous Callout
– IMS application invokes external applications without waiting for response.• DL/I ISRT ALTPCB • Destination can be
– Another IMS application (program switch)– An OTMA destination
> Sent to any OTMA clients, such as IMS Connect or WMQ > Tpipe name specified via DRU exits or OTMA descriptor.
– Any response sent back is a new transaction
104
IMS Connect Basics IMS OTMA Education®
Synchronous Callout Synchronous Callout
– IMS application invokes external application and waits for the response.• DL/I ICAL• Supports timeout capability and large messages• Secondary application is not in the same two-phase commit scope
– IMS application waits until the response is returned or the request receives a timeout
– Callout response is sent back to the same transaction that initiated it
105
IMS Connect Basics IMS OTMA Education®
IMS Asynchronous and Synchronous Callout
Sync Callout Response
Callout Request
Async Callout Response
IMS Application 1
IMS Application 2
Async: ISRT ALTPCBSync: ICAL
106
IMS Connect Basics IMS OTMA Education®
IMS application - DL/I ICAL
CALL 'AIBTDLI' USING ICAL, AIB, REQ-AREA, RESP-AREA.
where: • ICAL is the call verb (available on AIBTDLI only) and SENDRECV is the sub-function code• REQ-AREA is the Request data area for sync callout• RESP-AREA is the Response data area for returned data Note: REQ-AREA and RESP-AREA do not specify LLZZ, data can be > 32K
For example:
ICAL
IOAreas
107
IMS Connect Basics IMS OTMA Education®
IMS application - DL/I ICAL …
• AIB– AIBSFUNC = SENDRECV– AIBRSNM1 = 8 byte OTMA Descriptor name– AIBRSFLD = Timeout value
• 4 byte field for time value in 100th seconds. System default is 10 sec.
– AIBOALEN = Request area length• As an input parameter: 4 byte field contains the length of the request area• As an output parameter: Actual length of the response message updated
by IMS only when partial data is returned (AIB return code x'100', AIB reason code x'00C‘).
– AIBOAUSE = Response area length• As an input parameter: 4 byte field contains the length of the response
area• As an output parameter: Length of the response message placed in the
response area. When partial data is returned because the response area is not large enough, AIBOAUSE contains the length of data returned in the response area and AIBOALEN contains the actual length of the response message.
108
IMS Connect Basics IMS OTMA Education®
IMS application - DL/I ICAL… conc.
AIBFor example:
Descriptor name
Timeout
Request Area LengthResponse Area Length
Output return codes
109
IMS Connect Basics IMS OTMA Education®
Wrap up
.
110
IMS Connect Basics IMS OTMA Education®
IMS Connect Availability
There are many ways to design for availability with IMS Connect– Multiple IMS Connects on multiple LPARS can connect to
multiple IMS copies on multiple LPARS• The IMS copies can have shared queues and shared databases so
that any transaction can run on any IMS copy• The IMS Connect User Exit can be coded to route messages to
available IMS copies– IMS Connect supports VIPA and Dynamic VIPA
• There are considerations for Resume TPIPE and asynchronous output
– IMS Connect will work with SYSPLEX Distributor• Will work fine for CM1 messages and IOPCB output from CM0• Supports OTMA Supermember for Resume TPIPE and
asynchronous output and undeliverable output
111
IMS Connect Basics IMS OTMA Education®
IMS Performance
IMS Connect is very efficient– Average transit time for a message through IMS Connect is
1ms or less– Listening on multiple Ports can improve performance
• Each Port is a z/OS TCB– Each socket on a Port is an IMS Connect subtask
112
IMS Connect Basics IMS OTMA Education®
Conclusion
IMS Connect is being used in production in MANY installations with high availability and high performance
– There are many parameters and considerations for making this
work
– IMS Connect will continue to offer new functions and features