dab/mot data carousel system support library interface...
TRANSCRIPT
DAB/MOT Data CarouselSystem Support Library
Interface Definition
D. Knox & O. Gardiner
98-0003-001/1.3
5th Jul 1999
ENSIGMA LtdTuring HouseStation RoadChepstowGWENTNP6 5PB
Ensigma Ltd. Page 2 of 955th Jul 1999 98-0003-001/1.3
Distribution
Client
O. Gardiner
Ensigma Ltd
Project File
Ensigma Ltd. Page 3 of 955th Jul 1999 98-0003-001/1.3
Contents
1. Introduction.................................................................................. 8
1.1 Change Control ........................................................................................ 8
1.1.1 Release Summary ........................................................................... 8
1.1.2 Changes .......................................................................................... 81.1.2.1 Changes in version 1.1 ...................................................................... 8
1.2 Intended Audience ................................................................................... 8
1.3 Summary................................................................................................... 8
2. System Overview ....................................................................... 10
2.1 Server ...................................................................................................... 11
2.1.1 Carousel Maintenance Model ........................................................ 12
2.2 Client ....................................................................................................... 12
3. Interface Definitions .................................................................. 14
3.1 Function Definitions............................................................................... 14
3.2 Function Naming Conventions ............................................................. 14
3.3 Data Types .............................................................................................. 15
3.3.1 File arguments ............................................................................... 16
3.3.2 Character string arguments ........................................................... 16
3.3.3 Enumerated types.......................................................................... 16
3.3.4 Handles.......................................................................................... 16
3.4 Error Handlers ........................................................................................ 16
ErrorHandler............................................................................................. 19
3.5 DAB Packet Data Group transport configuration ................................ 20
4. Server library.............................................................................. 22
4.1 Module Identification ............................................................................. 22
4.2 Version Control ...................................................................................... 22
4.2.1 Carousel Capacity.......................................................................... 23
4.3 Spooler Interaction................................................................................. 23
Ensigma Ltd. Page 4 of 955th Jul 1999 98-0003-001/1.3
4.4 Module Descriptors................................................................................ 24
4.5 Server Interface Summary..................................................................... 24
MCSRVCarouselInfo ................................................................................ 26
MCSRVCloseCarousel............................................................................. 27
MCSRVControlFrequency........................................................................ 28
MCSRVCRC............................................................................................. 29
MCSRVCreateCarousel ........................................................................... 30
MCSRVCreateModule.............................................................................. 32
MCSRVDataRate ..................................................................................... 33
MCSRVDeleteCarousel............................................................................ 34
MCSRVDeleteModule .............................................................................. 35
MCSRVDescribeCarousel........................................................................ 36
MCSRVDescribeModule .......................................................................... 37
MCSRVErrorHandler................................................................................ 38
MCSRVFirstModule.................................................................................. 39
MCSRVHeaders....................................................................................... 40
MCSRVLocateModule.............................................................................. 41
MCSRVMatchModule............................................................................... 42
MCSRVModuleAccount............................................................................ 44
MCSRVModuleFrequency........................................................................ 45
MCSRVModuleInfo .................................................................................. 46
MCSRVModuleSize.................................................................................. 48
MCSRVNextModule ................................................................................. 49
MCSRVNextCarouselInfo......................................................................... 50
MCSRVNextModuleInfo ........................................................................... 52
MCSRVOpenCarousel ............................................................................. 54
MCSRVRestartCarouselInfo .................................................................... 55
MCSRVRestartModuleInfo ....................................................................... 56
MCSRVSegSize ....................................................................................... 57
MCSRVSpoolerStatistics.......................................................................... 58
MCSRVSpoolerStatus.............................................................................. 60
MCSRVStartSpooler ................................................................................ 61
MCSRVStopSpooler................................................................................. 62
MCSRVSyncCarousel .............................................................................. 63
MCSRVUpdateModule ............................................................................. 64
MCSRVUpdateSpooler ............................................................................ 65
Ensigma Ltd. Page 5 of 955th Jul 1999 98-0003-001/1.3
MCSRVVersions ...................................................................................... 67
5. Client library............................................................................... 68
5.1 Access to Modules and Data................................................................. 68
5.2 Changing Data ........................................................................................ 68
5.3 Cache Hints ............................................................................................ 69
5.4 Time-outs ................................................................................................ 69
5.5 Client Interface Summary ...................................................................... 71
MCCLICarouselInfo.................................................................................. 73
MCCLICloseCarousel............................................................................... 74
MCCLICloseModule ................................................................................. 75
MCCLIErrorHandler.................................................................................. 76
MCCLIFirstModule ................................................................................... 77
MCCLILocateModule................................................................................ 78
MCCLIMatchModule................................................................................. 79
MCCLIModuleInfo .................................................................................... 81
MCCLIModuleSize ................................................................................... 82
MCCLINextModule ................................................................................... 83
MCCLINextCarouselInfo .......................................................................... 84
MCCLINextModuleInfo ............................................................................. 86
MCCLIOpenCarousel ............................................................................... 88
MCCLIOpenModule.................................................................................. 89
MCCLIPositionModule.............................................................................. 90
MCCLIReadModule.................................................................................. 91
MCCLIStats.............................................................................................. 92
MCCLITimeout ......................................................................................... 93
MCCLIZeroStats....................................................................................... 94
6. References ................................................................................. 95
Ensigma Ltd. Page 6 of 955th Jul 1999 98-0003-001/1.3
List of Tables
Table 1 Library Name Prefixes ............................................................................................ 15
Table 2 Interface data types.................................................................................................. 15
Table 3 Error Severity Codes ............................................................................................... 18
Table 4 Module access codes ............................................................................................... 69
Ensigma Ltd. Page 7 of 955th Jul 1999 98-0003-001/1.3
List of Figures
Figure 1 Data Carousel Server ............................................................................................. 11
Figure 2 Data Carousel Client .............................................................................................. 13
Ensigma Ltd. Page 8 of 955th Jul 1999 98-0003-001/1.3
1. Introduction
This document describes a software library to support the development of data carouselapplications for DAB.
1.1 Change Control
1.1.1 Release Summary
Version Description
1.0 Initial Version
1.1 Various corrections
1.1.2 Changes
1.1.2.1 Changes in version 1.1
1. Inadvertent comments and typographical errors fixed.
2. Missing description of MCSRVDataRate added.
3. MCSRVModuleInfo and MCCLIModuleInfo modified to handle NULL descarguments.
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 communicationsprotocols 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 broadcastso that it may be accessed as required by many receivers. A common class of applicationsuses data carousels to carry a representation of a computer file system. One way ofimplementing a data carousel is to use the MOT protocol defined in [1] to carry directoryand file objects and to broadcast these objects repeatedly
Ensigma Ltd. Page 9 of 955th Jul 1999 98-0003-001/1.3
This document defines a software library intended to help programmers with theimplementation of applications based on data carousels transported using MOT. It providestwo related function libraries. One is for use by the broadcaster to construct applicationserver programs (which generate, maintain and transmit the messages defining thecarousel). The second is for use in receiving systems which must decode the messages andextract the data.
Ensigma Ltd. Page 10 of 955th Jul 1999 98-0003-001/1.3
2. System Overview
A data carousel is a system in which a number of data modules are repeatedly broadcast ina standardised format.
A data carousel application has two components—
• A server program operated by the broadcaster which maps application specific datainto the standardised format and then transmits it repeatedly.
• A client program, operating within receivers, performs a reverse mapping from thestandardised format to retrieve the application specific data in a form meaningful tothe application.
The data carousels discussed in this document are carried using the MOT protocol asdescribed in [1].
Ensigma Ltd. Page 11 of 955th Jul 1999 98-0003-001/1.3
2.1 Server
Figure 1 illustrates the application server environment. The server program creates andupdates the data carousel, by mapping a set of files onto a set of modules and associatedcontrol information which define the carousel. Updates performed by the server applicationare applied to a working copy of the carousel. They are not immediately reflected in thedata being broadcast. Once a consistent carousel is available, it can be frozen. This createsa snapshot of the carousel state, which is coded as a set of DAB data groups according tothe MOT protocol. Further changes to the carousel can then be made by the application
DABPacket
Encoder
Spooler
Server Application
MOT codedcarousel
Carousel underdevelopment
FreezeCarousel
DABPackets
VFS Server Library
DAB PacketData Groups
Server Library Interface
Figure 1 Data Carousel Server
Ensigma Ltd. Page 12 of 955th Jul 1999 98-0003-001/1.3
while the snapshot is being transmitted. The carousel must be frozen again for thesechanges to appear in the broadcast data.
The spooler takes a repeating sequence of DAB packet data groups from the frozen versionof the carousel and passes these on to the DAB packet transmission system. Because thespooler’s access to the carousel data must be synchronised with updates generated by theserver application, the spooler is implemented as part of the library and is controlledthrough server library functions..
Applications differ in the source of their data and in the nature of the mapping onto datacarousel modules. However, all applications can use common facilities to create andmanage their representation of the data carousel.
The server library, described in this document, implements these common parts of datacarousel application servers and the spooler system.
2.1.1 Carousel Maintenance Model
By their nature, data carousels are fairly static structures but, from time to time, theircontents change and the server library must support such changes. The maintenance systemis based on the concept of a frozen “snapshot” of the carousel. Changes to the carousel areaccumulated internally but are not reflected in the data provided to the spooler until aformal “update” notification is issued. This allows carousels to be built and alteredincrementally, without requiring that the data be fully validated and self consistent at everyintermediate step.
2.2 Client
Several client (receiver) application architectures are possible. For example, three likelyvariants are—
• Client reads DAB packet data groups off-air as required.
• Client builds a local representation of the carousel and used it to service applicationrequests.
• Client caches parts of the carousel and satisfies application requests from this cacheor off-air depending on whether the data is available.
The current implementation uses a multi-processing client-server model in which a cachemanager process services requests for carousel data from a number of clients. This isillustrated in Figure 2. However, the library interface makes no assumptions about theunderlying implementation. Applications developed using the library should be portable toother implementations.
Ensigma Ltd. Page 13 of 955th Jul 1999 98-0003-001/1.3
DABPacket
Decoder
ReaderClient
Client Application
Cache
CacheServer
DABPackets
DAB VFS Client Library
DAB PacketData Groups
DAB PacketData Groups
MOT Data Groups
MOT Data Groups
Client Library Interface
Figure 2 Data Carousel Client
Ensigma Ltd. Page 14 of 955th Jul 1999 98-0003-001/1.3
3. Interface Definitions
The programmers’ interface to the libraries is defined in terms of a set of functions andassociated data types.
3.1 Function Definitions
The library functions are defined as a set of C prototypes. Note that choosing the Clanguage binding to define the interface behaviour does not necessarily imply that either thelibraries or the applications using them will actually be written in C, merely that theinterfaces will behave as if they were. The choice of C as the defining language is arbitrarybut pragmatic—
• In most environments, other languages have mechanisms for calling C compatiblelibrary functions. The converse is not always the case.
• At least for early implementations, the operating system environment will reflecttraditional UNIX culture with a C style.
Other language bindings can be constructed as wrappers around the basic functionalitydescribed here. For example in a C++ environment we might construct a wrapperpresenting 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 librarieswhich may be required for building application servers and clients. While this does notguarantee to avoid clashes, the risks are substantially reduced. In an extreme case, if a nameclash did occur, the source code could be mechanically processed to change these prefixesconsistently. Table 1 summarises the name prefixes which defined in the currentimplementation.
Ensigma Ltd. Page 15 of 955th Jul 1999 98-0003-001/1.3
3.3 Data Types
To aid portability of client and server programs, the library interface is defined in terms of alimited set of data types. In any particular implementation, these will be mapped onto typesavailable in the local language. In the C language binding, this is achieved using a set oftypedefs.
Library Name Prefixes
Prefix Uses
MCSRV Server library names
MCCLI Client library names
MCAR Generic functions, not specific to client or server
DAB DAB data processing functions
Table 1 Library Name Prefixes
Interface Data Types
Type Definition
BYTE 8 bit storage unit with undefined semantics
CHAR Character — synonymous with C char
INT “Natural” signed integer — synonymous with C int.Assumed to have at least 16-bit precision.
LONG “Long” signed integer — assumed to have at least 32bits precision.
VOID Synonym for C void.
CHANDLE Handle for a data carousel
MHANDLE Handle for a module
EHANDLER Pointer to an error handling function. Error handlingfunctions are described in Section 3.4.
Table 2 Interface data types
Ensigma Ltd. Page 16 of 955th Jul 1999 98-0003-001/1.3
3.3.1 File arguments
Where it is necessary to pass files to library functions, we limit the interface to file namecharacter strings. This is not a limitation in practice and ensures that language or operatingsystem specific methods of file processing are not embedded in the interface definition1.
3.3.2 Character string arguments
Character string arguments are handled according to the normal C conventions. The actualargument is a pointer to a null-terminated array of characters.
3.3.3 Enumerated types
Where arguments are naturally expressed as an enumeration of logical values, we definethem as integers and specify the numeric representations. Although the equivalencebetween 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 languagecompatibility.
3.3.4 Handles
Where it is necessary to refer to a data carousel or to an entity within a carousel, we usehandles. Handles are typed references to hidden data objects. To aid inter-languageworking, 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 de-referencing 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 fromassignment 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 operatingenvironments, library functions do not attempt to report errors directly to the user. Insteadwe define a mechanism by which an application can establish its own error reportingregime.
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.
Ensigma Ltd. Page 17 of 955th Jul 1999 98-0003-001/1.3
• When library functions encounter errors, they call an error handler to deal with anyreporting. This error handler is called when the error occurs, i.e., before the libraryfunction returns.
• An application can replace the supplied error handler with one more suited to itsneeds.
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 aUNIX implementation, a failure in MCSRVCreateCarousel could be caused by adirectory ownership problem, but in a DOS implementation, this concept does not exist. Toassist applications in reporting errors without necessarily being aware of the full set ofpossible failure conditions, the error handler is provided with three additional pieces ofinformation—
• 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. Forexample 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 theresult to the user.
• Store any information required to assist with remedial action by the application afterthe library function returns.
• Force program exit if the error is not recoverable.
Error handlers must conform to C calling semantics for the ErrorHandler templateshown on Page19. The EHANDLER data type is a pointer to such a function.
Ensigma Ltd. Page 18 of 955th Jul 1999 98-0003-001/1.3
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 ofoperation is selected by the user.
1 Normal errors. Normal errors are those caused by erroneous use of thelibrary. E.g., bad arguments, forgetting to open a carousel.
2 Data changed errors. These occur only in the client library. See Section 5.1.
3 Time-out errors. These occur only in the client library. See Section 5.4.
4 Severe errors. Severe errors are those which indicate either design problemsinternal to the library or lack of key system resources. E.g., memoryallocation failures, full disks etc. Severe errors will result in malfunctionswithin the library. The only sensible behaviour for an error handler is toforce an immediate exit in response to a severe error.
Table 3 Error Severity Codes
Ensigma Ltd. Page 19 of 955th Jul 1999 98-0003-001/1.3
ErrorHandler
Definition:
VOID ErrorHandler(code, severity, text1, text2)
Arguments:
INT code Error code
INT severity Error severity code
CHAR * text1 Error message text
CHAR * text2 Supplementary text (possibly NULL)
Returns:
VOID
Description:
This is a template for customised error handling functions provided by applicationsand 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 maximumportability, application writers may prefer to limit themselves to acting in response tothe severity code and the success/failure indication returned by the library functiongiving rise to the error.
The two text arguments may be used directly for reporting errors to the user. The firstargument, text1, is always provided and contains a generic description of the errorcondition. The second argument, text2, provides supplementary information suchas the name of a file which could not be opened. If no supplementary information isavailable, 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.
Ensigma Ltd. Page 20 of 955th Jul 1999 98-0003-001/1.3
3.5 DAB Packet Data Group transport configuration
The output from server applications built with the library is a series of DAB packet datagroups which must subsequently be packaged for transmission in a DAB packet dataservice. Conversely a received packet data service must be presented as a series of DABpacket data groups for input to client applications.
In any given implementation, some means must be provided to “connect” the data groupstream produced by the server’s spooler to the DAB transmission system. Similarly, theclient must be able to receive packet data groups streams. DAB data group access functionsare system specific. Furthermore, the interaction between the client library functions andthe lower level I/O functions is implementation dependent. For example—
• In most server implementations, the spooler is a separate task from the main serverapplication, so it will not be practical for the application to configure the spooler byproviding a pointer to a suitable data group output function via the server interface.
• In client applications with carousel managers, data group message input will behandled by a separate task. Again it will not be practical to configure data inputsimply by passing a function pointer through the client interface.
• Some operating systems may provide a “read with time-out” function. In others, somekind of status polling may be necessary.
Instead, transport layer configuration is performed at compile time by linking suitable datagroup 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 systemenvironment (for example, UNIX, WinNT, VxWorks or whatever, with or withoutcarousel manager on client side). This will generally involve re-writing the librarycode to accommodate the particular features of the operating system concerned (fileI/O, inter task communications etc) and to implement whatever caching strategies areconsidered appropriate. Part of the implementation process is to ensure that allmessage I/O is channelled through a small number of functions, whose definition isconsidered part of the implementation.
2. For any given implementation, the second stage is to implement the defined set ofDAB data group message I/O functions to match the transport facilities provided (forexample TCP/IP socket interface in a UNIX implementation, or some kind of directhardware access in an embedded receiver design).
Typically, the first stage is a fairly substantial exercise, possibly involving a complete re-write. The second stage will be fairly quick in any given environment. For example in aUnix implementation, we anticipate that the server side transport interface (used by thespooler) would be defined by just three functions—
Ensigma Ltd. Page 21 of 955th Jul 1999 98-0003-001/1.3
DABHANDLE ServerOpenDAB(char *command);
ServerSendDAB(DABHANDLE channel, BYTE *group);
INT ServerCloseDAB(DABHANDLE channel);
The command argument to ServerOpenDAB is derived from that provided toMCSRVStartSpooler(). 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 pathargument to DCCLLIOpenCarousel. Many implementations will restrict operation to asingle DAB channel at any one time, in which case the DABHANDLE channel identifierscan be dispensed with.
These transport layer interfaces are not part of the library definition and are illustrativeonly.
Ensigma Ltd. Page 22 of 955th Jul 1999 98-0003-001/1.3
4. Server library
The server library provides support for applications which need to build and manage datacarousels. 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 ina 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 possibilityof a receiver failing to notice a change
4.2 Version Control
MOT provides for a version number to be associated with each module. These versionnumbers are encoded as parameters associated with each module. As such they areessentially descriptive information to be interpreted by the applications built on top of thedata carousel. The primary method of change detection is the unique transportIdidentifying each module.
The library arranges that—
• If a module is unchanged in successive versions of a carousel, then itstransportId will be unchanged.
• If a module is changed in any way (content or description) a new transportId isallocated.
• If the same transportId is used in two successive versions of a carousel, then theassociated module is identical.
Ensigma Ltd. Page 23 of 955th Jul 1999 98-0003-001/1.3
• The library allocates new transportIds on a cyclical basis so as to minimise thepossibility of a receiver not noticing that a module has changed.
The encoding of MOT version number parameters is optional and controlled by theMCSRVVersions function. The server library encodes version and transportIdinformation as follows—
• When a module is first created, it is allocated version number 1 and a newtransportId.
• If an existing module is replaced, it is marked as changed.
• When a set of changes are finalised and incorporated into an updated carousel, theversion numbers of changed modules are incremented and new transportIds areallocated. Unchanged modules retain their previous version numbers andtransportIds.
4.2.1 Carousel Capacity
Modules in MOT carousels are identified by a 16-bit transportId so, in principle, thecarousel can contain 65,536 modules. However, because the library arranges thattransportIds 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 ofthe 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, areasonable time should elapse between successive carousel versions in order to givereceivers 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 thespooler. In most implementations, the spooler will be a separate task which will be leftrunning even if the application server is not. The normal way to manage spooler executionwill be to construct simple start_spooler and stop_spooler applications, whichcall the corresponding spooler control functions. This ensures that the operational status ofthe 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-usedtransportIds appear in the carousel.
3 Receivers based on the original MOT protocol (prior to the introduction of the MOT directory object) maynot be able to deal well with this situation.
Ensigma Ltd. Page 24 of 955th Jul 1999 98-0003-001/1.3
4.4 Module Descriptors
Module descriptors can be defined by using MCSRVDescribeModule. These descriptorsprovide 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
Ensigma Ltd. Page 25 of 955th Jul 1999 98-0003-001/1.3
• 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.
Ensigma Ltd. Page 26 of 955th Jul 1999 98-0003-001/1.3
MCSRVCarouselInfo
Definition:
INT MCSRVCarouselInfo(carousel, tag, desc, buflen)
Arguments:
CHANDLE carousel Carousel reference.
INT tag Descriptor tag.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeCarousel on Page ??.
On successful completion, the return value is the length of the description associatedwith tag. The result is truncated if necessary to fit within the desc argument whoselength is specified in buflen. Note that descriptive information returned by thisfunction does not include a string terminator.
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is thenumber of bytes available, but no data is written.
Ensigma Ltd. Page 27 of 955th Jul 1999 98-0003-001/1.3
MCSRVCloseCarousel
Definition:
INT MCSRVCloseCarousel(carousel)
Arguments:
CHANDLE carousel Reference to a carousel
Returns:
INT non-zero Success
zero Failure
Description:
This function closes a carousel identified by the carousel handle argument.Once closed, a carousel can not be accessed (except by the spooler) without firstbeing re-opened.
Applications should always explicitly close a carousel to ensure that updates areproperly reflected in permanent storage.
On successful completion, the function returns a non-zero value.
Ensigma Ltd. Page 28 of 955th Jul 1999 98-0003-001/1.3
MCSRVControlFrequency
Definition:
INT MCSRVControlFrequency(carousel, frequency)
Arguments:
CHANDLE carousel Reference to a carousel
INT frequency Control frequency
Returns:
INT non-zero New control frequency
zero Failure
Description:
Normally, the control information in a data carousel is transmitted once perrotation. Responsiveness in some applications can be improved if the controlinformation is transmitted more often. This function can be used to change thecontrol transmission frequency of an open carousel. The frequency argumentmust be greater than zero to effect a change. A zero frequency argument can beused to query the current setting.
On successful completion, the function returns the new control frequency. A zeroreturn indicates failure.
Ensigma Ltd. Page 29 of 955th Jul 1999 98-0003-001/1.3
MCSRVCRC
Definition:
INT MCSRVCRC(carousel, crcs)
Arguments:
CHANDLE carousel Reference to a carousel
INT crcs CRC parameter
Returns:
INT CRC control setting
Description:
This function controls whether CRCs are included in the DAB data groups of theencoded 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 disableCRC generation would be to improve the performance of the spooler.
Ensigma Ltd. Page 30 of 955th Jul 1999 98-0003-001/1.3
MCSRVCreateCarousel
Definition:
CHANDLE MCSRVCreateCarousel(path, crc, dlest)
Arguments:
CHAR * path Path to data carousel store.
INT crc Enable module CRCs.
INT dlest Enable download time estimates
Returns:
CHANDLE non-NULL Success
NULL Failure
Description:
This function creates and initialises a new (empty) data carousel identified by thestring path. The precise interpretation of path is system dependent. In UNIXimplementations, path is the name of a directory where the internal representationof the carousel will be stored. In other implementations, the interpretation may bedifferent. 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 thisfunction, 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 descriptiveinformation transmitted with each module. This is a DSM-CC facility whichis probably superfluous because the DAB environment applies its own CRCchecks.
• If dlest is non-zero, then download time estimates will be included in thedescriptive information transmitted with each module.
Ensigma Ltd. Page 31 of 955th Jul 1999 98-0003-001/1.3
These options should not be enabled if they are not required, because each reducesthe amount of space available for module descriptions (seeMCSRVDescribeModule).
After creating the data carousel, MCSRVOpenCarousel is implicitly called withthe same path argument and a handle to reference the carousel is returned.
Ensigma Ltd. Page 32 of 955th Jul 1999 98-0003-001/1.3
MCSRVCreateModule
Definition:
MHANDLE MCSRVCreateModule(carousel, modpath)
Arguments:
CHANDLE carousel Carousel reference.
CHAR * modpath path to a file containing module contents
Returns:
MHANDLE non-NULL Success
NULL Failure
Description:
This function creates a new module in the carousel. The module contents aretaken from the file specified by modpath. The function returns a handle which canbe used to reference the newly created module.
If modpath is NULL an empty module is created. Empty modules can carrydescriptive information even though they have no data content4.
A NULL handle is returned if the function fails.
Note that, although modules are created from files, this does not necessarily requirethat there is a one-to-one correspondence between application files and datacarousel modules. For example, an application might package several files in onemodule or it might split a file across many modules. In such cases, the applicationserver 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 DownloadInfoIndicationmessages. It has zero length and there are no corresponding DownloadDataBlock messages.
Ensigma Ltd. Page 33 of 955th Jul 1999 98-0003-001/1.3
MCSRVDataRate
Definition:
INT MCSRVDataRate(carousel, rate)
Arguments:
CHANDLE carousel Reference to a carousel
INT rate Data rate in kBit/s
Returns:
INT non-zero New data rate
zero Failure
Description:
This function defines the average data transmission rate for the carousel. This isused by the carousel generator to define various time-out fields which aretransmitted in the carousel’s control messages.
This function does not actually change the transmitted data rate. It affects only thecontrol information which is transmitted after the next spooler update.
A value of zero for rate can be used to query the current setting without changingit.
Newly created carousels have a valid but undefined data rate.
On successful completion, the function returns the new data rate. A zero returnindicates failure.
Ensigma Ltd. Page 34 of 955th Jul 1999 98-0003-001/1.3
MCSRVDeleteCarousel
Definition:
INT MCSRVDeleteCarousel(path)
Arguments:
CHAR * path Path to data carousel store.
Returns:
INT non-zero Success
zero Failure
Description:
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 carouselwill be stored. In other implementations, the interpretation may be different. Forexample path may be simply an identifying name for the carousel, with the precisestorage location determined by system configuration.
The main requirement is that path is interpreted consistently between thisfunction, MCSRVCreateCarousel and MCSRVOpenCarousel.
A carousel can not be deleted while it is open (either by the caller or by another taskin a multi-processing system) or while its spooler is running.
On successful completion, the function returns a non-zero value.
Ensigma Ltd. Page 35 of 955th Jul 1999 98-0003-001/1.3
MCSRVDeleteModule
Definition:
INT MCSRVDeleteModule(module)
Arguments:
MHANDLE module Module reference
Returns:
INT non-zero Success
zero Failure
Description:
This deletes a module from the carousel containing it. Once a module has beendeleted, its handle is no longer valid.
If a module is a member of a group, then the group contents are adjusted toaccommodate the deletion. Deleting a module may leave an empty group, which isnot deleted.
The function returns a non-zero value on success and zero on failure.
Ensigma Ltd. Page 36 of 955th Jul 1999 98-0003-001/1.3
MCSRVDescribeCarousel
Definition:
INT MCSRVDescribeCarousel(carousel, tag, desc,length)
Arguments:
CHANDLE carousel Carousel reference
INT tag Descriptor tag
BYTE * desc Descriptive information
INT length Length in bytes of descriptive information
Returns:
INT non-zero Success
zero Failure
Description:
This function adds descriptive information provided as an array of bytes in desc tothe specified carousel. The length of the descriptive information in desc isspecified by length. For text descriptions, string terminator characters (such asthe NULL termination character in C) should not be included in length. Thedescriptive information is transmitted as an MOT parameter whose identifier isgiven by the tag value.
The maximum permissible length for a MOT parameter data field (given by desc)is 32767 bytes. The tag argument should take one of the values defined in [1]. Thefunction will report an error if tag is less than 0 or greater than 0x3f. Notehowever 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 orconflicting MOT version number parameters to be included in the carousel.
Ensigma Ltd. Page 37 of 955th Jul 1999 98-0003-001/1.3
MCSRVDescribeModule
Definition:
INT MCSRVDescribeModule(module, tag, desc, length)
Arguments:
MHANDLE module Module reference
INT tag Descriptor tag
BYTE * desc Descriptive information
INT length Length in bytes of descriptive information
Returns:
INT non-zero Success
zero Failure
Description:
This function adds descriptive information provided as an array of bytes in desc tothe specified module. The length of the descriptive information in desc isspecified by length. For text descriptions, string terminator characters (such asthe NULL termination character in C) should not be included in length. Thedescriptive information is transmitted as an MOT parameter whose identifier isgiven by the tag value.
The maximum permissible length for a MOT parameter data field (given by desc)is 32767 bytes. The tag argument should take one of the values defined in [1]. Thefunction will report an error if tag is less than 0 or greater than 0x3f. Notehowever 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 orconflicting MOT version number parameters to be included in the carousel.
Ensigma Ltd. Page 38 of 955th Jul 1999 98-0003-001/1.3
MCSRVErrorHandler
Definition:
EHANDLER MCSRVErrorHandler(handler)
Arguments:
EHANDLER handler Error handling function.
Returns:
EHANDLER non-NULL Previous error handler.
NULL Failure
Description:
This function allows a server application to replace the current error handler. Thereturn value contains a pointer to the old handler so it can be re-established later ifrequired.
If an application does not establish its own error handler, the library supplies a defaulthandler, which does nothing.
Ensigma Ltd. Page 39 of 955th Jul 1999 98-0003-001/1.3
MCSRVFirstModule
Definition:
MHANDLE MCSRVFirstModule(carousel)
Arguments:
CHANDLE carousel Carousel reference.
Returns:
MHANDLE non-NULL Module handle
NULL Failure
Description:
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 isthat a call to this function followed by successive calls to MCSRVNextModulewill 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 beinserted before or after the current iteration location.
• Not delete the current module until after using its handle to locate the nextone in sequence.
A NULL handle is returned if the function fails or if the carousel is empty.
Ensigma Ltd. Page 40 of 955th Jul 1999 98-0003-001/1.3
MCSRVHeaders
Definition:
INT MCSRVHeaders(carousel, headers)
Arguments:
CHANDLE carousel Reference to a carousel
INT headers MOT header control
Returns:
INT header control setting
Description:
This function controls whether MOT headers are included in the carousel5. Bydefault 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 librarydecoder. However, they may be required by older decoders which pre-date the introduction of the MOTDirectory object.
Ensigma Ltd. Page 41 of 955th Jul 1999 98-0003-001/1.3
MCSRVLocateModule
Definition:
MHANDLE MCSRVLocateModule(carousel, tag, desc, length)
Arguments:
CHANDLE carousel Carousel reference.
INT tag Descriptor tag value
BYTE * desc Match data
INT length Length of desc
Returns:
MHANDLE non-NULL Module handle.
NULL Failure
Description:
This function locates an existing module in the carousel with a descriptor oftype tag and content desc. The tag argument should be one of the descriptortypes listed under MCSRVDescribeModule on 37. Only exact matches arereturned. This function does not provide any pattern matching or wildcardprocessing facilities.
If no matching module is found, the function fails. If more than one modulematches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.
It is up to the application to ensure that module descriptors are managed in such away as to provide unique access if such functionality is required.
A NULL handle is returned if the function fails.
Ensigma Ltd. Page 42 of 955th Jul 1999 98-0003-001/1.3
MCSRVMatchModule
Definition:
MHANDLE MCSRVMatchModule(carousel, dcount, tag, desc, length)
Arguments:
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
Returns:
MHANDLE non-NULL Module handle.
NULL Failure
Description:
This function is similar to MCSRVLocateModule, except that the tag, descand length arguments are all arrays. Corresponding elements in these arraysdefine a descriptor, with the total number of descriptors being specified by thedcount argument6. The function returns a handle for a module with matchingdescriptors for every item in the descriptor set. For example, this function could beused to locate a module with a particular name and type. Only exact matches arereturned. 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 associatedwith using the library from languages other than C.
Ensigma Ltd. Page 43 of 955th Jul 1999 98-0003-001/1.3
matches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.
It is up to the application to ensure that module descriptors are managed in such away as to provide unique access if such functionality is required.
A NULL handle is returned if the function fails.
Ensigma Ltd. Page 44 of 955th Jul 1999 98-0003-001/1.3
MCSRVModuleAccount
Definition:
INT MCSRVModuleAccount(module, account)
Arguments:
MHANDLE module Reference to a module
INT account Account code
Returns:
INT non-zero New module account
zero Failure
Description:
Each module in a carousel can be assigned an account code for service monitoringpurposes, The MCSRVSpoolerStatistics function can then be used to reportthe total number of bytes transmitted for each account code.
This function associates an account code with a module. An account code is a smallinteger in the range 1…MCSRV_MAX_ACCOUNT7. By default, modules areassigned to account code 1 when they are first created. If a module is updated (withMCSRVUpdateModule) it retains its previous account code unless it is explicitlyaltered by calling this function.
A zero account argument can be used to query the current setting without makingany changes.
On successful completion, the function returns the new account code. A zero returnindicates failure (for example an out-of-range account).
7 15 in the current implementation, although this can be changed by recompiling the library.
Ensigma Ltd. Page 45 of 955th Jul 1999 98-0003-001/1.3
MCSRVModuleFrequency
Definition:
INT MCSRVModuleFrequency(module, frequency)
Arguments:
MHANDLE module Reference to a module
INT frequency Module frequency
Returns:
INT non-zero New module frequency
zero Failure
Description:
Normally, each module in a data carousel is transmitted once per rotation.Responsiveness in some applications can be improved if some modules aretransmitted more often. This function can be used to change the transmissionfrequency of a module. The frequency argument must be greater than zero toeffect a change. A zero frequency argument can be used to query the currentsetting.
On successful completion, the function returns the new frequency. A zero returnindicates failure.
Ensigma Ltd. Page 46 of 955th Jul 1999 98-0003-001/1.3
MCSRVModuleInfo
Definition:
INT MCSRVModuleInfo(module, tag, frequency, desc, buflen)
Arguments:
MHANDLE module Module reference.
INT tag Descriptor tag.
INT * frequency Module transmission frequency.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeModule on Page 37.
On successful completion, the return value is the length of the description associatedwith tag. The result is truncated if necessary to fit within the desc argument whoselength is specified in buflen. Note that descriptive information returned by thisfunction does not include a string terminator.
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is the
Ensigma Ltd. Page 47 of 955th Jul 1999 98-0003-001/1.3
number of bytes available, but no data is written.
Regardless of the values in tag and desc, the module transmission frequency (intransmissions per carousel turn) is always returned in the frequency argument.
Ensigma Ltd. Page 48 of 955th Jul 1999 98-0003-001/1.3
MCSRVModuleSize
Definition:
LONG MCSRVModuleSize(module)
Arguments:
MHANDLE module Module reference.
Returns:
LONG >= 0 Success, size of module in bytes
<0 Failure.
Description:
This function returns the size (in bytes) of the specified module. Modules may havezero size.
Ensigma Ltd. Page 49 of 955th Jul 1999 98-0003-001/1.3
MCSRVNextModule
Definition:
MHANDLE MCSRVNextModule(module)
Arguments:
MHANDLE module Current module reference
Returns:
MHANDLE non-NULL Module handle
NULL Failure
Description:
This function returns a handle to module’s successor in the carousel whichcontains it.
The sense in which modules are sequenced is undefined. All that is guaranteed isthat a call to MCSRVFirstModule followed by successive calls toMCSRVNextModule will eventually iterate through all the modules in thecarousel.
During iterative processing of carousel modules, applications must take care to—
• Not create new modules. It is unpredictable whether the new module will beinserted before or after the current iteration location.
• Not delete the current module until after using its handle to locate the nextone in sequence.
A NULL handle is returned if the function fails or if there are no more modules inthe carousel.
Ensigma Ltd. Page 50 of 955th Jul 1999 98-0003-001/1.3
MCSRVNextCarouselInfo
Definition:
INT MCSRVNextCarouselInfo(carousel, tag, desc,buflen)
Arguments:
CHANDLE carousel Carousel reference.
INT tag Descriptor tag.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a carousel. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeCarousel on Page??. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.
On successful completion, the return value is the length of the next descriptionassociated with tag. The result is truncated if necessary to fit within the descargument whose length is specified in buflen. Note that descriptive informationreturned by this function does not include a string terminator.
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is the
Ensigma Ltd. Page 51 of 955th Jul 1999 98-0003-001/1.3
number of bytes available, but no data is written.
Ensigma Ltd. Page 52 of 955th Jul 1999 98-0003-001/1.3
MCSRVNextModuleInfo
Definition:
INT MCSRVNextModuleInfo(module, tag, frequency, desc, buflen)
Arguments:
MHANDLE module Module reference.
INT tag Descriptor tag.
INT * frequency Module transmission frequency.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeModule on Page 37. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.
On successful completion, the return value is the length of the next descriptionassociated with tag. The result is truncated if necessary to fit within the descargument whose length is specified in buflen. Note that descriptive informationreturned by this function does not include a string terminator.
Ensigma Ltd. Page 53 of 955th Jul 1999 98-0003-001/1.3
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is thenumber of bytes available, but no data is written.
Regardless of the values in tag and desc, the module transmission frequency (intransmissions per carousel turn) is always returned in the frequency argument.
Ensigma Ltd. Page 54 of 955th Jul 1999 98-0003-001/1.3
MCSRVOpenCarousel
Definition:
CHANDLE MCSRVOpenCarousel(path)
Arguments:
CHAR * path Path to data carousel store.
Returns:
CHANDLE non-NULL Carousel handle
NULL Failure
Description:
This function opens an existing data carousel for modifications. The carousel isidentified by the string path. The precise interpretation of path is systemdependent. In UNIX implementations, path is the name of a directory where theinternal representation of the carousel will be stored. In other implementations, theinterpretation may be different. For example path may be simply an identifyingname for the carousel, with the precise storage location determined by systemconfiguration.
The main requirement is that path is interpreted consistently between thisfunction, MCSRVDeleteCarousel and MCSRVCreateCarousel.
In a multi-processing environment, only one process may open a carousel formodifications at a time.
On successful completion, the function returns a handle to reference the carousel.
Ensigma Ltd. Page 55 of 955th Jul 1999 98-0003-001/1.3
MCSRVRestartCarouselInfo
Definition:
VOID MCSRVRestartCarouselInfo(carousel)
Arguments:
CHANDLE carousel Carousel handle
Returns:
Description:
This function resets the internal pointer for iterating through carousel descriptorswith calls to MCSRVNextCarouselInfo.
Ensigma Ltd. Page 56 of 955th Jul 1999 98-0003-001/1.3
MCSRVRestartModuleInfo
Definition:
VOID MCSRVRestartModuleInfo(module)
Arguments:
MHANDLE module Module handle
Returns:
Description:
This function resets the internal pointer for iterating through module descriptorswith calls to MCSRVNextModuleInfo.
Ensigma Ltd. Page 57 of 955th Jul 1999 98-0003-001/1.3
MCSRVSegSize
Definition:
INT MCSRVSegSize(carousel, segsize)
Arguments:
CHANDLE carousel Reference to a carousel
INT segsize Segmentation size
Returns:
INT non-zero New segmentation size
zero Failure
Description:
This function sets the MOT segmentation size for the carousel. The segsizeargument must be in the range 1 to 8191. The default value for a new carousel is8191. A zero segsize argument simply returns the current segmentation sizewithout making any changes.
Although the MOT protocol allows different modules to have different segmentsizes8, the server library encodes all modules with the same segment size. Normallythe default is adequate.
On successful completion, the function returns the new segmentation size. A zeroreturn indicates failure.
8 And the client library can recognise and decode modules with different segment sizes.
Ensigma Ltd. Page 58 of 955th Jul 1999 98-0003-001/1.3
MCSRVSpoolerStatistics
Definition:
INT MCSRVSpoolerStatistics(carousel, stats, reset)
Arguments:
CHANDLE carousel Carousel reference
ULONG * stats Statistics array
INT reset Statistics reset flag
Returns:
INT 1 Success
0 Error
Description:
This provides the current spooler accounting statistics for the specified carousel.It returns meaningful values only when the spooler is running. If the spooler is notrunning, an error is signalled.
9 Account codes are values in the range 1…DCSRV_MAX_ACCOUNT. The array must contain at least(MCSRV_MAX_ACCOUNT + 1) elements
Ensigma Ltd. Page 59 of 955th Jul 1999 98-0003-001/1.3
The stats argument should be a pointer to an array of ULONGs to receive thecurrent counters. On completion of the function, this array will contain the number ofbytes transmitted since the spooler was started or the counters were last reset (seebelow). The array is indexed by account code9.
Element zero of the stats array will receive the counter for bytes not associatedwith any particular code. In practice, this means the carousel directory information10.
If the reset argument is non-zero, then all the counters will be zeroed once theirvalues have been copied to the function arguments.
10 Directory object data groups in the case of an MOT carousel.
Ensigma Ltd. Page 60 of 955th Jul 1999 98-0003-001/1.3
MCSRVSpoolerStatus
Definition:
INT MCSRVSpoolerStatus(carousel, info, infolen)
Arguments:
CHANDLE carousel Carousel reference
CHAR * info Text buffer
INT infolen Length of text buffer
Returns:
INT 0 Error
1 Spooler stopped (stopped on request)
2 Spooler running
3 Spooler abort (spooler encountered an error)
Description:
This function provides the current operating status of the spooler.
The info argument allows the return of a text string with implementation dependentextra information from the spooler (possibly the command line with which thespooler was invoked). This information is truncated if necessary to fit within thebuffer length indicated by infolen (including a string terminator).
A NULL info argument can be provided. In this case infolen should be zero.
Ensigma Ltd. Page 61 of 955th Jul 1999 98-0003-001/1.3
MCSRVStartSpooler
Definition:
INT MCSRVStartSpooler(carousel, command)
Arguments:
CHANDLE carousel Carousel reference.
CHAR * command Spooler command string
Returns:
INT non-zero Success
zero Failure
Description:
This function starts the spooler associated with the specified carousel. The spoolerwill use the most recent “frozen” state of the carousel. The function fails if thespooler is already running. Applications should call MCSRVSpoolerStatus to testthis possibility before attempting to start the spooler.
The command argument is a text string containing control information for thespooler. It’s significance will depend on the implementation. For example, it could beused to specify destination network and port addresses for the spooler.
If there is no command data, a NULL argument may be provided.
Ensigma Ltd. Page 62 of 955th Jul 1999 98-0003-001/1.3
MCSRVStopSpooler
Definition:
INT MCSRVStopSpooler(carousel)
Arguments:
CHANDLE carousel Carousel reference
Returns:
INT non-zero Success
zero Failure
Description:
This function stops the spooler associated with the specified carousel.
Note that attempting to stop a spooler that is not running is considered an error.Applications may wish to test for this possibility with MCSRVSpoolerStatus.
Ensigma Ltd. Page 63 of 955th Jul 1999 98-0003-001/1.3
MCSRVSyncCarousel
Definition:
INT MCSRVSyncCarousel(carousel)
Arguments:
CHANDLE carousel Carousel reference.
Returns:
INT non-zero Success
0 Failure
Description:
The server library maintains its description of the current state of the carousel inmemory. This description is written to disk when the carousel is closed. If aprogram using the server library fails without closing the carousel properly, thecarousel description on disk may be left in an inconsistent state.
To help protect against this possibility, programs can call MCSRVSyncCarouselto bring the on-disk description up to date with respect to the memory residentdescription.
Whether to call this function and, if so how often, is a design decision depending onthe nature of the particular application program. Simple batch processes may notneed to use this function at all. Interactive carousel editor programs may wish tosynchronise after every successful update.
Ensigma Ltd. Page 64 of 955th Jul 1999 98-0003-001/1.3
MCSRVUpdateModule
Definition:
MHANDLE MCSRVUpdateModule(module, modpath)
Arguments:
MHANDLE module Module reference.
CHAR * modpath Path to a file containing new module contents
Returns:
MHANDLE non-NULL Module handle
NULL Failure
Description:
This function replaces the contents of a module. The new module contents aretaken from the file specified by modpath. The function returns a handle which canbe used to reference the updated module. (Unless there is an error, this will be thesame as the module argument provided to the function).
A NULL handle is returned if the function fails.
Ensigma Ltd. Page 65 of 955th Jul 1999 98-0003-001/1.3
MCSRVUpdateSpooler
Definition:
INT MCSRVUpdateSpooler(carousel, when)
Arguments:
CHANDLE carousel Carousel reference
INT when Update timing code
Returns:
INT non-zero Success
zero Failure
Description:
This function validates the data carousel by attempting to generate a new “frozen”configuration. If this is successful, the spooler is instructed to use the newconfiguration. The changeover to the new configuration occurs at one of a messageboundary, module boundary or carousel turn boundary depending on the code in thewhen argument.
If the spooler is not running, the new frozen configuration will replace the old, but thespooler will not be started.
The when argument is coded as follows—
0 No replacement
1 Next message boundary
2 Next module boundary
3 Next carousel turn boundary
The “no replacement” option is provided to allow carousel configurations to be tested
Ensigma Ltd. Page 66 of 955th Jul 1999 98-0003-001/1.3
without influencing the spooler. If this option is selected, the new frozen carousel isgenerated and verified, but then discarded. The old carousel is not replaced.
If the function call fails in any way, the old carousel is not replaced.
Ensigma Ltd. Page 67 of 955th Jul 1999 98-0003-001/1.3
MCSRVVersions
Definition:
INT MCSRVVersions(carousel, versions)
Arguments:
CHANDLE carousel Reference to a carousel
INT versions MOT version parameter
Returns:
INT version control setting
Description:
This function controls whether MOT version number parameters are automaticallyincluded in the carousel11. By default carousels are created with MOT versionnumber parameters disabled.
The versions argument is interpreted as follows—
>0 – Enable MOT version number parameter encoding
<0 – Disable MOT version number parameter encoding
0 – Query the current setting without making changes
The function return value indicates the new setting as follows—
1 – MOT version number parameter encoding enabled
0 – MOT version number parameter encoding disabled
11 MOT version parameters are not needed to decode a data carousel. The client library does not use versionnumbers to detect changes. However, version numbers may be significant to some carousel applications.
Ensigma Ltd. Page 68 of 955th Jul 1999 98-0003-001/1.3
5. Client library
The client library interface provides access to modules and their descriptions, whileencapsulating and hiding the details of their encoding in DAB Packet data groups.
The caching strategy is also hidden. Different library implementations may or may notprovide a carousel manager and caches of control and module data. However, this is hiddenfrom the application, which uses the same interface in all cases. Cache “hints” to optimiseperformance are specified in terms of the application’s anticipated access to the modules,not in terms of the internal caching mechanisms. Depending on the implementation, thesehints may or may not actually affect performance.
The library is intended for implementation within some suitable multi-tasking softwareenvironment. The interface does not provide any scheduling functionality12. The interfacefunctions simply block the calling task until they either complete or time out.
5.1 Access to Modules and Data
The client library provides functions such as MCCLILocateModule to navigate throughthe carousel structure and return handles by which the modules can be referenced.Descriptive information associated with modules may be accessed via these handleswithout restriction. However, before a module’s data can be accessed (usingMCCLIReadModule or MCCLIPositionModule), the module must first be openedwith MCCLIOpenModule. Once access to a module’s data is no longer required, it shouldbe closed with MCCLICloseModule. Most implementations will impose a limit on thenumber of modules which may be opened simultaneously. Applications should closemodules after use to conserve resources.
5.2 Changing Data
The data carousel model implies repeated broadcasts of a fairly static data set. However,from time to time, the data will change. If such changes occur while a client application isactive, remedial action will almost certainly be necessary.
If the library detects that a data carousel has changed, all subsequent client library callsexcept MCCLICloseCarousel will fail and signal an error with severity code 2 usingthe mechanism described in Section 3.4. The application must close and re-open thecarousel to recover from this situation.
12 For example, we do not adopt a style in which a function returns immediately and some time later raises asignal or calls a completion function.
Ensigma Ltd. Page 69 of 955th Jul 1999 98-0003-001/1.3
Closing the carousel implicitly closes any open modules and invalidates all module andgroup handles.
5.3 Cache Hints
We anticipate that some client library implementations will retain data in internal caches toimprove performance. MCCLIOpenModule and MCCLICloseModule take accesspattern arguments to indicate anticipated future use of the module. Client libraries may beable to exploit this data to influence caching strategy and improve performance.
An access pattern argument of 0 indicates no information. For MCCLIOpenModule,this indicates the default of single sequential access. For MCCLICloseModule, the valueprovided on the previous MCCLIOpenModule call is used
Non-zero access pattern arguments are coded as 1 plus one or more of the following—
These access codes do not affect the functionality of the library in any way. Onlyperformance might be affected. Client applications may access module data in any orderregardless of anything they might have suggested though access arguments. However, insome implementations, performance may be improved if anticipated and actual accesspatterns agree. Performance may also be degraded if anticipated and actual access patternsdisagree.
In many cases, clients will simply specify access codes of zero and leave the library toimplement its default caching strategies.
5.4 Time-outs
The programming model presented to the client is that of a set of essentially static moduleswhich can be accessed through the interface functions. In reality of course, module data isonly briefly accessible as the broadcast carousel “turns”. Consequently, there may be a
Module Access Codes
Code Meaning Interpretation
2 Random access. Overrides the default assumption that module data willbe accessed sequentially and that once a block has beenread it is unlikely to be re-read without first closing andre-opening the module.
4 Repeated access. Overrides the default assumption that a module will notbe required again for some time after closure.
Table 4 Module access codes
Ensigma Ltd. Page 70 of 955th Jul 1999 98-0003-001/1.3
significant delay when accessing data. This delay may be exacerbated in poor transmissionconditions where errors could cause data blocks to be missed and require that the clientwait for the next turn of the carousel. In severe conditions, this process might continueindefinitely.
To address this problem, client functions may time-out, which they indicate by failing andsignalling an error with severity code 3 using the mechanism described in Section 3.4. Thedata carousel itself contains information indicating reasonable time-out periods (whichdepend on the total size of the carousel and the transmission data rate). The client libraryderives its default time-out behaviour from this information.
If a particular implementation supports time-outs, the defaults time-outs are established soas to be as short as practical while ensuring that, in good transmission conditions, time-outerrors rarely occur. Client applications may vary time-out values relative to the defaults byusing MCCLITimeout().
Ensigma Ltd. Page 71 of 955th Jul 1999 98-0003-001/1.3
5.5 Client Interface Summary
The client library interface is defined by the following functions—
Data carousel access:
• MCCLICarouselInfo
• MCCLICloseCarousel
• MCCLINextCarouselInfo
• MCCLIOpenCarousel
• MCCLIRestartCarouselInfo
• MCCLITimeout
Carousel Debugging Statistics:
• MCCLIStats
• MCCLIZeroStats
Module access:
• MCCLICloseModule
• MCCLIFirstModule
• MCCLILocateModule
• MCCLIMatchModule
• MCCLIModuleInfo
• MCCLIModuleSize
• MCCLINextModule
• MCCLINextModuleInfo
• MCCLIOpenModule
• MCCLIPositionModule
• MCCLIReadModule
• MCCLIRestartModuleInfo
Error reporting and debugging information:
• MCCLIErrorHandler
These are described on the following pages.
Ensigma Ltd. Page 72 of 955th Jul 1999 98-0003-001/1.3
Ensigma Ltd. Page 73 of 955th Jul 1999 98-0003-001/1.3
MCCLICarouselInfo
Definition:
INT MCCLICarouselInfo(carousel, tag, desc, buflen)
Arguments:
CHANDLE carousel Carousel reference.
INT tag Descriptor tag.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a module. The informationreturned is selected by tag which takes the same set of values as defined forMCSRVDescribeCarousel on Page ??.
On successful completion, the return value is the length of the description associatedwith tag. The result is truncated if necessary to fit within the desc argument whoselength is specified in buflen. Note that descriptive information returned by thisfunction does not include a string terminator.
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is thenumber of bytes available, but no data is written.
Ensigma Ltd. Page 74 of 955th Jul 1999 98-0003-001/1.3
MCCLICloseCarousel
Definition:
INT MCCLICloseCarousel(carousel)
Arguments:
CHANDLE carousel Reference to a carousel
Returns:
INT non-zero Success
zero Failure
Description:
This function closes a carousel identified by the carousel handle argument.Once closed, a carousel can not be accessed without first being re-opened.
Closing a carousel releases any resources associated with its management.
On successful completion, the function returns a non-zero value.
Ensigma Ltd. Page 75 of 955th Jul 1999 98-0003-001/1.3
MCCLICloseModule
Definition:
MHANDLE MCCLICloseModule(module, access)
Arguments:
MHANDLE module Module reference
INT access Access pattern code
Returns:
MHANDLE non-NULL New module handle
NULL Failure
Description:
This function closes a module identified by the module handle argument. Onceclosed, a module’s data can not be accessed without first re-opening the module.However, descriptive information about the module can still be retrieved using thehandle returned by the function.
The access argument takes one of the values listed in Section 5.3.
Module handles change when modules are opened or closed. After closing amodule, only the handle value returned by this function should be used for futurereferences. The following example is typical in C—
MHANDLE mh; … if ((mh = MCCLICloseModule(mh, 0)) == NULL) { /* error recovery */ } else { /* carry on using mh to refer to (closed) module */ }
Ensigma Ltd. Page 76 of 955th Jul 1999 98-0003-001/1.3
MCCLIErrorHandler
Definition:
EHANDLER MCCLIErrorHandler(handler)
Arguments:
EHANDLER handler Error handling function.
Returns:
EHANDLER Previous error handler
Description:
This function allows a client application to replace the current error handler. Thereturn value contains a pointer to the old handler so it can be re-established later ifrequired.
If an application does not establish its own error handler, the library supplies a defaulthandler, which does nothing.
Ensigma Ltd. Page 77 of 955th Jul 1999 98-0003-001/1.3
MCCLIFirstModule
Definition:
MHANDLE MCCLIFirstModule(carousel)
Arguments:
CHANDLE carousel Carousel reference.
Returns:
MHANDLE non-NULL Module handle
NULL Failure
Description:
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 isthat a call to this function followed by successive calls to MCCLINextModulewill eventually iterate through all the modules in the carousel.
A NULL handle is returned if the function fails or if the carousel is empty.
Ensigma Ltd. Page 78 of 955th Jul 1999 98-0003-001/1.3
MCCLILocateModule
Definition:
MHANDLE MCCLILocateModule(carousel, tag, desc, length)
Arguments:
CHANDLE carousel Carousel reference.
INT tag Descriptor tag value
BYTE * desc Match data
INT length Length of desc
Returns:
MHANDLE non-NULL Module handle.
NULL Failure
Description:
This function locates an existing module in the carousel with a descriptor oftype tag and content desc. The tag argument should be one of the descriptortypes listed under MCSRVDescribeModule on Page 37. Only exact matches arereturned. This function does not provide any pattern matching or wildcardprocessing facilities.
If no matching module is found, the function fails. If more than one modulematches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.
It is up to the server application to ensure that module descriptors are managed insuch a way as to provide unique access for the client if such functionality isrequired.
A NULL handle is returned if the function fails.
Ensigma Ltd. Page 79 of 955th Jul 1999 98-0003-001/1.3
MCCLIMatchModule
Definition:
MHANDLE MCCLIMatchModule(carousel, dcount, tag, desc, length)
Arguments:
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
Returns:
MHANDLE non-NULL Module handle.
NULL Failure
Description:
This function is similar to MCCLILocateModule, except that the tag, descand length arguments are all arrays. Corresponding elements in these arraysdefine a descriptor, with the total number of descriptors being specified by thedcount argument13. The function returns a handle for a module with matchingdescriptors for every item in the descriptor set. For example, this function could beused to locate a module with a particular name and type. Only exact matches arereturned. There are no pattern matching or wildcard processing facilities.
If no matching module is found, the function fails. If more than one module
13 We use this interface rather than a single array or linked list of structs to ease the problems associatedwith using the library from languages other than C.
Ensigma Ltd. Page 80 of 955th Jul 1999 98-0003-001/1.3
matches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.
It is up to the application to ensure that module descriptors are managed in such away as to provide unique access if such functionality is required.
A NULL handle is returned if the function fails.
Ensigma Ltd. Page 81 of 955th Jul 1999 98-0003-001/1.3
MCCLIModuleInfo
Definition:
INT MCCLIModuleInfo(module, tag, desc, buflen)
Arguments:
MHANDLE module Module reference.
INT tag Descriptor tag.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a module. The informationreturned is selected by tag which takes the same set of values as defined forMCSRVDescribeModule on Page 37.
On successful completion, the return value is the length of the description associatedwith tag. The result is truncated if necessary to fit within the desc argument whoselength is specified in buflen. Note that descriptive information returned by thisfunction does not include a string terminator.
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is thenumber of bytes available, but no data is written.
Ensigma Ltd. Page 82 of 955th Jul 1999 98-0003-001/1.3
MCCLIModuleSize
Definition:
LONG MCCLIModuleSize(module)
Arguments:
MHANDLE module Module reference.
Returns:
LONG >= 0 Success, size of module in bytes
<0 Failure.
Description:
This function returns the size (in bytes) of the specified module. Modules may havezero size.
Ensigma Ltd. Page 83 of 955th Jul 1999 98-0003-001/1.3
MCCLINextModule
Definition:
MHANDLE MCCLINextModule(module)
Arguments:
MHANDLE module Current module reference
Returns:
MHANDLE non-NULL Module handle
NULL Failure
Description:
This function returns a handle to module’s successor in the carousel whichcontains it.
The sense in which modules are sequenced is undefined. All that is guaranteed isthat a call to MCCLIFirstModule followed by successive calls toMCCLINextModule will eventually iterate through all the modules in thecarousel.
A NULL handle is returned if the function fails or if there are no more modules inthe carousel.
Ensigma Ltd. Page 84 of 955th Jul 1999 98-0003-001/1.3
MCCLINextCarouselInfo
Definition:
INT MCCLINextCarouselInfo(carousel, tag, desc,buflen)
Arguments:
CHANDLE carousel Carousel reference.
INT tag Descriptor tag.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a carousel. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeCarousel on Page??. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.
On successful completion, the return value is the length of the next descriptionassociated with tag. The result is truncated if necessary to fit within the descargument whose length is specified in buflen. Note that descriptive informationreturned by this function does not include a string terminator.
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is the
Ensigma Ltd. Page 85 of 955th Jul 1999 98-0003-001/1.3
number of bytes available, but no data is written.
Ensigma Ltd. Page 86 of 955th Jul 1999 98-0003-001/1.3
MCCLINextModuleInfo
Definition:
INT MCCLINextModuleInfo(module, tag, frequency, desc, buflen)
Arguments:
MHANDLE module Module reference.
INT tag Descriptor tag.
INT * frequency Module transmission frequency.
BYTE * desc Description buffer.
INT buflen Length of desc.
Returns:
INT >0 Success, length of descriptive information
<0 Success, no information defined for tag.
0 Failure
Description:
This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeModule on Page 37. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.
On successful completion, the return value is the length of the next descriptionassociated with tag. The result is truncated if necessary to fit within the descargument whose length is specified in buflen. Note that descriptive informationreturned by this function does not include a string terminator.
Ensigma Ltd. Page 87 of 955th Jul 1999 98-0003-001/1.3
The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is thenumber of bytes available, but no data is written.
Regardless of the values in tag and desc, the module transmission frequency (intransmissions per carousel turn) is always returned in the frequency argument.
Ensigma Ltd. Page 88 of 955th Jul 1999 98-0003-001/1.3
MCCLIOpenCarousel
Definition:
CHANDLE MCCLIOpenCarousel(source, path, timeout)
Arguments:
CHAR * source See description
CHAR * path See description
INT timeout Initial time-out in seconds.
Returns:
CHANDLE non-NULL Carousel handle
NULL Failure
Description:
This function opens a data carousel for access. The carousel is identified by thepath and source arguments. The precise interpretation of path and sourcesystem dependent. Typically, path specifies a directory in which carousel data iscached and source specifies the connection over which carousel messages arereceived. In a PC based implementation, source might specify a networkconnection to a packet dis-assembler task. In an integrated receiver environment,source might specify tuning and service information for the receiver to retrieveDAB packet data, while path might be unused.
Although data carousels include information which allows library functions toapply appropriate time-out values automatically, this information is only availableafter the carousel has been opened. The timeout argument specifies a time-outperiod for the initial carousel opening. If a zero timeout is specified, the functioncontinues indefinitely to try to open the carousel.
On successful completion, the function returns a handle to reference the carousel.
Ensigma Ltd. Page 89 of 955th Jul 1999 98-0003-001/1.3
MCCLIOpenModule
Definition:
MHANDLE MCCLIOpenModule(module, access)
Arguments:
MHANDLE module Module reference
INT access Access pattern code
Returns:
MHANDLE non-NULL New module handle
NULL Failure
Description:
This function opens a module identified by the module handle argument. Amodule must be opened before MCCLIReadModule orMCCLIPositionModule can be used.
The access argument takes one of the values listed in Section 5.3.
Module handles change when modules are opened or closed. After opening amodule, the handle value returned by this function should be used for futurereferences. The following example is typical in C—
MHANDLE mh; … if ((mh = MCCLIOpenModule(mh, 0)) == NULL) { /* error recovery */ } else { /* carry on using mh to refer to (open) module */ }
Ensigma Ltd. Page 90 of 955th Jul 1999 98-0003-001/1.3
MCCLIPositionModule
Definition:
INT MCCLIPositionModule(module, offset)
Arguments:
MHANDLE module Open module reference.
INT offset Byte offset from start of module.
Returns:
INT >= 0 New position.
< 0 Failure
Description:
This function sets the module read pointer to the specified offset from themodule start. If offset is negative, the function merely reports the currentposition. If offset is greater than the module size, the function fails.
A module must be opened with MCCLIOpenModule before this function can beused.
In some implementations, it may be helpful to set a module position some timebefore reading the data, since this may give the software time to pre-load internalcaches or perform other optimisations.
A module offset is set to zero when it is opened. Subsequently, unless this functionis called, module positions are incremented by successive MCCLIReadModulecalls.
Ensigma Ltd. Page 91 of 955th Jul 1999 98-0003-001/1.3
MCCLIReadModule
Definition:
INT MCCLIReadModule(module, buf, size)
Arguments:
MHANDLE module Open module reference
BYTE * buf Buffer to receive module data
INT size Number of bytes to read
Returns:
INT ≥ 0 Number of bytes actually read
< 0 Failure
Description:
This function reads size bytes from module, starting at is current position andreturning the data in buf. The return value will normally be the same as size,unless the end of the module is encountered, in which case the return value is thenumber of bytes actually read (possibly zero if the module is positioned at its endwhen the function is called).
The module read pointer is advanced by the number of bytes actually read.
A module must be opened with MCCLIOpenModule before this function can beused.
A negative return value indicates a failure.
Ensigma Ltd. Page 92 of 955th Jul 1999 98-0003-001/1.3
MCCLIStats
Definition:
INT MCCLIStats(carousel, hits, misses)
Arguments:
CHANDLE module Open carousel reference
INT * hits Returns number of cache hits
INT * misses Returns number of cache misses
Returns:
INT non-zero Success
0 Failure
Description:
This function provides statistics about the operation of the cache underlying thespecified carousel. Note that not all implementations necessarily implement acache. Those that do not will return zero for both hits and misses.
A zero return value indicates a failure.
Ensigma Ltd. Page 93 of 955th Jul 1999 98-0003-001/1.3
MCCLITimeout
Definition:
INT MCCLITimeout(carousel, scale)
Arguments:
CHANDLE carousel Carousel reference
INT scale time-out scale factor percentage
Returns:
INT ≥ 0 New scale factor
< 0 Failure
Description:
This function allows client applications to adjust the time-out values for thecarousel relative to the defaults. The scale parameter specifies a multiplier forthe default time-out values established by the library in response to the controlinformation in the carousel. These defaults are appropriate for good transmissionconditions. Applications may wish to extend the time-out periods to avoid failuresin less reliable conditions. It will rarely be sensible to reduce them relative to thedefaults.
The scale parameter is specified as a percentage. I.e., 100 represents the defaultvalue, 200 doubles all time-out values, 50 halves them. A value of 0 disables time-outs (i.e., library functions wait for ever). Small scale values may not behonoured accurately since the implementation will normally have some minimumgranularity in its time-out processing.
If the implementation does not support time-outs, then this function will returns 0,regardless of the scale value.
A negative return value indicates a failure.
Ensigma Ltd. Page 94 of 955th Jul 1999 98-0003-001/1.3
MCCLIZeroStats
Definition:
INT MCCLIZeroStats(carousel)
Arguments:
CHANDLE module Open carousel reference
Returns:
INT non-zero Success
0 Failure
Description:
This function zeroes the statistics associated with the cache underlying the specifiedcarousel. Note that not all implementations necessarily implement a cache. Inthose that do not, this function is ignored.
Note that a cache may be shared by all processes accessing the carousel. If morethan one process zeroes the statistics, the results reported by MCCLIStats mayseem confusing.
A zero return value indicates a failure.
Ensigma Ltd. Page 95 of 955th Jul 1999 98-0003-001/1.3
6. References
[1] ETSI. Digital Audio Broadcasting(DAB) Multimedia Object Transfer (MOT)protocol. EN 301 234.