Chapter 13. Programming the Visual Basic Program

In this chapter:

Having designed the Visual Basic component, now is the time to start programming it. And having programmed it, you need to set up the required configuration so that it can communicate with the CICS application.

Writing the Graphical User Interface

In Designing the Graphical User Interface in Chapter 12, we described the functions that would appear in the Log In panel, and the two main user interface screens, the Main Menu and the Account Details form. You can see the full Visual Basic application by looking at the code on the CD that accompanies this book. In this section, we look at how some of the controls on the user interface screens are coded.

Controls used on the Main Menu include:

  • Data entry fields for the user to enter information

  • List boxes to display the results of a name search, and the request type options

  • Push buttons to perform actions

  • Keyboard short cuts to enable experienced users to perform actions quicker

  • Tab indexes to scroll from one data entry field to another

  • The Main Menu also includes two other design elements: the Print control and links to help information (Figure 13-1)

The Main Menu
Figure 13-1. The Main Menu

The controls are created in Visual Basic by dragging and dropping objects from a palette onto a design area. You can then change control properties, and write code that is activated when a control is selected. For details of how to create basic controls and change properties, you need to look at the Visual Basic documentation. But let’s now look at the code behind the list boxes.

First, let’s consider the case where a user wishes to search for a particular account number, and then do an account request based on an entry from the list displayed. Selecting an entry from the resulting list box causes the selected account number to be entered in the Account Number box for the Account Request part of the form. The following code shows the method used:

Private Sub ResultList_Click( )
       AccountTxtBox.Text = cabrws_matches(ResultList.ListIndex).Acct
End Sub

The available request types for the Account Request are also shown in a list box. When the user selects a request type, the appropriate character is placed in the single character field used within the CICS COMMAREA. The following code shows the method used:

Private Sub RequestList_Click()
    'Initial letter of highlighted item is stored in the Request List.
    ca_request = RequestList.List(RequestList.ListIndex)
End Sub

Figure 13-2 shows the Account Details form.

The Account Details form
Figure 13-2. The Account Details form

There is one additional control that doesn’t appear on the Main Menu: the combo box is used for the reason code, which enables the user to type the code or select it from a list. The selection list is specified as one of the properties of the object. However you still need to write some additional code to check that one of the correct values (in this case, N, L, S, or R) has been entered:

If ReasonCodeCombo.Text Like "[!NLSRnlsr]" Then
        Call Guide_msg_box("Please enter valid reason code. Valid values are
        N,L,S,R", "Help Message")
    ReasonCodeCombo.BackColor = vbWhite
     ReasonCodeCombo.SetFocus
     Exit Sub
End If

Implementing the Print Function

The Print function is set up as a selection on the menu bar. As mentioned in Chapter 17, the Print option uses the PrintForm method. The code looks like this:

Menu.PrintForm

Implementing the Online Help

In Designing the Online Help in Chapter 12, we described three types of help text that you might wish to include in the GUI:

Tooltip text

Tooltip text is entered as a property for an object. The text that is entered then appears when the mouse pointer passes over the object.

WhatsThisHelp facility

WhatsThis Help is also defined as a property, but the help information associated with the object is specified in a separate help file that is called when the user requests help.

Help options

Help options, which appear under Help on the menu bar, are specified using the menu editor in Visual Basic. You can create a help file for each help option, and this is invoked when the user clicks on the help option in the menu.

Implementing the Data Validation Code

The Visual Basic component of the sample application contains many additional routines that work behind the scenes in the GUI. These include:

  • Routines for checking that alphabetic data has been entered in a field.

  • Date format checks.

  • Error-handling routines, invoked when incorrect data has been entered.

You can view these routines by looking at the Visual Basic application on the CD that is supplied with this book.

Accessing Applications on the CICS Server

This section describes two methods of handling data with standard CICS object-orientated support through the ECI and secondly using VisualAge InterSpace services.

Handling Data

Let’s look at some extracts taken from the Visual Basic Project module, comsubs.bas, of our sample application. Comsubs.bas is concerned with the connection to the CICS server application by native CICS calls. The data-handling methods used with VisualAge Interspace is discussed Creating the VisualAge Interspace Service for the NACT02 CICS Server Application later in this chapter.

The definitions of the Visual Basic GUI data fields used by NACT05 are shown in Example 13-1.

Example 13-1. Definitions of the Visual Basic GUI Data Fields
'structure of Account Browser (NACT05) commarea
Public Const commBRWSlength = 30668 '0 to 30688 total value 30669
' Byte array for Acct Browse CICS COMMAREA
Public cabrws(commBRWSlength) As Byte
Public cabrws_version As String * 3
Public cabrws_request  As String * 1
Public cabrws_response As String * 4
Public cabrws_reason   As String * 4
Public cabrws_function As String * 5
Public cabrws_limit    As String * 4
Public cabrws_found    As String * 4
Public cabrws_more     As String * 4
Public cabrws_matches(80) As AccRecord

Note how nested structures contained within the COMMAREA are handled. The COMMAREA definition contains a datatype AccRecord whose definition includes a datatype of PayHistory. The datatype AccRecord is defined as shown in Example 13-2.

Example 13-2. Datatypes for AccRecord
Type AccRecord
 Acct            As String * 5     'Account number
 SName           As String * 18    'Last/surname
 FName           As String * 12    'First Name
 Mid             As String * 1     'Middle Initial
 Title           As String * 4     'Title e.g. Mr./Mrs./Dr.
 TelNo           As String * 10    'Telephone Number
 Address1        As String * 24    'Address field 1
 Address2        As String * 24    'Address field 2
 Address3        As String * 24    'Address field 3
 AuthUser1       As String * 32    'Additional Authorised Card User 1
 AuthUser2       As String * 32    'Additional Authorised Card User 2
 AuthUser3       As String * 32    'Additional Authorised Card User 3
 AuthUser4       As String * 32    'Additional Authorised Card User 4
 Cards           As String * 1     'Number of cards issued to Customer
 Imonth          As String * 2     'Month card issued
 Iday            As String * 2     'Day card issued
 Iyear           As String * 2     'Year card issued
 Reason          As String * 1     'Reason code for card issue
 CardCode        As String * 1     'Card status Code e.g. G for Gold
 Approver        As String * 3     'Code of Card issue approver
 SpecialCode1    As String * 1     'Additional Privilege Code 1
 SpecialCode2    As String * 1     'Additional Privilege Code 2
 SpecialCode3    As String * 1     'Additional Privilege Code 3
 Status          As String * 2     'Account Status
 Limit           As String * 8     'Customer Account Credit Limit
 History1        As PayHistory     'Payment History first of last three
                                   'months
 History2        As PayHistory     'Payment History second of last three
                                   'months
 History3        As PayHistory     'Payment History third of last three
                                   'months
End Type

PayHistory is itself a data structure of fields of type String. The datatype of String used in the Visual Basic application corresponds to a datatype of CHAR on the OS/390 host. PayHistory is defined in Example 13-3.

Example 13-3. Definitions of Pay History Datatype
Type PayHistory
 Balance          As String * 8     'Account Balance
 BMonth           As String * 2     'Month
 BDay             As String * 2     'Day
 BYear            As String * 2     'Year
 BAmount          As String * 8     'Amount of Balance
 PMonth           As String * 2     'Payment Month
 PDay             As String * 2     'Payment Day
 PYear            As String * 2     'Payment Year
 PAmount          As String * 8     'Payment Amount
End Type

Writing the ECI Component

This section shows extracts from the Visual Basic module comsubs.bas that are used to link to the CICS Browser application. The Visual Basic application makes use of the ECI Component Object Module (COM) library supplied with the CICS Universal Clients Version 3.1. A set of samples is also supplied in the cicsadpIBM CICS Universal ClientSamplesVB directory.

The following guidelines will help you make an ECI link call to CICS:

  1. Declare and instantiate the objects to be used. This can be done in the Form_Load subroutine or at some later stage in response to some user action. Note that a CclOECI must be created first to allow use of the ECI COM class. The definitions look like this:

    Public  ECI As New CclOECI
Private Connect As New CclOConn
Private Flow As New CclOFlow
Private buffer As New CclOBuf
Private UOW As New CclOUOW

    Tip

    Using the CclOUOW class, a number of link calls can be made to a CICS server within a single unit of work (UOW). Updates to recoverable resources in the CICS server can then be committed or backed out by the client program as necessary. An example of UOW use is where several databases using the same data are to be updated by different CICS applications. It is important that either all or none are updated with the new information to keep them in step with one another. This is integral to the function on mainframe CICS, but this is an exercise for the programmer on CICS client.

    By specifying a null value for the UOW, we are in effect saying that each link call constitutes a complete unit of work (equivalent to LINK SYNCONRETURN in the CICS server).

  2. Set the length of the buffer to the required COMMAREA size for the Browser program NACT05:

    buffer.SetLength commBRWSlength

  3. Provide details of the CICS server to be used. The CICS server name variable CICSServer has been left as null, forcing the first entry in the CICS Client initiation file ctg.ini to be used. The user ID and password values are those supplied by the user at Log in. Details are supplied using the details method for the Connect COM class. Before the Connect COM class can be used it needs to be initialized using the details method:

    Connect.Details CICSServer, Userid, Password

  4. Build the buffer. This is done automatically, because the required fields for the input COMMAREA have already been set within the Data Structure, as described in the Data field definitions earlier in this chapter.

  5. Move data into the COMMAREA byte array. The parameters used are:

    Ca()

    The COMMAREA byte array

    In_str

    The input string to be added to the byte array

    Ca_ofs

    The offset in the byte array at which the input string is to be added

    Ca_len

    The length of the data (in bytes) to be added

    Example 13-4 shows the routine that is used to move data into the COMMAREA byte array.

    Example 13-4. Code to Move Data into the Byte Array for COMMAREA
    Public Sub move_comm(ca() As Byte, in_str As String, ca_ofs As Integer, ca_len As
         Integer)
    Dim st As String
    ' Get the input string
    st = in_str
    While Len(st) < ca_len
        st = st + " "
    Wend
    ' Make sure that the result is not too long
    If Len(st) > ca_len Then
        st = Left(st, ca_len)
    End If
    ' Now, move the data into the COMMAREA array
    For i = 1 To ca_len
        ca(ca_ofs + i - 1) = Asc(Mid(st, i, 1))
    Next
End Sub

  6. Use the SetData for the CclOBuffer object to populate the buffer with the contents of the byte array ca:

    buffer.SetData ca

  7. Now we are ready to make the call to CICS. The Link method takes as parameters the Flow object, the name of the CICS server program to be invoked, the buffer object, and a UOW object. In this example, the UOW object has been defined but not set explicitly. Java initializes it to a null value; this call is not part of a recoverable unit of work:

    Connect.Link Flow, prog, buffer, UOW

  8. The updated data contained in the buffer object is stored in the variable tempca and then restored to the COMMAREA byte array ca:

    For i = 0 To commlen
        ca(i) = tempca(i)
Next i

  9. Finally, the CICS COM objects are deleted:

    Public Sub deleteECIobjects()
    ' Delete the ECI objects we created
    Set buffer = Nothing
    Set Flow = Nothing
    Set Connect = Nothing
    Set ECI = Nothing
End Sub

Handling ECI errors

The recommended way of handling errors with the CICS ECI COM classes is to use the standard Visual Basic On Error statement.

The form of the call used in the sample Visual Basic application is shown in the following code extract:

' Execute the CICS NACT05 program

    On Error GoTo ErrorHandler
    Connect.Link Flow, prog, buffer, UOW

When an error condition occurs, the program logic drops through to the label ErrorHandler at the end of the subroutine, or in this case, function. The code below shows how the error information is stored. CclExceptionCodes contains details of the possible error exception codes that can be returned from CICS. Each exception code has a number and associated message that can be displayed to the application user. Where an abend has occurred, the value of the error returned is cclTransaction (code 13) and the Abendcode can be queried and displayed.

Tip

Example 13-5 shows the use of the preceding Exit Function statement to stop the error handler code being run as part of the normal flow through the function.

Example 13-5. Code to Stop Error Handling Code Used as Part of the Normal Flow
Exit Function
ErrorHandler:
'The connect call failed
'Parse the error number this will work regardless of
'how the ECI objects were Dimmed

Dim RealError As CclECIExceptionCodes
RealError = Err.Number And 65535 - ECI.ErrorOffset
If RealError = cclTransaction Then
    'Transaction abend, so query the Abend code
    If AbendCode = "AEY7" Then
MsgBox "Invalid Userid/Password to execute the CICS Program", , "CICS ECI Error"
    Else
MsgBox "Unable to execute EC01, transaction abend:" + AbendCode, , "CICS ECI Error"
    End If
Else
  MsgBox RealError, , "CICS Error"
  MsgBox Err.Description, , "CICS ECI Error"
End If
rc = RealError
End Function

Accessing Applications on the CICS Server with the VisualAge Interspace API

There are a number of methods for using VisualAge Interspace with CICS as a starting point for new CICS applications. We have focused on using a service to communicate using the CICS ECI with the existing CRUD program NACT02.

The following steps are required:

  1. Use the VisualAge Interspace Service Interface Painter to create the service to link to the CICS server application.

  2. Test the service from the painter.

  3. Generate the Visual Basic module for the service to be used by the Visual Basic program developer.

  4. Incorporate the generated service module together with other required modules into the Visual Basic project.

  5. Make the necessary VisualAge Interspace API calls to link to and use the CICS server application.

We now look at each of these steps in more detail in the following sections.

Creating the VisualAge Interspace Service for the NACT02 CICS Server Application

VisualAge Interspace thinks of a service for communicating with an application as providing a request to which it receives a reply. The request is the COMMAREA being sent to the NACT02 program and the reply is the COMMAREA returned from the NACT02 program. Figure 13-3 shows the Defaults window.

The Distributed Environment for which the new services will be used is CICS. The Buffer Type is STRING that corresponds to the datatype of CHAR used for the COMMAREA field definitions used in our COBOL program NACT02. The field definitions and services created are stored in a plain text catalog file that we have chosen to call NACT and placed under the Interspace base directory. These are the only default settings we need to concern ourselves with for this example.

VisualAge Interspace Defaults window
Figure 13-3. VisualAge Interspace Defaults window

In order to set up the COMMAREA for the service we first need to provide Interspace with definitions for fields to be used in the COMMAREA. This can be done in one of two ways:

  • Typing the details into the field list

  • Using Interspace to extract the field definitions from the relevant COBOL copybook

For more information about the Importing Fields topic, refer to the Interspace online help.

VisualAge Interspace allows for a request header and request data. The request header can be thought of as the fields at the start of the COMMAREA, and the request data as a set of records of the same layout returned at the end of the COMMAREA. We have chosen to split the COMMAREA between the request header and request data but could equally as well have chosen to supply the entire COMMAREA as the request data. The design of VisualAge Interspace is such that it normally expects a set of control character fields at the start of a transmission from the calling application which, amongst other information, gives the number of records of the type specified as request data that are being returned.

There is also an option Suppress Control Fields; this must be set here as the NACT02 program will not supply or understand these control fields. When set, the Suppress Control Fields option does not send any control data or expect any to be returned from the called application. Interspace assumes that it is to receive one record whose structure is specified by the fields set up in the Request Data. This simplifies the communication with any CICS ECI application.

NACT02 only ever receives one record. If we were to work with a different application that provided a list of records, then there are additional steps which would need to be implemented. VisualAge Interspace uses the idea of what it calls a composite service to deal with this type of CICS application. The data area used to hold the records being returned by the CICS application is defined as a single field. This field can then be supplied as the request data to a composite service set up by the user which transforms it into a field array using the record structure detailed in the reply data of the composite service.

Taking a simple case the field RecordData returned from a CICS application contains several customer records. This data is supplied as the request data to a composite service. The reply data is defined as consisting of three fields:

  • name (a nine-character STRING)

  • valuea (a one-character STRING)

  • valueb (a one-character STRING)

Data is extracted from RecordData using the field structure specified in the reply data for the composite service. The process is then repeated on the remaining characters in the string until it is used up, as shown in the following table:

Reply Data Provided from CICS Application

Request Data Supplied to Composite Service

Reply Data from Composite Service

field1 xxxx

  

field2 xxxx

  

RecordData SMITH….12JONES…. 34

RecordData SMITH….12JONES…. 34

name(1) SMITH….

  

valuea(1) 1

  

valueb(1) 2

  

name(2) JONES….

  

valuea(2) 3

  

valueb(2) 4

Again, this idea is explained in more detail in the online help provided with VisualAge Interspace.

Once the necessary fields have been set up within the Service Interface Painter, you can then create the service itself.

Click on the Add icon to create a new service.

The Add Service panel, as shown in Figure 13-4, is then used to add the fields in the order required for the NACT02 COMMAREA.

VisualAge InterSpace: Add Service panel
Figure 13-4. VisualAge InterSpace: Add Service panel

Testing the VisualAge Interspace Service

Once the service has been created it can be tested within the painter provided that the CICS client has been set up correctly and the NACT02 program is accessible. To bring up the Test window, select the NACT02 service and click on the Test icon; the Test window is shown in Figure 13-5.

VisualAge Interspace: Test Window
Figure 13-5. VisualAge Interspace: Test Window

You can then add the values required for the various COMMAREA fields. Click Execute to send the completed COMMAREA to the NACT02 program. The Reply Header and Reply Data are returned from the CICS application assuming it is available. This means that the service can be tested before any Visual Basic code is written.

Generating the Visual Basic module for the service

Once the service has been tested and data successfully retrieved, you can generate the required Visual Basic module that will link to NACT02:

  1. Click on the Generate icon to display the Service Interface Generation window, shown in Figure 13-6.

  2. Check the Visual Basic box, if it is not already checked.

  3. Specify a suitable destination directory and select the appropriate template from the set provided by VisualAge Interspace. For this synchronous communication with CICS we specify the vbsync.tpl (see Figure 13-6).

  4. Click OK. This causes the Visual Basic module NACT02.bas to be generated in the specified directory:

The module generated contains all the necessary procedures required to communicate with the NACT02 program, and includes all the relevant data structures.

VisualAge Interspace: Service Interface Generation
Figure 13-6. VisualAge Interspace: Service Interface Generation

Incorporating the generated service module into the Visual Basic project

To incorporate the service module into Visual Basic:

  1. Add the NACT02.bas module.

  2. Add the required Interspace function modules DCIDPL.bas and DCIGEL.bas.

Coding the required VisualAge Interspace API calls

Programming steps include:

  1. Initialize Interspace to CICS at startup.

  2. Create instances of the structures for NACT02 used to send and receive data.

  3. Prepare the COMMAREA fields required to be sent.

  4. Issue the Interspace request and receive the reply.

  5. Exit Interspace when the program has ended.

These steps are described in more detail below.

Initialize Interspace to CICS at startup. The application name field has been specified as NACT rather than NACT02. We are making use of the catalog file nact.cat, which contains the details of the NACT02 service and could be used to hold additional services. It is not unusual to keep a large number of services for related applications in the same catalog. The nact.cat file needs to be made available to VisualAge Interspace by placing it in the Windows NT path or current directory. The code looks like this:

ReturnCode = dcifx_init("CICS", "NACT", Userid, Password)
If ReturnCode = -1 Then
   dcifx_show_error vbCritical, "Interspace Initialization Failed"
   Call endProgram
End If

Create instances of the structures for NACT02 used to send and receive data. In order to communicate with the NACT02 server application, we need to create instances of the request and reply structures that will be used by the Interspace service. These are then accessed from within two separate forms, so we have chosen to add the declaration to the NACT02.bas module. The code looks like this:

'Create instances of the request message NACT02_request_msg
'and reply message NACT02_reply_msg.
Global NACT02_Request As NACT02_request_msg
Global NACT02_Reply As NACT02_reply_msg

Prepare the COMMAREA fields required to be sent. Now we need to set the required COMMAREA fields. The code looks like this:

'Set value of version in request service header
NACT02_Request.header.ca_version = "V1A"
'Set value of request type in request Service Header
NACT02_Request.header.ca_request = "E"
'Ensure we can write data into the RequestData
ReDim NACT02_Request.data(1)
'Set value of account number in request data
NACT02_Request.data(1).Acct = "10000"

Notice the use of header and data prefixes together with the fields names that were used in the Service Interface Painter service.

Issue the Interspace request and receive the reply. Once the required data has been added to the request COMMAREA we can issue the call to the NACT02 program through Interspace and check the response. Interspace returns the reply from NACT02 in the NACT02_Reply object structure. The code looks like this:

'Issue the relevant call for Interspace to send the request
'to NACT02 and receive the reply
ReturnCode = receive_NACT02_sync(NACT02_Request, NACT02_Reply)
'Check request issued correctly
     If ReturnCode = -1 Then
        dcifx_show_error vbCritical, "Call to the CICS application NACT02 failed
        to complete"
        Exit Sub
     End If

Exit Interspace when ending the program. To end communication using Interspace, issue the dcifx_exit call for CICS:

'Check to see if Interspace was initialized
If CICSOpen = 1 Then
       'Issue call to exit Interspace
        ReturnCode = dcifx_exit("CICS")
       'Check request issued correctly
       If ReturnCode = -1 Then
          dcifx_show_error vbCritical, "Interspace Exit Call Failed"
       End If
  End If

Interspace insulates the Visual Basic programmer from needing to know anything about CICS in order to make use of the NACT02 program. You can use the same Visual Basic application to communicate with several CICS server applications by generating additional service modules using the Service Interface Painter, and then adding them to the project.

Communicating with CICS

In order to communicate with a CICS application on a CICS server machine, you need have an IBM CICS Universal Client on your workstation, and to establish a connection from this client to the CICS server. In the sample application, we use TCP/IP to connect from our CICS client to our CICS for OS/390 server. However, our CICS for OS/390 server makes use of an LU6.2 protocol. Therefore, there is a mismatch between our workstation using TCP/IP and the server’s SNA LU6.2 protocol. This requires a translator of some sort to be used to allow the client and server to communicate. Fortunately CICS can handle the necessary translation using the TCP62 driver.

Tip

There are two ways to connect your CICS Universal Client to CICS TS on OS/390. You can use TCP62, which we are going to describe, or SNA. Talk to your local SNA specialist if your site uses this connection method.

A Digression About TCP62

TCP62 enables a CICS Universal Client to use TCP/IP to access a CICS Transaction Server. This access is achieved using a product called AnyNet. It is a part of ACF/VTAM for OS/390. On the client workstation, the AnyNet component is provided by IBM Personal Communications for Windows NT, Windows 98, and IBM Personal Communications for OS/2. Don’t worry if you think that you don’t have this because a cut-down version is shipped with the CICS Universal Client. When you install the latter, just make sure that you select the TCP62 checkbox in the installation wizard. This is how TCP62 works:

  1. The CICS Universal Client, using the definition in your ctg.ini file, passes data to the AnyNet.

    Warning

    If you have been using earlier versions (before Version 3.1) of the CICS Universal Client, you are probably used to the name cicscli.ini. This has been changed to ctg.ini in Version 3.1.

  2. The AnyNet component on the client workstation uses the domain name suffix with the partner LU name to generate an Internet Protocol (IP) name. The IP address for this name is then determined either from the local IP hosts file or from the Domain Name Server (DNS). Using standard TCP/IP flows, the data is shipped from the TCP/IP component on the workstation to TCP/IP on OS/390.

  3. TCP/IP on OS/390 routes the data received from the workstation to the AnyNet component on OS/390.

  4. The SNA over TCP/IP feature of AnyNet translates the inbound IP routing information to SNA routing information. The data is passed to VTAM and, in turn, to CICS Transaction Server for OS/390. Figure 13-7 illustrate the interrelations between the various products.

Data flow between the CICS Universal Client and CICS TS 1.3
Figure 13-7. Data flow between the CICS Universal Client and CICS TS 1.3

For more information refer to VTAM AnyNet: Guide to SNA over TCP/IP V4R4 for MVS/ESA. This manual describes how to configure AnyNet to run on your OS/390 system

That’s the end of the digression; now back to the business of configuring the host and client.

Configuring the Application

In order to establish the necessary communication between the CICS client and CICS server you need to:

  1. Configure CICS Transaction Server for OS/390 for TCP62

  2. Configure VTAM for OS/390

  3. Handle data conversion

  4. Configure the Windows NT etcHOSTS file on the client

  5. Configure the CICS Universal Client

We will now look at these steps in more detail in the following sections.

Configuring CICS Transaction Server for OS/390 for TCP62

In order to use the TCP62 driver from the CICS client, set up the LU6.2 terminal autoinstall on the CICS Transaction Server for OS/390 first:

  1. Create a copy of the supplied autoinstall connection and session models and group, CBPS:

    CEDA COPY CONNECTION(CBPS) GROUP(DFHAI62) TO(CBPS)
CEDA COPY SESSION(CBPS) GROUP(DFHAI62) TO(CBPS)
CEDA EXPAND GROUP(CBPS)

    Figure 13-8 shows the screen.

    CEDA EXPAND GROUP(CBPS) Screen
    Figure 13-8. CEDA EXPAND GROUP(CBPS) Screen

    Check that the CONNECTION definition has ATTACHSEC set to LOCAL by typing V (for VIEW) next to the CONNECTION entry displayed and page down (PF8) to see the ATTACHSEC attributes.

  2. Check the SESSION definition. You can modify settings by typing A (for ALTER) next to the appropriate entry in the screen. In the session definition:

    • Set MAXIMUM to 8,1 (Maximum eight sessions, one contention winner only).

    • Set MODENAME to either #INTER or IBMRDB (these are present in the default mode table, ISTINCLM, which is known to all VTAMs). What you specify here must be known to VTAM and must match MODENAME in the client INI file (ctg.ini).

  3. Install this GROUP definition:

    CEDA INSTALL GROUP(CBPS)

  4. Add the new CBPS group to a list. In order to install your group at CICS startup, add the LIST to the GRPLIST=(…) in the system initialization parameters:

    CEDA ADD GROUP(CBPS) LIST(locallist)

    where locallist is a unique name for you. If you enter a new name, it is automatically created.

  5. Set the terminal autoinstall program to DFHZATDY (default is DFHZATDX, which does not support LU6.2 autoinstall):

    CEMT SET AUTOINSTALL PROGRAM(DFHZATDY)

  6. Check that the system initialization parameters are defined as follows:

    • AIEXIT=DFHZATDY

    • ISC=YES

    • GRPLST=(DFHLIST,locallst)

Configuring VTAM for OS/390

Check with your VTAM system programmer before attempting to do the following steps yourself:

  1. Ensure that the VTAM APPL definition for CICS has:

    AUTH=(ACQ,VPACE,PASS),
    VPACING=5,
    PARSESS=YES,
    SONSCIP=NO

    Warning

    You must NOT have APPC=YES on the CICS Applid definition. And if you use #INTER as your MODENAME, you do not need MODETAB=MTCICS on the CICS APPL definition. The default is ISTINCLM.

  2. Create a major node definition for AnyNet. If this is a new system, the VTAM JCL will probably be in SYS1.PROCLIB(memberName), and it uses the ATCSTR00 startup options member in SYS1.VTAMLST. Example 13-6 shows an example of the definition.

    Example 13-6. Sample of VTAM Definition
    0        1         2         3         4         5         6         7         8
12345678901234567890123456789012345678901234567890123456789012345678901234567890
*    TCP62 major node definition
TCP62>>   VBUILD TYPE=TCP,                                             X
              DNSUFX=domain-suffix-of-TCPIP-in-the-MVS-with-CICS          X
              PORT=397,                                                   X
              TCPIPJOB=TCPIP
TCP62G     GROUP ISTATUS=ACTIVE
TCP62L     LINE  ISTATUS=ACTIVE
TCP62P     PU    ISTATUS ACTIVE,NETID=VTAM-network-name-of-client-LU

    Warning

    Your system programmer may be using JCL from a different dataset and with a different member name. Find where the //VTAMLST DD card points, usually to SYS1.VTAMLST. Edit SYS1.VTAMLST and create a new member; for example, TCP62. In TCP code, the macros are column sensitive.

  3. There are two ways that you can use TCP62. The preferred method is to make a dynamic link; this is easier and, by definition, does not need you to define multiple static CDRSC definitions within VTAM. To do this you need to check to see if the parameter DYNLU=YES is set as a startup option for VTAM. DYNLU=YES dynamically allocates CDRSC definitions. For security reasons, this is often turned off at many sites. If this is the case, your VTAM programmer will have to set up a localLuName for you. This is entered in the ctg.ini file. To check the status of this parameter, locate member ATCSTR00 in SYS1.VTAMLST and check that DYNLU=YES.

  4. To check your VTAM to TCP/IP interface settings, enter on a system console:

    /D NET,ID=TCP62P

    where Where TCP62P is the PU name from the sample JCL shown in Example 13-6. If your system is active, look in your system log and it returns:

    D NET,ID=TCP62P,E
IST097I DISPLAY ACCEPTED
IST075I NAME = TCP62, TYPE = PU_T2.1 170
IST486I STATUS= ACTIV, DESIRED STATE= ACTIV

Handling Data Conversion

The CICS Transaction Server for OS/390 uses an EBCDIC code page whereas the CICS Universal Client for Windows NT uses an ASCII code page. It follows that the COMMAREA supplied within an ECI request requires data conversion. To keep things simple, it is a good idea to arrange all the fields defined within the COMMAREA into datatype CHARACTER on the OS/390 system.

Data conversion is handled by the system that owns the resource being used. It follows that for an ECI request of the type we are using, the CICS Transaction Server for OS/390 is responsible for the data conversion. The CICS-supplied macro DFHCNV is used to perform the conversion.

Tip

If it is not practical for all fields to be CHARACTER type, then the DFHCNV macro must be coded to specify which conversion is necessary for each part of the COMMAREA, and this must be kept up to date as the COMMAREA structure is changed.

Assemble and link edit the sample DFHCNV macro. An extract from the source of a DFHCNV macro is shown in Example 13-7.

Example 13-7. Sample of the DFHCNV Macro
         DFHCNV TYPE=INITIAL
* Program: NACT02
*
         DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=NACT02,USREXIT=NO,           *
                SRVERCP=037,CLINTCP=850
         DFHCNV TYPE=SELECT,OPTION=DEFAULT
         DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=32767,   *
                LAST=YES
*
* Program: NACT05
*
         DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=NACT05,USREXIT=NO,           *
                SRVERCP=037,CLINTCP=850
         DFHCNV TYPE=SELECT,OPTION=DEFAULT
         DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=32767,   *
                LAST=YES                                               *
         DFHCNV TYPE=FINAL

The following parameters are of particular interest:

DFHCNV TYPE=INITIAL

Defines the beginning of the conversion table.

DFHCNV TYPE=ENTRY

You specify an entry for each resource where data conversion is to take place. The entry in Example 13-7 is specific to the sample programs NACT02 and NACT05.

RTYPE=PC

You specify a resource type of PC (Program Call) for a CICS server program that is to be invoked by the ECI.

RNAME=SRVTIME

Specifies the resource name is the CICS server program. There are two files that you have to define in the sample application. They are NACT02 (the business logic) and NACT05 (the browse logic).

SRVERCP=037

Specifies the server code page. 037 (U.S. English, EBCDIC) is normally used in the U.S.; 285 (UK, EBCDIC) is normally used in the U.K.

CLINTCP=850

Specifies the client code page, 437 (U.S. English, ASCII) and is normally used in the U.S.; 850 (W. Europe, ASCII) is normally used in Latin-1 countries in Western Europe.

OFFSET=0

Specifies the byte offset in the COMMAREA at which the data conversion should start. OFFSET=0 specifies the beginning of the COMMAREA.

DATATYP=CHARACTER

Specifies that the data in the COMMAREA is a character field. The sample program uses only uppercase alphanumeric characters.

DATALEN=32767

Specifies the length of the data field to be converted. For variable length fields, specify the maximum possible length (32767).

DFHCNV TYPE=FINAL

Defines the end of the conversion table.

Configuring the Windows NT HOSTS File on the Client

To configure the Windows NT HOSTS file on the client, locate the HOSTS file on NT in: WINNTsystem32driversetchosts and add an entry such as:

# MVSA      (this is a comment line)
n.n.n.n.    lu.netid.domain-suffix

The items in this macro are:

n.n.n.n.

The TCP/IP address (for example 195.24.24.292)

lu

The LU name (applid) of the CICS region

netid

The VTAM network name of the CICS region. You can find the LU name and the netid by entering D NET,ID=lu,E on an OS/390 system.

Domain-suffix

The name of your local domain, for example, hursley.ibm.com

Tip

In this command, LU name and net ID are reversed relative to standard SNA conventions. For the changes to take effect, you need to reboot your Windows NT system.

Configuring the CICS Universal Client

Before you start to configure the CICS Universal Client, you should have the following information:

  • The IP address and domain name of an OS/390 system.

  • The name of the CICS server. This is a purely arbitrary name but it is as well to decide on a name at this stage and keep to it.

  • A description of the CICS server. Again, this is an arbitrary description.

  • The protocol to be used. In our case, this will be TCP62 to allow the necessary communication between the client using TCP/IP and the server using LU6.2 protocols.

Either use the CICS Universal Clients configuration tool or locate and edit the client INIT file:

Program Files IBMIBM CICS Universal Clientinctg.ini

then code the information as shown in Example 13-8.

Example 13-8. Sample CTG.INI file
    SECTION CLIENT = CICSHT61
    CCSID=850    ; Ensures that the correct codepage is used for our ACCT app.
    CPNAME=GBIBMIYA.IYAMT0E0               ; See the VTAM definitions
    CPIPADDRESSMASK=FFFFFE00
    DCECELLDIRECTORY=Y
    DOMAINNAMESUFFIX=HURSLEY.IBM.COM
    ENABLEPOPUPS=Y
    LOADMANAGER=N
    LOGFILE=CICSCLI.LOG
    MAXBUFFERSIZE=32
    MAXREQUESTS=256
    MAXSERVERS=10
    MAXWRAPSIZE=0
    REMOTENODEINACTIVITYPOLLINTERVAL=60
    SRVRETRYINTERVAL=60
    TERMINALEXIT=EXIT
    TRACEFILE=CICSCLI.BIN
    USEOEMCP=N
ENDSECTION
SECTION SERVER = cicsadp                  ; Arbitary name
    DESCRIPTION=TCP62 link to winmvs26    ; Arbitary description
    LOCALLUNAME=LU62****        ; This uses dynamic generation of an LUname
    LUIPADDRESSMASK=FFFFFE00
    SNAMAXRUSIZE=1024
    SNASESSIONLIMIT=8
    MODENAME=ibmrdb            ;Corresponds to the name in the CICS session
    SNAPACINGSIZE=8            ;Corresponds to CICS MAXIMUM number of SESSIONs
    NETNAME=GBIBMIYA.CICSHT61  ; The VTAM netid and the name of the CICS region
    PROTOCOL=TCP62
    UPPERCASESECURITY=N
    USENPI=N
ENDSECTION

SECTION DRIVER = TCP62
    DRIVERNAME=CCLTCP62
ENDSECTION


SECTION LOADMANAGER
    TYPE=1
    Timeout=60
ENDSECTION

Tip

The CPName must be the net ID of the client plus some arbitrary mask.

The CPIPAddressMask masks out all but the right-most bits which will be set dynamically. This mask should match LUIPAddressMask.

The DomainNameSuffix is determined by the network systems programmer. Note that this may not be the same as the domain name suffix of the host CICS as specified in the TCPMAJ definition if CICS TS for OS/390 is in a different domain from the client.

For LocalLUName you should use 4 asterisks (****) on the right of the mask because the sample autoinstall program uses the last four characters of the LUNAME to define the connection name, and this must be unique.

Testing the TCP62 Connection

To check to see if your CICS client TCP62 connection is working, you can start a cicsterm session as described in the following procedure. Then either use one of the CICS supplied transaction commands; for example, CEMT or CEDA, or if you are really bold try entering the NACT transaction. The screen will look similar to Figure 13-9.

CICSTERM: The NACT transaction
Figure 13-9. CICSTERM: The NACT transaction

To start a cicsterm session:

  1. If the CICS Universal Client has been running, stop the client by selecting Start → Programs → IBM CICS Universal CICS Client → Stop Client or at a command prompt by entering:

    cicscli -x

  2. Start the CICS Client by selecting Start → Programs → IBM CICS Universal CICS Client → Start Client or at a command prompt by entering:

    cicscli -s

  3. To test your connections to the server start a CICS terminal session, either by selecting Start → Programs → IBM CICS Universal CICS Client → CICS Terminal or at a command prompt by entering:

    cicsterm -s=CICSADP

    where CICSADP is the name of your definition that you created in the ctg.ini file. When it is connected to your CICS region a terminal identifier appears at the bottom left of the cicsterm window; for example, /AAA.

  4. Verify that the connection works by typing CEMT in the CICS terminal window and pressing the Enter key (on a CICS terminal, this is the Ctrl key). This starts the CICS Master Terminal program. Alternatively you could enter the transaction identifier of our application (NACT in uppercase).

Warning

Many installations put a high level of security on the CEMT transaction, so do not be surprised if you get a message about a security violation.

Running the ACCT Application

To install the application open the Visual Basic with Interspace Customer Service Application directory on the CD-ROM and double-click on the setup icon.

What’s Next….

Chapter 12, and Chapter 13, described how to get a Visual Basic application working using ECI through a CICS client connection. Part VII describes how to develop a Java application and link two major products, CICS and MQSeries together. Kan-DoIT’s managers want the ability to enter an account number and view the details of the account without, in this case, making any changes.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.128.200.71