Home Previous Topic Next Topic

# 4. Verifying the Software

After installing and configuring the BEA eLink for Mainframe SNA product software, it is important to verify the operational integrity of the environment. To do this, you run a sample application on a simple server in client/server transaction scenarios. This process employs programs available in your product software libraries.

Note: Before running the sample application, you must configure the eLink SNA gateway environment, start the Physical Unit (PU), start the SNACRM, and start the BEA TUXEDO system. Refer to Section 3, "Configuring the System," and Section 5, "Administering the Application Domain," for details.

## Overview

The sample applications are located in the SNA simple server library. 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. In addition, the simple server may run in either transactional or nontransactional 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 a BEA TUXEDO client, the server runs as a CICS/ESA host. You 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 a BEA TUXEDO server. Again, you enter a text string in lower-case letters. The BEA TUXEDO 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, that is, between BEA TUXEDO applications and CICS/ESA applications. If your BEA TUXEDO applications operate in other environments, you must create your own verification process.

## Building Your Verification Tests

You must build the verification test to run in two domains, the BEA TUXEDO local domain and the CICS/ESA remote domain. The executables in each domain are different. The following subsections discuss how to build these executables.

### Building TUXEDO Executables

Use the following checklist to complete this process:

1. Modify the name of the simple server in the UBBCONFIG file provided.

2. Execute the `tmloadcf` command to compile the UBBCONFIG file.

3. Modify the required local and remote definitions in the DMCONFIG file provided.

4. Execute the `dmloadcf` command to compile the DMCONFIG file.

5. Modify the `apps.env` and `<machine>.env` environment files (optional).

6. Use the `buildserver` utility to build a server load module.

7. Use the `buildclient` utility to build a client load module.

#### Using the buildserver Utility

Use the BEA TUXEDO `buildserver` utility to build the `mirrorsrv` server load module from the source file `mirrorsrv.c` provided. 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.

This is an example of a command entry to invoke the `buildserver` utility:

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

(Refer to the BEA TUXEDO Reference Manual for option descriptions.)

#### Using the buildclient Utility

Use the BEA TUXEDO `buildclient` utility to build a client load module from the source file `toupclt` provided. 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. (Refer to the BEA TUXEDO Reference Manual for option descriptions.)

For example:

>     buildclient -o toupclt -f toupclt.c

#### Modifying the UBBCONFIG file

Include the name of the BEA TUXEDO simple server in the UBBCONFIG file.

>     *GROUPS
>     GROUP3        LMID=sna GRPNO=3

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

>     SERVICES
>     MIRROR

#### Enabling Transactional Services

If you plan to run the transactional version of the verification process, enable the `TLOGDEVICE` comment in the Machine section. This must point to a valid DTP transaction log. To run transaction examples, create the DTP transaction log named on the UBBCONFIG `TLOGDEVICE`. Create the log with the TUXEDO bulletin modification interpreter `tmadmin`. (Refer to the BEA TUXEDO Reference Manual for more details.)

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

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

>     SERVICES
>     MIRROR

#### Executing the tmloadcf Command

Execute the BEA TUXEDO `tmloadcf` command to parse the UBBCONFIG file and create a binary version of the file. (Refer to the BEA TUXEDO Reference Manual for more details.)

For example:

>     tmloadcf UBBCONFIG

Respond to the prompts as the command executes.

#### Modifying 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 4-1 Sample DMCONFIG File

>     *DM_LOCAL_SERVICES
>     #The Tuxedo 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 a TUXEDO 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`.

#### Executing the dmloadcf Command

Execute the BEA TUXEDO `dmloadcf` command to parse the DMCONFIG file and create a binary version of the file. (Refer to the BEA TUXEDO Reference Manual for more details.)

For example:

>     dmloadcf DMCONFIG

Respond to the prompts as the command executes.

#### Modifying the Environment Files

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

##### The apps.env File

Modify the `apps.env` file and include it with the `ENVFILE` parameter in the `MACHINES` section of the UBBCONFIG file. The `apps.env` file looks like this:

> Listing 4-2 The apps.env File

>     #================================================================
>     # apps.env
>     #      Environment macros for tuxedo 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 Tuxedo directory here>
>     FLDTBLDIR32=<Your Tuxedo directory here>/lib
>     FIELDTBLS32=fmb.def

##### The <Machine>.env Files

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

- `aix.env`

- `hpux.env`

- `solaris.env`

Each of these files is executable. Once you have modified the appropriate file for your system, execute it to export the machine environment variables. The files look like this:

> Listing 4-3 The aix.env File

>     #================================================================
>     # aix.env
>     #      Environment macros for AIX testing.
>     #
>     # See also
>     #      See $(TOP)/Makefile for more information.
>     #
>     # @(#)SNA Devel apps/simpsna aix.env 1.2 98/02/23 12:39:36
>     # Copyright 1997, BEA Systems, Inc., all rights reserved.
>     #----------------------------------------------------------------
>     export APPDIR=<Your application directory bin here>
>     export TUXCONFIG=<Your tuxedo configuration qualified name here>
>     export BDMCONFIG=<Your tuxedo domain configuration qualified name here>
>     export TUXDIR=<Your tuxedo product directory here>
>     export STACK=<Your stack product library here>
>     #example STACK=/opt/SUNWappc or /opt/sna/lib
>     export FLDTBLDIR32=$TUXDIR/lib
>     export FIELDTBLS32=fmb.def
>     export PATH=$APPDIR:$TUXDIR/bin:$PATH
>     export LIBPATH=$TUXDIR/lib:$LIBPATH:$STACK

> Listing 4-4 The hpux.env File

>     #================================================================
>     # hpux.env
>     #      Environment macros for HP-UX testing.
>     #
>     # See also
>     #      See $(TOP)/Makefile for more information.
>     #
>     # @(#)SNA Devel apps/simpsna hpux.env 1.3 98/02/23 12:38:34
>     # Copyright 1997, BEA Systems, Inc., all rights reserved.
>     #----------------------------------------------------------------
>     export APPDIR=<Your application directory bin here>
>     export TUXCONFIG=<Your tuxedo configuration qualified name here>
>     export BDMCONFIG=<Your tuxedo domain configuration qualified name here>
>     export TUXDIR=<Your tuxedo product directory here>
>     export STACK=<Your stack product library here>
>     #example STACK=/opt/sna/lib
>     export PATH=$APPDIR:$TUXDIR/bin:$PATH
>     export SHLIB_PATH=$APPDIR:$TUXDIR/lib:$SHLIB_PATH:$STACK

> Listing 4-5 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 tuxedo configuration qualified name here>
>     export BDMCONFIG=<Your tuxedo domain configuration qualified name here>
>     export TUXDIR=<Your tuxedo product directory here>
>     export STACK=<Your stack product library here>
>     #example STACK=/opt/SUNWappc
>     export FLDTBLDIR32=$TUXDIR/lib
>     export FIELDTBLS32=fmb.def
>     export PATH=$APPDIR:$TUXDIR/bin:$PATH
>     export LD_LIBRARY_PATH=$TUXDIR/lib:$LD_LIBRARY_PATH:$STACK

### Building CICS/ESA Executables

Use the following checklist to complete this process:

1. Choose either COBOL or C source.

2. Transfer source from SNA install directory to the PDS.

3. Translate CICS/ESA verbs.

4. Compile the translated source file.

5. Link-edit the compiled source file.

6. Configure the CICS/ESA application (similar to CICS LU configuration).

7. View the connection, session, or mode status.

#### Choosing the Source Code Language

The CICS/ESA sample programs used for verification are unloaded during the installation of your BEA eLink for Mainframe SNA product software. These programs are available in two languages, COBOL and C. You must choose which language is used 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 (requires a compiler that accepts COBOL II verbs)

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

#### Transferring the Source Code to Host

Transfer the source code to the host by the method you prefer, for example FTP (File Transfer Program). The destination could be sequential dataset or a PDS. Table 4-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 4-1 Source Code Filenames

UNIX Filename | MVS Member Name
--- | ---
BEACONN.RDO | BEACONN
BEASNA.RDO | BEASNA
MIRRDPLC.<c> <cbl> | MIRRDPLC
MIRRDTPC.<c> <cbl> | MIRRDTPC
TOUPDPLS.<c> <cbl> | TOUPDPLS
TOUPDTPS.<c> <cbl> | TOUPDTPS

#### Translating 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 following example is `DFHECP1$`. The parameter `COBOL2` indicates that a source module containing COBOL II verbs is to be translated.

> Listing 4-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 Listing 4-7 is `DFHEDP1$`. The parameter `C` indicates that a source module containing C verbs is to be translated.

> Listing 4-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))

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

Listing 4-8 shows a COBOL compiler example.

> Listing 4-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 SNA installation library contains C language compiler examples. Listing 4-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 reentrant 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 4-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=",REGION=2M
>     //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+*

#### Link-Editing the Compiled Source File

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 SAA resource recovery verbs (sync-level 2).

In Listing 4-10, the module is linked as re-entrant and marked with 31-bit mode addressability. This 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 4-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 4-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 4-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=*

#### Configuring the CICS/ESA Application

Your installed eLink SNA 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`. Listing 4-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 4-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 a eLink SNA 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**)

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, located under the installation group name BEACONN. It looks like this:

> Listing 4-14 Sample Connection Definition in BEACONN File

>     DEFINE CONNECTION(BEA)      GROUP(BEACONN)
>            DE(CONNECT SNA EXAMPLE RDO CONNECTION)
>            ACCESSMETHOD(VTAM)   PROTOCOL(APPC)
>            NETNAME(LUHP10A)
>            ATTACHSEC(LOCAL)     AUTOCONNECT(NO)

The `NETNAME` option must be changed to the LU name of the remote system 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 means that CICS does not attempt to bind sessions when the connection is established by the stack.

Note: It is required that the eLink SNA software acquire the connection and negotiate the bind when the eLink SNA software starts up.

To install the sample connection definition, put it in on the host in a separate group which does not contain existing connection. Use the `CEDA` `INSTALL` command, for example:

>     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 BEA TUXEDO local domain communicates with the remote host.

The name of the sample session definition is `BEATEST`, located under the installation group name `BEACONN`. It looks like this:

> Listing 4-15 Sample Session Definition in BEACONN File

>     DEFINE SESSION(BEATEST)     GROUP(BEACONN)
>            CONNECTION(BEA)
>            DE(CONNECT SNA EXAMPLE RDO SESSION)
>            PROTOCOL(APPC)       AUTOCONNECT(YES)
>            MODENAME(**SMSNA100**) MAXIMUM(**6**,**3**)

`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 it is required that the eLink SNA software 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 the VTAM `LOGMODE` name.

The `MAXIMUM` option defines the total number of sessions in the set and the total number of contention winner sessions. 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 Listing 4-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 4-16 Sample Program Definitions in BEASNA File

>     DEFINE  PROGRAM(MIRRDPLC)    GROUP(BEASNA)
>             DE(CONNECT SNA EXAMPLE CICS DPL CLIENT (MIRROR STRING))
>             LANGUAGE(**LANG**)   DATALOCATION(ANY)

>     DEFINE PROGRAM(MIRRDTPC)     GROUP(BEASNA)
>            DE(CONNECT SNA EXAMPLE CICS DTP CLIENT (MIRROR STRING))
>            LANGUAGE(**LANG**)    DATALOCATION(ANY)

>     DEFINE PROGRAM(TOUPDTPS)     GROUP(BEASNA)
>            DE(CONNECT SNA EXAMPLE CICS DTP SERVER (TOUPPER STRING))
>            LANGUAGE(**LANG**)    DATALOCATION(ANY)

>     DEFINE PROGRAM(TOUPDPLS)     GROUP(BEASNA)
>            DE(CONNECT SNA 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 Listing 4-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 4-17 Sample Remote Program Definition in BEASNA File

>     DEFINE PROGRAM(MIRRDPLS)    GROUP(BEASNA)
>            DE(CONNECT SNA 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 Listing 4-18.

> Listing 4-18 Sample Transaction Definitions in BEASNA File

>     DEFINE	TRANSACTION(DTPS     GROUP(BEASNA)
>            DE(CONNECT SNA EXAMPLE CICS DTP SERVER)
>            TASKDATALOC(ANY)     PROGRAM(TOUPDTPS)

>     DEFINE	TRANSACTION(H1PL)    GROUP(BEASNA)
>            DE(CONNECT SNA EXAMPLE CICS DPL CLIENT - SYNCLEVEL 1)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDPLC)

>     DEFINE	TRANSACTION(H2PL)    GROUP(BEASNA)
>            DE(CONNECT SNA EXAMPLE CICS DTP CLIENT - SYNCLEVEL 2)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDPLC)

>     DEFINE	TRANSACTION(H0TP)    GROUP(BEASNA)
>            DE(CONNECT SNA EXAMPLE CICS DPL CLIENT - SYNCLEVEL 0)
>            TASKDATALOC(ANY)     PROGRAM(MIRRDTPC)

>     DEFINE	TRANSACTION(H2TP)    GROUP(BEASNA)
>            DE(CONNECT SNA 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 TUXEDO server. It contains the information about the remote LU and transaction program.

As shown in Listing 4-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 configuration 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 (refer to"Create Connections at the Remote Host" ).

> Listing 4-19 Sample Partner Definition in BEASNA File

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

#### Viewing 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 SNA installation by running the sample application. At this stage, you should have completed the following prerequisites:

- Installed the BEA eLink for Mainframe SNAsoftware

- Configured the BEA TUXEDO and eLink SNA local domains

- Configured the CICS/ESA remote domain

- Initialized the stack processes

- Booted the servers

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

### Running the Application from a TUXEDO 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"

where:

`-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 BEA TUXEDO 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 paragraphs 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 SNA 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>

where:

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

where:

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

Home Previous Topic Next Topic