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:

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

LIST

[object-type] object-name-range [settings]

[object-type] object-name [options] [settings]
object-name-range [range-clause] [settings]
COUNT [object-name-range] [range-clause] [settings]
SEQUENTIAL [object-type] object-name-range [options]
DIRECTORY

object-name
object-name-range

 
EXTENDED [ extended-type] object-name-range [settings]
NOCOPT [object-type] object-name-range [settings]
OPTIONS [object-type] object-name-range [settings]
COMPOUT [compout-options] [settings]
DDM [ddm-name]

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 (*).

*

CLASS
4

COPYCODE
DATA-AREAS
  GLOBAL
  LOCAL
  PARAMETER

DIALOG
3

FUNCTION
7

ADAPTER
8

RESOURCE
9

MAP

PROCESSOR
CP
5

PROGRAM
RECORDING
ROUTINES
  HELPROUTINE  
 

SUBPROGRAM
N

  SUBROUTINE  
TEXT

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 (*).

*

CLASS
4

FUNCTION

7

SUBROUTINE

For a detailed description, see LIST EXTENDED below.

range-clause

[TYPE=type-list]
[KIND=kind-range]
[MODE=mode-range]
[VERSION=version-range ]
[USER=user-range]
[DATE=date-range]
[TIME=time-range]
[CP=code-page-range]
[ARCHLEVEL=arch-level-range]

SORTED=

TYPE
MODE
VERSION
USERID
DATE

ASCENDING
DESCENDING

DT
DATETIME

TIME
SIZE
LINES
BPSIZE

DSIZE
DATSIZE

CP
CODE-PAGE

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

Syntax Element Description:

Syntax Element Description
type-list * (for all types) or a list of up to 11 valid 1-byte Natural object type characters (e.g. P for Program, M for Map).
kind-range * List all objects.
S List only source objects.
C List only cataloged objects.
S/C List only objects which exist as source and cataloged.
S/ List only objects which exist as source only.
/C List only objects which exist as cataloged only.
W List only stowed objects.
mode-range * List all objects.
S List only structured mode objects.
R List only report mode objects.
version-range

The Natural version of the Natural objects.

You can also specify a range of versions: see range-notation.

See also the definition of the term Version in the Glossary.

user-range

The ID of the user who saved or cataloged a Natural object.

Specify a single user ID or a range of user IDs: see range-notation.

date-range

Selects all objects with a save or catalog date within the date range specified. Specify a single date or a date range.

Valid date format: YYYY-MM-DD

Valid date ranges:

  • Leading characters (Example: 2002*)

  • Start value (Example: 2002-05>)

  • End value (Example: 2003-02<)

Special dates allowed are:

TODAY (+/-nnnn)

All items with the date of the current day.

The day can be followed by +nnnn or -nnnn where nnnn has a maximum of 4 digits.

The resulting date is computed as the date of the current day plus or minus nnnn days.

Can be combined with the start value option (>) or the end value option (<), e.g. TO-1> selects all objects that were saved or cataloged within the last 2 days.

YESTERDAY All items with the date of the day before the current day.
MONTH All items with the date range of the current month.
YEAR All items with the date range of the current year.
time-range

Selects all objects with a save or catalog date within the time range specified. Specify a single time or a time range.

Valid time format: HH:II:SS (HH = hours, II = minutes, SS = seconds).

Valid time ranges:

  • Leading characters (Example: 10:*)

  • Start value (Example: 10:30>)

  • End value (Example: 11:20<)

code-page-range Specifies a single code page or a range of code pages: see range-notation below.
arch-level-range Only applies if Natural Optimizer Compiler is installed and if the ARCH option is set to supply IBM architecture levels (see the Natural Optimizer Compiler documentation).

Lists all Natural objects that were cataloged under the Natural Optimizer Compiler with the ARCH option set.

You can specify a single level or a range of levels as explained below, where n is a one or two-digit level number:

n* Lists all objects with levels n to 9.
n> Lists all objects with levels equal to or greater than n.
n< Lists all objects with levels less than n
nn Lists all objects with levels equal to nn.
nn* Lists all objects with levels equal to nn.
nn> Lists all objects with levels equal to or greater than nn.
nn< Lists all objects with levels equal to or less than nn.

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

SET

REUSE-LAST-LIST=YNvalue
RLL=YNvalue

 

COUNT-SOURCE-LINES=YNvalue
CNTS=YNvalue

 

SORT-TEXT-MEMBER-NAME=A8value
STMNA=A8value

 

SORT-TEXT-MEMBER-LIBRARY=A8value
STMLI=A8value

 

DELETE-SORT-TEXT-MEMBER=YNvalue
DELST=YNvalue

 

PRINT-PAGE-SIZE=N3value
PPS=N3value

  [MARK-LONG-LINES=YNvalue]
 

DATA-AREA-DEFINE-DATA-FORMAT=YNvalue
DADDF=YNvalue

 

SOURCE-LIST-WITH-DBID-FNR=YNvalue
SLDF=YNvalue

 

PAGE-TITLE-IN-BATCH=AFvalue
PTIB=AFvalue

 

OUTPUT-DESTINATION-IN-BATCH=DPTWvalue
ODIB=DPTWvalue

 

OUTPUT-TEXT-NAME=A8value
OTN=A8value

 

OUTPUT-TEXT-LIBRARY=A8value
OTL=A8value

 

TOTAL-LINES-DISPLAY-BATCH=YNvalue
TLDB=YNvalue

  [USEMAINPR=YNvalue]
 

LIST-SHIFT-INCREMENT=N3value
LSI=N3value

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

LIST If you enter only the LIST command itself, without any parameters, the contents of the work area will be listed.

Displaying an Individual Source Code

LIST object-name [options]

In both cases, the object's source code will be listed.

If you enter a single object name with the LIST command, you need not specify the object-type. If you specify an object-type, you must also specify an object-name.

LIST object-type object-name [options]

Displaying a List of Objects

LIST object-name-range In both cases, you must use asterisk (*) and/or wildcard (?) notation for the object-name-range. You get a list of all objects that meet the specified selection criteria. On the list you can then select objects for display by marking them with the function code LI (see Performing a Function on an Object).
LIST object-type object-name-range

Displaying a Presorted List of Preselected Objects

LIST object-name-range

In both cases, you must use asterisk (*) and/or wildcard (?) notation for the object-name-range. You get a list of all objects that meet the specified selection criteria. On the list you can then select objects for display by marking them with the function code LI (see Performing a Function on an Object).

With the range-clause, you specify additional selection and sorting criteria. See also example below.

LIST object-name-range range-clause

Displaying Numbers and Sizes of Objects

LIST COUNT [range-clause] [settings] Displays a summary report that contains the numbers and sizes (in bytes or KB if greater than 1 MB) of objects stored in the current library.

The numbers and sizes listed refer to all objects that have been saved as source (saved) objects only or as cataloged objects only, and all objects for which both saved and cataloged objects (stowed) exist, according to the selection criteria specified in the range-clause.

See also Examples of List of Objects Usage.

LIST COUNT object-name-range [range-clause] [settings] Displays an extended report where the numbers and sizes of saved/cataloged objects (same as above) are listed per object type(s) found, according to the selection criteria specified in the object-name-range and the range-clause.

Object type unknown indicates that no directory information exists for these objects.

See also Examples of List of Objects Usage.

Displaying Sources Sequentially

LIST SEQUENTIAL object-name-range [options] In both cases, you must use asterisk (*) and/or wildcard (?) notations for the object-name-range. Then the sources of all objects that meet the selection criteria will be displayed sequentially, i.e. one after the other.
LIST SEQUENTIAL object-type object-name-range [options]

Displaying Directory Information

LIST DIRECTORY Displays the directory information on the object currently in the work area:
  • Source code:

    Date/time when the source was saved,
    library name, user ID, programming mode (reporting or structured),
    TP system, terminal ID, operating system, transaction code,
    Natural version, code page information (if available), source size

  • Object code:

    Date/time when the source was cataloged,
    library name, user ID, programming mode,
    DBID (database ID) and FNR (file number) of the library where the object was cataloged (for objects cataloged with Natural Version 9.1 and above),
    TP monitor system, terminal ID, transaction code, Natural version,
    code page information (if available), operating system,
    size in DATSIZE, size in buffer pool, size of global data,
    size of NOC code (machine code generated by Natural Optimizer Compiler),
    GDA used by the object, date/time when the used GDA was cataloged,
    GDA time stamp from the date/time when the GDA was cataloged,
    GDA time stamp from the date/time when the source was cataloged,
    number of subroutines used by the object,
    Natural Optimizer Compiler (NOC) options set with the OPT profile parameter when the source was cataloged
    Architecture (ARCH) level used when cataloging the source with the Natural Optimizer Compiler (NOC) and the ARCH option set (see the Natural Optimizer Compiler documentation).

LIST DIRECTORY object-name

Displays the directory information (as described for LIST DIRECTORY) on the specified object.

If asterisk (*) and/or wildcard (?) notation is used in place of object-name-range, the directory information of the corresponding objects is displayed sequentially.

LIST DIRECTORY object-name-range
LIST object-name WITH DIRECTORY This command first displays the directory information (as described for LIST DIRECTORY) on the specified object and then lists the source code of the object.

Displaying Long Names of Cataloged Subroutines and Classes

LIST EXTENDED object-name-range Displays a list of the long names of cataloged subroutines, classes and functions. For the name options, see object-name-range above.
LIST EXTENDED extended-type object-name-range

Displaying NOC Options of Cataloged Objects

LIST NOCOPT [object-type] object-name-range Displays a list of the cataloged objects that are compiled with Natural Optimizer Compiler (NOC), together with the initial NOC options used during CATALOG. For the name options, see object-name-range above.

Displaying Compiler Options of Cataloged Objects

LIST OPTIONS [object-type] object-name-range Displays a list of the cataloged objects together with the compiler options used during CATALOG. For the name options, see object-name-range above.

By default, the final compiler options (that is, the options setting active at the end of the CATALOG) are displayed. For objects cataloged with Natural Version 4.2.5 or above, also the initial compiler options (that is, the options setting active at the beginning of the CATALOG) or the changed compiler options (that is, the options setting that are changed within the source code) can be displayed. See the corresponding help map for the range fields on the online map.

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:

LIST COMPOUT

object-name [REPORT]

[UNVARIABLES]
[USEDVARIABLES]
[CONTSUBROUTINES]
[EXTSUBROUTINES]
[STATPROFILE]
[STATCATEGORY]
[STATTYPE]
[DESTINATION]
[SCREEN]
[WORKFILE]
[TEXT [text-name [LIBRARY library-name]]]

Syntax Element Description:

Syntax Element Description
object-name The name of the cataloged Natural object.
REPORT Just a filler to make the command more readable, can be omitted.
UNVARIABLES Add to the report all unused variables, that is, variables that are defined but not referenced or modified.
USEDVARIABLES Add to the report all used variables, that is, variables that are referenced or modified.
CONTSUBROUTINES Add to the report the contained external subroutine (for Natural objects of type SUBROUTINE only).
EXTSUBROUTINES Add to the report the used external subroutines.
STATPROFILE Creates a report that displays contiguous sequences of statements grouped by categories in a source program suitable for optimization, or lists the NOC coding generated for an optimized program; see also NOCSTAT Command , Code Profile, in the Natural Optimizer Compiler documentation).
STATCATEGORY Creates a report that lists various categories of statements with the corresponding number of occurrences; see also NOCSTAT Command , Statement Category, in the Natural Optimizer Compiler documentation).
STATTYPE Creates a report that lists single statements with the corresponding number of occurrences; see also NOCSTAT Command , Statement Type, in the Natural Optimizer Compiler documentation).
DESTINATION Just a filler to make the command more readable, can be omitted.
SCREEN Show the report on the screen. This is the default value.
WORKFILE Write the report to work file 1.
TEXT Write the report to a Natural source of type TEXT.
text-name Name of the Natural source of type TEXT. The default value is REPCPOUT.
LIBRARY library-name Library name for the Natural source of type TEXT. The default value is the current library.

See also Examples of List of Objects Usage.

Displaying DDMs (Views)

LIST DDM Displays a list of all DDMs.
LIST DDM ddm-name If you specify a single DDM name, the specified DDM will be displayed.

For the ddm-name you can use a single DDM name (up to 32 characters) or a range as for object-name-range to display a list of a certain range of DDMs.

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.

[[WITH] DIRECTORY] [NUMBERS OFF] [expand-option]

formatted-option
CONVERTED
UNCONVERTED

Syntax Element Description

DIRECTORY This option first displays the directory information (as described below, see Displaying Directory Information) on the specified object and then lists the source code of the object.
NUMBERS OFF By default, the source code of an object will be listed with source-code line numbers. To list it without line numbers, specify the NUMBERS OFF option. (See also subcommands NUMBERS ON/NUMBERS OFF in the section Subcommands for Listed Source.)
UNCONVERTED By default, the source is listed in the session code page (see system variable *CODEPAGE)).

To list the source in the code page as stored on the system file, specify this option.

CONVERTED If the source is listed in the code page as stored on the system file (by option or command UNCONVERTED), specify this option to list the source in the session code page (see system variable *CODEPAGE)).

expand-option

EXPAND [ FORMATTED]

COMMENTS
n

[expand-type ...10]

object-name
object-name-range

Syntax Element Description

EXPAND object-name

With the EXPAND option, you can have the sources of other objects referenced by the listed object - copycodes, data areas, maps, helproutines, external subroutines, subprograms, programs called with a FETCH statement, error messages - listed within the source of the listed object. This option is particularly useful in batch mode.

For example, if a listed source program contains an INCLUDE statement, you can have the source code of the included copycode listed within the listed source program immediately after the INCLUDE statement.

Objects listed within a source will be referred to as "expand objects" in the explanations below.

Subcommands in Expand Object

Within a listed expand object, only the following subcommands are available:

PRINT
+
- -
.

See Examples of List of Objects Usage.

EXPAND object-name-range
EXPAND FORMATTED

The EXPAND FORMATTED option is only relevant for stowed data areas (where time stamp of source object and cataloged object are identical) and maps listed within a source.

For data areas, the following applies:

  • If FORMATTED is not specified, the display of the data area will resemble that in the data area editor

  • If FORMATTED is specified, the display of the data area will resemble a DEFINE DATA statement. This only applies to stowed data areas (i.e. the time stamp of source object and cataloged object are identical); see also subcommand FORMAT.

For maps, the following applies:

  • If FORMATTED is not specified, the map source will be listed.

  • If FORMATTED is specified, the map layout will be displayed (that is, the map as it is displayed to the users at runtime).

EXPAND COMMENTS

If you use the option EXPAND COMMENTS, only the initial comment lines of the expand object will be listed; that is, the expand object will be listed until (but not including) the first source-code line which is not a comment line.

If you use the option EXPAND n, only the first n lines of the expand object will be listed.

If you use neither of these two options, the entire expand object will be listed.

EXPAND n
expand-type

As expand-type, you specify the object type(s) of the expand object(s). The following expand-types can be specified:

P Programs If you wish to specify more than one expand-type, you can specify them in any sequence and without blanks between them; for example, to have maps, copycodes and subroutines listed within the listed source, specify the expand-type as MCS.
N Subprograms
S External subroutines
H Helproutines
G Global data areas
L Local data areas
A Parameter data areas
M Maps
C Copycodes
E Error messages
4 Classes
* All object types
object-name

As object-name or object-name-range, you specify the name(s) of the expand object(s) to be listed within the main listed source.

The same notations are possible as for object-name or object-name-range, except < and >.

object-name-range

formatted-option

FORMATTED ['c']   ['c']   [SETTINGS]  

FIELDS
EXTFIELDS

 

RULES
INLINERULES
FREERULES
AUTORULES

FORMATTED Option

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

FORMATTED
Stowed Data Area:

If you specify the FORMATTED option for a data area, the data area will be displayed formatted; that is, the display resembles a DEFINE DATA statement; see also subcommand FORMAT.

This only applies to stowed data areas (i.e. the time stamp of source object and cataloged object are identical). By default, data areas are displayed unformatted; that is, the display resembles that in the data area editor.

The default setting can be changed with in the List Profile. (Refer to Defining an Individual List Profile below and see also subcommand FORMAT ).

Map:

If you specify the FORMATTED option for a map, the map layout will be displayed; that is, the map as it is displayed to the users at runtime.

FORMATTED Options for Listing Maps

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

['c'] ['c']
Using Filler Characters:
You may specify filler characters c 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.

The following example shows all input fields with an underscore (_) and all output fields with a hash (#).

LIST MAP map-name FORMATTED '_' '#'
SETTINGS
Map Settings:
Displays the map settings of the specified map.
LIST MAP map-name FORMATTED SETTINGS
FIELDS
Field Summary:
Displays the field summary; that is, the list of fields in the specified map.
LIST MAP map-name FORMATTED FIELDS
EXTFIELDS
Extended Field Editing Information:
Causes the extended field editing information for all map fields to be displayed.
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.

RULES
All Rules:
LIST MAP map-name FORMATTED RULES

Displays all the rules for the specified map.

INLINERULES
Inline Rules Only:
LIST MAP map-name FORMATTED INLINERULES

Displays only the inline rules for the specified map.

FREERULES
Free Rules Only:
LIST MAP map-name FORMATTED FREERULES

Displays only the free rules for the specified map.

AUTORULES
Automatic Rules Only:
LIST MAP map-name FORMATTED AUTORULES

Displays only the automatic rules for the specified map.

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

The list of objects contains the following columns:

Column Explanation
Cmd In this column, you can enter a code to perform a function on an object in the selection list. See Performing a Function on an Object.
Name Name of object.
Type Type of object.
S/C Indicates whether the object exists as source (S) and/or cataloged object (C).
SM The Natural programming mode that was used when the object was created. S = structured mode, R = reporting mode.
Version Product version of Natural that was used to create or catalog the object.
User ID User ID of the user who created or cataloged the object.
Date, Time Date and time when the object was created or cataloged.

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.

Start of instruction setTo 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:

Code Function
SC List only objects containing a scan value (can only be used with long list).
SC OFF Switch off scan mode.
SHORT Display a short list of objects, i.e., display only the object names (can only be used if scan mode is off).
LONG Switch to long list including all fields available.
PRINT Print the list of objects.
EXTENDED Display the list of long names of subroutines/classes; same as LIST EXTENDED *.
ALL fx Enter the function code fx (where fx is a valid function code for a listed object) for all displayed objects.
SORT Invoke the sort window (see Sorting the List of Objects below).
COUNTSOURCE ON Display the number of source lines for source objects.
OFF Do not display the number of source lines for source objects.
MARK-LONG-LINES ON

Mark long lines in the list of a source object with an L in the first two positions.

The default value can be specified in the LIST profile; see Defining an Individual List Profile.

OFF Do not mark long lines in the list of a source object.
DEFINE-DATA ON

A listed data area source is listed in DEFINE DATA format by default (same as LIST data-area FORMATTED).

The default value can be specified in the LIST profile; see Defining an Individual List Profile.

OFF A listed data area source is listed unformatted.
LISTCOUNT List the number of objects and their sizes according to the selection criteria currently used.
LISTPROFILE Display the current value of the parameters of the LIST profile (see Defining an Individual List Profile below).
NOCOPT Display a list of the cataloged objects that are compiled with Natural Optimizer Compiler (NOC), together with the initial NOC options used during CATALOG; same as LIST NOCOPT *, see Displaying NOC Options of Cataloged Objects.
OPTIONS Display a list of the cataloged objects together with the initial compiler options used during catalog; same as LIST OPTIONS *, see Displaying Compiler Options of Cataloged Objects.
USE-TIMESTAMP ON Use the time stamp of the cataloged object for displaying the catalog date and time in the object list.
OFF Use the date and time values from the cataloged object directory for displaying the catalog date and time in the object list. See also the option SHOW-CAT-TIMESTAMP-VALUES in Defining an Individual List Profile.
REUSE ON Switch on reuse mode.

The last displayed list is reused after execution of commands entered in the Cmd column, except for the following commands:

E
ED (Edit)
CA (Catalog)
UC (Uncat)
S
ST (Stow)
D
DE (Delete)
RE (Rename)

OFF Switch off reuse mode.

The list is rebuilt after execution of commands entered in the Cmd column.

REFRESH Rebuild the currently displayed list. This subcommand can be used especially when reuse mode is switched on.
+ Scroll one page forward.
- Scroll one page backward.
++ Scroll to the end (bottom) of the object list.
-- Scroll to the beginning (top) of the object list.
? Command line help.

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).

Code Function
? A window will be displayed which shows all the functions available for the marked object. The window will only list those functions that are actually available for the selected object (for example, if the object is a subroutine, it cannot be run; if the object is only available in source form, it cannot be executed).

From the window you can select the function to be performed on the marked object.

CA Compile the object and store it in object form (equivalent to the system command CATALOG).
DE Delete the object (equivalent to the system command DELETE).
DL Download object from mainframe to personal computer (only available if Natural Connection is installed).
ED Edit the object's source code (equivalent to the system command EDIT).

Note:
This command is not available if the Natural program, data area and map editor are disabled in your environment. For more information, see Disabled Natural Editors in the Editors documentation.

EX Execute the object (equivalent to the system command EXECUTE).
LC List object's source code converted into the default code page *CODEPAGE, (equivalent to LIST object-name CONVERTED).
LD List directory information (equivalent to LIST DIRECTORY object-name) on the object.
LE List object's source code in expanded form (equivalent to LIST object-name EXPAND *).
LF Display a data area or map formatted (equivalent to LIST object-name FORMATTED).
LI List the object's source code.
LN Display long name of subroutine or class (only possible if a cataloged object exists) or resource.
LO Invoke LIST COMPOUT for the cataloged object (equivalent to LIST COMPOUT object-name); see Displaying Compiler Output of a Cataloged Object.
LU List object's source code converted into code page as stored on the system file (equivalent to LIST object-name UNCONVERTED).
NO Displays the Natural Optimizer Compiler (NOC) options used during CATALOG (only possible if a catalog object exists).
OP Displays the initial, final and changed Natural compiler options used during CATALOG (only possible if a cataloged object exists).

The initial and changed compiler options can be displayed for objects cataloged with Natural Version 4.2.5 or above only.

PR Print the object's source code.
RE Rename the object (equivalent to the system command RENAME).
RU Run (that is, compile and execute) the object's source code (equivalent to the system command RUN).
ST Stow the object in source and object form (equivalent to the system command STOW).
UC Delete the object module (equivalent to the system command UNCATALOG).
. Exit (from selection list window)

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.

Start of instruction set To invoke the sort function

  • Press PF4.

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

SORT Subcommand Syntax

SORT

TYPE
MODE
VERSION
USER
DATE

ASCENDING
DESCENDING

DT
DATETIME

TIME
SIZE
LINES
BPSIZE

DS
DATSIZE

CP
CODE-PAGE

MEMBER
OFF

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:

Sort Field Keyword in Sort Syntax
Natural object type TYPE
Programming mode (reporting or structured mode) MODE
Version VERSION
User ID USER
Date DATE
Date and time DATETIME
Time TIME
Source size SIZE
Number of source lines LINES
Buffer pool size BPSIZE
DATSIZE (size of local data buffer) DS/DATSIZE
Code page CP/CODE-PAGE
Member names of subroutines or classes (available in extended selection list only) MEMBER

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.

Start of instruction setTo 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 * Lists all objects in the current library.
LIST S * Lists all subroutines in the current library.
LIST SYS* Lists all objects (of any type) whose names begin with SYS.
LIST M SYS* Lists all maps whose names begin with SYS.
LIST C *CODE Lists all copycodes whose names end with CODE.
LIST NAT*AL Lists all objects whose names begin with NAT and end with AL no matter which and how many other characters are between NAT and AL (this would include the names NATURAL and NATIONAL as well as NATAL).
LIST DOO? Lists all objects with 4-character names beginning with DOO (this would include the names DOOR and DOOM, but not DOO or DOODLE).
LIST M NAT?AL     Lists all maps whose names begin with NAT and end with AL with exactly one character are between NAT and AL (this would include the names NAT1AL and NAT2AL, but not NATAL or NATIONAL).
LIST M *1* Lists all maps whose names contains a 1.
LIST M F> Lists all maps, starting from the first one whose name begins with F.
LIST M MA< Lists all maps, from the first one until the one named MA (if present).
LIST N?T*AL Lists all objects such as NATAL, NATURAL, NATvrAL (where vr represents the relevant product version).
LIST E* TYPE=PM KIND=S DATE=YEAR SORTED=DATE ASCENDING Creates a list of all source objects of programs and maps whose names start with E and which were saved in the current year. The list is sorted by object date in ascending order.
LIST COUNT Lists the total number/sizes of all objects in the current library for which saved and/or cataloged objects exist.
LIST COUNT * TYPE=PM KIND=S Lists the numbers/sizes of all programs and maps for which saved objects exist.
LIST COMPOUT HUGO REPORT UNV EXTS WORKF Writes a report of the cataloged object HUGO to Work File 1 with all unused variables and all used external subroutines.

List of Source

The following topics are covered below:

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).

Subcommand Function
+ Scrolls one page forward.
- Scrolls one page backward.
+H Scrolls forward half a page.
-H Scrolls backward half a page.
++ Scrolls to the end (bottom) of the source.
BOTTOM
-- Scrolls to the beginning (top) of the source.
TOP
+n Scrolls n lines forward.
-n Scrolls n lines backward.
nnnn Scrolls to line number nnnn.
UNCONVERTED See UNCONVERTED in Options.
CONVERTED See CONVERTED in Options.
DBFNR ON Displays the database id (DBID) and file number (FNR) of the source library in the header line of the source code.
DBFNR OFF Displays the header line of the source code without the database id (DBID) and file number (FNR) of the source library. This is the default value.
EXPAND See expand-option.
FIELDS Applies to maps only: displays the field summary; that is, the list of fields in the map.
FIND Displays only those source lines which contain the specified value. See Subcommands FIND, REF and SCAN for details.
FIND value
FIND ABSOLUTE value
FIND CASESENSITIVE value
FIND ABSC value
FORMAT Applies to data areas and maps only: displays formatted data area or map, and other items related to the map. See Subcommand FORMAT.
LAYOUT Applies to maps only: displays the map layout; that is, the map will be displayed as it is displayed to the users at runtime.
NUMBERS ON Displays the source code with line numbers. This is the default value.
NUMBERS OFF Displays the source code without line numbers.
PRINT Prints the listed source.
REF Displays the line numbers of the source-code lines which contain the specified value in a table. See Subcommands FIND, REF and SCAN for details.
REF value
REF ABSOLUTE value
REF CASESENSITIVE value
REF ABSC value
RULES Applies to maps only: displays the processing rules used by the map (the rules are displayed in order of fields to which they are assigned, and per field in order of rank).
SCAN Displays all lines intensified which contain the specified value. The source will be scrolled to the first line that contains the value. See Subcommands FIND, REF and SCAN for details.
SCAN value
SCAN ABSOLUTE value
SCAN CASESENSITIVE value
SCAN ABSC value
SCAN= or SC= Scans for the next occurrence of the last SCAN value (or press PF5).
SETTINGS Applies to maps only: displays the map settings of the map.
ZOOM [expand-type...10] object-name Specifying a single object-name with the ZOOM command has the same effect as marking the name in the listed source with the cursor (see the section Cursor-Sensitive Object Selection): the selected object will be displayed in a window.

If you use asterisk/wildcard notation for the object-name or the object-name-range, all selected objects will be displayed in a window in the sequence in which they are referenced in the listed source.

The specification of an expand-type is the same as for the expand-option.

For an object displayed within a window invoked by ZOOM, the same subcommands (except PRINT, EXPAND and ZOOM) are available as for the normal listed source. Moreover, if you have used asterisk or wildcard notation and several objects are displayed, you can use the commands NEXT and PREV (or PF4 and PF5) to move from one object in the window to the next one or previous one respectively.

ZOOM [expand-type...10] object-name-range
. Exit.

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

S>n Shift map layout n columns to the right.
S<n Shift map layout n columns to the left.

Additional Subcommands for Field Summary List

EXTEND Displays the extended field editing information for all map fields.

To have the extended field editing information for an individual field displayed, mark the field name on the field summary list with the cursor and press ENTER.

RULES nn Displays the processing rules attached to field nn (nn being the sequential field number (first column of the field summary list)).

To have the processing rules of a field displayed, you can also enter an R in the command line and then mark the field name on the field summary list with the cursor and press ENTER.

SCAN [ABSOLUTE] value Same as for Subcommands for Listed Source.
SCAN =

Additional Subcommands for Processing Rules

SCAN [ABSOLUTE] value Same as for Subcommands for Listed Source.
SCAN =

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.

Parameter Possible Values / Format Explanation
REUSE-LAST-LIST N or Y
N The default setting is N (No).
Y The last displayed list of objects is reused after execution of commands entered in the Cmd column, except for the commands E, ED (Edit), CA (Catalog), UC (Uncat), S, ST (Stow), D, DE (Delete) or RE (Rename).
SCAN-CASE-SENSITIVE N or Y
N The default setting is N (No).
Y Distinguish between uppercase and lowercase letters when scanning the source code for a search value specified with the FIND, REF or SCAN subcommand. See also Subcommands FIND, REF and SCAN.
COUNT-SOURCE-LINES N or Y
N The default setting is N (No).
Y Display the number of source lines for source objects in the map with the source directory data (use PF11 to display the source directory data).
SORT-TEXT-MEMBER-NAME A8 Name of the Natural text member that is used for storing the sorted list.

If no name is specified, a generated name is used.

SORT-TEXT-MEMBER-LIBRARY A8 Name of the library where the Natural text member that is used for storing the sorted list is saved.

If no name is specified, the library WORKPLAN is used.

DELETE-SORT-TEXT-MEMBER N or Y
N The Natural source of type text used for the SORT function is not deleted when the LIST command is terminated.
Y The Natural source of type text used for the SORT function is to be deleted when the LIST command is terminated. This is the default setting.
PRINT-PAGE-SIZE N3 Default page size for print.

The default setting is 60.

MARK-LONG-LINES N or Y
Y Long lines in a listed source are marked with L in front of the source line.
N Long lines in a listed source are not marked. This is the default setting.
DATA-AREA-DEFINE-DATA-FORMAT N or Y Specify whether data area sources are to be listed in DEFINE DATA format or unformatted.
Y A data area source is listed in DEFINE DATA format by default (same as LIST FORMATTED).
N A listed data area source is listed unformatted. This is the default setting.
SOURCE-LIST-WITH-DBID-FNR N or Y Specify whether the database ID and file number of the source library are to be listed in the header line.
N The default setting is N (No).
Y The database ID and file number of the source library will be listed in the header line.
PAGE-TITLE-IN-BATCH F or A Specify whether the page title is to be printed on top of every page or on top of first page only.
F Print the page title on top of first page only.
A Print the page title on top of every page. This is the default setting.
OUTPUT-DESTINATION-BATCH D, P, W or T Specify whether the LIST output is to be written in batch mode.
D Write to default output device (CMPRINT).
P Write to default printer device (CMPRT01).
W Write to default work file 1.
T Write to a Natural text member.
OUTPUT-TEXT-NAME A8 Name of the Natural text member that is used for storing the LIST output when OUTPUT-DESTINATION-BATCH=T.

If no name is specified, L_uuuuuu is used, where uuuuuu are the first 6 bytes of the user ID.

OUTPUT-TEXT-LIBRARY A8 Name of the Natural library for the Natural text member that is used for storing the LIST output when OUTPUT-DESTINATION-BATCH=T.

If no name is specified, the library WORKPLAN is used.

SHOW-CAT-TIMESTAMP-VALUES N or Y Specify the catalog date and time displayed in an object selection list and in an object directory (LIST DIRECTORY):
N Use the date and time values of the cataloged object directory that are adjusted by the values set with the Natural profile parameters DD and TD (see the Parameter Reference documentation). This is the default setting.
Y Use the time stamp (store clock value) of the cataloged object.
SHOW-CAT-DBID-FNR-IN-LIST-DIR N or Y Specify whether the directory of the cataloged object displays the DBID (database ID) and FNR (file number) of the library where the object was cataloged (LIST DIRECTORY):
N Do not display the DBID and FNR of the library where the object was cataloged.
Y Display the DBID and FNR of the library where the object was cataloged. This is the default setting.
TOTAL-LINES-DISPLAY-BATCH N or Y Specify whether in batch mode the total number of source lines of all sources displayed in the list of objects is to be displayed at the end of the list of objects.
N The total number of source lines is not displayed (better performance).
Y Display the total number of source lines.
USE-MAINPR N or Y Specify whether the MAINPR profile parameter is to be used for the output of the LIST command in batch mode.
N Write the output to Report 0.
Y Write the output to the printer specified with the MAINPR profile parameter.
LIST-SHIFT-INCREMENT N3 Specify the step increment the LIST command uses to scroll right or left in a result list with PF10 or PF11, respectively.