Configuring XML conversion support for IMS Connect clients

You must configure IMS Connect to convert the input and output messages between an IMS Connect client and an IMS application from XML to a language-specific structure, when the IMS Connect client is IMS Enterprise Suite SOAP Gateway.

1. Include the ADAPTER configuration statement, ADAPTER=(XML=Y), in the IMS Connect configuration member HWSCFGxx.
   Tip: You can increase the maximum number of XML converters that IMS Connect can load simultaneously with the MAXCVTR parameter of the ADAPTER statement. When your applications exceed the maximum number of allowable XML converters that are specified in MAXCVRT, IMS Connect unloads the least recently used XML converters first.
2. Specify the HWSSOAP1 user message exit in the EXIT= parameter of the TCPIP configuration statement.
3. Define the XML adapter as a BPE exit routine for IMS Connect by coding a BPE exit list IMS PROCLIB data set member and specifying it in the BPE configuration parameter IMS PROCLIB data set member:
   1. Create a BPE exit list IMS PROCLIB data set member with any name, for example HWSEXIT0.
      In the BPE exit list IMS PROCLIB data set member, define the XML Adapter (HWSXMLA0) as an exit by setting the following EXITDEF statement:

      EXITDEF(TYPE=XMLADAP,EXITS=(HWSXMLA0),ABLIM=8,COMP=HWS)

      All parameters must be coded as shown except for ABLIM, which sets the number of times the XML adapter can abend before it is disabled.
   2. Set the BPE exit list IMS PROCLIB data set member in the BPE configuration parameter IMS PROCLIB data set member by adding an EXITMBR statement.
      For example, if the BPE exit list IMS PROCLIB data set member is HWSEXIT0, then add the following statement to the BPE configuration member:

      EXITMBR=(HWSEXIT0,HWS)

4. Configure the z/OS® Unicode Conversion Services to support character conversions from UTF-8 to EBCDIC and from EBCDIC to UTF-8.
   Most likely, your z/OS system administrator performs this task. For more information about z/OS Unicode support, see z/OS Unicode Services User’s Guide and Reference.
5. Generate the XML converter to convert the XML data to the COBOL or PL/I data that the IMS application expects.
   XML converters are COBOL or PL/I application programs that are based on the COBOL copybook or PL/I source code of the IMS application program that processes the transactions between the IMS Connect client and the IMS application.

   The recommended method is by using the separately licensed tool IBM Developer for System z to generate the converters. Each IMS application requires a unique XML converter. For IMS Enterprise Suite SOAP Gateway, you can find an example of an XML converter in the IMS Enterprise Suite SOAP Gateway Phone Book Sample. You can download the sample from the IMS Enterprise Suite SOAP Gateway home page.

6. Compile and link the XML converter into an APF-authorized data set that is concatenated to the STEPLIB in the IMS Connect startup JCL.
   When linking the XML converter, specify an additional program entry name for an internal service as an ALIAS in the link job. The additional program entry name has the same name as the converter, except that the last character is an X. For example, if the converter name is CNVNAMED, the additional program entry name is CNVNAMEX.
7. If you are updating an existing converter, refresh it by issuing one of the following commands:
   • The z/OS Modify command UPDATE CONVERTER
   • The WTOR command REFRESH CONVERTER
   • The type-2 command UPDATE IMSCON TYPE(CONVERTER)
8. Configure your IMS Enterprise Suite SOAP Gateway and provide the generated XML converter.
   For detailed configuration instructions for IMS Enterprise Suite SOAP Gateway, see the XML-formatted IMS messages documentation.

***************************************************
* HWS EXAMPLE OF INCLUDING XML ADAPTER SUPPORT     
***************************************************
HWS=(ID=HWS8,RACF=Y,XIBAREA=20)
TCPIP=(HOSTNAME=MVSTCPIP,RACFID=RACFID,
PORTID=(9999,LOCAL),MAXSOC=2000,TIMEOUT=8800,
EXIT=(HWSSMPL1,HWSSOAP1))
ADAPTER=(XML=Y)
***************************************************

//COBLNK JOB (PLS,81038),'user',CLASS=A,REGION=4096K,
// MSGLEVEL=(1,1),MSGCLASS=A,NOTIFY=user
//*************************************************************
//* JOB TO COMPILE AND LINK A COBOL PROGRAM
//*************************************************************
//COMP EXEC PGM=IGYCRCTL
//STEPLIB DD DSN=COBOL.V3R4.X,DISP=SHR
//SYSIN DD DSN=COBOL.SOURCE(NNNNNNND),DISP=SHR
//SYSLIN DD DSN=&OBJ,SPACE=(3040,(40,40),,,ROUND),UNIT=VIO,
// DISP=(MOD,PASS),
// DCB=(BLKSIZE=3040,LRECL=80,RECFM=FBS,BUFNO=1)
//SYSUT1 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSUT2 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSUT3 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSUT4 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSUT5 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSUT6 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSUT7 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
/*
//**************************************************************
//LKED EXEC PGM=IEWL,COND=(4,LT,COMP),
// PARM='LIST,LET,XREF,MAP'
//SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR
// DD DSN=CEE.SCEEBIND,DISP=SHR
// DD DSN=CEE.SCEEBND2,DISP=SHR
//SYSLIN DD DSN=&OBJ,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//SYSLMOD DD DSN=IMSCONN.AUTHLIB,DISP=SHR
//SYSUT1 DD UNIT=VIO,SPACE=(1024,(120,120),,,ROUND)
//SYSPRINT DD SYSOUT=*
//LKED.SYSIN DD *
ENTRY NNNNNNND
ALIAS NNNNNNNX
NAME NNNNNNND(R)
/*