FIX: A new feature is available in the Transaction Integrator to initiate persistent TCP/IP connections to CICS in Host Integration Server 2004 (899946)


The information in this article applies to:

  • Microsoft Host Integration Server 2004

SUMMARY

The Transaction Integrator (TI) Windows-initiated processing (WIP) feature in Microsoft Host Integration Server 2004 can initiate a persistent TCP/IP connection to the host computer. When the TI runtime accesses the Customer Information Control System (CICS), the TI runtime sends message headers with all user data after the initial TCP/IP connection has been established. Therefore, user data can be exchanged without sending message headers after the initial connection is established. The new feature is implemented by using the following COMTIContext keywords:
  • ELMIN
  • ELMOUT
  • TRMIN
  • TRMOUT
For more information about how to use this new feature, see the "More Information" section.

MORE INFORMATION

A supported feature that modifies the product's default behavior is now available from Microsoft, but it is only intended to modify the behavior that this article describes. Apply it only to systems that specifically require it. This feature may receive additional testing. Therefore, if the system is not severely affected by the lack of this feature, we recommend that you wait for the next Host Integration Server 2004 service pack that contains this feature.

To obtain this feature immediately, contact Microsoft Product Support Services. For a complete list of Microsoft Product Support Services telephone numbers and information about support costs, visit the following Microsoft Web site:

http://support.microsoft.com/contactus/?ws=support

The English version of this feature has the file attributes (or later file attributes) that are listed in the following table. The dates and times for these files are listed in Coordinated Universal Time (UTC). When you view the file information, it is converted to local time. To find the difference between UTC and local time, use the Time Zone tab in the Date and Time tool in Control Panel.
   Date         Time   Version     Size     File name
   ---------------------------------------------------------------------------------------
   20-Jun-2005  17:44  6.0.1964.0   25,600  Capture.dll      
   20-Jun-2005  17:44  6.0.1964.0   98,816  Dcgen.dll        
   20-Jun-2005  17:44  6.0.1701.0    4,096  Microsoft.hostintegration.ti.dcgen.interop.dll
   20-Jun-2005  17:43  6.0.1964.0  249,344  Mobase.dll       
   20-Jun-2005  17:44  6.0.1964.0   24,064  Playback.dll     
   20-Jun-2005  17:43  6.0.1964.0   94,720  Tagen.dll        
   20-Jun-2005  17:43  6.0.1964.0  538,624  Tracing.dll      
   20-Jun-2005  17:44  6.0.1964.0   98,304  Trantcp.dll      
   20-Jun-2005  17:44  6.0.1964.0   34,304  Turnaround.dll
Note Because of file dependencies, the most recent fix that contains these files may also contain additional files.
When you access programs in CICS by using TCP/IP, the IBM-supplied listener program (EZACIC02) must be running in CICS. Additionally, a custom child server program must be compiled and linked within CICS. The TI runtime initiates a TCP/IP conversation with the IBM listener, and the TI runtime sends the transaction ID of the child server program. The IBM listener executes that transaction, and the child server program takes control of the TCP/IP conversation.

Sample child server COBOL programs are included with the Host Integration Server 2004 software development kit (SDK). These programs are written to handle non-persistent connections and persistent connections. In these connections, a message header is delivered. This header includes information such as the number of bytes of data that will be sent as user data.

The following sample child server COBOL programs are available:
  • Scmtics.cbl
  • Tcpcdrbk.cbl
  • Tcpcgtac.cbl
When you use the default settings to install the Host Integration Server 2004 SDK, these files are located in the TCP CICS Concurrent folder and the TCP CICS MSLink folder. These folders are in the Program Files\Microsoft Host Integration Server\SDK\Samples\AppInt\WindowsInitiated folder.

After you apply this hotfix, you can create custom child server programs that do not expect a message header. To do this, write a client program so that no message header will be sent.

Use Visual C#

The following example demonstrates how to write the client program in Microsoft Visual C# by using the CedarBank sample when the Enhanced listener is used on the mainframe. To do this, follow these steps:
  1. Install the CICS_LinkELM_CedarBank_NET.DLL sample CedarBank assembly by using TI Manager. For more information, see the "CICS WIP .NET Readme.txt" file. The file is included with the Host Integration Server 2004 SDK.
  2. Create a Visual C# project, and then add the following references:
    • System.Runtime.Remoting
    • Microsoft.HostIntegration.TI.ClientContext
    • TCP_LinkELM_NET.CedarBank_Proxy
    To add the TCP_LinkELM_NET.CedarBank_Proxy reference, follow these steps in Microsoft Visual Studio:
    1. In the Add Reference dialog box, click Browse.
    2. Browse the virtual directory that you used when you installed the CedarBank assembly in step 1.
    3. Click TCP_LinkELM_NET.CedarBank_Proxy.dll, and then click Open.
  3. Make three calls to the CedarBank TI WIP method by using a persistent TCP/IP connection. Do not include message headers on the second and third method calls. To do this, use the following code example.
    //Reference System.Runtime.Remoting
  //          Microsoft.HostIntegration.TI.ClientContext
  //          TCP_LinkELM_NET.CedarBank_Proxy
  try
  {
    // Create a context array and a TI Client Context object.
    object[] ctxArray = null;
    Microsoft.HostIntegration.TI.ClientContext objTIContext = new Microsoft.HostIntegration.TI.ClientContext();

    // Create the TI WIP object and the variables that are used by the TI method.
    TCP_LinkELM_NET.CedarBank wipTI = new TCP_LinkELM_NET.CedarBank();
    string sNameIn = "Jane", sAcct = "1234";
    decimal dBalance = 0.0M;

    // Write to the context array so that the TI runtime will start a persistent connection.
    objTIContext.WriteContext("CONNTYPE", "OPEN", ref ctxArray);

    // Make the first TI method call.
    wipTI.cedrbank(ref sNameIn, ref sAcct, ref dBalance, ref ctxArray);

    textBox1.Text = dBalance.ToString();

    // Set up the context array so that no message header is sent on the next call.
    objTIContext.WriteContext("ELMIN", 0, ref ctxArray);
    objTIContext.WriteContext("ELMOUT", 0, ref ctxArray);

    // Make the second call to the mainframe by using the same connection.
    wipTI.cedrbank(ref sNameIn, ref sAcct, ref dBalance, ref ctxArray);
    textBox2.Text = dBalance.ToString();

    // Set up the context array so that the next method call closes the connection.
    objTIContext.WriteContext("CONNTYPE", "CLOSE", ref ctxArray);

    // Make the third call to the mainframe. This call closes the connection.
    wipTI.cedrbank(ref sNameIn, ref sAcct, ref dBalance, ref ctxArray);

    // Clean up.
    wipTI = null;
    objTIContext = null;
    ctxArray = null;
  }
  catch(Exception ex)
  {
    MessageBox.Show(ex.Message);
  }

Use Visual Basic .NET

The following example demonstrates how to write the client program in Microsoft Visual Basic .NET by using the CedarBank sample when the Standard listener is used on the mainframe. To do this, follow these steps:
  1. Install the CICS_LinkELM_CedarBank_NET.DLL sample CedarBank assembly by using TI Manager. For more information, see the "CICS WIP .NET Readme.txt" file. This file is included with the Host Integration Server 2004 SDK.
  2. Create a Visual Basic .NET project, and then add the following references:
    • System.Runtime.Remoting
    • Microsoft.HostIntegration.TI.ClientContext
    • TCP_LinkELM_NET.CedarBank_Proxy
    To add the TCP_LinkELM_NET.CedarBank_Proxy reference, follow these steps in Visual Studio:
    1. In the Add Reference dialog box, click Browse.
    2. Browse the virtual directory that you used when you installed the CedarBank assembly in step 1.
    3. Click TCP_LinkELM_NET.CedarBank_Proxy.dll, and then click Open.
  3. Make three calls to the CedarBank TI WIP method by using a persistent TCP/IP connection. Do not include message headers on the second and third calls. To do this, use the following code example.
    'Reference System.Runtime.Remoting
  '          Microsoft.HostIntegration.TI.ClientContext
  '          TCP_LinkTRM_NET.CedarBank_Proxy
  Try
    'Create a context array and a TI Client Context object.
    Dim ctxArray() As Object
    Dim objTIContext As New Microsoft.HostIntegration.TI.ClientContext

    'Create the TI WIP Object and the variables that are used by the TI method.
    Dim wipTI As New TCP_LinkTRM_NET.CedarBank
    Dim sNameIn, sAcct As String
    Dim dBalance As Decimal
    sNameIn = "Jane"
    sAcct = "1234"
    dBalance = 0

    'Write to the context array so that the TI runtime will start a persistent connection.
    objTIContext.WriteContext("CONNTYPE", "OPEN", ctxArray)

    'Make the first TI Method call.
    wipTI.cedrbank(sNameIn, sAcct, dBalance, ctxArray)
    TextBox1.Text = dBalance.ToString()

    'Set up the context array so that no message header will be sent on the next call.
    objTIContext.WriteContext("TRMIN", 0, ctxArray)
    objTIContext.WriteContext("TRMOUT", 0, ctxArray)

    'Make the second call to the mainframe by using the same connection.
    wipTI.cedrbank(sNameIn, sAcct, dBalance, ctxArray)
    TextBox2.Text = dBalance.ToString()

    'Set up the context array so that the next method call closes the connection.
    objTIContext.WriteContext("CONNTYPE", "CLOSE", ctxArray)

    'Make the third call to the mainframe. This call closes the connection.
    wipTI.cedrbank(sNameIn, sAcct, dBalance, ctxArray)

    'Clean up.
    wipTI = Nothing
    objTIContext = Nothing
    ctxArray = Nothing

  Catch ex As Exception
    MessageBox.Show(ex.Message)
  End Try

REFERENCES

231862 Configuring COMTI to use TCP/IP link to CICS using the Cedar Bank demo

810956 FIX: A new feature in the COM Transaction Integrator gives the client program full control over a TRM request and lets the client program process the TRM reply

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, regarding the performance or reliability of these products.
Modification Type:MinorLast Reviewed:7/25/2006
Keywords:kbHotfixServer kbQFE kbHIS2004 kbinfo kbpubtypekc KB899946 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.