# FINDM (BPAM)

## Syntax:

    FINDM(ddname,{member|ttr}[,option])

## Arguments:

ddname
  is the 1 to 8 character name that identifies the data set you want to process. This name needs to have been previously associated with the data set, either via the ALLOCATE command or JCL DD statement, and opened via the OPEN function.
member
  is the 1 to 8 character name that identifies the member you want to process. The system searches the PDS directory for this name to determine the member's address.

  The second argument is treated as a member name for all values of option except 'T'

ttr
  is the 6 byte printable hexadecimal address (in TTR format) of the member you want to process. The system does not search for the member. It uses the TTR value to directly position to the member. A member's TTR can be obtained from the FINDM, STOWM, and LISTM functions.

  Note: This argument must be exactly 6 bytes long. The TTRs produced by LISTM, FINDM, and STOWM are in the proper format.

option
  indicates the type of the second argument (member or ttr), and determines the type of processing required. The valid options are:
  'M'
    indicates member name find only. The system establishes position so that subsequent GETs read records from the member. No directory information is returned. This is the default.
  'T'
    indicates positioning by TTR. The second argument must be a valid TTR address for a member. The system establishes position so that subsequent GETs read records from the member. No directory information is returned.
  'U'
    indicates member name positioning (see 'M' above) and in addition, the system retrieves directory information for the member. The directory entry's user field is returned, unformatted.
  'S'
    indicates member name positioning (see 'M' above) and in addition, the system retrieves directory information for the member. If the directory entry's user field contains syntactically valid ISPF statistics, FINDM formats and returns this information.

## Module Name:

SWXFINDM

## Service Description:

FINDM is used to position for reading a PDS/PDSE member. Optionally, FINDM will retrieve the member's directory information. If the file has been opened for update, and one or more PUTs to a member have been executed, FINDM will complete pending write operations, prior to finding the next member.

FINDM can be used only if the file has been opened for input or update. It is an error to use FINDM with a file that is open for output. You must close and re-open the file for input or update.

Note: FINDM establishes a connection to a PDSE member.

## Returned Information:

The FINDM function returns a string containing different values, depending on the value of option and the success of the operation.

- If a non-zero return code is encountered, only the return code is returned, regardless of the option. The return code is taken directly from the FIND or BLDL macros.
- If the return code is zero and option 'M' or 'T' is used, only the return code is returned.
- If the return code is zero and option 'U' is used, the following information is returned:
  rc
    the return code.
  ttr
    the address of the member in TTR format (TT=Track; R=Record). This value can be used in subsequent FINDM calls to reposition to the member (provided the member's position does not change!).
  k
    the concatenation number of the data set containing the member. The first (or only) data set in a concatenation of data sets has a "K" value of zero.
  z
    the "where found" indicator. The following values are possible:
    0
      Private library
    1
      Link library
    2
      Job, task, or step library
    3-255
      Job, task, or step library of parent task n, where n = z-2
  c
    the alias indicator. If '0' the directory entry is not an alias. If '1' the directory entry is an alias.
  userfield
    the user field of the directory entry. This field can be 0 to 62 bytes long. The data may contain any values, including blanks.
- If the return code is zero and option 'S' is used, the following information is returned:
  rc
    the return code.
  ttr
    the address of the member in TTR format (TT=Track; R=Record). This value can be used in subsequent FINDM calls to reposition to the member (provided the member's position does not change!).
  k
    the concatenation number of the data set containing the member. The first (or only) data set in a concatenation of data sets has a "K" value of zero.
  z
    the "where found" indicator. The following values are possible:
    0
      Private library
    1
      Link library
    2
      Job, task, or step library
    3-255
      Job, task, or step library of parent task n, where n = z-2
  c
    the alias indicator. If '0' the directory entry is not an alias. If '1' the directory entry is an alias.
  vv
    ISPF version number. Valid range: 00- 99.
  mm
    ISPF modification level. Valid range 00-99.
  cdate
    ISPF creation date in CCYY.DDD format (Julian date with 4-digit year).
  mdate
    ISPF modification date in CCYY.DDD format (Julian date with 4-digit year).
  mtime
    ISPF modification time in HH:MM:SS format.
  cl
    ISPF current lines.
  il
    ISPF initial lines.
  ml
    ISPF modified lines.
  muserid
    ISPF last modification user ID.

  Very Important: The ISPF statistics are taken from the member's directory entry. The system does not verify that the values are accurate. If the interface does not find syntactically valid ISPF statistics, items vv through muserid will be null. No other error indication is given.

If you CALL the FINDM function, the returned value is contained in the RESULT special variable.

After completion of a FINDM function call, several special REXX variables are populated with useful information. You should treat these variables as "read only" and make no attempt to modify any of them. The variables are:

RC
  Contains the FIND or BLDL return code. An RC of zero means the operation was completed successfully.
REASON
  Contains the FIND or BLDL reason code.

## Examples:

1. Position to a member:

       if findm('indd','payroll') = 0 then do
         /* read the member */
       end

2. Position to a member using its TTR:

       if findm('indd','0003A9','t') = 0 then do
         /* read the member */
       end

3. Position to a member and retrieve its directory entry in "user" format:

       parse value findm('indd','payroll','u') with,
         rc ttr k z c usrfld
       if rc = 0 then do
         /* read the member */
       end

4. Position to a member and retrieve its directory entry in ISPF format:

       parse value findm('indd','payroll','s') with,
         rc ttr k z c vv mm cdate mdate mtime cl il ml uid
       if rc = 0 then do
         /* read the member */
       end

© Copyright 1998 by Open Software Technologies, Inc.