(Required) The file whose entries are to be listed. This should equal the file or subfile number, depending on what the caller wishes to list.

(Optional) If the FILE parameter equals a file number, the Lister will ignore the IENS parameter. If the FILE parameter equals a subfile number, the Lister needs the IENS parameter to help identify which subfile to list. In other words, files can be specified with the FILE parameter alone, but subfiles require both the FILE and IENS parameters.

When the IENS parameter is used, it must equal an IENS that identifies the parent record of the exact subfile to list. Since this parameter identifies the subfile under that record, and not the subrecord itself, the first comma-piece of the parameter should be empty. (For more information on the IENS, see the discussion in the DBS Introduction.)

For example, to specify the Menu Item subfile under option number 67, you must pass FILE=19.01 (the subfile number for the Menu subfile) and IENS=",67," (showing that record number 67 holds the Menu subfile you want to list).

Defaults to empty string.

(Optional) The fields to return with each entry found. This parameter can be set equal to any of the specifications listed below. The individual specifications should be separated by semicolons (";").

NOTE: In most cases, a developer will want to include the "@" specifier (described below) to suppress the default output values normally returned by the Lister and then specify the fields and other elements to return here in the FIELDS parameters. This gives the developer full control over exactly what will be returned in the output list and makes the call more self-documenting in the developer's code. 

• Field Number: This specifier makes the Lister return the value of the field for each record found. For example, specifying .01 returns the value of the .01 field. You can specify computed fields. You cannot specify word processing or multiple fields. By default, fields will be returned in external format. The "I" suffix (described below) can be appended to the field number to get the internal format of the field.

  If a field is listed multiple times in the FIELDS parameter, it is returned multiple times in packed output, but only once in unpacked output, since the field number is one of the subscripts of the unpacked output.

• IX:  This returns, for each record, the value(s) from the index used in the call. If a subscript in the index is derived from a field, the external format of that field will be returned by default. Otherwise, the value will be returned directly as it appears in the index. The "I" suffix (described below) can be appended to IX to get the internal index value(s). The index values are returned in the "ID" nodes as described in the Output section below.

  NOTE: For records located on a mnemonic index entry, the value from the index entry will always be returned, rather than its corresponding external field value.

  
  
  
• FID:  This returns the fields display identifiers (i.e., field identifiers). By default, the field values are returned in external format. The "I" suffix (described below) can be appended to FID to get the internal format of the field identifiers.
  
  
• WID:  This returns the fields WRITE (display only) identifiers. The Lister executes each WRITE identifier's M code and copies contents of ^TMP("DIMSG",$J) to the output. You must ensure that the WRITE identifier code issues no direct I/O, but instead calls EN^DDIOL.

  NOTE: The "I" suffix, described below, cannot be used with "WID" and will generate an error.

  
  
  
• .E suffix:  You can append an "E" to a field number, the specifier "IX", or the specifier "FID" to force the fields to be returned in external format. You can use both the "E" and "I" suffix together (ex., .01EI) to return both the internal and external values of the field.
  
  
• .I suffix:  You can append an "I" to a field number, the specifier "IX", or the specifier "FID" to force the fields to be returned in internal format. You can use both the "E" and "I" suffix together (ex., .01IE) to return both the internal and external value of the field.
  
  
• - prefix:  A minus sign (-) prefixing one of the other field specifiers tells the Lister to exclude it from the returned list. This could be used, for example, in combination with the "FID" specifier to exclude one of the identifier fields. For example, if field 2 was one of the field identifiers for a file, "FID;-2" would output all of the field identifiers except for field 2.
  
  
• @:  This suppresses all the default values normally returned by the Lister, except for the IEN and any fields and values specified in the FIELDS parameter. It is recommended that developers ALWAYS use the "@" specifier in their Lister calls. Use of the "@" specifier allows the developer to control exactly what will be returned in the output. See the default values below to see what is normally returned by the Lister.  
  
  
• 22.2 Computed expression: Any computed expression valid in the context of the the File can be used to retrieve the value of that expression for the records found.

Default Values

If you DO NOT pass a FIELDS parameter, the Lister returns:

1. The IEN
2. The indexed field value, in external format (note that for mnemonic cross-referenced entries, this would be the mnemonic subscript, not a field value)
3. The .01 field, in external format, if the indexed field value is not .01
4. Any field display identifiers
5. Any WRITE (display-only) identifiers
6. The results of executing the Lister's IDENTIFIER parameter

If you DO pass a FIELDS parameter but it does not contain the @ specifier, the Lister returns:

1. The IEN
2. The indexed field value, in external format (note that for mnemonic cross-referenced entries, this would be the mnemonic subscript, not a field value)
3. The .01 field, in external format, if the indexed field value is not .01
4. The fields and values specified by the FIELDS parameter
5. Any WRITE (display-only) identifiers
6. The results of executing the Lister's IDENTIFIER parameter

(Optional) Flags to control processing:

Backwards. Traverses the index in the opposite direction of normal traversal.

Internal format is returned. All output values are returned in internal format (the default is external). Because the new "I" suffixcan be used in the FIELDS parameter to return information in internal format, using I in the FLAGS parameter is virtually obsolete. It greatly simplifies the call to use the "@" specifierin the FIELDS parameter to suppress return of default values and to specify in the FIELDS parameter exactly what other data elements are to be returned. You can use the "I" suffix if you wish to have them returned in internal format.

Primary Key used for default index.

Mnemonic suppression. Tells the Lister to ignore any mnemonic cross-reference entries it finds in the index.

Pack output. This flag changes the Lister's output format to pack the information returned for each record onto a single node per record. See the information in the "Output," the "Details and Features," and the "Examples" sections for more details.

Quick List. If this flag is passed, the Lister will use the order of the index to return the output, rather than sorting the information into a more user-friendly order. This will make a difference when doing Lister calls where the index value is a pointer or variable pointer. The call will be more efficient but the output may not be in an intuitive order.

When the Q flag is used, both the FROM and PART parameters must be in the same format as the subscripts found in the index whose name is passed in the INDEX parameter. In the case of a pointer, for example, the FROM and PART parameters would be an internal pointer value. See the description of the FROM, PART and INDEX parameters.

Unscreened lookup. This flag makes the Lister ignore any whole file screen (stored at ^DD(file#,0,"SCR")) on the file specified in the FILE parameter. NOTE: Passing this flag does NOT make the Lister ignore any code passed in the SCREEN parameter.

(Optional) The number of entries to return. If the Lister reaches the end of its list, the number of entries output may be fewer than this parameter. A value of "*" or no value in this parameter designates all entries. The developer has the option to make multiple calls to the Lister, in order to control the number of records returned. In that case, the FROM value (described below) must be passed by reference, and should not be altered between calls. The Lister will return -- in the FROM parameter -- the values needed to find the next record on a subsequent call.

Defaults to "*".

(Optional) The index entry from which to begin the list (e.g., a FROM value of "XQ" would list entries following XQ). The FROM values must be passed as they appear in the index, not in external value. The index entry for the FROM value itself is not included in the returned list.

If the INDEX parameter specifies a compound index (i.e., one with more than one data-valued subscript), then the FROM parameter should be passed by reference as an array where FROM(n) represents the "n^th" subscript on the compound index. This array helps VA FileMan find a single entry in the index. Generally, the developer can set the FROM array to establish a starting point from which the Lister should traverse the index. However, the FROM array is especially useful when making multiple calls to the Lister to return records in discrete chunks. The Lister sets the FROM array to information about the last record returned, so the developer can simply pass this array unchanged from one Lister call to the next to return the next set of records. 

This parameter can contain an array node FROM("IEN"). This subscript can be set equal to a record number that identifies the specific entry from which to begin the list. This can alternately be passed as FROM(m) where "m" is equal to the number of data value subscripts in the index plus 1. This array entry would be passed only when there is more than one entry in the index with the same values in all of the data value subscripts. For example, using a regular single-field index on a NAME field, if there were two "SMITH,JOHN" entries in the file with IENs of 30 and 43, then passing FROM(1)="SMITH,JOHN" and either FROM(2) or FROM("IEN")=30 would return a list of entries starting with name of SMITH,JOHN and IEN of 43. If the list is built using the upright file (INDEX parameter="#"), then FROM, FROM(1) and FROM("IEN") would all be the same and would represent the starting internal entry number for the list.

When listing an index on a Pointer or Variable Pointer field, the FROM value should equal a value from the "B" index at the end of the pointer chain, NOT a pointer value. However, the FROM("IEN") should still equal the number of a record in the pointing file as it does for other Lister calls. For example, suppose you have listed entries from a simple index that points to the STATE file and the previous call finished with entry 12 which points to Utah (record 49 in the STATE file). Then FROM(1) would be set to "UTAH" and FROM("IEN") or FROM(2) would be set to 12. Again, you would only want to set FROM(2) if there were other entries in your file that pointed to Utah, with IENs that followed 12.

This parameter lets the caller make multiple calls to the Lister to return a limited number of records with each call, rather than one large one. If the FROM parameter values are passed by reference, then the Lister will return -- in the FROM array -- information that will tell it which record to start with on subsequent Lister calls.

To start a new list, pass FROM undefined or equal to the empty string. This will start the list with the first entry in the index unless you're traversing the index backwards, in which case, it will start the list with the last entry in the index.

See "Details and Features" and the "Examples" sections for more help on how to use this parameter.

(Optional) The partial match restriction. For example, a PART value of "DI" would restrict the list to those entries starting with the letters "DI". Again, this value must be a partial match to an index value, not the external value of a field. This can be passed by reference and subscripted the same as the FROM parameter so that PART values can be specified for any subscript in a compound index.

PART is often a partial match to FROM. For example, FROM(1)="ZTMMGR", and PART(1)="ZTM" would return only entries that began with "ZTM" and came after "ZTMMGR". It would not include "ZTZERO", even though it comes after "ZTMMGR". (If traversing the index backwards, it would find only entries that came before ZTMMGR).

If FROM is passed and PART is not a partial match to FROM, then the Lister will return all the partial matches to PART that come after FROM. Thus if FROM(1)="DI" and PART(1)="ZTM", then the Lister returns all partial matches to "ZTM". If in this example we were traversing the index backwards, then the Lister would return nothing, because there would be nothing that came before "DI" and started with "ZTM".

For indexes on pointers or variable pointers, PART should refer to values on the "B" index of the pointed-to file at the end of the pointer chain. For example if the index was on a field pointing to the STATE file, PART(1) could be set to "A" to find all states whose name begins with "A".

(Optional) one of the following:

• The name of the index from which to build the list. For example, setting this to "C" could refer to the Upper Case Menu Text index on the Option file. Whether the specified index is simple (single data-value subscript like the "B" index on most files) or compound (more than one data-value subscript) affects the FROM and PART parameters as previously described.
• If "#" is passed in the INDEX parameter, then the list will be built from the upright file (i.e., in order by internal entry number) rather than from an index. In that case, if a FROM value is passed, it should be an IEN and could be passed either as a literal or in FROM(1) or FROM("IEN"), all of which are equivalent (see FROM parameter above).
• 22.2The [bracketed] name of a SORT TEMPLATE.   FLAGS (above) must include "X"
• 22.2A COMPUTED EXPRESSION (which might simply be the name of a Field).   FLAGS (above) must include "X"

If the index is not specified, the default will be "B" unless the FLAGS parameter contains a K, in which case, the default will be the Uniqueness Index defined for the Primary Key on the file. 

If there is no "B" index and either "B" is passed in the INDEX parameter or is the default index, then a temporary index is built on the file (which could take some time). The index is removed after the Lister call.

Unless the M flag is used to suppress them, mnemonic cross-references folded into the specified index are included in the output.

(Optional) Entry Screen. The screen to apply to each potential entry in the returned list to decide whether or not to include it. This may be set to any valid M code that sets $TEST to 1 if the entry should be included, to 0 if not. This is exactly equivalent to the DIC("S") input variable to Classic FileMan lookup ^DIC. The Lister will execute this screen in addition to any SCR node (whole-file screen) defined for the file. Optionally, the screen can be defined in an array entry subscripted by "S" (for example, SCR("S")), allowing additional screen entries to be defined for variable pointer fields as described below.

The Entry Screen code can rely upon the following:

Zero-node of entry's record.

Index being traversed.

Open global reference of file being traversed.

Flags passed to the Lister.

Record number of entry under consideration.

For subfiles, descendants give record numbers for all upper levels. Structure resembles the DA array as used in a call to the classic FileMan edit routine ^DIE.

IENS equivalent to Y array.

The SCREEN parameter can safely change any of these values. For example, suppose there is a set of codes field defined as the 5th piece of the 0 node on the file and you only want to find entries that have the value "Y" in that field. Then the code might look like "I $P(^(0),U,5)=""Y""". All other variables used, however, must be carefully namespaced.

Defaults to no extra screening.

Variable Pointer Screen.If one of the fields indexed by the cross-reference passed in the INDEX parameter is a variable pointer, then additional screens equivalent to the DIC("V") input variable to Classic FileMan lookup ^DIC can also be passed. Suppose the screens are being passed in the SCR array. Then for a simple index with just one data value field, the code can be passed in SCR("V"). For simple or compound indexes, screens can be passed for any indexed fields that are variable pointers in the format SCR("V",n) where "n" represents the subscript location of the variable pointer field on the index from the INDEX parameter.

The Variable Pointer screen restricts the user's ability to see entries on one or more of the files pointed to by the variable pointer. The screen logic is set equal to a line of M code that will return a truth value when executed. If it evaluates TRUE, then entries that point to the file can be included in the output; if FALSE, then any entry pointing to the file is excluded. At the time the code is executed, the variable Y(0) is set equal to the information for that file from the data dictionary definition of the variable pointer field. You can use Y(0) in the code set into the DIC("V") variable. Y(0) contains:

All of this information was defined when that file was entered as one of the possibilities for the variable pointer field.

For example, suppose your .01 field is a variable pointer pointing to files 1000, 2000, and 3000. If you only want the user to be able to enter values from files 1000 or 3000, you could set up DIC("V") like this:

 S DIC("V")="I +Y(0)=1000!(+Y(0)=3000)"

(Optional) The text to accompany each potential entry in the returned list to help identify it to the end user. This may be set to any valid M code that calls the EN^DDIOL utility to load identification text. The Lister will list this text AFTER that generated by any M identifiers on the file itself. This parameter takes and can change the same input as the SCREEN parameter.

For example, a value of "D EN^DDIOL(""KILROY WAS HERE!"")" would include that string with each entry returned as a separate node under the "ID","WRITE" nodes of the output array.

This parameter should issue no READ or WRITE commands itself nor should it call utilities that issue READs or WRITEs (except for EN^DDIOL itself).

Defaults to no extra identification text.

See the description of EN^DDIOL for more information.

(Optional) The array that should receive the output list. This must be a closed array reference and can be either local or global. For example, if TARGET_ROOT equals OROUT(42), the output list appears in OROUT(42,"DILIST").

If the TARGET_ROOT is not passed, the list is returned descendent from ^TMP("DILIST",$J).

(Optional) The array that should receive any error messages. This must be a closed array reference and can be either local or global. For example, if MSG_ROOT equals "OROUT(42)", any errors generated appear in OROUT(42,"DIERR").

If the MSG_ROOT is not passed, errors are returned descendent from ^TMP("DIERR",$J).

See FROM under Input Parameters. If the FROM parameter is passed by reference and if there are more entries to return in the list, then the FROM array will be set to information about the last entry returned in the current Lister call. Subsequent Lister calls will use this information to know where to start the next list.

Other than FROM(1), none of the other FROM values from the index will contain data unless the next entry to return has the same index value as the last entry returned by the current Lister call. For example, if the index is on NAME and DATE_OF_BIRTH: if the last entry returned was for "Smith,John" and there is only one "Smith,John" in the file, then FROM(1)="Smith,John", FROM(2)="", FROM(3)="". However, if there is another "Smith,John", with a different DOB, then you might have FROM(1)="Smith,John", FROM(2)=2690101. If there are two "Smith,John" entries with the same DOB, then FROM(1)="Smith,John", FROM(2)=2690101, FROM(3)=the IEN of the last entry output.

The examples in this section assume that the output from the Lister was returned in the default location descendent from ^TMP("DILIST",$J), but it could just as well be in an array specified by the caller in the TARGET_ROOT parameter described above.

There are two different formats possible for the output: (1) Standard output format and (2) Packed output (format returned when the P flag is included in the FLAGS parameter).

1. Standard Output Format

The format of the Output List is:

• Header Node

  Unless the Lister has run into an error condition, it will always return a header node for its output list, even if the list is empty because no matches were found. The header node on the zero node of the output array, has this format:

  ^TMP("DILIST",$J,0) = # of entries found 
  ^ maximum requested ^ any more? ^ results flags
  

  1. The # of entries found will be equal to or less than the maximum requested.
     
     
  2. The maximum requested should equal the NUMBER parameter, or, if NUMBER was not passed, "*".
     
     
  3. The any more? value is 1 if there are more matching entries in the file than were returned in this list, or 0 if not.
     
     
  4. The results flag at present is usually empty. If the output was packed, and some of the data contained embedded "^" characters, the results flag contains the flag H. Check for the the results containing H rather than results equal to H. For more information see "Details and Features. "
     
     
• Record Data

  Standard output for the Lister returns each field of each matching record on a separate node. Records are subscripted in this array by arbitrary sequence number that reflects the order in which the record was found.

  
  
  
  • Indexed Field (Simple Index)

    Unless suppressed with the "@" in the FIELDS parameter (the suggested practice), the indexed values are returned descendent from the 1 nodes in external format.

    ^TMP("DILIST",$J,1,seq#) = index_value

    NOTE: This is different from the Finder, which returns the .01 field value in the 1 subtree.

    
    
    
  • Indexed Field (Compound Index)

    If the Lister call used a compound index, an additional sequential integer reflects the subscript position at which the value was found.

    ^TMP("DILIST",$J,1,seq#,1) = first_subscript_
    index_value

    ^TMP("DILIST",$J,1,seq#,2) = second_subscript_
    index_value

    
    
    
  • IEN

    Each record's IEN is returned under the 2 subtree:

    ^TMP("DILIST",$J,2,seq#) = IEN

    The other values returned for each record are grouped together under the "ID" subtree, then by record.

    
    
    
  • Field Values or Field Identifiers.

    The output format is the same whether the field value is one of the Field Identifiers from the data dictionary for the file, or the field was requested in the FIELDS parameter. In addition, if the .01 field is not one of the indexed fields and is not suppressed by use of "@" in the FIELDS parameter, then it is also returned along with the other Field values. By default, field values are returned in external format.

    Field identifiers and field values are subscripted by their field numbers. Each node shows up as:

    ^TMP("DILIST",$J,"ID",seq#,field#) = field_value

    Fields default to external format unless I is passed in the FLAGS parameter (obsolete) or the I suffix is specified in the FIELDS parameter (recommended way to get internal field values).

    If both the "I" and "E" suffix are specified, an additional subscript level with the values of "E" and "I" is used to distinguish the external and internal values of the field. If a field is only returned in one format, the extra subscript is never included. Values output with the extra format specifier look like:

    ^TMP("DILIST",$J,"ID",seq#,field#,"E" or "I") = 
    field_value 

    
    
    
  • Output for field specifier "IX" in FIELDS

    A field specifier of "IX" in the FIELDS parameter retrieves the value of the indexed field(s). In the output, the values of these fields are returned as follows, where the final subscript is a sequential number indicating the subscript location in the index.

    ^TMP("DILIST",$J,"ID",seq#,0,1) = 
    first_subscript_index_value
    ^TMP("DILIST",$J,"ID",seq#,0,2) = 
    second_subscript_index_value
    

    If both the "I" and "E" suffix are specified, an additional subscript level with the values of "E" and "I" is used to distinguish the external and internal values from the index. If the subscript on the index is not derived from a field, i.e. if it's a computed subscript, then the internal and external value will both be the same, the value directly from the index.

  
  
  
  • 22.2Output for Computed Expressions 

    ^TMP("DILIST",$J,"ID",1,"C1",1)=
    value_of_computed_expression 

    
    
    
  • WRITE Identifiers

    WRITE (display-only) identifiers are grouped under the "WRITE" subtree of the "ID" tree, then by record number. It is the caller's responsibility to ensure that none of the WRITE identifiers issue direct READ or WRITE commands and that they issue any output through EN^DDIOL so it can be collected by the Lister. The output from all the WRITE identifiers for a single record is listed as individual lines of text:

    ^TMP("DILIST",$J,"ID","WRITE",seq#,line #) = 
     text generated by WRITE IDs
    

    
    
    
  • IDENTIFIER parameter

    Any text generated by the caller's IDENTIFIER parameter is returned in the last lines of the WRITE identifier text.

  
  
  
• Map Node for Unpacked Format 

  In order to facilitate finding information in the output, a Map Node is built for unpacked format. This node is returned in ^TMP("DILIST",$J,0,"MAP").

  The Map node for unpacked format describes what Field Identifier data can be found in the "ID" output data nodes. It contains ^-delimited pieces described below. The position of the piece in the map node corresponds to the order in which it can be found in the "ID" output nodes. If the data is returned in internal format, the piece will be followed by "I" (ex., "2I" means that the internal value of field 2 was returned in the output).

  • #: Individually requested field number, where # is the field number, for each field requested in the FIELDS parameter
    
    
  • FID(#): Field Identifier, where # is the field number.

2. Packed Output Format 

If the P flag is used to request packed output, the Lister packs all the return values into one output node per record. You must ensure that all requested data will fit onto a single node. Overflow causes error 206. Return values containing embedded "^" characters make the Lister encode the output data using HTML encoding (see "Details and Features")

• Header Node

  Identical to Standard Output Format

  
  
  
• Record Data

  Values in the output are delimited by "^" characters. Piece 1 is always the IEN. The values of other pieces depend on the value of the FIELDS parameter. If the FIELDS parameter is not passed, each record's packed node will follow this format:

  ^TMP("DILIST",$J,seq#,0)=IEN^Indexed_field_
  values^field_Identifiers^Write_Identifiers^
  Output_from_Identifier_parameter
  

  Field Identifiers are sequenced by field number. Output values specified by the FIELDS parameter are packed in the order in which they occur in the FIELDS parameter. WRITE identifiers are packed in the same order as their subscripts occur in the ID subtree of the file's data dictionary.

  To parse the output of the packed nodes, use the MAP node described below.

• Map Node for Packed Format 

  Because the packed format is not self-documenting and because individual field specifiers such as FID can correspond to a variable number of field values, the Lister always includes a map node when returning output in Packed format. This node is returned in ^TMP("DILIST",$J,0,"MAP").

  Its value resembles a data node's value in that it has the same number of ^-pieces, but the value of each piece identifies the field or value used to populate the equivalent location in the data nodes. The possible values for each piece in the map node are:

  • IEN: (the IEN)
    
    
  • .01: (the .01 field)
    
    
  • FID(#): (Field identifier, where # is the field number of the identifier)
    
    
  • WID(string): (Write identifier, where string is the value of the subscript in the ^DD where the identifier is stored (such as "WRITE"))
    
    
  • IDP: (Identifier parameter)
    
    
  • IX(n): Indexed field values, where "n" refers to the subscript position in the index.
    
    
  • #: Individually requested field, by field number

  NOTE: For any piece except IEN, the WID, or the IDP, if the internal value is to be returned, the piece will be followed by "I". Thus instead of "IX(1)", you would have "IX(1)I", indicating that the internal index value was being returned.

  For example, the map node for a Lister call on the OPTION file, if FIELDS=> "3.6I;3.6;4", might look like this:

  ^TMP("DILIST",$J,0,"MAP") = "IEN^.01^3.6I^3.6^4"

Aside from the optional screen parameter, the Lister applies one other screen to each index entry before adding it to the output list as follows: ^DD(file#,0,"SCR"). Other screens, such as the 7.5 node and field-level screens on various data types, are not checked because they relate specifically to entry and editing, not selection.

It is possible for any field with an output transform to sort differently than a user would expect. Although the value displayed is the output value, the value that determines its order is its internal value. When the I flag is used, the output transform is never executed, and the output will always appear in the expected order.

Since the Lister uses the "^" character as its delimiter for packed output, it cannot let any of the data contain that character. If any does, it will encode all of the data using an HTML encoding scheme.

In this scheme, all "&" characters are replaced with the substring "&" and all "^" characters with the string "&#94". This keeps the data properly parsable and decodable. The data for all records found, not just the ones with embedded ^s, will be encoded if embedded ^s are found in the data of any of the records.

If the Lister has encoded the output, it will include an H flag in ^-piece four of the output header node.

Data can be decoded using the VA FileMan library function call $$HTML^DILF(encoded string,-1). It can properly decode individual fields or complete packed data nodes.

The Lister treats indexes on fields of these two data types specially. For every other data type, the value of the indexed field is completely contained in the file indicated by the FILE parameter. For pointer and variable pointers, this is not the case. All index values come from the B index of the pointed-to file. The Lister uses the values in the pointed-to file, extending the search to the end of the pointer chain, to select records in the pointing file at the beginning of the chain.

For example, suppose the FILE parameter picks file A, and the INDEX parameter picks the X index, a cross-reference on a pointer field. Suppose further that field points to file B, whose .01 field points to file C, and file C's .01 is a set of codes. Then this Lister call will select records in file A (the pointing file) based on the index values it finds in file C (the pointed-to file).

The FROM("IEN"), SCREEN, and IDENTIFIER parameters always apply to the pointing file, the one identified by the FILE parameter, because they deal with actual record selection. However, for pointers and variable pointers, the FROM and PART parameters apply to the "B" index on the pointed-to file, since they deal with index values.

Variable pointers work similarly, except that their index values usually come from more than one pointed-to file.