LIST

This system command is used to display the source code of a single object or to list one or more objects which are contained in the current library. The options of the LIST command are explained below.

This document covers the following topics:

• Syntax Overview

• Listing the Contents of the Work Area

• Displaying an Individual Source Code

• Displaying a List of Objects

• Displaying a Presorted List of Preselected Objects

• Displaying Numbers and Sizes of Objects

• Displaying Sources Sequentially

• Displaying Directory Information

• Displaying Long Names of Cataloged Subroutines and Classes

• Displaying NOC Options of Cataloged Objects

• Displaying Compiler Options of Cataloged Objects

• Displaying Compiler Output of a Cataloged Object

• Displaying DDMs (Views)

• Options

• List of Objects

• List of Source

• Defining an Individual List Profile

See also LIST XREF and the LIST commands specific to DB2 or SQL database management systems (to be selected from the System Commands overview page) described in separate documentation sections.

Application programming interfaces: USR1054N, USR1055N, USR1056N, USR2018N, USR4216N. See SYSEXT - Natural Application Programming Interfaces in the Utilities documentation.

Syntax Overview

Notes:

1. Instead of the keyword DDM, you can also use the keyword VIEW (or V for short).
2. Since LIST can display long lines containing up to 244 characters, set the line size as big as possible, using profile parameter LS. If possible, set LS=250.

object-type

In place of object-type, you may specify one of the object types shown below or an asterisk (*).

object-name

In place of object-name, you may specify the name of an object (8 characters long at maximum; exception: 32 characters with LIST EXTENDED).

object-name-range

In place of object-name-range, you may specify asterisk (*) and wildcard (?) notations:

• To have all objects in the current library listed, you specify an asterisk (*) for the object-name-range, but no object-type.

• To have all objects of a certain type listed, you specify a certain object-type and an asterisk (*) for the object-name-range.

• If you wish a certain range of objects to be listed, you can use asterisk notation and wildcard notation for the object-name-range:

  • Asterisk notation is the option to specify an asterisk (*) in the object-name-range: the asterisk stands for any string of characters of any length.

  • Wildcard notation is the option to specify a question mark (?) in the object-name-range: the question mark stands for any single character.

• One or more asterisk and wildcard notations can be combined in an object-name-range.

• For a list of all objects from a specific start value or until a specific end value, you can use the notation > or < respectively.

• The notations < and > cannot be combined with each other or with asterisk or wildcard notation and can only be used for displaying a list of objects (see List of Objects below).

options

For a detailed description of the options, see Options.

extended-type

In place of extended-type, you may specify one of the object types shown below or an asterisk (*).

For a detailed description, see LIST EXTENDED below.

range-clause

Note:
SORTED cannot be used with the LIST COUNT command.

Syntax Element Description:

range-notation

• To have all objects in the current library listed, you use an asterisk (*).

• If you wish a certain range of objects to be listed, you can use asterisk notation and wildcard notation:

  • Asterisk notation is the option to specify an asterisk (*): the asterisk stands for any string of characters of any length.

  • Wildcard notation is the option to specify a question mark (?): the question mark stands for any single character.

• One or more asterisk and wildcard notations can be combined.

• For a list of all objects from a specific start value or until a specific end value, you can use the less than or greater than notation (< or >).

• The less than or greater than notation (< or >) cannot be combined neither with each other nor with asterisk (*) or wildcard (?) notation.

Settings

Where:

YNvalue= Y or N
N3value = 3-byte numeric value
A8value = 8-byte alphanumeric value
AFvalue = A or F
DPTWvalue = D, P, T or W

Note:
For the description of the options, see List Profile Parameters.

Listing the Contents of the Work Area

Displaying an Individual Source Code

Displaying a List of Objects

Displaying a Presorted List of Preselected Objects

Displaying Numbers and Sizes of Objects

Displaying Sources Sequentially

Displaying Directory Information

Displaying Long Names of Cataloged Subroutines and Classes

Displaying NOC Options of Cataloged Objects

Displaying Compiler Options of Cataloged Objects

Displaying Compiler Output of a Cataloged Object

LIST COMPOUT displays compiler information from the cataloged object in a report that can be displayed on screen or written to work file 1 or to a Natural source of type TEXT. If no additional options are specified or if required options are missing in the command, a map is displayed where the desired options and the output destination can be specified.

Command Syntax:

Syntax Element Description:

See also Examples of List of Objects Usage.

Displaying DDMs (Views)

Note:
Instead of the keyword DDM, you can also use the keyword VIEW (or V for short).

Options

In place of options, you may specify one of the options shown below.

Syntax Element Description

expand-option

Syntax Element Description

formatted-option

FORMATTED Option

The FORMATTED option applies to stowed data areas (where time stamp of source object and cataloged object are identical) and maps:

FORMATTED Options for Listing Maps

When you are listing maps, you may specify options in addition to the keyword FORMATTED:

LIST MAP map-name FORMATTED '_' '#'

LIST MAP map-name FORMATTED SETTINGS

LIST MAP map-name FORMATTED FIELDS

LIST MAP map-name FORMATTED EXTFIELDS

Diplaying Processing Rules for a Map

The following options cause the processing rules used by the map to be displayed. The rules are displayed in order of fields to which they are assigned, and per field in order of rank.

LIST MAP map-name FORMATTED RULES

LIST MAP map-name FORMATTED INLINERULES

LIST MAP map-name FORMATTED FREERULES

LIST MAP map-name FORMATTED AUTORULES

See also the subcommands LAYOUT and FORMAT in the section List of Source.

List of Objects

When you use asterisk or wildcard notation for the object name, you get a list of all objects that meet the specified selection criteria. On this list, you can then select objects for display, print, etc. by marking them with a function code, or you can enter a Natural system command or a LIST subcommand in the command line.

This section describes the functions, subcommands and function codes that are available in the list of objects which is displayed, for example, after you have issued a LIST * command. The following topics are covered:

• Explanation of the Column Headers

• Scrolling the Selection List of Objects

• New Criteria for the Selection List

• Information Displayed on the Selection List

• Items Intensified on the Selection List

• Subcommands for the Selection List

• Performing a Function on an Object

• Sorting the List of Objects

• Examples of List of Objects Usage

Explanation of the Column Headers

The list of objects contains the following columns:

Scrolling the Selection List of Objects

Once a list of objects is displayed, you can scroll it as follows:

• To scroll the list one page forward or backward, press PF8 or PF7 respectively.

• To scroll the list to its beginning or end, press PF6 or PF9 respectively.

New Criteria for the Selection List

When a list of objects is displayed, the fields immediately underneath the column headings show the selection criteria for the current list. You can change the selection criteria by overwriting the values of these fields. For information on the possible values for one of these fields, you enter a question mark (?) in the field.

Information Displayed on the Selection List

If there exists both a source and an object module for an object (as indicated in the column S/C), the information displayed refers to the source, not the object module.

Note:
When the sort function is active the source and the object module may be displayed separately, e.g. when the list is sorted by the object date and the source and the object module have different date values.

To display more information on source and cataloged objects

• Press PF11 to shift right.

  Or:
  Press PF10 to shift left.

Note:
By default the number of source lines of source objects is not calculated due to performance reasons. If you want the number of source lines of source objects being displayed, you can either enter the subcommand COUNTSOURCE ON or set in the LIST profile (see Defining an Individual List Profile below) the parameter COUNT-SOURCE-LINES to Y.

Items Intensified on the Selection List

If an item is displayed intensified on the left-most list page, this indicates that there is a discrepancy between the object's source and its object module. For information on the discrepancy, you may mark the object with the function code LD to list its directory information. To eliminate the discrepancy, it is usually sufficient to stow the object again (function code ST).

Subcommands for the Selection List

In a list of objects, you can enter a Natural system command or a LIST subcommand in the command line. Valid subcommands are:

Performing a Function on an Object

To perform a function on an object in the selection list, you simply mark the object with the appropriate function code in the left-hand column (titled Cmd).

You can mark several objects on the selection list with different function codes; the functions will then be performed one after the other.

The following function codes are available (possible abbreviations are underlined).

Sorting the List of Objects

The LIST command provides the possibility to sort the list of the displayed objects by several sort criteria.

Note:
To use this function, it is necessary to set the WRKSIZE (Size of Work Buffer Used by Sort Program) in the Natural profile parameter SORT to an appropriate value. The maximum size of the list that can be sorted is limited by the size of this work buffer.

To invoke the sort function

• Press PF4.

  Or:
  Enter a SORT subcommand on the list of objects.

SORT Subcommand Syntax

When you press PF4, a window is displayed where you can specify whether you want to sort the list or the sort field, and the sort order. You can sort the list in ascending or descending order by the following sort fields:

If you change the selection criteria after a list has been sorted and displayed, this will result in the creation of a new list from all objects contained in the library according to the selection criteria, which is then sorted by the selection criteria.

To switch off the sort mode

• Enter the subcommand SORT OFF.

  Or:
  Deactivate the sort function in the Sort Options window invoked by pressing PF4.

The sorted list is built in a Natural text object in library WORKPLAN. The name of the text object is generated by the LIST command. If the LIST profile is activated (see Defining an Individual List Profile below) the name of the text object and the library can be specified in the LIST profile.

Examples of List of Objects Usage

List of Source

The following topics are covered below:

• Subcommands for Listed Source

• Subcommands FIND, REF and SCAN

• Subcommand FORMAT

• Cursor-Sensitive Object Selection

Subcommands for Listed Source

When you have the source code of an object listed, in the command line, you can enter one of the subcommands listed in the following table.

Note:
By default, the database id (DBID) and file number (FNR) of the source library are not displayed in the header line of the listed source. If you want the DBID and FNR of the source library to be displayed, you can either enter the subcommand DBFNR ON or, in the LIST profile, set the parameter SOURCE-LIST-WITH-DBID-FNR to Y (see Defining an Individual List Profile below).

Subcommands FIND, REF and SCAN

Specifying value

value is a search string of up to 34 characters to be supplied with the FIND, REF or SCAN command.

If the value to be found is identical to the command option CAS, CASESENSITIVE, ABS, ABSC or ABSOLUTE, you have to enclose value in single quotation marks (' '), for example: FIND 'ABS'.

If you issue a command without value, a window prompts you for the required value. In the prompt window, you can also set options (Y = Yes, N = No) to determine whether the search is to be absolute and/or case-sensitive.

Absolute Search

If you issue a command with ABSOLUTE, all matches of value are found, even if value is part of a word. By default, the search is performed on whole words only.

You can also set ABSOLUTE as an option in the prompt window (see Specifying value).

Case-Sensitive Search

If you issue a command with CASESENSITIVE, the search is case-sensitive. The string to be found must exactly match the uppercase/ lowercase letter combination specified as value. By default, the search is not case-sensitive; all matches are found, regardless of the case in which the letters are specified.

You can also set CASESENSITIVE as an option in the prompt window (see Specifying value), and you can change the default setting for CASESENSITIVE in the LIST profile: see SCAN-CASE-SENSITIVE in Defining an Individual List Profile.

Absolute Combined with Case-Sensitive

ABSC (or ABSOLUTECASESENSITIVE) is a combination of ABSOLUTE and CASESENSITIVE.

Subcommand FORMAT

This subcommand only applies to stowed data areas (where time stamp of source object and cataloged object are identical) and maps.

For data areas, this subcommand corresponds to the option FORMATTED.

In the List Profile, you can specify how data areas are listed by default:

• formatted (that is, the display resembles a DEFINE DATA statement) or

• unformatted (that is, the display resembles that in the Natural data area editor).

In the List of Objects, you can use the subcommand DEFINE-DATA ON/OFF to set the default for the time the LIST command is being executed.

If data areas are listed formatted by default and if it is not possible to convert the data area source code into DEFINE DATA format, a corresponding message is displayed and the data area is listed unformatted.

When you enter the subcommand FORMAT for a map, a window will be displayed in which you can select one or more additional items related to the map to be displayed:

• Map settings (corresponds to subcommand SETTINGS).

• Map layout (corresponds to subcommand LAYOUT). When you select this item, you have the option to specify filler characters for input fields (AD=A and AD=M) and output fields (AD=O) to make these fields visible. You may specify any character as filler character.

• Field summary (corresponds to subcommand FIELDS).

• Processing rules (corresponds to subcommand RULES).

The items you select are displayed one after the other in the order in which they appear in the selection window.

In FORMAT mode, the same subcommands for scrolling - except B - and the subcommands FIELDS, LAYOUT, PRINT, RULES and SETTINGS are available as for a normal listed source (see above). Additional subcommands are available as described below for each item.

• Additional Subcommands for Map Layout
• Additional Subcommands for Field Summary List
• Additional Subcommands for Processing Rules

Additional Subcommands for Map Layout

Additional Subcommands for Field Summary List

Additional Subcommands for Processing Rules

Cursor-Sensitive Object Selection

Within a source that is being listed, you can mark with the cursor the name of an object referenced within that source, and the source of the selected object will be listed in a window.

For the source displayed within the window, the same subcommands - except PRINT, EXPAND and ZOOM - are available as for the "normal" listed source.

Defining an Individual List Profile

You can define an individual profile for the LIST command. For this purpose, the Natural LIST command provides the subcommand LISTPROF.

This command invokes the profile maintenance tool that

• creates a new LIST profile with default values as used internally, if the LIST profile does not exist;

• allows you to specify general values for single users for the profile parameters in the LIST profile (controlled by Natural Security);

• allows you to specify individual values for single users for the profile parameters in the LIST profile (controlled by Natural Security);

• provides a description of and help information on each profile parameter.

The profile maintenance tool shows a map with the general profile parameters and their current values. Using a PF-key or a command, you can switch to the settings of your own profile data.

Using line commands, parameters can be added to or removed from the user specific profile.

For further information, invoke the help screens of the single fields.

If new parameters are introduced, the profile maintenance tool internal command UPDATE integrates the changes into the LIST profile.

The LIST profile itself is named LIST-PRF and located in library SYSLIB. The default profile that is used for updates of the LIST profile is named LIST-DEF and is also located in library SYSLIB.

List Profile Parameters

The table below lists the parameters contained in the LIST profile and the possible values that can be entered. In addition, the table provides a brief description of the parameters. The default parameter values are underlined.