Data type descriptions reside in type declaration files, which end with the suffix .t (for “type”). You create and name the type declaration file when you define the new data type.

This is the basic structure of a modulename.t file:

The keywords used in each type definition are defined in “Syntax.”

As can be seen from this outline of the modulename.t file contents, the root type is a struct, similar to a C structure. The building blocks of the type include other structs, enumerations, unions, and arrays of any of these.

All data types have names. The naming conventions are similar to those in C, that is, the first character must be a letter, but the rest of the name may contain digits and the underscore (_). Data type names may be of any length and case is significant. The type filename and data type name must agree. For example, if the data type is to be called myCylinder, the file must be named myCylinder.t. If the file is named bxMyCylinder.t, the data type must be called bxMyCylinder.

A single type declaration file may contain several type declarations if the root data type contains subsidiary data types. The order of data type declarations in the file is not important; they are sorted during the translation into C.

These conventions apply in this chapter:

There is a small set of special keywords used in defining an Explorer data type.

There are special language symbols for a few of these keywords.

Other keywords are used in-place in subsequent sections of the language definition.

Declarations in the Explorer typing language (ETL) are more constrained than in C. These are the basic rules for data type definitions:

There is a a standard naming convention for data types defined by Explorer. A standard scheme makes it easy to recognize the different forms of names used in a type and to identify their purpose.

Here are the standard Explorer conventions:

typedef struct {  } cxData; 
typedef struct {  } cxPyramidDictionary; 

long         nDim; 
long         dims;   
cxPrimType   primType;

typedef enum {
        cx_compress_none, 
        cx_compress_unique, 
        cx_compress_multiple 
} cxCompressType;

typedef enum {
        cx_prim_byte, 
        cx_prim_short,
        cx_prim_long, 
        cx_prim_float, 
        cx_prim_double, 
        cx_prim_string 
} cxPrimType;

These are the basic scalar types that Explorer will accept.

The grammar fragments are:

You can define, as a new type, an enumeration of consecutive named constants starting at zero.

An Explorer type includes structures composed of the basic scalar types in three forms:

The composition rules may be applied both to scalars and to other composed types. Thus, you may construct an array of integers, and also an array of enumerated constants, structures, unions, or arrays,. The language syntax for these elements is shown below.

In C, it is possible to declare a structure without defining that structure as a new type. In Explorer, you must name all new types in order to declare members of that type. The typedef statement defines a new type from a simple type, a struct, or an enumeration. It can also be used to create a new type from a previously created type, in effect creating a pseudonym for an existing type. These operations are defined below:

STANDARD_TYPE is a name of type standard_definition; REFERENCE_TYPE is a name of type reference_count_definition.

Both C header files and other Explorer type files (with a .t suffix) may be included into a type file using the standard C preprocessor syntax, which uses a # character in the first column. If a file TypeA.t needs definitions from file TypeB.t, it must include TypeB.t in a #include statement.

Inclusion of an Explorer type file has the effect of incorporating the included file into the current typing file. This allows you to reuse previously defined types; for example, the cxPyramid type uses the cxLattice type. Inclusion of a modulename.t file also means the corresponding modulename.h file will be included in the resulting C header file.

Inclusion of a C header file has no effect on the actual type processing, but only serves to put the same include statement into the resulting C header file.

FILENAME is a name referring to a file in the file system, located in $EXPLORERHOME/include/cx or in the current directory.

There are two forms of structures in the Explorer typing language, in-line and reference-counted structures. Reference-counted structures are denoted by the root and shared keywords in the typing language. Both keywords imply reference-counting, but root has other meanings as well, described below.

     typedef struct { 
           int b; 
     }oneInt; 

    typedef struct { 
          int a; 
          oneInt i; 
     } twoInt;

    twoInt two;

   shared typedef struct { 
          float b; 
   } oneFloat; 	 

   typedef struct { 
           float a; 
           oneFloat i; 
   } twoFloat;

   twoFloat two;

Differences Between Structures

There are two differences to be noted in accessing the in-line and the reference-counted structures.

The first difference is that a shared member will always be a pointer to a structure, rather than an in-line structure. An array of a shared type is really an array of pointers to shared structures.

The following example shows a structure member two with two members, two.n and two.i, where the several double precision numbers in two are two.i[j]->b, for values of j between 0 and n-1:

shared typedef struct { double b; } oneDouble; typedef struct { int n; oneDouble i[n]; } doubleArray; doubleArray two;

The second main difference, and the reason why there is a distinction between in-line and reference-counted of structures, is that the reference-counted structure has some additional information that allows the structure to be shared between two or more data sets. Because the reference-counted structure is referred to by a pointer, several data sets can hold the same pointer: a single update of the shared data affects all data sets. It is impossible for two or more structures to share a single in-line structure.

---

Note: The user should not change values within the reference-counting structure, nor rely on the form or content of that structure, as it is subject to change in subsequent releases of Explorer.

---

At most, one variable may be declared in each member statement. This is distinct from the C style, where multiple variables of the same type may be declared together. The grammar fragment is:

simple_type VAR;

For example, this is legal in Explorer:

   int a;       /* Legal */ 
   int b;

but this is not:

   int a, b;    /* Illegal */

The most general form of a member declaration is:

However, the example

simple_type VAR;

is actually much simpler than the general form. It has no closed keyword, uses an integer simple_type, is not an array, and has no label.

Other simple-typed members include:

int a;
unsigned long b[n] “Value of B”;
closed   int c; 
float    d[ a, a, 3 ]; 
double   e    "Real Number E"; 

Table 8-2 lists the parts of a simple-typed member.

You could also use common Explorer types in this example, where you use other defined_type types:

cxLattice a; 
cxLattice b[10]; 
closed cxLattice c "Not visible in Module Builder";

Explorer arrays can be dimensioned by a combination of integer constants, scalar integer variables, and arrays of integers. It is important to understand how the array declaration in the Explorer typing language translates into an array of bytes in memory and how to access that memory in C, C++, or Fortran.

All Explorer arrays are represented by 1-D arrays of memory. The indexing into this long array depends on the order of the array bounds in the array declaration. Array bounds are given in the normal Fortran order, so that the first bound represents the fastest varying index. For example, the following 3-D array ThreeD has shape m by n by p, with the m-based index varying fastest:

int m; 
int n; 
int p; 
int ThreeD[ m, n, p ];

The equivalent Fortran declaration is:

integer ThreeD(m, n, p)

The equivalent C or C++ declaration is:

Arrays can have integer constants or scalars as bounds. The constant or the value of the variable is used at run-time to determine the array length. Arrays can also have other arrays as dimensioning variables, as in the data array of cxLattice;

long     nDim; 
long     dims[nDim]; 
double   values[nDataVar, dims];

In this case, the array contents are treated as a list of scalar values, so that the previous example is equivalent to the following one for nDim = 3:

long      dims[3];  
double    values[ nDataVar, dims[0], dims[1], dims[2] ];

Thus the length of an array can be calculated as the product of all of its dimensioning bounds, where a dimensioning array (for example, dims) has a product equal to the product of its integer contents.

BOUND is a name of type integer or an array of type integer

Most members in a type should be assigned labels. Labels are used in the creation of automatically generated API routines for programmatic access to the data types. All members that are to be accessed through this API must have labels. Labels are also used in the Module Builder Connections window for data type member wiring.

Members that can get labels include scalars, arrays, and reference-counted structures. Members that do not get labels include in-line structures (see below), switch structures, and type definitions.

The author of the type file may assign labels to structure members. The label is a quoted text string following the variable name and optional array bounds. Table 8-3 how the scalars are labeled in a lattice.

Explorer type files use the standard C comment syntax, which is a block of text surrounded by the delimiters /* and */. Comments may be inserted anywhere in the file.

The comma “,” does not work in ETL as it does in C. You must define each variable on a separate line. For example, this structure in C:

typedef struct {
       float x,y; /* Invalid in ETL */
} mine;

looks like this in ETL:

typedef struct {
       float x; /* Correct in ETL */
       float y;
} mine;

The ETL does not allow you to explicitly declare pointer variables in Explorer types. Thus you may not declare an object by reference. This is because Explorer transcription routines need to know the size of the object pointed to, and a pointer to an object could be a pointer to one or many consecutive objects. However, in the generated C structure, two Explorer type members are represented as pointers to allow for multiple references. These are the array and the reference-counted structures (shared and root structures). The array has a variable dimension determined at run-time, so it cannot be stored in-line in the containing structure. The reference-counted structures are described above.

ETL must be able to calculate the size of every non-in-line structure it manipulates so that it can handle the transcription of data properly. To do this, it needs a name for the structure.

This means you must use a typedef statement to name all such structures, and the name must be unique. If the structure is anonymous (or if the name is duplicated), there is no name handle for ETL to use when calculating its size.

This example illustrates the premise that all types must be explicitly and uniquely named. You may not declare an Explorer type of the following form, for Explorer would have no way of naming the structure or of representing its size and contents internally:

struct { 
    int a; 
    int b; 
} s;        /* WRONG: Can't have an anonymous structure. */

The correct way to do this is to define a new type:

typedef struct { 
   int a; 
   int b; 
} twoInt;   /* RIGHT: Structure has a type. */

twoInt s;

This example illustrates the premise that an embedded struct must be a named type unless it is in-line

typedef struct {
   int n;
   struct {

float x; (Wrong: Undefined (no name), and therefore anonymous structure. No name available for computing the size of “foo.”)

      float y;
   } foo[n];
} mine;

typedef struct {
   float x;
   float y;   (The foottype is first defined in its own typedef)
} footype;

typedef struct {
    int n;  (Size of “foo” computable from n* sizeof(footype).)
    footype foo[n];
} mine;

Array bounds must exist at the same level of lexical scope where they are used. Furthermore, the array bound member must precede the array in which it is used in the structure. The following examples illustrate this concept.

In this example, the variables m and n are used without having been defined.

typedef struct { 
     int    len;
     float  vec[len];/* Correct scope for len  */ 
     float  box[m,n];/* Incorrect scope for m and n. */ 
} Example1;

Here, the first use of len occurs before it has been defined.

typedef struct { 
      float   vec[len];     /* Len not yet set -- incorrect.*/ 
      int     len
      float    box[len,len];/* Len set -- correct. */ 
} Example2; 

The member order in this fragment of cxLattice is correct:

root typedef struct {
     long   nDim            “Num Dimensions”;
     long   dims[nDim]      “Dimensions Array”;
     ...
     cxLattice;

But this order is wrong, because nDim is used before it has been defined:

root typedef struct {
    long   dims[nDim]   “Dimensions Array”
    long  nDim          “Num Dimensions”;
    ...
} cxLattice;

---

Note: Shared memory types, such as cxData, cxCoord, and cxLattice, may be defined in any order.

---

shared typedef struct { 
   long            nDim; 
   long            dims[nDim]; 
   long            nDataVar       "Num Data Variables"; 
   cxPrimType      primType       "Primitive Data Type"; 
   switch          (primType) { 
      case cx_prim_byte: 
           char     values[nDataVar, dims]  "Data Array"; 
      case cx_prim_short: 
            short    values[nDataVar, dims] "Data Array"; 
      case cx_prim_long: 
           long     values[nDataVar, dims]  "Data Array"; 
      case cx_prim_float: 
           float    values[nDataVar, dims]  "Data Array"; 
      case cx_prim_double: 
           double   values[nDataVar, dims]  "Data Array"; 
     } d; 
} cxData;

To be useful to the Explorer programmer, the Explorer typing system provides a data structure that can be accessed through a conventional programming language. Explorer types are translated into C structures, which can be accessed directly from C or through a functional application programmer interface (API) from C, C++, or Fortran.

Here are some points to note about the structure:

Labels for the structure members are not reflected in the resulting C structure, but are used to create the API for accessing the data structure and the menus in the Module Builder.

The switch statement is translated into a union of variant structures in the resulting C code. Each variant structure is named by the enumerated constant value that selects the variant. For example, this Explorer structure translates into the subsequent C structure:

Explorer switch structure:

   switch (myType) { 
   case cx_my_long: 
       long    a; 
   case cx_my_float: 
        float         b;
    case cx_my_double: 
        double  d ; 
   } s;

C equivalent (union structure):

 union {
        struct { 
              long  a; 
                    } cx_my_long; 
        struct {    
              float        b; 
                 } cx_my_float; 
        struct { 
               double d;
                 } cx_my_double; 
   } s;

An important detail to notice here is that the structure members are accessed in C as members:

  s.cx_my_long.a 
  s.cx_my_float.b 
  s.cx_my_double.d

The closed keyword has no effect on the generated C structure.

Let us suppose that you have created the data structure for the myCylinder data type by using the grammar and principles described in “Using the ETL.” You have saved it in a file called myCylinder.t.

To build the data type and install it in weExplorer, follow these steps.

This command installs the made files in $EXPLORERUSERHOME. These files are:

include/cx/myCylinder.t
include/cx/myCylinder.h
include/cx/myCylinder.inc
include/cx/myCylinder.api.h
include/cx/myCylinder.api.inc
lib/libmyCylinder.a
types/myCylinder.type
man/man3/myCylinder.3

When you run make install, Explorer translates the language in the type declaration file into C and creates the myCylinder.type file. It also creates the header file for the data type, myCylinder.h and the include file myCylinder.inc. You include this file in the user function file (for example, in ReadCyl.c) when you build a module that makes use of the Cylinder data type (for example, to read cylinder data).

The files have these uses:

Figure 8-1 shows the sequence of events in the build process.

Figure 8-1. Explorer Types Information Flow

The data types are visible to users at several places in the GUI (graphical user interface). In the Map Editor, the user sees the data type on each module port when a map is wired. The Map Editor uses the data types and auxiliary constraint information to determine which ports are valid for a given wiring, hence the IO pad highlighting to illuminate potential wiring destinations.

In the Module Builder, the module writer sees a menu of all available port data types when creating input and output ports. Input and output ports can be of any root data type. The Module Builder must configure these menus at run time from the wiring connections made in the Connections panel. Description strings appear as menu items in the Connections window.

Module communication across socket links, for example between modules on different hosts or on a single host with non-shared memory, requires that both the sender and receiver know how to transmit the data structure. Explorer data structures may have variably sized portions, pointers to shared pieces, and may even be recursive. Each module is compiled with the necessary information about its constituent data types, so that it can correctly transmit, read, and write those types. Furthermore, some modules, such as For and While, must be able to receive and send data structures that were not known when they were built.

Here is a list of the types of members and their functions. The type is myType, the label is Label, and a trailing name indicates the form of access.

Functions for Reference-counted Structure

The reference-counted structures get these routines:

myTypeAlloc()		Allocates the structure
myTypeRead()		Reads an Explorer transcribed (ASCII or binary) type file
myTypeWrite()		Writes an Explorer transcribed (ASCII or binary) type file
myTypeDup()		Duplicates all contents of the data structure

---

Note: cxDataRefDec() is used to delete all reference-counted structures.

---

Fortran wrappers are generated for almost all user-defined type API routines. They follow the usual rules for the Explorer Fortran API:

char **myTypeItemGet( myType* src, cxErrorCode *ec );

int         nFiles               “Number Files"; 
string      filename[ nFiles ]   "File Names";

The manual pages for the API, also automatically generated, will be installed in $EXPLORERUSERHOME/man/man3. To set the value of the environment variable EXPLORERUSERHOME, refer to “Defining EXPLORERUSERHOME.”

This directory is probably not searched by default by the man command, but you can add this directory to your search path by defining the MANPATH variable as follows:

setenv MANPATH /usr/catman:/usr/man:$EXPLORERUSERHOME/man

This code uses the user-defined data type, tstLattice. It takes in an Explorer lattice and generates a tstLattice. The easiest way to demonstrate this is to connect GenLat to the input. The code resides in /usr/explorer/src/UDTmods/test.c and /usr/explorer/src/UDTmods/test2.f.

#include <cx/DataAccess.h>
#include <cx/DataTypes.h>
#include <cx/DataOps.h>
#include <cx/tstLattice.api.h>
#define CLEAN(A,B,C) if(memclean((void *)A,B,C)) return

int memclean(void *ptr, cxErrorCode ier, tstLattice *lat)
{
  if((ptr == NULL) || (ier != cx_err_none))
  {
    cxDataRefDec(lat);
    return 1;
  } else { 
    return 0;
  }
}

void test( cxLattice *inLat, tstLattice **outLat )
{
  cxCoord *coord;
  cxData *data;
  tstData *tdata;
  cxErrorCode err;
  void *inDataArray,*outDataArray;
  int num_bytes,i;
  long nDim,*dims,hasData,nDataVar,hasCoord,nCoordVar;
  cxPrimType primType;
  cxCoordType coordType;
  char **labels;

  cxLatDescGet(inLat,&nDim,&dims,&hasData,&nDataVar,&primType,
               &hasCoord,&nCoordVar,&coordType);
/* make the complete tstLattice structure and all components */
  *outLat = tstLatticeAlloc(nDim,dims);
  if(*outLat == NULL) return;
  tdata = tstDataAlloc(nDim,dims,nDataVar,primType);
  CLEAN(tdata,0,*outLat);
  tstLatticeDataStructureSet(*outLat,tdata,&err);
  CLEAN(tdata,err,*outLat);
  outDataArray = tstDataDataArrayAlloc(tdata);
  CLEAN(outDataArray,0,*outLat);
  tstDataDataArraySet(tdata,&outDataArray,&err);
  CLEAN(tdata,err,*outLat);
  cxLatPtrGet(inLat,&data,&inDataArray,&coord,NULL);
  tstLatticeCoordStructureSet(*outLat,coord,&err);
  CLEAN(tdata,err,*outLat);

/* It's all allocated, now fill it */
  tstDataMinimumSet(tdata,0.0,&err);
  CLEAN(tdata,err,*outLat);
  tstDataMaximumSet(tdata,1.0,&err);
  CLEAN(tdata,err,*outLat);
  tstDataEmptySet(tdata,-999.,&err);
  CLEAN(tdata,err,*outLat);
  labels = tstDataDataLabelsGet(tdata,&err);
  CLEAN(tdata,err,*outLat);
/* I lied. Now allocate the label strings long-hand */  
  for(i=0;i<nDataVar;i++)
  {
    labels[i] = cxDataMalloc(sizeof(“label 99”)+1);
    CLEAN(labels[i],err,*outLat);
    sprintf(labels[i],”label %d”,i);
  }
  num_bytes = cxDataPrimSize(data);
  num_bytes *= cxDimsProd(nDim,dims,nDataVar);
  bcopy(inDataArray,outDataArray,num_bytes);    
}

#define CLEAN(A,B,C) if(memclean(A,B,C) .gt. 0) return
c     fortran example for user-defined types
c
      subroutine test(inLat, outLat)
      implicit none
      integer inLat, outLat, coord,data,err,tdata, memclean
      character*1 inDataArray(1),outDataArray(1)
      integer nDim,dims(1),hasData,nDataVar,hasCoord,nCoordVar
      integer primType, coordType
      character*10 labels
      integer plabels(1),inull,num_bytes,i
      real zero,one,empty
      pointer (pdims,dims)
      pointer (pdims1,dims1)
      pointer (pin, inDataArray)
      pointer (pout, outDataArray)
      pointer (pplabels, plabels)
      pointer (ptmp, labels)
      pointer (null,inull)
      parameter (zero = 0.0 ) 
      parameter (one = 1.0 ) 
      parameter (empty = -999.)
        integer tstLatticeAlloc, tstDataAlloc, tstDataDataArrayAlloc
      integer tstDataDataLabelsGet
      integer cxDimsProd, cxDataPrimSize,cxDataMalloc

      call cxlatdescget(inLat,nDim,pdims,hasData,nDataVar,
     +   primType,hasCoord,nCoordVar,coordType)
      outLat = tstLatticeAlloc(nDim,dims)
      if(outLat .eq. 0) return
      tdata = tstDataAlloc(nDim,dims,nDataVar,primType)
      CLEAN(tdata,0,outLat)
      call tstLatticeDataStructureSet(outLat,tdata,err)
      CLEAN(tdata,err,outLat)
      pout = tstDataDataArrayAlloc(tdata)
      CLEAN(pout,0,outLat)
      call tstDataDataArraySet(tdata,pout,err)
      CLEAN(tdata,err,outLat)
      call cxLatPtrGet(inLat, data, pin,coord,null)
      call tstLatticeCoordStructureSet(outLat, coord,err)
      CLEAN(tdata,err,outLat)
      call tstDataMinimumSet(tdata,zero,err)
      CLEAN(tdata,err,outLat)
      call tstDataMaximumSet(tdata,one,err)
      CLEAN(tdata,err,outLat)
      call tstDataEmptySet(tdata,empty,err)
      CLEAN(tdata,err,outLat)
      pplabels = tstDataDataLabelsGet(tdata,err)
      CLEAN(tdata,err,outLat)
      do i=1, nDataVar
         plabels(i) = cxDataMalloc(10)
         CLEAN(plabels(i),err,outLat)
         ptmp = plabels(i)
         write(labels,”('label ',i2,a1)”)i,0
      end do
        num_bytes = cxDataPrimSize(data) * cxDimsProd(nDim,dims,nDataVar)
      do i=1,num_bytes
         outDataArray(i) = inDataArray(i)
      end do
      return
      end
c
c     cleanup routine
c
      integer function memclean(ptr,errcode,tstlat)
      implicit none
      integer ptr, errcode, tstlat, retcode
      if((ptr .eq. 0) .or. (errcode .ne. 0))then
         call cxDataRefDec(tstlat)
         memclean = 1
      else
         memclean = 0
      endif
      return
      end

This module reads in a tstLattice user-defined type and prints out some specific information from it. The code resides in /usr/explorer/src/UDTmods/print.c and /usr/explorer/src/UDTmods/print.f.

#include <cx/DataAccess.h>
#include <cx/DataTypes.h>

#include <cx/tstLattice.api.h>
void prt( tstLattice *inlat )
{
  char **f;
  tstData *outData;
  long i, nDV;
  float mt;
  cxErrorCode err;
  
  outData = tstLatticeDataStructureGet(inlat,&err);
  f = tstDataDataLabelsGet(outData,&err);
  nDV = tstDataNumDataVariablesGet(outData,&err);
  for(i=0;i<nDV;i++)
  {
    printf(“label %d = %s\n”,i,f[i]);
  }
  mt = tstDataEmptyGet(outData,&err);
  printf(“ Empty value = %f\n”,mt);
}

    subroutine prt(inLat)
      integer inLat,outData
      real tstDataEmptyGet
      integer tstLatticeDataStructureGet
      integer tstDataNumDataVariablesGet
      outData = tstLatticeDataStructureGet(inLat,err)
c
c     there is no fortran call for getting an array of
c     strings. So we cannot say 
c
c      f = tstDataDataLabelsGet(outData,err)
c
      nDV = tstDataNumDataVariablesGet(outData,err)
      empty = tstDataEmptyGet(outData,err)
      print *,” Empty value = “,empty
      return
      end

There are two modules, ReadtstLattice and WritetstLattice, that allow the user to read and write ASCII or binary versions of the user-defined type. The code for these modules is auto-generated. The two routines are tstLatticeWrite and tstLatticeRead.