ATMHELLO Test Verification Program

To allow out-of-the-box testing of the Bridge, a small CICS Hello World transaction is available for use after the Attachmate Services Builder for CICS 3270 Bridge is installed. This transaction is used to determine the status of the bridge. It reports the bridge version and other useful information. Sample ASP, Java, and JSP client code is provided to test remote connectivity to the bridge.

ATMHELLO Host Components

The ATMHELLO test program is installed during the base product install and provides the following capabilities:

A CICS COBOL transaction program (ATMHELLO) and a BMS Mapset (ATMMAPB) are optionally installed on the host during the product SMP/E install. A default name, ATM1, is used for the CICS four-character transaction code. If you want, you can change the default name during the CICSDEF phase of the installation. This transaction can be called using standard emulation software such as Attachmate EXTRA! X-treme to verify that it is available after the Bridge is installed.
The ATMHELLO application helps verify your SMP/E install by displaying pertinent information about the CICS environment for the install and product build data for the Server (XTR1A002), Converter (XTR1A001) and Analyzer (XTR1A000). This product build data will be helpful for Attachmate support, should you ever need their services.

		 LINE # 01  ATMMAPB      Attachmate Verification Program                    ATM1
LINE # 02                                                          AAAAAAAAAAAA
LINE # 03          Welcome to                                      BBBBBBBBBBBB
LINE # 04          Attachmate                                      CCCCCCCCCCCC
LINE # 05          Test Verification Program                       DDDDDDDDDDDD
LINE # 06                                                          EEEEEEEEEEEE
LINE # 07     Absolute System Time     003318052371890             FFFFFFFFFFFF
LINE # 08                                                          GGGGGGGGGGGG
LINE # 09     Terminal ID              CP19                        HHHHHHHHHHHH
LINE # 10     Network ID               SC0TCP19                    IIIIIIIIIIII
LINE # 11     Appl ID                  A21CICS                     JJJJJJJJJJJJ
LINE # 12     System ID                CICS                        KKKKKKKKKKKK
LINE # 13     User ID                  P390B                       LLLLLLLLLLLL
LINE # 14                                                          MMMMMMMMMMMM
LINE # 15     Server Date         2005-02-17 17:00:50.030100       NNNNNNNNNNNN
LINE # 16                                                          OOOOOOOOOOOO
LINE # 17     Converter Version   001  001  001                    PPPPPPPPPPPP
LINE # 18     Converter Date      2005-02-15 00:25:30.246421       QQQQQQQQQQQQ
LINE # 19                                                          RRRRRRRRRRRR
LINE # 20     Analyzer Version    001  001  001                    SSSSSSSSSSSS
LINE # 21     Analyzer Date       2005-02-09 19:01:32.134096       TTTTTTTTTTTT
LINE # 22                                                          UUUUUUUUUUUU
LINE # 23          YOU PRESSED:                  ENTER             VVVVVVVVVVVV
LINE # 24     PF3=EXIT  PF4=ATM LOGO                               WWWWWWWWWWWW

Standard CICS environment information is displayed including, TERMID, NETID, Application ID, System ID, and User ID. This information can be useful for troubleshooting issues such as user security access or session pooling.
The last Attention Identifier (AID) key pressed is displayed and the transaction will be called again until the application is exited. The application is exited by pressing either PF3 or the Clear button. A separate logo screen is provided that can be used to test basic navigation—accessed by pressing PF4.
After testing, the test transaction can be removed, but you may want to consider leaving it in place to provide a demarcation test for the functionality of the Bridge as the systems are placed into production. If, after using the ATMHELLO transaction to test the basic functionality of the Bridge, and you wish to uninstall it, follow the uninstall instructions later in this document.

Uninstalling the Sample Transaction Host Components

Copy the uninstall HELLODEL JCL to the library of your choice on the host.
Customize the job, STEPLIB and DHHCSD DD cards, then run the HELLODEL JCL job to delete the program, map, and transaction.
Use CEMT to discard the elements or cold-start the CICS region to uninstall the following definitions:

CEMT	DISCARD	TRANSACTION (ATM1)
CEMT	DISCARD	PROGRAM (ATMHELLO1)
CEMT	DISCARD	PROGRAM (ATMMAPB)

Optionally, use TSO to remove the ATMHELLO and ATMMAPB load modules from the CICS load library. You may want to consider leaving the modules in place if they are needed in the future for troubleshooting.

Customizable HELLODEL - JCL Code

(Deletes CICS Program, Group, and Transaction)

//CICSDEF JOB (BATCH),BLDSMP1.SMPEUSER,
//             MSGCLASS=X,NOTIFY=&SYSUID,
//             REGION=6M,TIME=1439
//*
//*** REMOVE CICS DEFINITIONS FOR
//*** SYNAPTA(TM) SERVICES BUILDER(TM)
//*** FOR CICS(R) 3270 BRIDGE ATMEHLLO 
//*
//********************************************************************
//* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
//*
//********************************************************************
//*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS
//*
//*  GLOBAL CHANGE &CICSLOAD
//*    to the prefix of the LOADLIB containing DFHCSDUP
//*
//*  GLOBAL CHANGE &CICSREG
//*    to the prefix to the CSD for the target region
//*
//*  GLOBAL CHANGE &TRAN
//*    to the desired Clean up transaction
//*
//*   Note that Attachmate recommends ATMC as the Clean up Tranid
//* The value must match the value used in the configuration
//* macro for the Converter (XTR1A001).
//*
//*  GLOBAL CHANGE &SAMPTRAN
//*    to the desired supplied sample application transaction.  For
//*    example ATM1 (if unused at your installation).
//*
//*  GLOBAL CHANGE &CICSDEF
//*    to the desired RDO group name.
//*
//********************************************************************
//*
//DEFINE EXEC PGM=DFHCSDUP,REGION=1024K,
//            PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT'
//STEPLIB DD  DSN='&CICSLOAD.SDFHLOAD',DISP=SHR
//SYSPRINT DD SYSOUT=A
//DFHCSD   DD DSN='&CICSREG.DFHCSD',DISP=SHR
//SYSIN  DD *
*
***** DELETE PROGRAM ***************************************           
DELETE PROGRAM(ATMHELLO) GROUP(&CICSDEF)                               
                                                                        
***** DELETE MAP********************************************           
DELETE MAPSET(ATMMAPB) GROUP(&CICSDEF)                                 
                                                                        
***** DELETE SAMPLE TRANSACTION ****************************           
DELETE TRANSACTION(&SAMPTRAN) GROUP(&CICSDEF)
/*

Example HELLODEL - JCL Code

(Deletes CICS Program, Group and Transaction)

//JOBNAME1  JOB ,'HELLODEL',NOTIFY=&SYSUID,                                
//          CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)                             
//*********************************************************************   
//DFHCSDUP EXEC PGM=DFHCSDUP,REGION=6M,                                   
//*        PARM='CSD(READONLY),PAGESIZE(60),NOCOMPAT'                     
//         PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT'                    
//**** YOUR CICS LIB                                                      
//STEPLIB DD   DSN=SYS2.CICSTSXX.LOADLIB,DISP=SHR                         
//**** YOUR CICS CSD                                                      
//DFHCSD   DD  DISP=SHR,DSN=CICSTS22.CICS.DFHCSD                          
//OUTDD    DD  SYSOUT=*                                                   
//SYSPRINT DD  SYSOUT=*                                                   
//CBDOUT   DD  SYSOUT=*                                                   
//SYSIN    DD  *                                                          
***********************************************************************   
***  ATTACHMATE - TEST PROGRAM REMOVAL SAMPLE                       
***   
***  UPDATED 3/15/2005                                              
***      
***********************************************************************   

***** PROGRAM **********************************************           
DELETE PROGRAM(ATMHELLO) GROUP(XTR3DEF)                               
                                                                        
***** MAPS **********************************************           
DELETE MAPSET(ATMMAPB) GROUP(XTR3DEF)                                 
                                                                        
***** TRANSACTIONS ******************************************           
DELETE TRANSACTION(ATM1) GROUP(XTR3DEF)                               
/*

Client Components

Included on the CD in the \Samples\ATMHello directory are the BridgeTester.asp, BridgeTester.jsp, and BridgeSimple1.java samples.

In a production application it is typically appropriate to add additional error handing logic beyond what is contained in these basic samples.

ASP Sample

The ASP sample can be used to call a test transaction such as ATM1 and then display the screen that is returned. You can continue to send keys to the transaction using standard HLLAPI style keys. Refer to the application programming guides for further information.

Before you run the ASP page, use a text editor to edit the file and replace the IP Address with that of the target system, and set the port to the port number corresponding to that target CICS region. Also, provide a user name and a password for the target host system that is running the Bridge.

The sample ASP page uses the COM BridgeAPI.dll which must be installed using the Attachmate COM Client Install Program. This step must be done before the test ASP page is used to communicate to the Bridge.

Active Server pages run under the Microsoft Internet Information Server. To install the sample ASP, check with the IIS web server administrator for local standards and procedures. It may be acceptable to create a BridgeTester directory in Inetpub\wwwroot, then copy the sample ASP page to that directory. If this is done you will be able to call the ASP page using a URL such as:

http://localhost/BridgeTester/BridgeTester.asp

You can edit the keys to send to the test application. The ASP page provides ATM1@E to call the default test transaction using the ENTER key.

Additional steps to enable access to the ASP page may be required depending on how security is configured in IIS. You may need to ask the IIS web server administrator to change security settings to enable the ASP page to run.

JSP Sample

The JSP sample can be used to call a test transaction such as ATM1 and then display the screen that is returned. You can continue to send keys to the transaction using standard HLLAPI style keys. For more information, refer to the javadocs included with the product. Before you run the JSP page, use a text editor to edit the file and replace the IP Address with that of the target system and set the port to the port number corresponding to that target CICS region. Also, provide a user name and password for the target host system that is running the Bridge.

Java Server Pages run under many Java platforms. The Apache web platform is a common open source platform and will be assumed for the configuration. Other Java platforms such as those provided by BEA will be similar. You may be required to configure additional information for different platforms. Refer to the platform documentation for further information.

To install the sample JSP, check with the web server administrator for local standards and procedures. It may be acceptable to create a BridgeTester directory in Apache_Root\webapps and then copy the sample JSP page to that directory.

The sample JSP page uses the Java BridgeAPI.jar which must be copied to a lib directory on the Java platform so it is available. You must complete this step before the test JSP page is used to communicate to the Bridge. For example, if you are using Apache Tomcat, you might use the following directory structure:

Tomcat/webapps/BridgeTester/WEB-INF/Lib/

with the BridgeTester.jsp file in the BridgeTester folder and the BridgeAPI.jar file in the Lib folder.

You may have to change the default port number (8080) to match your installed configuration. To run the samples after installing or upgrading, you may need to restart your application server.

When you have completed those steps, you will be able to call the JSP page using a URL such as:

http://localhost/BridgeTester/BridgeTester.JSP

Additional steps to enable access to the JSP page may be required depending on how security is configured. You may need to contact the web server administrator, if this is the case, to enable the JSP page to run.

When the JSP page is running, you can edit the keys to send to the test application. By default, the JSP page provides ATM1@E to call the default test transaction using the ENTER key.

The sample JSPs were developed and tested on Windows 2000 using the HTTP Apache Tomcat server that is installed with MCS. The sample application should work on other Java server platforms providing the following requirements are met:

A web server running JDK 1.4 (or greater) with JSP support (minimum version 1.2)
IE 5.0 or greater

If you have questions concerning JSPs, refer to JSP programming books for more information, or visit the Sun JSP home page at http://java.sun.com/

Java Sample

The Java sample is coded to call the ATM1 test transaction and then display the screen that is returned. Before you compile the BridgeSimple1.java program, use a text editor to edit the file and replace the IP Address with that of the target system and set the port to the port number corresponding to that target CICS region. Also, provide a user name and password for the target host system that is running the Bridge. If you used a transaction code of something other then ATM1 for the Attachmate verification, change that in the BridgeSimple1.Java sample as well.

BridgeSimple1 is a console Java application that requires the Sun Java SDK.

The sample Java program uses the Java BridgeAPI.jar which must be copied to a directory containing the BridgeSimple1.java program that you created. The four files listed below comprise the sample Java program.

SimpleBridge1.java
BridgeAPI.jar
Compile.bat
Run.bat

To install the sample Java program

Create a directory on your machine and copy the four files to that local directory.
Run the compile.bat file to create a SimpleBridge1.class run-time file.
When these steps are completed, run the run.bat file to call the program.

If you have questions concerning Java, refer to Java programming books for more information, or visit the Sun JSP home page at http://java.sun.com/

Sample Command Tester Tool

On the product CD in the \Samples\Command_Tester directory, the four files listed below comprise the sample Command Tester tool.

BridgeCmdTester.exe
BridgeRetCodes.txt
BridgeRetCodesNote.txt
Interop.BRIDGEAPILib.dll

To use the Command Tester tool

Create a directory on your machine and copy the four files to that local directory.
Run the BridgeCmdTester.exe file.
You will be presented with the Command Tester user interface.
Under Bridge Commands, from the Command drop-down list, select a command (API Method), and in the Paramenters group box, type the appropriate parameters in the various parameters fields.
Upon completion, click the ADD CMD button to add your completed method to the Commands to Run window.
Click the RUN button and your Brige Command Tester sequence is run against the CICS region you identified in your ConnectBridge.

In order for this tool to work, the COM and/or .NET client must have been previously installed.

The default requestor used by the Bridge Command Tester is the COM requestor.

To switch to the .NET requestor
Under Requestor Type/Information, choose the .NET option. The IP Address and Port fields are enabled to allow you to identify the location of your .NET Requestor (managed web service). When you are satisfied with your sequence of commands, from the File menu, select Save to keep the sequence for later use.

To enhance your sequence
In the Commands to Run dialog box, select a command. Click the UPDATE CMD or DELETE CMD button.


	Installation, Overview
	Upgrading, Overview
	Installing MCS in UNIX
	Installation Prompts for Management Components in Windows