Embedded IDE Link™ MU

list - Information listings from MULTI

Syntax

list(ff,varname)
infolist = list(id,'type')
infolist = list(id,'type',typename)

Description

list(ff,varname) lists the local variables associated with the function accessed by function object ff. Compare to list(id,'variable','varname') which works the same way to return variables from object id.

Note   list does not recognize or return information about variables that you declare in your code but that are not used or initialized.

Some restrictions apply when you use list with function objects. list generates an error in the following circumstances:

• When varname is not a valid input argument for the function accessed by ff

  For example, if your function declaration is

  int foo(int a)
  

  but you request information about input argument b, which is not defined

  list(ff,'b')
  

  MATLAB^® returns an error.

• When varname is the same as a variable assigned by MATLAB. Usually this happens when you use declare to pass a function declaration to MATLAB and the declaration string does not match the declaration for ff as determined when you created ff.

  In an example that demonstrates this problem, the function declaration has a name for the first input, a. In the declare call, the declaration string does not provide a name for the first input, just a data type, int. When you issue the declare call, MATLAB software names the first input ML_Input1. If you try to use list to get information about the input named ML_Input, list returns an error. Here is the code, starting with the function declaration in your code:

  int foo(int a)  % Function declaration in your source code
  declare(ff,'decl','int foo(int)')
  % MATLAB generates a warning that it has assigned the name 
  % ML_Input to the first input argument
  list(ff,'ML_Input') % list returns an error for this call
  

• When varname does not match the input name in the function declaration provided in your source code, as compared to the declaration string you used in a declare operation.

  Assume your source code includes a function declaration for foo:

  int foo(int a);
  

  Now pass a declaration for foo to MATLAB:

  declare(ff,'decl','int foo(int b)')
  

  MATLAB issues a warning that the input names do not match. When you use list on the input argument b,

  list(ff,'b')
  

  list returns an error.

• When varname is an input to a library function. list always fails in this case. It does not matter whether you use declare to provide the declaration string for the library function.

Note   When you call list for a variable in a function object  list(ff,varname)the address field may contain an incorrect address if the program counter is not within the scope of the function that includes varname when you call list.

infolist = list(id,type) reads information about your MULTI project and returns it in infolist. Different types of information and return formats are possible depending on the input arguments you supply to the list function call. The type argument specifies which information listing to return. To determine the information that list returns, use one of the following as the type parameter string:

• project — Tell list to return information about the current project in MULTI.

• variable — Tell list to return information about one or more embedded variables.

• globalvar — Tell list to return information about one or more global embedded variables.

• function — Tell list to return details about one or more functions in your project.

• type — Tell list to return information about one or more defined data types, including struct, enum, and union. C data type typedefs are excluded from the list of data types.

Note, list returns dynamic MULTI information that you can alter. Returned listings represent snapshots of the current MULTI IDE configuration only. Be aware that earlier copies of infolist might contain stale information.

Also, list may report incorrect information when you make changes to variables from MATLAB. To report variable information, list uses the MULTI API, which only knows about variables in MULTI. Your changes from MATLAB, such as changing the data type of a variable, do not appear through the API and list. For example, the following operations return incorrect or old data information from list.

infolist = list(id,'project') returns a vector of structures containing project information in the format shown here when you specify option type as project.

infolist = list(id,'variable') returns a structure of structures that contains information on all local variables within scope. The list also includes information on all global variables. Note, however, that if a local variable has the same symbol name as a global variable, list returns the information about the local variable.

infolist = list(id,'variable',varname) returns information about the specified variable varname.

infolist = list(id,'variable',varnamelist) returns information about variables in a list specified by varnamelist. The information returned in each structure follows the format below when you specify option type as variable:

list uses the variable name as the field name to refer to the structure information for the variable.

infolist = list(id,'globalvar') returns a structure that contains information on all global variables.

infolist = list(id,'globalvar',varname) returns a structure that contains information on the specified global variable.

infolist = list(id,'globalvar',varnamelist) returns a structure that contains information on global variables in the list. The returned information follows the same format as the syntax infolist = list(id,'variable',...).

infolist = list(id,'function') returns a structure that contains information on all functions in the embedded program.

infolist = list(id,'function',functionname) returns a structure that contains information on the specified function functionname.

infolist = list(id,'function',functionnamelist) returns a structure that contains information on the specified functions in functionnamelist. The returned information follows the format below when you specify option type as function:

To refer to the function structure information, list uses the function name as the field name.

infolist = list(id,'type') returns a structure that contains information on all defined data types in the embedded program. This method includes struct, enum and union data types and excludes typedefs. The name of a defined type is its C struct tag, enum tag or union tag. If the C tag is not defined, it is referred to by the MULTI compiler as '$faken' where n is an assigned number.

infolist = list(id,'type',typename) returns a structure that contains information on the specified defined data type.

infolist = list(id,'type',typenamelist) returns a structure that contains information on the specified defined data types in the list. The returned information follows the format below when you specify option type as type:

For the field name, list uses the type name to refer to the type structure information.

The following list provides important information about variable and field names:

• When a variable name, type name, or function name is not a valid MATLAB structure field name, list replaces or modifies the name so it becomes valid.

• In field names that contain the invalid dollar character $, list replaces the $ with DOLLAR.

• Changing the MATLAB field name does not change the name of the embedded symbol or type.

Examples

This first example shows list used with a variable, providing information about the variable varname. Notice that the invalid field name _with_underscore gets changed to Q_with_underscore. To make the invalid name valid, list inserts the character Q before the name.

varname1 = '_with_underscore'; % invalid fieldname
list(id,'variable',varname1);
ans =

    Q_with_underscore : [varinfo]
ans. Q_with_underscore 
ans=

       name: '_with_underscore'
   isglobal: 0
   location: [1x62 char]
       size: 1
     uclass: 'numeric'
       type: 'int' 
    bitsize: 16 

To demonstrate using list with a defined C type, variable typename1 includes the type argument. Because valid field names cannot contain the $ character, list changes the $ to DOLLAR.

typename1 = '$fake3'; % name of defined C type with no tag 
list(id,'type',typename1);            
ans =

       DOLLARfake0 : [typeinfo]    

ans.DOLLARfake0=
                 
        type: 'struct $fake0'       
        size: 1     
      uclass: 'structure'     
      sizeof: 1    
     members: [1x1 struct]

When you request information about a project in MULTI, you see a listing like the following that includes structures containing details about your project.

projectinfo=list(id,'project')

projectinfo = 

          name: 'D:\Work\c6711dskafxr_c6000_rtw\c6711dskafxr.pjt'
          type: 'project'
    targettype: 'TMS320C67XX'
      srcfiles: [69x1 struct]
      buildcfg: [3x1 struct]

See Also

info

isrunning

load