Here is a simple example of how Program A starts a conversation with Program C:
After issuing their respective Initialize_Conversation and Accept_Conversation calls, both Program A and Program C have a set of default conversation characteristics set up for the conversation. The default values established by CPI Communications are discussed in "Conversation Characteristics".
In the previous example, Program A established a single conversation with a single partner, but CPI Communications allows a program to communicate with multiple partners using multiple, concurrent conversations:
Specific combinations of outbound and inbound conversations are determined by application design. The sections that follow discuss in greater detail the concepts required for multiple conversations.
After a program issues Initialize_Conversation to establish its conversation characteristics, a name for its partner program (the TP_Name) is established. This name is transmitted to the remote system in the conversation startup request after the program issues the Allocate call.
At the remote system, the partner program can be started in one of two ways:
In the first case, node services starts the program named in the conversation startup request. However, if a program is started locally, the program must notify node services of its ability to accept conversations for a given name. The program associates a name with itself by issuing the Specify_Local_TP_Name call. The program can release a name from association with itself by issuing the Release_Local_TP_Name call.
To accept multiple conversations for different names, the program issues multiple Specify_Local_TP_Name calls, thus associating multiple names with itself.
Note: A locally-started program cannot accept conversations until a name has been associated with the program.
Figure 6 shows Program A establishing conversations with two partners. For example, a program may need to request data from multiple data bases on different nodes to answer a particular query. The conversation with Program B is initialized with an Initialize_Conversation (CMINIT) call that returns a conversation_ID parameter of X. The conversation with Program C is initialized with an Initialize_Conversation call that returns a conversation_ID parameter of Y. When Program A issues subsequent calls with a conversation_ID of X, CPI Communications will know these calls apply to the conversation with Program B. Similarly, when Program A issues subsequent calls with a conversation_ID of Y, CPI Communications will know these calls apply to the conversation with Program C.
Figure 6. A Program Using Multiple Outbound CPI Communications Conversations
Note: In some implementing environments, Program A can share the conversation_ID with another task, allowing that task to issue calls on the conversation with Program C.
Some programs, often referred to as server programs, may need to accept more than one inbound conversation. For example, a server could accept conversations from multiple partners in order to work on the request from one partner while waiting for a second partner's request or work to complete.
This type of application is shown in Figure 7, where Programs D and E have both chosen to initiate conversations with the same partner, Program S.
Figure 7. A Program Using Multiple Inbound CPI Communications Conversations
In the simplest case, Program S can accept the two conversations by issuing Accept_Conversation twice. Alternatively, Program S may make use of two advanced calls, Initialize_For_Incoming and Accept_Incoming.
Note: A program would use the advanced calls to achieve greater programming flexibility. See "Non-Blocking Operations" for a more detailed discussion. See "Example 12: Accepting Multiple Conversations Using Blocking Calls" and "Example 13: Accepting Multiple Conversations Using Conversation-Level Non-Blocking Calls" for examples using these calls.
Node services provides support for programs that perform work on behalf of multiple partners, such as server Program S in the previous example. Each time a program accepts an incoming conversation, a new context is created. The context is identified by a system-wide context identifier and is used by node services to group logical attributes for the work to be done on behalf of the partner program.
Node services maintains one or more contexts for a program in execution within the node. For each program, there is one distinguished context, the current context, within which work is currently being done. A program can manage different contexts by making calls to node services in order to:
Note: The discussion of contexts throughout this and following sections assumes a context is maintained on a program basis. However, in a system that supports multi-threaded programs, the context may be maintained on a thread basis.
Each conversation is assigned to a context when it is allocated or accepted.
A program can retrieve the context identifier for a conversation's context by issuing the Extract_Conversation_Context call.
The program's current context is set by node services to the newly created context when an Accept_Conversation or Accept_Incoming call completes successfully with return_code set to CM_OK.
Security parameters are among the logical attributes maintained by node services for a context. The access security information carried in the conversation startup request is used to set the security parameters for the context created as a result of an incoming conversation. The security parameters for other contexts are based on security information maintained within the system. See "Conversation Security" for a complete discussion of conversation security.
A program that accepts incoming conversations from multiple program partners must ensure that work is done within the right context. In the expanded server example shown in Figure 8, Program S accepts two conversations, one each from Programs D and E. Two new contexts are created, one for the work done on behalf of Program D and one for the work done on behalf of Program E. Program S can retrieve the context identifier for each conversation by issuing the Extract_Conversation_Context call twice.
Figure 8. Server Program with Both Inbound and Outbound Conversations
Now consider a scenario where Program S is doing work for Program E and receives a request from Program D. The request is for information that Program S does not have. In this case, Program S allocates a conversation to a third partner, Program F, in order to answer Program D's request.
Before allocating the conversation to Program F, Program S must first ensure that it is using the correct context. It does this by setting the current context to that for Program D. This causes the outgoing conversation to be established using information, such as the proper security parameters, from the correct context. "Conversation Security" provides a complete discussion of how the current context is used by node services to establish security parameters for new conversations.
For more information about establishing and managing conversations, see the following sections: