Appendix B C API Code Samples

## Find all References To and From an Entity

### Description

This example reports all references used by a specified entity and also all references where a specified entity is used.

This example is different from the others in that a specific entity is needed when calling the example function. Choosing the desired entity to report is left as an exercise for the user.

### Sample Code

     1	 static void reportRefs(UdbEntity entity)  {
     2	    UdbReference   *refs;
     3	    int            refsSize;
     4	    UdbReference   *filterRefs;
     5	    int            filterRefsSize;
     6	    int            i,j;
     7
     8	    udbListReference(entity, &refs, &refsSize);
     9
     10	    udbListReferenceFilter(refs,
     11	       udbKindParse("call,declare,define,friend,use,include,modify,base,set,typed"),
     12	       NULL, 0, &filterRefs, &filterRefsSize);
     13	    printf ("\nWho (%s) %s references: \n",
     14	                udbKindShortname(udbEntityKind(entity)),
     15	                udbEntityNameLong(entity) );
     16	    for (j=0; j<filterRefsSize; j++) {
     17	       printf ("   %s: %s [%s (%d)] \n",
     18	                 udbKindShortname(udbReferenceKind(filterRefs[j])),
     19	                 udbEntityNameShort(udbReferenceEntity(filterRefs[j])),
     20	                 udbEntityNameShort(udbReferenceFile(filterRefs[j])),
     21	                 udbReferenceLine(filterRefs[j]) );
     22	       }
     23	    udbListReferenceFree(filterRefs);
     24	    udbListReferenceFilter(refs,
     25	        udbKindParse("callby,declarein,definein,friendby,useby,includeby,modifyby,
    derive,setby,typedby"),
     26	        NULL,  0,  &filterRefs, &filterRefsSize);
     27	     printf ("\nWho references (%s) %s: \n",
     28	                udbKindShortname(udbEntityKind(entity)),
     29	                udbEntityNameLong(entity));
     30	     for (j=0; j<filterRefsSize; j++) {
     31	        printf ("   %s: %s [%s (%d)] \n",
     32	                    udbKindShortname(udbReferenceKind(filterRefs[j])),
     33	                    udbEntityNameShort(udbReferenceEntity(filterRefs[j])),
     34	                  udbEntityNameShort(udbReferenceFile(filterRefs[j])),
     35	                  udbReferenceLine(filterRefs[j]) );
     36	      }
     37	      udbListReferenceFree(filterRefs);
     38	      udbListReferenceFree(refs);
     39	 }

### Explanation of Sample Code

lines 2-5: Declare variables for all references and the filtered list of references and their corresponding list sizes. The list of all references is retrieved once and then filtered repeatedly to obtain the list of references desired.

line 8: Retrieve the list of all references for the specified entity.

lines 10-12: Filter the list of references to include `forward' types of references. What the specified entity calls, declares, defines, friends, uses, includes, modifies, derived from, sets, or types. In this example, the entity kindlist is NULL, indicating that we want these types of references to all kinds of entities. Alternatively, the entity kind could have been specified to include references only to functions, or classes, for example.

lines 13-15: Print header with kind and name of the entity.

line 16: Loop through list of forward references.

line 17-21: Report forward reference info; the kind of reference, the name of the entity being referenced, and the file and line where the reference occurs.

line 23: Free the list of forward references.

line 24-26: Filter the list of references to include `backward' types of references. Where the specified entity is called by, declared in, defined in, is friend by, used by, included by, modified by, a base of, set by, or is typed by. In this example, the entity kind is NULL, indicating that we want these types of references to all kinds of entities. Alternatively, the entity kind could have been specified to include references only to functions, or classes, for example.

lines 27--29: Print header with kind and name of the entity.

line 30: Loop through list of backward references.

line 31-35: Report backward reference info; the kind of reference, the name of the entity being referenced, and the file and line where the reference occurs.

line 37: Free the list of backward references.

line 38: Free the list of all references.

### Sample Output

     Who (Function) AppendFilterSuffix references:
        Define: filter [DocMan.cpp (22)]
        Define: ofn [DocMan.cpp (22)]
        Define: pTemplate [DocMan.cpp (23)]
        Define: pstrDefaultExt [DocMan.cpp (23)]
        Use: pTemplate [DocMan.cpp (29)]
        Call: GetDocString [DocMan.cpp (29)]
        Use: filterExt [DocMan.cpp (29)]
        Call: IsEmpty [DocMan.cpp (30)]
        Use: pTemplate [DocMan.cpp (31)]
        Call: GetDocString [DocMan.cpp (31)]
        Use: filterName [DocMan.cpp (31)]
        Call: IsEmpty [DocMan.cpp (32)]
        Use: pstrDefaultExt [DocMan.cpp (38)]
        Use: LPCTSTR [DocMan.cpp (42)]
        Set: pstrDefaultExt [DocMan.cpp (42)]
        Inactive Use: pstrDefaultExt [DocMan.cpp (44)]
        Use: LPTSTR [DocMan.cpp (46)]
        Use: LPCTSTR [DocMan.cpp (46)]
        Use: pstrDefaultExt [DocMan.cpp (46)]
        Set: ofn [DocMan.cpp (46)]
        Set: lpstrDefExt [DocMan.cpp (46)]
        Use: ofn [DocMan.cpp (47)]
        Use: nMaxCustFilter [DocMan.cpp (47)]
        Set: ofn [DocMan.cpp (47)]
        Set: nFilterIndex [DocMan.cpp (47)]
        Modify: filter [DocMan.cpp (51)]
        Use: TCHAR [DocMan.cpp (53)]
        Modify: filter [DocMan.cpp (53)]
        Use: TCHAR [DocMan.cpp (55)]
        Modify: filter [DocMan.cpp (55)]
        Modify: filter [DocMan.cpp (57)]
        Use: TCHAR [DocMan.cpp (58)]
        Modify: filter [DocMan.cpp (58)]
        Use: ofn [DocMan.cpp (59)]
        Use: nMaxCustFilter [DocMan.cpp (59)]
        Modify: nMaxCustFilter [DocMan.cpp (59)]

     Who references (Function) AppendFilterSuffix:
        Define: DocMan.cpp [DocMan.cpp (22)]
        Call: DoPromptFileName [DocMan.cpp (82)]
        Call: DoPromptFileName [DocMan.cpp (92)]

Scientific Toolworks, Inc. http://www.scitools.com Voice: (802) 763-2995 Fax: (802) 763-3066 support@scitools.com sales@scitools.com