Recommendation for Space Data System Practices

3.6SLE Application

3.6.1Obligations

The application shall create all API components and configure them (see 3.6.5).

The application shall control processing of the service element and participate in service instance management (see 3.6.6).

The application shall implement and export the interface ISLE_ServiceInform used by the service element for passing of SLE protocol data units received from the peer SLE application for one service instance.

The application shall implement and export an interface by which API components can enter records to the system log and notify the application of specific events (see 3.6.2).

The application shall implement and export an interface by which API components can enter event trace records for diagnostic purposes. The application shall also start and stop tracing using the interface ISLE_TraceControl exported by the components (see 3.6.3).

The application may implement and export an interface by which the API component ‘SLE Utilities’ can obtain current time (see 3.6.4).

The application shall participate in memory management by applying the reference counting scheme for component interfaces specified in annex A.1.48.1.1.1.1.2 to this specification and using the API memory manager via the interface IMalloc.

The application shall terminate processing of the API and control orderly shutdown of the API (see 3.6.5).

3.6.2Logging and Notification

1. 
   The specifications in this subsection partially apply to clients of the interface ISLE_Reporter.
   
2. 
   API components shall apply the following guidelines for production of log records and notifications. Errors detected by a component shall always be logged, providing as much information as possible to support investigation of the problem. Errors reported by a lower layer component shall not be logged unless important information can be added. Nominal events shall only be logged when the higher layer component or the application is not informed of the event by other means.
   
3. 
   Notifications shall be constrained to events related to security, failure of the communication system, and to events that cannot be detected by the application by other means. The event shall be notified by the highest layer in the API that can detect the event.
   

The SLE Application shall export the interface ISLE_Reporter by which API Proxy and the API Service Element can enter log records and notify the application of specific alarms.

The implementation of the interface ISLE_Reporter shall be multi-thread safe.

Log records shall be classified as ‘alarms’ or ‘information messages’.

Alarms shall be raised for non-nominal events, including but not limited to:

1. 
   security alarms (access violations and authentication failures);
   
2. 
   communication system failures;
   
3. 
   incorrect specification of operation parameters;
   
4. 
   protocol errors;
   
5. 
   configuration deficiencies; and
   
6. 
   errors that might be caused by a malfunctioning component.
   

Information messages shall report nominal events for documentation purposes.

A log record shall be an ASCII string without any formatting characters.

For every log record the following additional information shall be supplied, using the arguments of the method LogRecord():

1. 
   the identification of the component that produced the log record;
   
2. 
   the service instance identifier, if applicable;
   
3. 
   the classification of the log record as defined in ; and
   
4. 
   a unique identification number, which is referenced in the documentation supplied by the implementation of the API component.
   

The application shall be notified of the following types of events using the function Notify():

1. 
   access violation alarms;
   
2. 
   authentication failures;
   
3. 
   communication system failures;
   
4. 
   premature termination of an association by a component before the higher layer becomes aware of association establishment; and
   
5. 
   premature termination of an association by the peer system before the higher layer becomes aware of association establishment.
   

The following information shall be supplied with a notification, using the arguments of the method Notify():

1. 
   the type of the notification as defined in ;
   
2. 
   the identification of the component that issued the notification;
   
3. 
   the service instance identifier, if applicable;
   
4. 
   a unique identification number, which is referenced in the documentation supplied by the implementation of the API component; and
   
5. 
   optionally an additional text with a maximum length of 20 characters.
   

3.6.3Diagnostic Traces

1. 
   The following specifications partially apply to clients of the interface ISLE_Trace.
   
2. 
   This specification does not prescribe how an application deals with the trace records passed to the interface ISLE_Trace.
   
3. 
   This specification does not prescribe how a trace record is formatted. When defining the layout, it should be considered that traces are generally used for printout and must be readable for humans. The output should be understandable to engineers that are not programmers.
   

Components supporting traces of events shall generate trace records that are passed to the interface ISLE_Trace, provided by the SLE Application.

The implementation of the interface ISLE_Trace shall be multi-thread safe.

The events for which for which trace records are generated and the amount of information that is entered in trace records shall be controlled by a trace level argument to the method StartTrace() in the interface ISLE_TraceControl. The trace levels are defined as follows:

1. 
   ‘Low’ – state changes are traced. The information includes the old state, the new state, and the event that caused the state change.
   
2. 
   ‘Medium’ – the trace additionally includes the type of all PDUs processed as well as additional interactions between components.
   

3. 
   ‘High’ – the trace additionally contains a printout of all parameters of the PDU processed. The maximum length for the printout of one argument is constrained by the associated argument of the method StartTrace().
   
4. 
   ‘Full’ – the trace additionally contains a dump of the encoded data sent to and received from the network.
   

For every trace record the following additional information shall be supplied, using the arguments of the method TraceRecord() defined in ISLE_Trace:

1. 
   the identification of the component that produced the trace record; and
   
2. 
   the service instance identifier, if applicable.
   

3.6.4Time Source

1. 
   Applications may require that API components use a time source supplied by the application. Such a feature might be needed if the application uses an external time source, which is not necessarily synchronized with system time. It might also be used within simulation campaigns where a simulation might have to run in ‘future time’ without changing system time.
   
2. 
   The Time Source interface specified in this subsection is used by the API component ‘SLE Utilities’ to set current time in the interface ISLE_Time. As API components are required to use that interface for handling of time, the time reference is distributed to all other API components. If the application opts not to use this feature, the component ‘SLE Utilities’ uses system time.
   

Applications wishing to provide a time source to the API shall export the interface ISLE_TimeSource and pass this interface to the creator function of the API component ‘SLE Utilities’.

The interface ISLE_TimeSource shall provide a method returning the current time in CCSDS CDS format.

The time returned by the interface ISLE_TimeSource may have a positive or negative offset to the system time. However, API components may rely on the fact that this offset remains constant within the limits of the accuracy for timers defined in this specification.

1. 
   The required timer accuracy is specified in .
   
2. 
   A constant offset from system time allows implementation of timers using standard services of the operating system.
   

3.6.5Initialization and Shutdown of the API

The application shall create the API components needed for the specific installation using the creator functions provided by the components.

The application shall configure and link the API components.

The application shall configure the service element providing it the path name of the configuration file and the required interface references.

The application shall configure all proxy instances with the path name of the configuration file for each proxy and the required interface references including the reference to the interface ISLE_Locator obtained from the service element.

The application shall register each of the proxies with the service element.

After configuration of all components, the application shall start processing of the service element by invocation of the start method of the control interface selected according to .

For closedown of the API, the application shall perform the following steps in the sequence specified.

The application shall call the terminate method of the selected control interface on the service element.

The application shall release all API interfaces on which it holds references.

The application shall call the method ShutDown() of the administrative interfaces of the service element and of all proxies.

3.6.6Control of the Service Element

For the interaction with the service element, the application shall provide one of the behaviors defined in 3.7 and control the service element using the interface associated with that behavior.

If the application provides the sequential behavior, it shall also provide the event monitor and the timer handler defined in 3.7.2.

The application shall create and delete service instances using the interface ISLE_SIFactory provided by the service element.

The application shall configure service instances providing the common service parameters defined in this specification and the service-type specific parameters defined in the relevant supplemental Recommended Practice for the service-specific API.

A service provider application shall update service instances with values of parameters that are modified by the service production process.

3.6.7Component Objects and Interfaces

An SLE Application shall implement the following component objects and interfaces:

1. 
   objects for use by service instances exporting the interface ISLE_ServiceInform;
   

2. 
   one or more objects accepting log records and notifications and exporting the interface ISLE_Reporter;
   
3. 
   one or more objects exporting the interface ISLE_EventMonitor, if the application requires the interface behavior ‘sequential’;
   
4. 
   one or more objects exporting the interface ISLE_TimerHandler if the application requires the interface behavior ‘sequential’.