PreviousCCI Status Messages Attachmate Personal Client v6.1 and v6.2Next

Appendix A: Attachmate Personal Client v6.3


Note: Screen snapshots are copyright Attachmate Corporation


Important Bulletin Regarding Support For Attachmate EXTRA! Personal Client


This document provides views of a sample installation for Attachmate Personal Client v6.3 for 95/NT over an 802.2 DLC connection. We have validated the CCIAPPC component against Attachmate Personal Client version 6.1, 6.2 and 6.3. This document is arranged in a logical sequence for an new installation of the Attachmate product.

A.1 Installing DLC for Windows 95

The Rumba product requires the Microsoft 32-bit DLC protocol to provide support for a connection over 802.2. You should already have installed the 32-bit DLC driver for Windows 95 or Windows NT. If you have not yet done this, please follow the instructions for installing this driver in Configuring DLC over 802.2 on Windows 95 or Configuring DLC over 802.2 on Windows NT.

A.2 Installing Attachmate Personal Client

You should have already installed Attachmate Personal Client. We suggest that you confirm that the CPI-C interface is installed before continuing, the 3270 display portion of this product will be fully functional without CPI-C, but CCIAPPC will not be able to access APPC.

A.3 Configuring Attachmate Personal Client

After successfully installing the Attachmate Personal Client product, you can start to configure your APPC connection. You should have a VTAM definition of the connection you are attempting to configure available to you during the configuration. Select Start from the Taskbar, then Programs, then EXTRA! Personal Client 32-bit, then APPN Configurator. The APPN Configurator window will be displayed. A sample window with a full configuration is displayed below for reference.

A.4 Step 1: Creating a New Configuration

The first screen presented in the configuration tool allows you to enter a new configuration by choosing File from the action bar and selecting New to create a new configuration.

A.5 Step 2: Local Node Definition

Select Node Definition from the Sections window and then click the Add button. The Local Node Configuration window will appear.

  1. Enter the Network ID for this SNA network. This should be obtained from the network administrator of the host system.
  2. Enter the Control Point (CP) name assigned to this machine. This should be obtained from the network administrator of the host system. The CP Name should match the Physical Unit (PU) name assigned to this machine as specified in the PU definition in VTAM for this machine.
  3. Enter the CP Alias, This should duplicate the CP Name.
  4. Enter the Default Node ID (Block ID, PU ID) This is the 8 digit hexadecimal number which is used to identify this local system on the SNA network. The first 3 digits is the block (IDBLK) number followed by the last 5 digits of the node (IDNUM) number. These numbers usually correspond with the IDBLK and IDNUM fields of the PU definition for this machine as defined in VTAM on the host system, however EXTRA requires that the PU ID be set to FFFFF.
  5. The Maximum locates and Locate timeout parameters can be left to the default values.
  6. The Default Protocol can be left to default to APPN then MPTN.
  7. HPR support level should be set to None.
  8. Support DLUR can be left to default to selected. This allows a Dependent LU Requester connection which allows you to route 3270 LU information through APPN traffic.
  9. The Start attach manager check box should be unselected. This does not need to be selected if only running CCIAPPC clients (e.g. Fileshare clients). The attach manager is only needed for incoming APPC requests, for example if running CCIAPPC servers.
  10. The Request discontact check box can be left unselected.

A.6 Step 3: Data Link Control Definition

Select Data Link Control from the Sections window and then click the Add button. The Add Data Link Control dialog box will appear. Select DLC type Network (802.2) and press OK. The 802.2 definition template will then be displayed.

  1. Enter the DLC Name, a name to describe the DLC definition which will be unique within this node. For example, LANDLC since this is going to be a LAN connection.
  2. Leave the Negotiable links checkbox to default to unselected.
  3. The Activate on startup checkbox, we suggest initially be left unselected so that the DLC is tested by starting manually. Once this is tested this option can then be selected.
  4. For Board number specify the adapter number which will be used for this connection. If there is only one network adapter configured in this machine then select 0. To determine the network adapters installed double-click the Network icon in the Control Panel. The adapters are listed in ascending adapter number starting at zero.
  5. Select the appropriate Adapter type for the LAN network adapter, either Tokenring or Ethernet.
  6. You may allow the Buffer size in kilobytes to default to 64.

A.7 Step 4: Port Definition

Select Port from the Sections window and then click the Add button. The Add Port definition dialog box will appear. Select DLC type Network (802.2) and press OK. The Port definition template will then be displayed.

  1. Enter the Port Name to describe the Port definition which will be unique within this node. For example, LANPORT since this is going to be a LAN connection.
  2. Select the Port Type, select SATF (shared access transport facility), the appropriate choice for a LAN connection. Note: select Switched for SDLC over a dialup line, Nonswitched for leased line SLDC or DFT.
  3. Enter the BTU size, select the maximum size of packet that the port can receive without segmentation. You must specify a value that is less than or equal to the value of the MAXDATA parameter of the PU definition in VTAM for this machine. For a 4 Mbs Token Ring specify a BTU value of 4195 or less. For a 16 Mbs Token Ring specify a value of 16393 or less. For an Ethernet LAN specify a BTU value of 1493 or less.
  4. Select the DLC section name, the definition to associate with this port, that is, the DLC definition configured above.
  5. Select Link station role, choose the default, Negotiable.
  6. Select Transmit/receive capability, choose the default, Half.
  7. Enter Target pacing count, allow this field to default to 7.
  8. Enter Maximum I-frames received, allow this field to default to 7.
  9. You may leave the TG characteristics section name blank.
  10. Enter Active Links. These parameters define the maximum number of connections or links which can be active using this port. This will define the maximum number of SNA connections to other nodes using this port, i.e. how many mainframes or peer systems you want to connect to using this port. We suggest you set both the Inbound and Outbound parameters to 2.
  11. The Implicit limited resource check box should be unselected.
  12. The Implicit CP-CP session check box should default to selected.

A.8 Step 5: Configuring the 802.2 Template (Port Definition)

Select the 802.2 template by clicking on the tab labelled 802.2.

  1. Enter the Local SAP, allow this field to default to 4.
  2. Uncheck the HPR support checkbox to disable HPR.
  3. Enter Test Timeout and Retry, these values determine the time waited (in milliseconds) for the remote node to respond to a test frame and the number of times a test frame is transmitted if no response is received. A test frame is sent when you attempt to establish the SNA connection with the host. If you find that the connection fails to activate or fails to activate on an intermittent basis increase these values (defaults are 6 and 6).
  4. Enter the XID Timeout and Retry, these values determine the time waited (in milliseconds) for the remote node to respond to an XID frame and the number of times an XID frame is transmitted if no response is received. A NULL XID frame is sent following the response to a test frame when you attempt to establish the SNA connection with the host. If you find that the connection fails to activate or fails to activate on an intermittent basis increase these values (defaults are 6 and 6).

A.9 Step 6: Link Definition

Select Link from the Sections window and then click the Add button. The Add Link definition dialog box will appear. Select DLC type Network (802.2) and press OK. The Link definition template will then be displayed.

  1. Enter the Link Name, enter a name to describe the Link definition which will be unique within this node. For example, use a name which will describe the remote node, i.e. the host system, which this Link is used to communicate with.
  2. Select Adjacent CP type, select Learn.
  3. Select Port section name, select the Port definition to associate with this Link, that is, the Port definition configured above.
  4. Enter PU Name, enter a name which will act as an internal PU name which will be uniquely associated with this Link. For example duplicate the Link Name for the PU Name.
  5. Enter Adjacent net ID, leave this field blank.
  6. Enter Adjacent CP name, leave blank.
  7. Enter the Block ID, PU ID, this is the 8 digit hexadecimal number which is used to identify this local system on the SNA network.. The first 3 digits is the block (IDBLK) number followed by the last 5 digits of the node (IDNUM) number. These numbers correspond with the IDBLK and IDNUM fields of the PU definition for this machine as defined in VTAM on the host system.
  8. Select Back level XID, choose the default, No.
  9. Enter Target pacing count, allow this field to default to 7.
  10. Enter Maximum send BTU size, select the maximum size of packet that the Link can send without segmentation. You must specify a value that is less than or equal to the value of the MAXDATA parameter of the PU definition in VTAM for this machine. For a 4 Mbs Token Ring specify a BTU value of 4195 or less. For a 16 Mbs Token Ring specify a value of 16393 or less. For an Ethernet LAN specify a BTU value of 1493 or less.
  11. Select Default TG chars check box.
  12. TG characteristics, leave blank.
  13. Activate on startup check box, we suggest that initially this be left unselected so that the Link is tested by starting manually. Once this is tested this option can then be selected.
  14. Limited resource check box, do not select.
  15. Select Host connection check box.
  16. CP-CP session check box, do not select.

A.10 Step 7: Configuring the 802.2 Template (Link Definition)

Select the 802.2 template by clicking on the tab labeled 802.2.

  1. Enter the Remote MAC Address, the 12 digit hexadecimal adapter address of the network controller attached to the remote host system. This should be obtained from the network administrator of the host system.
  2. Select the Remote SAP, allow this field to default to 4.
  3. Select the Address format, select the format which corresponds to type of adapter installed in the network controller attached to the remote host system. This is likely to be Tokenring but could be Ethernet.
  4. Enter the Test Timeout and Retry, these values determine the time waited (in seconds) for the remote node to respond to a test frame and the number of times a test frame is transmitted if no response is received. A test frame is sent when you attempt to establish the SNA connection with the host. If you find that the connection fails to activate or fails to activate on an intermittent basis increase these values (defaults are 6 and 6).
  5. Enter the XID Timeout and Retry, these values determine the time waited (in seconds) for the remote node to respond to an XID frame and the number of times an XID frame is transmitted if no response is received. A NULL XID frame is sent following the response to a test frame when you attempt to establish the SNA connection with the host. If you find that the connection fails to activate or fails to activate on an intermittent basis increase these values (defaults are 6 and 6).
  6. The configuration of the SNA LAN connection to the remote host is now complete. In the File menu select Save As and specify the name DEFAULT as the configuration file name.

A.11 Step 8: Configuring a 3270 LU for Terminal Emulation

Select 3270 from the Sections window and then click the Add button.

  1. Select the PU name, select the PU name associated with the Link to be used.
  2. Enter the LU name, this should match a dependent LU definition name for this PU as defined in VTAM. Dependent LUs are recognizable by the fact that the LOCADDR parameter of the LU definition is non-zero (LUs with a LOCADDR value of zero are Independent LUs used for APPC.
  3. Specify the NAU address, this should match the value of the LOCADDR parameter of the dependent LU as defined in VTAM.
  4. Leave the Pool Name blank.
  5. Select Priority, Allow this field to default to High.
  6. Select LU Type, allow this field to default to Unknown.

A.12 Step 9: Configuring LU's for APPC

Before attempting to communicate using CCIAPPC you must define the local and remote LUs which will be used to communicate over the SNA connection you have configured. In this section we will describe the configuration of Independent LUs to be used to communicate over the host connection configured in section 1. When communicating with Host systems running VTAM (or NCP) the Remote LU is known as the APPLID (pronounced 'apple-id').

A.13 Step 10: Configuring the Local LU

Select Local LU (LU 6.2) from the Sections window and then click the Add button.

  1. Enter the Local LU Name as defined in the list of LUs defined for this PU in VTAM on the host system.
  2. Enter the LU Alias, duplicate the LU name.
  3. Enter the NAU address, this value should correspond to the value of the LOCADDR parameter of this LU definition in VTAM on the host system. For independent LUs this value should be zero, whereas dependent LUs have a non-zero address.
  4. Select the PU Name, choose the PU Name associated with the Link to be used.
  5. Session limit For independent LUs specify the maximum number of parallel sessions which will be supported. Set the Session limit according to the number of CCIAPPC clients which are to communicate using this Local LU name. If the clients all specify the same LU Name in the machinename parameter of CCI-INITCLIENT (or the /MA parameter in FHREDIR.CFG for Fileshare clients) then the session limit should reflect this number of clients. If a different Local LU name is specified for each client, meaning that multiple Local LUs will need to be defined the session limit can remain at 1. Hence, a value of 8 is recommended for flexibility. Dependent LUs must have a maximum session limit of 1, that is, they are single session only.
  6. Repeat this section until all required Local LUs have been added.

A.14 Step 11: Configuring the Remote LU

Select Partner LU (LU 6.2) from the Sections window and then click the Add button.

  1. Enter the Network ID, the network name for SNA network which includes the host system as defined in VTAM on the host system. This should be obtained from the network administrator of the host system.
  2. Enter the LU Name, the name of the VTAM APPL ID on the host system which is specified by the CCIAPPC server in the publicname parameter (or in the /S parameter of the Fileshare Server).
  3. Enter the PLU Alias, duplicate the LU Name.
  4. Enter the Maximum logical record size, allow this field to default to 32767.
  5. PLU unqualified name, leave blank.
  6. You do not need to enter any information in the MPTN area or the Owning control point area.
  7. Leave Protocol preference to default to Use Node Default.
  8. Leave Domain Name or IP address blank.
  9. Leave Owning Control Point parameters, Network ID and CP name blank.
  10. Conversion security verification check box, leave unselected.
  11. Parallel session support check box, leave selected.
  12. Repeat this section until all required Partner LUs have been added.

A.15 Step 12: Adjacent Link Definition

Select Adjacent Link from the Sections window and then click the Add button.

  1. Enter the Network ID, enter the network name for SNA network which includes the host system as defined in VTAM on the host system. This should be obtained from the network administrator of the host system.
  2. Enter the CP name, enter the PU name of the host system as defined in VTAM on the host system. This should be obtained from the network administrator of the host system.
  3. Enter the Partner LU names to be associated with the host system (up to 8 names, separated by commas). Specify the Partner LUs, also known as APPLIDs defined in VTAM on the host system, which will be used by Fileshare servers running on the host system.
  4. Use as a wildcard check box, leave this unselected.

A.16 Step 13: Configuring Session Limits - Defining a Mode

A Mode is used to define the attributes of sessions used between a Local LU and a Remote LU.

If the default mode #INTER is not appropriate (because its settings are incompatible with the modes defined on the host system for the Remote LU, or perhaps because a larger number of sessions is required) then a new mode can be defined.

CCIAPPC uses a single APPC session for each CCI session between the client and the server (e.g. between the MFA client and Fileshare running on a mainframe). When CCIAPPC establishes a connection between the client and server the attributes of the Mode determine, amongst other things, the number of CCI sessions available between the Local LU and the Remote LU (APPLID in VTAM). Hence the Mode determines how many client sessions can be established using the same Local LU - Remote LU pairing.

The Maximum Session Limit and the Minimum Contention Winners values together determine how many sessions can be established by the Local LU (see below).

For example: if 10 client sessions are required, all using the same Local LU then the Mode session attributes might be:

Session Limits:
Maximum = 20
Minimum contention winners = 15

Alternatively the same number of client sessions could be attained by using multiple Local LUs with the client sessions divided between these LUs.


IMPORTANT NOTE : When a connection is established between a Local LU and a Remote LU the Mode characteristics are negotiated. This means that it is possible that the partner system (e.g. mainframe) will reduce the session limits to values which it can support. This may mean that fewer client sessions than expected will be supported. Hence it is important that the Mode characteristics, as defined for both the Local and Remote LUs, are compatible.


A.17 Step 14: Enabling CCIAPPC to Find the Local LU

This is a very important topic and without following the instructions below you will fail to establish a CCI session with CCIAPPC. If the CCI-INITCLIENT call returns CCI error 9 and CCI_GETERROR returns the message "Transport failure, the client could not make a connection" it is likely that these instructions have not been implemented. When CCIAPPC attempts to allocate an LU 6.2 session with the remote system it must specify the Remote LU name which it requires a session with. This is the Remote LU name specified in the CCI Servername parameter (e.g. the /S parameter in FHREDIR.CFG). However, APPC needs to know the Local LU name as well as the Remote LU name when attempting to establish a session between the LUs. To enable APPC to retrieve the Local LU name to use when attempting to allocate APPC sessions set the APPCLLU environment variable to the Local LU Name prior to starting the CCAPPC client.

For Example:

SET APPCLLU=NBTRN1L0; 

This can be done in the Cobol MFENV environment file.

A.18 Step 15: Updating the System Path

Before EXTRA can be used with CCIAPPC the system path must be updated so that the required EXTRA runtime DLLs can be found by CCIAPPC. CCIAPPC on 32 Bit Windows uses the WCPIC32.DLL from the EXTRA product to provide CPI-C APPC support.

Use one of the following methods to update the path:

This takes effect immediately, applications subsequently started will have the correct path setting.

Restart Windows 95 to adopt the new path setting.

The new path will now be set when MFENV is used to set the environment for Cobol.

A.19 Step 16: Activating the Configuration

Once the settings described above have been made the configuration must be saved before starting the EXTRA APPN Node. In the File menu, click Save and then exit the APPN Configurator. From the EXTRA! Personal Client 32 Bit program folder start the Start APPN Node program. This should start successfully without generating any error messages.

Once the Node has successfully started without generating any error messages start the Node Manager from the EXTRA! Personal Client 32 Bit program folder.

  1. Select the DLC icon in the toolbar (green adapter card) and select Start to start the Data Link Control (DLC). Once the DLC has started successfully the DLC Status should display active.
  2. Select the Link icon in the toolbar (linked circles), select the link name to start and select Start to start the link. Once the link has started successfully the Status should display Active.

Once the Link is active CCIAPPC can be used with this connection to the host system.

If an error message is generated at any stage see the section Error Reporting and Diagnostics for information on determining how to correct the error.

A.20 Error Reporting and Diagnostics

Configuration errors are detected when the APPN Node is started and error messages are displayed in the Node Events window of the APPN Node Information dialog box. These configuration errors must be corrected before attempting to use CCIAPPC with EXTRA! Personal Client.

Fileshare clients log messages returned from CCI in both the fhredir.msg and fhneterr.log files in the current directory. For Example:e.g. an entry from fhredir.cfg CCI: 970116 15183855 0009 07 CCIAPPC failed to allocate an APPC session, ensure that Local LU is defined Column 2 and 3 gives the date and time stamp of the error. Column 4 (in this case 0009) gives the CCI error code Column 6 gives the CCI error message returned by CCI-GETERROR.

The Audit Log function of the Status App displays information on significant events and error messages and should be checked if problems are experienced.

The API Trace function of the Status App can be used to provide tracing of CPI-C api calls made by CCIAPPC.

Trace entries can be selected and expanded by double-clicking. This then displays parameters and return codes, etc. Trace files can be saved by selecting the Save/Save as options from the File menu.

A.21 Known Problems

  1. Mainframe Access (MFA) hangs when communicating with the host system using Attachmate EXTRA! Personal Client

Problems have been experienced whereby MFA hangs when drag-and-drop or Record Level IO (RLIO) operations are attempted to the host system using Extra! Personal Client. In these circumstances MFA must be terminated and restarted. This issue has been raised with Attachmate and the cause of the problem has been diagnosed. Watch this space for news on the availability of a patch from Attachmate for this problem.

If CCIAPPC is used over a LAN (802.2) connection which uses routers to reach the host system intermittent connection failures may be experienced. If packet sizes of the APPC traffic are larger than the maximum packet size allowed by the router then the larger APPC packets will be discarded resulting in a connection failure. This could also cause problems in activating a connection with the host system.

The solution to this problem is to reduce the Basic Transmission Unit (BTU) size of the APPC traffic so that it is less than or equal to the maximum packet size allowed by the router. This is achieved by reducing the BTU parameter on the Link definition using the APPN Configurator.

You should check with the Network Administrator to determine the maximum packet size allowed by the router. If in doubt, we suggest that the BTU be reduced to 521 bytes which is usually well below the limit imposed by the router.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousCCI Status Messages Attachmate Personal Client v6.1 and v6.2Next