⟦ca2d69151⟧

TextFile

% run this through LaTeX with the appropriate wrapper

\f

\chapter	{Pepy Optional Structure-Generator}\label{posy}
The \man posy(1) program is a compiler for specifications of abstract
syntaxes.

For those interested in trivia,
\pgm{posy} stands for
\underbar{P}epy
\underbar{O}ptional
\underbar{S}tructure-generator
(\underbar{Y}ACC-based).
The \man pepy(1) program is an ASN.1 compiler,
and the \man yacc(1) program,
of course,
is a compiler-compiler.

\f

\section	{Abstract Syntax Module}
The \pgm{posy} program reads a description of an {\em abstract syntax
module\/}
and produces the corresponding {\em C\/} structures along with an augmented
abstract syntax module.

The syntax of the input file corresponds almost exactly to the notation
described in \cite{ISO.PP.Syntax,CCITT.PP.Syntax}.
(But see Section~\ref{posy:deficiencies} on page~\pageref{posy:deficiencies}
for the details.)
As the ASN.1 language is rich in its notation,
the rules are not presented herein,
though Section~\ref{asn1:notation} on page~\pageref{asn1:notation} of \volone/
presents an incomplete treatment of the less substantive aspects of the
language.

An example of a complete abstract syntax module can be found in
Figure~\ref{POSexample} starting on page~\pageref{POSexample}.
This corresponds to the output produced by \man rosy(1) when given
the remote operations module in Figure~\ref{ROSexample} as input.

For our purposes,
the input file is relatively unimportant as it is usually generated by the
\pgm{rosy} program.
Hence,
the output from \pgm{posy} is where this chapter focuses.

\newpage
\tagrindfile{grindposy-1}{Example of an Abstract Syntax Module}{POSexample}
\newpage

\f

\section	{POSY Environment}
The \pgm{posy} program will produce two files after reading its abstract
syntax module.

\subsection	{C Language Structures}
For each type in the abstract syntax module,
\pgm{posy} will define a corresponding {\em C\/} language structure
(\verb"struct").

The rules that \pgm{posy} uses to generate the structures are fairly simple:
\begin{describe}
\item	[\verb"BOOLEAN":] represented as a \verb"char".

\item	[\verb"INTEGER":] represented as an \verb"int".
	If the \verb"INTEGER" type has a list of tagged values,
	then for each value:
\begin{quote}\small\begin{verbatim}
#define int_MODULE_TYPE_TAG value
\end{verbatim}\end{quote}
	as in:
\begin{quote}\small\begin{verbatim}
#define int_IMAGE_IntList_zero 0
\end{verbatim}\end{quote}

\item	[\verb"BIT STRING":] represented as a \verb"struct PElement"
	(these are described in Section~\ref{psap:bits} of \volone/).
	If the \verb"BIT STRING" type has a list of tagged bits,
	then for each bit:
\begin{quote}\small\begin{verbatim}
#define bit_MODULE_TYPE_TAG value
\end{verbatim}\end{quote}
	as in:
\begin{quote}\small\begin{verbatim}
#define bit_IMAGE_Version_version__1 0
\end{verbatim}\end{quote}
	In addition, one other definition is present:
\begin{quote}\small\begin{verbatim}
#define bits_MODULE_TYPE string
\end{verbatim}\end{quote}
	as in:
\begin{quote}\small\begin{verbatim}
#define bits_IMAGE_Version "\020\01version-1"
\end{verbatim}\end{quote}

\item	[\verb"OCTET STRING":] represented as a \verb"struct qbuf"
	(these are described in Section~\ref{psap:qbuf} of \volone/
	and Section~\ref{tsap:qbuf} of \voltwo/).

\item	[\verb"NULL":]	represented as a \verb"char".

\item	[\verb"SEQUENCE"/\verb"SET"/\verb"ANY":]
	represented as a \verb"struct PElement"
	(which are described throughout Chapter~\ref{libpsap} of \volone/).
	This format is used for those \verb"SEQUENCE"s or \verb"SET"s which
	contain no elements.

\item	[\verb"SEQUENCE OF"/\verb"SET OF":]
	by default, represented as a \verb"struct" with two elements,
	a linked-list.
	The first element is the type for set or sequence,
	the second element is a pointer to another instance of the structure.
	For example:
\begin{quote}\small\begin{verbatim}
SEQUENCE OF
    Format
\end{verbatim}\end{quote}
	might be translated as:
\begin{quote}\small\begin{verbatim}
struct element_IMAGE_4 {
    struct type_IMAGE_Format *Format;

    struct element_IMAGE_4 *next;
};
\end{verbatim}\end{quote}
	By using the \switch"h2" option (described below),
	an array structure can be generated instead.

\item	[\verb"SEQUENCE"/\verb"SET":] represented as a simple \verb"struct"
with an element for each member.
For example:
\begin{quote}\small\begin{verbatim}
Mail-Address ::= SEQUENCE {
    local[0]
        IMPLICIT GraphicString,

    domain[1]
        IMPLICIT GraphicString,

    options[2]
        IMPLICIT BITSTRING
}
\end{verbatim}\end{quote}
might be translated as:
\begin{quote}\small\begin{verbatim}
struct type_IMAGE_Mail__Address {
    struct type_UNIV_GraphicString *local;

    struct type_UNIV_GraphicString *domain;

    PE      options;
};
\end{verbatim}\end{quote}

\item	[\verb"CHOICE":] represented as a \verb"struct" containing an
\verb"int" and a \verb"union".
\begin{quote}\small\begin{verbatim}
CHOICE {
    file-name[0]
        IMPLICIT Filename,

    mail-address[1]
        IMPLICIT Mail-Address
}
\end{verbatim}\end{quote}
might be translated as:
\begin{quote}\small\begin{verbatim}
struct choice_IMAGE_0 {
  int     offset;
#define choice_IMAGE_0_file__name       1
#define choice_IMAGE_0_mail__address    2

  union {
     struct type_IMAGE_Filename *file__name;

     struct type_IMAGE_Mail__Address *mail__address;
  }   un;
};
\end{verbatim}\end{quote}

\item	[\verb"OBJECT IDENTIFIER":] represented as a \verb"struct OIDentifier"
	(these are described in Section~\ref{psap:oid} of \volone/).

\item	[\verb"MODULE.TYPE":] represented as a pointer to a
	\verb"struct" \verb"type_MODULE_TYPE".
\end{describe}

Although these rules might seem complicated,
in point of fact they are actually very straight-forward and regular.
The easiest way to gain familiarity with them is to run some abstract syntax
modules through \pgm{posy} and then view the resulting definitions.
Figure~\ref{CStructs} starting on page~\pageref{CStructs} presents the
{\em C\/} language structures corresponding to the abstract syntax module in
Figure~\ref{POSexample}.

\subsubsection	{Controlling the names that POSY generates}
One of the least friendly aspects of \pgm{posy} is the algorithm
it uses for choosing the names of {\em C\/} language structures being
generated.
The rules for choosing some names are fixed,
i.e., the top-level name generated for an ASN.1 type can not be changed.
However,
the names used for the parts of the \verb"struct"s generated by \pgm{posy} can
be controlled~---~to an extent using either (or both) of two techniques.

The first method takes advantage of the observation that \pgm{posy} uses
commentary tags in the ASN.1 definition, whenever possible, as variable names.
To revisit an earlier example:
\begin{quote}\small\begin{verbatim}
Mail-Address ::= SEQUENCE {
    local[0]
        IMPLICIT GraphicString,

    domain[1]
        IMPLICIT GraphicString,

    options[2]
        IMPLICIT BITSTRING
}
\end{verbatim}\end{quote}
might be translated as:
\begin{quote}\small\begin{verbatim}
struct type_IMAGE_Mail__Address {
    struct type_UNIV_GraphicString *local;

    struct type_UNIV_GraphicString *domain;

    PE      options;
};
\end{verbatim}\end{quote}
In each case, the names of the variables (e.g., \verb"local") were taken from
the commentary tag.
Note that if no tag is present,
\pgm{posy} must choose a name in a different fashion.
Hence,
the first level of control is to simply add short, descriptive commentary tags
to the remote operations module (the \pgm{rosy} program will preserve the
ASN.1 when it generates an abstract syntax module.

The second method is to augment the remote operations module with the
\verb"%[ ... %]" construct.
This construct allows the user to select both the name used for
intermediate structures that are generated and the name used for the
corresponding variable in certain cases.
Consider:
\begin{quote}\small\begin{verbatim}
ReadImage-INV ::= SEQUENCE {
    ...

    SEQUENCE OF %[ format_list $ head %]
        FORMAT

    ...
}
\end{verbatim}\end{quote}
might be translated as:
\begin{quote}\small\begin{verbatim}
struct type_IMAGE_ReadImage__INV {
    ...

    struct format_list {
        struct type_IMAGE_Format *element_IMAGE_4;

        struct format_list *next;
    } *head;

    ...
};
\end{verbatim}\end{quote}
More formally,
the
\begin{quote}\small\begin{verbatim}
%[ structure-name $ variable-name %]
\end{verbatim}\end{quote}
construct can be used to control the names used when generating intermediate
structures.
The construct can be used with any of these ASN.1 constructs:
\begin{itemize}
\item	\verb"SEQUENCE %[ ... %]"
\item	\verb"SEQUENCE OF %[ ... %]"
\item	\verb"SEQUENCE %[ ... %] { ... }"
\item	\verb"SET %[ ... %]"
\item	\verb"SET OF %[ ... %]"
\item	\verb"SET %[ ... %] { ... }"
\item	\verb"CHOICE %[ ... %] { ... }"
\end{itemize}
If the \verb"$ variable-name" portion of the construct is missing,
then only the structure name is taken from the construct,
the name of the corresponding variable is generated in the usual fashion.

NOTE: This facility is only allowed in the use of nested constructs. It is
not possible to override the names chosen for the top level constructs as
this would break the inheritence of structures names from other modules.
E.g.
\begin{quote}\small\begin{verbatim}
Defn ::= SEQUENCE %[ ... %] { ...
\end{verbatim}\end{quote}
is not supported but
\begin{quote}\small\begin{verbatim}
Defn ::= SEQUENCE {
        SEQUENCE OF %[ ... %] Thing,
        ...
\end{verbatim}\end{quote}
is.

\subsection	{Augmented Abstract Syntax Module}
In addition to the definition of {\em C\/} language structures,
\pgm{posy} will prepare an augmented abstract syntax module for use with the
\man pepy(1) program.
With this augmented module,
\pgm{pepy} will generate {\em C\/} code to translate {\em C\/} structures to
and from their corresponding abstract syntax.
As this is entirely an automatic process,
the contents of the augmented abstract syntax module are relatively
unimportant.

\newpage
\tagrindfile{grindposy-2}{Example of C Language Structures}{CStructs}
\newpage

\f

\section	{Known Deficiences}\label{posy:deficiencies}
\pgm{posy} uses essentially the same front-end as the \man pepy(1) program,
so it has some limitations in the ASN.1 syntax it can accept.
Consult Section~\ref{pepy:syntax} for the details.

When generating the augmented abstract syntax module for \pgm{pepy},
\pgm{posy} has a well-defined set of rules.
There are, however, some aspects which are still incomplete or subject to
change:
\begin{itemize}
\item	On determining if an \verb"OPTIONAL" element is present,
	for elements represented by a pointer (e.g., an \verb"OCTET STRING"
	and its corresponding \verb"struct qbuf" pointer),
	if the pointer is non-\verb"NULL" (non-zero valued),
	then the element is considered to be present.

\item	For elements which are represented by a scalar and not a pointer
	(e.g., an \verb"INTEGER" and its corresponding \verb"int"),
	an additional element, \verb"optionals", is created in the 
	structure. This is a
	bitmask value, with each bit indicating whether a particular
	element is present or not. So for optional element, a test is
	first required to see if this element is really present. e.g.,
	\begin{quote}\small\begin{verbatim}
	if (element -> optionals & opt_element_member1)
	    /* process element -> member1 */
	\end{verbatim}\end{quote}		 

\end{itemize}

\f

\section	{Running POSY}
Here are a few things to know when running \pgm{posy}.

\subsection	{Options}\label{posy:options}
The \pgm{posy} program has a few options to modify its behavior.

The \switch"a" switch directs \pgm{posy} to augment the \verb"#include" file
it generates with commentary text.

Normally, \pgm{posy} ignores all \pgm{pepy}-style augmentations except the
``verbatim'' actions occuring at the very beginning and end of the module.
The \switch"d" switch directs \pgm{posy} to ignore the verbatim actions as
well.

The \switch"f" switch directs \pgm{posy}  to generate {\em C\/} routines to
deallocate the structures it defines
(e.g., for type \verb"type_MODULE_type",
a routine called \verb"free_MODULE_type" is defined).
These are appended to the augmented module definition
(as a consequence,
use of the \switch"f" switch forces use of the \switch"d" switch).

The \switch"h" switch enables additional heuristics when \pgm{posy} generates
a {\em C\/} language structure definition.
These heuristics are used to make the \verb"struct"s more concise.
For example,
compare the definitions in Figure~\ref{CStructs} with those in
Figure~\ref{H0Structs} starting on page~\pageref{H0Structs}.
Both were derived from the abstract syntax module in Figure~\ref{POSexample},
but the definitions in Figure~\ref{H0Structs} was generated using the
\switch"h0" switch.
The current wisdom is that use of the \switch"h0" switch is a good thing.
Enabling any other option also results in enabling option \switch"h0".

The \switch"h1" switch
enables ``clever'' but non-unique structure naming.
Use of the \switch"h1" switch is {\bf not\/} recommended.

The \switch"h2" switch enables the generation of arrays rather than
linked-lists whenever possible.
For example,
compare the definitions in Figure~\ref{CStructs} with the fragment in
Figure~\ref{H2Structs} on page~\pageref{H2Structs}.
Both were derived from the abstract syntax module in Figure~\ref{POSexample},
but the fragment in Figure~\ref{H2Structs} was generated using the
\switch"h2" switch.
The current wisdom makes no pronouncement as to whether the \switch"h2" switch
is a good thing: some people prefer linked-lists, others perfer arrays.

The \switch"o" switch sets the name of the output file.
If this switch is not specified,
the standard output is used
(\pgm{posy} can not derive the name of the output file from the input file
since both should have extension \verb".py").

Normally, \pgm{posy} prints the name of each type as it works.
The \switch"s" switch disables this behavior.

\subsection	{Makefiles}\label{posy:make}
By convention,
input files to \pgm{posy} have the extension \verb".py".
This causes something of a problem with \man make(1) as the augmented
abstract syntax module which \pgm{posy} outputs should also have an extension
of \verb"py".

Since \pgm{posy} can not intuit the name of the output file from the input
file,
rather than starting with file \verb"module.py",
we assume we are starting with file \verb"MODULE-asn.py".
(Hence the reason for the complexity in Section~\ref{rosy:make}.)
Let us arbitrarily select the file named \verb"MODULE-types.py" for the
augmented abstract syntax module produced by \pgm{posy}.
Hence
\begin{quote}\begin{verbatim}
posy -o MODULE-types.py MODULE-asn.py
\end{verbatim}\end{quote}
will produce:
\begin{describe}
\item[\verb"MODULE-types.py":]	the augmented abstract syntax module;
				and,

\item[\verb"MODULE-types.h":]	the {\em C\/} language structures.
\end{describe}

Our \man make(1) rules are:
\begin{quote}\small\begin{verbatim}
MODULE-types.py:  MODULE-asn.py
                  posy $(POFLAGS) -o $@ MODULE-asn.rpy
MODULE-types.h:   MODULE-types.py
\end{verbatim}\end{quote}
Usually \verb"POFLAGS" is set to ``\verb"-f -h"''.

In our particular discipline,
we will generate two sets of files:
one for the invoker and the other for the performer.
\begin{quote}\small\begin{verbatim}
MODULE-Rtypes.c:  MODULE-types.py
          pepy -a ryr_advise $(PYFLAGS) -o $@ MODULE-types.py

MODULE-Itypes.c:  MODULE-types.py
                  pepy $(PYFLAGS) -o $@ MODULE-types.py
\end{verbatim}\end{quote}

\newpage
\tagrindfile{grindposy-3}{Example of C Language Structures (with -h0)}%
	{H0Structs}

\newpage
\tagrindfile{grindposy-4}{Example of C Language Structures (with -h2)}%
	{H2Structs}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦ca2d69151⟧ TextFile

Derivation

TextFile
