APPC/IMS Programming Considerations

This section is intended for application programmers who implement and integrate ATMI platform and host enterprise applications using Application Program-to-Program Communication/Information Management System (APPC/IMS) programs. The application programmer in the IMS environment can use implicit or explicit IMS programming techniques.

Note:

All references to ATMI files, functions, and documentation apply to Tuxedo files, functions, and documentation.

This section discusses the following topics:

•	APPC/IMS Overview

•	Implicit API

•	Explicit API

•	APPC/IMS Programming

•	Non-Transactional Application Programming

•	Transactional Application Programming

•	Sample Transaction Programs

APPC/IMS Overview

APPC/IMS allows application programs using APPC protocols to enter IMS transactions from LU 6.2 devices supporting APPC. APPC/IMS also provides an environment that enables remote LU 6.2 devices to enter IMS local and remote transactions. In this environment, IMS application programs can insert transaction output to LU 6.2 devices without requiring coding changes to existing application programs and new application programs can make full use of existing LU 6.2 facilities. Applications enter transactions using an implicit or explicit Application Programming Interface (API).

Implicit API

The implicit API can be a useful simplification for many applications. While it does not provide all the existing LU6.2 capabilities, this API provides additional functions, such as message queueing and automatic asynchronous message delivery.

Using the IMS application programming base with the implicit API, you can write transactional applications that do not have Common Programming Interface for Communications (CPI-C) calls. IMS generates all the CPI-C calls for you. The application interaction is strictly with the IMS message queue.

The implicit API accesses an APPC conversation indirectly. It uses the standard DL/I calls (GU, ISRT, PURG) to send and receive data. The implicit API allows non-LU 6.2 specific applications to use LU 6.2 transactional protocols, using new and changed DL/I calls (CHNG, INQY, SETO).

The implicit API creates asynchronous LU 6.2 output by using alternate PCBs referencing LU 6.2 destinations. The DL/I CHNG call can supply parameters to specify an LU 6.2 destination. Default values substitute for omitted parameters.

An application program can use the implicit API to retrieve the current conversation attributes, such as the conversation type (basic or mapped), the sync_level, and whether it is asynchronous or synchronous.

Explicit API

An IMS application program can use the explicit API to issue the CPI-C calls directly. The explicit API is useful with remote LU 6.2 systems that have incomplete LU 6.2 implementations, or that are incompatible with the IMS implicit API support.

The explicit API can be used by any IMS application program to access an APPC conversation directly. IMS resources are available to the CPI-C driven application program only if the application issues the APSB (Allocate_ PSB) call. The CPI-C driven application program must use the CPI-RR SRRCMIT and SRRBACK verbs to initiate an IMS sync point or backout.

APPC/IMS Programming

The Oracle Tuxedo Mainframe Adapter for SNA system supports non-transactional and transactional IMS servers using either the implicit APPC support for IMS or the explicit APPC interface using APPC/MVS calls from a user application. Any IMS program that gets messages from, and puts messages into, the IMS message queue can be used without change as either a client or server.

To use the implicit APPC capabilities of IMS, you must modify the APPCMxx file in the SYS1.PARMLIB library provided with your Oracle Tuxedo Mainframe Adapter for SNA software. The configuration parameters in this file associate the LU with the IMS scheduler. You must identify the LU representing the application name used by Oracle Tuxedo Mainframe Adapter for SNA to access the IMS region and the IMS system ID which provides scheduling for inbound requests. Be sure to discuss with mainframe support personnel the changes you make to the APPCMxx file.

Non-Transactional Application Programming

Listing 6‑1 is an example of a non-transactional program. In this example, the VTAM application major node is designated to be MVSLUO1 and the scheduling facility is designated to be the IMS control region IVP4.

Listing 6‑1 APPCM File in SYS1.PARMLIB Library (Example Only)

SYS1.PARMLIB(APPCMxx)

LUADD ACBNAME(MVSLU01) BASE TPDATA(SYS1.APPCTP),
SCHED(IVP4),
SIDEINFO DATASET(SYS1.APPCSI)

SYS1.VTAMLST(MVSLU01)

MVSLU01 APPL ACBNAME=MVSLU01, ACBNAME FOR APPC C
APPC=YES, C
AUTOSES=0, C
DDRAINL=NALOW, C
DLOGMOD=APPCHOST, C
DMINWNL=3, C
DMINWNR=3, C
DRESPL=NALLOW, C
DSESLIM=6, C
LMDENT=19, C
MODETAB=APPCTAB, C
PARSESS=YES, C
SECACPT=CONV, C
SRBEXIT=YES, C
VPACING=1

 

The job that starts the IMS subsystem should have the APPC parameter set to Y. The example in Listing 6‑2 illustrates such a job, but is not intended to be used under actual conditions. Use your own custom job for starting IMS.

Listing 6‑2 IMS Subsystem Start Job (Example Only)

PROC RGN=2000K,SOUT=A,DPTY='(14,15)',
SYS=,SYS1=,SYS2=,
RGSUF=IV1,PARM1=APPC=Y,PARM2=,APPLID1=IMS61CR1,AOIS=R IEFPROC EXEC PGM=DFSMVRC0,DPRTY=&DPTY,
REGION=&RGN,
PARM='CTL,&RGSUF,&PARM1,&PARM2,&APPLID1,&AOIS'
*
*
* THE MEANING AND MAXIMUM SIZE OF EACH PARAMETER
* IS AS FOLLOWS:
*
********** CONTROL REGION SPECIFICATIONS ***********
****************************************************
* RGSUF XXX EXEC PARM DEFAULT BLOCK SUFFIX FOR
* MEMBER DFSPBXXX.
****************************************************
*
* PARM1 , PARM2 PARAMETERS BOTH ARE USED TO SPECIFY
* CHARACTER STRINGS THAT CONTAIN IMS KEYWORD
*
* PARAMETERS. I.E. PARM1='AUTO=Y,PST=222,RES=Y'
*
*
* APPC X Y = ACTIVATE APPC/IMS
* N = DO NOT ACTIVATE APPC/IMS

 

Transactional Application Programming

Listing 6‑3 is an example of a transactional VTAM program. The inclusion of the LU definition SYNCLVL=SYNCPT (shown in bold) makes the program transactional.

Note:

You should include the ATNLOSS=ALL parameter value whenever you use the SYNCLVL=SYNCPT definition.

Listing 6‑3 Sample VTAM LU Definition

MVSLU01 APPL ACBNAME=MVSLU01, ACBNAME FOR APPC C
APPC=YES, C
AUTOSES=0, C
DDRAINL=NALOW, C
DLMOD=APPCHOST, C
DMWNL=5, C
DMINWNR=5, C
DRESPL=NALLOW, C
DSESLIM=10, C
LMDENT=19, C
MODETAB=APPCTAB, C
PARSESS=YES, C
SECACPT=CONV, C
SRBEXIT=YES, C
SYNCLVL=SYNCPT, C
ATNLOSS=ALL, C
VPACING=1

 

Sample Transaction Programs

The following Oracle Tuxedo Mainframe Adapter for SNA transactional test programs are installed in the ATMI platform installation in the subdirectory TMA/sna/simpapp:

•	simpims.c is a simple ATMI client used to invoke both the sample IMS server programs. It takes a data string and service name as inputs. It invokes the service and passes the input data string.

•	IMPIMSSV.cbl is a simple IMS echo server. It reads data from the IMS message queue and writes the same data in response. It is intended to be used as an implicit SNA example.

•	EXPIMSSV.c is an IMS server transaction using explicit CPI-C calls. It is written for sync level 2 use. The program uses an IBM sample database, IVPDB2. The program displays, adds, and deletes records from the database, based on an input string. Sample input strings are documented in the source.

•	BEAWTOR.asm is an assembler subroutine used by EXPIMSSV.c to write messages to the MVS console log.