Component: | FIND-FILE |
Functional area: | Command processing |
Domain: | UTILITIES |
Privileges: | STD-PROCESSING |
Function description
The FIND-FILE command searches for C-strings and hexadecimal strings in a set of files. You can choose to output either the filenames containing the matches (SHOW-RESULT=*MATCHES, the default) or only the filenames where the search pattern was found (SHOW-RESULT=*FILE-NAMES).
All file types except tape files are supported. SAM and ISAM files are searched record by record, and PAM files are searched page by page. The output of the found data reflects this: for SAM and ISAM files, the record number and byte position within the record are displayed; for PAM files, the page number is given. The page number of the match is also provided for PLAM libraries. The specific element must be identified using LMS tools (e.g., FIND-ELEMENT).
To select the files to be searched, the operand `SELECT=*BY-ATTRIBUTES(...)` can be used. Since the selection criteria are limited, in addition to this operand, it is possible to specify a file list within a file (`FILE-NAME=*FROM-FILE(LIST-FILE-NAME=...)`). This file list can be created, among other methods, using the `SHOW-FILE-ATTRIBUTES` command. See Example 11.
The command supports output to an S variable.
Format
FIND-FILE | Kurzname: FNF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operand description
FILE-NAME = list-poss(100): <filename 1..54_without-gen_with-wild(80)> / *FROM-FILE(…)
Files searched by FIND-FILE.
FILE-NAME = list-poss(100): <filename 1..54_without-gen_with-wild(80)>
The file names can be specified using wildcards. A list of up to 100 file names can be specified.
FILE-NAME = *FROM-FILE(…)
The path names of the files to be searched are taken from a file.
LIST-FILE-NAME = <filename_1..54_without_gen>
The specified file must be a variable-length SAM file containing a list of path names. Such a file can be created, for example, using the SHOW-FILE-ATTRIBUTES command (with OUTPUT=SH.OUT(FORM-NAME=*FILE-NAME)), which allows for more detailed selection criteria.
The file must contain one file name per record or line. Spaces before and after the file name are ignored.
PATTERN = <c-string 1..256_with-lower-case>(…) / <x-string 1…256>(…)
The pattern searched for in the specified files.
PATTERN = <c-string 1..256_with-lower-case>(…)
String of the pattern searched for in the files. The search pattern is interpreted as an EBCDIC character string. Therefore, when searching files whose CCS is not an EBCDIC character set, the search pattern must be specified as an x-string.
CASE-SENSITIVE = *NO / *YES
Specifies whether the pattern must match exactly, including upper and lower case letters.
CASE-SENSITIVE = *NO
The pattern's upper and lower case letters are ignored, and all variants are searched for.
CASE-SENSITIVE = *YES
The pattern is case-sensitive and only searched for accordingly.
TYPE = *FIXED-STRING
Specifies the type of the entered pattern.
TYPE = *FIXED-STRING
The pattern type is a string of fixed length and without placeholders. The pattern is searched for exactly as specified, with the exception of upper and lower case letters.
PATTERN = <x-string 1…256>
Hexadecimal search string that is searched for in the files.
SELECT = *ALL / *BY-ATTRIBUTES(…)
Selection of which files are searched when executing the command.
SELECT = *ALL
All files specified with FILE-NAME are searched.
SELECT = *BY-ATTRIBUTES(…)
Only files with the selected attributes will be searched.
FILE-STRUCTURE = *ANY / list-poss(3): *SAM / *PAM / *ISAM
Only files with the selected file structure are searched. Multiple file structures can be transferred in a list.
FILE-STRUCTURE = *ANY
Searches all files with SAM, PAM, and ISAM structures.
FILE-STRUCTURE = list-poss(3): *SAM / *PAM / *ISAM
The file structure of the files to be searched must correspond to SAM, PAM, or ISAM. A list can also be specified.
SIZE = *ANY / *INTERVAL(…)
Only files with the selected memory allocation are searched.
SIZE = *ANY
The size of the files is not taken into account.
SIZE = *INTERVAL(…)
The size of the files must be within this range.
FROM = 1 / <integer 1..2147483647 pam pages>
'From' Indication of the size interval.
TO = 2147483647 / <integer 1..2147483647 pam pages>
'Up to' specification of the size range.
CODED-CHARACTER-SET = *ANY / list-poss(10): <name 1..8> / *EBCDIC /*ISO
Specifies which CODED CHARACTER SET (CCS) the files to be searched have.
The user must ensure that a meaningful search pattern is specified under PATTERN. See the notes on the PATTERN operand for further information.
CODED-CHARACTER-SET = *ANY
The CCS of the files is not taken into account.
CODED-CHARACTER-SET = list-poss(10): <name 1..8>
Only files with the specified CCS are searched. A list of multiple CCS can be specified.
CODED-CHARACTER-SET = *EBCDIC
All files with an EBCDIC character set are searched. Specifically, these are all CCS files with an ‘EDF’ prefix.
CODED-CHARACTER-SET = *ISO
All files with an ISO character set are searched. Specifically, these are all CCS files with an ‘ISO’ prefix.
SEARCH-OPTIONS = *PARAMETERS(...)
Options to influence the search behavior of the FIND-FILE command.
MATCH-LIMIT = *NO-LIMIT / <integer 1..255>
Specifies the number of hits in a file after which the search is no longer continued in that file.
MATCH-LIMIT = *NO-LIMIT
All matches found are displayed.
MATCH-LIMIT = <integer 1..255>
Only hits up to this point are displayed; after that, the search in a file is terminated.
OUTPUT-OPTIONS = *PARAMETERS(…)
Output options of the command.
SHOW-RESULT = *MATCHES(…) / *FILE-NAMES(…)
Specifies whether the hits found or only file names are displayed.
SHOW-RESULT = *MATCHES(…)
Specifies that the hits found are to be output.
LINES-BEFORE = 0 / <integer 0..10>
How many lines are output before a line with a hit.
LINES-AFTER = 0 / <integer 0..10>
How many lines are output after a line with a hit.
MAX-LINE-LENGTH = *STD / <integer 30..132>
Specifies the maximum length of an output line.
MAX-LINE-LENGTH = *STD
The maximum value depends on the output value (OUTPUT). The following variants exist:
SYSOUT: 80 characters
SYSLST: 132 characters
File: MAX-LINE-LENGTH has no effect
MAX-LINE-LENGTH = <integer 30..132>
The specified value is limited by the output medium and must be less than this value. A higher value has no effect on the program.
POSITION = *NO / *YES(…)
Inserts the position of the found pattern before the output line.
| Dateityp | Prefix | Erklärung |
|---|---|---|
| SAM | REC#:BYTE#: | Specified using the record number (counted from the start of the file) and the byte position within the record. |
| ISAM | PRIMARY-KEY:BYTE#: | Specified via the primary ISAM key and the byte position within the record. |
shortened: | Since the ISAMKEY can be up to 255 bytes in size and there is not enough space available on the output, it is truncated if necessary. The truncation is indicated by two dots before the key. The maximum displayed length is then 9 characters. The beginning of the key is truncated. | |
| PAM | HP#:BYTE#: | For files without a record structure, the position is defined by the PAM page and the byte position within that page. |
POSITION = *NO
The position of the hit is not displayed.
POSITION = *YES(…)
As indicated above, the position is displayed before the expenditure line.
SHOW-LABEL = *NO / *YES
In addition to the numerical position information, a label describing the value is also output.
- SAM: REC=1:BYTE=5:
- ISAM: ISAMKEY=00010OUT:BYTE=5:
- PAM: HP=5:BYTE=10:
SHOW-LABEL = *NO
By default, the labels for the position information are not displayed.
SHOW-LABEL = *YES
With SHOW-LABEL = *YES, the labels for the position information can also be output.
SHOW-RESULT = *FILE-NAMES(…)
This option outputs only file names.
LIST-FILES = *WITH-MATCHES / *WITHOUT-MATCHES / *BOTH
Selects which file names are displayed.
LIST-FILES = *WITH-MATCHES
Only output file names that contain the specified pattern.
LIST-FILES = *WITHOUT-MATCHES
Only output file names that do not contain the pattern.
LIST-FILES = *BOTH
Display all files that are searched.
MATCH-COUNTER = *NO / *YES
Specifies whether the number of hits is displayed before the file name in addition to the file names.
MATCH-COUNTER = *NO
The number of hits is not displayed.
MATCH-COUNTER = *YES
The number of hits is displayed before the file name.
OUTPUT = *SYSOUT / *SYSLST / <filename_1..54_without-generation_without-wildcards(80)> / *NONE
Specifies the output location of the command.
OUTPUT = *SYSOUT
The output is performed via SYSOUT. The maximum output length is 80 characters.
OUTPUT = *SYSLST
The output is generated via SYSLST. The maximum output length is 132 characters.
OUTPUT = <filename_1..54_without-generation>
The output is written to the specified file. For record-based files (SAM and ISAM), the complete records are written to the output file.
For PAM files, the limit is 132 characters, as with *SYSLST.
OUTPUT = *NONE
Output is completely suppressed.
Command-Returncodes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed successfully | |
| 2 | 0 | CMD0002 | Command executed, pattern not found anywhere |
32 | FNF0001 | Unexpected internal error in FIND-FILE | |
64 | FNF0002 | Unable to close file | |
64 | FNF0003 | The command was executed, no file was searched | |
64 | FNF0004 | At least one of the specified operands was invalid | |
64 | FNF0005 | Could not process the LIST-FILE-NAME file |
Messages
Maincode | Message |
|---|---|
FNF0001 | Unexpected internal error (&00) in FIND-FILE |
FNF0002 | DMS error (&00). Unable to close file (&01) |
FNF0003 | The command was executed, no file was searched |
FNF0004 | Syntax error |
FNF0101 | DMS error (DMS0533). Specified file (&00) does not exist |
FNF0102 | DMS error (&00). File (&01) could not be resolved |
FNF0103 | DMS error (&00). Unable to open file (&01) for searching |
FNF0104 | No valid filename could be found in the specified LIST-FILE-NAME file |
FNF0105 | The filename wildcard could only be partially resolved |
Output in S-Variable
The SHOW-RESULT operand of the command determines which S-variables are generated. The following specifications are possible for SHOW-RESULT:
Spelling in the command | Abbreviated notation in table |
|---|---|
SHOW-RESULT = *MATCH(POSITION=*YES) | 1 |
SHOW-RESULT = *MATCH(POSITION=*NO) | 2 |
SHOW-RESULT = *FILE-NAMES | 3 |
Output information | Name of the S-Variable | Content | Condition | |
|---|---|---|---|---|
Name of the searched file | var(*LIST).F-NAME | <filename_1..54> | 1,2,3 | |
File structure | var(*LIST).F-STRUCT | SAM | 1,2,3 | |
Number of hits found (also the length of the MATCHES list) | var(*LIST).MATCH-COUNT | <integer> | 1,2,3 | |
SAM: Logical block in which a hit was found | var(*LIST).RECORD(*LIST).POSITION(*LIST).BLK | <integer> | 1 | |
PAM: Logical block in which a hit was found | var(*LIST).DATA(*LIST).POSITION(*LIST).BLK | <integer> | 1 | |
SAM: Record number in which a match was found | var(*LIST).RECORD(*LIST).POSITION(*LIST).REC | <integer> | 1 | |
ISAM: ISAM KEY at the location where a match was found | var(*LIST).RECORD(*LIST).POSITION(*LIST).ISAM-KEY | <xstring_1..256> | 1 | |
SAM, ISAM: Byte number of the hit within the logical block | var(*LIST).RECORD(*LIST).POSITION(*LIST).BYTE | <integer> | 1 | |
PAM: Byte number of the hit within the logical block | var(*LIST).DATA(*LIST).POSITION(*LIST).BYTE | <integer> | 1 | |
SAM, ISAM: Length of the hit | var(*LIST).RECORD(*LIST).POSITION(*LIST).LEN | <integer> | 1 | |
PAM: Length of the hit | var(*LIST).DATA(*LIST).POSITION(*LIST).LEN | <integer> | 1 | |
PAM: The data containing the hit | var(*LIST).DATA(*LIST).DATA | <cstring_1..256> | 1,2 | |
SAM, ISAM: The record containing the hit | var(*LIST).RECORD(*LIST).RECORD | <cstring_1..256> | 1,2 | |
Examples
The following examples assume these files:
:X:$Y.TEST.SAM | :X:$Y.TEST.ISAM | :X:$Y.TEST.PAM |
BEISPIEL TEST BEISPIEL | 00001000BEISPIEL TEST BEISPIEL | F0F0F0F0 F1D6E4E3 C9D54040 |
Example 1: Standard search across all files
/FIND-FILE TEST*,'test'
:X:$Y.TEST.ISAM: 00001000BEISPIEL TEST BEISPIEL :X:$Y.TEST.SAM: BEISPIEL TEST BEISPIEL
Example 2: Search with position specification
/FIND-FILE TEST*,'test',POSITION=*YES
:X:$Y.TEST.ISAM: 00001000:17:00001000BEISPIEL TEST BEISPIEL :X:$Y.TEST.SAM: 1:9:BEISPIEL TEST BEISPIEL
Example 3: Search with position specification and label - SAM and ISAM
/FIND-FILE TEST*,'test',POSITION=*YES(SHOW-LABEL=*YES)
:X:$Y.TEST.ISAM: ISAMKEY=00001000:BYTE=17:00001000BEISPIEL TEST BEISPIEL :X:$Y.TEST.SAM: REC=1:BYTE=9:BEISPIEL TEST BEISPIEL
Example 4: Search with position specification and label - PAM
/FIND-FILE TEST.PAM,'outin',POSITION=*YES(SHOW-LABEL=*YES)
:X:$Y.TEST.PAM: HP=1:BYTE=5:00001OUTIN
Example 5: Search with SHOW-RESULT=*FILE-NAMES and MATCH-COUNTER
/FIND-FILE TEST*,'test',SHOW-RESULT=*FILE-NAMES(LIST-FILES=*BOTH, MATCH-COUNTER=*YES)
1: :X:$Y.TEST.ISAM 0: :X:$Y.TEST.PAM 1: :X:$Y.TEST.SAM
Example 6: ISAM/SAM: S variable with position specification
/DECLARE-VARIABLE OPS(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST /EXEC-CMD (FIND-FILE TEST*,’TEST’,OUTPUT-OPTIONS=*PARAMETERS(SHOW-RESULT=*MATCHES(POSITION=*YES))),STRUCTURE-OUTPUT=OPS /SHOW-VARIABLE OPS,INFORMATION=*PARAMETERS(NAME=*FULL-NAME(LIST-INDEX-NUMBER=*YES)) OPS#1.F-NAME = :X:$Y.TEST.SAM OPS#1.F-STRUCT = SAM OPS#1.RECORD#1.POSITION#1.BLK = 1 OPS#1.RECORD#1.POSITION#1.REC = 1 OPS#1.RECORD#1.POSITION#1.BYTE = 7 OPS#1.RECORD#1.POSITION#1.LEN = 4 OPS#1.MATCH-COUNT = 1 OPS#2.F-NAME = :X:$Y.TEST.ISAM OPS#2.F-STRUCT = ISAM OPS#2.RECORD#1.POSITION#1.ISAM-KEY = 00001000 OPS#2.RECORD#1.POSITION#1.BYTE = 15 OPS#2.RECORD#1.POSITION#1.LEN = 4 OPS#2.MATCH-COUNT = 1
Example 7: PAM: S variable with position specification
/DECLARE-VARIABLE OPS(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST /EXEC-CMD (FIND-FILE TEST*,X’F1D6E4E3’,OUTPUT-OPTIONS=*PARAMETERS(SHOW-RESULT=*MATCHES(POSITION=*YES))),STRUCTURE-OUTPUT=OPS /SHOW-VARIABLE OPS,INFORMATION=*PARAMETERS(NAME=*FULL-NAME(LIST-INDEX-NUMBER=*YES)) OPS#1.F-NAME = :X:$Y.TEST.PAM OPS#1.F-STRUCT = PAM OPS#1.DATA#1.POSITION#1.BLK = 1 OPS#1.DATA#1.POSITION#1.BYTE = 4 OPS#1.DATA#1.POSITION#1.LEN = 4 OPS#1.MATCH-COUNT = 1
Example 8: ISAM/SAM: S variable without position specification
/DECLARE-VARIABLE OPS(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST /EXEC-CMD (FIND-FILE TEST*,’TEST’,OUTPUT-OPTIONS=*PARAMETERS(SHOW-RESULT=*MATCHES(POSITION=*NO))),STRUCTURE-OUTPUT=OPS /SHOW-VARIABLE OPS,INFORMATION=*PARAMETERS(NAME=*FULL-NAME(LIST-INDEX-NUMBER=*YES)) OPS#1.F-NAME = :X:$Y.TEST.SAM OPS#1.F-STRUCT = SAM OPS#1.MATCH-COUNT = 1 OPS#2.F-NAME = :X:$Y.TEST.ISAM OPS#2.F-STRUCT = ISAM OPS#2.MATCH-COUNT = 1
Example 9: PAM: S variable without position specification
/DECLARE-VARIABLE OPS(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST /EXEC-CMD (FIND-FILE TEST*,X’F1D6E4E3’,OUTPUT-OPTIONS=*PARAMETERS(SHOW-RESULT=*MATCHES(POSITION=*NO))),STRUCTURE-OUTPUT=OPS /SHOW-VARIABLE OPS,INFORMATION=*PARAMETERS(NAME=*FULL-NAME(LIST-INDEX-NUMBER=*YES)) OPS#1.F-NAME = :X:$Y.TEST.PAM OPS#1.F-STRUCT = PAM OPS#1.MATCH-COUNT = 1
Example 10: S variable with SHOW-RESULT=*FILE-NAMES
/DECLARE-VARIABLE OPS(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST /EXEC-CMD (FIND-FILE TEST*,’TEST’,OUTPUT-OPTIONS=*PARAMETERS(SHOW-RESULT=*FILE-NAMES(MATCH-COUNTER=*YES))),STRUCTURE-OUTPUT=OPS /SHOW-VARIABLE OPS,INFORMATION=*PARAMETERS(NAME=*FULL-NAME(LIST-INDEX-NUMBER=*YES)) OPS#1.F-NAME = :X:$Y.TEST.SAM OPS#1.F-STRUCT = SAM OPS#1.MATCH-COUNT = 1 OPS#2.F-NAME = :X:$Y.TEST.ISAM OPS#2.F-STRUCT = ISAM OPS#2.MATCH-COUNT = 1
Example 11: Entering a file list
/&* The parameter 'FORM-NAME=*FILE-NAME' is important! /SHOW-FILE-ATTRIBUTES SELECT=*BY-ATTRIBUTES(FILE-STRUCTURE=*ISAM),OUTPUT=SH.OUT(FORM-NAME=*FILE-NAME) /FIND-FILE FILE-NAME=*FROM-FILE(LIST-FILE-NAME=SH.OUT),PATTERN='ISAM'