Big-Data-HPC-Platform/docs/ECLLanguageReference/ECLR_mods/SpecStruc-Interface.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<sect1 id="INTERFACE_Structure">
  <title>INTERFACE Structure<indexterm>
      <primary>INTERFACE Structure</primary>
    </indexterm></title>

  <para><emphasis>interfacename </emphasis><emphasis role="bold">[
  (</emphasis><emphasis> parameters </emphasis><emphasis role="bold">) ] :=
  INTERFACE<indexterm>
      <primary>INTERFACE</primary>
    </indexterm> [ (</emphasis><emphasis> inherit </emphasis><emphasis
  role="bold">) ]</emphasis><emphasis role="bold"> </emphasis></para>

  <para><emphasis>members;</emphasis></para>

  <para><emphasis role="bold">END;</emphasis></para>

  <informaltable colsep="1" frame="all" rowsep="1">
    <tgroup cols="2">
      <colspec align="left" colwidth="122.40pt" />

      <colspec />

      <tbody>
        <row>
          <entry><emphasis>interfacename</emphasis></entry>

          <entry>The ECL definition name of the interface.</entry>
        </row>

        <row>
          <entry><emphasis>parameters</emphasis></entry>

          <entry><para>Optional. The input parameters to the
          interface.</para></entry>
        </row>

        <row>
          <entry><emphasis>inherit</emphasis></entry>

          <entry>Optional. A comma-delimited list of INTERFACE structures
          whose <emphasis>members</emphasis> to inherit. This may not be a
          passed parameter. Multiple <emphasis>inherited</emphasis> interfaces
          may contain attributes with the same name if they are the same type
          and receive the same parameters, but if those
          <emphasis>inherited</emphasis> <emphasis>members</emphasis> have
          different values defined for them, the conflict must be resolved by
          overriding that <emphasis>member</emphasis> in the current
          instance.</entry>
        </row>

        <row>
          <entry><emphasis>members</emphasis></entry>

          <entry>Definitions, which may be EXPORTed or SHARED. These may be
          similar to fields defined in a RECORD structure where only the type
          and name are defined—the expression that defines the value may be
          left off (except in some cases where the expression itself defines
          the type of definition, like TRANSFORM structures). If no default
          value is defined for a <emphasis>member</emphasis>, any MODULE
          derived from the INTERFACE must define a value for that
          <emphasis>member</emphasis> before that MODULE can be used. These
          may not include other INTERFACE or abstract MODULE
          structures.</entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>

  <para>The <emphasis role="bold">INTERFACE </emphasis>structure defines a
  structured block of related <emphasis>members</emphasis> that may be passed
  as a single parameter to complex queries, instead of passing each attribute
  individually. It is similar to a MODULE structure with the VIRTUAL option,
  except errors are given for private (not SHARED or EXPORTed)
  <emphasis>member</emphasis> definitions.</para>

  <para>An INTERFACE is an abstract structure—a concrete instance must be
  defined before it can be used in a query. A MODULE structure that inherits
  the INTERFACE and defines the values for the <emphasis>members</emphasis>
  creates the concrete instance for use by the query.</para>

  <para>Example:</para>

  <programlisting>HeaderRec := RECORD
  UNSIGNED4 RecID;
  STRING20  company;
  STRING25  address;
  STRING25  city;
  STRING2   state;
  STRING5   zip;
END;
HeaderFile := DATASET([{1,'ABC Co','123 Main','Boca Raton','FL','33487'},
                       {2,'XYZ Co','456 High','Jackson','MI','49202'},
                       {3,'ABC Co','619 Eaton','Jackson','MI','49202'},
                       {4,'XYZ Co','999 Yamato','Boca Raton','FL','33487'},
                       {5,'Joes Eats','666 Slippery Lane','Nether','SC','12345'}
                      ],HeaderRec);

//define an interface
IHeaderFileSearch := INTERFACE
  EXPORT STRING20 company_val;
  EXPORT STRING2   state_val;
  EXPORT STRING25  city_val := '';
END;

//define a function that uses that interface
FetchAddress(IHeaderFileSearch opts) := FUNCTION
        
  //define passed values tests
  CompanyPassed := opts.company_val &lt;&gt; '';
  StatePassed := opts.state_val &lt;&gt; '';
  CityPassed := opts.city_val &lt;&gt; '';

   //define passed value filters
   NFilter := HeaderFile.Company = opts.company_val;
   SFilter := HeaderFile.State = opts.state_val;
   CFilter := HeaderFile.City = opts.city_val;

   //define the actual filter to use based on the passed values
   filter := MAP(CompanyPassed AND StatePassed AND CityPassed
                    =&gt; NFilter AND SFilter AND CFilter,
            CompanyPassed AND StatePassed
                    =&gt; NFilter AND SFilter ,
            CompanyPassed AND CityPassed
                    =&gt; NFilter AND CFilter,
            StatePassed AND CityPassed
                    =&gt; SFilter AND CFilter,
            CompanyPassed =&gt; NFilter ,
            StatePassed =&gt; SFilter ,
            CityPassed =&gt; CFilter,
            TRUE);
   RETURN HeaderFile(filter);
END;
        
//*****************************************************************
//then you can use the interface

InRec  := {HeaderRec AND NOT [RecID,Address,Zip]};

//this MODULE creates a concrete instance
BatchHeaderSearch(InRec l) := MODULE(IHeaderFileSearch)
  EXPORT STRING120 company_val := l.company;
  EXPORT STRING2 state_val := l.state;
  EXPORT STRING25 city_val := l.city;
END;

//that can be used like this       
FetchAddress(BatchHeaderSearch(ROW({'ABC Co','',''},InRec))); 
 
//or we can define an input dataset
InFile := DATASET([{'ABC Co','Boca Raton','FL'},
                   {'XYZ Co','Jackson','MI'},
                   {'ABC Co','',''},
                   {'XYZ Co','',''},
                   {'Joes Eats','',''}
                  ],InRec);

//and an output nested child structure
HeaderRecs := RECORD
  UNSIGNED4 Pass;
  DATASET(HeaderRec) Headers;
END;

//and allow PROJECT to run the query once for each record in InFile
HeaderRecs XF(InRec L, INTEGER C) :=  TRANSFORM
  SELF.Pass := C;
  SELF.Headers := FetchAddress(BatchHeaderSearch(L));
END;
batchHeaderLookup := PROJECT(InFile,XF(LEFT,COUNTER));
batchHeaderLookup;</programlisting>

  <para>See Also: <link linkend="MODULE_Structure">MODULE Structure</link>,
  <link linkend="LIBRARY">LIBRARY</link></para>
</sect1>