With %FIND you can search for a literal in a data element or in the executable part of a program, and output hits to the terminal (via SYSOUT). In addition, the address of the hit and the continuation address are stored in AID registers %0G and %1G. %FIND can be used to search both virtual memory and a dump file.
search-criterion is the character literal or hexadecimal literal to be searched.
With find-area you specify which data element or which section of the executable part of the program AID is to search for search-criterion. AID can search the virtual address space of the task as well as dump files. If the find-area value is omitted, AID searches the entire memory area in accordance with the base qualification currently set (see %BASE).
With alignment you specify whether the search for search-criterion is to be effected at a doubleword, word, halfword or byte boundary. When a value for alignment is not given, searching takes place at the byte boundary.
With ALL you specify that the search is not to be terminated after output of the first hit, rather the entire find-area is to be searched and all hits are to be output. The search can only be aborted by pressing the K2 key.
Command | Operands |
%F[IND] | [ [ALL] search-criterion [IN find-area] [alignment] ] |
If the ALL operand is omitted from a %FIND command, the user may continue after the address of the last hit and up to the end of the find-area by specifying a new %FIND command without any operand values.
In a %FIND command with a separate search-criterion and without any other operands, AID inserts the corresponding default value for an operand without a current value. In this case, therefore, no operands are taken over from a previous %FIND command.
In the event of a hit, output is to a maximum length of 12 bytes, from the hit to the end of find-area on the terminal (SYSOUT) in dump format (hexadecimal and character representation). In addition to the hit itself, its address and (insofar as possible) the name of the compilation unit in which the hit was found, and the relative address of the hit with respect to the beginning of the compilation unit, are output.
The hit address is stored in AID register %0G and the continuation address (hit address + search string length) in AID register %1G. With the ALL specification, the address of the last hit is stored in %OG and the continuation address of the last hit is stored in %1G. If the
search-criterion has not been found, AID registers %0G and %1G remain unchanged.
The two register contents permit you to use the %FIND command in procedures as well as in subcommands and to further process the results.
The %FIND command does not alter the program state.
search-criterion |
is a character literal, hexadecimal literal or a memory location. When a memory location is specified, parentheses must be specified in the format (search-criterion).
In the case of a literal specification of search-criterion you may use wildcard symbols. These symbols are always hits. They are represented by ’%’.
search-criterion-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - C'x...x' | 'x...x' X'f...f' | %C(literal) / %UTF16(literal) (memory-location) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
{C'x...x' | 'x...x'}
Character literal with a maximum length of 80 characters. Lowercase letters can only be located as character literals after specifying %AID LOW[=ON].
x can be any representable character, in particular the wildcard symbol ’%’, which always represents a hit. The character ’%’ itself cannot be located when it is in this form, since C’%’ in a character literal must always result in a hit. For this reason it must be represented as the hexadecimal literal X’6C’.
Please note that in order to properly locate character data, the CCS of find-area has to agree with the CCS of the input media (SYSCMD). Be sure to specify the CCS
of find-area before looking for some character data in find-area:
%AID CCS= CCS-name
A complete list of CCS-name supported by XHCS and the current CCS of SYSCMD can be displayed with the following AID command:
%SHOW %CCSN
The CCS of SYSCMD can be changed with the following SDF command:
MODIFY-TERMINAL-OPTION CODED-CHARACTER-SET= {EBCDIC-CCS-name | UTFE}
The current CCS of find-area can be displayed with the following AID command:
%SHOW %AID
Be aware that since V3.4B11 the %DISPLAY command refers to the CCS value of %AID as to the default (implicit) CCS of character data to be displayed:
%D char-data ['CCS-name']
See the section “Character literal” in the AID Core Manual [1] for an example on how to search for character literals in different coded character sets.
{X'f...f'}
Hexadecimal literal with a maximum length of 80 hexadecimal digits or 40 characters. A literal with an odd number of digits is padded with X’0’ on the right.
f can assume any value between 0 and F, as well as the wildcard symbol X’%’. The wildcard symbol represents a hit for every hexadecimal digit between 0 and F.
%C(literal) | %UTF16(literal)
These functions must be used when, for example, UTF16 encoding of the searchcriterion is required or when strings in 1-byte encoding are searched for even though the literal was specified in UTFE encoding.
(memory-location)
The search-criterion is taken from memory-location. If memory-location is of the type %UTF16, up to 160 bytes = 80 UTF16 characters can be searched for. In all other cases search-criterion is limited to 80 bytes.
memory-location can also be a symbolic field. A NATIONAL field is then treated like a %UTF16 memory-location.
find-area |
defines the memory area to be searched for search-criterion. find-area can be a data item or part of the PROCEDURE DIVISION of the loaded program or of a dump file. find-area must not exceed 65535 bytes in length.
If no find-area has been specified, AID inserts the default value %CLASS6 (see AID Core Manual (Related publications) [1]), i.e. the class 6 memory for the currently set base qualification is searched (see %BASE).
find-area-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IN [•][qua•] { dataname | statement-name -> | source-reference -> | compl-memref }
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
•
If the period is in the leading position it denotes a prequalification, which must have been defined with a preceding %QUALIFY command. Consecutive qualifications
must be separated by a period. In addition, there must be a period between the final qualification and the following operand part.
qua
Qualifications need only be specified if an address operand does not apply to the
current AID work area of if an address is to be referenced which is not in the current compilation unit or the current program.
E={VM | Dn}
Need only be specified if the current base qualification is not to apply for findarea (see also %BASE command).
S=srcname
Need only be specified if find-area is not within the current compilation unit (see chapter “COBOL-specific addressing”).
PROC=program-id
Need only be specified if find-area is not within the current program (see chapter “COBOL-specific addressing”) or if it is defined with a dataname or statementname which is not unique in the compilation unit.
If srcname in the S qualification is the same as program-id, only the PROG qualification need be written.
Only the base qualification or the CTX qualification can be placed before the C qualifications listed below. The C qualification takes the user away from the symbolic level. No symbolic operands can be written directly afterwards (see section “Symbolic memory references”), only a compl-memref.
C=segmentname
Without a length modification the entire segment is specified as find-area.
C=sharename
Without a length modification the entire object module is specified as find-area.
dataname
is the name of a data item defined in the source program or the name of a COBOL special register.
If dataname is not unique within a program, it can be marked.
If dataname is the name of an element in a table, it can be indexed or subscripted in the same way as in a COBOL statement (see section “Symbolic memory references").
dataname [identifier][...] [(index[,...])]
identifier
IN or OF can be used to assign dataname to a certain group item. dataname must have as many identifiers as are required to designate it unambiguously.
If it is not identified, AID only processes dataname if a data definition is provided for it at level 01 or 77. If this is not the case, an error message is issued.
index
This is written in the same way as in a COBOL except that multiple indexes in the AID command must be separated by commas. index can be specified as follws:
{ n | index-name | dataname | TALLY | arithmetic-expression }
COBOL special registers
LINAGE-COUNTER
RETURN-CODE
SORT-CCSN
SORT-CORE-SIZE
SORT-EOW
SORT-FILE-SIZE
SORT-MODE-SIZE
SORT-RETURN
TALLY
{ statement-name | source-reference } ->
designates 4 bytes of the program code from the address contained in the address constant. If a different number of bytes is to be searched, you must specify a corresponding length modification.
statement-name
defines the address of the first instruction in a section or paragraph in the PROCEDURE DIVISION.
{ L'section' | L'paragraph' [IN L'section']}
If a paragraph name is not unambiguous within a program, it must be identified by the section name of the section in which it was defined: L'paragraph' IN L'section'
source-reference
designates the address of the first instruction generated for a statement in the PROCEDURE DIVISION and must be specified in one of the following formats:
S’n’
for lines with paragraph or section names in which no COBOL verb occurs.
This specification is not possible for programs which have been compiled with STMT-REFERENCE=COLUMN1-TO-6.
S’nverb[m]’ | S’xverb[m]’
for lines containing a COBOL verb.
compl-memref
The following operations may occur in compl-memref (see AID Core Manual (Related publications) [1]):
byte offset (•)
indirect addressing (->)
type modification (%A, %S, %SX)
length modification (%L(...), %L=(expression), %Ln)
address selection (%@(...))
If compl-memref begins with a statement name or source reference, it must be followed by a pointer operator ( -> ). In this case statement-name must be specified with L’...’. Without the pointer operator the statement name and source reference can be used anywhere where hexadecimal numbers can be written.
compl-memref designates an area of 4 bytes starting from the calculated address. If a different number of bytes is to be searched, a corresponding length modification must be added. When modifying the length of data items you must pay attention to area boundaries or switch to machine code level using %@(dataname)->.
alignment |
defines that the search for search-criterion is to be effected at certain aligned addresses only.
alignment-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ALIGN [=] {1 | 2 | 4 | 8}
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
search-criterion is searched for at:
1 2 4 8 | byte boundary (default) halfword boundary word boundary doubleword boundary |
Examples
%FIND X'F0' IN DATAThe hexadecimal literal X’F0’ is searched for in the variable DATA. Any hit is output to SYSOUT.- %F X'D2' IN S'12MOV'->%L=(S'13ADD'-S'12MOV') ALIGN=2
The hexadecimal literal X’D2’ is searched for at a halfword boundary in the machine code generated for statement 12MOV. - %F
The search is continued with the parameters of the last %FIND command behind the last hit. - The input medium has the CCSN UTFE:
%FIND %UTF16('[{Ö') IN V'xxx'The command searches for the string ’[{Ö’ in its UTF16 encoding starting at the memory location V'xxx'.
If the %UTF16() function were not specified, AID would search for the UTFE encoding X’BBFB9EB6’ of ’[{Ö’ in the memory.
Using the %UTF16() function means that its UTF16 encoding X’005B007B00D6' is searched for in the memory. - The input medium has the CCSN UTFE.
%FIND %C('Ä') IN V'xxx'
%AID EBCDIC=EDF03DRV(German character set)
The command searches for the German encoding of Ä (corresponds to X’BB’)
starting at address V’xxx’. If %C() were not specified, AID would search for X’9E9F’ (= UFTE encoding of ’Ä’) in the memory.- %AID EBCDIC=EDF03IRV
Instead of the character ’Ä’, which is illegal in the character set EDF03IRV, the command searches for the substitute character ’.’. In this case AID reports that a replacement character has occurred in %C() conversion.