Chapter 5 . Administering BEA Connect TCP for CICS

This section describes what you must do to start BEA Connect TCP for CICS

Starting the Listener Program

The Listener program is supplied by IBM and is part of the Sockets for CICS software product which must be purchased from IBM. Before you can use BEA Connect TCP for CICS, you must install and configure both IBM TCP/IP and the Sockets for CICS product as outlined in the documentation that accompanies those products.

The Listener's job is to wait for connection requests at a particular network address and port of your choosing. When the Listener receives a connection request it invokes the appropriate CICS program automatically, based on the name supplied as part of the Listener's connection protocol buffer. For example, if the Listener receives a connection request from Connect TPS running on a remote BEA TUXEDO node, it processes the connection and invokes the BEA Connect TCP Handler.

Invoking Connect TCP for CICS

The Connect TCP Handler is invoked automatically by the Listener process. Once invoked, the Handler takes control of the socket connection and retains control either until the Handler is shut down or until there is a network problem that affects the socket connection. The Handler processes service requests in a serialized manner. To process several service requests at the same time, start more than one Handler. Due to the limitations of the IBM Sockets for CICS Listener, the maximum number of concurrent socket connections is 50, which means that up to 50 Handlers can be processing service requests at any one time.

Starting the Requester Program

The Requester is started automatically when the first service request for it is made by a CICS client program. At that point, the Requester establishes a connection with its remote endpoint and updates its control tables with run-time information for use by subsequent requests. If the connection with the remote endpoint is lost for any reason, the Requester attempts to re-establish the connection automatically. After a configured number of unsuccessful connection attempts, the Requester will mark itself disabled.

Administrative Commands

There is a subset of commands that can be issued by the Connect TPS administrator (in the BEA TUXEDO domain) that may be helpful to the CICS administrator. In addition, BEA Connect TCP for CICS has an easy to use on-line application tool available for CICS administrators. The BEA TUXEDO tmadmin subcommands are discussed first.

BEA TUXEDO includes a set of tmadmin subcommands for the administration of gateways to remote systems or regions. These two subcommands, summarized here in Table 5-1, are fully supported by Connect TCP.

These two subcommands operate by invoking the standard BEA TUXEDO gateway administrative service (GATE_ADMIN) that is offered by Connect TPS Liaisons.

Refer to your BEA TUXEDO documentation for detailed information about the tmadmin command.

The printdomain Subcommand

The printdomain subcommand (pd) displays information about Connect TPS gateways. The results include the following items:

• Names of Connect TPS server groups

• Configuration of gateway servers

• Other information

Syntax and Usage

The syntax of the printdomain subcommand is as follows:

tmadmin

printdomain (pd) [ { -i srvid | -g grpid | -q qaddress} ]

where:

-i srvid

specifies an integer that uniquely identifies a server within a server group. The server you specify is a Connect TPS Liaison that offers the gateway administrative service.

-g grpid

specifies the name of the Connect TPS server group. This is the group to which the specified server (srvid) belongs.

-q qaddress

specifies the queue address of a Connect TPS Liaison that offers the gateway administrative service.

As the syntax indicates, you specify a Connect TPS Liaison by using its srvid, grpid, or qaddress. However, there is one condition. If you use a srvid, the srvid must be unique across the entire node. If the srvid is not unique, you must specify one of the following parameters:

• the srvid and the grpid with which it is associated

• the qaddress

If you don't specify any parameters when you use the printdomain subcommand, all servers that offer the gateway administrative service are queried for information.

Note: For more specific information about these parameters, see ubbconfig(5) in the BEA TUXEDO system documentation.

Example

Here is an example of the output that the printdomain subcommand produces.

printdomain

The stats subcommand prints statistical information about services that are available through Connect TPS gateways. An example of the output that the stats subcommand produces is provided later in this chapter.

You can obtain statistics for a single service by specifying the service name when you issue the subcommand.

Syntax and Usage

The syntax of the stats subcommand is as follows:

tmadmin
stats { -i srvid | -g grpid | -q qaddress }  [ -s service ]

where:

-i srvid

specifies an integer that uniquely identifies a server within a server group. The server you specify is the Connect TPS Liaison that offers administrative services to the gateway.

-g grpid

specifies the name of the Connect TPS server group. This is the group to which the specified server (srvid) belongs.

-q qaddress

specifies the queue address of a Connect TPS Liaison that offers administrative services to the gateway.

-s service

specifies a single service about which you want statistical information.

As the syntax indicates, you can obtain information about services by specifying one of the following parameters:

• The identifier of a Connect TPS Liaison

• The server group to which the Connect TPS Liaison belongs

• The queue address of a Connect TPS Liaison

There is one condition. If you specify a srvid, the srvid must be unique across the entire node. If the srvid is not unique, you must specify one of the following parameters:

• the srvid and the grpd with which it is associated

• the qaddress

You can obtain statistics for a single service by specifying the service name when you issue the subcommand.

Note: For more specific information about these parameters, see the ubbconfig(5) manual page in the BEA TUXEDO documentation.

Example

Here is an example of the stats subcommand and the output it produces.

$tmadmin
> stats -q GW_1

REMOTE SERVICES:

node1 GWIPCKEY=38200 GWID=GW_1
                ==SVCS=DONE== DATA  ==AVERAGE=USER=DATA==  ====LAST=USER=DATA===
SERVICE NAME   PASS   FAIL   MSGS    SENT SVNG  RCVD SVNG   SENT SVNG  RCVD SVNG
-------------  ----   ----   -----   ---- ----  ---- ----   ---- ----  ---- ----
OpenAccount       0      0       0      0   0%     0   0%      0   0%     0   0%

node2 GWIPCKEY=38200 GWID=GW_2
              ==SVCS=DONE==  DATA   ==AVERAGE=USER=DATA==  ====LAST=USER=DATA===
SERVICE NAME   PASS   FAIL   MSGS    SENT SVNG  RCVD SVNG   SENT SVNG  RCVD SVNG
-------------  ----   ----   -----   ---- ----  ---- ----   ---- ----  ---- ----

DEPOSIT           0      0       0      0   0%     0   0%      0   0%     0   0%
WITHDRAW          0      0       0      0   0%     0   0%      0   0%     0   0%
BALANCE           0      0       0      0   0%     0   0%      0   0%     0   0%
              ====== ====== ======   ===== ==== ===== ====
                  0      0       0      0   0%     0   0%

LOCAL SERVICES:

node3 GWIPCKEY=38201 GWID=GW_3
              ==SVCS=DONE==  DATA   ==AVERAGE=USER=DATA==  ====LAST=USER=DATA===
SERVICE NAME   PASS   FAIL   MSGS    SENT SVNG  RCVD SVNG   SENT SVNG  RCVD SVNG
-------------  ----   ----   -----   ---- ----  ---- ----   ---- ----  ---- ----
TRANSFER           0       0        0       0    0%     0    0%      0    0%     0    0%

The following subsections describe the BEA Connect TCP for CICS Maintenance System. The BEA Connect TCP Maintenance System is an on-line CICS application for use in configuring, maintaining, and administering the BEA Connect TCP for CICS gateway. To start the administration system, enter the transaction code as defined to CICS in the installation procedure.

Menu Navigation

Figure 5-1 illustrates the hierarchy of screens in the Maintenance System. You can access any maintenance screen from the Main menu, shown at the top of the figure. Below it are three groups of menus for maintaining connections, requesters, and services. Table 5-2, below, describes how you can use each group of menus.

Each of these topics is discussed in more detail in the following sections.

The Main Menu

The Main menu, pictured below, gives you access to all the maintenance screens.

Figure 5-2 Main Menu

Usage

Use the Main menu to access the screens that make up the maintenance system. To move from the Main menu to a sub-menu, enter the appropriate two-character code. The first character in the code denotes the area on which you want to operate and the second character denotes the operation you want to perform on that area.

The following are the codes for the three areas of operation:

• C - Connections

• R - Requesters

• S - Services

The following are the codes for the allowable operations:

• 1 - Insert

• 2 - Update

• 3 - Inquire

• 4 - Delete

• 5 - Browse

Because some operations are not available in all three areas, there are only twelve valid combinations, as shown in the following table.

You can use the Maintenance System screens to view and alter a connection, but not to insert (create) or delete a connection. Connections are created and deleted by BEA Connect TCP for CICS in its normal operation.

The maintenance system will check the two-character selection code that you enter and will display the appropriate screen if the code is valid. If the code you enter is not valid you will receive an error message.

Note: The maintenance screens use the field name LOGICAL MACHINE NAME. The logical machine name corresponds to a Connect TPS Gateway ID.

The Connections Screens

The three screens available for maintaining connection instances are labeled Update, Inquiry and Browse. The screens allow you to make an inquiry concerning a specific connection, to browse a list of all connections, or to disable/enable a connection.

A connection instance is an established TCP/IP connection between a Requester and a remote endpoint. For the purposes of BEA Connect TCP for CICS, a remote endpoint is a BEA Connect TPS Handler executing within a remote BEA TUXEDO domain.

The Connections Update Screen (C2)

Usage

Use this screen to update a record from the Connection file. When the screen is initially displayed, the LOGICAL MACHINE NAME field is unprotected. Enter a valid Gateway ID (GWID) and press ENTER.The screen is redisplayed showing the data from the record you specified and the STATUS field is unprotected. The message RECORD READY FOR UPDATE is displayed. You can now make changes to the record.

PF Keys

The following function keys are available on this screen.

ENTER

Process the data entered

PF3

Transfer to Main Menu

PF5

Transfer to Connections Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the update process is aborted and the new screen is displayed.

Usage

Use this screen to inquire about a record from the Connection file.

When the screen is initially displayed, the LOGICAL MACHINE NAME field is unprotected. Enter a valid GWID and press ENTER.The screen is redisplayed with the data from the record you specified and the LOGICAL MACHINE NAME field is unprotected.

PF Keys

The following function keys are available on this screen.

ENTER

Process the data entered

PF3

Transfer to Main Menu

PF5

Transfer to Connections Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the inquiry process is aborted and the appropriate screen is displayed.

Usage

Use this screen to browse records in the Connection file and to select individual records for further processing. If you access this screen from the Main menu, the first record on file is displayed at the top of the screen. If you access this screen from the Connection Update screen or the Inquire screen, the list starts with the key received from that screen.

To select a record for processing enter a valid selection code in the SEL CDE field. For example, to make an inquiry about a record, enter "3". If you enter more than one selection code, the first one is used and all others are ignored. After the selection code is validated and processed, the screen for that process is displayed, and the record key appears in the LOGICAL MACHINE NAME field.

PF Keys

ENTER

Process the selection code entered

PF3

Transfer to Main Menu

PF7

Display the previous page of records

PF8

Display the next page of records

A Requester is responsible for collecting request information to be sent to the remote BEA TUXEDO domain. The Requester establishes network connectivity, transmits data to BEA TUXEDO, and receives data from BEA TUXEDO. Each Requester is responsible for one and only one remote endpoint (or one TCP/IP address/port combination). You can configure more than one Requester to point to the same endpoint, but each Requester worries about only one endpoint.

On the following maintenance screens, each instance of the Requester is given a Gateway ID (GWID). You can give a Requester any unique GWID that is meaningful to you. Every service name is associated with one or more GWIDs. That's how the Requester knows which remote machine is responsible for a particular service.

The Insert Requester Screen (R1)

Usage

Use this screen to configure a new Requester by inserting a new record into the Requester file.

When the screen is first displayed, all the fields are unprotected. Type the required data as described in the table below, then press ENTER. After the data is validated and processed, the screen is redisplayed and all the fields are unprotected.

Fields

Field Name	Description
Logical Machine Name	This is the GWID. Give it a unique name up to 16 characters. Example: (bankmach1)
Host Address	The TCP/IP dot address. Example: (199.99.99.99)
Port Number	The TCP/IP port. Check with the TCP/IP administrator for available ports. Example: (11111)
Account ID	An eight-character ID. This must be the same ID that is used on the BEA TUXEDO side configuration. Coordinate with the BEA TUXEDO Administrator. Required if there is an entry in the Password field. Example: (CICS001A)
Password	An eight-character password. This must be the same as on the BEA TUXEDO side configuration. Coordinate with the BEA TUXEDO Administrator. Required if there is an entry in the Account ID field. Example: (LETMEIN1)
Max Msg Size	The largest message allowed to be sent across this connection. The maximum is 31936. Example: (32000)
Connect Retry Limit	If the connection fails, this number determines how many attempts the system will make to reestablish the connection before marking the connection disabled. Example: (5).
LMID	The version of TPS you are running (C for CICS, I for IMS, T for TCP, L for InterLink)
Start TranID	The ID of the transaction to be started (C for CICS)

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Requester Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the insert process is aborted and the appropriate screen is displayed.

Usage

Use this screen to update a record from the Requester file.The fields are the same as the ones on the Requester Insert screen, but on this screen you can change the values.

When the screen is first displayed, the LOGICAL MACHINE NAME field is unprotected. Enter a logical machine name and press ENTER. The screen is redisplayed showing the data from the requested record. The HOST ADDRESS, PORT NUMBER, ACCOUNT ID, PASSWORD, MAX MSG SIZE, and CONNECT RETRY LIMIT fields are unprotected. The following message is displayed: RECORD READY FOR UPDATE.

After the changes you entered are validated and processed, the screen is redisplayed and the LOGICAL MACHINE NAME field is unprotected.

PF Keys

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Requester Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the update process is aborted and the appropriate screen is displayed.

Usage

Use this screen to make an inquiry about a record from the Requester file.

The screen is initially displayed with the LOGICAL MACHINE NAME field unprotected. Enter the logical machine name and press ENTER. The screen is redisplayed with the data from the requested record and the LOGICAL MACHINE NAME field is unprotected.

PF Keys

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Requester Browse

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the inquiry process is aborted and the appropriate screen is displayed.

Usage

Use this screen to delete a record from the Requester file.

Warning: Deleting a Requester record can have serious ramifications. Think carefully before performing this operation. If there are any Service records that point to this GWID, any client calls to those services will be rejected because BEA Connect won't know to which remote machine the request should go.

The screen is initially displayed with the LOGICAL MACHINE NAME field unprotected. Enter the logical machine name and press ENTER. The screen is then redisplayed with the data from the requested record and the LOGICAL MACHINE NAME field is protected. The following message is displayed: TO CONFIRM DELETE, PRESS ENTER AGAIN.

PF Keys

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Requester Browse

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the deletion process is aborted and the appropriate screen is displayed.

Usage

Use this screen to browse a list of the records in the Requester file. Additionally, you can select a record for further processing by entering a valid selection code in the first column of that record's row.

If you access this screen from the Main menu the first record on file is displayed at the top of the screen. If you access this screen from the Insert, Update, Inquire, or Delete screens, the key received from that screen determines which records are displayed.

To choose a record, enter a valid selection code in the SEL CDE field next to that record. For example, to make an inquiry about a record, enter "3". If you enter more than one selection code, the first one is used and the others are ignored.

After the entry in the SEL CDE field is validated and processed, the screen for that process is displayed and the record key appears in the LOGICAL MACHINE NAME field.

PF Keys

ENTER

Process the selection code entered

PF3

Transfer to Main menu

PF7

Display the previous page of records

PF8

Display the next page of records

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the deletion process is aborted and the appropriate screen is displayed.

A service is a name associated with some component of work. That component of work might be a banking transaction, an airline flight reservation, or an order for a dozen widgets.In BEA TUXEDO, a client program that needs work done makes a "service request." A process called a server performs the work described in the service request on behalf of the client, then returns the results of its efforts back to the client. In MVS this would be referred to as a call to a "black box."

In a CICS application that uses BEA Connect TCP for CICS, a service name is passed in the data area in an EXEC CICS LINK command and the results are returned in that same area. The service screens use the terms "service name" and "remote service name". The service name (e.g., CIC01XXYYZZ) is what the service is known as to your CICS environment and the remote service name (e.g., WITHDRAWAL) is what the service is known as to BEA TUXEDO. For simplicity, you can make both names the same, but if naming conventions differ, you can use different names.

BEA Connect TCP for CICS uses a "first available" scheme for locating a remote machine on which to satisfy a service request. You can add more than one entry for each service and use a different GWID for each one. BEA Connect will attempt to satisfy a service request using the first record for a particular service. If that remote endpoint is busy or disabled, BEA Connect will try the next GWID configured for that service until all configured GWIDs are exhausted.

The Service Insert Screen (S1)

Usage

Use this screen to insert a record into the Service Name file.

The screen is first displayed with all fields unprotected. Enter the required data in the fields listed below and press ENTER. After the data is validated and processed, the screen is redisplayed and all the fields are unprotected.

Fields

Field Name	Description
Service Name	The service name as it is known to the CICS programmer
Logical Machine Name	This is a symbolic name as it was defined on the Requester Insert screen. It denotes the remote machine on which this service should be processed.
Remote Service Name	The name as it is known in the remote BEA TUXEDO domain.
Service Timeout:	The number of seconds to wait for timing out this service request.

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the INSERT process is aborted and the appropriate screen is displayed.

Usage

Use this screen to update a record from the Service Name file.

When the screen is first displayed, the SERVICE NAME and LOGICAL MACHINE NAME fields are unprotected. Enter the service name and logical machine name, and press ENTER. The screen is then redisplayed with the data from the requested record and the REMOTE SERVICE NAME and SERVICE TIMEOUT(SEC) fields are unprotected.The following message is displayed: RECORD READY FOR UPDATE.

After the changes are validated and processed, the screen is redisplayed and the SERVICE NAME and LOGICAL MACHINE NAME fields are unprotected.

PF Keys

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the UPDATE process is aborted and the appropriate screen is displayed.

Usage

Use this screen to make an inquiry about a record from the Service Name file.

The screen is initially displayed with the SERVICE NAME and LOGICAL MACHINE NAME fields unprotected. Enter the service name and logical machine name and press ENTER. The screen is redisplayed with the data from the requested record and the SERVICE NAME and LOGICAL MACHINE NAME fields are unprotected.

PF Keys

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the inquiry process is aborted and the appropriate screen is displayed.

Usage

Use this screen to delete records from the Service Name file.

The screen is initially displayed with the SERVICE NAME and LOGICAL MACHINE NAME fields unprotected. Type the service name and logical machine name and press ENTER. The screen is redisplayed with the data from the record requested and all the fields protected.

The following message is displayed: TO CONFIRM DELETE, PRESS ENTER: AGAIN. After you press enter to confirm the deletion, the screen is redisplayed and the SERVICE NAME and LOGICAL MACHINE NAME fields are unprotected.

PF Keys

ENTER

Process the data entered

PF3

Transfer to Main menu

PF5

Transfer to Browse screen

Note: If you enter data and press PF3 or PF5 before pressing ENTER, the deletion process is aborted and the appropriate screen is displayed.

Usage

Use this screen to browse the records in the Service Name file. If you access this screen from the Main menu the first record on file is displayed at the top of the screen. If you access this screen from the Insert, Update, Inquire, or Delete screens, the list starts with the record key received from that screen.

To select a record for processing, enter a valid selection code. For example, to make an inquiry about a record, enter "3". If you enter more than one selection code, the first one is used, and the others are ignored. After the selection code is validated and processed, the screen for that process is displayed and the record key appears in the SERVICE NAME and LOGICAL MACHINE NAME fields.

PF Keys

ENTER

Process the selection code entered

PF3

Transfer to Main menu

PF7

Display the previous page of records

PF8

Display the next page of records