<!-- This file generated automatically by mtex2html(1) -->

<HTML>

<HEAD>

<TITLE>Manpage for the stub generator</TITLE>

</HEAD>

<BODY BGCOLOR="#ffffff" VLINK="#006633">

<H2>stablegen(1)</H2>

<H3>Name</H3>

<BLOCKQUOTE>

stablegen -- Generate stubs for stable objects.

</BLOCKQUOTE>

<H3>Syntax</H3>

<BLOCKQUOTE>

<DL>

<DT><B>stablegen</B><DD> [<B>-i</B> <I>Interfaces</I>] [<B>-o</B> <I>StableObjectIntf</I>]

[<B>-im</B> <I>StableObjectImpl</I>] [<B>-rm</B> <I>RepModule</I>] [options]

</DL>

<P>

</BLOCKQUOTE>

<H3>Description</H3>

<BLOCKQUOTE>

The program <I>stablegen</I> generates stubs for Modula-3 stable 

objects. Stable objects are Modula-3 objects whose state 

is backed up on the disk or other stable medium, so that it 

will survive program crashes.  <P>

It is not intended to be used from the command line. Use

<I>m3build</I> and the quake macros <I>stableobj</I> and <I>Stableobj</I>

instead to run the stub generator (see the m3build section

below).<P>

The command

<PRE>

    stablegen -i Data -o Data -im Impl -rm Rep

</PRE>

writes into "<I>Impl</I><TT>.m3</TT>" an implementation of the generic

interface "<TT>Stable(Data)</TT>". See this generic interface for the

specifications of the methods and procedures implemented by

<I>stablegen</I>.  Thus <I>Data</I> should be the name of an interface and

<I>Data</I>.T should name an object type; <I>stablegen</I> implements a

stable version of <I>Data</I>.T and writes the implementation to

"<I>Impl</I><TT>.m3</TT>".  <I>Impl</I> defaults to the objects interface

name as stated in the -o option with "<TT>Stable</TT>" prepended.  All

interfaces that contain revealations of <I>Data</I>.T must be listed

after the -i parameter.  The first interface of the list must contain the

most specific supertype of <I>Data</I>.T. In most cases this will be <I>Data</I>

itself. But if <I>Data</I> does not state any more specific supertyp of 

<I>Data</I>.T than <TT>ROOT</TT>, the interface listet after the -i will be the

one containing the most specific revealation.<P>

To complete your program, you

should include in the file "<I>Impl</I><TT>.i3</TT>" the text

<PRE>

    INTERFACE Impl = Stable(Data) END Impl.

</PRE>

The implementation of stable objects consists of two modules.

The first is generated by <I>stablegen</I>, the second is an

instantiation of the generic module "<TT>StableRep</TT>". The name of

this second module is stated after the -rm option. It

defaults to the name of the generated implementation <I>Impl</I>

with "<TT>Rep</TT>" appended. If both module names are defaulted,

"<TT>Stable</TT>Data<TT>Rep</TT>" will be used for the generic's instantiation.

So in the file "<I>Rep</I><TT>.i3</TT>" you will

need the text

<PRE>

    INTERFACE Rep = StableRep(Impl) END Rep.

</PRE>

And the file "<I>Rep</I><TT>.m3</TT>" looks like

<PRE>

    MODULE Rep = StableRep(Impl) END REP.

</PRE>

The m3build macros will also generate all these files (see below). 

</BLOCKQUOTE>

<H3>Classifying the methods</H3>

<BLOCKQUOTE>

The interface "<I>Data</I><TT>.i3</TT>" presented to the stub generator

must contain a pragma that lists all methods of <I>Data</I>.T that modify

the state of the object.  The pragma has the form

<PRE>

    <* STABLE UPDATE METHODS m_1, ..., m_k *>

</PRE>

where the m's are the names of the update methods of <I>Data</I>.T.  The

stub generator will override these methods to log their arguments

before calling the corresponding method of the supertype.  The stub

generator will not override the other methods of <I>Data</I>.T; the

stable object will simply inherit them from its supertype.  The pragma

may appear more than once (the list stated in the second pragma will

be appended to those methods already mentioned).  You may use <TT>ANY</TT>

instead of a list of methods in which case all methods of the object

are treated as update methods.

</BLOCKQUOTE>

<H3>Options</H3>

<BLOCKQUOTE>

The stub generator is based on the Modula 3 toolkit, therefore the

other options defined by the toolkit are available.  See the manpage

for <I>m3fe</I> for a list of these options.  In particular, it is

possible to set the search path used by the stub generator with the

<TT>-T</TT><I>x</I> option, where <I>x</I> is the name of a map file

generated by m3build.  The name of the map file associated with

package <I>P</I> and build directory <I>B</I> is <TT>P/B/.M3IMPORTS</TT>. It is also

possible to set a specific search path with the <TT>-D</TT> option, though

this is usually more trouble than it is worth.<P>

You may use -help instead of any other options to get a list of available

options.

</BLOCKQUOTE>

<H3>Restrictions</H3>

<BLOCKQUOTE>

As mentioned before, not all types Data.T are valid for stub generation.

The following restrictions apply.  The stub generator will not 

produce stubs for types that violate any of the restrictions. 

<OL>

<LI>      No argument to an update method may be of type <TT>PROCEDURE</TT> 

or have a component of type <TT>PROCEDURE</TT>.

<LI>      The name of the update methods listed in the <TT>STABLE UPDATE METHODS</TT>

        pragma must not conflict with the names of the stable object

methods as declared in <TT>Stable.ig</TT>.

</OL>

The marshaling of parameters to update methods is performed as 

for network objects, as specified in the documentation for <I>stubgen</I>. 

</BLOCKQUOTE>

<H3>Generating stubs using m3build</H3>

<BLOCKQUOTE>

Currently the macros described here only support the defaults

for the filenames of the generated module and the instatiated

generic part of the implementation.<P>

It is possible to manage stub generation using <I>m3build</I>.  You must

put the following line in your <I>m3makefile</I>, prior to any

occurrences of one of the macros:

<PRE>

    import("stable")

</PRE>

To state that an interface <I>Data</I> contains a stable object use one

of the macros:

<PRE>

    stableobj("Data", [])

    Stableobj("Data", [])

</PRE>

(<I>Stableobj</I> sets the visability of the stable object's interface

to visible, <I>stableobj</I> to hidden) which generates stubs for

<I>Data</I>.T, storing them in "<TT>Stable</TT><I>Data</I><TT>.m3</TT>". It

generate the instatiation of <TT>Stable.ig</TT> in

"<TT>Stable</TT><I>Data</I><TT>.i3</TT>" and the instatiation of the generic

part of the implementation (<TT>StableRep</TT>) in

"<TT>Stable</TT><I>Data</I><TT>Rep.i3</TT>" and

"<TT>Stable</TT><I>Data</I><TT>Rep.i3</TT>". It also arranges for the

generated stubs to be compiled and linked into the program.<P>

The second parameter of the macros is a list of interfaces that

<I>Data</I> depends on. The first in the list must be the interface

containing the most specific exported revealation of Data.T.

The following interface names are only used to trigger <I>stablegen</I>

correctly. If one of those interfaces are changed, <I>stablegen</I>

will be run again on the next call of <I>m3build</I>.<P>

If the second parameter is the empty list, it is assumed that

"<I>Data</I><TT>.i3</TT>" is the only interface containing definitions

necessary for <I>Data</I>.T.<P>

The rules for importing interfaces during stub generation are 

the same as those for compilation under <I>m3build</I>. See the <I>m3build</I> 

manpage for further detail.

</BLOCKQUOTE>

<H3>Copyright</H3>

<BLOCKQUOTE>

Copyright (C) 1994, Digital Equipment Corporation.<BR>

Distributed only by permission.<BR>

Last modified on Thu Jan 19 14:28:03 PST 1995 by kalsow  

     modified on Tue Sep 27 11:52:22 PDT 1994 by weich   

<BR>

</BLOCKQUOTE>

</BODY>

</HTML>