Neda's Implementation of
ESRO - Source
Documentation Applies for:
ESRO-FULL-SRC
ESRO-BASE-SRC
ESRO-TEST-SRC
Neda Document Number: 105-102-06
Last Updated: 2000/03/23 20:37:24
Doc. Revision: 1.1.1.1
Neda Communications, Inc.
January 27, 1999
| IBM is a registered trademark of International Business Machines Corporation. |
| Unix is a trademark of AT&T and Unix System Laboratories. |
| Sun is a registered trademark and Sun Workstation is a trademark of Sun Microsystems, Inc. |
| Windows is a registered trademark of Microsoft Corporation. |
This document provides details on the programming development environment of Neda's source code of ESROS (Efficient Short Remote Operation Services) protocols. It will document the design of the system and the code written to implement those protocols.
The scope of this document is the protocols of Efficient Short Remote Operation Services.
For more information about this document or its contents, please
contact:
Neda Communications, Inc. Phone: +1 425644-8026 Fax: 1+1 425562-9591 E-Mail: info@neda.com
Neda's Implementation of ESRO - Source documents ESRO-FULL-SRC, the portable source code of Neda's Implementation of the Efficient Short Remote Operation Services Protocol. This implementation conforms to "RFC-2188" [2].
ESRO-FULL-SRC consists of the Efficient Short Remote Operations Base (ESROS-BASE-SRC) and Efficient Short Remote Operations Test Tools (ESROS-TEST-SRC). ESRO-FULL-SRC relies on Neda's Open C Platform [1]. Open C Platform and related documentation is supplied separately.
ESRO-BASE-SRC is a relatively complete implementation of the ESROS protocol specification. Complete sources for both invoker and performer sides are implemented. The specific features and options implemented are enumerated in Neda's Protocol Implementation Conformance Statement (PICS). Neda's PICS is included as a part of this documentation in Appendix E.
ESRO-FULL-SRC is provided as portable software which may be ported to a variety of environments. Although a great deal of portation specific code and documentation is included, it is important to note that they are provided only as examples. It is only the portable software which is fully supported and maintained.
This implementation can be configured to be utilized in a complex Message Center, handling extremely high volumes, or in a very small, embedded device whose size and efficiency are of the highest importance.
This document supplies the documentation for the following products:
Some of the documentation may not be pertinent to the reader, but it is included for the sake of completeness.
It is recommended that for this document to be of the most use to the reader, they should be extremely familiar with "RFC-2188" [2] and the Open C Platform [1]. There has been no attempt in this document to re-explain anything previously covered in the Protocol Specifications.
For ease of reference, all citations from Neda source code files are printed in boldface type.
Chapter 1 consists of an introduction to the product, ESRO-FULL-SRC, and the whole document.
Chapter 2 describes the Efficient Short Remote Operation Protocol Engine.
Chapter 3 provides information about the interface to ESROS services.
Chapter 4 describes the design and operation of real-world ESROS programs which have been ported to both Unix and MS-DOS platforms. However, it is important to note that they are provided only as examples. It is only the portable software which is fully supported and maintained.
Chapter 5 describes the testing methodologies and tools used to test an ESROS implementations.
Appendices include a Bibliography, a list of relevant Acronyms, ESROS API Example Usage, ESROS Program Man Pages, Trace Bit Definitions and Neda's Protocol Implementation Conformance Statement (PICS).
ESROS-Daemon is responsible for implementation of ESRO-Protocol ("RFC-2188".[2]) on both invoker and performer sides. ESROS-Daemon exposes the ESROS API (see chapter entitled ESROS API) to its users, the ESROS-User-Daemon and the ESROS-System-Daemon.
The software consists of two files:
esros-full-src.tar includes:
From the installation home directory, type tar -xvf ocpForEsros-svr4.tar, to install the Open C Platform. This is required for ESRO-FULL-SRC, ESRO-BASE-SRC and ESRO-TEST-SRC.
By typing tar -xvf esros-full-src.tar, the ESROS user,provider and test programs will be installed.
A brief description of the directory hierarchy follows:
It is very important to note that all sub directories under "unsupp.*" are not considered part of Neda ESROS products and are supplied as example portations only. Eventhough, many of the example programs are described in some detail in this document, they should not be considered a proper part of ESROS products.
To build this distribution:
source sourceme.csh
And then:
./buildAll.sh
If you don't have gmake, you may have to edit the build scripts.
To run esros example programs refer to the relevant sections of this document.
The ESRO layer operates above the Transport layer and provides services to other application layer entities. It provides remote operation services between application layer entities by relieving them of concern over how the remote operation is achieved.
The Neda ESRO Protocol Engine (ESROP) is the Neda implementation of the ESRO protocol. The ESRO protocol is defined in "RFC-2188" [2].
The Neda ESROP implementation is designed to be independent of the environment to which it will be ported. ESROP software makes minimal assumptions about its target environment.
While this chapter describes how protocol options are implemented and used, it does not attempt to explain the protocol. ESROP interface function calls are modeled after the ESROS service definition,"RFC-2188" [2]. References to concepts defined by the ESRO Protocol Specifications are made throughout the book. We recommend reading the ESRO Protocol Specification documents [2] in conjunction with this document.
ESROP module uses a set of common facilities. These common facilities are described in Open C Platform [1]. We suggest a review of that manual before starting this manual.
The chapter is divided into three basic parts. An overview and concepts of ESROP's functionality can be found in Section 2.2. ESROS Service Primitives are described in Section 2.3. Section 2.4 and Section 2.5 define the upper and lower interface functions, respectively, of ESROP. The environment dependent facilities and network management are discussed in Section 2.6 and Section 2.7. Portation issues and design of ESROP are discussed in Section 2.8 and Section 2.9.
To an ESROP user the ESROP Services offer the means to perform an Operation with another ESROP-User for the purpose of exchanging ESROS Data Units (DU). More than one Operation may be in progress simultaneously between the same pair of ESROP-Users.
ESROP is designed to be independent of the environment to which it will be ported.
ESROP appears to its user as a link module with four defined interfaces. The ESROP module's interfaces are shown Figure 2.1.
The ESROP upper interface is a series of function calls (primitives). Each function call accepts a group of arguments (parameters).
The Neda ESROP upper interface provides the ESROP-User with primitives which match the definitions of ESROS services [1]. Each function call is non-blocking and asynchronous.
ESROP requests and responses, collectively referred to as ESROP action primitives, are function calls to the ESROP software module. ESROP action primitives are invoked by the ESROP-User. The code for ESROP action primitives is provided by the ESROP software module.
ESROP indications and confirmations, collectively referred to as ESROP event primitives, are function calls to the ESROP-User module. ESROP event primitives are invoked by the ESROP software module. The code for ESROP event primitives is expected to be provided by the ESROP-User.
Section 2.4 describes in detail the ESROP upper interface primitives and their parameters.
The lower interface of the ESROP software module matches the upper interface of the Transport software module.
The ESROP lower interface is a series of function calls (primitives). Each function call accepts a group of arguments (parameters).
Neda ESROP lower interface primitives match the ESRO Service definitions [1]. Lower interface function calls are non-blocking and asynchronous.
Transport requests and responses, collectively referred to as Transport action primitives, are function calls to the Transport software module. Transport action primitives are invoked by the ESROP software module. The code for Transport action primitives is expected to be in the Transport software module.
Transport indications and confirmations, collectively referred to as Transport event primitives, are function calls to the ESROP software module. Transport event primitives are invoked by the Transport software module. The code for Transport event primitives is provided in the ESROP software module.
ESROP relies on the availability of a group of facilities for data unit and timer manipulation. A common high-level interface for these facilities is used by the ESROP module. This interface is defined in Open C Platform document, [1] and reviewed later.
A set of counters is locally maintained by the ESROP software module. These counters, which may be used for Network Management, are described later.
This section describes the service primitives provided by the ESROP module, and the constraints on the sequence in which the ESROP primitives may occur. Each ESROP-User interacts with the ESROP module through one or more ESROP-SAPs.
The following is a list of ESRO service primitive names:
The Neda ESROP upper interface conforms to the ESRO Service Definition [1]. The constraints on the sequence in which ESROP primitives may occur are explained in Reference [1].
An ESROP-User must create an ESROP-SAP before it can use any of the services provided by the ESROP module. Creation of an ESROP-SAP is accomplished through the ESROP_sapBind function. Parameters to ESROP_sapBind communicate to the ESROP module both an ESRO-SAP selector address and a set of functions for handling event primitives for that ESROP-SAP. ESROP event primitives are:
Deletion of an ESROP-SAP is accomplished through the ESROP_sapUnbind function. A summary of Neda ESROP-SAP management facilities follows.
|
The sequence of ESROP primitives in an OPERATION is illustrated in the time sequence diagram below.
The ESROS-INVOKE-P.confirm primitive is communicated to the invoker user through the return value/parameter of the ESROP_invokeReq function.
An ESROS-INVOKE.indication event primitive is generated at the performer ESROP entity's ESROP-SAP through the invocation of the (*ESROP_invokeInd)() function associated with the performer ESROP-SAP.
The performer ESROP-User can accept the operation and communicate the results by generating an ESROS-RESULT.request at the ESROP layer interface by invoking the function ESROP_resultReq. The performer ESROP-User can issue an ESROS-ERROR.request by invoking the function ESROP_errorReq.
An ESROS-RESULT.confirm or ESROS-ERROR.confirm event primitive is generated at the performer ESROP entity ESROP-SAP through the invocation of the (*ESROP_resultCnf)() or (*ESROP_errorCnf)() function associated with the performer ESROP-SAP.
An ESROS-RESULT.indication or ESROS-ERROR.indication event primitive is generated at the invoker ESROP entity ESROP-SAP through the invocation of the (*ESROP_resultInd)() or (*ESROP_errorInd)() function associated with the invoker ESROP-SAP.
A summary of all operation primitives appears below in Table 2.3:
|
The OPERATION may fail due to either the inability of the ESROS provider to transmit the INVOKE PDU or the unwillingness of the ESROS performer user to accept an ESROS-INVOKE.indication. These cases are described later in this chapter. The OPERATION may also fail as a result of the failure in delivery of RESULT or ERROR PDU. In such cases an ESROS-FAILURE.indication event primitive is issued at the invoker or performer ESROP-SAP through the invocation of the (*ESROP_failureInd)() function.
The ESROP-User calls ESROP SAP management functions to register or deregister as an ESROS service user.
Int
ESROP_sapBind (ESROP_SapDescsapDesc,
ESROP_SapSelsapSel,
ESROP_FunctionalUnit functionalUnit,
int (*invokeInd)(ESROP_SapSel,
ESROP_SapSel,
T_SapSel */
N_SapAddr */
ESROP_InvokeDesc,
ESROP_OperationValue,
ESROP_EncodingType,
DU_View),
int (*resultInd) (ESROP_InvokeDesc,
ESROP_UserInvokeRef,
ESROP_EncodingType,
DU_View),
int (*errorInd) (ESROP_InvokeDesc,
ESROP_UserInvokeRef,
ESROP_EncodingType,
ESROP_ErrorValue,
DU_View),
int (*resultCnf) (ESROP_InvokeDesc,
ESROP_UserInvokeRef),
int (*errorCnf)( ESROP_InvokeDesc,
ESROP_UserInvokeRef),
int (*failureInd)(ESROP_InvokeDesc,
ESROP_UserInvokeRef,
ESROP_FailureValue))
This function binds an ESROP-User at the ESROP layer by creating an ESROP-SAP.
The sapSel argument specifies the ESROP-SAP Selector Address to be associated with this service user. The ESROP-SAP descriptor value is returned to the caller through sapDesc argument.
The functionalUnit argument specifies the method of handshaking used by the SAP.
The remaining arguments specify the addresses of the callback functions (and their arguments) that the SAP should invoke upon the occurrence of specific events. For instance, invokeInd points to the function that is executed when a performer ESROP receives an invocation.
ESROP_sapBind returns 0 on successful completion. It returns a negative value if unsuccessful.
SuccFail ESROP_sapUnbind(ESROP_SapSel sapSel)
This function unbinds an ESROP-User. If there are any remaining invocations associated with this SAP for that ESROP-User, the pending or in process requests are dropped and if there are any events queued up for this ESROP-User's SAP, they are discarded.
The sapSel argument specifies the ESROP-SAP currently in use by the caller.
This function returns 0 on successful completion. It returns a negative value if unsuccessful.
Int
ESROP_invokeReq(ESROP_InvokeDescinvokeDesc,
ESROP_UserInvokeRefuserInvokeRef,
ESROP_SapSellocESRSap,
ESROP_SapSelremESRSap,
T_SapSel*remTsap,
N_SapAddr*remNsap,
ESROP_OperationValueopValue,
ESROP_EncodingTypeencodingType,
DU_View parameter)
The invoker ESROP-User invokes this function to initiate the invocation of an ESROS operation. The ESROP-User specifies both local and remote ESROP-SAP. The locESROSap argument contains the ESROP-SAP Selector of the invoker, while the remESROSap argument contains the ESROP-SAP of the performer. The remTsap specifies the Transport SAP Selector of the performer and remNsap specifies the Network SAP of the performer. Invoker ESROP-User passes an invocation identifier (userInvokeRef) to the ESROP which is returned to it in all future references to that specific operation.
opValue is the operation value. The invoker ESROP-User can specify its desired encoding type through the encodingType argument. parameter is the operation's parameter.
An invocation descriptor is passed to the caller of the function (invoker ESROP-User) through the invokeDesc argument to be used to identify the ESROS invocation in future references. If ESROP fails in initializing the invocation operation a negative value is returned by the function, otherwise 0 is returned on successful completion of the function call.
Int ESROP_resultReq(ESROP_InvokeDescinvokeDesc, ESROP_UserInvokeRefuserInvokeRef, ESROP_EncodingTypeencodingType, DU_View parameter)
When ESROP performer user accepts an invocation indication, it invokes this function to request transmission of the result of the operation.
invokeDesc is the invocation identifier that was previously obtained through the ESROS-INVOKE.indication primitive on performer-user side. Performer ESROP-User passes the userInvokeRef to ESROP which is returned to it in all future references to the operation. encodingType reflects the encoding type of the parameter. parameter is the operation's parameter.
This function returns 0 on successful completion. If the function is unsuccessful, it returns a negative value.
Int
ESROP_errorReq(ESROP_InvokeDesc invokeDesc,
ESROP_UserInvokeRefuserInvokeRef,
ESROP_EncodingType encodingType,
ESROP_ErrorValue errorValue,
DU_View parameter)
When ESROP performer user accepts an invocation indication, it invokes this function to request transmission of the error response to the invoker of the operation.
invokeDesc is the invocation identifier that was previously obtained through the ESROS-INVOKE.indication primitive on performer-user side. encodingType reflects the encoding type of the parameter. parameter is the operation's parameter.
This function returns 0 on successful completion. If the function is unsuccessful, it returns a negative value.
Int
(*ESROP_invokeInd)(ESROP_SapSellocESROSap,
ESROP_SapSelremESROSap,
T_SapSel **remTsap,
N_SapAddr **remNsap,
ESROP_InvokeDescinvokeDesc,
ESROP_OperationValueoperationValue,
ESROP_EncodingTypeencodingType,
DU_Viewparameter)
The performer ESROP invokes this function to communicate an invoke indication to the ESROP-User. ESROP specifies both the invoker ESROP-SAP Selector and the performer ESROP-SAP Selector.
The remTsap argument contains the Transport SAP Selector of the performer and remNsap specifies the Network SAP of the performer. The encodingType argument specifies the encoding type of the parameter. parameter is the operation's parameter.
This function returns 0 in the case of success and a negative value if unsuccessful.
Int
(*ESROP_resultInd)(ESROP_InvokeDescinvokeDesc,
ESROP_UserInvokeRefuserInvokeRef,
ESROP_EncodingTypeencodingType,
DU_View parameter)
The ESROP invokes this function to communicate to the ESROP-User a result indication.
invokeDesc is the invocation identifier that was previously communicated to the invoker user through ESROS-INVOKE-P.confirm. userInvokeRef is the user's invocation identifier that was passed to ESROP by invoker-user at the time of initiation of ESROS-INVOKE.request. encodingType reflects the encoding type of the parameter used by the performer ESROP-User. parameter is the operation's parameter.
This function returns 0 in the case of success and a negative value if unsuccessful.
Int
(*ESROP_errorInd) (ESROP_InvokeDescinvokeDesc,
ESROP_UserInvokeRefuserInvokeRef,
ESROP_EncodingTypeencodingType,
ESROP_ErrorValueerrorValue,
DU_Viewparameter)
The ESROP invokes this function to communicate to the invoker ESROP-User an error response to its invocation.
invokeDesc is the invocation identifier that was previously communicated to the invoker user through ESROS-INVOKE-P.confirm (ESROP_invokeReq parameter). userInvokeRef is the user's invocation identifier that was passed to ESROP by invoker-user at the time of initiation of ESROS-INVOKE.request. encodingType reflects the encoding type of the parameter used by the performer ESROP-User. parameter is the operation's parameter.
This function returns 0 in the case of success and a negative value if unsuccessful.
Int
(*ESROP_failureInd) (ESROP_InvokeDescinvokeDesc,
ESROP_UserInvokeRefuserInvokeRef,
ESROP_FailureValuefailureValue)
The ESROP invokes this function to communicate to the ESROP-User a failure indication.
invokeDesc is the invocation identifier that was previously communicated to the invoker ESROP-User through ESROS-INVOKE-P.confirm (ESROP_invokeReq parameter) or communicated to the performer ESROP-User through ESROS-INVOKE.indication. userInvokeRef is the user's invocation identifier that was passed to ESROP by invoker-user at the time of initiation of ESROS-INVOKE.request (ESROP_invokeReq) on invoker side or ESROS-RESULT/ERROR.request on performer side.
The failureValue argument specifies the failure reason.
This function returns 0 in the case of success and a negative error value if unsuccessful.
Int
(*ESROP_resultCnf) (ESROP_InvokeDescinvokeDesc,
ESROP_UserInvokeRefuserInvokeRef)
The ESROP invokes this function to communicate the confirmation of the result.
invokeDesc is the invocation identifier that was previously communicated to the performer ESROP-user through ESROS-INVOKE.indication. userInvokeRef is the user's invocation identifier that was passed to ESROP by performer ESROP-User at the time of initiation of ESROS-RESULT.request (ESROP_resultReq).
This function returns 0 in the case of success and a negative value if unsuccessful.
Int
(*ESROP_errorCnf)(ESROP_InvokeDescinvokeDesc,
ESROP_UserInvokeRefuserInvokeRef)
The ESROP invokes this function to communicate the confirmation of the error.
invokeDesc is the invocation identifier that was previously communicated to the performer ESROP-user through ESROS-INVOKE.indication. userInvokeRef is the user's invocation identifier that was passed to ESROP by performer ESROP-User at the time of initiation of ESROS-ERROR.request (ESROP_errorReq).
This function returns 0 in the case of success and a negative value if unsuccessful.
ESROP relies on the connectionless or connection oriented services provided by Transport layer based on the SDU size. The following sections describe the Transport services assumed by ESROP.
UDP_SapDesc
UDP_sapBind (T_SapSelsapSel,
int (*dataInd)(T_SapSel,
N_SapAddr,
T_SapSel,
N_SapAddr,
DU_View))
This function binds the ESROP to the lower layer by creating a UDP-SAP.
The sapSel argument specifies the local T-SAP Selector Address to be associated with this UDP-SAP.
The dataInd argument specifies the callback function that gets executed when the lower layer has data for the ESROP layer.
The UDP-SAP descriptor value is returned to the caller on successful completion. Otherwise a NULL value is returned.
SuccFail UDP_sapUnBind (T_SapSel *sapSel)
This function unbinds an ESROP from the lower layer. If there are any remaining requests associated with this SAP, the pending or in process requests are dropped and if there are any events queued up for this, they are dumped.
The sapSel argument specifies the UDP-SAP currently in use by the caller.
This function returns SUCCESS on successful completion and FAIL if unsuccessful.
SuccFail UDP_dataReq (UDP_SapDesc locSapDesc, T_SapSel *remTsapSel, N_SapAddr *remNsapAddr, DU_View udpSdu)
This function is called by the ESROP layer when it needs to send a TSDU.
The locSapDesc argument identifies the local UDP SAP in use. remTsapSel specifies the destination SAP address. remNsapAddr specifies the Network SAP address of the remote peer. udpSdu is a buffer containing the TSDU.
Int (*dataInd) (T_SapSel *remTsapSel, N_SapAddr *remNsapAddr, T_SapSel *locTsapSel, N_SapAddr *locNsapAddr, DU_View udpSdu))
The UDP layer invokes this function to communicate received SDU's to the UDP user.
remTsapSel specifies the transport SAP address of the remote peer. remNsapAddr specifies the Network SAP address of the remote peer. udpSdu is a buffer containing the TSDU.
Note: locTsapSel and locNsapAddr are reserved for future use. Do not rely on their values.
This section describes the environment dependent facilities used by the ESROP module. The Neda publication, Open C Platform [1], describes these facilities in detail.
ESROP uses all of the data unit management facilities described in Open C Platform [1].
Several counters are locally maintained to be used for Network Management in each ESROP entity (see Table 2.4).
|
This section describes some of the more important points which should be considered when porting ESROP to a target environment.
If all ESROP layer modules are linked together, the symbols listed in Table 2.5 are unresolved for the ESROP module.
The remaining symbols are associated with the Open C Platform[1] which contains detailed information about each of these facilities.
|
Several compile time constants must be configured before the ESROP module can be used. These constants are either defined by ESROP or ESROP User. Some of these configuration parameters can be statically changed at run time by changing the ESROP configuration file. The following table is the list of these configuration parameters.
|
To facilitate the portation process of ESROP, some tracing capabilities have been built into this product.
To enable the tracing feature, the compile time constant TM_ENABLED must be defined.
Tracing level can be controlled through definition of trace masks in the ESROP configuration file.
The major differences between the Unix and MS-DOS/Windows portations are isolated to several discrete locations in the code. These differences are discussed in the following sections.
The most significant difference between the two portations lies in the manner in which an ESROS user communicates with ESROS itself. Under Unix, ESROS runs as a separate task. There may thus be one or more ESROS users that invoke ESROS primitives via an interprocess communication mechanism provided by the UPQ_BSD_ module.
MS-DOS, of course, does not support such a mechanism. Therefor, ESROS and ESROS users are linked together as single executable. This is the same for Windows. As explained in the previous sections, ESROP has a call-back interface to the upper layer. However, there are two different API's available to the ESROS user (see Section , ESROS API). In the case of applications that use the Call-back API, the inter-process communication module is eliminated for one-process model. In the case of Function Call API, in place of the interprocess communication mechanism, there is a a module that emulates the UPQ_BSD_ facilities. This module, named UPQ_SIMU_, uses disk files to simulate the interprocess communication mechanism.
The developer of an ESROS application who has to port between these two environments will be chiefly concerned with the ESROS user's make file. Under Unix and for two process model, the ESROS user application is linked to the UPQ_BSD_ library. Under MS-DOS it is linked to the UPQ_SIMU_ library. In addition, the MS-DOS user must link to the libraries containing the ESROS code. The following excerpts illustrate this principle.
USER_SH = $(LIBS_PATH)/esro_ushcb.a UPQ = $(LIBS_PATH)/upq_bsd.a GF = $(LIBS_PATH)/gf.a
USER_SH = $(LIBS_PATH)\esro_ush.lib PRVDR_SH = $(LIBS_PATH)\sp_shell.lib UPQ_SIMU = $(LIBS_PATH)\upq_simu.lib UDP_IF = $(LIBS_PATH)\udp_pco.lib ESROP_SH = $(LIBS_PATH)\esrop_sh.lib PROT_ENG = $(LIBS_PATH)\esroprot.lib GF = $(LIBS_PATH)\gf.lib
UDP_IF = $(LIBS_PATH)\udp_pco.lib ESROP_SH = $(LIBS_PATH)\esrop_sh.lib PROT_ENG = $(LIBS_PATH)\esroprot.lib GF = $(LIBS_PATH)\gf.lib SF = $(LIBS_PATH)\sf.lib FSM = $(LIBS_PATH)\fsm.lib
SCH_ module can be used for scheduling the program's modules.
One of the common usages of SCH_ module is scheduling of further processing within the same module. This happens most often to prevent re-entry to non-re-entrant code. For more information about the Scheduler module refer to OPEN C Platform document.
The TMR_ module defines a model and an interface for providing timer facilities to Open C Layers, regardless of the environment, provided that all implementations of the TMR_ module conform to the interface defined here. For more information about the Timer module refer to OPEN C Platform document.
FLEX is a DOS portation of the lex utility commonly found on Unix systems. BISON is a DOS portation of the yacc utility. These utilities are used in the compilation of the ESROS Scenario interpreter, ESROSSI.
An overview of the structure of the ESROP module appears in Figure 2.3.
The USER-IN Interface is the module that deals with ESROP action primitives. userin.c contains the source to this module.
The USER-OUT Interface is the module that deals with ESROP event primitives. userout.c contains the source to this module.
The SAP Map deals with multiplexing of ESROP-Users. esrop_sap.c contains the functions related to this module.
The ESROP Finite State Machine is the heart of ESROP. invokact.c/invact2.c, perfact.c/perfact2.c, clinvktd.c/clinvtd2.c, and clperftd.c/clpertd2.c contain the functions related to this module.
The PDU Formatter deals with encoding of information into PDUs. The pduout.c contains the source to this module.
The PDU Parser deals with decoding of information from PDUs. The pduin.c contains the source to this module.
ESROP has the capability of supporting communication with several entities in the layer above. This is accomplished through the concept of an ESROP-SAP. struct SapInfo is the basic structure used. The SapInfo structure associates a series of event primitives with an ESROP_SapSel.
SapInfo structures are maintained as doubly linked lists. SapInfoSeq contains pointers to the first and last SapInfo structures. ESROP_init creates a pool of ESROP-SAPS SapInfo. ESROP_SAPS is a configuration parameter that specifies the maximum number of ESRO-SAPs supported by ESROP.
Each SapInfo structure maintains a list of active invocations associated with it. The InvokeInfoSeq field of SapInfo structure is the head of this list.
The ESROP Finite State Machine (FSM) is the heart of ESROP. Figure 2.4 ESROP Finite State Machine is a high level diagram of ESROP state machine.
The inputs to the FSM are:
/* User Action Primitives */
#define lsfsm_EvtInvokeReq2
#define lsfsm_EvtErrorReq3
#define lsfsm_EvtResultReq4
#define lsfsm_EvtPduInputInd5
/* In PDU Indications */
#define lsfsm_EvtPduInvoke6
#define lsfsm_EvtPduResult7
#define lsfsm_EvtPduAck8
#define lsfsm_EvtPduFailure9
#define lsfsm_EvtTimerInd10
/* Timer Indications */
#define lsfsm_EvtInvokePduRetranTimer11
#define lsfsm_EvtResultPduRetranTimer12
#define lsfsm_EvtRefNuTimer13
#define lsfsm_EvtInactivityTimer14
#define lsfsm_EvtLastTimer15
#define lsfsm_EvtPerfNoResponseTimer16
Each of these events have some information associated with them:
typedef union FSM_EventInfo {
struct InvokeReq {
ESRO_SapSel remESROSap;
T_SapSel *remTsap;
N_SapAddr *remNsap;
ESROP_OperationValue opValue;
ESROP_EncodingType encodingType;
DU_View parameter;
} invokeReq;
struct ResultReq {
Bool isResultNotError;
ESROP_EncodingType encodingType;
DU_View parameter;
} resultReq;
struct ErrorReq {
Bool isResultNotError;
ESROP_EncodingType encodingType;
ESROP_ErrorValue errorValue;
DU_View parameter;
} errorReq;
struct InternalInfo {
Int expiredTimerName;
} internalInfo;
struct TmrInfo {
Int name;7%)
long subscript;
Int datum;)
} tmrInfo;
} FSM_EventInfo;
Each time one of these events is observed by the USER-IN Interface module, by the ESRO-PDU PARSER module, or by the Timer Management Module, the event code and the information associated with it are passed to the event processor (esropfsm).
PUBLIC Int FSM_runMachine (FSM_Machine *machine, FSM_EventId evtId)
FSM_runMachine contains the information regarding the current state of an ESROS operation. evtId is an event ID corresponding to the event that has been observed.
Each state has an entry and an exit functions associated to it.
typedef struct FSM_State {
Int (*entry)(FSM_Machine *machine,
FSM_UserData *userData,
FSM_EventId evtId);
Int (*exit)(FSM_Machine *machine,
FSM_UserData *userData,
FSM_EventId evtId);
struct FSM_Trans *trans;
String name;
} FSM_State;
Using the information regarding the current state and the observed event, FSM_runMachine looks into the link list of transitions and finds the next state corresponding to the observed event. The transitions are a link list of:
typedef struct FSM_Trans {
FSM_EventId evtId;
Bool (*predicate) (FSM_Machine *machine,
FSM_UserData *userData,
FSM_EventId evtId);
Int (*action)(FSM_Machine *machine,
FSM_UserData *userData,
FSM_EventId evtId);
FSM_State *nextStatePtr;
String name;
} FSM_Trans;
The exit function of the current state is called. Then the action function is executed. After that, the current sate is changed to the next state and the entry function of the next state is called.
Information regarding the state of each invocation is maintained in a structure FSM_State. FSM_State contains various information about the current state of a connection.
typedef struct FSM_State {
Int (*entry)(FSM_Machine *machine,
FSM_UserData *userData,
FSM_EventId evtId);
Int (*exit)(FSM_Machine *machine,
FSM_UserData *userData,
FSM_EventId evtId);
struct FSM_Trans *trans;
String name;
} FSM_State;
The timers of ESROP are statically defined as follows.
|
lower_dataInd [lowerind.c] delivers an TSDU to ESROP.
inpdu reads the PDU header of an incoming PDU. It constructs the PDU structure and strips the header from the data buffer. If there is no data in the buffer, it frees it. At the completion of inpdu, ESRO-PDU contains the information about the received PDU. This information is then used by finite state machine.
A new machine is created through esrop_invokeInit facility.
Formatting of ESRO-PDUs is accomplished through a set of functions contained in pduout.c.
The sequence of ESROS primitives in a successful operation is next chapters. This section briefly describes the procedures that ESROP performs to invoke an operation. The description here does not deal with all possible state transitions; only the normal state transitions are described to give a general view to the reader. It is recommended that this section be read in conjunction with the source code.
Upon invocation of ESROS-INVOKE.request [userin.c], the invoker ESROP-Provider allocates a new machine and sets up the parameters relating to the invoke request event. Then delivers the ESROS-INVOKE.request event to the event processor FSM_runMachine. The state machine is assumed to be in the start state. The resulting action transition tr_clInvoker01/tr_2clInvoker01 [invokact.c/invact2.c] saves the remote address and the parameter which the user wishes to invoke. An invoke reference number which will be used to identify the invocation is created. The ESRO-INVOKE-PDU is formed and transmitted. A retransmission timer is also initialized. The resulting state is ESRO-INVOKE-PDU Sent state.
In ESRO-INVOKE-PDU Sent state, when the retransmission timer expiration event occurs, it indicates that the retransmission interval has expired since the last ESRO-INOVKE-PDU transmission, or the first transmission after ESROS-INVOKE.request. The resulting action transition tr_clInvoker02/tr_2clInvoker02 (invokact.c/invact2.c) retransmits the ESRO-INVOKE-PDU while the number of retransmissions is less than maximum number of retransmissions (invoke->nuOfRetrans). The retransmission counter is incremented and when the maximum number of retransmissions is reached, the last timer is started. The retransmission continues to await the arrival of the ESRO-RESULT-PDU or ESRO-ERROR-PDU, or last timer time out (maximum number of retransmissions), or receipt of ESRO-FAILURE-PDU.
In ESRO-INVOKE-PDU Sent state, when the last timer expiration event occurs after maximum retransmission of ESRO-INVOKE-PDU's, the tr_clInvoke03/tr_2clInvoker03 (invokact.c/invact2.c) action function issues an ESROS-FAILURE.indication primitive and initializes the reference number timer. The next state is the Invoker Reference Number Wait state that waits for the reference number timer to expire.
On receipt of ESRO-RESULT-PDU or ESRO-ERROR-PDU in the ESRO-INVOKE-PDU Sent state, the action and next state depends on the service mode and eventually 2-Way or 3-Way handshake. In the case of 3-Way handshake, the tr_clInvoker04 (invokact.c) action function sends an ESRO-ACK-PDU, issues ESROS-RESULT.indication or ESROS-ERROR.indication primitive, and initializes the inactivity timer. The resulting state is ESRO-ACK-PDU-Sent state. In the case of 2-Way handshake, the tr_2clInvoker04 (invact2.c) action function issues ESROS-RESULT.indication or ESROS-ERROR.indication primitive, and initializes the reference number timer.
In ESRO-INVOKE-PDU Sent state, on receipt of an ESRO-FAILURE-PDU, the tr_clInvoker05/tr_2clInvoker05 action (invokact.c/invact2.c) issues an ESROS-FAILURE.indication primitive with User Not Responding failure cause, and initializes the reference number timer. The resulting state is wait state for invoker reference number to expire.
In the case of 3-Way handshake, after receiving the ESRO-RESULT-PDU or ESRO-ERROR-PDU and going to ESRO-ACK-PDU send state, the duplicate ESRO-RESULT-PDU or ESRO-ERROR-PDU causes the action function tr_clInvoker07 (invokact.c) to initialize the inactivity timer and send another ESRO-ACK-PDU. The state machine stays in the ESRO-ACK-PDU Send state until the inactivity timer time-out.
In the Invoker RefNu Wait state, when the reference number timer time-out event occurs, the action tr_clInvoker08/tr_2clInvoker07 (invokact.c/invact2.c) releases the invoke reference number and the state machine goes to idle state.
In Invoker Reference Number Wait state, when ESRO-RESULT-PDU or ESRO-ERROR PDU is received, the action function tr_clInvoker09/tr_2clInvoker06 (invokact.c/invact2.c) resets the invoke reference number timer. The machine doesn't change state.
In the case of 3-Way handshake, In ESRO-ACK-PDU Send state, when the inactivity timer expiration event occurs, the action function tr_clInvoker10 (invokact.c) initializes the reference number timer, and the state is changed to Invoker Reference Number Wait state.
When ESROP receives an ESRO-INVOKE-PDU, it parses it, then delivers the INVOKEIND event to the event processor. The state machine is assumed to be in start state. The resulting action transition tr_clPerformer01/tr_2clPerformer01 (perfact.c/perfact2.c) accepts the ESRO-INVOKE-PDU and issues the ESROS-INVOKE.indication event primitive associated with the invoker of the operation. The new state becomes Invoke PDU Received state.
On receipt of an ESROS-RESULT.request primitive from performer user, the action transition tr_clPerformer02/tr_2clPerformer03 (perfact.c/perfact2.c) adds the invoke reference number to the active list, transmits the ESRO-RESULT-PDU or ESRO-ERROR-PDU, and sets the retransmission timer. In the case of 3-Way handshake, the state is changed to ESRO-ACK-PDU Wait state, waiting for ESRO-ACK-PDU. In the case of 2-Way handshake, the Inactivity Timer is set and the state is changed to Result PDU Retransmit.
In the case of 3-Way handshake, on receipt of an ESRO-ACK-PDU in ESRO-ACK-PDU Wait state, the action transition tr_clPerformer03 (perfact.c) initializes the invoke reference number timer and issues an ESROS-RESULT.confirm or an ESROS-ERROR.confirm. The state is changed to Reference Number Wait state.
In the case of 3-Way handshake, when Inactivity Timer expires, the action transition tr_2clPerformer06 (perfact2.c) initializes the invoke reference number timer and issues an ESROS-RESULT.confirm or an ESROS-ERROR.confirm. The state is changed to Reference Number Wait state.
The duplicate ESRO-INVOKE-PDUs in ESRO-INVOKE-PDU received state are ignored, and state machine stays in the same state.
In the case of 3-Way handshake, and in ESRO-ACK-PDU Wait state, when the ESRO-RESULT-PDU or ESRO-ERROR-PDU retransmission timer expires, the action transition tr_clPerformer05 (perfact.c) retransmits the ESRO-RESULT-PDU or ESRO-ERROR-PDU while the number of retransmissions is less than the maximum. The timer for number of retransmissions is incremented. The state machine stays in the ACK-PDU Wait state. The duplicate ESRO-INVOKE-PDUs in ESRO-ACK-PDU Wait state are ignored, and state machine stays in the same state.
In the case of 2-Way handshake, and in Result PDU Retransmit state, when a duplicate Invoke PDU arrives, the action transition tr_2clPerformer05 (perfact2.c) retransmits the ESRO-RESULT-PDU or ESRO-ERROR-PDU and the state machine stays in the same state.
In the ESRO-INVOKE-PDU received state, in the case of any kind of internal failure in ESROP, the action transition tr_clPerformer08/tr_clPerformer04 (perfact.c/perfact2.c) sends an ESRO-FAILURE-PDU. The state is changed to Connectionless Performer Start.
In the case of 2-Way handshake, when Inactivity Timer expires, the action transition tr_clPerformer09 issues an ESROS-FAILURE.indication primitive and initializes the invoke reference number timer. The state is changed to Performer Reference Number Wait state.
In the case of 3-Way handshake and in the ESRO-ACK-PDU Wait state, on expiration of last timer, the action transition tr_clPerformer09 (perfact.c) issues an ESROS-FAILURE.indication primitive and initializes the invoke reference number timer. The state is changed to Performer Reference Number Wait state.
In Performer Reference Number Wait state, the expiration of reference number timer causes the action transition tr_clPerformer10/tr_2clPerformer08 (perfact.c/perfact2.c) to release the invoke reference number. The state is changed to Connectionless Performer Start.
In Performer Reference Number Wait state, on receipt of duplicate ESRO-INVOKE-PDU, the action transition tr_clPerformer7/tr_2clPerformer7 (perfact.c/perfact2.c) resets the invoke reference number timer. The state is not changed.
In the case of 3-Way handshake and in Performer Reference Number Wait state, on receipt of duplicate ESRO-ACK-PDU, the action transition tr_clPerformer11 resets the invoke reference number timer. The state is not changed.
This chapter provides information about the interface to ESROS services. It is intended for the users of the ESROS sublayer.
The ESROS API is available in two different styles. In the first case the events are made available to the user of the API through function calls. This is known as the Function Call API. Functions of this API implementation all have the ESRO_ prefix. In the second case ESROS events trigger call backs to functions registered by the user of the ESROS API. This is known as Call back API. Functions of this API implementation all have the ESRO_CB_ prefix, in which CB stands for Call Back.
This section provides information about the Function Call API.
The services provided by the ESROS are defined in the ESROS Protocol Specification. The requests and responses are communicated via non-blocking function calls. Remote operation requests, and error and failure indications are communicated to the ESROS user via a call to the ESRO_getEvent function, which may be a blocking call in some implementations.
Remote operation requests, result, error and failure indications are delivered to the ESROS user in an event structure. The reader should consult the following chapters for information about the parameters which make up the structures.
The following subsections describe the ESROS library functions.
PUBLIC ESRO_RetVal ESRO_init (String configFileName)
The argument is defined as follows:
configFileName Config file name
configFileName specifies the config file name that contains ESROS initialization values.
The ESRO_sapBind function binds an ESRO Service Access Point (ESRO_SAP) to the current user process. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_sapBind(ESRO_SapDesc*sapDesc, /* out */ ESRO_SapSelsapSel ESRO_FunctionalUnitfunctionalUnit)
The arguments are defined as follows:
sapDesc Return value: the SAP descriptor sapSel SAP selector functionalUnitHandshaking type
sapDesc is a pointer to an ESRO_SapDesc structure that is created for the current user.
sapSel identifies the ESROS SAP. If the SAP is in use by another user the function returns an error value.
functionalUnit specifies the type of handshaking that is in effect for the SAP. ESRO_2Way specifies two-way handshaking. ESRO_3Way specifies three-way handshaking. In order for ESROS user processes to interact with one another over a network, they must specify local SAPs that use the same type of handshaking. Furthermore, once a SAP is created the handshaking type stays in effect until the SAP is released. Once an ESRO-SAP has been activated, the user process can use the services provided by ESROS sublayer.
The function returns zero if successful, otherwise it returns a nonzero error value.
The ESRO_sapUnbind function deactivates the ESROs service access point which is currently in use. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_sapUnbind(ESRO_SapSel sapSel)
The argument is defined as follows:
sapSel SAP selector
sapSel identifies the ESROS SAP which is already in use.
The function would return 0 if successful, and a nonzero error value otherwise.
The ESRO_invokeReq function requests a remote operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_invokeReq( ESRO_InvokeId*invokeId,/* out */ ESRO_UserInvokeRefuserInvokeRef, ESRO_SapDesclocSapDesc, ESRO_SapSelremESROSap, T_SapSel*remTsap, N_SapAddr*remNsap, ESRO_OperationValueopValue, ESRO_EncodingTypeencodingType, IntparameterLen, Byte*parameter)
The input arguments are defined as follows:
invokeId Return value: invocation identifier userInvokeRef User's invocation reference locSapDesc The local SAP descriptor remESROSap Remote network SAP address remTsap Remote Transport SAP. remNsap The remote SAP selector opValue Operation value encodingType Encoding type parameterLen The length of the parameter parameter The address of the parameter buffer.
invokeId is assigned by ESROS sublayer. It is returned by ESROS sublayer. This identifier is used in future communications between ESROS sublayer and service user to identify the invocation for ESROS sublayer.
userInvokeRef is assigned by ESROS user. It is passed to ESROS sublayer by the user of service. This identifier is used in future communications between ESROS sublayer and service user to identify the invocation for the user of ESROS.
locSapDesc is the local SAP descriptor which is provided by ESROS sublayer at the time of SAP bind.
If ESROS can serve the invoker, the function returns 0 and the invocation identifier is returned through the invokeId parameter. If ESROS cannot serve the invoker, the function returns a nonzero failure reason value.
The ESRO_resultReq function is issued by the performer of the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_resultReq( ESRO_InvokeIdinvokeId, ESRO_UserInvokeRefuserInvokeRef, ESRO_EncodingTypeencodingType, IntparameterLen, Byte*parameter)
The input arguments are defined as follows:
invokeId Invocation Identifier. userInvokeRef User's invocation reference encodingType Encoding type parameterLen Length of the parameter parameter Address of the parameter buffer.
This primitive should be issued after an ESRO_INVOKEIND event. If ESROS cannot serve the requestor, the function returns a nonzero reason value which is the failure value.
The ESRO_errorReq function is issued by the performer of the operation in case of error in performing the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_errorReq( ESRO_InvokeIdinvokeId, ESRO_UserInvokeRefuserInvokeRef, ESRO_EncodingTypeencodingType, ESRO_ErrorValueerrorValue, IntparameterLen, Byte*parameter)
The input arguments are defined as follows:
invokeId The Invocation Identifier. userInvokeRef User's invocation reference encodingType Encoding type errorValue Identifies the nature of the error. parameterLen The length of the parameter parameter String describing the error.
This primitive should be issued after a INVOKEIND event. If esros cannot serve the requestor, the function returns a negative value which is the failure value.
If any event has occurred in ESROS sublayer, the ESRO_getEvent function gets the event(s). Based on the value of wait, it either waits for and event (if no event available) or immediately returns.
PUBLIC ESRO_RetVal ESRO_getEvent( ESRO_SapDesc sapDesc, ESRO_Event *event, Bool wait)
The input arguments are defined as follows:
sapDesc Return value: the SAP descriptor event ESROS event wait Blocking/non-blocking flag
The function returns any of the following event codes as the corresponding events are detected:
ESRO_INVOKEIND Remote user is requesting an operation ESRO_FAILUREIND Operation has failed ESRO_RESULTIND ESRO-RESULT-PDU recieved ESRO_ERRORIND ESRO-ERROR-PDU received ESRO_RESULTCNF ESROS RESULT confirm ESRO_ERRORCNF ESROS ERROR confirm
The function returns negative error number if unsuccessful, or the number of events (0 or greater than 0).
The data structures of ESROS events and the corresponding event codes are listed below:
Click here to see the complete codes.
The code fragments described in the following sections illustrate the steps required to create a ESRO service access point, and invoke and perform an operation. They are patterned after the primitives of the time sequence in , Example of time sequence diagram for ESROS Services. The code fragments themselves are listed in , ESRO API Example Usage. The code sample "invoker.c" implements the left side, and the code sample "performer.c" implements the right side.
invoker.c first establishes a SAP, then issues an ESRO_invokeReq of a shell command operation. In this example, the command operation is "date". It receives a confirmation (ESROESRO_ResultInd) indicating that the operation was performed. It then retrieves the results which are communicated through the ESRO_ResultInd.
performer.c receives the ESRO_InvokeInd of a "date" command operation in the struct ESRO_InvokeInd. The result of the command is the system date which is returned to invoker.c through ESRO_resultReq. performer.c then waits for the next request from invoker.c.
This section provides information about the callback API functions.
The services provided by the ESROS are defined in the ESROS Protocol Specification,"RFC-2188" [2]. The requests are issued through function calls. Callback functions associated with ESROS events are passed to ESROS at the time of sapBind function call.
The following subsections describe the ESROS library functions
PUBLIC ESRO_RetVal ESRO_CB_init (String configFileName)
The argument is defined as follows:
configFileName Config file name
configFileName specifies the config file name that contains ESROS initialization parameters.
The ESRO_CB_sapBind function binds an ESRO Service Access Point (ESRO_SAP) for the current user process. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_sapBind( ESRO_SapDesc *sapDesc, ESRO_SapSel sapSel, ESRO_FunctionalUnit functionalUnit, int (*invokeInd)( ESRO_SapDesc locSapDesc, ESRO_SapSel remESROSap, T_SapSel *remTsap, N_SapAddr *remNsap, ESRO_InvokeId invokeId, ESRO_OperationValue opValue, ESRO_EncodingType encodingType, DU_View parameter), int (*resultInd) ( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, DU_View parameter), int (*errorInd) ( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, ESRO_ErrorValue errorValue, DU_View parameter), int (*resultCnf)( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef), int (*errorCnf) ( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef), int (*failureInd)( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_FailureValue failureValue))
The input arguments are defined as follows:
sapDesc Local SAP descriptor (outgoing param) sapSel Local SAP selector functionalUnit Handshaking type locSapDesc Local SAP descriptor remESROSap Remote network SAP address remTsap Rmote Transport SAP. remNsap The remote SAP selector invokeId Invocation identifier userInvokeRef User's invocation reference opValue Operation value encodingType Encoding type errorValue Error value failureValue Failure value parameter parameter. (*invokeInd)() Invoke indication function (*resultInd)() Result indication function (*errorInd)() Error indication function (*resultCnf)() Result confirmation function (*errorCnf)() Error confirmation function (*failureInd)() Failure indication function
sapDesc is a pointer to an ESRO_SapDesc structure that is created for the current user.
sapSel identifies the ESROS SAP. If the SAP is in use by another user the function returns an error value.
functionalUnit specifies the type of handshaking that is in effect for the SAP. ESRO_2Way specifies two-way handshaking. ESRO_3Way specifies three-way handshaking. In order for ESROS user processes to interact with one another over a network, they must specify local SAPs that use the same type of handshaking. Furthermore, once a SAP is created the handshaking type stays in effect until the SAP is released. Once an ESRO-SAP has been activated, the user process can use the services provided by ESROS.
After its ESRO-SAP has been activated, the user process can use the services provided by ESROS.
The function returns zero if successful, otherwise it returns a nonzero error value.
The ESRO_CB_sapUnbind function deactivates the ESROs service access point which is currently in use. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_sapUnbind( ESRO_SapSel sapSel)
The argument is defined as follows:
sapSel SAP selector
sapSel identifies the ESROS SAP which is already in use.
The function would return 0 if successful, and a nonzero error value otherwise.
The ESRO_CB_invokeReq function requests a remote operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_invokeReq( ESRO_InvokeId *invokeId,/* out */ ESRO_UserInvokeRef userInvokeRef, ESRO_SapDesc locSapDesc, ESRO_SapSel remESROSap, T_SapSel *remTsap, N_SapAddr *remNsap, ESRO_OperationValue opValue, ESRO_EncodingType encodingType, DU_View parameter)
The input arguments are defined as follows:
invokeId Return value: invocation identifier userInvokeRef User's invocation reference locSapDesc The local SAP descriptor remESROSap Remote network SAP address remTsap Rmote Transport SAP remNsap The remote SAP selector opValue Operation value encodingType Encoding type parameter user data
invokeId is assigned by ESROS sublayer. It is returned by ESROS sublayer and identifies an invocation for ESROS sublayer. This identifier is used in future communications between ESROS sublayer and service user to identify the invocation for ESROS sublayer.
userInvokeRef is assigned by ESROS user. It is passed to ESROS sublayer by the user of service. This identifier is used in future communications between ESROS sublayer and service user to identify the invocation for the user of ESROS.
locSapDesc is the local SAP descriptor which is provided by ESROS sublayer at the time of SAP bind.
parameter is a pointer to a DU_view data structure into which user data was previously copied. Refer to the Open C Platform document [1] for a discussion of the DU_ module.
If ESROS can serve the invoker, the function returns 0 and the invocation identifier is returned through the invokeId parameter. If ESROS cannot serve the invoker, the function returns a nonzero failure reason value.
The ESRO_CB_resultReq function is issued by the performer of the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_resultReq( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, DU_View parameter)
The input arguments are defined as follows:
invokeId invocation Identifier userInvokeRef User's invocation reference encodingType Encoding type parameter Parameter.
This primitive should be issued after invokeInd function is called. If ESROS cannot serve the requestor, the function returns a nonzero reason value which is the failure value.
The ESRO_CB_errorReq function is issued by the performer of the operation in case of error in performing the operation. It has the following syntax:
PUBLIC ESRO_RetVal ESRO_CB_errorReq( ESRO_InvokeId invokeId, ESRO_UserInvokeRef userInvokeRef, ESRO_EncodingType encodingType, ESRO_ErrorValue errorValue, DU_View parameter)
The input arguments are defined as follows:
invokeId The Invocation Identifier userInvokeRef User's invocation reference encodingType Encoding type errorValue Error value parameter Parameter.
This primitive should be issued after invokeInd function is called. If ESROS cannot serve the requestor, the function returns a negative value which is the failure value.
The code fragments described in the following sections illustrate the steps required to create a ESRO service access point, and invoke and perform an operation. They are patterned after the primitives of the time sequence in , Example of time sequence diagram for ESROS CB Services. The code fragments themselves are listed in , ESRO API Example Usage. The code sample "invoksch.c" implements the left side, and the code sample "perfsch.c" implements the right side.
invoksch.c first establishes a SAP, then issues an ESRO_invokeReq of a shell command operation. In this example, the command operation is "date". The resultInd function is called indicating that the operation was performed and the result is passed to it through data parameter.
perfsch.c establishes a SAP and waits for a request from invoksch.c. The invokeInd function is called when the request for a command operation arrives. The result of the "date" command is the system date. perfsch.c then returns the data to invoksch.c through ESRO_resultReq. perfsch.c then waits for the next request from invoksch.c.
This chapter describes the design and operation of real-world ESROS programs which have been ported to both Unix and MS-DOS platforms. These programs fall into one of three categories:
The ESROS provider program, ESROS, runs under Unix as a process separate from its potentially numerous user processes. There may be one or more ESROS user processes that invoke ESROS primitives via the interprocess communication mechanisms provided by the underlying operating system.
In order to run an ESROS user program under Unix, it is necessary to first start the ESROS provider program. Each user, in turn, opens an ESROS service access point (SAP) at run time through which it invokes ESROS primitives.
Each of the ESROS test utilities is really a pair of programs - one Invoker and one Performer. In order to successfully test ESROS both need to be started in the proper order: Performer first, then Invoker.
Under MS-DOS, ESROS users are linked to the ESROS provider at build-time, since MS-DOS does not provide facilities for running multiple, concurrent processes. In the case of Microsoft Windows, the same single process model is used. Thus, at any given time, only one application can be running. In the case of the test programs this will be either an Invoker or a Performer. That application's peer must execute on another network-connected machine (either Unix or MS-DOS or Windows) in order to execute successfully.
There is just one ESROS service provider program - the Unix ESROS-Daemon. Under MS-DOS and Windows the ESROS service provider entity is linked with the various ESROS users at build-time.
esros [ -p port ] [ -s socket ] [ -c configfile ] [ - o outlogfile ] [ -T module,mask ... ] ...
This command is described in detail in its man page. See Appendix C.
The following listing describes the format of the esros configuration file which is specified with the -c command line option. In the absence of the -c option esros looks for the file esrop.ini in the same directory as the esros binary. Note that command line options, when present, override their configuration file counterparts.
Click here to see the list description.
First go to the root directory of the ESROS source tree and execute the following command:
source sourceme.csh
Then go to the directory containing shell scripts for running programs and start ESROS using the shell script runEsros.sh. You may first wish to edit this script to enable tracing or PDU logging. (See Section 4.8 for more information on tracing and logging.) Do this for both machines if you are running the Invoker and Performer in isolation.
The shell script will prompt you to take further action to display the trace output. This involves running the Unix tail utility on the trace file. You may also wish to display either of the PDU transaction logs by running esropscop as described in Chapter 4.
Next, proceed to one of the following three sections for instructions on how to run the test itself.
As discussed previously, the ESROS provider does not execute as a separate task under MS-DOS/Windows. Rather, it is linked at build-time with the various user programs. However, the command line options for the Unix version still apply. They are simply entered on the command line of the user program along with that program's specific options. Again, refer to the esros man page in Appendix C for a discussion of the command line options for esros. The MS-DOS/Windows ESROS provider also uses the esros configuration file in the same manner as the Unix implementation.
This section describes the ESROS user programs that were developed to support testing of ESROS installations.
There are three groups of test utilities that are ported to both Unix and MS-DOS/Windows. Under Unix, these are known as ops_xmpl (single operation invoker/performer), stress (Stress Tester), and tester (ESROS Scenario Interpreter).
Under MS-DOS/Windows these utilities are linked to the ESROS provider program at build-time. (These so-called stand alone versions of the user programs also exist under Unix for test purposes.)
ops_xmpl invoker and performer programs invoke and perform a single operation respectively.
Single Operation Invoker:
invoker -l localEsroSapSel -r remoteEsroSapSel -p remotePortNu -s pubQueueName -n remoteIPadr [-T <module_name>,<bit_mask> ] ...
Single Operation Performer:
performer -l localEsroSapSel -s pubQueueName [-T <module_name>,<bit_mask>] ...
Single Operation Invoker:
invoker -l localEsroSapSel -r remoteEsroSapSel -p remotePortNu -s pubQueueName -n remoteIPadr -o outfile -e errfile [-T <module_name>,<bit_mask>] ...
Single Operation Performer:
performer -l localEsroSapSel -s pubQueueName -o outfile -e errfile [-T <module_name>,<bit_mask>] ...
stress is very similar to ops_xmpl except that it repetitively invokes and performs the same operation every delay milliseconds. Also, the invoker performs cumulative error reporting every reportPeriod milliseconds to outfile, which defaults to stdout and can be set to a file. See the previous section for a discussion of the other options.
Stress Tester Invoker:
stress_i -l localEsroSapSel -r remoteEsroSapSel -p remotePortNu -s -o logfile pubQueueName -n remoteIPadr -d delay -t reportPeriod -o logFile [-T <module_name>,<bit_mask>] ...
Stress Tester Performer:
stress_p -l localEsroSapSel -s pubQueueName [-T <module_name>,<bit_mask>] ...
Stress Tester Invoker:
stress_i -l localEsroSapSel -r remoteEsroSapSel -p remotePortNu -s pubQueueName -n remoteIPadr -d delay -t reportPeriod -o logFile [-T <module_name>,<bit_mask>] ...
Stress Tester Performer:
stress_p -l localEsroSapSel -s pubQueueName [-T <module_name>,<bit_mask>] ...
Tester (also called esrossi) is the ESROS scenario interpreter. The same program is used as both the Invoker and the Performer. The program reads scenario files that contain sequences of commands that result in ESROS primitive invocations. The scenarios themselves are discussed in greater detail in the next sections.
esrossi [-d scenariosDir] [-T <module_name>,<bit_mask>] ...
esrossi [-d scenariosDir] [-o outfile] [-e errfile] [-T <module_name>,<bit_mask>] ...
This Program is used to interpret and display the ESROS protocol log file.
esropscop esroslog.pdu
Go to the directory containing the shell scripts for running programs. There you will find the shell scripts runExamplePer.sh and runExampleInv.sh . These scripts are used to execute single operation performer and invoker, respectively. Edit these files to enable any desired tracing options. (Do this on both machines if running the Invoker and Performer in isolation.) Also, be sure to specify the correct remoteEsroSapSel and remoteIPAdr in runExampleInv.sh. For example,
# #runExampleInv.sh # $BINDIR/bin/invoker -l 12 -r 15 -p 2002 -s /tmp/SP -n 198.62.92.28 -T G_,ffff -T ESRO_,ffff -T IMQ_,ffff -T SCH_,ffff -T FSM_,ffff # #runExamplePer.sh # $BINDIR/bin/performer -l 15 -s /tmp/SP -T G_,ffff -T ESRO_,ffff -T IMQ_,ffff
In this case 198.62.92.28 is the IP address of the machine on which the Performer and its copy of ESROS will execute.
Also, note that the remote and local SAP selectors of the Invoker and Performer, respectively, match, i.e. the -l 15 option in the Performer corresponds to the -r 15 option in the Invoker.
Once the shell scripts are correct, execute the Performer script and then the Invoker.
Go to the directory containing the shell scripts for running programs. There you will find the shell scripts runStressPer.sh and runStressInv.sh. These scripts are used to execute stress_p and stress_i, respectively. Edit these files as necessary. Start the Performer and then the Invoker.
As stated earl
