Configuring TCP/IP and the VSL for DOS and Windows

Client/Server Binding

Chapter 6: Calling CCI Functions by Value

The CCI Call Interface using the Pascal Call Convention (Call-Convention 3) used by earlier versions of CCI, is maintained for backward compatibility, and is described in this chapter. If you are writing new calls to CCI, you should ignore this chapter and use the Call Interface described in the chapter Common Communications Interface.

If you have applications coded using the older style call interface documented in this chapter, you can still use the new style functions documented in the chapter Common Communications Interface (these functions were added to CCI in V3.1 of this COBOL system). You can use the new CCI API calls without having to recode any of the other functions.

6.1 CCI Functions

This section lists and describes the available CCI functions in alphabetical order.

CCI-Closeclient

call api CCI-Closeclient using by value sessid

where:

sessid is a PIC X(4) COMP-5 parameter containing the session identifier.

The routine uses the session handle sessid (returned by a previous CCI-Initclient call) to request the disconnection of the client workstation from the server workstation. A CCI-Hangup call needs to be made at the server workstation to allow the disconnect to take place. The request is performed synchronously. This call cancels any outstanding asynchronous requests which had been made for this connection.

CCI-Closeserver

call api CCI-Closeserver using by value srvrhandle

where:

srvrhandle is a PIC X(4) COMP-5 parameter containing the server handle.

The routine uses the server handle srvrhandle returned by a previous CCI-Initserver call to request the termination of a server. No matching call needs to be made at the client workstations. The request is performed synchronously. This call logically terminates any sessions currently connected to this server.

CCI-Connect

call api CCI-Connect using by value srvrhandle
                           by reference sessid
                           by reference async
                           by value 0 size 4 unused

where:

`srvrhandle`	is a PIC X(4) COMP-5 parameter containing the server handle.
`sessid`	is a PIC X(4) COMP-5 parameter containing the returned session identifier.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine establishes a connection between a server workstation and a client. The server is identified by the 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

call api CCI-Geterror using by reference buffer
                            by value maxlen
                            by reference actuallen

where:

`buffer`	is a PIC X(n) parameter containing the returned extended error message.
`maxlen`	is a PIC X(4) COMP-5 parameter containing the maximum length of `buffer`.
`actuallen`	is a PIC X(4) COMP-5 parameter containing the returned length of the error message.

This routine returns an error message for the last reported error. 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

call api CCI-Hangup using by value sessid

where:

sessid is a PIC X(4) COMP-5 parameter containing the session identifier.

The routine uses the session handle sessid returned by a previous CCI-Connect or CCI-Receiveall call to request the disconnection of the server workstation from the client workstation. 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 had been made for this connection.

CCI-Initclient

call api CCI-Initclient using by reference publicname
                              by reference machinename
                              by reference sessid
                              by reference async
                              by value 0 size 4 unused

where:

`publicname`	is a PIC X(n) parameter containing the name of the server to connect to.
`machinename`	is a PIC X(n) parameter containing the machine identifier of server workstation.
`sessid`	is a PIC X(4) COMP-5 parameter containing the returned session identifier.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine establishes a connection between a client workstation and a server. The server is identified by publicname and machinename (see the chapter Common Communications Interface 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

call api CCI-Initserver using by reference publicname
                              by reference srvrhandle
                              by value 0 size 4 unused

where:

`publicname`	is a PIC X(n) parameter containing the name of server to initialize.
`srvrhandle`	is a PIC X(4) COMP-5 parameter containing the server handle.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine initializes a workstation as a server using the name specified in publicname (see the chapter Common Communications Interface earlier in this manual for details of what needs to be specified). Following a successful initialization, a server handle is returned in srvrhandle. The request is performed synchronously.

If the value in the return code is 4 (name clash local), this means that communications have been set up using a server name that has already been defined. Any other non-zero return code indicates failure.

CCI-Query

call api CCI-Query using by value async

where:

async is a PIC X(4) COMP-5 parameter containing the asynchronous request handle.

This routine is used to determine whether an asynchronous request has completed. Asynchronous requests may have been established using the CCI-Connect, CCI-Initclient, CCI-Receive, 4all, and CCI-SEND calls. If the request has not completed, this routine passes back a return code of -1. If the request has completed, this routine passes back the request's completion code as the 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. 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) programs, you should fix your programs' Data Divisions in memory using sub-function 60 of COBOL system library routine x"91". Otherwise your Data Divisions may be relocated while CCI is in the middle of an asynchronous operation that is returning data to your program.

CCI-Receive

call api CCI-Receive using by value sessid
                           by reference buffer
                           by value maxlen
                           by reference actuallen
                           by reference async
                           by value 0 size 4 unused

where:

`sessid`	is a PIC X(4) COMP-5 parameter containing the session identifier.
`buffer`	is a PIC X(n) parameter containing the buffer in which to receive the message.
`maxlen`	is a PIC X(4) COMP-5 parameter containing the maximum length of `buffer`.
`actuallen`	is a PIC X(4) COMP-5 parameter containing the returned length of message written to `buffer`.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine receives a message from the workstation identified by sessid. A CCI-Send or CCI-Transact call needs to have been made at the client 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

call api CCI-Receiveall using by value srvrhandle
                              by reference sessid
                              by reference buffer
                              by value maxlen
                              by reference actuallen
                              by reference async
                              by value 0 size 4 unused

where:

`srvrhandle`	is a PIC X(4) COMP-5 parameter containing the server handle.
`sessid`	is a PIC X(4) COMP-5 parameter containing the session identifier.
`buffer`	is a PIC X(n) parameter containing the buffer in which to receive the message.
`maxlen`	is a PIC X(4) COMP-5 parameter containing the maximum length of `buffer`.
`actuallen`	is a PIC X(4) COMP-5 parameter containing the returned length of message written to `buffer`.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine reads a message from any client targeted at the server 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 will also connect 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 a Connected and Resumeservered state. CCI-Resumeserver should not therefore be called before the next CCI-Receive, CCI-Receiveall, CCI-Send, or CCI-Transact.

CCI-Resumeclient

call api CCI-Resumeclient using by value sessid
                             by reference async
                             by value 0 size 4 unused

where the parameters are:

`sessid`	is a PIC X(4) COMP-5 parameter containing the session identifier.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine prepares a connection between a client workstation and server for use. 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

call api CCI-Resumeserver using by value  sessid
                             by reference async
                             by value 0 size 4 unused

where:

`sessid`	is a PIC X(4) COMP-5 parameter containing the session identifier.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine prepares a connection between a server workstation and client for use. 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 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

call api CCI-Send using by value sessid
                        by reference buffer
                        by value sendlen
                        by reference async
                        by value 0 size 4 unused

where:

`sessid`	is a PIC X(4) COMP-5 parameter containing the session identifier.
`buffer`	is a PIC X(n) parameter containing the message to send.
`sendlen`	is a PIC X(4) COMP-5 parameter containing the length of data to be sent from `buffer`.
`async`	is a PIC X(4) COMP-5 parameter containing the returned asynchronous request handle. This parameter can be replaced by a BY VALUE 0 SIZE 4 parameter to indicate a synchronous request.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

This routine sends a message to the workstation 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

call api CCI-Suspendclient using by value sessid

where:

sessid is a PIC X(4) COMP-5 parameter containing the session identifier.

This routine suspends a connection between a client workstation and a server. 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

call api CCI-Suspendserver using by value sessid

where:

sessid is a PIC X(4) COMP-5 parameter containing the session identifier.

This routine suspends a connection between a server workstation and a client. 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)

call api CCI-Timeout using by reference time-period 
                           by value 0 size 4

where:

time-period is a PIC X(4) COMP-5 parameter containing the new timeout value in 1/10th of a second.

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

This function is only available with CCI modules supporting CCI Version 3 and later.

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 4 seconds.

CCI-Trace

call CCI-Trace using by value toggle 
                     by reference control-buffer
                     by value 0 size 4

where:

toggle

is a PIC X(4) COMP-5 parameter containing one of the following values:

1	Enable trace output
0	Disable trace output

control-buffer

is a PIC X(n) parameter containing a control information sequence describing which format the trace is to take. n is the number of bytes large enough to incorporate the text string plus its terminating 0. control-buffer can be one of the following options, which must be uppercase:

/B or -B logs the status of CCI functions before execution. When B is specified, all parameters are logged to the disk file. The default condition for this option is ON unless /A or -A is specified.

/D or -D logs the contents of all buffers passed to and from the CCI functions. The default condition for this option is OFF.

See the chapter Communications Programming with CCI for more information on how to trace the execution path of a CCI application.

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.

CCI-Transact

call api CCI-Transact using by value sessid
                            by reference buffer
                            by value sendlen
                            by value maxlen
                            by reference actuallen
                            by value 0 size 4 unused

where:

`sessid`	is a PIC X(4) COMP-5 parameter containing the session identifier.
`buffer`	is a PIC X(n) parameter containing the buffer in which to receive the message.
`sendlen`	is a PIC X(4) COMP-5 parameter containing the length of data to be sent from `buffer`.
`maxlen`	is a PIC X(4) COMP-5 parameter containing maximum length of `buffer`.
`actuallen`	is a PIC X(4) COMP-5 parameter containing the returned length of message written to `buffer`.
`unused`	is a PIC X(4) COMP-5 VALUE 0 parameter which is reserved for future use.

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

CCI-Wait

call api CCI-Wait using by value async

where:

async is a PIC X(4) COMP-5 parameter containing the asynchronous request handle.

This routine is used to wait until an asynchronous request has completed. Asynchronous requests may have been established using the CCI-Connect, CCI-Initclient, CCI-Receive, CCI-Receiveall, and CCI-Send calls. When the request has completed, this routine will pass back the request's completion code in RETURN-CODE, and cause 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.

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

Configuring TCP/IP and the VSL for DOS and Windows

Client/Server Binding