Invoking the search on CMS using menu input

You can use the SuperC Search on CMS to search:

A file
A file group
A member within a MACLIB or TXTLIB
Complete MACLIBs or TXTLIBs

This section describes how to use the Primary Search Menu. This menu allows you to specify the file to be searched, and other SuperC options. For information about invoking the SuperC Search directly from the command line without using the menu, see Invoking the search on CMS using command line input.

To display the Primary Search Menu (see Figure 1) do one of these:

Enter
```
ASMFSUPC SRCH
```
on the CMS command line
Press the PF6 key from the Primary Comparison Menu (see Invoking the comparison on CMS using menu input).

Figure 1. SuperC primary search menu

HLASM Toolkit Feature SuperC Compare Program - Search Menu
COMMAND ==>

                         Fn    Ft    Fm             (MACLIB/TXTLIB Files Only)
Search File ID     ==>                              Member  ==>

    Enter Search Strings and  Optional operands (WORD/PREFIX/SUFFIX and/or C)
             where C denotes Continuation/Additional Match String Requirement
CAPS    ==>
CAPS    ==>
CAPS    ==>
ASIS    ==>
ASIS    ==>
ASIS    ==>
                        Optional Section
Selection List     ==>                             ( NO / * )

Process Options    ==>
Listing File ID    ==>                             ( srchfn SRCHFOR A /file-id)
Process Stmts ID   ==>                             ( file-ID                  )
Auto Display Pgm   ==>                             ( BROWSE/XEDIT/EPDF etc.   )
 1=Help  3/6=Primary Menu   4=Quit   5=Proc Stmts   8=Proc Opts   ENTER/10=Exec

Suppose you want to search for the uppercase string ABCD in the file NEW TEST1 A:

Enter the name of the file to be searched in theSearch File ID field:
```
  Search File ID   ==> new test1 a
```
Enter the string to be searched for in one of the (three) CAPS fields:
```
   CAPS    ==> ABCD
```
Press Enter

The result of the search is then displayed.

Here are descriptions of each input field on the SuperC Primary Search Menu. Default values are underlined.

COMMAND

This field allows you to issue CP and CMS commands, such as FILELIST, ERASE, or RDRLIST.

Search File ID

This field specifies the name of the file to be searched. In almost all cases, this is a required field.

SuperC allows the CMS convention of including wildcard characters (*) and equal signs (=) as part of the file ID. (However, only the * wildcard character applies for the Search File ID.)

The following examples show the effect of various entries in the Search File ID field:

File ID Specified	Meaning
`new test1 a`	Single CMS file
`new test* a`	File group (all with file name NEW and a file type starting with TEST and file mode A)
`new maclib`	The entire macro library, NEW

Note: A macro or text library with a file name containing an * (for example, ABC* MACLIB A or * TXTLIB C) is not processed as individual MACLIB/TXTLIBs with members. There is no method for specifying the concatenation of more than one MACLIB/TXTLIB.

Member

This field specifies the name of the member, within either a macro library (MACLIB) or text library (TXTLIB),` to be searched. (This field is only used when the file specified in Search File ID refers to a macro or text library.) If left blank, all members within the specified library are selected for the search.

File ID Specified	Member	Meaning
`new maclib c`	`xyz`	XYZ member in NEW MACLIB C.
`new maclib c`	`*`	All members in NEW MACLIB C. Note: The Selection List field must = NO.

Search String Fields (CAPS, ASIS)

You can specify up to 6 different strings to be searched for in a single search. Strings can be entered in any of the three CAPS entry fields and in any of the three ASIS entry fields. (The differences between the CAPS and ASIS entry fields are explained later in this section; see “Using the CAPS Entry Field”.)

You can specify strings as all uppercase characters, all lowercase characters, or a mixture of both. The case that you use depends on the entry field used (CAPS or ASIS).

A string may be further qualified as a word, prefix, or suffix, and where it appears on a line:

Qualifier

Meaning

WORD (or W)

String must appear as a separate word, that is, be delimited by spaces or special characters.

PREFIX (or P)

String must appear as the first part of some other text.

SUFFIX (or S)

String must appear as the last part of some other text.

C

Indicates continuation. The string must appear on the same line of input as the string defined in the previous entry line. (The two strings may appear in the input line in any order.) Strings without the C qualification are independent of previously specified lines.

C may have further qualifiers:

+: The string in the C entry line must appear after the string specified in the previous entry line.
+n: The string in the C entry line must start in the nth position after the string specified in the previous entry line.

column_range

The string must start within this range of columns on a line.

Format is: start_column:last_start_column

Strings may be entered as a contiguous character string. If spaces are included in the string to be searched for, the entire search string must be enclosed within apostrophes. If the string to be searched for contains apostrophes, each embedded apostrophe must be represented by two apostrophes in the search string.

When a string is qualified, the qualifier starts at the first non-space character after the (possibly quoted) string.

Hexadecimal strings must be specified using an X prefix followed by the hexadecimal string enclosed in apostrophes. Such strings must contain an even number of valid hexadecimal characters (0 to 9, A to Z).

Using the CAPS Entry Field: Entering a string in one of the CAPS fields makes SuperC search for occurrences of the specified string in uppercase only. For example, if you enter the character string abcd in one of the CAPS fields, each occurrence of the string ABCD is searched for, but strings such as aBcD or abcd or ABCd are not sought.

The contents of each CAPS field is raised to uppercase after it is entered on the menu line.

Each of the following examples causes a search for all occurrences of the prefix WXYZ:

 CAPS         ==> WXYZ  prefix
 CAPS         ==> wxyz  prefix
 CAPS         ==> wXyZ  prefix

Note: If you use the Process Option ANYC (Any Case) with the CAPS entry, then the string specified is searched for regardless of case.

Using the ASIS Entry Field: Entering a string in one of the ASIS fields makes SuperC search for occurrences of the specified string exactly as specified.

For example, if you enter the character string abcd in one of the ASIS fields, each occurrence of the string abcd is searched for, but strings such as aBcD or ABCD or ABCd are not sought.

The following example causes a search for all occurrences of the prefix wXyZ:

 ASIS         ==> wXyZ prefix

Examples of Search Strings:

Search String Specified	Searches For
`CAPS ==> ABC CAPS ==> efg`	Lines containing the string ABC or the string EFG
`CAPS ==> ABC WORD CAPS ==> EFG C`	Strings ABC and EFGon the same line; ABC must be a complete word
`ASIS ==> AbcD PREFIX`	All occurrences of the prefix AbcD
`CAPS ==> 'AB C''D'`	The string AB C'D
`CAPS ==> X'004CFF'`	The hexadecimal string X'004CFF'
`CAPS ==> ABC W 5:60 CAPS ==> EFG W C + CAPS ==> HIJ C +5`	The string ABC starting within columns 5 to 60 with the string EFG following somewhere in the same line and the string HIJ starting in the 5th position after EFG

Note: You can also specify search strings using any number of SRCHFOR and SRCHFORC process statements in a process statement file (see “Process Statements ID”). These search strings are used in addition to any search strings you specify in the menu.

Selection List

This field indicates if the Selection List facility is to be used. Valid values are:

NO: Selection list facility not required.
*: Selection list facility required.

Note: The Selection List facility is only applicable when an * (asterisk) is contained within the Search File ID. (In the case of a macro or text file, an * must be contained within the specified Member name.)

Enter an * in the Selection List field to see a list of files from which to select the ones that you want.

The following examples illustrate the files that are listed for selection according to the file ID specified:

File ID Specified	Member	Files Listed for Selection
`new test1 *`		All files with the file name NEW and the file type TEST1
`old test* a`		All files with the file name OLD and a file type beginning with TEST and file mode A
`new txtlib a`	`*`	All members within the text library NEW TXTLIB A
`new maclib a`	`abc*`	All members within the macro library NEW MACLIB A whose name begins with ABC

For details about using the selection list, see CMS file selection list for using the selection list.

Process Options

You can specify the process options that you want (if any) by doing one of these:

Entering them directly in the process option line on the Primary Search Menu.
Selecting them from the Process Options Selection Menu (PF8).

For a full list and description of process options, see Process options.

Entering Process Options Directly: If you choose to enter the process options directly, type in each process option keyword on the entry line (each keyword must be separated by a space). Up to 51 characters (including spaces) can be entered.

Figure 2. SuperC primary search menu with process options entered directly

HLASM Toolkit Feature SuperC Compare Program - Search Menu
COMMAND ==>

                        Fn    Ft    Fm             (MACLIB/TXTLIB Files Only)

⋮

Process Options    ==>  anyc nosums


⋮
 1=Help  3/6=Primary Menu   4=Quit   5=Proc Stmts   8=Proc Opts   ENTER/1

Figure 2 shows two process options entered directly on the Process Options line:

ANYC (Any Case)
NOSUMS (No Summary Section)

Selecting Process Options from the Menu: The second way to specify process options is to select them from the Process Options Selection Menu. This menu shows the process options that are valid for a search. To display this menu, press PF8 (see Figure 3).

Figure 3. Example of the SuperC process options selection menu (search)

 HLASM Toolkit Feature SuperC Compare Program - Search Options          1 of 1)
 Search Options -------- SuperC Compare Program  ------------------ (1 of 1)
 COMMAND ==>
 Select option(s) from the following list or "blank" to remove.
/*GE Select option(s) from the following list or "blank" to remove.

 Sel                             Search Process Options
       SEQ     - Ignore sequence columns 73-80 on F 80 input source files,  or
       NOSEQ   - Process columns 73-80 as data on F 80 input source files,  or
       COBOL   - Ignore sequence columns 1-6 on F 80 input source files.

  S    ANYC    - Process text lines as upper case.
       IDPFX   - List filename/member as prefix to each search line found.
       XREF    - Cross references lines found for each search string.
       LPSF    - List search and up to six preceding and following lines, or
       LMTO    - List group totals only,                                  or
       LNFMTO  - List members/files where no lines were found,            or
       LTO     - List total summary only.

       LONGLN   - Lists up to 176 columns.  Maximum line length = 202/203.
       NOPRTCC  - No print control column and page separators.
       APNDLST  - Append listing report to listing data set.
  S    NOSUMS   - Generate no summary section in the report listing.
  Others:DPACMT,DPADCMT,DPBLKCL,DPCBCMT,DPFTCMT,DPPDCMT,DPPLCMT,DPPSCMT,DPMACMT
      (Enter these keywords directly on the main menu options selection lines)
  PF1=Help                        PF3=Menu                           PF8=Menu

To select a process option, enter an S next to it.

Process options which have been selected previously appear with an S alongside them (as for ANYC and NOSUMS in Figure 3).

When you no longer require a process option, you can either clear the S from the Process Options Selection Menu or delete the option keyword from the Process Option field on the Primary Search Menu.

Listing File ID

This field specifies the name of the listing file generated as a result of the search. (The SuperC Search always generates a listing file.)

You can:

Leave this field blank (in which case SuperC allocates a default name for the listing file)
Specify a full file ID to be used for the listing file
Use * and = symbols (which results in the listing file ID being a combination of the fn ft fm specified in the Search File ID and the details you enter for the Listing File ID)

This is best illustrated by some examples:

Search File ID	Listing File ID	File ID Used
`new test a`		`new srchfor a`
`new test a`	`myname mytype a`	`myname mytype a`
`* test a`		`$ srchfor a`
`new test a`	`= listing a`	`new listing a`
`new* test a`	`* listing a`	`new$ listing a`

Process Statements ID

This field specifies the name of the file (if any) containing the process statements to be used in the search.

Process statements (which are like process options but require one or more additional items of information to be specified) are always passed to SuperC in a file.

For a full list and description of process statements, see Process statements.

You can either enter the name of an existing file that contains process statements, or press PF5 to create a new file and specify the process statements.

Pressing PF5 displays the Process Statements Entry Menu (see Figure 4) showing examples of some of the process statements available and allows you to enter the process statements that you want.

When you exit from the Primary Search Menu, SuperC automatically generates a file (called SRCHFOR SYSIN A) containing each of the process statements you have specified. (SRCHFOR SYSIN A is entered against Process Stmts ID on the Primary Search Menu.)

Figure 4. Example of the SuperC process statements entry menu (search)

 HLASM Toolkit Feature SuperC Compare Program - Search Statements       (1 of 1)


 Enter Process Statements for Statements File:
    ==>

      Examples                            Explanation

   SRCHFOR  'ABCD' W           Search for the word "ABCD"
   SRCHFORC 'DEFG'             "DEFG" must be on same line as word "ABCD"
   CMPCOLM  1:60  75:90        Search columns 1:60 and 75:90 for string(s).

⋮


  PF1=Help       PF3=Menu       PF5=Menu       PF6=Cancel       ENTER=Save Line

Note: When you press PF5, SuperC erases any existing SRCHFOR SYSIN A file before creating the new file.

Auto Display Pgm

This field specifies the name of an editor or browse program to inspect the search results:

program name: The name of a valid editor or browse program to be invoked to display the results of the search. (For example, XEDIT, EPDF, BROWSE)
(space): Results of search not displayed. Editor defaults to XEDIT.

Note: If no strings are found in the search:

The search results are not displayed.
The output listing file is still generated.

Primary Search Menu PF Key Definitions

PF1: Help. Displays the first search help menu.
PF3: SuperC exits from the search process and goes (or returns) to the Primary Comparison Menu.
PF4: Quit. Terminates the search. Returns to the environment before SuperC.
PF5: Proc Stmts (Process Statements). Displays the Process Statements Entry Menu. This menu contains some examples of the more widely used process statements. It also has a field to allow you to input one process statement at a time into the SRCHFOR SYSIN A file.
Note: When you press PF5, SuperC erases any existing SRCHFOR SYSIN A file before creating the new file.
PF8: Proc Opts (Process Options). Displays the Process Options Selection Menu.
PF10: Execute and Quit. Verifies user-input fields, invokes SuperC, and returns to the environment before SuperC.
ENTER: Execute. Verifies user-input fields and invokes SuperC. After the search has completed, control returns to the environment before the SuperC Search was invoked.

¹ If a Process Statements file is specified and it contains any SELECTF process statements, the Search File ID name is ignored.