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.

This document covers the following topics:

• SCAN Menu Options

• SCAN Edit Commands

• SCAN via Direct Command

• Defining an Individual SCAN Profile

• SCAN Under Natural Security

---

SCAN 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 (excluding the skipped objects, see below); the number of objects in which the scan value was found; the number of source-code lines in which the scan value was found. the number of objects that were skipped due to source work area overflow (Natural error NAT0886); increase size of profile parameter ESIZE to scan/replace all required objects. Note: Press PF-Key PF5 for SCAN statistics of the last results (if available).
	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
	*
	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.
	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.
	N	By default, the scan is not absolute.
Trace	Y	Activates the trace facility.
	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.
Ignore case	Y	Any combination of upper and lower-case letters will be found.
	N	By default, the exact scan value is searched.
Ignore comments	Y	Values found within comments are not displayed or replaced.
	N	By default, all values found are displayed or replaced.

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.
.
EDIT	Edit the object using full-screen editor. Note: This command is not available if the Natural program, data area, and map editor are disabled in your environment. For more information, see NaturalONE as the Default Development Environment in the Editors documentation.
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 a period (.) 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.

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

1. Enter the command SCAN to activate the SCAN menu.

2. In the input fields of the SCAN menu, enter all required values.

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

1. Specify the command SCAN to call the SCAN menu.

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

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.
IGNORE-CASE	Y or N	Search is not case sensitive. For details, see the description of the menu field Ignore case.
IGNORE-COMMENTS	Y or N	Search excludes values found in commentary text. For details, see the description of the menu field Ignore comments.

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.

Syntax of SCAN with Positional Parameters:

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

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.
ignore-case	Y or N	Search is not case sensitive. For details, see the description of the menu field Ignore case.
ignore-comments	Y or N	Search excludes values found in commentary text. For details, see the description of the menu field Ignore comments.

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

Defining an Individual SCAN Profile

You can define an individual profile for the SCAN command. For this purpose, the Natural SCAN command provides the subcommand SCANPROF or PF-Key PF10 ‘Prof’.

This command invokes the profile maintenance tool that:

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

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

• allows you to specify individual values for single users for the profile parameters in the SCAN 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 SCAN profile. The SCAN profile itself is named SCANPROF and located in library SYSLIB. The default profile that is used for updates of the SCAN profile is named SCANDEFP and is also located in library SYSLIB.

SCAN Profile Parameters

The parameters contained in the SCAN profile correspond to the fields of the SCAN map, see Menu Options.

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.