This section provides examples of programs using the CPI Communications starter-set calls:
Figure 10 shows an example of a conversation where the flow of data is in only one direction.
The steps shown in Figure 10 are:
| Step | Description |
|---|---|
| (1) |
To communicate with its partner program, Program A must first establish
a conversation.
Program A uses the Initialize_Conversation call to tell CPI Communications
that it wants to:
Upon successful completion of the Initialize_Conversation call,
CPI Communications assigns a conversation_ID and returns it to Program A.
The program must store
the conversation_ID and use it on all
subsequent calls intended for that conversation.
|
| (2) |
No errors were found on the Initialize_Conversation call,
and the return_code is set to CM_OK.
Two major tasks are now accomplished:
|
| (3) |
Program A asks that a conversation be started with
an Allocate call
(see Allocate (CMALLC)) using the
conversation_ID previously
assigned by the Initialize_Conversation call.
|
| (4) |
If a
logical connection
between the systems is not already available,
one is activated.
Program A and Program C can now have a conversation.
|
| (5) |
A return_code of CM_OK indicates that
the Allocate call was successful and the system has allocated the
necessary resources to the program for its conversation.
Program A's conversation is now in Send state and
Program A can begin to send data.
Note: In this example, the error conditions that can arise (such as no
logical connections
available) are not discussed.
See Allocate (CMALLC) for
more information about the error conditions that can result.
|
| (6) and (7) |
Program A sends data with the Send_Data call
(described in Send_Data (CMSEND)) and receives a
return_code of CM_OK.
Until now, the conversation may not have been established because
the conversation startup request may not be sent until the
first flow of data.
In fact, any number of Send_Data calls can be issued before
CPI Communications actually has a full buffer, which causes it to send the
startup request and data.
Step (6) shows a case where the amount of data sent by
the first Send_Data is greater than the size of the
local system's send buffer (a
system-dependent property), which is one of the conditions that
triggers the sending of data.
The request for a conversation is sent at this time.
Notes:
For a complete discussion of transmission conditions and how to
ensure the immediate establishment of a conversation and transmission
of data, see "Data Buffering and Transmission".
|
| (8) and (9) |
Once the conversation is established, the remote
program's system takes care of starting Program C.
The conversation on Program C's side is
in Reset state and Program C
issues a call to Accept_Conversation,
which places the conversation into Receive state.
The Accept_Conversation call is similar to the
Initialize_Conversation call
in that it equates a conversation_ID with a
set of conversation characteristics (see Accept_Conversation (CMACCP) for
details).
Program C, like Program A in Step (2),
receives a unique conversation_ID
that it will use in all future
CPI Communications calls for that particular conversation.
As discussed
in "Conversation Characteristics", some of Program C's defaults are
based on information contained in the conversation startup request.
|
| (10) and (11) |
Once its end of the conversation is
in Receive state, Program C begins whatever
processing role it and Program A have agreed upon.
In this case,
Program C accepts data with a Receive call
(as described in Receive (CMRCV)).
Program A could continue to make Send_Data calls (and Program C
could continue to make
Receive calls), but, for the purposes of this example,
assume that Program A only wanted to send the
data contained in its initial Send_Data call.
|
| (12) |
Program A issues a Deallocate call (see Deallocate (CMDEAL)) to
send any data buffered in the local system and
release the conversation.
Program C issues a final Receive,
shown here in the same step as the Deallocate, to check that it
has all the received data.
|
| (13) and (14) |
The return_code of
CM_DEALLOCATED_NORMAL tells Program C that
the conversation is deallocated.
Both Program C and Program A finish normally.
Note: Only one program should issue Deallocate; in this case it was
Program A.
If Program C had issued Deallocate after receiving
CM_DEALLOCATED_NORMAL, an error would have resulted.
|
Figure 10. Data Flow in One Direction
System X System Y
*-------------------------------* *-------------------------------*
| *-------* *--------------* | | *--------------* *-------* |
| |Program| | CPI | *---------------------------* | CPI | |Program| |
| | A | |Communications| | | |Communications| | C | |
| *.------* *-------------.* | | *.-------------* *------.* |
*--.-------------------------.--* *--.-------------------------.--*
. . . .
Initialize_Conversation (sym_dest_name) . .
(1) .*----------------------->. . .
conversation_ID, return_code=CM_OK . .
(2) .<-----------------------*. . .
. . . .
.Allocate(conversation_ID). . .
(3) .*----------------------->. Logical connection setup, . .
. . if logical connection . .
. . not already available . .
(4) . .<------------------------------->. .
. return_code=CM_OK . . .
(5) .<-----------------------*. . .
. . . .
.Send_Data(conversation_ID, conversation startup request, . .
. data) . data . .
(6) .*----------------------->.*------------------------------->. .
. return_code=CM_OK . . .
(7) .<------------------------. .(Program C is started by .
. . . node services) .
. . . .
. . . Accept_Conversation .
(8) . . .<-----------------------*.
. . conversation_ID, return_code=CM_OK
(9) . . .*----------------------->.
. . . .
. . . Receive(conversation_ID).
(10). . .<-----------------------*.
. . . data, return_code=CM_OK .
(11). . .*----------------------->.
. . remainder of data, . .
.Deallocate(conversation_ID) conversation end . Receive(conversation_ID).
(12).------------------------>.-------------------------------->.<-----------------------*.
. return_code=CM_OK . . data, .
(13).<------------------------. return_code=CM_DEALLOCATED_NORMAL
. . .*----------------------->.
. . . .
. . . .
(14). (Program A completes . . (Program C completes .
. normally) . . normally) .
. . . .
. . . .
Figure 11 shows a conversation in which the flow of data is in both directions. It describes how two programs using starter-set calls can initiate a change of control over who is sending the data.
The steps shown in Figure 11 are:
| Step | Description |
|---|---|
| (1) through (4) |
Program A is sending data and Program C is receiving data.
Note: The conversation in this example is already established with the
default characteristics.
Program A's end of the conversation is in Send
state, and Program C's is in Receive state.
|
| (5) |
After sending some amount of data (an indeterminate number of
Send_Data calls),
Program A issues the Receive call while
its end of the conversation is
in Send state.
As described in Receive (CMRCV),
this call causes the remaining data buffered at System X
to be sent and permission to send to be given to Program C.
Program A's
end of the conversation
is placed in Receive state, and
Program A
waits for a response from Program C.
Note: See "Example 3: The Sending Program Changes the Data Flow Direction" for alternate methods that allow Program A to continue processing.
Program C issues a Receive call in the same way it issued the two
prior Receive calls.
|
| (6) |
Program C receives not only the
last of the data from Program A, but also a
status_received parameter
set to CM_SEND_RECEIVED.
The value of CM_SEND_RECEIVED notifies Program C that
its end of the
conversation is now in Send state.
|
| (7) |
As a result of the status_received value,
Program C issues a Send_Data call.
The data from this call, on
arrival at System X, is returned to Program A as a response to the
Receive it issued in Step (5).
At this point, the flow of data has been completely reversed and the two programs can continue whatever processing their logic dictates.
To give control of the conversation back to Program A, Program C
would simply follow the same procedure that Program A executed in
Step(5).
|
| (8) through (10) |
Programs A and C continue processing.
Program C sends data and Program A receives the data.
|
Figure 11. Data Flow in Both Directions
System X System Y
*-------------------------------* *-------------------------------*
| *-------* *--------------* | | *--------------* *-------* |
| |Program| | CPI | *---------------------------* | CPI | |Program| |
| | A | |Communications| | | |Communications| | C | |
| *.------* *-------------.* | | *.-------------* *------.* |
*--.-------------------------.--* *--.-------------------------.--*
. . Programs A and C are in . .
. . conversation . .
. . . .
.Send_Data(conversation_ID, data) data . Receive(conversation_ID).
(1) .*----------------------->.-------------------------------->.<------------------------.
. return_code=CM_OK . . data, return_code=CM_OK .
(2) .<-----------------------*. .------------------------>.
. . . .
.Send_Data(conversation_ID, data) data . Receive(conversation_ID).
(3) .*----------------------->.-------------------------------->.<------------------------.
. return_code=CM_OK . . data, return_code=CM_OK .
(4) .<-----------------------*. .------------------------>.
. . permission to send, . .
. Receive(conversation_ID). remainder of data, if any . Receive(conversation_ID).
(5) .------------------------>.-------------------------------->.<-----------------------*.
. (Program A waits for . . data, .
. data from C) . status_received=CM_SEND_RECEIVED
(6) . . .*----------------------->.
. . . .
. data, return_code=CM_OK . data Send_Data(conversation_ID, data)
(7) .<------------------------.<--------------------------------.<-----------------------*.
. . . return_code=CM_OK .
(8) . . .*----------------------->.
. . . .
. Receive(conversation_ID). data Send_Data(conversation_ID, data)
(9) .------------------------>.<--------------------------------.<-----------------------*.
. data, return_code=CM_OK . . return_code=CM_OK .
(10).<------------------------. .*----------------------->.
. . . .
. (further processing by both programs) .
. . . .