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.

You can scan single objects, all objects with a specific prefix, all objects within a library or all objects of a specific object type. If Predict is installed, you can also scan objects contained in a Predict set.

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
SCAN Edit Commands
SCAN via Direct Command
SCAN Under Natural Security

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` edit commands 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` edit commands 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 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
	*	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.
Selection list	Y	Display 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) from scan processing.
Selection list	N	By default, no selection is displayed.
Object type(s)	You can restrict the search to specific object types. One or several types may be specified. 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.
Absolute scan	N	By default, the scan is not absolute. Note: In data areas, a scan is always absolute, regardless of the value of this parameter.
Trace	Y	Activates the trace facility.
Trace	N	By default, the trace facility is deactivated.
Predict set number	Predict set number to be scanned. Note: Predict has to be installed. A one- or two-digit number that identifies the retained set to be used for the names of the objects to be processed. A retained set is created with the save set option of the `LIST XREF` command. The value specified for Library is used as Predict set library. If the Predict set number is specified, the value specified for Object name must be an asterisk (*) instead. For detailed information on Predict sets, refer to the Predict documentation.
Predict set user	The ID of the user who created the Predict set. Note: Predict has to be installed. If no ID is specified, the value of the system variable `*USER` (see also the System Variables documentation) is used.

Note:
For possible restrictions, see SCAN under Natural Security.

SCAN Edit Commands

The following edit commands can be entered in the command line(s) of the SCAN editor generated by the scan operation:

Command	Function
blank	Continue with normal scan processing.
`Q`	Terminate scan processing.
`.`	Terminate scan processing.
`EDIT`	Edit the object using full-screen 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. To indicate that the line has been deleted, the character `D` will appear next to the line.
`.L`	Ignore any changes after last ENTER. Will also restore any line previously deleted with the line command `.D`.

Editing Rules

The line length of the source object in the result screen is limited to 72 characters. Lines exceeding 72 characters are marked with an L and cannot be modified.
If the Replace value option is used and/or an object is modified in the result screen, the object will always be saved unless an I, Q or dot (.) is specified before the next object is scanned.
Lines containing PASSW, PASSWORD=, CIPHER=, or CIPH= will be ignored.

SCAN via Direct Command

The SCAN functions may also be invoked via direct command, in either online mode or batch mode. The SCAN direct command can be specified with keywords or with positional parameters.

In batch mode, the SCAN command will process only one function per invocation to minimize the repercussions of invalid data being specified.

Warning:
If you use scan/replace values that contain lowercase characters or embedded blanks, we strongly recommend that you follow the instructions below to avoid unexpected results.

To use SCAN with lowercase characters or embedded blanks in online mode

Enter the command SCAN to activate the SCAN menu.
In the input fields of the SCAN menu, enter all required values.

To use SCAN with lowercase characters or embedded blanks in batch mode

Specify the command SCAN to call the SCAN menu.
Specify the values in a separate data line and exactly in the order of the map fields (see Menu Options), for example:
```
SCAN 
S,MOVE LEFT,MOVE RIGHT,SYSTEM,*,N,P,N,N,1,SAG 
```
In the example of a batch job above, the value MOVE LEFT is replaced by MOVE RIGHT for all programs of Predict Set 1 for the user SAG in the library SYSTEM.

This section covers the following topics:

SCAN with Keywords
SCAN with Positional Parameters

SCAN with Keywords

The SCAN direct command with keywords consists of the command SCAN itself which is followed by keywords.

Keywords can be specified in any order or can be omitted. If a keyword is not used, the default value will be assumed for this keyword.

Warning:
Do not mix keywords and positional parameters within the SCAN direct command to avoid unexpected results.

Syntax of SCAN with Keywords:

SCAN keyword=value,...

Syntax Explanation:

Keyword	Value	Explanation
`FUNC`	T, L or S	Function code. For details, see the description of the menu field Code.
`LIB`	max. 8 characters	Name of library to be scanned. For details, see the description of the menu field Library. Default value is the current library.
`OBJ`	max. 9 characters	Object name. The object sources to be scanned. For details, see the description of the menu field Object name.
`TYPE`	max. 14 characters	Object type. The object type(s) to be used for the selection. For details, see the description of the menu field Object type(s).
`SVAL`	max. 32 characters	Scan value. The character string (without embedded blanks) to be scanned for in each object source. For details, see the description of the menu field Scan value.
`RVAL`	max. 32 characters	Replace value. The character string (without embedded blanks) to be replaced by the scan value. For details, see description of the menu field Replace value.
`ABSOL`	Y or N	Absolute scan. For details, see the description of the menu field Absolute scan.
`SETNO`	max. 2 digits	Predict set number to be scanned. For details, see the description of the menu field Predict set number.
`SETUSER`	max. 8 characters	Predict set user ID. The ID of the user who created the Predict set. For details, see the description of the menu field Predict set user.

Examples of SCAN with Keywords:

SCAN FUNC=S,LIB=SYSTEM,OBJ=PGM0*,TYPE=S,SVAL=FETCH

SCAN FUNC=S,SVAL=WRITE,RVAL=PRINT,OBJ=PGM1

SCAN FUNC=S,SETNO=1,TYPE=P,SVAL=GLOBAL

SCAN with Positional Parameters

The SCAN direct command with positional parameters consists of the command SCAN itself which is followed by parameters that reference each word on the command line by their position within the command. The order of the positional parameters must be strictly adhered to.

If a positional parameter is not specified, its default value will be assumed. If you want to indicate that a positional parameter is to be omitted, use a comma as shown in Examples of SCAN with Positional Parameters.

Warning:
Do not mix keywords and positional parameters within the SCAN direct command to avoid unexpected results.

Syntax of SCAN with Positional Parameters:

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

Syntax Explanation:

Positional Parameter	Value	Explanation
`func`	T, L or S	Function code. For details, see the description of the menu field Code.
`scan-value`	max. 32 characters	Scan value. The character string (without embedded blanks) to be scanned for in each object source. For details, see the description of the menu field Scan value.
`replace-value`	max. 32 characters	Replace value. The character string (without embedded blanks) to be replaced by the scan value. For details, see the description of the menu field Replace value.
`library`	max. 8 characters	Name of library to be scanned. For details, see the description of the menu field Library. Default value is the current library.
`object-name`	max. 9 characters	Object name. The object sources to be scanned. For details, see the description of the menu field Object name.
`object-type`	max. 14 characters	Object type. The object type(s) to be used for the selection. For details, see the description of the menu field Object type(s).
`absolute`	Y or N	Absolute scan. For details, see the description of the menu field Absolute scan.
`set-number`	max. 2 digits	Predict set number to be scanned. For details, see the description of the menu field Predict set number.
`set-user`	max. 8 characters	Predict set user ID. The ID of the user who created the Predict set. For details, see the description of the menu field Predict set user.

Examples of SCAN with Positional Parameters:

SCAN S,ABC,,SYSTEM,PGM0*,P,N

SCAN S,ABC,DEF,SYSTEM,PGM1,*,Y

SCAN T,ABC,,SYSTEM,*,7,N,1,SAG

SCAN Under Natural Security

In a Natural Security environment, you can specify a library security profile to disallow the use of the SCAN system command for a particular library or restrict the use to avoid source modifications. You have the following options:

Disallow the use of the SCAN system command.
Allow the use of the SCAN system command, but disallow the system commands LIST and EDIT.
Disallow the replace function of the SCAN system command. Additionally, disallow the use of the SAVE system command to avoid source modifications through the full-screen editor.

For detailed information on restricting the use of the SCAN system command, see Command Restrictions in the Library Maintenance section of the Natural Security documentation.

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