FWD » Core Development » Base Language

**    GES  20210208          Added table-level signature calculation (saved as an annotation). Added

**                           findTableInfo() to provide a set of related data about a matched record. This

**                           saves multiple calls each having to resolve the same name node lookup.

      // calculate and save the table signature

      calculateSignature(table);

    * Get the Progress parser token type of a table, temp-table, work-table,

    * or buffer. If <code>name</code> represents a buffer, the type of the

    * backing record is returned. That is, a type of <code>BUFFER</code> is

    * never returned, only the type of the record which backs the buffer.

    * <p>

    * If both forceTemp and forcePersistent are <code>false</code>, then the lookup is performed

    * with no preference for temp-table or persistent table.

    *

    * @param   name

    *          Case insensitive record name; may be qualified or not. If

    *          qualified, only the table portion of the name may be

    *          abbreviated.

    * @param   forceTemp

    *          If <code>true</code>, force a temp-table lookup.

    * @param   forcePersistent

    *          If <code>true</code>, force a persistent table lookup.

    *

    * @return  One of the Progress parser token types <code>TABLE</code>,

    *          <code>TEMP_TABLE</code>, or <code>WORK_TABLE</code>, or

    *          <code>UNKNOWN</code> if <code>name</code> cannot be found.

    *

    * @throws  AmbiguousSchemaNameException

    *          if <code>name</code> is an ambiguous identifier for the

    *          target record.

    */

   public TableInfo findTableInfo(String name, boolean forceTemp, boolean forcePersistent)

   throws AmbiguousSchemaNameException

   {

      // TODO: The recordType lookup used scopes.size() - 1 instead of nearestEnclosingInternal(), is this

      //       an issue?  It seems like it should have been consistent with the other lookups, so this is

      //       being made consistent here.

      int l1 = computeLevel(forceTemp, forcePersistent, true, nearestEnclosingInternal());

      int l2 = computeLevel(forceTemp, forcePersistent, false, SCHEMA_GLOBAL_SCOPE);

      // Look up record name node.

      NameNode node = findEntry(name, EntityName.TABLE, l1, l2, false);

      TableInfo info = null;

      if (node != null)

      {

         NameNode dbNode  = node.getParent();

         // don't just use getAst() here, we need the AST for the backing table if this is a buffer

         // (this will work for both the simple case and the buffer case)

         Aast   ast   = getTable(node); 

         String sig   = ast != null ? (String) ast.getAnnotation("signature") : null;

         String sname = getQualifiedName(node);

         String bname = getRecordName(node, EntityName.TABLE, name);

         String dname = (dbNode != null) ? dbNode.getName() : "";

         int    ttype = getTable(node).getType();

         info = new TableInfo(sig, sname, bname, dname, ttype);

      }

      return info;

   }

   /**

    * Calculate and save the signature for the table.  Each field is represented by "datatype" or

    * "datatype[extent]" format.  The table level signature is all of the field signatures separated

    * by "|" delimiter with the number and order of the fields matching the order in the AST.

    *  

    * @param    table

    *           The table AST substree.

    */

   private void calculateSignature(Aast table)

   {

      String signature = "";

      Aast next = (Aast) table.getFirstChild();

      // iterate through all fields

      while (next != null)

      {

         int type = next.getType();

         // if this is a field, calculate the field's portion of the signature

         if (type >= BEGIN_FIELDTYPES && type <= END_FIELDTYPES ||

             type >= BEGIN_METATYPES  && type <= END_METATYPES)

         {

            Aast ext = next.getImmediateChild(KW_EXTENT, null);

            String extent = null;

            // read the extent value if any

            if (ext != null)

            {

               if (ext.getNumImmediateChildren() == 0)

               {

                  String err = String.format("Indeterminate EXTENT in a temp-table definition for %s",

                                             next.dumpTree());

                  // indeterminate extent does not make sense for a temp-table, should not happen

                  throw new RuntimeException(err);

               }

               else

               {

                  // the only child is a NUM_LITERAL

                  Aast num = (Aast) ext.getFirstChild();

                  extent = num.getText();

               }

            }

            // create the field portion of the signature

            String fsig = SchemaParser.fieldSignature(type, extent);

            // add it in to the table signature

            signature += (signature.length() == 0) ? fsig : "|" + fsig;

         }

         next = (Aast) next.getNextSibling();

      }

      // save the result

      if (signature.isEmpty())

      {

         // there should always be at least 1 field

         throw new RuntimeException(String.format("Invalid temp-table, no fields!\n%s", table.dumpTree()));

      }

      else

      {

         table.putAnnotation("signature", signature);

      }

   }

   /**

/*

** Module   : TableInfo.java

** Abstract : Schema information about a database field.

**

** Copyright (c) 2021, Golden Code Development Corporation.

**

** -#- -I- --Date-- --------------------------------Description----------------------------------

** 001 GES 20210224 Created initial version.

*/

/*

** This program is free software: you can redistribute it and/or modify

** it under the terms of the GNU Affero General Public License as

** published by the Free Software Foundation, either version 3 of the

** License, or (at your option) any later version.

**

** This program is distributed in the hope that it will be useful,

** but WITHOUT ANY WARRANTY; without even the implied warranty of

** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

** GNU Affero General Public License for more details.

**

** You may find a copy of the GNU Affero GPL version 3 at the following

** location: https://www.gnu.org/licenses/agpl-3.0.en.html

** 

** Additional terms under GNU Affero GPL version 3 section 7:

** 

**   Under Section 7 of the GNU Affero GPL version 3, the following additional

**   terms apply to the works covered under the License.  These additional terms

**   are non-permissive additional terms allowed under Section 7 of the GNU

**   Affero GPL version 3 and may not be removed by you.

** 

**   0. Attribution Requirement.

** 

**     You must preserve all legal notices or author attributions in the covered

**     work or Appropriate Legal Notices displayed by works containing the covered

**     work.  You may not remove from the covered work any author or developer

**     credit already included within the covered work.

** 

**   1. No License To Use Trademarks.

** 

**     This license does not grant any license or rights to use the trademarks

**     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks

**     of Golden Code Development Corporation. You are not authorized to use the

**     name Golden Code, FWD, or the names of any author or contributor, for

**     publicity purposes without written authorization.

** 

**   2. No Misrepresentation of Affiliation.

** 

**     You may not represent yourself as Golden Code Development Corporation or FWD.

** 

**     You may not represent yourself for publicity purposes as associated with

**     Golden Code Development Corporation, FWD, or any author or contributor to

**     the covered work, without written authorization.

** 

**   3. No Misrepresentation of Source or Origin.

** 

**     You may not represent the covered work as solely your work.  All modified

**     versions of the covered work must be marked in a reasonable way to make it

**     clear that the modified work is not originating from Golden Code Development

**     Corporation or FWD.  All modified versions must contain the notices of

**     attribution required in this license.

*/

package com.goldencode.p2j.schema;

/**

 * A read-only bean which exposes schema-related information associated with a database table

 * which is referenced in source code.

 */

public class TableInfo

{

   /** Table signature associated with the table. */

   private final String signature;

   /** Fully qualified schema name of the table. */

   private final String qualified;

   /** Table's buffer name as indicated in source. */

   private final String buffer;

   /** Table's database logical name or alias. */

   private final String database;

   /** Table's token type. */

   private final int recordType;

   /**

    * Constructor.

    * 

    * @param   signature

    *          Structural signature for the table.

    * @param   qualified

    *          Fully qualified schema name of the table.

    * @param   buffer

    *          Name of the buffer indicated by the table reference in source code.

    * @param   database

    *          Name of the database which contains the table, as specified by the table reference

    *          in source code, or looked up if the source reference was unqualified.

    * @param   recordType

    *          Token type of the table backing the buffer indicated by the table reference in

    *          source code.

    */

   TableInfo(String signature, String qualified, String buffer, String database, int recordType)

   {

      this.signature  = signature;

      this.qualified  = qualified;

      this.buffer     = buffer;

      this.database   = database;

      this.recordType = recordType;

   }

   /**

    * Get the signature of the table in the schema.

    * 

    * @return   Table signature.

    */

   public String getSignature()

   {

      return signature;

   }

   /**

    * Get the fully qualified schema name of the field.

    * 

    * @return  Qualified field name.

    */

   public String getQualified()

   {

      return qualified;

   }

   /**

    * Get the buffer name associated with the field.

    * 

    * @return  Buffer name.

    */

   public String getBuffer()

   {

      return buffer;

   }

   /**

    * Get the logical database name or alias, if any, associated with the field.

    * 

    * @return  The logical name of the database associated with the buffer associated with the

    *          field. An empty string is returned if the containing table is a temp- or

    *          work-table.

    */

   public String getDatabase()

   {

      return database;

   }

   /**

    * Get the Progress parser token type of a table, temp-table, work-table, or buffer which

    * contains the field. If the record containing the field is a buffer, the type of the backing

    * record is returned. That is, a type of {@code BUFFER} is never returned, only the type of

    * the record which backs the buffer.

    * 

    * @return  Record token type.

    */

   public int getRecordType()

   {

      return recordType;

   }

}

** Copyright (c) 2004-2021, Golden Code Development Corporation.

**     GES 20210208          Added table-level signature calculation and it is saved as an annotation.

** Copyright (c) 2004-2021, Golden Code Development Corporation.

    * Calculate the signature string for a field.

    *

    * @param    type

    *           The field's data type.

    * @param    extent

    *           The extent size (as a num literal) or {@code null} if the field is scalar.

    *

    * @return   The signature in "datatype" or "datatype[extent]" format.

    */

   public static String fieldSignature(int type, String extent)

   {

      String code = null;

      switch (type)

      {

         case FIELD_BLOB:

            code = "blob";

            break;

         case FIELD_CHAR:

            code = "char";

            break;

         case FIELD_CLOB:

            code = "clob";

            break;

         case FIELD_COM_HANDLE:

            code = "comh";

            break;

         case FIELD_DATE:

            code = "date";

            break;

         case FIELD_DATETIME:

            code = "dt";

            break;

         case FIELD_DATETIME_TZ:

            code = "dttz";

            break;

         case FIELD_DEC:

            code = "dec";

            break;

         case FIELD_INT:

            code = "int";

            break;

         case FIELD_INT64:

            code = "i64";

            break;

         case FIELD_LOGICAL:

            code = "log";

            break;

         case FIELD_RECID:

            code = "rec";

            break;

         case FIELD_ROWID:

            code = "row";

            break;

         case FIELD_RAW:

            code = "raw";

            break;

         case FIELD_HANDLE:

            code = "hndl";

            break;

         case FIELD_BIGINT:

            code = "bigi";

            break;

         case FIELD_BYTE:

            code = "byte";

            break;

         case FIELD_DOUBLE:

            code = "dbl";

            break;

         case FIELD_FIXCHAR:

            code = "fixc";

            break;

         case FIELD_FLOAT:

            code = "flt";

            break;

         case FIELD_SHORT:

            code = "shrt";

            break;

         case FIELD_TIMESTAMP:

            code = "tmst";

            break;

         case FIELD_TIME:

            code = "time";

            break;

         default:

            code = "unkw";

            break;

      }

      return (extent == null) ? code : code + "[" + extent + "]";

   }

   /**

      {

         astFactory.makeASTRoot(currentAST, #[TABLE]);

         String signature = "";

         String fsig = null;

      }

              fsig=field

              {

                 signature += (signature.length() == 0) ? fsig : "|" + fsig;

              }

         ##.putAnnotation("signature", signature);

 * @return   The signature for this field in "datatype" or "datatype[extent]" format.

 *

 * @throws   SemanticException

 *           if this field definition reports a different parent table name

 *           from the table definition most recently parsed.

field returns [String sig = null]

         String ext = null;

            | ext=extent

      {

         sig = fieldSignature(ftype, ext);

      }

 *

 * @return   The size of the extent.

extent returns [String num = null]

      KW_EXTENT^ n:NUM_LITERAL { num = #n.getText(); }

**     GES 20210311          Rewrote exact and fuzzy method matching to support all data types and

**                           overloading rules.  Fixed many latent problems.

import java.util.stream.*;

                        : parents.toArray(new ClassDefinition[0]);

               // System.out.printf("DUPLICATE %s\n at %s", prevMdat.toString(), node.dumpTree());

         node.putAnnotation("return_type", (long) type);

         node.putAnnotation("access-mode", (long) access);

         node.putAnnotation("static", isStatic);

         node.putAnnotation("tempidx", (long) mTempIdx);

            node.putAnnotation("extent", (long) extent);

         MethodSearchResult found = lookupMethodWorker(mname, signature, access, isStatic, internal, node);

         MemberData         mdat    = (found == null) ?  null : found.data;

            node.putAnnotation("access-mode", (long) mdat.access);

            node.putAnnotation("static", mdat.isStatic);

            node.putAnnotation("tempidx", (long) mdat.tempIdx);

               node.putAnnotation("extent", (long) mdat.extent);

            annotateCallSignature(node, signature, mdat.signature, found.getOverrides());

            // dynamic cases will have a non-null result; this may be for table-handle parms, dataset-handle

            // parms or POLY parms

            if (found != null && found.isDynamic())

                  String datatype = SymbolResolver.translateType(vdata.type, null, vdata.qname);

                  int    extent = vdata.var.getExtent();

                  String ext = (extent == 0) ? "" : "[" + (extent > 0 ? Integer.toString(extent) : "") +"]";

    * @param    defSig

    *           The array of parameter types that is the method definition signature.

    * @param    overrides

    *           Type overrides found by any fuzzy matching for this method.

   private void annotateCallSignature(Aast           call,

                                      ParameterKey[] callSig,

                                      ParameterKey[] defSig,

                                      String[]       overrides)

                           parm.putAnnotation("wrap_parameter", true);

                     else if (!classname.startsWith("object<") && 

                        parm.putAnnotation("wrap_parameter", true);

   private MethodSearchResult lookupMethodWorker(String         name,

                                                 ParameterKey[] sig,

                                                 int            access,

                                                 boolean        isStatic,

                                                 boolean        internal,

                                                 Aast           node)

      MethodSearchResult result = null;

         result = exactMethodLookup(name, sig, access, isStatic, internal);

         if (result == null && !isStatic && internal)

            result = exactMethodLookup(name, sig, access, true, internal);

         if (result == null)

            result = fuzzyMethodLookup(name, sig, access, isStatic, internal, node);

            if (result == null && !isStatic && internal)

               result = fuzzyMethodLookup(name, sig, access, true, internal, node);

      return result;

    * Find the named method based on an exact signature match. This method searches all methods in the

    * parent hierarchy not just in the current class.  This search the hierarchy approach is needed so

    * that some special exceptions can be honored:

    * <p>

    * <ul>

    *    <li>If the caller does not specify a mode and there is an otherwise exact match, that method is

    *        selected.  Buffers have no mode processing so this case is ignored for them.</li>

    *    <li>A caller's table-handle or dataset-handle parameter which has an exact match is disallowed

    *        if there are any alternatives with a table/dataset at that parameter AND that parameter type

    *        is what determines that the signatures are different.</li>

    * </ul>

    * @param    caller

   private MethodSearchResult exactMethodLookup(final String         name,

                                                final ParameterKey[] caller,

                                                final int            access,

                                                final boolean        isStatic,

                                                final boolean        internal)

   {

      List<MatchMetrics> list = candidates(name, caller.length, access, isStatic, internal, false, null);

      // quick out if there are no possible matches

      if (list.isEmpty())

      {

         return null;

      }

      final boolean[] ignore = new boolean[caller.length];

      Predicate<MatchMetrics> exactMatch = (mem) -> 

      {

         for (int i = 0; i < caller.length; i++)

         {

            if (!ignore[i] && !caller[i].equals(mem.data.signature[i]))

            {

               return false;

            }

         }

         return true;

      };

      List<MatchMetrics> exact = list.stream().filter(exactMatch).collect(Collectors.toList());

      Predicate<MatchMetrics> flexModeMatch = (mem) -> 

      {

         for (int i = 0; i < caller.length; i++)

         {

            if (!ignore[i])

            {

               if (caller[i].mode != null)

               {

                  if (!caller[i].equals(mem.data.signature[i]))

                  {

                     return false;

                  }

               }

               else

               {

                  if (!caller[i].typeEquivalent(mem.data.signature[i]))

                  {

                     return false;

                  }

               }

            }

         }

         return true;

      };

      MethodSearchResult result = null;

      boolean       flex   = false;

      if (exact.isEmpty())

      {

         List<MatchMetrics> flexMode = list.stream().filter(flexModeMatch).collect(Collectors.toList());

         if (flexMode.size() == 1)

         {

            result = new MethodSearchResult(flexMode.get(0).data, null);

            flex   = true;

         }

      }

      else

      {

         if (exact.size() == 1)

         {

            result = new MethodSearchResult(exact.get(0).data, null);

         }

      }

      if (result != null)

      {

         // table-handle/dataset-handle matches are only valid when the only difference in signature is

         // between a table/dataset and table-handle/dataset-handle

         Iterator<MatchMetrics> iter = list.iterator();

         // calculate which parameters are both table-handles/dataset-handles and have conflicting

         // signature (another signature that has a table/dataset in the same parameter position)

         while (iter.hasNext())

         {

            MatchMetrics m = iter.next();

            for (int i = 0; i < caller.length; i++)

            {

               // quick iteration if we already know this parameter should be ignored 

               if (ignore[i])

                  continue;

               String type = m.data.signature[i].type;

               if ("TABLE-HANDLE".equals(caller[i].type))

               {

                  if (type != null && type.startsWith("TEMP-TABLE"))

                  {

                     ignore[i] = true;

                  }

               }

               else if ("DATASET-HANDLE".equals(caller[i].type))

               {

                  if (type != null && type.startsWith("DATA-SET "))

                  {

                     ignore[i] = true;

                  }

               }

            }

         }

         // ignoring the conflicting parameters, can we still calculate find a unique match?

         List<MatchMetrics> ignoreTH = list.stream()

                                            .filter(flex ? flexModeMatch : exactMatch)

                                            .collect(Collectors.toList());

         if (ignoreTH.size() != 1)

         {

            result = null;

         }

      }

      return result;

   }

   /**

    * Remove any candidates from the list which do not match the caller's extent.  The following are

    * possible matches:

    * <p>

    * <ul>

    *    <li> Neither the caller nor the parameter definition have an extent specification.

    *    <li> Both the caller and the parameter definition have an indeterminate extent.

    *    <li> The caller has a fixed extent value and the parameter definition has the same fixed extent

    *         value.

    *    <li> The caller has a fixed extent value and the parameter definition has an indeterminate

    *         extent.  This is a fuzzy match (all the above criteria are the same as exact matches). 

    *

    * @param    list

    *           The list of candidates.

    * @param    callerExtVal

    *           Caller's extent value (-1 means indeterminate, 0 is scalar and any positive value is

    *           the fixed extent).

    * @param    idx

    *           Parameter number being processed.

    */

   private void processExtentMatches(List<MatchMetrics> list, int callerExtVal, int idx)

   {

      Predicate<MatchMetrics> test = null;

      Consumer<MatchMetrics>  mark = (m) -> m.extExact++;

      // no extent in caller

      if (callerExtVal == 0)

      {

         // no extent in the parameter definition

         test = (mem) -> mem.data.signature[idx].type.indexOf("[") == -1;

         // no marking needed here

         mark = (m) -> {};

      }

      // indeterminate extent in caller

      else if (callerExtVal == -1)

      {

         // indeterminate extent in the parameter definition

         test = (mem) -> mem.data.signature[idx].type.indexOf("[") != -1 && 

                         getExtent(mem.data.signature[idx].type) == -1;

      }

      // fixed extent in caller

      else

      {

         test = (mem) -> 

         {

            int extIdx = mem.data.signature[idx].type.indexOf("[");

            if (extIdx != -1)

            {

               // the parameter definition is an extent

               int parmExtVal = getExtent(mem.data.signature[idx].type);

               // fixed extents match exactly or the parm is indeterminate

               return callerExtVal == parmExtVal || parmExtVal == -1;

            }

            else

            {

               // the parameter definition is NOT an extent

               return false;

            }

         };

         // this will only be used for where we already know extIdx != -1 above which means it is an

         // extent at the parameter definition (it may be either fixed or indeterminate) 

         mark = (mem) -> 

         {

            // the parameter definition is an extent

            int parmExtVal = getExtent(mem.data.signature[idx].type);

            if (callerExtVal == parmExtVal)

            {

               // both are fixed extents match exactly

               mem.extExact++;

            }

            else if (parmExtVal == -1) 

            {

               // or the parm is indeterminate

               mem.extCvt++;

            }

         };

      }

      list.removeIf(test.negate());

      list.stream().forEach(mark);

    * Check if there is only 1 possible match for the given predicate, if so then remove all candidates

    * from the list except for that one possible match.

    * 

    * @param    list

    *           The list to edit.

    * @param    test

    *           The predicate to test.

    * @param    idx

    *           The parameter index for error messages.

    * @param    callerType

    *           The caller type for error messages.

    * @param    error

    *           A location to store an error message for the caller.

    */

   private boolean allowIfOnlyOne(List<MatchMetrics>      list, 

                                  Predicate<MatchMetrics> test,

                                  int                      idx, 

                                  String                   callerType,

                                  String[]                 error)

   {

      boolean result = false;

      List<MatchMetrics> matches = list.stream().filter(test).collect(Collectors.toList());

      int num = matches.size();

      if (num == 1)

      {

         result = true;

         matches.stream().forEach((m) -> m.cvt++);

         list.removeIf(test.negate());

      }

      else if (num > 1)

      {

         error[0] = String.format("Ambiguous matches (%d) for parameter %d of type %s.",

                               num,

                               idx, 

                               callerType);

      }

      else

      {

         error[0] = String.format("No possible matches for parameter %d of type %s.", idx, callerType);

      }

      if (!result)

      {

         list.clear();

      }

      return result;

   }

   /**

    * Remove any non-exact matches from the given list.

    * 

    * @param    list

    *           The list to edit.

    * @param    exactMatch

    *           The test for an exact match.

    *           

    * @return   {@code true} if edits were made.

    */

   private boolean processExactMatches(List<MatchMetrics> list, Predicate<MatchMetrics> exactMatch)

   {

      // calculate the exact TYPE matches

      List<MatchMetrics> exacts = list.stream().filter(exactMatch).collect(Collectors.toList());

      if (!exacts.isEmpty())

      {

         exacts.stream().forEach((m) -> m.exact++);

         // there is at least 1 exact match, remove everything else

         list.removeIf(exactMatch.negate());

         return true;

      }

      return false;

   }

   /**

   private MethodSearchResult fuzzyMethodLookup(String         name,

                                                ParameterKey[] caller,

                                                int            access,

                                                boolean        isStatic,

                                                boolean        internal,

                                                Aast           node)

      List<MatchMetrics> list = candidates(name, caller.length, access, isStatic, internal, first, null);

      // GES_TODO: remove

      // boolean debug = "calc3".equals(name) && caller.length == 1 && caller[0].type.equals("object<? extends oo.basic.compleximplements>");;

      boolean debug = false;

      if (debug)

         System.out.println("\n\n--------------------fuzzyMethodLookup START--------------------\n");

         System.out.printf("\n   CALLER %s\n   PARAMETERS: %d\n", node.dumpTree(true), caller.length);

         for (int i = 0; i < caller.length; i++)

         {

            System.out.printf("      %s\n", caller[i]);

         }

         for (MatchMetrics m : list)

         {

            System.out.printf("DEBUG: %s\n", m.data);

         }

         if (debug)

            System.out.println("--------------------fuzzyMethodLookup QUICK OUT--------------------");

         return new MethodSearchResult(list.get(0).data, null);

      String[] error = new String[1];

      boolean polyArgs = false;

      // TODO: constructors

      // PHASE 1: cut down the list of all matches to include only those which are potentially valid

      if (debug)

         System.out.println("\n\n---PHASE 1 START---\n");

      // types (e.g. objects) have multi-step checks and other types are a simple comparison; at each

      // left which COULD match all criteria; at that point if there are more than one then we have an

      // additional disambiguation step, a dynamic invocation scenario or there is some ambiguity (which

      // should not happen if the code compiles in the 4GL)

      // process the caller's parameters, left to right; for each caller parameter we examine the matching

      // parameter in the list of candidates, removing any candidates in the list that cannot match

         final int idx = i;

         final Integer callerMode = caller[i].mode;

         final String  callerType = fromJava(caller[i].type);

         // these are all specific to the current parameter

         Predicate<MatchMetrics> exactMatch = (m) -> callerType.equals(fromJava(m.data.signature[idx].type)); 

         Predicate<MatchMetrics> isTable    = (m) -> m.data.signature[idx].type.startsWith("TEMP-TABLE");

         Predicate<MatchMetrics> isTH       = (m) -> "TABLE-HANDLE".equals(m.data.signature[idx].type);

         Predicate<MatchMetrics> isDataset  = (m) -> m.data.signature[idx].type.startsWith("DATASET <");

         Predicate<MatchMetrics> isDH       = (m) -> "DATASET-HANDLE".equals(m.data.signature[idx].type);

         Predicate<MatchMetrics> modeMatch  = (m) -> callerMode.equals(m.data.signature[idx].mode);

         // exclude any candidates which cannot ever match due to a caller MODE constraint; a null for the

         // caller's mode is a wildcard that can match any mode in the parameter definition; this means that

         // when the caller's mode is null, no matches can be excluded

         if (callerMode != null)

         {

            list.removeIf(modeMatch.negate());

            if (debug)

               System.out.printf("PARM %d: mode %d\n", idx, list.size());

         }

         // TYPE-specific processing

         boolean poly = (callerType == null) || callerType.equals("BaseDataType");

         // TYPE wildcards: unknown value or BDT (POLY cases) match any TYPE

         if (poly || callerType.equals("unknown"))

         {

            list.stream().forEach((m) -> m.wildcard++);

            if (poly)

               polyArgs = true;

            // no cases can be excluded based on type; the list remains unchanged

            if (debug)

               System.out.printf("PARM %d: type wildcard %d\n", idx, list.size());

         }

         else

         {

            // table parameters

            if (callerType.startsWith("TEMP-TABLE"))

            {

               // check for any exact TYPE matches

               if (!processExactMatches(list, exactMatch))

               {

                  // allow a match to a table-handle if there is only 1 table-handle option

                  allowIfOnlyOne(list, isTH, idx, callerType, error);

               }

               if (debug)

                  System.out.printf("PARM %d: TT %d\n", idx, list.size());

            }

            // table handles

            else if (callerType.equals("TABLE-HANDLE"))

            {

               // at this point we can't know if we have a match, we can just remove anything that is not

               // a table-handle or table; we defer the matching to the next phase once all other removals

               // are done               

               list.removeIf(isTH.or(isTable).negate());

               list.stream().forEach((m) -> m.cvt++);

               if (debug)

                  System.out.printf("PARM %d: TH %d\n", idx, list.size());

            }

            // dataset parameters

            else if (callerType.startsWith("DATASET <"))

            {

               // check for any exact TYPE matches

               if (!processExactMatches(list, exactMatch))

               {

                  // allow a match to a dataset-handle if there is only 1 dataset-handle option

                  allowIfOnlyOne(list, isDH, idx, callerType, error);

               }

               if (debug)

                  System.out.printf("PARM %d: DS %d\n", idx, list.size());

            }

            // dataset handles

            else if (callerType.equals("DATASET-HANDLE"))

            {

               // at this point we can't know if we have a match, we can just remove anything that is not

               // a dataset-handle or dataset; we defer the matching to the next phase once all other

               // removals are done               

               list.removeIf(isDH.or(isDataset).negate());

               list.stream().forEach((m) -> m.cvt++);

               if (debug)

                  System.out.printf("PARM %d: DH %d\n", idx, list.size());

            }

            // buffers

            else if (callerType.startsWith("BUFFER"))

            {

               // only an exact match works (handled above); no fuzzy matching here

               list.removeIf(exactMatch.negate());

               list.stream().forEach((m) -> m.exact++);

               if (debug)

                  System.out.printf("PARM %d: buf %d\n", idx, list.size());

            }

            // must be one of the BaseDataType wrapper classes

            else

            {

               final int     extIdx    = callerType.indexOf("[");

               final int     extVal    = (extIdx == -1) ? 0 : getExtent(callerType);

               final String  basicType = (extIdx == -1) ? callerType : callerType.substring(0, extIdx);

               // extents

               processExtentMatches(list, extVal, idx);