Version 4.2.6 for Mainframes
 —  System Commands  —

SCAN

SCAN

The SCAN command is used to search for a string of characters within an object, with the option to replace the string with another string.

The object may be a single object, all objects beginning with a specified setting, or all objects within a library. The SCAN may also be restricted to a specific object type.

Important:
The source work area is used by the SCAN command. Therefore, a SAVE or STOW command should be issued before using the SCAN command.

This document covers the following topics:


Menu Options

When you enter the SCAN command, the SCAN menu will be displayed, providing the following:

Field Input setting
Code T
Statistics

Returns the following information:

  • the number of objects that were scanned;

  • the number of objects in which the scan value was found;

  • the number of source-code lines in which the scan value was found.

L
List of Objects Containing Scan Value

Displays a list of all objects in which the scan setting was found. From the list, you can select individual objects for further processing.

If you wish, you can modify the lines directly in the result screens or by using the appropriate SCAN subcommands as described below. The scanned lines can be modified for any object, except maps and data areas or locked objects (Locking of Source Objects).

To modify the entire object, enter the E subcommand to call the corresponding editor. If any modifications were previously done in the result screen, you are prompted to confirm any updates.

Once the object has been edited, the object should be saved and the editor terminated. Scan processing can then continue.

S
Object Lines with Scan Value

Displays one after another each source-code line in which the scan value was found.

If you wish, you can modify the lines directly in the result screens or by using the appropriate SCAN subcommands as described below. The scanned lines can be modified for any object, except maps and data areas or locked objects (Locking of Source Objects).

To modify the entire object, enter the E subcommand to call the corresponding editor. If any modifications were previously done in the result screen, you are prompted to confirm any updates.

Once the object has been edited, the object should be saved and the editor terminated. Scan processing can then continue.

Scan value

The string of characters to be scanned for.

Note:
To prevent lower-case characters from being translated to upper-case by Natural, use the terminal command %L.

Replace value

The value which is to replace the scan value.

The Replace value option has no effect with maps, data areas, recordings, dialogs and functions or locked objects (Locking of Source Objects).

Library

The ID of the library to be scanned. Default is the current library.

If the library specified is SYSTEM, the library in the FUSER file will be scanned. If the name of the specified library begins with "SYS" but is not SYSTEM, the library in the FNAT file will be scanned.

Object name The object(s) to be scanned:
blank all objects
*
object-name> all objects whose names are greater than or equal to name
object-name< all objects whose names are less than or equal to name
If you wish to scan within a certain range of objects, you can use asterisk notation (*) and wildcard notation (?) for the object name, in the same manner as described for the system command LIST.

See also Object Naming Conventions in the Using Natural documentation.

Object type(s) You can restrict the search to specific object types. For a selection list of possible types, enter a question mark (?) in this field.

If you leave this field blank or enter an asterisk (*), objects of any type will be scanned.

Absolute scan Y The scan will be "absolute"; that is, the value to be scanned for will be found in any form, even as part of a longer character string.
N By default, the scan is not absolute.

Note:
In data areas, a scan is always absolute, regardless of the value of this parameter.

Selection list Y Displays a list of objects as specified by Library, Name, Type(s) for Code T or S (see above). From this list, you can select individual objects (by marking them with any character) for scan processing.
N By default, no selection list is displayed.
Trace Y Activates the trace facility.
N By default, the trace facility is deactivated.

Top of page

SCAN Subcommands

The following subcommands can be entered in the command line(s) of the result screens generated by the scan operation:

Command Function
blank Continue with normal scan processing.
Q Terminate scan processing.
.
E Edit the object using full-screen editor.
EDT Edit the object using line editor.
LIST List the object as it currently appears in the source work area.
LET Ignore all line changes made after last ENTER.
I Ignore the object currently being scanned, do not save any modifications, and continue with next object.
.D Delete line. A "D" will appear next to the line to indicate that it has been deleted.
.L Ignore any changes after last ENTER. Will also restore any line previously deleted with the line command .D.

Editing Rules

Top of page

SCAN Keywords

SCAN functions may be invoked direct, in either batch or online mode, by specifying the following keywords:

Keyword Explanation
FUNC Function code
SVAL Scan value
LIB Library
RVAL Replace value
OBJ Object name
TYPE Object type
ABSOL Absolute scan

Caution:
In a direct command, values containing embedded blanks must be avoided to prevent undesired scan/replace results. In online mode, a scan for a value that contains embedded blanks is only possible from the SCAN menu.

Examples of SCAN Command with Keywords:

SCAN FUNC=S,SVAL=value,LIB=SYSTEM,OBJ=PGM0*,TYPE=S
SCAN FUNC=S,SVAL=value,RVAL=value,OBJ=PGM1

Top of page

SCAN in Batch Mode

The SCAN command will process only one function per invocation to minimize the repercussions of invalid data being specified. Either keywords (as described above) or positional parameters may be used.

Positional parameters are specified as follows:

SCAN func, scan-value, replace-value, library, object-name, object-type, absolute

Possible values of the positional parameters are as decribed under Menu Options.

Important:
To scan for a value that contains lower-case characters or embedded blanks, do not specify the scan-value in the same line of the batch job as the SCAN command, but in a separate data line, and enter the data according to the online map, see Menu Options.

Example of using a scan/replace value with embedded blanks:

SCAN S,MOVE LEFT,MOVE RIGHT,SYSTEM,PGM0*,N,*,N,N

Top of page

SCAN under Natural Security

For you to be able to use the SCAN in a Natural Security environment, the system commands LIST, EDT, EDIT, and READ must be allowed in the current library's security profile. If the Replace value option is to be used or if the source is to be modifiable, the system command SAVE must also be allowed.

Under Natural Security, the use of the SCAN command may be disallowed in some libraries.

If only structured mode is allowed for the library, objects in reporting mode can be scanned, but not modified.

Top of page