| Common Communications Interface | Configuring TCP/IP and the VSL for DOS and Windows | |
This chapter documents, for the CCILU2 communications module, the conversation states which can result from each CCI function call. It also describes how asynchronous calls are validated and lists those error codes which are specific to CCILU2.
CCILU2 enforces states, that is, a CCI-Query or CCI-Wait function must be called for each outstanding asynchronous CCI request which changes state. If you do not call CCI-Query or CCI-Wait for this purpose, an INVALID-REQUEST error (RETURN-CODE 10) is returned.
Asynchronous calls are validated to ensure that the same CCI function cannot be called with the same async parameter value during any one session. For example:
| Valid |
Invalid |
|---|---|
CCI-Send (async-1) |
CCI-Send (async-1) |
The following error codes may be generated by the CCILU2 module. These are in addition to the error codes documented in the chapter Common Communications Interface.
| 51 or 12 | Status error. |
| 52 or 13 | Invalid async parameter. |
| 53 or 14 | The async parameter is currently in use by another call in this process. |
| 54 or 15 | Invalid server handle. |
| 55 or 16 | Invalid session identifier (this may be the same as error 07 described in the chapter Common Communications Interface). |
When a RETURN-CODE which is not 0 or -1 is received by the calling program, you can use the CCI-Geterror function to obtain additional information about the error.
CCI-Geterror does not change the conversation state.
CCI-Geterror issues a RETURN-CODE value of 2 if the value of maxlen
is smaller than the length of the available text. You can treat this as a
warning because actuallen contains the length of the
available text. If you do get this error, you can issue another call with
a larger maxlen value to retrieve all the text. If no
additional information is available, the value of actuallen
is 0.
The following conversation states are used for CCILU2:
| State 1 | Session not allocated. |
| State 2 | Session allocated. |
| State 3 | Send. |
| State 4 | Receive pending. |
| State 5 | N/A (Receiver issues confirmation). |
| State 7 | N/A (Receiver takes syncpoint). |
| State 8 | N/A (Receiver takes rollback). |
| State 9 | Free pending. |
| State 10 | Free session. |
The following tables show the CCI functions, the return code values which are normally returned when the function is processed and the resulting conversation state. The tables also give the conversation state for the function if it does not return one of the given return codes.
| Commands you can enter | RETURN-CODE values | New State |
| CCI-Initclient* (CCI-Query or CCI-Wait) |
1, 6, 9, 10, 11 | 1 |
| Otherwise | 2 | |
| CCI-Initserver* (CCI-Query or CCI-Wait) |
4, 5, 6, 9, 10, 11 | 1 |
| Otherwise | 2 |
| * | If you want your program to wait until the command is
completed,. specify "by value 0 size 4" in place of "by
reference async" and do NOT use the CCI-Query or CCI-Wait commands. |
| If you want control returned to your program before the function is completed, specify "by reference async" and use CCI-Query to determine if and when the command is complete or use CCI-Wait to wait for the command to complete. |
When using CCI-Initclient and a machinename (other
than NULL-x, where x is a 3270 short session identifier),
a VTAM logon command of the form:
LOGON APPLID(machinename
will be issued on each available 3270 session. A call to the Customer Logon Exit is made with the results of each logon. This exit will have to process the resulting presentation space (terminal buffer) and return to CCILU2. CCILU2 then either indicates a key to press, continues processing or reports a failure to the client workstation.
If NULL-x is specified, CCILU2 connects to the session specified by x and calls Customer Logon Exit for further processing.
If machinename is blank (spaces), connection is
not made to any 3270 session. However, a call to the Client Logon Exit is
made for further processing.
| Commands you can enter | RETURN-CODE Value | New State |
| CCI-Resumeclient* (CCI-Query or CCI-Wait) |
1, 3, 7, 9, 10, 11 | 9 |
| Otherwise | 3 | |
| CCI-Closeclient | 0, 3, 7, 9, 10, 11 | 1 |
| CCI-Connect* [Server only] (CCI-Query or CCI-Wait) |
9, 10, 11 | 10 |
| Otherwise | 4 | |
| CCI-Receivall* [Server only] (CCI-Query or CCI-Wait) (data has been received when this command has completed) |
1, 2, 7, 8, 9, 10, 11 | 9 |
| Otherwise | 5 | |
| CCI-Closeserver | 0, 3, 7, 9, 10, 11 | 1 |
* see note on State 1
| Commands you can enter | RETURN-CODE Value | New State |
| CCI-Send* (CCI-Query or CCI-Wait) |
0, 3, 7, 9, 10, 11 | 3 |
| CCI-Receive* (CCI-Query or CCI-Wait) |
0, 1, 2, 3, 7, 8, 9, 10, 11 | 5 |
| CCI-Transact | 0, 1, 2, 3, 7, 8, 9, 10, 11 | 5 |
| CCI-Suspendclient | 0, 3, 7, 9, 10, 11 | 9 |
| CCI-Suspendserver | 0, 3, 7, 9, 10, 11 | 9 |
* see note on State 1
| Commands you can enter | RETURN-CODE Value | New State |
| CCI-Resumeserver* (CCI-Query or CCI-Wait) |
3, 7, 9, 10, 11 | 9 |
| Otherwise | 5 | |
| CCI-Hangup [Server only] | 0, 3, 7, 9, 10, 11 | 10 |
* see note on State 1
| Commands you can enter | RETURN-CODE Value | New State |
| CCI-Receive* (CCI-Query or CCI-Wait) |
0, 1, 2, 3, 7, 8, 9, 10, 11 | 5 |
| CCI-Send* (CCI-Query or CCI-Wait) |
0, 3, 7, 9, 10, 11 | 3 |
| CCI-Transact | 0, 1, 2, 3, 7, 8, 9, 10, 11 | 5 |
| CCI-Suspendclient | 0, 3, 7, 9, 10, 11 | 9 |
| CCI-Suspendserver | 0, 3, 7, 9, 10, 11 | 9 |
* see note on State 1
| Commands you can enter | RETURN-CODE Value | New State |
| Not applicable within CCILU2 | -- | - |
| Commands you can enter | RETURN-CODE Value | New State |
| Not applicable within CCILU2 | -- | - |
| Commands you can enter | RETURN-CODE Value | New State |
| Not applicable within CCILU2 | -- | - |
| Commands you can enter | RETURN-CODE Value | New State |
| CCI-Resumeclient* (CCI-Query or CCI-Wait) |
1, 3, 7, 9, 10, 11 | 9 |
| Otherwise | 3 | |
| CCI-Closeclient | 0, 3, 7, 9, 10, 11 | 1 |
| CCI-Resumeserver* (CCI-Query or CCI-Wait) |
3, 7, 9, 10, 11 | 9 |
| Otherwise | 5 | |
| CCI-Receiveall* [Server only] (CCI-Query or CCI-Wait) (data has been received when this command has completed) |
1, 2, 7, 8, 9, 10, 11 | 9 |
| Otherwise | 5 | |
| CCI-Hangup [Server only] | 0, 3, 7, 9, 10, 11 | 10 |
* see note on State 1
| Commands you can enter | RETURN-CODE Value | New State |
| CCI-Closeserver | 0, 3, 7, 9, 10, 11 | 1 |
The following table is a quick reference of states and CCI functions. The boxes containing dashes indicate that the function cannot be issued in this state.
You can use the table in several ways:
| State vs Command cross reference table | Not Allocated | Allocated |
Send |
Receive Pending |
Receive |
Free Pending |
Free Session |
| 1 | 2 | 3 | 4 | 5 | 9 | 10 | |
| CCI-Closeclient | - | 1 | - | - | - | 1 | - |
| CCI-Closeserver | - | 1 | - | , | |||
| CCI-Connect | - | 4 | - | , | |||
| CCI-Geterror | 1 | 2 | 3 | 4 | 5 | 9, | |
| CCI-Hangup | - | - | - | , | |||
| CCI-Initclient | 2 | - | - | , | |||
| CCI-Initserver | - | - | , | ||||
| CCI-Query | * | * | * | * | * | * | * |
| CCI-Receive | - | - | , | ||||
| CCI-Receiveall | - | - | , | ||||
| CCI-Resumeclient | - | - | , | ||||
| CCI-Resumeserver | - | - | - | , | |||
| CCI-Send | - | - | 3 | , | |||
| CCI-Suspendclient | - | - | 9 | , | |||
| CCI-Suspendserver | - | - | 9 | , | |||
| CCI-Transact | - | - | 5 | , | |||
| CCI-Wait | * | * | * | * | * | * | * |
* CCI-Query and CCI-Wait result in the state of the command being checked.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Common Communications Interface | Configuring TCP/IP and the VSL for DOS and Windows | |