Attachmate Personal Client v6.1 and v6.2

IBM Personal Communications v4.2 for Windows NT & Window

Appendix C: IBM Communications Server v5.01 for Windows NT

Screen snapshots are copyright IBM Corporation

This document provides sample views of an 802.2 DLC connection for IBM Communications Server Version for NT. We have validated the CCIAPPC component against IBM Communications Server version 5.01. This document is arranged in a logical sequence for a new installation of the Communications Server product.

C.1 Installing IBM Communications Server

This documentation assumes that you have already installed IBM Communications Server. In addition you should have opted to install the IBM LLC2 protocol during the installation of IBM Communications Server.

C.2 Installing IBM LLC2 Protocol for Windows NT

IBM Communications Server requires the IBM LLC2 protocol to provide support for a connection over 802.2. Towards the end of the installation of IBM Communications Server you will be prompted to choose whether to automatically install the IBM LLC2 protocol for use with IBM Communications Server over a LAN. Unless you have installed LLC2 previously you must opt to install LLC2 if you intend to configure connections over 802.2.

C.3 Configuring IBM Communications Server

After successfully installing the Communications Server 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.

From the IBM Communications Server program folder, start the SNA Node Configuration program.

C.4 Configuring the Node

1. In the File menu select New to create a new Node configuration.
2. In the Scenarios menu select SNA API Clients running APPC applications.

The Configuration Steps window describes the configuration steps you will complete. Note that for CCIAPPC configuration step 7. Configure Modes is optional and that step 8. Transaction program configuration is not required.

C.5 Step 1: Node Setup

From the Configuration options listbox select Configure Node and then select New.

C.5.1 Basic Settings

1. In the Fully Qualified CP name enter the Network Name for this SNA network in the first box. This should be obtained from the network administrator of the host system. In the second box following the period 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.
2. Enter the 8 digit hexadecimal Local Node ID which is used to identify this local system on the SNA network. The first 3 digits is the Block ID (IDBLK) number followed by the last 5 digits of the Physical Unit ID (IDNUM) (also known as the Node number). These numbers must correspond with the IDBLK and IDNUM fields of the PU definition for this machine as defined in VTAM on the host system.
3. Set the Node Type to End Node.

C.5.2 Advanced Settings

These can be left to their default settings

C.5.3 DLU Requester Settings

These can be left to their default settings

Select OK to complete the Node configuration.

C.6 Step 2: Device Configuration

From the Configuration options listbox select Configure Devices. Then from the DLCs list box select LAN and then select New.

C.6.1 Basic Settings

1. From the Adapter number pulldown select the LAN adapter which will be used for the SNA connection to the host system.
2. Leave the Local SAP setting to default to 04.

C.6.2 Advanced Settings

These can be left to their default settings

C.6.3 Performance Settings

These can be left to their default settings

Select OK to complete the Device configuration.

C.7 Step 3: Connection Configuration

From the Configuration options listbox select Configure connections and then select New.

C.7.1 Basic Settings

1. Enter a name for the connection in the Link station name. This must be up to 8 characters long and will describe the connection, e.g. the destination of the connection.
2. From the Device name pulldown select the LAN Device name configured previously in step 2.
3. Enter the 12 digit hexadecimal Destination address of the network controller attached to the remote host system. This should be obtained from the network administrator of the host system.
4. Unless directed otherwise, leave the Remote SAP to default to 04.

C.7.2 Advanced Settings

1. Select Activate link at start to automatically activate the connection when the Node is started.
2. Select APPN support.
3. Leave HPR Support, Auto-activate support, Link to preferred NN server and Solicit SSCP sessions unselected.
4. Enter the 8 digit hexadecimal Local Node ID which is used to identify this local system on the SNA network. This should be the same as the Local Node ID specified when configuring the Node in step 1 previously.

C.7.3 Security Settings

1. Enter the fully qualified Control Point name of the Host system in the Adjacent CP name. Enter the Network Name for this SNA network in the first box. This should be obtained from the network administrator of the host system. In the second box following the period enter the Control Point (CP) name assigned to the remote Host machine. This should be obtained from the network administrator of the host system.
2. From the Adjacent CP type pulldown select APPN Node.
3. Leave the TG number to default to 0.

Select OK to complete the Connection configuration.

C.8 Step 4: Enable API Client Support (Configure the Gateway)

From the Configuration options list box select Configure the Gateway and then select View/Change/Add.

C.8.1 SNA Clients Settings

1. Ensure that the Enable SNA API Client Services checkbox is selected.
2. The Default pool for SNA API Client Services can be left to default to None.

Select OK to complete the Gateway configuration.

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. When communicating with Host systems running VTAM (or NCP) the Remote LU is known as the APPLID (pronounced 'apple-eye-dee').

C.9 Step 5: Local LU Configuration

From the Configuration options list box select Configure Local LU 6.2 and then select New.

1. For the Local LU name specify the LU name as defined in the list of LUs defined for this PU in VTAM on the host system.
2. Select SNA API client use.
3. Leave Dependent LU unselected.
4. For the Local LU alias enter the same Local LU name.
5. Leave the LU session limit to default to 0.

Select OK to complete the Local LU configuration.

C.10 Step 6: Partner LU 6.2 Configuration

From the Configuration options list box select Configure Partner LU 6.2 and then select New.

Unlike Local LUs, Remote LUs are assigned to a connection which will be used to communicate with it.

C.10.1 Basic Settings

1. Enter the fully qualified Partner LU Name.

This LU Name should match the definition of the LU as it exists on the remote system, in this case in the form of a VTAM APPL definition on the host system.

Enter the Network Name for this SNA network in the first box. This should be obtained from the network administrator of the host system. In the second box following the period enter the name of the APPL on the remote Host machine. This should be obtained from the network administrator of the host system.

• Leave Wildcard unselected.
• For the Partner LU alias enter the Partner LU name (i.e. APPL name).
• Enter the Fully qualified CP name of the Host system on which the partner LU resides.

This is the same as the fully qualified CP name entered in the Security settings of the Connection configured previously in step 3.

Setting this correctly will enable the Server to determine which connection to use to locate a partner LU when establishing a session with a Local LU.

C.10.2 Advanced Settings

1. Leave the Maximum LL record sixe to default to 32767.
2. Selecting Conversation security support will have no effect since this is not supported by CCIAPPC.
3. Ensure that the Parallel session support is selected.

Select OK to complete the Partner LU configuration.

C.11 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 PLU mode session limit and the Minimum contention winner sessions 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:

PLU mode session limit = 20
Minimum contention winner sessions = 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.

C.11.1 Step 7: Configuring Modes (Optional)

From the Configuration options list box select Configure Modes and then select New.

C.11.2 Basic Settings

1. Enter Mode Name, this should match the Mode Name as defined on the Host system in VTAM. This can be the default log mode specified by the DLOGMOD parameter of the VTAM Applid (APPL) definition.
2. Enter the PLU mode session limit. This is the maximum number of sessions that can be established between the two LUs.
3. Enter the number of Minimum contention winner sessions. This is the number of sessions that the Local LU can establish without needing the permission of the Remote LU.

This value cannot be greater than the PLU mode session limit.

C.11.3 Advanced Settings

1. Leave Maximum negotiable session limit to default to 128.
2. Leave Receive pacing window size to default to 1.
3. Enter the number of Automatic activate sessions. This is the number of contention winner sessions to activate when the connection using this mode is started.
4. From the Class of service name pulldown select #INTER. This is the default APPC class of service.
5. Do not select Use cryptography or Use Compression support.
6. Leave Use default RIU size selected.

If you are in doubt over these values check with the network administrator of the host system.

Select OK to complete the Mode configuration.

C.12 Configuring the IBM Communications Server SNA Client

The IBM Communications Server SNA Client (also known as the SNA API Client) runs on a client machine and communicates with the IBM Communications Server over the LAN using either TCP/IP or Novell SPX.

Having installed the IBM Communications Server SNA Client the following configuration is required.

C.12.1 Creating User IDs

Clients are authorized to connect with the Communications Server by specifying a Windows NT Domain userid which is in the IBMCSAPI user group. You may want to define a unique userid for each client user or a single userid used by all users.

1. On the NT Server, in the Administrative Tools program folder select User Manager.
2. In the User menu select New User... and fill in the Username, Description, Password, etc. and select Add. Repeat this until all the required userids have been added.
3. The group IBMCSAPI should have been created during the installation of IBM Communications Server. If is was not, select New Global Group... from the User menu. Enter Group Name IBMCSAPI and a description and select OK.
4. In the Groups window double-click on IBMCSAPI and add the required userids from the Not Members window into the Members window. Select OK when all the required userids have been added to the group.

C.12.2 Creating the SNA Client Configuration File

Start the Configuration program from the IBM Communications Server SNA Client program folder.

1. In the Configuration Options window select Configure Global Data and then select New...
2. Enter a a userid which is a member of the IBMCSAPI group.
3. Enter and confirm the userid password.
4. Select OK to complete the Global Data configuration.

1. In the Configuration options window select Configure APPC Server List and then select New...
2. In the first Servers edit box enter the name of the IBM Communications Server machine.

If the client will use TCP/IP to communicate with the Server the machine name should be the IP address of the Server machine or the TCP/IP hostname of the Server machine.

• Select the Transport Type for this Server. This is either TCP (TCP/IP) or SPX (Novell Sequenced Packet Exchange).
• Select OK to complete the APPC Server List configuration.

In the File menu select Save As... and save the configuration file as CSNTAPI.INI. Exit the SNA Client Configuration program.

C.13 Enabling CCIAPPC to Find the Local LU

It is very important that the CCIAPPC module be able to determine the Local LU to use for communication with the Host application. You may have configured everything else correctly and all of your other APPC applications may work, but if you miss this final step you will fail to establish a CCI session with the host application. If the CCI-INITCLIENT call returns CCI error 9 and CCI_GETERROR returns the message "CCIAPPC failed to allocate an APPC session, ensure that Local LU is defined" it is likely that you have failed to complete this final step. 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 CCIAPPC client. This must be done wherever the CCIAPPC client (e.g. MFA Drag and Drop) is run. If the CCIAPPC client communicates with the Server using the IBM Communications Server SNA Client then the APPCLLU environment variable must be set on each client machine. If the CCIAPPC client runs on the Server itself then the APPCLLU environment variable must be set on the Server machine.

For Example:

SET APPCLLU=CCILLU01 

C.13.1 To Set the APPCLLU in the Windows NT Environment

1. In the Start programs menu, select Settings and then Control Panel.
2. Start the System program.
3. Select the Environment settings.
4. To set the Local LU for all users select any variable setting in the System Variables list box. Now overtype the Variable name with APPCLLU and overtype the Value with the Local LU name. Alternatively, to just set the Local LU for the current user enter APPCLLU in the Variable edit box and the Local LU name in the Value edit box.
5. Select Set to define the variable.
6. Select OK to complete the setting.

This setting will be enabled the next time an application is started.

C.13.2 To Set the APPCLLU in the Windows 95 Environment

This must be done in the Windows 95 AUTOEXEC.BAT file found in the root directory of the Windows 95 System drive, e.g. C:\.

1. Edit the AUTOEXEC.BAT and add the following to the end of the file:

SET APPCLLU=<Local LU name>
E.g. SET APPCLLU=CCILLU01 

• Shutdown and restart Windows 95 to enable the new environment setting.

C.14 Verifying the Configuration

To save and verify the configuration:

1. In the File menu select Save to save the configuration. If prompted, opt to make configuration the default configuration.
2. In the IBM Communications Server program folder start the Configuration Verification program.
3. In the File menu select Open and select the configuration file. The file will be loaded and the configuration displayed.
4. In the File menu select Verify. If the configuration is correct the Verify will complete with no errors. If there are errors correct these using the SNA Node Configuration program, save the configuration and run Verify again.

C.15 Activating the Configuration

Once the configuration has been verified as correct the Node can be started.

1. In the IBM Communications Server program folder start the SNA Node Operations program.
2. In the Operations menu select Start Node... or select the green Start Node icon in the task bar.
3. Select the configuration to open and select Open.

Once the Node is active the underlying connections will activate if Activate link at start was defined for the connections.

C.16 Testing the Configuration

Once you have an active connection use the CNOS Initialize option in the Operations menu of the SNA Node Operations program to test the configuration. This will test the configuration by attempting to bind an LU 6.2 session between the Local LU and the Remote LU over the configured LAN connection.

1. In the View menu of the SNA Node Operations program select LU 6.2 Sessions.
2. In the Operations menu of the SNA Node Operations program select CNOS Initialize...
3. Select the Local LU to be used from the Local LU 6.2 pulldown.
4. Enter the fully qualified Partner LU name (as defined in step 6 previously). This is of the format <Network Name>.<Partner LU Name>.
5. Select the Mode to use. This may be a custom Mode you have defined or can be left to default to #INTER.
6. Specify the characteristics of the Mode.

In Sessions specify the maximum number of sessions allowed by the Mode, this is PLU mode session limit defined for the Mode.

In Winners specify the number of Minimum Contention winners as defined for the mode.

Specify 0 in Losers for the number of Contention Losers.

Specify 1 in Activate to activate a single session as a test.

• Select OK to initiate the bind test.

If the test is successful the session bound between the Local LU and Partner LU will appear in the LU 6.2 Sessions window of the SNA Node Operations program (in the View menu select Refresh to refresh the window). Sessions bound in this way can safely be terminated by selecting the Session Id, clicking the right mouse button and selecting Stop Abnormally.

If the test fails an error will be reported in a dialog box. Use the IBM Communications Server Log File to help you diagnose the cause of failure (see the section Error Reporting and Diagnostics below).

Now you have tested the active connection it is ready for use with CCIAPPC.

C.17 Error Reporting and Diagnostics

• Fileshare Error Reporting

  Fileshare clients log messages returned from CCI in both the fhredir.msg and fhneterr.log files in the current directory. For example 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.

• Windows NT Event Log

  Events can be viewed using the Microsoft NT Event Viewer (in the Administrative Tools(Common) program folder). In the Event Viewer select Application from the Log menu. This will then display the Application Log. Events generated by the IBM Communications Server itself are prefixed with IBMCommServer. Events generated by interaction with clients use the prefix IBM SNA Client Services. Double-clicking on an event will show details of the event.

• IBM Communications Server Log File (\IBMCS\PCWMSG.MLG)

  The Log file can be viewed by selecting Log Viewer from the Launch menu of the Node Operations program or by selecting Log Viewer from the IBM Communications Server program folder.

  Details of the selected message are shown at the bottom of the Log Viewer window. In addition, double-clicking on the message number will display an explanation of the message.

  Further useful diagnostic information can be obtained by interpreting the Sense Code returned with many errors using the Display SNA Sense Data utility in the IBM Communications Server program folder.

• IBM Communications Server Trace Facility

  This can be used to provide tracing of CPI-C and APPC interface calls made by CCIAPPC.

  Start the Trace Facility program from the IBM Communications Server program folder or from the Launch menu of the SNA Node Operations program.

  1. Select Function Name APPN and APPC.
  2. Select Component Name CPI-C API and then select the desired Trace Options (Verb trace, Verb trace plus up to 128 bytes of data, or Verb trace plus full data).
  3. Select Component Name APPC API and then select the desired Trace Options (Verb trace, Verb trace plus up to 128 bytes of data, or Verb trace plus full data). CPI-C is built upon APPC and so it is sometimes useful to glean more information by tracing APPC as well as CPI-C.
  4. Adjust the Maximum Trace Data Length if required (default 16K).
  5. Select Start to start tracing.
  6. Having performed the required tracing select Stop to stop tracing.
  7. Select Save and opt to either overwrite or append to the unformatted trace file.
  8. Select Format and specify a name for the formatted trace file. The unformatted trace file will then be formatted and saved in this file.
  9. This file can be viewed using an editor or the Windows Notepad program.

C.18 Known Problems

None.

Attachmate Personal Client v6.1 and v6.2

IBM Personal Communications v4.2 for Windows NT & Window