ims connect overview

®

© 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


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

5


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 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 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 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


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 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

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 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 clientConcepts

14


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 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 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 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 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 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 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 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 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 Basic Message Flow

24


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


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


(2)Send

(7)Receive

Receive Send

Send Receive

Receive


(6)Output Sent

MSGQ (4)GU Call


(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


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…


(16)Sync EndTransaction completes

ISRT to IOPCBReceive

27


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


(2 )Send

(8) Receive

(9)Send

Receive Send

Send Receive

Receive Send


(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


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


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


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


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 Parameters• BPECFG

• HWSCFG

32


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



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



BPECFG– VERY STRONGLY RECOMMEND internal trace parameters

TRCLEV=(*,HIGH,HWS,PAGES=300)TRCLEV=(*,HIGH,BPE,PAGES=300)

Reference material

35



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



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 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



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



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



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



HWSCFG (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



HWSCFG (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



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



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



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



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



HWSCFG (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




• 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




• 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




• 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 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




• 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



– 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 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



– 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



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



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



HWSCFG (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



HWSCFG (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



HWSCFG (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



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



– 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



HWSCFG (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




• 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




• 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



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



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



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



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



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=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=DS3,GROUP=GR2,MEMBER=MB6,TMEMBER=IMSBOTMA,DRU=ICONDRUY,ACKTO=10)

71


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 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



/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 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 to IMS Connect Communications

76


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 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



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



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



IMS1

IMS2DescriptorDESC1

XCF

XCF

TCP/IP

ISRTALTPCB

App TMEMBER/TPIPE


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



IMS1

ICON1

IMS2DescriptorDESC1

XCF

XCF

TCP/IP

ISRTALTPCB

App TMEMBER/TPIPE


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



IMS1 IMS2

ICON1 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 MSC TCP/IP

84


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 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 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



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 and TCP/IP Considerations

89


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 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 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 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 User Exits

94


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 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 Commands

97



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 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



– 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



– 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 IMS Callout

.

102


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


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


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 Asynchronous and Synchronous Callout

Sync Callout Response

Callout Request

Async Callout Response

IMS Application 1

IMS Application 2

Async: ISRT ALTPCBSync: ICAL

106


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 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 application - DL/I ICAL… conc.

AIBFor example:

Descriptor name

Timeout

Request Area LengthResponse Area Length

Output return codes

109


Wrap up

.

110


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 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


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

ims connect overview

Technology