String search (special window: FIND)

The FIND function can be used to search for strings in the entire area of the diagnosisobject. The area to be searched can be defined by specifying a memory interval, load units or memory class.
DAMP supports searching with one or two search patterns. If the search involves two patterns, the displacement (offset) from the start of the first pattern to the start of the second patterns must be specified.

The user can specify a special memory alignment with respect to the first search pattern. For both search patterns, DAMP supports the use of various string formats (hexadecimal, character, string and text) and variable wildcard symbols. The search can be restricted by specifying the maximum number of hits.

In order to execute the FIND function, the diagnosis object must be open. The call to search for strings is issued with the statement:

START-PATTERN-SEARCH WINDOW=<w>

Following the call, the FIND selection window initially appears. This selection window is used to define the search area and the search patterns. You can search within any address space supported by DAMP by making a corresponding entry in the “ASEL” and “ASID” fields (see also "Input fields of a standard dump window (W4 - W9 and W21 - W99)"):

• in the virtual address space (ASEL = TSN | TID)

• in the data space (ASEL = ALT | SPI)

• in the real address space (ASEL = RM)

• in the absolute address space (ASEL = ABS)

• in the Processor Saved Status (ASEL = PSS)

• in the Hardware System Area (ASEL = HSA)

• in a dumpfile section (ASEL = SCT).

The FIND window is based on the following input principles:

• All entered data is retained on executing the FIND function and serves as the default for the next function to be executed. You can thus always expand on the earlier specification.

• All input fields are interpreted on executing the function exactly a they appear on the screen.

• Before executing the function, only one input field needs to be modified. The only exception is a new FIND window, where at least the search area and the first search pattern must be defined.

Only blanks may be used to reset inputs to “not specified”. NULL characters (X'00') may not be used for this purpose (except in the case of the two search patterns).

Figure 53: Selection mask for searching in the virtual address space

Figure 54: Selection mask for searching within other address spaces (example using ASEL=ALT)

By default the output is directed to the screen, to the same diagnostic window as the input. The user can also specify a file, *SYSLST or *EDT, as the output medium (Output Area). In addition, the user can also only have the number of hits found output and suppress the hit list (“Count only=Y”).

Specifying the search area

When selecting the search area in the virtual address space, you can specify a memory interval (Interval), one or more load units (Load Unit), or one or more memory classes (Memory Class). All three specifications for the search area are mutually exclusive (disjunct), i.e. only one specification can be valid at a given time, and no combinations are supported.
Only an Interval can be specified in the other address spaces.

The selection of the currently valid search area occurs in DAMP as follows:

• If precisely one search area is specified - either explicitly or as a default setting from the previous FIND call - that search area is selected.

• If two search areas have been specified, of which only one was specified explicitly, the explicitly specified search area applies.

• If multiple search areas are explicitly specified, the call to the function is rejected with the output of a message.

A search area is considered explicitly specified whenever any changes are not exclusively restricted to overwriting fields with blanks.
After a search area has been selected, all values of the other search areas are implicitly reset by DAMP and do not need to be explicitly reset.

For the virtual address space (ASEL=TSN | TID), the function supports searching in a selected address space (ASID=<tsn>|<tid>) as well as all address spaces (ASID=*ALL) contained in the object. With ASID=<tsn>|<tid>, you can enter search areas from the user and system memory; with ASID=*ALL, only the areas that are fully located in the user address space are allowed.

• Interval search area

  Start field End field

  Specifies the start address of the search area Specifies the end address of the search area

  The search area is defined fully only when both the Start and End addresses have been specified. There are no default settings.

• Load Unit search area
  This search area specifies the modules of BLS or DSSM load units.

  The delineation of the search area occurs hierarchically in the following levels:

  Scope  ->   Subsystem  ->   Version  ->   Module.

  If “Load Unit” is set as the search area, it is not necessary to specify all the available fields. An implicit assumption is made for each of the omitted fields.

  Scope selection bar DISTANCEDISTANCEDI	Specifies one or more BLS or DSSM load areas
  	ALL CLASS4 PRIV NONPRIV USER		All modules (from the CP, all subsystems and the user program) All modules from the system address space, except CP All modules from CP and the privileged subsystems All modules from the nonprivileged subsystems and the user program All modules from the user program
  	If “Load Unit” is set as the search area and “Scope” is not  specified, “Scope=ALL” is implicitly assumed. For “NONPRIV” and “USER”, the result of the search depends on whether the set task is connected to the subsystems or whether the task has loaded a program.
  Subsystem field	Specifies one or more subsystems Subsystem names can be entered with a length of up to 8 characters. The use of wildcards to specify multiple subsystems is supported: the “*” symbol matches any number of characters in the name, and “/” matches exactly one character.
  DISTANCEDISTANCEDI	If “Load Unit” is set as the search area and “Subsystem” is not specified, “Subsystem=*” (i.e. all subsystems from the specified “Scope”) is assumed.
  Version field DISTANCEDISTANCE	Specifies one or more subsystem versions Versions can be specified with a length of up to 8 characters. The use of wildcards to specify multiple versions is supported (as explained under the “Subsystem” field). If “Load Unit” is set as the search area and “Version” is not specified, “Version=*” (i.e. all versions of the specified subsystems) is assumed.
  Module field	Specifies one or more modules Module names can be entered with a length of up to 32 characters. The use of wildcards to specify multiple modules is supported (as in the “Subsystem” field). If “Load Unit” is set as the search area and “Module” is not specified, “Module=*” (i.e. all modules of the specified subsystems) is assumed.

• Memory Class search area

  This search area specifies one or more memory classes as the search area(s). The memory classes are selected by marking, and all possible combinations are allowed. The selection of memory classes from the user address space always applies only to the currently set task.

  The following memory classes and subclasses are supported:

  Field

  Selected area

  ALL CL1 CL2 CL3PP CL3FP CL4PP CL4FP CL4NP	Class-1-Memory Class-2-Memory Class-3-Partial-Pages Class-3-Full-Pages Class-4-Partial-Pages Class-4-Full-Pages Class-4-Nonpriv-Pages
  CL5PP CL5FP CL5MP CL6FP CL6MP	Class-5-Partial-Pages Class-5-Full-Pages Class-5-Memory-Pool Class-6-Full-Pages Class-6-Memory-Pool

  All memory classes Resident system modules Pageable system modules Resident partial pages Resident full pages Pageable partial page Pageable full pages Nonprivileged class 4 pages		System address space
  Privileged partial pages Privileged full pages Class 5 memory pool Nonprivileged full pages Class 6 memory pool		User- address space

Table 7: Memory classes (selected by marking)

Specifying the search patterns

You can specify one or two search patterns. If you are specifying two search patterns, you will need to specify the offset between the start of the first search pattern and the start of the second pattern. Search patterns are specified via the 1.Search Strg, Offset and 2.Search Strg fields.

The Alignment field can be used to specify a memory alignment with respect to the first search pattern. In addition, you can also change the Wildcard Symbol field.

• 1.Search Strg field
  Specifies the first search pattern. This search pattern must always be specified. You can enter up to 64 characters, which are preceded by on byte to indicate the format type.

  The following formats are supported:

  X C S T

  Hexadecimal format Character format String format Text format

  The allowed characters are 0..9 and A..F Conversion of lowercase to uppercase in the search pattern, followed by a match No conversion Conversion of uppercase to lowercase, both for the search pattern and for the search area contents, followed by a match

  The default setting is the “C” format.

  The use of wildcards in the search pattern is supported. The wildcard symbol corresponds to the character defined in the “Wildcard Symbol” field. It can be used at any position in the search pattern and matches exactly one character at that position.

• Offset field
  Specifies the offset between the start of the “1.Search Strg” and the start of the “2.Search Strg”. The “Offset” is specified as a hexadecimal value. In order to set the offset to “not specified”, the input field must be overwritten with blanks.

• 2.Search Strg field
  Specifies the second search pattern. The “2.Search Strg” field is defined like the “1.Search Strg” field and is only taken into account in the search if an “Offset” has been specified.

• Wildcard Symbol field
  Specifies a character to be used as a wildcard symbol in the first and second search patterns (i.e. the “1.Search Strg” and “2.Search Strg” fields). The wildcard symbol is set to “*” by default, but may be modified by the user. All characters except digits, letters and blanks are allowed.

• Alignment field
  Specifies a memory alignment, with respect to the first pattern (“1.Search Strg”).

  The following alignment types are supported:

  B H W D P

  Byte boundary Half-word boundary Word boundary Double-word boundary Page boundary

  The default setting is the “H” format.

  A page boundary (“P”) generally means that the search is aligned on a 4 KB boundary. The only exception is when searching in objects that were opened as PAM files, in which case the alignment is on a 2 KB boundary.

Specifying the output for the FIND function

The output medium is defined using the “Output Area” field. By default the output is directed to the screen, to the same diagnostic window as the input. The maximum number of hits for the search is set in the “Number of Hits” field, and “Count Only” defines whether the hit list should be output or just the number of hits. The format of the output can be selected using the “Mode field” in the header line.

• Output Area field
  Specifies the output medium.

  The following output media are supported:

  *SYSOUT <filename> *SYSLST *EDT

  Screen, same dialog window as for the input File System file *SYSLST EDT window which was used last or EDT window 0

  The default setting is *SYSOUT.

• Number of Hits field
  Specifies the maximum number of hits after which the search is to be interrupted and the found hits displayed. The ’Number of Hits‘ is entered as a decimal value. The maximum number of hits displayed is, however, also restricted by the size of the output window.

• Count only field
  Specifies whether the hit list is to be output or only the number of hits.

  The following specifications are supported:

  N Y	Hit list Only number of hits

  The default setting is Count only=N, i.e. the hit list is output.

• Mode field in the header line

  The following output formats are supported:

  D(MP) C(HR) H(EX)

  Normal dump format Character format Hexadecimal format

  The default setting is the D(MP) format:

The output format can be entered in the selection and output windows.

Output window of the FIND function

After starting the FIND function with Output Area = *SYSOUT (default setting), the hits are shown in the same diagnosis window. If one search pattern was specified, one line is output for each hit; if two search patterns were specified, each hit is displayed in two lines, where the second line is always preceded by the “Offset” in the output.

Figure 55: FIND output window (when searching with two patterns)

The search is interrupted when the window is completely filled with hits in accordance with the current window length or when the maximum number of hits set in the “Number of Hits” field is reached. It can then be resumed with +/ or aborted with - / .

Furthermore, you can force a cancellation of the search with  followed by /INFORM-PROGRAM MSG='*CANCEL'. All hits found up to that point are then displayed.

If the search area includes pages that are not contained in the diagnosis object, this is indicated by messages, but the search is not aborted.

The address of the found search pattern can be marked in each line of the hits and the memory area can be displayed in a dump window, see the section "Marking" (Modifying the diagnostic windows).

In the D and HEX output modes, the individual words in the output area can be marked with and assigned as start addresses to the individual dump windows.