|Contents:||Main||Chapter||See Also:||Getting Started Manual||Advanced User Manual|
This procedure returns a sorted list of entries from a file. Callers must specify a file number. Callers can also specify the index to be used in sorting the output, a starting location, a number of records to retrieve and/or a partial match value. They can also pass screening logic. By default, the Lister returns the .01 field of the entries, along with the index value(s) used to retrieve them, and all identifiers for the entries. The developer can override the default output and return other information for the entries.
This call is designed to populate a GUI Listbox gadget. It merely returns a list of entries from an index. Starting values must be in the same format as the index, unlike a lookup which allows search values to be in external format. The caller can make an initial call to the Lister to return a number of records "n" from the file and follow that by subsequent calls to return the next "n" records.
(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.
If you DO NOT pass a FIELDS parameter, the Lister returns:
If you DO pass a FIELDS parameter but it does not contain the @ specifier, the Lister returns:
(Optional) Flags to control processing:
Backwards. Traverses the index in the opposite direction of normal traversal.
|E||22.2Complete list of matches is returned, even if Errors are encountered during the generation of the results.|
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.
|X||22.2Eighth parameter (below) may be a SORT TEMPLATE or COMPUTED EXPRESSION.|
(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 "nth" 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.
(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:
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.
The format of the Output List is:
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")
This is an example of a forward traversal of the "B" index on the Option file, limited to five entries that all begin with the characters "DIFG", but skipping any first entry that might equal "DIFG" (the FROM value is always skipped):
OUT("DILIST","ID",1,1)=Create/Edit Filegram Template
OUT("DILIST","ID",2,1)=Display Filegram Template
This related example reveals that there is a DIFG option. When we traverse backward, starting with the first entry from the previous example, DIFG is the only option that meets both the FROM and PART parameter criteria. The sequence number is 5. When we traverse an index backward to get a set number of records, the sequence number counts backward from that number in order to make the output come out in the same order as when we traverse forward. This type of Lister call is normally used in a GUI ListBox when the user is backing up on a list.
In this example we'll return just one entry from a file using a compound index. This index is on the .01 field (NAME) and field 1 (DATE OF BIRTH). Note how the two index entries are returned in the 1 nodes. Also note that this file has several field identifiers and WRITE identifiers. After the call, because there are two different entries in the file with a .01 equal to "ADDFIFTEEN", but different dates of birth, the DIFR array has been set up ready for a subsequent call. On this index, the DATE OF BIRTH field has a collation of "backwards", so we see the most current date first in the output.
>K DIFR,DIPRT S DIPRT(1)="ADD"
OUT("DILIST",1,1,2)=JAN 03, 1997
OUT("DILIST","ID",1,10)=MAY 02, 1997@09:00
OUT("DILIST","ID","WRITE",1,3)= FIRST LINE
OUT("DILIST","ID","WRITE",1,5)= SECOND LINETHIRD LINE
However, if we do another Lister call on the same file, using the DIFR array that was passed back from the previous call, this time we'll return two records. We get back the second record in the index with "ADDFIFTEEN" as the .01 field, and the next one that follows it alphabetically. In this call, we suppressed the normal default values returned by the call, and instead asked for the index field values "IX", the internal value of the field identifiers "FIDI", both the internal and external values of field 3 (a set-of-codes type field), and the external value of computed field 8. All of this was done with entries in the FIELDS parameter. As you see, field 4 is a pointer, field 10 is a variable pointer. Note how the MAP node describes what is found in the "ID" nodes.
OUT("DILIST","ID",1,0,2)=JAN 01, 1969
OUT("DILIST","ID",2,0,2)=JAN 01, 1949
In this example, we use the P flag to return the next two records in Packed output format. We revert to letting the Lister return default values, rather than controlling them with the FIELDS parameter, but we'll return additional output by using the IDENTIFIER parameter. Note that although we asked for two records, there was only one left that fit our PART criteria. The first piece of the header node tells us one record was returned; the second piece tells us that two records were requested; the third tells us there are no records left that meet the criteria.
Here's what the FROM values are set to going into the call:
EN^DDIOL(""Hi there"")"," OUT")
OUT("DILIST",1,0)=16^ADDSIXTEEN^MAR 28, 1970^MA HERE TOO*^^DIFG^2700328^^ FIRST
LINE~~ SECOND LINETHIRD LINE^^Hi there
|120||Error occurred during execution of a VA FileMan hook.|
|202||Missing or invalid input parameter.|
|205||The File and IENS represent different subfile levels.|
|206||The data requested for the record is too long to pack together.|
|207||The value is too long to encode into HTML.|
|301||The passed flags are missing or inconsistent.|
|304||The IENS lacks a final comma.|
|306||The first comma-piece of the IENS should be empty.|
|401||The file does not exist.|
|402||The global root is missing or not valid.|
|406||The file has no .01 field definition.|
|407||A word-processing field is not a file.|
|420||The index is missing.|
|501||The file does not contain that field.|
|520||That kind of field cannot be processed by this utility.|
The Lister may also return any error returned by $$EXTERNAL^DILFD.
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 "^". 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.
|Pointers and Variable Pointers||
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.
|WRITE ID nodes||The Lister executes each individual WRITE ID node from the data dictionary. If an individual node results in creating multiple lines in the output from the EN^DDIOL call(s) it contains, then in Standard Output Format the results will appear on multiple lines in the output array. Thus there is not a direct correlation between the number of WRITE ID nodes and the number of nodes that will be returned in the output array of a Lister call for each record. In Packed output format, each WRITE ID node appears in a separate "^" piece and line feeds are designated with a tilde (~) character.|
|FROM parameter with Compound Indexes||The FROM parameter designates only a starting point on the index defined in the INDEX parameter. For example, we have a compound index where the first subscript is a NAME and the second is a DATE OF BIRTH. Supposing that after a Lister call, FROM(1)="SMITH,JOHN" and FROM(2)="2690101. A subsequent Lister call assumes that there must be another entry with the name "SMITH,JOHN", but a date-of-birth that follows 1/1/69. Any other entries returned will have names that equal or follow SMITH,JOHN, but after processing all of the SMITH,JOHN entries, other output entries could have any date-of-birth. This is NOT like a sort where we say that we want only entries where the date-of-birth follows 1/1/69.|
Reviewed/Updated: October 2016