DAB/MOT Data Carousel System Support Library Interface Definition

Transcription

1 DAB/MOT Data Carousel System Support Library Interface Definition D. Knox & O. Gardiner /1.3 5th Jul 1999 ENSIGMA Ltd Turing House Station Road Chepstow GWENT NP6 5PB

2 Ensigma Ltd. Page 2 of 95 Distribution Client O. Gardiner Ensigma Ltd Project File

3 Ensigma Ltd. Page 3 of 95 Contents 1. Introduction Change Control Release Summary Changes Changes in version Intended Audience Summary System Overview Server Carousel Maintenance Model Client Interface Definitions Function Definitions Function Naming Conventions Data Types File arguments Character string arguments Enumerated types Handles Error Handlers ErrorHandler DAB Packet Data Group transport configuration Server library Module Identification Version Control Carousel Capacity Spooler Interaction... 23

4 Ensigma Ltd. Page 4 of Module Descriptors Server Interface Summary MCSRVCarouselInfo MCSRVCloseCarousel MCSRVControlFrequency MCSRVCRC MCSRVCreateCarousel MCSRVCreateModule MCSRVDataRate MCSRVDeleteCarousel MCSRVDeleteModule MCSRVDescribeCarousel MCSRVDescribeModule MCSRVErrorHandler MCSRVFirstModule MCSRVHeaders MCSRVLocateModule MCSRVMatchModule MCSRVModuleAccount MCSRVModuleFrequency MCSRVModuleInfo MCSRVModuleSize MCSRVNextModule MCSRVNextCarouselInfo MCSRVNextModuleInfo MCSRVOpenCarousel MCSRVRestartCarouselInfo MCSRVRestartModuleInfo MCSRVSegSize MCSRVSpoolerStatistics MCSRVSpoolerStatus MCSRVStartSpooler MCSRVStopSpooler MCSRVSyncCarousel MCSRVUpdateModule MCSRVUpdateSpooler... 65

5 Ensigma Ltd. Page 5 of 95 MCSRVVersions Client library Access to Modules and Data Changing Data Cache Hints Time-outs Client Interface Summary MCCLICarouselInfo MCCLICloseCarousel MCCLICloseModule MCCLIErrorHandler MCCLIFirstModule MCCLILocateModule MCCLIMatchModule MCCLIModuleInfo MCCLIModuleSize MCCLINextModule MCCLINextCarouselInfo MCCLINextModuleInfo MCCLIOpenCarousel MCCLIOpenModule MCCLIPositionModule MCCLIReadModule MCCLIStats MCCLITimeout MCCLIZeroStats References... 95

6 Ensigma Ltd. Page 6 of 95 List of Tables Table 1 Library Name Prefixes Table 2 Interface data types Table 3 Error Severity Codes Table 4 Module access codes... 69

7 Ensigma Ltd. Page 7 of 95 List of Figures Figure 1 Data Carousel Server Figure 2 Data Carousel Client... 13

8 Ensigma Ltd. Page 8 of Introduction This document describes a software library to support the development of data carousel applications for DAB. 1.1 Change Control Release Summary Version Description 1.0 Initial Version 1.1 Various corrections Changes Changes in version Inadvertent comments and typographical errors fixed. 2. Missing description of MCSRVDataRate added. 3. MCSRVModuleInfo and MCCLIModuleInfo modified to handle NULL desc arguments. 4. Description of MCSRVDescribeModule corrected. 5. MCSRVModuleSize and MCCLIModuleSize added. 1.2 Intended Audience This is a technical report intended for software designers familiar with the communications protocols and messaging formats used within digital broadcasting and multi-media systems. 1.3 Summary The term data carousel describes a system in which a static data set is repeatedly broadcast so that it may be accessed as required by many receivers. A common class of applications uses data carousels to carry a representation of a computer file system. One way of implementing a data carousel is to use the MOT protocol defined in [1] to carry directory and file objects and to broadcast these objects repeatedly

9 Ensigma Ltd. Page 9 of 95 This document defines a software library intended to help programmers with the implementation of applications based on data carousels transported using MOT. It provides two related function libraries. One is for use by the broadcaster to construct application server programs (which generate, maintain and transmit the messages defining the carousel). The second is for use in receiving systems which must decode the messages and extract the data.

10 Ensigma Ltd. Page 10 of System Overview A data carousel is a system in which a number of data modules are repeatedly broadcast in a standardised format. A data carousel application has two components A server program operated by the broadcaster which maps application specific data into the standardised format and then transmits it repeatedly. A client program, operating within receivers, performs a reverse mapping from the standardised format to retrieve the application specific data in a form meaningful to the application. The data carousels discussed in this document are carried using the MOT protocol as described in [1].

11 Ensigma Ltd. Page 11 of Server Server Application Server Library Interface VFS Server Library Carousel under development Freeze Carousel MOT coded carousel Spooler DAB Packet Data Groups DAB Packet Encoder DAB Packets Figure 1 Data Carousel Server Figure 1 illustrates the application server environment. The server program creates and updates the data carousel, by mapping a set of files onto a set of modules and associated control information which define the carousel. Updates performed by the server application are applied to a working copy of the carousel. They are not immediately reflected in the data being broadcast. Once a consistent carousel is available, it can be frozen. This creates a snapshot of the carousel state, which is coded as a set of DAB data groups according to the MOT protocol. Further changes to the carousel can then be made by the application

12 Ensigma Ltd. Page 12 of 95 while the snapshot is being transmitted. The carousel must be frozen again for these changes to appear in the broadcast data. The spooler takes a repeating sequence of DAB packet data groups from the frozen version of the carousel and passes these on to the DAB packet transmission system. Because the spooler s access to the carousel data must be synchronised with updates generated by the server application, the spooler is implemented as part of the library and is controlled through server library functions.. Applications differ in the source of their data and in the nature of the mapping onto data carousel modules. However, all applications can use common facilities to create and manage their representation of the data carousel. The server library, described in this document, implements these common parts of data carousel application servers and the spooler system Carousel Maintenance Model By their nature, data carousels are fairly static structures but, from time to time, their contents change and the server library must support such changes. The maintenance system is based on the concept of a frozen snapshot of the carousel. Changes to the carousel are accumulated internally but are not reflected in the data provided to the spooler until a formal update notification is issued. This allows carousels to be built and altered incrementally, without requiring that the data be fully validated and self consistent at every intermediate step. 2.2 Client Several client (receiver) application architectures are possible. For example, three likely variants are Client reads DAB packet data groups off-air as required. Client builds a local representation of the carousel and used it to service application requests. Client caches parts of the carousel and satisfies application requests from this cache or off-air depending on whether the data is available. The current implementation uses a multi-processing client-server model in which a cache manager process services requests for carousel data from a number of clients. This is illustrated in Figure 2. However, the library interface makes no assumptions about the underlying implementation. Applications developed using the library should be portable to other implementations.

13 Ensigma Ltd. Page 13 of 95 Client Application Client Library Interface DAB VFS Client Library MOT Data Groups Cache Server MOT Data Groups DAB Packet Data Groups Cache Reader Client DAB Packet Data Groups DAB Packet Decoder DAB Packets Figure 2 Data Carousel Client

14 Ensigma Ltd. Page 14 of Interface Definitions The programmers interface to the libraries is defined in terms of a set of functions and associated data types. 3.1 Function Definitions The library functions are defined as a set of C prototypes. Note that choosing the C language binding to define the interface behaviour does not necessarily imply that either the libraries or the applications using them will actually be written in C, merely that the interfaces will behave as if they were. The choice of C as the defining language is arbitrary but pragmatic In most environments, other languages have mechanisms for calling C compatible library functions. The converse is not always the case. At least for early implementations, the operating system environment will reflect traditional UNIX culture with a C style. Other language bindings can be constructed as wrappers around the basic functionality described here. For example in a C++ environment we might construct a wrapper presenting the interface in terms of a set of object classes and methods. 3.2 Function Naming Conventions We have used a standard set of function name prefixes to avoid clashes with other libraries which may be required for building application servers and clients. While this does not guarantee to avoid clashes, the risks are substantially reduced. In an extreme case, if a name clash did occur, the source code could be mechanically processed to change these prefixes consistently. Table 1 summarises the name prefixes which defined in the current implementation.

15 Ensigma Ltd. Page 15 of 95 Library Name Prefixes Prefix MCSRV MCCLI MCAR DAB Uses Server library names Client library names Generic functions, not specific to client or server DAB data processing functions Table 1 Library Name Prefixes 3.3 Data Types To aid portability of client and server programs, the library interface is defined in terms of a limited set of data types. In any particular implementation, these will be mapped onto types available in the local language. In the C language binding, this is achieved using a set of typedefs. Interface Data Types Type BYTE CHAR INT Definition 8 bit storage unit with undefined semantics Character synonymous with C char Natural signed integer synonymous with C int. Assumed to have at least 16-bit precision. LONG Long signed integer assumed to have at least 32 bits precision. VOID CHANDLE MHANDLE EHANDLER Synonym for C void. Handle for a data carousel Handle for a module Pointer to an error handling function. Error handling functions are described in Section 3.4. Table 2 Interface data types

16 Ensigma Ltd. Page 16 of File arguments Where it is necessary to pass files to library functions, we limit the interface to file name character strings. This is not a limitation in practice and ensures that language or operating system specific methods of file processing are not embedded in the interface definition Character string arguments Character string arguments are handled according to the normal C conventions. The actual argument is a pointer to a null-terminated array of characters Enumerated types Where arguments are naturally expressed as an enumeration of logical values, we define them as integers and specify the numeric representations. Although the equivalence between integers and enumerations is natural in C, this is not the case for other languages. By defining numeric rather than symbolic representations we ensure cross language compatibility Handles Where it is necessary to refer to a data carousel or to an entity within a carousel, we use handles. Handles are typed references to hidden data objects. To aid inter-language working, implementations will ensure that Handles can be cast to and from C pointers of type void *. Although handles can be stored in pointer variables, the only supported means of dereferencing a handle is to pass it as an argument to one of the functions in the library. A handle containing a value equivalent to a C NULL pointer is considered invalid. The interface is defined such that no manipulation of handles is required apart from assignment or passing them as function arguments. 3.4 Error Handlers Since the libraries will be used to create a variety of applications in a variety of operating environments, library functions do not attempt to report errors directly to the user. Instead we define a mechanism by which an application can establish its own error reporting regime. The approach to error handling is Functions report simple success/failure indications to their callers. 1 At least beyond the requirement that a file can be represented uniquely by a character string.

17 Ensigma Ltd. Page 17 of 95 When library functions encounter errors, they call an error handler to deal with any reporting. This error handler is called when the error occurs, i.e., before the library function returns. An application can replace the supplied error handler with one more suited to its needs. Possible alternative behaviours for error handlers might be to Force program exit. Report error messages on stderr (in a UNIX or DOS environment). Report error messages in a pop-up dialogue box (in a windowing environment). Store error information in a global variable for inspection after the function returns (in the style of UNIX stdio library errno variable). Application supplied error handlers are provided with an integer code defining the error. However, the set of possible errors will be implementation dependent. For example, in a UNIX implementation, a failure in MCSRVCreateCarousel could be caused by a directory ownership problem, but in a DOS implementation, this concept does not exist. To assist applications in reporting errors without necessarily being aware of the full set of possible failure conditions, the error handler is provided with three additional pieces of information A severity code. Severity codes are listed in Table 3. A constant text message. This is a simple textual description of the failure. A variable text message, possibly NULL. Contains additional information. For example the name of a file which couldn t be opened. A typical handler would Examine the severity code to determine the appropriate style of reporting. Concatenate the two text messages with appropriate punctuation and display the result to the user. Store any information required to assist with remedial action by the application after the library function returns. Force program exit if the error is not recoverable. Error handlers must conform to C calling semantics for the ErrorHandler template shown on Page19. The EHANDLER data type is a pointer to such a function.

18 Ensigma Ltd. Page 18 of 95 Error Severity Codes Code Interpretation 0 Information. Information messages report normal operation of the library. Typically applications will report these only when a verbose mode of operation is selected by the user. 1 Normal errors. Normal errors are those caused by erroneous use of the library. E.g., bad arguments, forgetting to open a carousel. 2 Data changed errors. These occur only in the client library. See Section Time-out errors. These occur only in the client library. See Section Severe errors. Severe errors are those which indicate either design problems internal to the library or lack of key system resources. E.g., memory allocation failures, full disks etc. Severe errors will result in malfunctions within the library. The only sensible behaviour for an error handler is to force an immediate exit in response to a severe error. Table 3 Error Severity Codes

19 Ensigma Ltd. Page 19 of 95 ErrorHandler VOID ErrorHandler(code, severity, text1, text2) INT code Error code INT severity Error severity code CHAR * text1 Error message text CHAR * text2 Supplementary text (possibly NULL) VOID This is a template for customised error handling functions provided by applications and established using the MCSRVErrorHandler library function. The code argument defines the error condition which resulted in the handler call. The complete set of error codes is implementation dependent. For maximum portability, application writers may prefer to limit themselves to acting in response to the severity code and the success/failure indication returned by the library function giving rise to the error. The two text arguments may be used directly for reporting errors to the user. The first argument, text1, is always provided and contains a generic description of the error condition. The second argument, text2, provides supplementary information such as the name of a file which could not be opened. If no supplementary information is available, text2 contains the value NULL. Severity codes are listed in Table 3. The default handler forces exit in response to severe errors and ignores others.

20 Ensigma Ltd. Page 20 of DAB Packet Data Group transport configuration The output from server applications built with the library is a series of DAB packet data groups which must subsequently be packaged for transmission in a DAB packet data service. Conversely a received packet data service must be presented as a series of DAB packet data groups for input to client applications. In any given implementation, some means must be provided to connect the data group stream produced by the server s spooler to the DAB transmission system. Similarly, the client must be able to receive packet data groups streams. DAB data group access functions are system specific. Furthermore, the interaction between the client library functions and the lower level I/O functions is implementation dependent. For example In most server implementations, the spooler is a separate task from the main server application, so it will not be practical for the application to configure the spooler by providing a pointer to a suitable data group output function via the server interface. In client applications with carousel managers, data group message input will be handled by a separate task. Again it will not be practical to configure data input simply by passing a function pointer through the client interface. Some operating systems may provide a read with time-out function. In others, some kind of status polling may be necessary. Instead, transport layer configuration is performed at compile time by linking suitable data group I/O functions when the server spooler or the client application is built. Porting the library to different operating environments is thus a two stage process 1. The first stage is to implement the library for a particular operating system environment (for example, UNIX, WinNT, VxWorks or whatever, with or without carousel manager on client side). This will generally involve re-writing the library code to accommodate the particular features of the operating system concerned (file I/O, inter task communications etc) and to implement whatever caching strategies are considered appropriate. Part of the implementation process is to ensure that all message I/O is channelled through a small number of functions, whose definition is considered part of the implementation. 2. For any given implementation, the second stage is to implement the defined set of DAB data group message I/O functions to match the transport facilities provided (for example TCP/IP socket interface in a UNIX implementation, or some kind of direct hardware access in an embedded receiver design). Typically, the first stage is a fairly substantial exercise, possibly involving a complete rewrite. The second stage will be fairly quick in any given environment. For example in a Unix implementation, we anticipate that the server side transport interface (used by the spooler) would be defined by just three functions

21 Ensigma Ltd. Page 21 of 95 DABHANDLE ServerOpenDAB(char *command); ServerSendDAB(DABHANDLE channel, BYTE *group); INT ServerCloseDAB(DABHANDLE channel); The command argument to ServerOpenDAB is derived from that provided to MCSRVStartSpooler(). A possible interface for the client side would be DABHANDLE ClientOpenDAB(char *command); INT ClientGetDAB(DABHANDLE channel, BYTE *msgbuf, INT buflen, INT timeout); ClientCloseDAB(DSMCCHANDLE channel); The command argument to ClientOpenDAB would perhaps be derived from the path argument to DCCLLIOpenCarousel. Many implementations will restrict operation to a single DAB channel at any one time, in which case the DABHANDLE channel identifiers can be dispensed with. These transport layer interfaces are not part of the library definition and are illustrative only.

22 Ensigma Ltd. Page 22 of Server library The server library provides support for applications which need to build and manage data carousels. It allows an application to Create, open and close data carousels. Insert delete and modify modules. Define module properties (descriptions and transmission frequency). Control the spooler associated with the carousel. The concept of opening and closing the carousel is introduced so that A server application can access more than one data carousel. A carousel can be locked against concurrent changes by more than one application in a multi-tasking environment. 4.1 Module Identification The server library encapsulates and hides the concept of the module identifiers as follows When a module is created, an unused module identifier is allocated. When a module is deleted, its module identifier is made available for re-use. When a module is replaced, its module identifier is reused by the replacement. Re-use of module identifiers is delayed as long as possible to minimise the possibility of a receiver failing to notice a change 4.2 Version Control MOT provides for a version number to be associated with each module. These version numbers are encoded as parameters associated with each module. As such they are essentially descriptive information to be interpreted by the applications built on top of the data carousel. The primary method of change detection is the unique transportid identifying each module. The library arranges that If a module is unchanged in successive versions of a carousel, then its transportid will be unchanged. If a module is changed in any way (content or description) a new transportid is allocated. If the same transportid is used in two successive versions of a carousel, then the associated module is identical.

23 Ensigma Ltd. Page 23 of 95 The library allocates new transportids on a cyclical basis so as to minimise the possibility of a receiver not noticing that a module has changed. The encoding of MOT version number parameters is optional and controlled by the MCSRVVersions function. The server library encodes version and transportid information as follows When a module is first created, it is allocated version number 1 and a new transportid. If an existing module is replaced, it is marked as changed. When a set of changes are finalised and incorporated into an updated carousel, the version numbers of changed modules are incremented and new transportids are allocated. Unchanged modules retain their previous version numbers and transportids Carousel Capacity Modules in MOT carousels are identified by a 16-bit transportid so, in principle, the carousel can contain 65,536 modules. However, because the library arranges that transportids are not re-used for different modules in successive versions of a carousel, the actual capacity of a carousel may be less than the theoretical maximum. The extent of the reduction will depend on the carousel s change history. In extreme circumstances, it may become necessary for server applications to change and freeze the carousel in stages to release transportids for re-use. In such cases, a reasonable time should elapse between successive carousel versions in order to give receivers the best chance of detecting the change. 2,3 4.3 Spooler Interaction The server library provides functions for starting, stopping and notifying updates to the spooler. In most implementations, the spooler will be a separate task which will be left running even if the application server is not. The normal way to manage spooler execution will be to construct simple start_spooler and stop_spooler applications, which call the corresponding spooler control functions. This ensures that the operational status of the spooler is communicated correctly to other server applications. 2 I.e. to give receivers an opportunity to detect that the MOT directory object has been updated before re-used transportids appear in the carousel. 3 Receivers based on the original MOT protocol (prior to the introduction of the MOT directory object) may not be able to deal well with this situation.

24 Ensigma Ltd. Page 24 of Module Descriptors Module descriptors can be defined by using MCSRVDescribeModule. These descriptors provide the basic mechanisms by which applications identify modules. 4.5 Server Interface Summary The server library interface is defined by the following functions Data carousel control: MCSRVCarouselInfo MCSRVCloseCarousel MCSRVControlFrequency MCSRVCRC MCSRVCreateCarousel MCSRVDataRate MCSRVDeleteCarousel MCSRVHeaders MCSRVNextCarouselInfo MCSRVOpenCarousel MCSRVRestartCarouselInfo MCSRVSegSize MCSRVSyncCarousel MCSRVVersions Module management: MCSRVCreateModule MCSRVDeleteModule MCSRVDescribeCarousel MCSRVDescribeModule MCSRVFirstModule MCSRVLocateModule MCSRVMatchModule MCSRVModuleFrequency

25 Ensigma Ltd. Page 25 of 95 MCSRVModuleInfo MCSRVModuleSize MCSRVNextModule MCSRVNextModuleInfo MCSRVRestartModuleInfo MCSRVUpdateModule Spooler control: MCSRVSpoolerStatus MCSRVStartSpooler MCSRVStopSpooler MCSRVUpdateSpooler Playout accounting and statistics MCSRVModuleAccount MCSRVSpoolerStatistics Error reporting and debugging information: MCSRVErrorHandler These are described on the following pages.

26 Ensigma Ltd. Page 26 of 95 MCSRVCarouselInfo INT MCSRVCarouselInfo(carousel, tag, desc, buflen) CHANDLE carousel Carousel reference. INT tag Descriptor tag. BYTE * desc Description buffer. INT buflen Length of desc. INT >0 Success, length of descriptive information <0 Success, no information defined for tag. 0 Failure This function retrieves descriptive information about a module. The information returned is selected by tag which take the same set of values as defined for MCSRVDescribeCarousel on Page??. On successful completion, the return value is the length of the description associated with tag. The result is truncated if necessary to fit within the desc argument whose length is specified in buflen. Note that descriptive information returned by this function does not include a string terminator. The function return value is normally the number of bytes written to desc (allowing for any truncation) unless desc is NULL, in which case the return value is the number of bytes available, but no data is written.

27 Ensigma Ltd. Page 27 of 95 MCSRVCloseCarousel INT MCSRVCloseCarousel(carousel) CHANDLE carousel Reference to a carousel INT non-zero Success zero Failure This function closes a carousel identified by the carousel handle argument. Once closed, a carousel can not be accessed (except by the spooler) without first being re-opened. Applications should always explicitly close a carousel to ensure that updates are properly reflected in permanent storage. On successful completion, the function returns a non-zero value.

28 Ensigma Ltd. Page 28 of 95 MCSRVControlFrequency INT MCSRVControlFrequency(carousel, frequency) CHANDLE carousel Reference to a carousel INT frequency Control frequency INT non-zero New control frequency zero Failure Normally, the control information in a data carousel is transmitted once per rotation. Responsiveness in some applications can be improved if the control information is transmitted more often. This function can be used to change the control transmission frequency of an open carousel. The frequency argument must be greater than zero to effect a change. A zero frequency argument can be used to query the current setting. On successful completion, the function returns the new control frequency. A zero return indicates failure.

29 Ensigma Ltd. Page 29 of 95 MCSRVCRC INT MCSRVCRC(carousel, crcs) CHANDLE carousel Reference to a carousel INT crcs CRC parameter INT CRC control setting This function controls whether CRCs are included in the DAB data groups of the encoded carousel. By default carousels are created with CRCs enabled. The crcs argument is interpreted as follows >0 Enable CRC generation <0 Disable CRC generation 0 Query the current setting without making changes The function return value indicates the new setting as follows 1 CRC generation enabled 0 CRC generation disabled Since a receiver can choose to ignore the CRCs, probably the only reason to disable CRC generation would be to improve the performance of the spooler.

30 Ensigma Ltd. Page 30 of 95 MCSRVCreateCarousel CHANDLE MCSRVCreateCarousel(path, crc, dlest) CHAR * path Path to data carousel store. INT crc Enable module CRCs. INT dlest Enable download time estimates CHANDLE non-null Success NULL Failure This function creates and initialises a new (empty) data carousel identified by the string path. The precise interpretation of path is system dependent. In UNIX implementations, path is the name of a directory where the internal representation of the carousel will be stored. In other implementations, the interpretation may be different. For example path may be simply an identifying name for the carousel, with the precise storage location determined by system configuration. The main requirement is that path is interpreted consistently between this function, MCSRVDeleteCarousel and MCSRVOpenCarousel. The crc and dlest arguments enable optional features of the carousel If crc is non-zero, then 32 bit CRCs will be included in the descriptive information transmitted with each module. This is a DSM-CC facility which is probably superfluous because the DAB environment applies its own CRC checks. If dlest is non-zero, then download time estimates will be included in the descriptive information transmitted with each module.

31 Ensigma Ltd. Page 31 of 95 These options should not be enabled if they are not required, because each reduces the amount of space available for module descriptions (see MCSRVDescribeModule). After creating the data carousel, MCSRVOpenCarousel is implicitly called with the same path argument and a handle to reference the carousel is returned.

32 Ensigma Ltd. Page 32 of 95 MCSRVCreateModule MHANDLE MCSRVCreateModule(carousel, modpath) CHANDLE carousel Carousel reference. CHAR * modpath path to a file containing module contents MHANDLE non-null Success NULL Failure This function creates a new module in the carousel. The module contents are taken from the file specified by modpath. The function returns a handle which can be used to reference the newly created module. If modpath is NULL an empty module is created. Empty modules can carry descriptive information even though they have no data content 4. A NULL handle is returned if the function fails. Note that, although modules are created from files, this does not necessarily require that there is a one-to-one correspondence between application files and data carousel modules. For example, an application might package several files in one module or it might split a file across many modules. In such cases, the application server would construct temporary intermediate files in order to use this function. 4 An empty module is represented in a DAB data carousel by descriptors in DownloadInfoIndication messages. It has zero length and there are no corresponding DownloadDataBlock messages.

33 Ensigma Ltd. Page 33 of 95 MCSRVDataRate INT MCSRVDataRate(carousel, rate) CHANDLE carousel Reference to a carousel INT rate Data rate in kbit/s INT non-zero New data rate zero Failure This function defines the average data transmission rate for the carousel. This is used by the carousel generator to define various time-out fields which are transmitted in the carousel s control messages. This function does not actually change the transmitted data rate. It affects only the control information which is transmitted after the next spooler update. A value of zero for rate can be used to query the current setting without changing it. Newly created carousels have a valid but undefined data rate. On successful completion, the function returns the new data rate. A zero return indicates failure.

34 Ensigma Ltd. Page 34 of 95 MCSRVDeleteCarousel INT MCSRVDeleteCarousel(path) CHAR * path Path to data carousel store. INT non-zero Success zero Failure This function deletes the carousel referenced by path. The precise interpretation of path is system dependent. In UNIX implementations, path is the name of a directory where the internal representation of the carousel will be stored. In other implementations, the interpretation may be different. For example path may be simply an identifying name for the carousel, with the precise storage location determined by system configuration. The main requirement is that path is interpreted consistently between this function, MCSRVCreateCarousel and MCSRVOpenCarousel. A carousel can not be deleted while it is open (either by the caller or by another task in a multi-processing system) or while its spooler is running. On successful completion, the function returns a non-zero value.

35 Ensigma Ltd. Page 35 of 95 MCSRVDeleteModule INT MCSRVDeleteModule(module) MHANDLE module Module reference INT non-zero Success zero Failure This deletes a module from the carousel containing it. Once a module has been deleted, its handle is no longer valid. If a module is a member of a group, then the group contents are adjusted to accommodate the deletion. Deleting a module may leave an empty group, which is not deleted. The function returns a non-zero value on success and zero on failure.

36 Ensigma Ltd. Page 36 of 95 MCSRVDescribeCarousel INT MCSRVDescribeCarousel(carousel, tag, desc, length) CHANDLE carousel Carousel reference INT tag Descriptor tag BYTE * desc Descriptive information INT length Length in bytes of descriptive information INT non-zero Success zero Failure This function adds descriptive information provided as an array of bytes in desc to the specified carousel. The length of the descriptive information in desc is specified by length. For text descriptions, string terminator characters (such as the NULL termination character in C) should not be included in length. The descriptive information is transmitted as an MOT parameter whose identifier is given by the tag value. The maximum permissible length for a MOT parameter data field (given by desc) is bytes. The tag argument should take one of the values defined in [1]. The function will report an error if tag is less than 0 or greater than 0x3f. Note however that [1] imposes additional restrictions which are not detected. Applications should avoid using tag 0x06 if automatic MOT version numbering (see MCSRVVersions) is to be used, since this may cause duplicated or conflicting MOT version number parameters to be included in the carousel.

37 Ensigma Ltd. Page 37 of 95 MCSRVDescribeModule INT MCSRVDescribeModule(module, tag, desc, length) MHANDLE module Module reference INT tag Descriptor tag BYTE * desc Descriptive information INT length Length in bytes of descriptive information INT non-zero Success zero Failure This function adds descriptive information provided as an array of bytes in desc to the specified module. The length of the descriptive information in desc is specified by length. For text descriptions, string terminator characters (such as the NULL termination character in C) should not be included in length. The descriptive information is transmitted as an MOT parameter whose identifier is given by the tag value. The maximum permissible length for a MOT parameter data field (given by desc) is bytes. The tag argument should take one of the values defined in [1]. The function will report an error if tag is less than 0 or greater than 0x3f. Note however that [1] imposes additional restrictions which are not detected. Applications should avoid using tag 0x06 if automatic MOT version numbering (see MCSRVVersions) is to be used, since this may cause duplicated or conflicting MOT version number parameters to be included in the carousel.

38 Ensigma Ltd. Page 38 of 95 MCSRVErrorHandler EHANDLER MCSRVErrorHandler(handler) EHANDLER handler Error handling function. EHANDLER non-null Previous error handler. NULL Failure This function allows a server application to replace the current error handler. The return value contains a pointer to the old handler so it can be re-established later if required. If an application does not establish its own error handler, the library supplies a default handler, which does nothing.

39 Ensigma Ltd. Page 39 of 95 MCSRVFirstModule MHANDLE MCSRVFirstModule(carousel) CHANDLE carousel Carousel reference. MHANDLE non-null Module handle NULL Failure This function returns a handle to the first module in the specified carousel. The sense in which modules are sequenced is undefined. All that is guaranteed is that a call to this function followed by successive calls to MCSRVNextModule will eventually iterate through all the modules in the carousel. During iterative processing of carousel modules, applications must take care to Not create new modules. It is unpredictable whether the new module will be inserted before or after the current iteration location. Not delete the current module until after using its handle to locate the next one in sequence. A NULL handle is returned if the function fails or if the carousel is empty.

40 Ensigma Ltd. Page 40 of 95 MCSRVHeaders INT MCSRVHeaders(carousel, headers) CHANDLE carousel Reference to a carousel INT headers MOT header control INT header control setting This function controls whether MOT headers are included in the carousel 5. By default carousels are created with MOT header encoding disabled. The headers argument is interpreted as follows >0 Enable MOT header encoding <0 Disable MOT header encoding 0 Query the current setting without making changes The function return value indicates the new setting as follows 1 MOT header encoding enabled 0 MOT header encoding disabled 5 MOT headers are not essential to decode a data carousel and they are not required by the client library decoder. However, they may be required by older decoders which pre-date the introduction of the MOT Directory object.

41 Ensigma Ltd. Page 41 of 95 MCSRVLocateModule MHANDLE MCSRVLocateModule(carousel, tag, desc, length) CHANDLE carousel Carousel reference. INT tag Descriptor tag value BYTE * desc Match data INT length Length of desc MHANDLE non-null Module handle. NULL Failure This function locates an existing module in the carousel with a descriptor of type tag and content desc. The tag argument should be one of the descriptor types listed under MCSRVDescribeModule on 37. Only exact matches are returned. This function does not provide any pattern matching or wildcard processing facilities. If no matching module is found, the function fails. If more than one module matches the search criterion, a valid handle will be returned, but precisely which of the matching modules is referenced is unpredictable. It is up to the application to ensure that module descriptors are managed in such a way as to provide unique access if such functionality is required. A NULL handle is returned if the function fails.

42 Ensigma Ltd. Page 42 of 95 MCSRVMatchModule MHANDLE MCSRVMatchModule(carousel, dcount, tag, desc, length) CHANDLE carousel Carousel reference. INT dcount Descriptor count INT * tag Descriptor tag values BYTE ** desc Descriptor data arrays INT * length Lengths of descriptor data arrays MHANDLE non-null Module handle. NULL Failure This function is similar to MCSRVLocateModule, except that the tag, desc and length arguments are all arrays. Corresponding elements in these arrays define a descriptor, with the total number of descriptors being specified by the dcount argument 6. The function returns a handle for a module with matching descriptors for every item in the descriptor set. For example, this function could be used to locate a module with a particular name and type. Only exact matches are returned. There are no pattern matching or wildcard processing facilities. If no matching module is found, the function fails. If more than one module 6 We use this interface rather than a single array or linked list of structs to ease the problems associated with using the library from languages other than C.

43 Ensigma Ltd. Page 43 of 95 matches the search criterion, a valid handle will be returned, but precisely which of the matching modules is referenced is unpredictable. It is up to the application to ensure that module descriptors are managed in such a way as to provide unique access if such functionality is required. A NULL handle is returned if the function fails.

44 Ensigma Ltd. Page 44 of 95 MCSRVModuleAccount INT MCSRVModuleAccount(module, account) MHANDLE module Reference to a module INT account Account code INT non-zero New module account zero Failure Each module in a carousel can be assigned an account code for service monitoring purposes, The MCSRVSpoolerStatistics function can then be used to report the total number of bytes transmitted for each account code. This function associates an account code with a module. An account code is a small integer in the range 1 MCSRV_MAX_ACCOUNT 7. By default, modules are assigned to account code 1 when they are first created. If a module is updated (with MCSRVUpdateModule) it retains its previous account code unless it is explicitly altered by calling this function. A zero account argument can be used to query the current setting without making any changes. On successful completion, the function returns the new account code. A zero return indicates failure (for example an out-of-range account) in the current implementation, although this can be changed by recompiling the library.

45 Ensigma Ltd. Page 45 of 95 MCSRVModuleFrequency INT MCSRVModuleFrequency(module, frequency) MHANDLE module Reference to a module INT frequency Module frequency INT non-zero New module frequency zero Failure Normally, each module in a data carousel is transmitted once per rotation. Responsiveness in some applications can be improved if some modules are transmitted more often. This function can be used to change the transmission frequency of a module. The frequency argument must be greater than zero to effect a change. A zero frequency argument can be used to query the current setting. On successful completion, the function returns the new frequency. A zero return indicates failure.

46 Ensigma Ltd. Page 46 of 95 MCSRVModuleInfo INT MCSRVModuleInfo(module, tag, frequency, desc, buflen) MHANDLE module Module reference. INT tag Descriptor tag. INT * frequency Module transmission frequency. BYTE * desc Description buffer. INT buflen Length of desc. INT >0 Success, length of descriptive information <0 Success, no information defined for tag. 0 Failure This function retrieves descriptive information about a module. The information returned is selected by tag which take the same set of values as defined for MCSRVDescribeModule on Page 37. On successful completion, the return value is the length of the description associated with tag. The result is truncated if necessary to fit within the desc argument whose length is specified in buflen. Note that descriptive information returned by this function does not include a string terminator. The function return value is normally the number of bytes written to desc (allowing for any truncation) unless desc is NULL, in which case the return value is the

47 Ensigma Ltd. Page 47 of 95 number of bytes available, but no data is written. Regardless of the values in tag and desc, the module transmission frequency (in transmissions per carousel turn) is always returned in the frequency argument.

48 Ensigma Ltd. Page 48 of 95 MCSRVModuleSize LONG MCSRVModuleSize(module) MHANDLE module Module reference. LONG >= 0 Success, size of module in bytes <0 Failure. This function returns the size (in bytes) of the specified module. Modules may have zero size.

49 Ensigma Ltd. Page 49 of 95 MCSRVNextModule MHANDLE MCSRVNextModule(module) MHANDLE module Current module reference MHANDLE non-null Module handle NULL Failure This function returns a handle to module s successor in the carousel which contains it. The sense in which modules are sequenced is undefined. All that is guaranteed is that a call to MCSRVFirstModule followed by successive calls to MCSRVNextModule will eventually iterate through all the modules in the carousel. During iterative processing of carousel modules, applications must take care to Not create new modules. It is unpredictable whether the new module will be inserted before or after the current iteration location. Not delete the current module until after using its handle to locate the next one in sequence. A NULL handle is returned if the function fails or if there are no more modules in the carousel.

50 Ensigma Ltd. Page 50 of 95 MCSRVNextCarouselInfo INT MCSRVNextCarouselInfo(carousel, tag, desc, buflen) CHANDLE carousel Carousel reference. INT tag Descriptor tag. BYTE * desc Description buffer. INT buflen Length of desc. INT >0 Success, length of descriptive information <0 Success, no information defined for tag. 0 Failure This function retrieves descriptive information about a carousel. The information returned is selected by tag which take the same set of values as defined for MCSRVDescribeCarousel on Page??. Where multiple instances of a given descriptor may be applied to a module, this function allows all instances to be retrieved. On successful completion, the return value is the length of the next description associated with tag. The result is truncated if necessary to fit within the desc argument whose length is specified in buflen. Note that descriptive information returned by this function does not include a string terminator. The function return value is normally the number of bytes written to desc (allowing for any truncation) unless desc is NULL, in which case the return value is the

51 Ensigma Ltd. Page 51 of 95 number of bytes available, but no data is written.

52 Ensigma Ltd. Page 52 of 95 MCSRVNextModuleInfo INT MCSRVNextModuleInfo(module, tag, frequency, desc, buflen) MHANDLE module Module reference. INT tag Descriptor tag. INT * frequency Module transmission frequency. BYTE * desc Description buffer. INT buflen Length of desc. INT >0 Success, length of descriptive information <0 Success, no information defined for tag. 0 Failure This function retrieves descriptive information about a module. The information returned is selected by tag which take the same set of values as defined for MCSRVDescribeModule on Page 37. Where multiple instances of a given descriptor may be applied to a module, this function allows all instances to be retrieved. On successful completion, the return value is the length of the next description associated with tag. The result is truncated if necessary to fit within the desc argument whose length is specified in buflen. Note that descriptive information returned by this function does not include a string terminator.

53 Ensigma Ltd. Page 53 of 95 The function return value is normally the number of bytes written to desc (allowing for any truncation) unless desc is NULL, in which case the return value is the number of bytes available, but no data is written. Regardless of the values in tag and desc, the module transmission frequency (in transmissions per carousel turn) is always returned in the frequency argument.

54 Ensigma Ltd. Page 54 of 95 MCSRVOpenCarousel CHANDLE MCSRVOpenCarousel(path) CHAR * path Path to data carousel store. CHANDLE non-null Carousel handle NULL Failure This function opens an existing data carousel for modifications. The carousel is identified by the string path. The precise interpretation of path is system dependent. In UNIX implementations, path is the name of a directory where the internal representation of the carousel will be stored. In other implementations, the interpretation may be different. For example path may be simply an identifying name for the carousel, with the precise storage location determined by system configuration. The main requirement is that path is interpreted consistently between this function, MCSRVDeleteCarousel and MCSRVCreateCarousel. In a multi-processing environment, only one process may open a carousel for modifications at a time. On successful completion, the function returns a handle to reference the carousel.

55 Ensigma Ltd. Page 55 of 95 MCSRVRestartCarouselInfo VOID MCSRVRestartCarouselInfo(carousel) CHANDLE carousel Carousel handle This function resets the internal pointer for iterating through carousel descriptors with calls to MCSRVNextCarouselInfo.

56 Ensigma Ltd. Page 56 of 95 MCSRVRestartModuleInfo VOID MCSRVRestartModuleInfo(module) MHANDLE module Module handle This function resets the internal pointer for iterating through module descriptors with calls to MCSRVNextModuleInfo.

57 Ensigma Ltd. Page 57 of 95 MCSRVSegSize INT MCSRVSegSize(carousel, segsize) CHANDLE carousel Reference to a carousel INT segsize Segmentation size INT non-zero New segmentation size zero Failure This function sets the MOT segmentation size for the carousel. The segsize argument must be in the range 1 to The default value for a new carousel is A zero segsize argument simply returns the current segmentation size without making any changes. Although the MOT protocol allows different modules to have different segment sizes 8, the server library encodes all modules with the same segment size. Normally the default is adequate. On successful completion, the function returns the new segmentation size. A zero return indicates failure. 8 And the client library can recognise and decode modules with different segment sizes.