SCAN

#### Search Results

Search

# 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:

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

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

| 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

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.

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

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

### On this page

- SCAN Menu Options
- SCAN Edit Commands
- SCAN via Direct Command
- Defining an Individual SCAN Profile
- SCAN Under Natural Security