Communications Programming with CCI

CCILU2 Communications Module States

Chapter 3: Common Communications Interface

This chapter documents the CCI functions, the CCI error codes and each of the available communications modules.

Note: The CCI modules are not supported in virtual environments such as Windows running under OS/2.

3.1 CCI Functions

This section describes the available CCI functions. Functions are listed in alphabetical order.

CCI-Closeclient

Requests the disconnection of the client workstation from the server workstation.

Syntax:

call CCI-Closeclient using sessid

Parameters:

Comments:

Uses the session handle sessid (returned by a previous CCI-Initclient call). A CCI-Hangup call needs to be made at the server workstation to allow the disconnect to take place. These requests are performed synchronously. This call cancels any outstanding asynchronous requests which have been made for this connection.

CCI-Closeserver

Requests the termination of a server.

Syntax:

call CCI-Closeserver using srvrhandle

Parameters:

Comments:

Uses the server handle srvrhandle returned by a previous CCI-Initserver call. No matching call needs to be made at the client workstation(s). The request is performed synchronously. This call logically terminates any sessions currently connected to this server, and can cause errors at the client workstations if they are not already in the process of closing their own session connections to the closing server.

CCI-Connect

Establishes a connection between a server workstation and a client.

Syntax:

call CCI-Connect using srvrhandle
                       sessid
                       async
                       cciend

Parameters:

Comments:

The server is identified by srvrhandle returned by a previous CCI-Initserver call. A CCI-Initclient call needs to be made at the client workstation to allow the connection to take place. If successful, a session identifier is returned in sessid. The request can be performed either synchronously or asynchronously.

CCI-Geterror

Returns an error message for the last reported error.

Syntax:

call CCI-Geterror using buffer
                        maxlen
                        actuallen

Parameters:

Comments:

The error message allows CCI module-specific errors to be returned to the caller without the caller needing to know anything about the specific communications protocol being used. The request is performed synchronously.

CCI-Hangup

Requests the disconnection of the server workstation from the client workstation.

Syntax:

call CCI-Hangup using sessid

Parameters:

Comments:

Uses the session handle sessid returned by a previous CCI-Connect or CCI-Receiveall call. A CCI-Closeclient call needs to be made at the client workstation to allow the disconnect to take place. The request is performed synchronously. This routine cancels any outstanding asynchronous requests which have been made for this connection.

CCI-Initclient

Establishes a connection between a client workstation and a server.

Syntax:

call CCI-Initclient using publicname
                          machinename
                          sessid
                          async
                          cciend

Parameters:

Comments:

The server is identified by publicname and machinename (see the section Communications Protocols later in this chapter for details of what needs to be specified in publicname and machinename). A CCI-Connect or CCI-Receiveall call needs to be made at the server workstation to allow the connect to take place. If successful, a connection identifier is returned in sessid. The request can be performed either synchronously or asynchronously.

CCI-Initserver

Initializes a workstation as a server.

Syntax:

call CCI-Initserver using publicname
                          srvrhandle
                          cciend

Parameters:

Comments:

Uses the name specified in publicname (see the section Communications Protocols later in this chapter for details of what needs to be specified). Following a successful initialization, a server handle is returned in srvrhandle. The request is performed synchronously.

Although normally a non-zero value in the return code means failure, for this routine a value of 4 (name clash local) should be treated as a warning as it means that communications have been set up using a server name that has already been defined. You can find more detailed information regarding error 4 in the section CCI Error Codes later in this chapter.

CCI-Query

Used to determine whether an asynchronous request has completed.

Syntax:

call CCI-Query using async

Parameters:

Comments:

Asynchronous requests may have been established using the CCI-Connect, CCI-Initclient, CCI-Receive, CCI-Receiveall, CCI-Resumeserver, CCI-Resumeclient and CCI-Send calls. If the request has not completed, this routine will pass back a return code of -1. If the request has completed, this routine will pass back the request's completion code as the return code, and cause all return parameters from the original CCI call to be updated.

Once a request has completed, this routine should not be invoked again using the same asynchronous request handle value. This routine should also not be called with a handle from a session which has been terminated by a CCI-Closeclient, CCI-Closeserver, or CCI-Hangup call, or if the original CCI function call terminated with a non-zero RETURN-CODE.

16-bit:
On 16-bit systems, if you are using asynchronous CCI routines in intermediate code (.int) or generated code (.gnt), you should fix your program's Data Division in memory using subfunction 60 of COBOL system library routine x"91". Otherwise your Data Division may be relocated while CCI is in the middle of an asynchronous operation that returns data to your program.

CCI-Receive

Receives a message from a workstation.

Syntax:

call CCI-Receive using sessid
                       buffer
                       maxlen
                       actuallen
                       async
                       cciend

Parameters:

Comments:

The workstation is identified by sessid. A CCI-Send or CCI-Transact call needs to have been made at the other workstation to allow the receive to take place. The size of the message received is returned in actuallen, but will never be greater than the maximum buffer size specified by maxlen. The request can be performed synchronously or asynchronously.

CCI-Receiveall

Reads a message from any client targeted at the server.

Syntax:

call CCI-Receiveall using srvrhandle
                          sessid
                          buffer
                          maxlen
                          actuallen
                          async
                          cciend

Parameters:

Comments:

The client is identified by srvrhandle. srvrhandle has been established by a previous CCI-Initserver call. A CCI-Send or CCI-Transact call needs to have been made at the client workstation to allow the receive to take place. The session identifier of the connection to the client workstation is returned in sessid. The size of the message received is returned in actuallen, but will never be greater than the maximum buffer size specified by maxlen. The request can be performed synchronously or asynchronously.

This routine also connects the server workstation to a client workstation if a CCI-Initclient or CCI-Resumeclient call has been made at the client end. However, this routine will not complete until it has received a message from a client (not necessarily from a client workstation which has just connected).

When this routine returns, the session specified in sessid is in the same state as a session on which CCI-Connect and CCI-Resumeserver have been executed. CCI-Resumeserver should not therefore be called before the next CCI-Receive, CCI-Receiveall, CCI-Send or CCI-Transact.

CCI-Resumeclient

Prepares a connection between a client workstation and server for use.

Syntax:

call CCI-Resumeclient using sessid
                            async
                            cciend

Parameters:

Comments:

This call should be made following a CCI-Initclient or CCI-Suspendclient call. A CCI-Resumeserver or CCI-Receiveall call needs to be made at the server workstation to allow the resume to take place. The request can be performed synchronously or asynchronously.

CCI-Resumeserver

Prepares a connection between a server workstation and client for use.

Syntax:

call CCI-Resumeserver using sessid
                            async
                            cciend

Parameters:

Comments:

This call should be made following a CCI-Connect or CCI-Suspendserver call. A CCI-Resumeserver call is not required if a CCI-Receiveall call is being made. A CCI-Resumeclient call needs to be made at the client workstation to allow the resume to take place. The request can be performed synchronously or asynchronously.

CCI-Send

Sends a message to a workstation.

Syntax:

call CCI-Send using sessid
                    buffer
                    sendlen
                    async
                    cciend

Parameters:

Comments:

The workstation is identified by sessid. A CCI-Receive, CCI-Receiveall, or CCI-Transact call needs to have been made at the other workstation to allow the send to take place. The CCI modules will guarantee that the message has been received by the connected workstation, and the request will not complete until it has done so. The request can be performed synchronously or asynchronously.

CCI-Suspendclient

Suspends a connection between a client workstation and a server.

Syntax:

call CCI-Suspendclient using sessid

Parameters:

Comments:

This routine should be called after each use of the session (for example, a message sent and received), as some CCI implementations cannot service another client at the server workstation until this has been done.

A CCI-Suspendserver call needs to be made at the server workstation to allow the suspend to take place. The request is performed synchronously.

CCI-Suspendserver

Suspends a connection between a server workstation and a client.

Syntax:

call CCI-Suspendserver using sessid

Parameters:

Comments:

This call should be made after each use of the session (for example, a message sent and received), as some CCI implementations cannot service another client at the server workstation until this has been done.

A CCI-Suspendclient call needs to be made at the client workstation to allow the suspend to take place. The request is performed synchronously.

CCI-Timeout (CCI V3 and later only)

Overrides the CCI system timeout default.

Syntax:

call CCI-Timeout using time-period 
                       cciend

Parameters:

Comments:

This function can be used to override the CCI system timeout default (120 secs) for all future CCI calls on the currently active CCI module. The timeout is specified in 1/10th (tenths) of a second, so to set a timeout of 60 seconds, specify 600 in time-period. Previously issued calls retain the timeout period that was in use when they were originally invoked.

Note: CCI-Initclient and CCI-Initserver may take longer than a specified user value before they report a timeout, this behavior represents the minimum time that these functions require before they can report success or failure. The actual minimum return time of these functions is protocol dependent. For example, CCINETB requires approximately 15 seconds to process a CCI-Initserver call. CCITCP, however, should complete in approximately four seconds.

CCI-Trace

Logs the communication flow.

Syntax:

call CCI-Trace using toggle 
                     control-buffer
                     cciend

Parameters:

Comments:

See the section Tracing and Debugging in the chapter Communications Programming with CCI for more information.

CCI-Trace is only available with CCI Version 2 or later.

CCI-Trace is not available on DOS with any version of CCI. On DOS, CCI-Trace is treated as a null operation and no output is performed.

CCI-Transact

This routine provides the functionality of a synchronous CCI-Send followed immediately by a synchronous CCI-Receive.

Syntax:

call CCI-Transact using sessid
                        buffer
                        sendlen
                        maxlen
                        actuallen
                        cciend

Parameters:

CCI-Wait

Waits until an asynchronous request has completed.

Syntax:

call CCI-Wait using async

Parameters:

Comments:

Asynchronous requests can be established via CCI-Connect, CCI-Initclient, CCI-Receive, CCI-Receiveall or CCI-Send calls. When the request has completed, this routine passes back the request's completion code in RETURN-CODE and causes all return parameters from the original CCI call to be completed. Once a request has completed, this routine should not be invoked again using the same asynchronous request handle value, since the handle value is no longer valid in this instance as the request is complete.

This routine should also not be called with a handle from a session which has been terminated by a CCI-Closeclient, CCI-Closeserver, or CCI-Hangup call, or if the original CCI function call terminated with a non-zero RETURN-CODE.

CCI Error Codes

CCI functions return error codes in the special register RETURN-CODE. On 32-bit operating systems (such as UNIX, Netware 386, and OS/2 2.x), you must set the Compiler directive RTNCODE-SIZE to four. On 16-bit operating systems (such as DOS, Windows 3.x, or OS/2 1.x), you must set RTNCODE-SIZE to 2.

There are 13 return code values. Some are recoverable and some require specific actions to enable the function to complete. The following list gives all of the CCI function return code values and the meaning of each.

Other error codes are allocated for implementation dependent errors. Currently, a "1" is appended to the beginning of NETBIOS errors giving CCI error values of x"101" through x"1FE" for NETBIOS errors. For example, NETBIOS error x"53" (which indicates a hardware malfunction) becomes CCI error x"153". For details of these error conditions, refer to your NETBIOS interface documentation.

3.2 Communications Protocols

The following sections describe each of the available communications modules. See the chapter Communications Programming with CCI for a list of which protocols are available on which operating systems.

3.2.1 CCIAPPC

The CCIAPPC module is provided for the APPC communications protocol.

The information in this section applies equally to DOS, Windows and OS/2. However, there are some additional steps which you must take to access CCIAPPC from DOS. These are described in the section Accessing CCIAPPC from DOS.

CCIAPPC has been tested with OS/2 Communications Manager, Wall Data's Rumba Tools for APPC in Windows and DOS APPC/PC from IBM. Currently the Windows support is restricted to Rumba Version 4.1 and Extra! Personal Client Version 6.1.

3.2.1.1 Basic APPC Concepts

APPC is a high-performance communications protocol with complex configuration requirements. A complete discussion of APPC, and full details of APPC configuration are beyond the scope of this manual. This discussion presents a simple picture of APPC and how CCIAPPC relates to it.

Using APPC, two Transaction Programs (TPs) carry on a conversation. This conversation takes place over a Session, which is established between a pair of Logical Units (LUs). Conversation details such as packet sizes, number of parallel sessions available, and how to resolve resource conflicts are specified using a Mode.

In the case of CCIAPPC, the client and server programs are the TPs. The parameters submitted on the CCI-Initclient and CCI-Initserver calls tell CCIAPPC what values to use in setting up the conversation. These must match values in the APPC configuration files on the local and remote machines.

Each machine has an LU associated with it. Each machine must know its own name (the Local LU) and also the names of any machines it wants to talk to (Remote LUs).

On each machine, CCIAPPC requires you to configure your vendor's APPC support to define a Local LU, one or more Remote LUs, and one or more Modes. In addition, you will need to define a Remotely Attachable TP on the machine where the server program resides. You may need to configure other profiles to define the physical connections between the machines. These are explained in the vendor's documentation for each APPC product.

In most vendors' APPC products, a particular LU profile will contain both an LU Alias and an LU Name. The LU Alias is the name used by the program which calls APPC (in this case, CCIAPPC) and the LU Name is the name actually used in communications. This mapping is intended to give APPC programmers some degree of name transparency, allowing locations to change while the names used in programs remain constant. To avoid confusion, Micro Focus strongly recommends making LU Alias names and LU names identical whenever possible.

The examples given below assume a client program on a machine with the LU name CLIENTLU, and a server program on a machine with the LU name SERVERLU. The server program will use the TP name of SRV1. The programs will communicate using the Mode "#INTER", which is predefined on many APPC platforms.

3.2.1.2 Defining a Server Application

The publicname parameter of the CCI-Initserver routine specifies the Local LU Alias of the server machine and the TP name used by CCIAPPC when issuing the APPC RECEIVE_ALLOCATE verb which accepts the incoming conversation from the client TP. The publicname parameter must be specified in the following format:

LUNAME.TPNAME

where the parameters are:

So, in our example, CCI-Initserver is called with a publicname value of SERVERLU.SRV1. The following profiles need to be defined to APPC on the server machine:

• A Local LU with an Alias Name and LU Name of SERVERLU.

• A Partner LU with an Alias Name and LU Name of CLIENTLU.

• A Mode called #INTER.

• A Remotely Attachable TP Profile for SRV1, detailed below.

If your node receives incoming requests, you must define a Remotely Attachable TP Profile for CCIAPPC. This tells the Attach Manager (a facility within APPC) how to handle the incoming conversation. TP profiles contain a number of fields relevant to CCIAPPC:

CCIAPPC2 (or CCIAPPCW) is started every time a request for a new conversation arrives at the server machine. If a server program has issued a CCI-Initserver and a CCI-Connect or CCI-Receiveall, CCIAPPC2 signals the server program to accept the incoming conversation. If no server program is started, CCIAPPC2 accepts the conversation and sends back an indication that no server is ready.

Note that several servers can run on a single machine by using different TP name values, but the same LU Alias. SERVERLU.SRV1 and SERVERLU.SRV2 can run simultaneously using the same Local LU, conversing with different clients.

3.2.1.3 Initializing a Client Application

The publicname parameter of the CCI-Initclient routine specifies the Local LU Alias of the server machine and the TP name used by CCIAPPC when issuing the APPC ALLOCATE verb to initiate a conversation with the server TP. The publicname parameter must be specified in the following format:

LUNAME.TPNAME

where the parameters are:

The machinename parameter of the CCI-Initclient routine specifies the Local LU Alias of the client machine and the Mode used by CCIAPPC when issuing the APPC ALLOCATE verb to initiate a conversation with the server TP. The machinename parameter must be specified in the following format:

LUNAME.MODENAME

where the parameters are:

So, in our example, CCI-Initclient is called with a publicname value of SERVERLU.SRV1 and a machinename value of CLIENTLU.#INTER. The following profiles need to be defined to APPC on the client machine:

• A Local LU with an Alias Name and LU Name of CLIENTLU.

• A Partner LU with an Alias Name and LU Name of SERVERLU.

• A Mode called #INTER.

3.2.1.4 Limits

The longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Receiveall, and CCI-Transact is 65,535 bytes in length.

3.2.1.5 Accessing CCIAPPC from DOS

On DOS, CCIAPPC uses the IBM APPC/PC product. Unlike many other APPC products, APPC/PC requires minimal configuration during installation. On OS/2 or Windows, you define resource profiles which are referenced by name when issuing APPC verbs. With APPC/PC, LUs and Modes are defined on the fly in the application program.

CCIAPPC on DOS only provides client functionality. The publicname and machinename values on the CCI-Initclient call are the same as those described above in the section Initializing a Client Application. Instead of referring to predefined configuration items, these are used to initialize the appropriate resources when starting a conversation.

In addition to the information contained in publicname and machinename, certain APPC parameters need to be defined in a file called appc_dos.cfg. This file must be available, either by being in the current directory or on the path.

The appc_dos.cfg file is organized into sections corresponding to Partner LUs. Each section contains parameters used when connecting to a particular Partner LU. A sample appc_dos.cfg file is provided with CCIAPPC.

When constructing the appc_dos.cfg configuration file, you should note that:

• An open bracket in the first column begins a definition for the LU within the brackets and terminates the definition of any previous LU.

• The left-hand side (the variable) is not case sensitive.

• The right-hand side (the value) is case sensitive.

• The first white-space on the line ends the parse of that line.

You must include the following items in the appc_dos.cfg configuration file:

• net_name (1-8 characters)

• dlc_name (ITRN/SDLC/COAX)

• pu_name (1-8 characters)

• adapter_number (0 = primary, 1 = secondary)

• lu_local_addr (0 or as defined in VTAM/NCP)

• plu_adapter_addr (12 hex/decimal digits)

The following items are optional when constructing the appc_dos.cfg file and are used to override the default values:

• min_ru_size (default = 256)

• max_ru_size (default = 1024)

• lu_pacing (default = 8)

3.2.1.6 CCIAPPC on CICS

The CCIAPPC module is also available on CICS/MVS and CICS/VSE with a separate product. Contact your Micro Focus sales representative for more information.

CCI normally requires the server program to be pre-started in order to service incoming client requests but on CICS a server program is started by an incoming client request, instead of by operator action. The CCI-Initserver call, followed by CCI-Receiveall or CCI-Connect completes the connection to the client. Each incoming CCI-Initclient request causes a separate instance of the server program to be started by CICS; so a server is unable to connect to multiple client programs. Servers written to support multiple clients (using CCI-Receiveall) will work correctly, but will only connect to a single client.

The CICS server program is conversational; that is, CCI-Send does not contain an EXEC CICS RETURN. Instead, the CICS code waits for a response from the workstation. When the response is received, the CCI-Send completes.

All CCI functions on CICS are performed synchronously, that is, control is returned only when the call has been completed. If an asynchronous function is called, it will be handled as a synchronous call.

Each element of a session leaves the communications module in a particular state. See the chapter CCILU2 Communications Module States for details of the resulting communication states.

3.2.1.6.1 Defining a CICS Server Application

In CICS there is no APPC Local LU definition. CICS implements its own APPC support, and the name which corresponds with the Local LU on other platforms is the VTAM APPLID of the CICS region itself. In CICS there is also no Remotely Attachable TP Profile. Instead, the TP name specified on the incoming conversation is matched against a CICS Transaction ID. In the example used earlier, the transaction SRV1 would be defined in a CICS region called SERVERLU.

The publicname parameter of the CCI-Initserver routine is the CICS Transaction ID of the Server program. The name is 1 to 4 characters in length and unique within the CICS region in which the server executes. Assuming a COBOL program called CCIAPS, whose publicname is SRV1, the following environmental support must be provided in CICS:

• Program Control Table (PCT)

  This table maps the transaction code to a program name. Additionally, our example shows how to specify a time-out value for the transaction. This timeout causes CICS to issue an ABEND AKCT for the transaction if a connected client fails to honor an outstanding read request within the specified period. The following entries are needed:

  DEFINE TRAN(SRV1) PROGRAM(CCIAPS) PROFILE(CCITIME) 
  DEFINE PROFILE(CCITIME) RTIMOUT(mmss) 

  where mmss in the DEFINE PROFILE() entry is a 4-character value specifying minutes and seconds.

• Program Properties Table (PPT)

  Two entries are required for CCI error support on all host systems, as follows:

  DEF PROGRAM(CCIERROR) LANGUAGE(ASSEMBLER) 
  DEF PROGRAM(CCI62ERR) LANGUAGE(ASSEMBLER)

  In addition, an entry is necessary for each server program which is defined in the PCT:

  DEF PROGRAM(CCIAPS) LANGUAGE(COBOL)

CCI is invoked using a standard static call, for example:

move eibtrnid to publicname
call "CCIINITS" using publicname
                      srvrhandle
                      cciend

You must ensure that the CCI object modules will be auto-linked when the server module is processed. For example:

//EXEC PGM=IEWL,PARM='LIST,MAP,XREF' 
//SYSPRINT  DD SYSOUT=* 
//SYSUT1  DD UNIT=VIO,SPACE=(CYL(1,1)) 
//SYSLMOD DD DSP=SHR,DSN=cics_load_lib(server_name)
//SYSLIB  DD DSP=SHR,DSN=cci_lib_obj     (CCI object library)
//SYSLIN  DD DSP=SHR,DSN=library_with_include_DFHEAI/DFHECI
//        DD DSP=SHR,DSN=compiler_syspunch_output

Other methods include:

• Creating INCLUDE cards to be used with SYSLIN input as in the following example (although we advise you not to do this):

  //CICSLIB DD DISP=SHR,DSN=LIBRARY_WITH_EXEC_STUB
  //CCILIB  DD DEISP=SHR,DSN=LIBRARY_WITH_CCI-OBJECT
  //SYSLIN  DD *
  INCLUDE CICSLIB(DFHECI)
  INCLUDE CCILIB(CCIINITS,...) (all CCI modules must be listed)

• Link-editing the CCI modules to be included in a concatenation with other load libraries:

  //SYSLIN DD *
  INCLUDE CCILIB(CCIINITS)
  NAME CCIINITS(R)
  INCLUDE CCILIB(CCICONCT)
  NAME CCICONCT(R)      ...

3.2.1.6.2 Limits and Mainframe-compatible Naming Conventions

External function names on the HOST are limited to 8 characters in length. CCI Server programs on the HOST must call the following entry points:

3.2.2 CCIDDE

The CCIDDE module is provided for session-to-session communication within a single Windows machine and between Windows V3.1x applications and native Windows NT V3.51 applications running within a single Windows NT V3.51 machine.

CCIDDE is supplied for Windows V3.1 or V3.11 and for Windows NT V3.51. CCIDDE uses the Microsoft Dynamic Data Exchange method to transfer data from one application to another.

CCIDDE only supports connections to other CCIDDE applications.

When communicating between single sessions within a Windows architecture, CCIDDE is the preferred CCI module to use for performance.

On Windows V3.1x CCIDDE is supplied as ccidde.dlw in line with the naming conventions used with other CCI 16-bit modules. On Windows NT V3.51, CCIDDE is supplied as ccide32.dll in line with naming conventions used with other CCI 32-bit modules.

3.2.2.1 Limits

The limits on the size of data buffer that can be sent or received using CCIDDE depend on the operating systems being used.

For 16-bit Windows applications, 65522 bytes is the largest buffer that can reliably be used.

When using Windows NT the upper limit is theoretically 2 Gbytes.

When sending data between dissimilar systems, for example, from Windows 16-bit applications running under Windows NT emulators to a true Windows NT application, the Windows NT application will receive the full buffer being sent without any problems. However, sending the data from a Windows NT application to a Windows 16-bit application can potentially cause problems as the 16-bit receiving module cannot cope with the quantity of data being sent.

3.2.3 CCIIPX

The CCIIPX module is provided for the Novell IPX communications protocol.

3.2.3.1 Defining a Server Application

The publicname parameter of the CCI-Initserver routine specifies the name the server is known by on a Novell network. The name must be unique across the network and can be up to eight characters in length. It should be terminated by either a space or a null character.

3.2.3.2 Initializing a Client Application

The publicname parameter of the CCI-Initclient routine specifies the name of the server to connect to.

The machinename parameter of the CCI-Initclient routine is ignored.

3.2.3.3 Limits

The longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Receiveall, and CCI-Transact is 65,535 bytes.

3.2.3.4 CCIIPX on Windows

This section details CCIIPX issues which are specific to the various Windows platforms.

Windows 3.1 and 3.11

To install the Novell Requester on Windows V3.1 and V3.11, refer to the Novell installation documentation.

The following files, supplied with the Novell Netware Requester for Windows, are required for cciipx.dlw to function correctly:

nwipxspx.dll, nwnet.dll, nwcalls.dll, and netapi.dll.

Note: You should obtain the latest drivers from Novell, via CompuServe or the Internet. See the section Novell Support Locations.

CCIIPX has been tested with the Novell NetWare Requester for DOS/Windows using VLM support (patch level VLMUP4) and NETX support (patch level NET33X). Both these patches are available from the Novell support sources listed below.

It is recommended that:

• Novell ODI Network Interface driver modules are used with Novell Client Requester software.

• You read the file deadlock.txt which is included in the Novell NetWare Requester for DOS/Windows and follow the advice that it contains.

• You install the Windows kernel patch (mentioned in deadlock.txt) whenever Novell Requesters are installed in a Windows environment.

Windows for Workgroups V3.11

It is recommended that you install Novell's VIPX.386 module which is supplied with the NetWare Requester rather than the NWLINK.386 IPX support module shipped by Microsoft. To install VIPX.386:

1. Select the Network folder

2. Select the Network Setup icon

3. Select the Drivers button

4. Remove the currently configured protocols and NIC (Network Interface Card, Adapter) driver for the card that the Novell Requester is going to be installed on.

5. Add IPX Support Driver(Monolithic) with NETBIOS transport (NDIS3) as a new network driver. This provides both IPX and NetBEUI support.

6. Close the window and, when prompted, insert the appropriate Novell NetWare Requester diskettes.

7. Follow the installation instructions to install the Novell NetWare Requester software.

With the IPX Monolithic driver installed you can only use IPX and NETBIOS. If you need to use other protocols such as Microsoft TCP/IP or Microsoft DLC, install the ODINSUP driver which is shipped with the NetWare Client Requester diskettes. Alternatively, it is possible to install both the IPX Monolithic driver and a Windows ODI interface driver. Binding the additional protocols to the Windows ODI interface driver enables all the protocols to co-exist without the manual configuration which ODINSUP installations typically require.

Windows 95

The 16-bit CCIIPX module has been tested with Novell's Client32 NetWare Requester.

CCIIPX does not currently support the Microsoft IPX-compatible transport shipped with Windows 95.

3.2.3.4.1 Novell Support Locations

The latest client requesters, and any required patches, are available from ftp.novell.com or www.novell.com on the Internet or from the NetWire forum on CompuServe.

3.2.3.4.2 Microsoft Support Locations

The latest patches for Microsoft Windows for Workgroups V3.11 and Microsoft Windows V3.1 and V3.11 are available from ftp.microsoft.com or www.microsoft.com on the Internet or from the Microsoft forum on CompuServe.

3.2.4 CCILU2

The CCILU2 modules are provided for communications to CICS server programs using 3270 communications protocols. Due to the nature of the 3270 protocols and of CICS transaction processing, there are several significant limitations on client and server architectures as described below. CCILU2 uses the IBM EHLLAPI protocol to interface with 3270 terminal support on the client workstation. Supported emulators are described below, along with any installation and configuration requirements.

Each element of a session will leave the communications module in a particular state. See the chapter CCILU2 Communications Module States for details of the resulting communication states.

3.2.4.1 Defining a Server Application

The publicname parameter of the CCI-Initserver routine is the CICS Transaction ID of the Server program. The name is 1 to 4 characters in length and unique in the CICS region in which the server executes. Assuming a COBOL program called CCILU2S, whose publicname is SRV1, the following environmental support must be provided in CICS:

• Program Control Table (PCT)

  This table maps the transaction code to a program name. Additionally, our example shows how to specify a timeout value for the transaction. This timeout will cause CICS to issue an ABEND AKCT for the transaction if a connected client fails to honor an outstanding read request within the specified period. The following entries are needed:

  DEFINE TRAN(SRV1) PROGRAM(CCILU2S) PROFILE(CCITIME) 
  DEFINE PROFILE(CCITIME) RTIMOUT(mmss) 

  where mmss in the DEFINE PROFILE() entry is a 4-character value specifying minutes and seconds.

• Program Properties Table (PPT)

  One entry is required for CCI error support on all host systems, as follows:

  DEF PROGRAM(CCIERROR) LANGUAGE(ASSEMBLER)

  In addition, an entry is necessary for each server program which is defined in the PCT:

  DEF PROGRAM(CCILU2S) LANGUAGE(COBOL)

CCI is invoked using a standard static call, for example:

move eibtrnid to publicname
call "CCIINITS" using publicname
                      srvrhandle
                      cciend

You must ensure that the CCI object modules will be auto-linked when the server module is processed. For example:

//  EXEC PGM=IEWL,PARM='LIST,MAP,XREF'
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD UNIT=VIO,SPACE=(CYL(1,1))
//SYSLMOD   DD DSP=SHR,DSN=cics_load_lib(server_name)
//SYSLIB    DD DSP=SHR,DSN=cci_lib_obj       (CCI object library)
//SYSLIN    DD DSP=SHR,DSN=library_with_include_DFHEAI/DFHECI
//          DD DSP=SHR,DSN=compiler_syspunch_output

Other methods include:

• Creating INCLUDE cards to be used with SYSLIN input as in the following example (although we advise you not to do this):

  //CICSLIB  DD DISP=SHR,DSN=LIBRARY_WITH_EXEC_STUB
  //CCILIB        DD DEISP=SHR,DSN=LIBRARY_WITH_CCI_OBJECT
  //SYSLIN   DD *
  INCLUDE CICSLIB(DFHECI)
  INCLUDE CCILIB(CCIINITS,...)  (all CCI modules must be listed) 

• Link-editing the CCI modules to be included in a concatenation with other load libraries:

  //SYSLIN DD *
  INCLUDE CCILIB(CCIINITS)
  NAME CCIINITS(R)
  INCLUDE CCILIB(CCICONCT)
  NAME CCICONCT(R)
        ...

3.2.4.2 Initializing a Client Application

The publicname parameter of the CCI-Initclient call is the CICS Transaction ID of the Server program. The name is 1 to 4 characters in length and unique in the CICS region in which the server executes. Using the example above, the publicname would be SRV1.

The machinename parameter of the CCI-Initclient call specifies the method by which the 3270 connection is established to the HOST region in which the server executes. The machinename is 8 characters long, and has one of three forms:

• VTAM APPLID of the CICS region to connect to.

• NULL-x, where x is the 3270 short session identifier.

• Spaces.

CCI-Initclient establishes a connection to the HOST in one of the following ways.

• When a VTAM APPLID is provided, locate the first available 3270 session and issue a VTAM Logon command of the form:

  LOGON APPLID(machinename). 

  The results of the Logon command and any further logon and/or signon activity will be the responsibility of the Customer Logon exit (described below). If the Logon exit reports a failure, the same process will be repeated with the next available 3270 session in the list until a connection is established or no sessions are available.

• Connect to the 3270 session specified as x in the NULL-x machinename and call the Customer Logon exit. See the section Customer Logon Exit for further information.

• When no machinename is specified call the Customer Logon exit for all processing.

The Customer exit will support logon and signon processing. This exit will handle the results of the VTAM logon as well as perform any HOST system signon including dealing with "about to expire" and "expired" passwords. The Customer exit will be called at CCI-Closeclient and will be responsible for signoff and logoff processing.

3.2.4.3 Limits

• The longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Transact, and CCI-Receiveall is 65,535 bytes.

• CCI normally requires the server program to be pre-started in order to service incoming client requests. 3270 communications to CICS are such that a server program is started by an incoming client request, instead of by operator action. The CCI-Initserver call, followed by CCI-Receiveall or CCI-Connect will complete the connection to the client. Each incoming CCI-Initclient request will cause a separate instance of the server program to be started by CICS. Thus a server will be unable to connect to multiple client programs. Servers written to support multiple clients (using CCI-Receiveall) will work correctly, but will only connect to a single client.

• A Client can issue multiple CCI-Initclient commands to connect to multiple Servers. Each CCI-Initclient will need its own 3270 session because 3270 sessions are held until a CCI-Closeclient command is issued.

• The CICS server program is conversational in nature, that is, CCI-Send does not contain an EXEC CICS RETURN. Instead, the CICS code waits for a response from the workstation. When the response is received, the CCI-Send completes.

• All CCI functions on CICS are performed synchronously. That is, control is returned only when the function has completed. Asynchronous call syntax is supported, but the actual call will be performed synchronously. The CCI-Query and/or CCI-Wait calls usually associated with asynchronous call completion always
  return 0.

• Servers reside only on the HOST. All 3270 transactions are driven form the workstation. Any CCI calls which support servers (CCI-Initserver, CCI-Connect, CCI-Resumeserver, CCI-Receiveall, CCI-Suspendserver, CCI-Hangup, CCI-Closeserver) will result in a return value of 9 from CCI if issued on the workstation. Similarly, Client support calls cannot be issued by a HOST program.

• External function names on the HOST are limited to 8 characters in length. CCI Server programs on the HOST must call the following entry points:

  8 Character CCI API	Equivalent CCI Call
  CIINITS	CCI-Initserver
  CCICLOSS	CCI-Closeserver
  CCIINITC	CCI-Initclient
  CCICLOSC	CCI-Closeclient
  CCIHNGUP	CCI-Hangup
  CCISEND	CCI-Send
  CCIRECV	CCI-Receive
  CCIRECVA	CCI-Receiveall
  CCITRANS	CCI-Transact
  CCICONCT	CCI-Connect
  CCIWAIT	CCI-Wait
  CCIQUERY	CCI-Query
  CCIRESMC	CCI-Resumeclient
  CCISUSPC	CCI-Suspendclient
  CCIRESMS	CCI-Resumeserver
  CCISUSPC	CCI-Suspendserver
  CCIGERR	CCI-Geterror

3.2.4.4 Customer Logon Exit

This module contains user code to extend the base function of the CCILU2 communications module. It handles both logon and logoff duties for the base system.

Three basic modes of operation can be handled. These are keyed on the 8 character machinename parameter provided on a call to CCI-Initclient. The three formats of machinename and the resulting behavior of CCILU2 for CCI-Initclient function are documented below. The exit is passed a control block, whose format is as follows:

 01 EXIT-CONTROL-BLOCK 
  03 EXIT-APPL             PIC X(8) 
  03 EXIT-SHORT-NAME       PIC X 
  03 EXIT-MODE             PIC X
   88 LOGON_APPL           VALUE "1" 
   88 LOGON_SESSID         VALUE "2"
   88 LOGON_BLANK          VALUE "3"
   88 LOGOFF_APPL          VALUE "A"
   88 LOGOFF_SESSID        VALUE "B"
   88 LOGOFF_BLANK         VALUE "C"
  03 EXIT-SESSIONS-USED    PIC X(26)
  03 EXIT-RETURN-CODE      PIC S9(4) COMP

3.2.4.4.1 Logon Behavior

CCILU2 calls the exit primarily to ensure that logon procedures are handled correctly for the HOST system. After the exit has completed, the HOST session must be logged on to CICS, and in a state where a CICS transaction can be initiated from the terminal.

If machinename is a VTAM APPLID:

• CCILU2 finds all active 3270 HOST sessions. It will loop through the sessions, performing the following sequence of events until it runs out of sessions, or until the exit indicates success.

• CCILU2 connects to the current session and issues the command:

  "LOGON APPLID(EXIT-APPL)" 

  It will then disconnect and call the exit.

• The EXITCTL structure is set up as follows on entry:

  EXIT-APPL	The APPLID just used to log on
  EXIT-SHORT-NAME	The Short Session ID used
  EXIT-MODE	The character "1"

This exit must determine if the logon has succeeded, or provide any necessary security handling, and so on. If the session is successfully logged on, the exit returns with EXIT-RETURN-CODE = 0. If the attempt fails, the exit returns with EXIT-RETURN-CODE set to a non-zero value.

If machinename is of the form NULL-x, where x is a 3270 Short Session ID:

• CCILU2 will verify that the 3270 session designated by x is a HOST session and can be connected. This exit is called for any necessary processing on the session. If the user has already logged on to CICS this exit can simply return with EXIT-RETURN-CODE set to 0.

• The EXITCTL structure is set up as follows on entry:

  EXIT-APPL	"NULL-x" ( x is replaced by A-Z )
  EXIT-SHORT-NAME	the Short Session ID used ("x")
  EXIT-MODE	the character "2"

If machinename is blank:

• The exit is expected to handle all logon processing. The exit must find an active session, or prompt the user to start one. Upon exit, EXIT-SHORT-NAME must contain a Short session ID of a session which is logged on to CICS and ready to use.

• The array EXIT-SESSIONS-USED contains 26 characters. It is a list of sessions already in use by the client program, left-justified in the array, and blank-filled. This exit MUST NOT USE any session whose ID appears in the array. These sessions are already being used by this process, and HLLAPI will not prevent access to them by new threads in the same process.

3.2.4.4.2 Logoff Behavior

When CCILU2 is called for CCI-Closeclient, the logon Exit is called to provide any session-specific or environment-specific logoff service which is necessary. Since any session is serially reusable and all access is synchronized by CCI, the EXIT-APPL can be used to key any logoff call to its corresponding logon call. During normal operations, a session which is logged on will never be logged on again without an intervening logoff.

The EXITCTL structure is set up as follows on entry:

If machinename is:

CCI ignores the EXIT-RETURN-CODE from the Logoff call.

3.2.4.5 Supported 3270 Emulators

OS/2:
For OS/2, use IBM Communications Manager. You must configure at least one 3270 terminal session. CCI supports the maximum of 10 sessions provided by the Communications Manager. EHLLAPI support is automatically installed.

Windows:
For Windows, use DCA IRMA Workstation for Windows. Install the IRMA software to enable 3270 emulation.

DOS:
For PC/DOS, use DCA IRMA Workstation for DOS. Install the IRMA software to enable 3270 emulation. In addition, you must load a module for EHLLAPI support. If you have configured a CUT emulation, load ehllc.exe. If you have configured DFT emulation, load ehlln.exe.

3.2.5 CCINAMP

The CCINAMP module is provided for the Named Pipes communications protocol on OS/2.

3.2.5.1 Defining a Server Application

The publicname parameter of the CCI-Initserver routine specifies the name of a named pipe to be created. The named pipe must have a unique name that distinguishes it from other named pipes. The following pipe name will be created by the CCI-Initserver routine:

\pipe\publicname 

where publicname must conform to the rules for OS/2 filenames.

3.2.5.2 Initializing a Client Application

The publicname parameter of the CCI-Initclient routine specifies the name of the named pipe to be connected to. A server application should have been started to create the named pipe via the CCI-Initserver routine. CCI-Initclient first tries to connect to a local pipe of the name:

\pipe\publicname 

If this pipe does not exist and the computer is connected to a LAN server, CCI-Initclient tries to connect to a remote pipe of the name:

\\server\pipe\publicname 

where server is the name of the LAN Server. CCI-Initclient connects to the first server it finds having the required pipe name. The machine must be an OS/2 LAN Server.

The machinename parameter of the CCI-Initclient routine is ignored.

3.2.5.3 Limits

The longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Receiveall, and CCI-Transact is 65,500 bytes.

3.2.6 CCINAMPU

The CCINAMPU module is used to connect processes on single UNIX machines using UNIX named pipes (FIFO). Any process running on a machine which has CCINAMPU installed can access any service on that same machine. CCINAMPU cannot communicate with CCINAMP for OS/2.

3.2.6.1 Transport Speed

For a given machine CCINAMPU is approximately three to five times faster than using CCITCP in loopback mode (communicating on a single machine).

3.2.6.2 Server Names and Machine Names

The server name specified in the publicname parameter of a call to CCI-Initserver can be one of the following:

• A relative pipe-name (default)

• An absolute pipe-name

For example, a servername consisting of

mainsrvr

would generate a named-pipe with the name:

which would be unique on the machine in use.

The only restriction for using an absolute pipe-name is that the pipe name must be of a file layout supported by the host machine's file system.

An example of an absolute pipe-name is:

/u/work/pipespace/

This creates a pipe at the exact location specified. If the user attempting to create the pipe does not have permissions to use the requested directory, CCI-Initserver issues an error.

All absolute pipe-names must start with a leading slash (/).

The CCI-Initclient function assumes servername is a relative pipe-name when it is passed an empty machinename parameter. When CCI-Initclient is passed a non-empty machinename parameter, the pipe-name searched for is composed of the absolute servername with the machinename preceding it to form the complete absolute path.

Thus if servername is passed as:

mainsrvr

and machinename is passed as:

/u/work/pipespace

the resultant pipe that is searched for would be:

/u/work/pipespace/mainsrvr

and would connect with the example of an absolute servername in the description for calling CCI-Initserver given above.

An absolute pipe-name must be consistant with any limitations of the file system in use on the host machine at all times. You should be aware that file permissions apply to named-pipes as well as to files.

Absolute pipe-names cannot be used across network file systems (NFS) succesfully. Therefore, we recommend that relative pipe-names are used for simplicity in the majority of applications.

3.2.6.3 Registration Module

Unlike CCITCP, there is no central registration module for CCINAMPU. Any service name given to CCI_NAMPU_Initserver, for example, "SRVS" appears as a pipe-file in the directory /var/spool/uucppublic/.cci/.SRVS on Linux, or /usr/spool/uucppublic/.cci/.SRVS on other UNIX systems .

These are not normal files but they are affected by access permissions. So, if a server doesn't respond to a client's request, the first check should be made on access permissions. All files, and the directory itself, should have READ and WRITE permissions for all processes.

This check for adequate permissions is equally true for all occurrences where absolute path-names are given to CCI, especially when the client and server modules have been started by different system users.

3.2.6.4 Using CCINAMPU

As with all UNIX system support modules, the program calling the modules needs access to the entry points of the support modules. In the case of CCI modules this means that before a program can call a CCI module it must first be linked to a segment of executable code that the user can access.

For .int and .gnt code execution, the CCI modules must be present in the run-time system that will be executing the .int/.gnt code module.

To do this you must use either the Toolbox base run-time system, which already contains CCINAMPU, or use the following command line to create a run-time system which includes CCI modules:

cob -xvo newrts -I CCIXXXX [-I CCIXXXX]

where:

More than one -I CCIXXXX can be issued for a given run-time system; however, only one should be issued for each protocol.

For each CCI module to be included in a new RTS the following components must be present:

• A linker

• A system development kit (for system specific support code)

The same dependencies are true for generating a statically linked executable module.

3.2.7 CCINETB

The CCINETB module is provided for the NETBIOS communications protocol. To use CCINETB, you must already have network services loaded on the machine in question. On OS/2, this requires a LAN requester to be started using the command:

net start req

DOS and Windows:
On DOS and Windows, this requires a NETBIOS interrupt interface to be installed. These interfaces are supplied by various vendors; see the documentation supplied with your NETBOIS interrupt interface for installation details.

Windows:
On Windows, with most NETBIOS vendors, there is a potential problem that when using synchronous CCINETB functions, the Windows desktop may pause until the call is completed. This is not a fault of CCINETB but is a symptom of the NETBIOS API, which is not aware of its use within a Windows environment and fails to yield the CPU back to the desktop at the appropriate time. The solution to this problem is to install a version of the NETBIOS interface which is aware of Windows and which yields the CPU at the appropriate time.

Currently Micro Focus has identified one set of drivers meeting these conditions - the drivers forming part of Microsoft's Windows for Workgroups. These drivers will work correctly when installed for Windows operation. To do this, add the following line to your autoexec.bat file to start the network support modules:

net start

If DOS NETBIOS is required using the Windows for Workgroups modules, before invoking Windows, the following commands can be used:

net start netbeui
or
net start netbios 
or
net start wrkstation

You should be aware that when you use any of these commands, the drivers are no longer aware of operating under Windows, so they will subsequently fail to yield the CPU as required when they are used under Windows.

Therefore we recommend that if you are using Windows for Workgroups, you do any DOS work from within a Windows for Workgroups DOS emulation session and load the NETBIOS support as specified in the first example above.

With Windows for Workgroups, CCINETB and CCIIPX can only be used concurrently if the selected default protocol is NetBEUI.

To load protocols other than IPX and NetBEUI when using the IPX Support Driver (Monolithic) with NetBIOS transport, see the section CCIIPX.

With Windows for Workgroups and Windows 95, the default protocol is the NetBIOS interface that CCINETB uses to communicate with the network. For successful CCI communication, the same default protocol must be used by both the machines making a connection.

For Windows 3.1 and 3.11, the default protocol is selected according to the setting of lana0= in the protocol.ini file. Refer to your network documentation for information on setting the default protocol.

3.2.7.1 Defining a Server Application

The publicname parameter of the CCI-Initserver routine specifies the name which is to be added to the NETBIOS name table to allow other processes/workstations to connect to the application. The name must be unique across the network and can be up to 16 characters in length. It should be terminated with either a space or a null character.

3.2.7.2 Initializing a Client Application

The publicname parameter of the CCI-Initclient routine specifies the name of the server application to be connected to. A server application should have been started to define this name to the network via the CCI-Initserver routine.

The machinename parameter of the CCI-Initclient routine is ignored.

3.2.7.3 Limits

The longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Receiveall, and CCI-Transact is 65,535 bytes.

3.2.8 CCITCP

The CCITCP modules are provided for the TCP/IP communications protocol and are available for DOS, Windows, Windows NT, OS/2 and UNIX.

The CCI suite for TCP/IP networks on UNIX, Windows NT and OS/2 consists of two execution modules; on DOS and Windows only one module is supplied. These modules are:

• The CCITCP API module, which contains the CCI interface routines.

• A registration module, which is used to register and advertise server processes that are available for clients to call. This module is called ccitcp2.

The CCITCP modules can be used to connect DOS, Windows, OS/2 and UNIX machines in any combination for inter-machine cooperative processing. CCITCP can also be used for process-to-process cooperative processing within any single UNIX or OS/2 machine exactly as if the processes were executing on separate networked machines and without generating network traffic.

All CCITCP modules assume that the appropriate TCP/IP network hardware and software drivers are already installed, fully configured, and working. Once the software is installed and configured, it is essential that the network connections are fully checked out in both directions using suitable utilities, such as the TCP/IP standard commands "ping" and "ftp", before attempting to use CCITCP routines. Where an ethernet network is connected to a token ring network, ensure that TCP/IP is aware of the gateway by running "route add" or a similar command. Please see your TCP/IP vendor's installation and configuration guides for details of these steps.

CCITCP modules for UNIX are supplied as archived object modules, which must be linked with your application program before they can be used with UNIX executable modules. They are also built into the Toolbox and OSX run-time systems, for use with .int and .gnt modules.

CCITCP for DOS, Windows and OS/2 is supplied in both linkable and executable form, so you can choose to link the modules and/or run the pre-built executables as your circumstances require.

Full details on loading and configuring the TCP/IP system files for CCITCP and on linking CCITCP object modules are contained in the section CCITCP Setup and Limits.

3.2.8.1 Defining a Server Application

The publicname parameter of the CCI-Initserver routine specifies the service name that will be registered and advertised by the ccitcp2 process (see the section Process Registration Daemon for details). The name must be unique to the machine on which it is running (this is not necessarily the same machine on which it is registered) and can be up to 127 characters in length. It should be terminated by either a space or a null (binary zero) character.

When CCI-Closeserver is called, the currently selected ccitcp2 is instructed to de-register the service. The CCITCP modules then close down all connections related to that service.

It is the calling program's responsibility to ensure that the ccitcp2 process attempting to de-register the service is the same ccitcp2 process that was used to register the service.

Note: It is the caller's responsibility to ensure that all services call CCI-Closeserver before quitting. A service remains registered until either CCI-Closeserver is called or another service of the same name and from the same machine takes its place in the list.

If a registered program terminates prematurely (that is, before de-registering by executing CCI-Closeserver), then it will block access to other programs registered with the same name with the same ccitcp2 process. This block will be removed as soon as a service of the same name registers with the same registration daemon from the same machine that the original (prematurely terminated) service was running on. For example, if PROGA on MACHINE1 is registered with ccitcp2 on machine TCP1 and PROGA terminates prematurely, no CCI-Closeserver call is made. Therefore, PROGA service on MACHINE2 registered with ccitcp2 on machine TCP1 cannot be connected to. In this situation, there are two ways to overcome the problem:

• The original server, PROGA on MACHINE1, may restart and close correctly, which will clear the block.

• The client program that wants to connect to a blocked service should state the host name of the machine on which the blocked service resides (MACHINE1) as the second parameter of the CCI-Initclient call. This bypasses the blockage in the manner described in the section CCITCP2 Search Order.

When a CCI TCP service starts, the port used to detect new incoming clients is allocated by the underlying TCP stack. However, it is sometimes necessary to make the server listen for incoming connections on a specific port. For instance, if you want to make the service available through a firewall which only allows access through certain ports you will need to define which port the CCI server is listening on.

To make a service use a specific port the publicname can be appended with ,MFPORT:port, where port is the decimal value of the port you want the server to listen on for connecting clients. (The public name of the server as advertised remains unchanged by adding the ,MFPORT:port suffix: these additional characters are removed and parsed internally by the CCI.)

If an MFPORT value is specified then a CCITCP2 process is not required in order for the CCI-Initserver call to succeed (although the server will register normally if the CCITCP2 daemon is present) - this is because clients can now connect to the service directly if they know the address and port it is using (see section below on how they can do this).

The CCI-Initserver API servername parameter can be over-ridden if the following is present in the cci.ini file:

[ccitcp-servers]
servername=MFPORT:port

where servername is the public name of the server.

In turn, this value too can be over-ridden by an environment variable of the form:

CCITCPS_servername=MFPORT:port

3.2.8.2 Initializing a Client Application

The publicname parameter of the CCI-Initclient routine specifies the name of the server application to connect to.

The machinename parameter of the CCI-Initclient routine can be set to one of the following values:

• The text-based internet machine name of the target machine as it appears in the "hosts" file. This parameter is case sensitive.

• SPACES if the target machine name is not known.

• LOW VALUES (Binary zeros) if the target machine name is unknown.

The process registers a service's existence using the settings of the machinename and publicname parameters of the CCI-Initclient routine. See the section Process Registration Daemon for details on the ccitcp2 process. If both publicname and machinename are specified, then ccitcp2 returns the machine and port addresses of only the service registered from the machine specified in machinename. If the service is not found, an error is returned. If publicname is specified but machinename is not, ccitcp2 follows a set search order to locate an occurrence of the requested service (see the section CCITCP2 Search Order for details). This is useful if you do not need to know about a particular machine but simply want to find a machine that provides a desired service.

If a client wishes to target a specific CCI server at a specific address and port value then it can do this by using the following form of machinename:

MFNODE:node,MFPORT:port

where node is the text hostname or dotted decimal address of the target server, and port is the decimal value of the port it is known to be listening on.

The CCITCP2 daemon need not be present for this CCI-Initclient call to succeed, since the client is attempting to contact the server directly.

The CCI-Initclient machinename parameter value can be over-ridden if the following is present in the CCI.INI file:

[ccitcp-targets]
servername=MFNODE:node,MFPORT:port

where servername is the public name of the server.

In turn, this value too can be over-ridden by an environment variable of the form:

CCITCPT_servername=MFNODE:node,MFPORT:port

3.2.8.3 Buffer Limits

It is possible for CCITCP on 32-bit platforms (for example, UNIX and Windows NT) to inadvertantly send more than 64K to a 16-bit CCITCP module, (for example, on DOS). In these circumstances, CCITCP on the DOS machine will accept as much incoming data as possible (usually "maxlen" or 64K whichever is less), and return a RETURN-CODE value of "2". This value should not be treated as a failure of the reading operation as subsequent CCI-Receive or CCI-Receiveall function calls can be used to receive the remaining data. You should code your applications to take this situation into account, or limit the transmission buffer sizes in use to those common across all connected environments.

DOS and Windows:
For DOS and Windows, the longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Receiveall, and CCI-Transact is 65535 bytes.

There are also a number of process limits set by TCP/IP vendors. Please see the chapter Configuring TCP/IP and the VSL for DOS and Windows.

Windows NT and UNIX:
For UNIX and Windows NT, the longest buffer that can be handled by CCI-Send, CCI-Receive, CCI-Receiveall, and CCI-Transact is dependent on operating system constraints. Theoretically, the upper limit is 4,294,967,294 bytes. This size must only be transmitted between CCI applications of similar capacity.

OS/2:
For OS/2, the limit is 65535 bytes. Additionally, a number of process limits are set by the network software. These are detailed in the section CCITCP Limitations under OS/2.

3.2.8.4 Using CCITCP on UNIX

As with all UNIX system support modules, the program calling the modules needs access to the entry points of the support modules. In the case of CCI modules this means that before a program can call a CCI module it must first be linked to a segment of executable code that the user can access.

For .int and .gnt code execution, the CCI modules must be present in the run-time system that will be executing the .int/.gnt code module.

To do this you must use either the base run-time system, which already contains CCITCP, or create a run-time system which includes CCITCP. See the next section Linking CCITCP Modules for details.

3.2.8.5 Linking CCITCP Modules

CCITCP object code libraries or archives are available for DOS, Windows, OS/2 and UNIX. The files supplied are listed below.

Note: The libosx library is also supplied as a shared library on some UNIX platforms. For example, on SVR4 systems, it is supplied as libosx.so.

DOS:
CCITCP cannot be statically linked with programs that use the Adis ACCEPT and DISPLAY module from COBOL because a fixed function of the SOCKETS interface used by CCITCP is ACCEPT which is also a fixed function of Adis. This causes errors at run-time.

As the DOS TCP/IP vendor support interface is proprietary and DOS does not support dynamic linking, a CCITCP statically linked program will be tied to the TCP/IP vendor support used at the time of linking. Static linking when VSL support is enabled allows CCITCP support for more TCP/IP vendors than if you linked with other vendor support.

When linking with VSL support enabled, the link library lsocklib.lib must be included in the link command before coblib or lcobol. When linking with other TCP/IP vendor's support you must include the relevant SOCKETS support libraries supplied by the TCP/IP vendor's Software Development Kits (SDK) for linking. See your TCP/IP vendor's re-seller for details of SDKs. These are not required when linking with VSL support modules.

Windows:
On Windows systems, CCITCP will be dynamically linked to the ccitcp.dlw module present on the machine at run-time. There are several different ccitcp.dlw modules that can be loaded for the different types of TCP/IP support. You can change to a different ccitcp.dlw module at any time for different TCP/IP support installations when you run them with a single dynamically linked program.

OS/2:
To dynamically link ccitcp.dll with your executable, enter:

link /NOD /NOE /STACK 16384 user-file.obj,,,ccitcp;

where:

CCITCP will be dynamically linked with the ccitcp.dll module as described for the Windows ccitcp.dlw module above.

UNIX:
In UNIX environments, the CCITCP module needs to be built either into a run-time system, if you are running generated or intermediate code, or directly into an executable program before CCITCP can be used.

To build the functions into an executable program, enter:

cob -xv program-name.cbl -I CCITCP

To build the functions into a run-time system, enter:

cob -xvo newrts -I CCIXXXX [-I CCIXXXX]

where:

More than one -I CCIXXXX can be issued for a given run-time system; however, only one should be issued for each protocol.

For each CCI module to be included in a new RTS, several components must be present including:

• A linker

• A system development kit (for system specific support code and TCP/IP libraries)

For CCITCP, a TCP/IP system development kit is required. Some CCITCP support code is linked from system specific network support, development libraries and archives. This must be included in the operating system running CCITCP by the operating system supplier.

The same dependencies are true for generating a statically linked executable module.

3.2.8.6 Process Registration Daemon

On Windows NT, Windows 95 and OS/2 systems, the ccitcp2 registration process can be started automatically at system start-up by including it in the startup folder.

Alternatively, ccitcp2 can be started manually by entering:

ccitcp2 [-v]

at the operating system command prompt.

Specifying the -v option causes ccitcp2 to display its version number and then terminate.

On UNIX, ccitcp2 must be invoked by root.

The ccitcp2 process registration program is designed to be loaded as a background task under UNIX and OS/2.

There only needs to be one ccitcp2 module active on a network in order for CCITCP to work. However, for maximum efficiency, you should install a ccitcp2 program on each machine on the network using CCITCP and the service registrations should be shared evenly between the active ccitcp2 modules.

No configuration is necessary for the UNIX, Windows NT or OS/2 ccitcp2 modules. They will accept service registrations until the effective RAM available to the process is exhausted, or until the machine is shut down.

3.2.8.6.1 Local and Remote Registration Utilities

As noted previously, you can specify a particular machine to ccitcp2 on which to locate a requested service or you can set the machinename parameter to spaces. If you use spaces, the setting of the CCITCP2 environment variable can be used to determine the actual service to which the client process connects.

If the CCITCP2 environment variable specifies the calling machine, or if it is not set, then the ccitcp2 process to be used is regarded as local .

If the CCITCP2 environment variable specifies a machine other than the calling machine, then the ccitcp2 process to be used is regarded as remote .

For example, specifying:

set CCITCP2=unixserver1 

in a system configuration file forces the DOS, OS/2 or UNIX CCITCP module to use the ccitcp2 process running on the machine called unixserver1.

Note that CCITCP2 must be upper case in the set command, and unixserver1 must match the name and case given in the hosts file.

You can use the standard TCP/IP "ping" command to check that the machine on which the ccitcp2 process is running is up and accessible, before actually attempting to use CCITCP.

Note: This command provides a rough confidence check that TCP/IP is installed on the machine to be used. As "ping" does not actually use all of the aspects of TCP/IP that CCITCP uses, the results of "ping" and CCITCP connectivity may vary.

You must use a remote ccitcp2 process if you are running under DOS or Windows and it may be found useful when using OS/2, or if you have a service named on several machines on the network.

For information on configuring ccitcp2 under Windows, see the section Manually Configuring CCITCP for Windows.

When a service name is registered on several machines on the network and the machinename parameter is not specified in the CCI-Initclient routine, then using a remote ccitcp2 process can enable you to predict which version of the named service will be connected. You can do so by understanding the search order that the ccitcp2 process follows.

3.2.8.6.2 CCITCP2 Search Order

If both publicname and machinename are specified in the CCI-Initclient routine, the ccitcp2 process returns the machine and port addresses of the service specified in the routine. If the service is not found, an error is returned.

However, if publicname is specified in CCI-Initclient but machinename is not, the ccitcp2 process searches the registered services and addressable machines in the following order until either a process is found or an error is returned:

1. The ccitcp2 process returns the address and port of any occurrence of the named service that is registered with it and is resident on the same machine as the ccitcp2 process.

2. The ccitcp2 process returns the address and port of any occurrence of the named service that is registered with it but resident on another machine.

3. The ccitcp2 process returns the address and port of the first occurrence of the named service that is registered with any other addressable ccitcp2 process. Note that there is no guarantee which particular service this will be.

4. The ccitcp2 process returns an error to the calling program if the named service still cannot be found.

You can avoid the potential problem of producing an undesired connection from the third level search by closely observing the rules followed at the first two search levels or by using a unique name for each server process on the network.

3.2.8.6.3 CCITCP2 Troubleshooting

This section provides information that may be useful if you experience problems with ccitcp2. For example, you may notice that a client fails to connect with a registered service as follows:

• Service A registers itself with the ccitcp2 process running on machine A

• Client B looks for service A using the ccitcp2 process running on machine B

• Client B fails to connect to service A.

The ccitcp2 modules are designed to communicate with each other using the TCP/IP broadcast address mechanism. If this is not correctly configured, ccitcp2 cannot locate services registered with other ccitcp2 modules. If this happens, you should advise your system administrator.

System administrators should be aware of the following:

• On TCP/IP network systems built around BSD UNIX version 4.2, the network broadcast address which is in use defaults to 0.0.0.0 (all binary zeros). In all other network configurations, including later BSD UNIX versions, the network broadcast address used by default is 255.255.255.255 (all binary ones).

• For ccitcp2 processes to communicate with each other; that is, share registration information, the host network configurations must use the same broadcast address convention. The system command "ifconfig" (InterFace CONFIGuration) at system startup is usually used to specify the broadcast address. Alternatively, the system configuration manager (sysadmsh, smit, and so on) may have a similar capability.

• Bridges and gateways that are not configured to pass broadcast addressed packets will have a blocking effect on CCITCP connectivity. These items must be re-configured to pass broadcast packets if the registration of processes is performed on a leg of a network other than that of the requesting client. The actual configuration operations for these are specific to each device. In this situation, the use of a ccitcp2 module on the same leg of the network for both client and server applications will avoid the problem.

• Most bridges and routers can be configured to only pass broadcast packets using certain TCP/IP port numbers; that is, a filter is applied. To allow ccitcp2 to communicate across bridged networks, your router or bridge should allow broadcasts using port number 86 in the UDP domain to pass unhindered through the filter.

• If you are using host names rather than IP addresses to make connections, remember that host names can be defined in several places (including the local HOSTS file which takes precedence) and therefore you must ensure that the names being used are consistent across the network.

For ccitcp2 modules to communicate correctly, your network must be configured to pass broadcast packets to all areas that want to use CCITCP.

3.2.8.7 CCITCP Setup, Configuration, and Limits

This section contains information that will help you to configure TCP/IP. See also the chapter Configuring TCP/IP and the VSL for DOS and Windows.

TCP/IP support must be installed and configured before you can use CCITCP.

UNIX:
UNIX TCP/IP is supplied by the operating system vendor for all machines. Please contact your operating system supplier for further details.

3.2.8.7.1 CCI Installation Utility (DOS, Windows and OS/2)

The CCI installation utility enables you to install specific versions of CCITCP to enable TCP/IP support for specific protocol suppliers. You need to identify the type of TCP/IP support required and the directories into which the software is to be installed. For further details on the CCI installation utility, see the chapter Configuring TCP/IP and the VSL for DOS and Windows.

3.2.8.7.2 Hardware and Software Requirements

UNIX:
The CCITCP modules for UNIX require BSD 4.3 Sockets to be installed and working and the correct network software to enable socket connection to a physical network. The CCITCP modules for UNIX enable immediate connections between all TCP/IP and CCITCP equipped machines that are registered in the /etc/hosts file on each client and server machine. You must ensure that the /etc/services file contains the services entry:

mfcobol     86/udp

Windows NT:
On Windows NT, the /etc/services file can be found in the
%SystemRoot\system32\driver\etc directory.

OS/2:
The CCITCP module for TCP/IP on OS/2 relies on either PCTCP socket emulation software from FTP Software, Inc., or IBM's TCP/IP for OS/2 V1.2.1 (refresh) for access to TCP/IP networks.

Before CCITCP connections can be made on OS/2, the FTP PCTCP or IBM's TCP/IP V1.2.1 (refresh) and TCP/IP kernel interfaces need to be loaded on any OS/2 machine requiring access to the network. The relevant system configuration files HOSTS and SERVICES need to be configured for all remote CCITCP hosts as well as for the mfcobol service. Additionally, a suitable hardware card needs to be installed for access to the network.

DOS and Windows:
Many independent vendors supply TCP/IP products for machines running DOS and Windows.

On Windows systems, many of these support the Winsock 1.1 standard interface. With these products, the CCITCP Generic Winsock 1.1 support module should be selected when CCITCP is installed. Products which are currently supported by this module include:

FTP PC/TCP V3.0, V3.1 and V4.0
FTP Onnet V1.x, V2.x
Microsoft 32-Bit TCP/IP V3.11b
Novell LAN Workplace V4.2
Netmanage Chameleon/NEWT V4.6
Sun PC-NFS V5.1a
Sun PC-NFS Pro V1.x

From Version 3 of CCI onwards, the CCITCP Generic Winsock 1.1 support module supports multiple Windows applications.

For other supported TCP/IP products on Windows, see the chapter Configuring TCP/IP and the VSL for DOS and Windows. For these products, you will need to select VSL support when you install CCITCP.

On DOS systems, by default, CCITCP supports FTP PC/TCP, without the use of the Micro Focus memory extender (XM). It can be configured to support XM, and/or other TCP/IP products - see the chapter Configuring TCP/IP and the VSL for DOS and Windows for details.

All:
TCP/IP requires that both the machines involved in a conversation are aware of each other in order for the conversation to take place. This means that either each must have an entry in the other's HOSTS configuration file, or both must be accessible via a network host nameserver.

Once you have set up your CCITCP connections, you can use the standard TCP/IP command "ping" to check that the connections are up and running before attempting to use CCITCP.

3.2.8.7.3 Manually Configuring TCP/IP for CCITCP

Each TCP/IP machine maintains a list of services which can be advertised within the TCP/IP domain. This list is kept in the services file in the /etc directory on UNIX machines. On OS/2, DOS, and Windows, an environment variable points to the directory which contains the services file. The following line must appear in the services file on each machine running or calling ccitcp2:

Servicename:      Port Number/Protocol:

mfcobol           86/udp

This port number is registered with the internet controllers and must appear exactly as shown here. No other services should use this port address.

3.2.8.7.3.1 Manually Configuring CCITCP for DOS

To successfully run CCITCP under DOS, you must first perform these steps:

• Set the following environment variables:

  COBPOOL	Set to a value of at least 4. If COBPOOL is already set, add 4 to the original value.
  CCITCP2	Set to point to the host name of the machine running the ccitcp2 registration process.

• Install VSL support if XM is required, and set the VSL environment variable to point to the directory containing the vsldos.ini file to be used with this installation.

• Select the required CCITCP module by entering the following command from the operating system command line:

      setup cciins

3.2.8.7.3.2 Manually Configuring CCITCP for Windows

To use CCITCP in a Windows environment the configuration file, cci.ini, is required in the Windows initialization directory (the directory that contains the initialization files win.ini, and system.ini).

The cci.ini initialization file should contain the following entries:

[ccitcp-base]
CCITCP2=xxxxxx
NAME=nnnnnnn 

where:

The location of the hosts file varies; refer to your TCP/IP vendors documentation for details.

An example cci.ini initialization file is shown below:

[ccitcp-base]
CCITCP2=RegHost
NAME=myhostname 

If remote execution of the ccitcp2 process is required on a network incorporating several domains, the format of the cci.ini file is:

[ccitcp-base]
CCITCP2=RegHost.domain_name.co.uk
NAME=myhostname

where:

3.2.8.8 CCITCP Data Transfer Speed

TCP/IP is extremely flexible and reliable; TCP/IP connections can be made over RS232, x.25, Token Ring, Arcnet, and Ethernet. However, the penalty for this flexibility is reduced data transfer speed.

The speed with which data is transferred by CCITCP is dependent on various factors including the operating system. In some circumstances, you may find that you can increase data transfer speed by taking some or all of the following actions:

• Increase the bit size of the network card

  An 8-bit card can be at least twice as slow as a 16-bit card. Likewise, a 16-bit card can be at least twice as slow as a 32-bit card. The smaller the data size of the card in use, the longer the main CPU will be interrupted to service the needs of the network devices.

• Increase the cache size of the network card

  Card based storage reduces the load on the host operating system and allows more processing of the data. See the documentation supplied with your hardware card for more information.

• Install the latest optimized drivers for your network card

  Later driver software will generally have better optimization features and will usually make more efficient use of on-card features such as cache buffers.

• Install the latest operating system

  Operating system revisions will generally increase the efficiency and/or reliability of all hardware related features.

  For example, the LLI 1.0 drivers supplied with SCO UNIX version 3.2.2 do not take full advantage of the on-card data cache facilities of wd8003e 8-bit cards. This combination of card/operating system driver can take 40-60% of the available CPU time to service network traffic. The later LLI 1.1 drivers supplied with SCO UNIX version 3.2.4 go some way to solving this problem, as does the use of faster 16-bit network cards.

• TCP/IP links between sessions on the same machine are made via a software device called a "loopback" driver. This is a software device that emulates a network transmission within a single machine. In general, these drivers tend to be slower than direct network access. This is due to the increased system overheads involved in actually running both ends of the communications and the intervening connection software (the loopback driver) on the same machine. When attempting to increase the speed of data transfer between sessions, installing later and better loopback drivers may provide some benefit. In this specific case, where there is no hardware driven control of the data throughput, the base speed of the processing machine itself is a critical factor.

Communications Programming with CCI

CCILU2 Communications Module States