Advanced Control Capabilities
The controlled interface is used to conduct an APPC conversation without automatic state switching. This is one in which your ESL APPC program must explicitly request to receive and to send data. Using the controlled interface, your program must also handle all error recovery for APPC system errors. All ESL APPC subroutines can be used in both the automatic interface and the controlled interface with the exception of APPCReceiveNotify. This subroutine is used only in the controlled interface.
There are three basic conversation states that you need to understand in order to use the controlled interface: receive, send, and confirm. For an introduction to the automatic interface, see The Automatic Interface. The three conversation states are also briefly described in this section.
Knowledge of ESL APPC event notifications is assumed for the following discussion. For an introduction to event notifications, see ESL APPC Events.
Receive State
Your ESL APPC program indicates that it will use the controlled interface at conversation startup, by calling either APPCStart or APPCAcceptStart with the value for the STATE_SWITCH parameter set to APPC_Controlled. Once the conversation has begun, your program must keep track of the conversation state it is in, and explicitly control all switches in state. APPC errors result if a subroutine is called in the wrong state. No attempt is made by ESL APPC to recover from APPC system errors; errors are simply signalled to your program as APPC_SystemError events. The rest of this discussion assumes that all subroutine calls complete without error.
In Receive state, your program is allowed to use the conversation to retrieve data and status information. To get the conversation into Receive state, your program must issue one of the following calls:
•APPCAcceptStart (to initialize the conversation)
•APPCReceiveNotify (to request data and/or status)
•APPCReadyToReceive
•APPCSendString (with the value for the MORE_TO_SEND argument set to APPC_ReadyToReceive)
Once in receive state, your program calls APPCReceiveNotify to request additional data or status notifications. One call to APPCReceiveNotify can generate one or more notifications. APPC_Data, APPC_ConfirmRequest, and APPC_SendState event notifications may all be sent to your program as a result of one call to APPCReceiveNotify.
Event notifications are grouped, so you can determine when to issue the next call to APPCReceiveNotify. The APPC_InputReceived notification arrives at your program first, followed by data or status notifications, and trailed by an APPC_EndReceive notification. An ESL response block designed to take advantage of this sequence is shown later in this section.
The event notifications APPC_InputReceived and APPC_EndReceive bracket event notifications associated with one APPC receive verb or receive notify request, namely:
APPC_Data
APPC_ConfirmRequest
APPC_Ended
APPC_ReceiveError
APPC_SendError
APPC_SystemError
APPC_RequestToSend
Event notifications that can occur independently of the APPC_InputReceived and APPC_EndReceive signals are:
APPC_Started
APPC_Ended
APPC_Confirmed
APPC_ReceiveError
APPC_SendError
APPC_SystemError
APPC_RequestToSend
In receive state, your program can call:
•APPC SendConfirmed
•APPCReceiveNotify (which should be called every time an APPC_EndReceive event is signalled, as long as more data or status information is still wanted)
•APPCSendError (to indicate a problem receiving data. This call changes the conversation state to send.)
•APPCRequestToSend
•APPCEnd (when APPC_Abend is specified)
Typical Event Notification Sequence
# Start of input
response to stimulus APPC_EVENT APPC_InputReceived
begin ProcessInput
response to stimulus APPC_EVENT APPC_Data
call APPCGetString(....) # Get data
# Process it
. . .
response to stimulus APPC_EVENT APPC_ConfirmRequest
if (Process = "OK") then
call APPCSendConfirmed(....)
else
call APPCSendError(....) # Send error
# indication
call APPCSendString(....)# With
# APPC_ReadyToReceive
end if # Give reason for
# error
response to stimulus APPC_EVENT APPC_SendState
copy "Send" to State
call APPCSendString(....)
call APPCSendString(....) # With APPC_Confirm
response to stimulus APPC_EVENT APPC_RequestToSend
copy "Receive" to State
# Partner sent error
response to stimulus APPC_EVENT APPC_ReceiveError
copy "Receive" to State
copy "ReDo" to Process
# Partner sent error
response to stimulus APPC_EVENT APPC_SendError
copy "Receive" to State
copy "Error" to Process
response to stimulus APPC_EVENT APPC_SystemError
. . .
response to stimulus APPC_EVENT APPC_Ended
if (Process ="OK") then
call APPCEnd(....)
end if
# End of input
response to stimulus APPC_EVENT APPC_EndReceive
if (State = "Receive") then
call APPCReceiveNotify(....) # Request more data
end if
leave block
end ProcessInput
Send State
In send state, your program has send authority; it is allowed to use the conversation to send data. To get the conversation into send state, your program must issue one of the following calls:
•APPCStart (to initialize the conversation)
•APPCRequestToSend (to request send state from the partner. This call must be followed by APPCReceiveNotify calls until the APPC_SendState notification is received.)
•APPCSendError (to indicate a problem with the data that was received)
Once the conversation is in send state, your program may issue the following calls:
APPCSendString
APPCFlush
APPCRequestConfirm
APPCReceiveNotify
APPCTestReqToSend
APPCEnd
APPCSendError (to indicate a problem producing the data to be sent)
Confirm State
A request for confirmation from your partner program causes the conversation to go into confirm state. Your program can recognize that the conversation has gone into confirm state when it gets an APPC_ConfirmRequest event notification. The partner will wait to receive a confirmation or an error response from your program. The only subroutines valid for your program to call when the conversation is in confirm state are APPCSendConfirmed and APPCSendError.
The Controlled Interface Subroutines
Three subroutines are used primarily with the controlled interface: APPCReceiveNotify, APPCRequestToSend, and APPCTestReqToSend. These three subroutines, plus all the other ESL APPC subroutines together, make up the ESL APPC controlled interface.
Subroutines to Switch Conversation State
The following are the subroutines for switching conversation state:
call APPCReceiveNotify ( CONVERSATION_ID )
call APPCRequestToSend ( CONVERSATION_ID )
call APPCTestReqToSend ( CONVERSATION_ID )
