After installing and configuring the BEA Connect 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 SNA gateway environment, start the Physical Unit (PU), start the SNACRM, and start TUXEDO. Refer to Chapter 4, "Configuring BEA Connect SNA," and Chapter 5, "Administering the BEA Connect SNA Application Domain," for details.
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 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 TUXEDO server. Again, you enter a text string in lower-case letters. The 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 TUXEDO applications and CICS/ESA applications. If your TUXEDO applications operate in other environments, you must create your own verification process.
You must build the verification test to run in two domains, the 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.
Use the following checklist to complete this process:
tmloadcf command to compile the UBBCONFIG file.
dmloadcf command to compile the DMCONFIG file.
apps.env and <machine>.env environment files (optional).
Use the 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.)
Use the 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
Include the name of the TUXEDO simple server in the UBBCONFIG file. 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. The application server GROUP3 in the Groups section must point to a valid transaction manager server.
Note:
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.)
For example:
*GROUP
GROUP3 LMID=sna GRPNO=3 TMSNAME=<transaction mgr name>
#example TMSNAME=tstms
mirrorsrv SRVGRP=GROUP3 SRVID=1 RQADDR=MIRR1 REPLYQ=Y
*SERVICES
MIRROR
Execute the 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.
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 6-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. 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 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.
Two types of files are provided with your Connect 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.
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 6-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
Modify the <machine>.env file that is appropriate for your system:
aix.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 6-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 6-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 6-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
Use the following checklist to complete this process:
The CICS/ESA sample programs used for verification are unloaded during the installation of your BEA Connect 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 TUXEDO executable program that you build communicates with either.
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 6-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.
Transferring the Source Code to Host
This step translates the 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 The translator module name in the following example is Translating CICS/ESA Verbs
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.
CICSxxx.SDFHLOAD entry, where xxx is the CICS/ESA release number.
COBOL Language Translator Example
DFHECP1$. The parameter COBOL2 indicates that a source module containing COBOL II verbs is to be translated.
Listing 6-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))
The translator module name in Listing 6-7 is DFHEDP1$. The parameter C indicates that a source module containing C verbs is to be translated.
Listing 6-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))
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)
Listing 6-8 shows a COBOL compiler example.
COBOL Compiler Example
Listing 6-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))
Compile and pre-link your C language source. The BEA Connect SNA installation library contains C language compiler examples. Listing 6-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 6-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+*
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 6-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 6-10 COBOL Link-Edit Sample forTOUPDPLS, 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 6-11 COBOL Link-Edit Sample forMIRRDTPC
//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 6-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=*
Your installed Connect SNA software contains two sample files that can be used to configure the CICS application:
BEACONN file contains the CICS/ESA configuration parameters to the host system. These include connection definitions and session definitions.
One method of adding the files is to use the batch utility program DFHCSDUP. Listing 6-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 6-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 Connect 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)
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 6-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 Connect SNA software acquire the connection and negotiate the bind when the Connect 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)
The BEACONN file also includes a sample session definition. When placed on the remote host, it defines the logical links by which the 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 6-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 Connect 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.
The BEASNA file includes a sample program definition, shown in Listing 6-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 6-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)
The BEASNA file also contains a sample remote program definition, shown in Listing 6-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 6-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)
The BEASNA file also contains a sample transaction definition, shown in Listing 6-18.
Listing 6-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)
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 6-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" on page 4-14).
Listing 6-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**)
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
Now you are ready to validate the Connect SNA installation by running the sample application. At this stage, you should have completed the following prerequisites:
The sample application contains several scenarios. When the client runs as a TUXEDO client, the server runs as a CICS/ESA host. When the client runs as a CICS/ESA client, the server runs as a TUXEDO server.
In this scenario, the For example, enter the following command:
where:
Running the Application from a TUXEDO Client
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
toupclt -s 0 -t DTP "hello world"
-s (0|2)
-t (DPL|DTP)
-h
If the TUXEDO client successfully executes the command, it displays the text string in upper-case letters, for example:
"HELLO WORLD"
The following paragraphs depict two scenarios for running the application from a CICS/ESA client.
In this scenario, the CICS/ESA client sends a text string to the Connect 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>isa 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"
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>isa 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"