If DISP$ is passed to CDS037, it contains the field names and optional formatting details.  In the most basic form DISP$ contains the field names to be displayed separated by the pipe (|) character.  The trailing pipe is optional.

"CUSTNO|NAME|ADDRESS|CITY|STATE|ZIP" would be a valid DISP$. See Example 2.

Following each field name, you may specify additional positional arguments separated by back slash (\).  The complete format for each field is: FILPGM.FIELD[INDEX]\Title\Mask.

can be set to the number of horizontal print positions for the window, including the window border.  If not specified, WINCOLS will be computed based on the number of positions required to display the data.  If the window width exceeds the physical display, then the display will be shifted into 132 column mode if supported by that display.  If the window width still exceeds the physical display, then WINCOLS will be set to the physical display, either 80 or 132 columns.

By setting WINCOLS to 80, you can force the screen to stay in 80 column mode, even when more than 80 columns are required to display all data.

By setting WINCOLS to 132, you can force the screen to use 132 column mode, even when the data will display in 80 columns or less.

can be used on color terminals to override the default colors.  By default, the colors used are those specified in Operator Preference Maintenance for Display (F2).  If different colors are preferred, then COLORS$ should contain the zero filled, three 3-digit color numbers corresponding to the window border, window text, and highlighted selected text respectively.  It may also contain a 4th color number which will be used for the column headings and grid lines.  Refer to Operator Preference Maintenance (SMS) for the specific color numbers to use or click here.  See Example 7.

The chart below lists several COLORS$ values that produce good, high-contrast, displays.  See example to view many more COLORS$ values.

Alternatively you may print another window, then 'POP' it before exiting back to CDS037.  Effective with versions dated 11/24/04, the default colors are changed to the primary display color once a record is selected.  These colors are typically different than the colors used within CDS037 during record selection.

Note: the 'SP' mnemonic is used to place the display back to 80 column mode, for those cases where CDS037 has displayed in 132 column mode ('CP').  At the end of the routine, you only need to 'POP' the window.  CDS037 will convert the display back to 132 column mode and restore the colors if required.

You may modify SELREC$ within the selection routine and write the modified record back to the disc.  If you do modify the record, CDS037 will re-display the record. See example programs CDX090 and 091.

If you do not change the record, but want CDS037 to redisplay the record, because of related file display, or external programs referenced in DISP$, then return L as 0 to CDS037.

In some cases, you may need to modify more than one record in the file, or even add records to the primary data file.  In this case return L as a negative number to signal CDS037 to restart. This option is useful when the external routine added and/or deleted records. Note that the first record will be highlighted after the restart, just as if calling CDS037 again.

SELRTN$ can also remove records from the primary data file.  If so, then DIM SELREC$:FATTR(SELREC$) before exiting.  This is required in order to keep any temporary work file created by CDS037 to remain synchronized with the primary data file.

CDS037 creates a work file whenever it needs to use SELECT instead of OPEN on the primary data file.  CDS037 will use SELECT instead of OPEN when you pass a non-blank WHERE$, SORTBY$, or MODE$.  If SELRTN$ modifies or deletes a record in the primary data files, then CDS037 will modify or remove the record in the work file.  However it does not add records to the work file that are added by the SELRTN$ nor can it change more than one record.  This means that you should only modify or delete a single record at a time when using WHERE$, SORTBY$, or MODE$.

In most cases, you can do what is necessary within the record selection routine.  There is another option of CDS037 that actually exits CDS037, passing you the SELREC$, but does not pop the display window.  This option is invoked by passing SELRTN$ as "*exit*".  The calling program may modify the selected record and CDS037 will display the revised record if CDS037 is called again.  After processing is completed outside of CDS037, then by calling CDS037 again, the list of records will re-display, the highlighted record will be moved down to the next record.  Note that this option does not offer a method of informing CDS037 that records other than the selected record was changed, nor if any records were added or deleted.

You can also pass SELRTN$ as "CDS279" which will display the selected record with one field per row in a separate window.

When SELRTN$ is not used, and CDS037 is called with a complete ENTER list including SELREC$, then when the user highlights a record and touches the Enter key, CDS037 exits and returns the selected record to the calling program.  It is possible to enable that option even when using SELRTN$.  In that case the user has two options: Touching Enter will exit CDS037 and return the selected record to the calling program, and touching F2 will call the SELRTN$ program.  To enable this option, append a colon (:) and F2 prompt text to SELRTN$.  For example, if SELRTN$="PO150:Display PO Line Items", then the CDS037 prompt will include: Enter=select record, F2=Display PO Line Items, F3=Help, F4=End.  If the user touches the Enter key, then CDS037 will exit and the highlighted record will be returned to the calling program.  If the user touches F2, program PO150 will be called, and when it exits, the CDS037 window will be re-displayed, the highlighted row moves down to the next record, just like when SELRTN is used.  Note that because of the use of a colon as the separator between the program name and the F2 prompt text, you cannot include a colon in the program name.

The following four parameters WHERE$, SORTBY$, MODE$, and LIMIT are used when instructing CDS037 to use a SELECT verb.  When any of these parameters are specified, the KNO and KEYPFX$ parameters are ignored.  When one of these SELECT parameters is specified, CDS037 will create a temporary file in the tmp/ subdirectory, however, on Unix systems, this file will not appear in a disc directory and will be automatically erased when the display is completed or if the process is killed or otherwise aborted.

If there is a KNUM of the data file that can be used to limit the records to be displayed, use the KNO and KEYPFX$ parameters instead of WHERE$.  This will result in faster operation and eliminate the need for the temporary work file.

WHERE$ may be used when only selected records are to be displayed.  The format of WHERE$ is that used for the SELECT verb.  You can refer to the record template string as REC., the file name, i.e, CM01., or leave off the string.  All of the following are equivalent:
POS(REC.STATE$="OHPAWV",2)
POS(CM01.STATE$="OHPAWV",2)
POS(STATE$="OHPAVW",2)

If the WHERE$ parameters is not specified, but one of the other SELECT parameters are specified, then all records in the file will be displayed. 

Note that the WHERE$ cannot include any fields derived from related files or called routines.  Only fields located in the primary file can be used.

is used when special sorting sequence is desired.  You may use REC., the string based on the file name, i.e., CM01. or leave off the string as explained above for WHERE$.  Unlike the WHERE$ clause, SORTBY$ can contain fields from related files or other called routines.

When sorting by a numeric field, use the functions listed below: For U type fields, use the string version of the field name as in REC.VALUE$.  For all other numeric fields, use ADJN(REC.AMOUNT).

When a segment of a sortby key must be descending, add the NOT() function as shown below.  For string fields, use NOT(REC.FIELD$).  For U type numeric fields, use the string version of the field name as in NOT(REC.VALUE$).  For all other numeric fields, use NOT(ADJN(REC.VALUE)).

Set by CDS037 as the primary file record selected by the operator.  SELREC$ does not need to contain anything when passed to CDS037, but will contain the template based selected record unless the operator touches F4 to exit.  You can disable the message at the bottom of the display that prompts the operator to highlight and select a record by excluding SELREC$ from the variables passed to CDS037.  SELREC$ is typically passed as the actual file name variable as in CM01$, IM01$, etc.

Note that when SELREC$ is passed to CDS037, in addition to setting CTL=4 if the operator touches F4 instead of selecting a record, CDS037 will also set CTL=4 if the file specified in FILENAME$ cannot be opened, or if there are no eligible records to display.  The calling program should not also perform such tests unless it is desirable not to inform the operator.