BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
eLink Adapter for Mainframe Documentation | eLink Adapter for Mainframe User Guide | Previous Topic | Next Topic | Contents | Index

Verifying the Software

After installing and configuring the eLink Adapter for Mainframe software, verify the operational integrity of the environment by running a sample application on a simple server in client/server transaction scenarios. This process employs programs available in your product software libraries.

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

This section covers the following topics:

- Building Verification Tests

- Building ATMI Platform Executables

- Building CICS/ESA Executables

- Running the Sample Application

- Running the Application from an ATMI Client

- Running the Application from a CICS/ESA Client

- Running the Application from a CICS/VSE Client

The sample applications are located in the simple server library (eLink/sna/simpapp). The simple server passes a string from the client to the server.

The CICS/ESA programs may run as either DTP or DPL processes, and as either servers or clients. The simple server may also run in either transactional or non-transactional mode. In the transactional mode, these scenarios verify that the sync-level 2 protocol is established between the two application environments.

When the client runs as an ATMI client, the server runs as a CICS/ESA host. Enter a text string in lower-case letters with command arguments. The CICS/ESA server converts the lower-case letters to upper-case letters and re-displays the text string.

When the client runs as a CICS/ESA client, the server runs as an ATMI server. Again, enter a text string in lower-case letters. The ATMI server converts the text string into a mirror image and displays the string as reversed letters.

Note: The verification process is intended for the CICS/ESA environment only between ATMI applications and CICS/ESA applications. If your ATMI applications operate in other environments, you must create your own verification process. See the "APPC/IMS Programming Considerations" section.

Building Verification Tests

Build the verification test to run in two domains, the ATMI local domain and the CICS/ESA remote domain. The executables in each domain are different. The following sections discuss how to build these executables.

Building ATMI Platform Executables

To build the ATMI platform executables, perform the tasks that are described in detail in the following sections:

- Modify the UBBCONFIG File

- Execute the tmloadcf Command

- Modify the DMCONFIG File

- Execute the dmloadcf Command

- Modify the Environment Files

- Build the Server

- Build the Client

Modify the UBBCONFIG File

Make the following modifications to the UBBCONFIG file.

Add the ATMI Simple Server to the UBBCONFIG File

Modify the UBBCONFIG file to include the name of the ATMI simple server in the following way:

>     GROUPS
>     GROUP3        LMID=sna GRPNO=3

>     SERVERS
>     mirrorsrv     SRVGRP=GROUP3 SRVID=1 RQADDR=MIRR1 REPLYQ=Y

>     SERVICES
>     MIRROR

Enable Transactional Services

If you plan to run the transactional version of the verification process, enable the TLOGDEVICE comment in the Machine section to point to a valid DTP transaction log. To run transaction examples, create the DTP transaction log named on the UBBCONFIG TLOGDEVICE with the ATMI platform bulletin modification interpreter tmadmin. Refer to the appropriate ATMI platform documentation for option descriptions.

The application server GROUP3 in the Groups section must point to a valid transaction manager server. For example:

>     GROUPS
>     GROUP3        LMID=sna GRPNO=3 TMSNAME=tsttms TMSCOUNT=2

>     SERVERS
>     mirrorsrv     SRVGRP=GROUP3 SRVID=1 RQADDR=MIRR1 REPLYQ=Y

>     SERVICES
>     MIRROR

Execute the tmloadcf Command

Execute the ATMI tmloadcf command to parse the UBBCONFIG file and create a binary version of the file. Refer to the appropriate ATMI platform documentation for option descriptions.

For example:

>     tmloadcf UBBCONFIG

Respond to the prompts as the command executes.

Modify the DMCONFIG File

The DMCONFIG file must contain both local and remote definitions for the simple server.

Note: A sample DMCONFIG file is included with the simple server.

Listing 3-1 Sample DMCONFIG File

>     *DM_LOCAL_SERVICES
>     #The ATMI reverse string server
>     MIRROR       LDOM="simpsnad"
>            CONV=N
>            RNAME="MIRRORSERV"
>            INBUFTYPE="STRING"
>            OUTBUFTYPE="STRING"
>     DOUBLEMIRROR
>            CONV=N
>            RNAME="MIRRDPLS"
>            INBUFTYPE="STRING"
>            OUTBUFTYPE="STRING"
>     *DM_REMOTE_SERVICES
>     #The CICS upper-case DTP and DPL servers
>     SIMPDPL      AUTOTRAN=N
>            LDOM="simpsnad"
>            RDOM=SNAG1
>            CONV=N
>            RNAME="TOUPDPLS"
>            INBUFTYPE="STRING"
>            OUTPBUFTYPE="STRING"
>            FUNCTION="DPL"
>     SIMPDTP      AUTOTRAN=N
>            LDOM="simpsnad"
>            RDOM=SNAG1
>            CONV=N
>            RNAME="DTPS"
>            INBUFTYPE="STRING"
>            OUTPBUFTYPE="STRING"
>            FUNCTION="APPC"

In the preceding DMCONFIG file example, both instances of the LDOM name correspond to the SNA domain name in the DM_LOCAL_DOMAINS section. The server is a request/response server.

In the DM_LOCAL_SERVICES section, the RNAME="MIRRORSERV" and RNAME="MIRRDPLS" values are the names passed from the CICS/ESA environment. MIRROR and DOUBLEMIRROR refer to the advertised services provided by the mirrorsrv server named in the UBBCONFIG file. The CONV=N definition indicates the protocol that is observed by the SNA domain, although the CICS/ESA client does not perform an ATMI tpcall.

In the DM_REMOTE_SERVICES section, the RNAME value identifies what is invoked in the CICS/ESA domain. For the Distributed Program Link (DPL) request, the RNAME equals the name of the program called (or for alternate mirror transaction identifiers, a TRANSID/program name combination). For the Distributed Transaction Processing (DTP) request, the RNAME equals the name of the transaction ID.

If you want to run transactional verification tests, you must enter a link definition MAXSYNCLVL=2 in the DM_SNALINKS section. If you want to run non-transactional DPL tests only, you must enter MAXSYNCLVL=1.

Execute the dmloadcf Command

Execute the ATMI dmloadcf command to parse the DMCONFIG file and create a binary version of the file. Refer to the appropriate ATMI platform documentation for option descriptions.

For example:

>     dmloadcf DMCONFIG

Respond to the prompts as the command executes.

Modify the Environment Files

Two types of files are provided with your eLink Adapter for Mainframe product software that can be used to define the application and/or machine environments for verification testing. If their equivalents do not already exist, modify the files provided and make them available to your system. The files are apps.env and <machine>.env.

The app.env File

Modify the app.env file and include it with the ENVFILE parameter in the MACHINES section of the UBBCONFIG file. Listing3-2 is an example of the app.env file.

Listing 3-2 The app.env File

>     #================================================================
>     # app.env
>     #      Environment macros for ATMI application testing.
>     #
>     # See also
>     #      See $(TOP)/Makefile for more information.
>     #
>     # @(#)SNA Devel apps/simpsna app.env 1.4 98/03/03 15:42:30
>     # Copyright 1997, BEA Systems, Inc., all rights reserved.
>     #----------------------------------------------------------------
>     APPDIR=<Your application directory here>
>     TUXCONFIG=<Your Tux configuration here>
>     BDMCONFIG=<Your Domain configuration here>
>     TUXDIR=<Your ATMI directory here>

The <Machine>.env Files

Modify the <machine>.env file that is appropriate for your system:

- solaris.env

- uss.env

- ENV (MVS)

- aix.env

- hpux.env

- ntenv.bat

Each of these files is executable. Once you have modified the appropriate file for your system, execute it to export the machine environment variables. Examples of some of the .env files are shown in the following listings.

Listing3-3 is an example of a UNIX .env file.

Listing 3-3 The solaris.env File

>     #================================================================
>     # solaris.env
>     #      Environment macros for SOLARIS testing.
>     #
>     # See also
>     #      See $(TOP)/Makefile for more information.
>     #
>     # @(#)SNA Devel apps/simpsna solaris.env 1.3 98/02/23 12:39:05
>     # Copyright 1997, BEA Systems, Inc., all rights reserved.
>     #----------------------------------------------------------------

>     export APPDIR=<Your application directory bin here>
>     export TUXCONFIG=<Your ATMI configuration qualified name here>
>     export BDMCONFIG=<Your ATMI domain configuration qualified name here>
>     export TUXDIR=<Your ATMI product directory here>
>     export STACK=<Your stack product library here>
>     #example STACK=/opt/SUNWappc
>     export PATH=$APPDIR:$TUXDIR/bin:$PATH
>     export LD_LIBRARY_PATH=$TUXDIR/lib:$LD_LIBRARY_PATH:$STACK

Listing3-4 is an example of an OS/390 .env file.

Listing 3-4 The uss.env File

>     ==============================================================
>     # uss.env
>     #	Environment macros for OS/390 USS testing.
>     #
>     # @(#)SNA $Header: /repos/sna/apps/simpsna/uss.env,v 1.2 2000/04/26 19:32:58 crount Exp $
>     # Copyright 2000, BEA Systems, Inc., all rights reserved.
>     #---------------------------------------------------------------
>     export APPDIR=<Your application directory bin here>
>     export EAMDIR=<Your eLink Adapter for Mainframe installation directory here>
>     export PATH=$APPDIR:$EAMDIR/bin:$PATH
>     export LIBPATH=$EAMDIR/lib:$LIBPATH

Listing3-5 is an example of an MVS .env file.

Listing 3-5 The mvs.env File

>     *================================================================
>     * mvs.env
>     *	Environment macros for running the SNACRM on MVS.
>     *
>     * @(#)SNA $Source: /repos/sna/apps/simpsna/mvs.env,v $
>     *         $Revision: 1.4 $   $Author: crount $
>     *         $Date: 2000/08/22 15:30:46 $   $State: Exp $ $Locker:  $
>     * Copyright 2000, BEA Systems, Inc., all rights reserved.

>     *---------------------------------------------------------------

>     APPDIR=<Your site high-level qualifier here>
>     *example APPDIR=BEA

Build the Server

Use the ATMI platform buildserver utility to build the mirrorsrv server load module from the provided source file mirrorsrv.c. The source file contains two service entries, MIRROR and DOUBLEMIRROR, which will be advertised by the mirrorsrv server.

When executed, the MIRROR service receives a text string from the client, reverses the letters, and displays a mirror image of the input text string.

When executed, the DOUBLEMIRROR service receives a text string from the client, reverses the letters, and concatenates the reversed string to the forward image of the string.

The following command is an example of a command entry to invoke the buildserver utility:

>     buildserver -o mirrorsrv -f mirrorsrv.c -s MIRROR,DOUBLEMIRROR

Refer to the appropriate ATMI platform documentation for option descriptions.

Build the Client

Use the ATMI platform buildclient utility to build a client load module from the provided source file toupclt. When executed, the load module sends a lower-case text string to the server, which converts it to uppercase in several modes, causing different server scenarios to execute.

For example:

>     buildclient -o toupclt -f toupclt.c

>     Refer to the appropriate ATMI platform documentation for option descriptions.

Building CICS/ESA Executables

To build the CICS/ESA executables, perform the tasks that are described in detail in the following sections:

- Choose the Source Code Language

- Transfer the Source Code to the Host

- Translate CICS/ESA Verbs

- Compile the Translated Source File

- Create the Executable Object

- Configure the CICS/ESA Application

- View Connection and Session Status

Choose the Source Code Language

The CICS/ESA sample programs used for verification are unloaded during the installation of your eLink Adapter for Mainframe product software. These programs are available in two languages, COBOL and C. You must choose which language to use to build the CICS/ESA executable object code. (Your choice might be affected by the type of compiler available on your MVS host.)

You can identify the sample program names by their suffixes:

- TOUPDTPS.c is the C language program name

- TOUPDTPS.cbl is the COBOL language program name

Although the structures of the sample programs are different, they both perform the same function. The ATMI platform executable program that you build communicates with either.

Transfer the Source Code to the Host

Transfer the source code to the host by the method you prefer, for example FTP (File Transfer Program). The destination could be a sequential dataset or a PDS file. Table 3-1 lists the source code files provided for UNIX and MVS platforms. The UNIX filename extensions suggest the type of destination libraries into which the source code may be transferred.

Table 3-1 Source Code Filenames

UNIX Filename

MVS Member Name

BEACONN.RDO

BEACONN

BEASNA.RDO

BEASNA

MIRRDPLC.c
or
MIRRDPLC.cbl

MIRRDPLC

MIRRDTPC.c
or
MIRRDTPC.cbl

MIRRDTPC

TOUPDPLS.c
or
TOUPDPLS.cbl

TOUPDPLS

TOUPDTPS.c
or
TOUPDTPS.cbl

TOUPDTPS

Translate CICS/ESA Verbs

This step translates the EXEC CICS verbs into program CALL statements of the form required by the selected source language. The source is read from the SYSIN dataset. The translated source program is written to the SYSPUNCH dataset. The translator listing is written to the SYSPRINT dataset.

Different translator modules are provided for different source languages. There are also language-specific parameters for the translation step. Refer to the IBM CICS/ESA Application Programming Guide for additional translation options that might apply to your environment.

The translator modules are installed in the CICS/ESA load datasets. This is indicated in the following examples by the CICSxxx.SDFHLOAD entry, where xxx is the CICS/ESA release number.

COBOL Language Translator Example

The translator module name in the Listing3-6 is DFHECP1$. The parameter COBOL2 indicates that a source module containing COBOL II verbs is to be translated.

Listing 3-6 COBOL Language Translator Example

>     //TRN  EXEC PGM=DFHECP1$,
>     //     PARM=`COBOL2,NOS,CICS',REGION=256K
>     //STEPLIB     DD DSN=CICSXXX.SDFHLOAD,DISP=SHR
>     //SYSIN       DD DSN=YOUR.PDS(pgmname),DISP=SHR
>     //SYSPRINT    DD SYSOUT=*
>     //SYSPUNCH    DD DSN=&&SYSCIN,
>     //            DISP=(,PASS),UNIT=SYSDA,
>     //            DCP=BLKSIZE=400,
>     //            SPACE=(400,(400,100))

C Language Translator example

The translator module name in Listing3-7 is DFHEDP1$. The parameter C indicates that a source module containing C verbs is to be translated.

Listing 3-7 C Language Translator Example

>     //TRN  EXEC PGM=DFHEDP1$,
>     //     PARM=`C,NOS,CICS',REGION=256K
>     //STEPLIB     DD DSN=CICSXXX.SDFHLOAD,DISP=SHR
>     //SYSIN       DD DSN=YOUR.PDS(pgmname),DISP=SHR
>     //SYSPRINT    DD SYSOUT=*
>     //SYSPUNCH    DD DSN=&&SYSCIN,
>     //            DISP=(,PASS),UNIT=SYSDA,
>     //            DCB=BLKSIZE=400,
>     //            SPACE=(400,(400,100))

Compile the Translated Source File

The next step is to compile the translated source file &&SYSCIN. This step generates the following program modules in preparation for the link-edit step:

- TOUPDPLS (CICS server DPL module)

- TOUPDTPS (CICS server DTP module using CICS APIs)

- MIRRDPLC (CICS client DPL module)

- MIRRDTPC (CICS client DTP module using CPI-C verbs)

COBOL Compiler Example

Listing3-8 shows a COBOL compiler example.

Listing 3-8 COBOL Compiler Example

>     //COB  EXEC PGM=IGYCRCTL,REGION=GM,
>     //     PARM=`NODYNAM,RENT,RES,APOST,MAP,XREF'
>     //STEPLIB     DD DSN=SYS2.COB2.COB2COMP,DISP=SHR
>     //SYSLIB      DD DSN=CICSXXX.SDFCOB,DISP=SHR
>     //SYSPRINT    DD SYSOUT=*
>     //SYSIN       DD DSN=&&SYSCIN,DISP=(OLD,DELETE)
>     //SYSLIN      DD DSN=&&LOADSET,DISP=(MOD,PASS),
>     //            UNIT=&WORK,SPACE=(400,(20,20))
>     //SYSUT1      DD UNIT-WORK,SPACE=(460,(350,100))
>     //SYSUT2      DD UNIT=WORK,SPACE=(460,350,100))
>     //SYSUT3      DD UNIT=WORK,SPACE=(460,(350,100))
>     //SYSUT4      DD UNIT=&WORK,SPACE=(460,(350,100))
>     //SYSUT5      DD UNIT=&WORK,SPACE=(460,(350,100))
>     //SYSUT6      DD UNIT=&WORK,SPACE=(460,(350,100))
>     //SYSUT7      DD UNIT=&WORK,SPACE=(460,(350,100))

C Compiler Example

Compile and pre-link your C language source. The BEA eLink Adapter for Mainframe installation library contains C language compiler examples. Listing3-9 shows a C/MVS compiler example.

In this example, the external storage variables must be re-entrant in the load module for the CICS/ESA environment. Additionally, the C language source contains long variable and function names. The pre-link step must be run to resolve the long names and create re-entrant variables from the compiled object. Perform the pre-link step, use the RENT option in the compile program, and use the compile output in the link-edit step.

Listing 3-9 C/MVS Compiler Example

>     //*----------------------------------------
>     //* COMPILE STEP:
>     //*----------------------------------------
>     //COMPILE EXEC PGM=CBC310,REGION=2M,COND=(7,LT,TRN),
>     //     PARM=(`OPT(1),LONGNAME,RENT,SOURCE')
>     //STEPLIB     DD DSNAME=SYS1.SCEERUN,DISP=SHR
>     //            DD DSNAME=SYS1.SCBC3CMP,DISP=SHR
>     //SYSMSGS     DD DSNAME=SYS1.SCBC3MSG(EDCMSGE),DISP=SHR
>     //SYSIN       DD DSNAME=&&SYSCIN,DISP=SHR **FROM TRN STEP
>     //SYSLIB      DD DSNAME=SYS1.SCEEH.H,DISP=SHR
>     //            DD DSNAME=SYS1.SCEEH.SYS.H,DISP=SHR
>     //            DD DSNAME=CICSxxx.SDFHC370,DISP=SHR**CPIC
>     //            REQUIRED**
>     //SYSLIN      DD DSNAME=&&PLNKSET,UNIT=VIO,
>     //            DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
>     //            DCP=(RECFM=FG,LRECL=80,BLKSIZE=&SYSLBLK)
>     //SYSPRINT    DD SYSOUT=*
>     //SYSOUT      DD SYSOUT=*
>     //SYSCPRT     DD SYSOUT=*
>     //SYSUT1      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200
>     //SYSUT4      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200
>     //SYSUT5      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=12800
>     //SYSUT6      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=12800
>     //SYSUT7      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=12800
>     //SYSUT8      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=12800
>     //SYSUT9      DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=137,BLKSIZE=882
>     //SYSUT10     DD SYSOUT=*
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200
>     //SYSUT14     DD UNIT=VIO,SPACE=(32000,(30,30,)),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=128007
>     //PLKED EXEC PGM=EDCPRLK,COND=((7.LT,C),(7,LT,TRN)),
>     //            PARM='MAP'
>     //STEPLIB     DD DSN=SYS1.SCEERUN,DISP-SHR
>     //SYSMSGS     DD DSN=SYS1.SCEEMSGP(EDCPMSGE),DISP+SHR
>     //SYSLIB      DD DSN=&LE370HLQ..SCEECPP,DISP=SHR
>     //            DD DUMMY
>     //SYSIN       DD DSN=&&PLNKSET,DISP=(MOD,PASS)
>     //SYSMOD      DD DSN=&&LOADSET,DISP=(,PASS),
>     //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
>     //SYSOUT      DD SYSOUT=*
>     //SYSPRINT    DD SYSOUT=*

Create the Executable Object

The next step is to take the compiled source and create the executable object. You should load the resulting object module into the application library that is concatenated with the CICS/ESA region datasets.

In the following COBOL and C program examples, SYSLIN is the name of the file containing the compiled source concatenated with other necessary executables, including interfaces for the CICS API verbs, interfaces for CPI-C verbs, and interfaces for SNA resource recovery verbs (sync-level 2).

In Listing3-10, the module is linked as re-entrant and marked with 31-bit mode address-ability. This action is required for the module MIRRDTPC which performs CPI-C and SAA Resource/Recovery requests.

You must change the NAME to that of the executable being generated.

Listing 3-10 COBOL Link-Edit Sample for TOUPDPLS, TOUPDTPS, and MIRRDPLC

>     //LKED    EXEC PGM=IEWL,   * ** LINKAGE EDITOR **
>     //             PARM=AMODE=31,RENT,
>     //             REGION=512K
>     //SYSPRINT DD SYSOUT=*
>     //SYSLIN       DD DSN=&&LOADSET,DISP=(OLD,DELETE)
>     //             DD *
>     //	INCLUDE SYSLIB(DFHECI)
>     //	ORDER DFHECI
>     //		NAME xxxxxxxx(R)
>     /*
>     //SYSLIB    DD DSN=CICSxxx.SDFHLOAD,DISP=SHR
>     //          DD DSN=CICSxxx.SDFHCOB,DISP=SHR
>     //          DD DSN=SYS1.SCEELKED,DISP=SHR
>     //          DD DSN=SYS1.SIGYCOMP,DISP=SHR
>     //SYSLMOD   DD DSN=application.loadlib,DISP=(SHR,PASS)
>     //SYSUT1    DD UNIT=VIOD,SPACE=(1024,(50,20))
>     //

Listing 3-11 COBOL Link-Edit Sample for MIRRDTPC

>     //LKED    EXEC PGM=IEWL,   * ** LINKAGE EDITOR **
>     //             PARM=AMODE=31,RENT,
>     //             REGION=512K
>     //SYSPRINT DD SYSOUT=*
>     //SYSLIN       DD DSN=&&LOADSET,DISP=(OLD,DELETE)
>     //             DD *
>     //	INCLUDE SYSLIB(DFHECI)
>     //	INCLUDE SYSLIB(DFHCPLC)
>     //	INCLUDE SYSLIB(DFHCPLRR)
>     //	ORDER DFHECI
>     //		NAME xxxxxxxx(R)
>     /*
>     //SYSLIB    DD DSN=CICSxxx.SDFHLOAD,DISP=SHR
>     //          DD DSN=CICSxxx.SDFHCOB,DISP=SHR
>     //          DD DSN=SYS1.SCEELKED,DISP=SHR
>     //          DD DSN=SYS1.SIGYCOMP,DISP=SHR
>     //SYSLMOD   DD DSN=application.loadlib(xxxxxxxx),DISP=(SHR,PASS)
>     //SYSUT1    DD UNIT=VIOD,SPACE=(1024,(50,20))
>     //

Listing 3-12 C Link-Edit Sample

>     //LKED     EXEC PGM=HEWL,REGION=4M,
>     //         PARM='AMODE=31,RENT,
>     //         COND=((7,LT,C),(7,LT,PLKED),(7,LT,TRN))
>     //SYSLIB   DD DSN=CICSxxx.SDFHLOAD,DISP=SHR
>     //         DD DSN=SYS1.SCEELKED,DISP=SHR
>     //SYSLIN   DD DSN=&&LOADSET,DISP=(OLD,DELETE)
>     //         DD *INCLUDE SYSLIB(DFHELII)
>     //	INCLUDE SYSLIB(DFHCPLC)
>     //	INCLUDE SYSLIB(DFHCPLRR)NAME xxxxxxxx(R)
>     /*
>     //SYSLMOD  DD DSN=application.loadlib(xxxxxxxx),DISP=SHR
>     //SYSUT1   DD UNIT=VIOD,SPACE=(1024,(50,20))
>     //SYSPRINT DD SYSOUT=*

Configure the CICS/ESA Application

Your installed eLink Adapter for Mainframe software contains two sample files that can be used to configure the CICS application:

- The BEACONN file contains the CICS/ESA configuration parameters to the host system. These include connection definitions and session definitions.

- The BEASNA file contains the application definitions that enable you to perform the installation verification in the CICS/ESA environment. These definitions are required to run the installation verification. They include the program definitions, transaction definitions, and for the CPI-C example, the partner definition.

Caution: The BEACONN file should only be added to the CICS/ESA System Definition (CSD) file if no definitions currently exist. Check with your system administrator.

One method of adding the files is to use the batch utility program, DFHCSDUP. Listing3-13 is an example of the Job Control Language (JCL) statements you can use to invoke DFHCSDUP as a batch program to add the BEASNA file:

Listing 3-13 JCL Example for Invoking DFHCSDUP

>     //YOURJOB JOB accounting info,name,MSGLEVEL=1
>     //STEP1 EXEC PGM=DFHCSDUP,REGION=512K,
>     //      PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT'
>     //STEPLIB  DD DSN=CICSxxx.SDFHLOAD,DISP=SHR
>     //DFHCSD   DD UNIT=SYSDA,DISP=SHR,DSN=CICSxxx.DFHCSD
>     //SYSPRINT DD SYSOUT=A
>     //SYSIN    DD DSN=YOUR.PDS(BEASNA),DISP=SHR

The definitions in the sample member use an eLink Adapter for Mainframe Resource Definition Online (RDO) Group name. You may want to add these definitions to an existing RDO group, or you might consider adding them to your CICS/ESA start-up list if you plan to use them often. (This automatically installs the group on start-up of the CICS/ESA region.) To add the groups to the start-up list, un-comment the following statements in the sample RDO.

>     ADD GROUP(BEACONN) LIST(**YOURLIST**)

>     ADD GROUP(BEASNA) LIST(**YOURLIST**)

In these arguments, **YOURLIST** is the name of your startup list.

To manually install the groups after start-up of the CICS/ESA region, issue the following commands from a CICS/ESA terminal session.

>     CEDA I GROUP(BEACONN)

>     CEDA I GROUP(BEASNA)

BEACONN File: Connection definition

The BEACONN file includes a sample connection definition.

Note: The sample connection definition achieves the minimum requirements for a connection over which the installation verification can be executed. Do not rely on it to provide optimal performance. Consult the CICS/ESA Resource Definition Guide for information about adding options not included in the sample.

The name of the sample connection definition is BEA, which is located under the installation group name BEACONN. It looks like this:

Listing 3-14 Sample Connection Definition in BEACONN File

>     DEFINE CONNECTION(BEA)      GROUP(BEACONN)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE RDO CONNECTION)
>            ACCESSMETHOD(VTAM)   PROTOCOL(APPC)
>            NETNAME(**LOCALLU**)
>            ATTACHSEC(LOCAL)     AUTOCONNECT(NO)

**LOCALLU** must be changed to the LU name of the SNA stack as known by VTAM. The ATTACHSEC option indicates the level of attach-time user security required for the connection. LOCAL is the simplest security. The authorization of the user is taken to be that of the link itself, relying on the authorization validation provided by the remote security utility. AUTOCONNECT indicates when the connection is acquired. NO is required. This entry means that CICS does not attempt to bind sessions when the connection is established by the stack.

Note: The eLink Adapter for Mainframe software must acquire the connection and negotiate the bind when the eLink Adapter for Mainframe software starts up.

Install the sample connection definition by putting it on the host in a separate group that does not contain existing connection. For example, use the CEDA INSTALL command:

>     CEDA INSTALL GROUP(BEACONN)

BEACONN File: Session Definition

The BEACONN file also includes a sample session definition. When placed on the remote host, it defines the logical links by which the ATMI platform local domain communicates with the remote host.

The name of the sample session definition is BEATEST, which is located under the installation group named BEACONN. Listing3-15 shows an example of a BEACONN file session definition.

Listing 3-15 Sample Session Definition in BEACONN File

>     DEFINE SESSION(BEATEST)     GROUP(BEACONN)
>            CONNECTION(BEA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE RDO SESSION)
>            PROTOCOL(APPC)       AUTOCONNECT(YES)
>            MODENAME(**MODE**) MAXIMUM(**MAX**,**MIN**)

AUTOCONNECT indicates how the activation of the session is to be negotiated. YES enables the CICS/ESA host to negotiate its own winner sessions when the connection is bound. Remember that the eLink Adapter for Mainframe software must acquire the connection instead of the CICS/ESA host. However, when the stack acquires the connection, it can only bind the number of sessions identified as its winners. Setting the AUTOCONNECT parameter to YES causes the host to bind winner sessions immediately when the connection is acquired. Otherwise, the host's outbound clients must wait for winner sessions to bind.

Replace **MODE** with either a CICS/ESA-supplied mode name, such as SMSNA100, or with your own defined mode name. If another set of session definitions exist for the BEA connection, this mode name must be unique among all sets defined to the connection. The mode name corresponds to a VTAM LOGMODE name.

The MAXIMUM option defines the total number of sessions in the set (**MAX**) and the total number of contention winner sessions (**MIN**). To verify the installation, the total number of winner sessions must include those for the host and the remote stack. The installation verification process allows both sides to execute as the client. The total number of local contention winner sessions plus remote contention winner sessions must equal the number of sessions. The local number of sessions must equal the remote number of sessions.

BEASNA File: Program Definition

The BEASNA file includes a sample program definition, shown in Listing3-16. Replace the LANGUAGE variable **LANG** in the sample with either C or COBOL to identify the source type you have selected for the sample application.

Listing 3-16 Sample Program Definitions in BEASNA File

>     DEFINE  PROGRAM(MIRRDPLC)    GROUP(BEASNA)
>             DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DPL CLIENT
>                (MIRROR STRING))
>             LANGUAGE(**LANG**)   DATALOCATION(ANY)

>     DEFINE PROGRAM(MIRRDTPC)     GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DTP CLIENT (MIRROR
>                  STRING))
>            LANGUAGE(**LANG**)    DATALOCATION(ANY)

>     DEFINE PROGRAM(TOUPDTPS)     GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DTP SERVER
>                   (TOUPPER STRING))
>            LANGUAGE(**LANG**)    DATALOCATION(ANY)

>     DEFINE PROGRAM(TOUPDPLS)     GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DPL SERVER
>                   (TOUPPER STRING))
>            LANGUAGE(**LANG**)    DATALOCATION(ANY)

BEASNA File: Remote Program Definition

The BEASNA file also contains a sample remote program definition, shown in Listing3-17. The program definition is used by the CICS DPL client to identify the remote system and service for the DPL request. Replace the REMOTESYSTEM variable **CONNECTION ID** in the sample with the name of the connection for the remote LU.

Listing 3-17 Sample Remote Program Definition in BEASNA File

>     DEFINE PROGRAM(MIRRDPLS)    GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE DPL REMOTE PROGRAM
>                   DEFINITION)
>             LANGUAGE(C)         DATALOCATION(ANY)
>             REMOTESYSTEM(**CONNECTION ID**) REMOTENAME(MIRRDPLS)

BEASNA File: Transaction Definition

The BEASNA file also contains a sample transaction definition, shown in Listing3-18.

Listing 3-18 Sample Transaction Definitions in BEASNA File

>     DEFINE	TRANSACTION(DTPS     GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DTP SERVER)
>            TASKDATALOC(ANY)     PROGRAM(TOUPDTPS)

>     DEFINE	TRANSACTION(H1PL)    GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DPL CLIENT -
>                SYNCLEVEL 1)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDPLC)

>     DEFINE	TRANSACTION(H2PL)    GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DTP CLIENT -
>                SYNCLEVEL 2)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDPLC)

>     DEFINE	TRANSACTION(H0TP)    GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DPL CLIENT -
>                SYNCLEVEL 0)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDTPC)

>     DEFINE	TRANSACTION(H2TP)    GROUP(BEASNA)
>            DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DTP CLIENT -
>                SYNCLEVEL 2)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDTPC)

BEASNA File: Partner Definition

The sample CICS/ESA client MIRRDTPC contains CPI-C verbs. The partner resource definition contains the CPI-C side information needed to allocate a conversation with the ATMI server and information about the remote LU and transaction program.

As shown in Listing3-19, the TPNAME parameter identifies the transaction program that is invoked in the remote system. In this case, the name correlates to the RNAME value in the DM_LOCAL_SERVICES section of the DMCONFIG file. The RNAME there must match the TPNAME in the partner definition. (Notice in the sample DMCONFIG file that a local service definition MIRROR exists. The RNAME in that definition matches the TPNAME in the sample partner definition.)

The profile resource definition can define conversation attributes, in particular MODENAME. In the sample, the PROFILE parameter can be replaced with a valid profile resource definition. The default profile name for the parameter is DFHCICSA. DFHCICSA is a CICS-delivered profile.

Use the NETNAME specified in the Connection definition of the remote LU to replace **NETWORK NAME**.

Listing 3-19 Sample Partner Definition in BEASNA File

>     DEFINE PARTNER(MIRRDTPS)    GROUP(BEASNA)
>     DE(ELINK ADAPTER FOR MAINFRAME EXAMPLE CICS DTP CLIENT USING CPIC
>          VERBS
>     TPNAME(MIRRORSERV)          PROFILE(**DFHCICSA**)
>     NETNAME(**NETWORK NAME**)

View Connection and Session Status

Once you have made the verification group definitions, you can view the status of connections and sessions using the following CICS/ESA system commands:

>     CEMT I CONN(BEA)           **view the status of the connection
>     CEMT I NET(**NETNAME**)    **View the status of the sessions
>     CEMT I MODENAME(**MODE**)  **View the status of the mode

Running the Sample Application

Now you are ready to validate the eLink Adapter for Mainframe installation by running the sample application. You should have completed the following prerequisites:

- Install the eLink Adapter for Mainframe software

- Configure the ATMI platform and eLink Adapter for Mainframe local domains

- Configure the CICS/ESA remote domain

- Initialize the stack processes

- Start the servers

The sample application contains several scenarios. When the client runs as an ATMI client, the server runs as a CICS/ESA host. When the client runs as a CICS/ESA client, the server runs as an ATMI server.

Running the Application from an ATMI Client

In this scenario, the toupclt client performs a tpcall to the CICS/ESA host server. The server converts the text string you enter from lower-case to upper-case letters. The client may be run in transactional or non-transactional mode. The CICS/ESA server may be run as a DTP or DPL program

For example, enter the following command:

>     toupclt -s 0 -t DTP "hello world"

In this command, the arguments and options are defined in the following way:

  -s (0|2)

  Application Sync-Level.

  0 = none (default)

  2 = Transactional.

  -t (DPL|DTP)

  Remote Server Program.

  DPL = Distributed Program Link (default)

  DTP = Distributed Transaction Program

  -h

  Help

  " "

  Lowercase text string of up to 1915 characters.

If the ATMI client successfully executes the command, it displays the text string in upper-case letters, for example:

>     "HELLO WORLD"

Running the Application from a CICS/ESA Client

The following sections depict two scenarios for running the application from a CICS/ESA client.

CICS/ESA Client with CPI-C

In this scenario, the CICS/ESA client sends a text string to the eLink Adapter for Mainframe simple server. The string is re-displayed on the client's screen in reverse order.

Enter either of the following commands:

>     H0TP <string>

>     H2TP <string>

In these commands, the arguments and options are defined in the following way:

>     H0TP = CPI-C Application Sync-Level 0

>     H2TP = CPI-C Application Sync-Level 2

>     <string> is a text string up to 1915 characters long.

If the CICS/ESA client successfully completes the transaction, it displays the text string in reverse order. For example:

You enter:

>     H0TP HELLO WORLD

The system returns:

>     DLROW OLLEH

CICS/ESA Client with DPL

Two transactions are available to execute the same program for the DPL sample. One is a simple request/response with the required sync-level 1, the other is a transactional request/response with sync-level 2.

Enter either of the following commands:

>     H1PL <string>

>     H2PL <string>

In these commands, the arguments and options are defined in the following way:

>     H1PL = DPL Application Sync-Level 1

>     H2PL = DPL Application Sync-Level 2

>     <string> is a text string up to 955 characters long.

If the CICS/ESA client successfully completes the transaction, it displays a reverse (or mirror) image of the text string concatenated to the input text string. For example:

You enter:

>     H1PL HELLO WORLD

The system returns:

>     HELLO WORLD : DLROW OLLEH

Running the Application from a CICS/VSE Client

The CICS/VSE sample applications are virtually identical to the CICS/ESA sample applications, except the file names have the .vse extension. The same scenarios for running the sample applications apply for both client categories. Other noteworthy differences are minor syntax changes in the sample applications to accommodate the CICS/VSE operating system and lack of CICS/VSE support for a CPI-C interface.

CICS/VSE Sample Applications

The following is a list of the CICS/VSE sample applications:

- BEASNA.RDO.VSE

- MIRRDPLC.c.VSE

- TOUPDPLS.c.VSE

- TOUPDTPS.c.VSE

- TOUPDTPS.cbl.VSE

Other Considerations

Some FTP operations may result in mistranslation of C-language special characters. It may be necessary for you to edit the source file(s) and correct the mistranslations of brackets [ ] and parallel bar | | characters.

CSMI and CVMI use profile DFHCICST with the attribute INBFMH = NO. When using DTP transactions, you are required to set INBFMH = ALL; otherwise, an ABEND AXFQ occurs.

CICS/VSE transactions should be defined with the security attribute RSLC=NO; otherwise an EIBRCODE (NOTAUTH) is returned to the client.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.