Retrieve Member Description (RTVMBRD)

The Retrieve Member Description (RTVMBRD) command is used in a CL program or REXX procedure to retrieve (return) the member-level information (in CL variables) from a database file.

The values are returned (copied) to the specified CL variables. The following kinds of member information can be retrieved:

• The library name.
• The member name.
• The file attribute.
• The file type.
• The source type.
• The source date.
• The date created.
• The expiration date.
• The member text.
• The number of nondeleted records.
• The number of deleted records.
• The open data path status (shared or not shared).
• The data space size.
• The access path size.
• The date changed.
• The date saved.
• The date restored.
• The number of data members.
• The last date used.
• The days count used.
• The date and days count was reset.

Parameters

File (FILE)

Specifies the file that contains the member description that is retrieved.

This is a required parameter.

Note: You must have use (*USE) authority to the file and execute (*EXECUTE) authority to the library before the member description information can be retrieved.

Qualifier 1: File

name

Specify the name of the file that contains the file member.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is searched. If no current entry exists in the library list, QGPL is used.

name

Specify the library name to search.

Member (MBR)

Specifies the file member whose description is retrieved. Either a single value (*FIRST or *LAST) or a double value (reference member and relationship) can be specified.

Single values

*FIRST

The first member in a date-ordered list is retrieved.

*LAST

The last member in a date-ordered list is retrieved.

Element 1: Reference member

*FIRSTMBR

The first member in a name ordered list is retrieved. The relationship value *SAME is required.

*LASTMBR

The last member in a name ordered list is retrieved. The relationship value *SAME is required.

name

Specify the name of the reference member. The relationship of the retrieved member to the reference member is specified on the second element of this parameter (*SAME, *NEXT, or *PRV). If a variable is specified, it must be a 10-character field that contains the name of the reference member.

generic-name

Specify the starting characters of the member name followed by an asterisk. This retrieves the first member in the name ordered list that starts with the specified characters. The relationship value is required to be *SAME.

Element 2: Relationship

*SAME

The reference member is retrieved.

*NEXT

The member immediately after the reference member in a name ordered list is retrieved.

*PRV

The member immediately previous to the reference member in a name ordered list is retrieved.

CL var for RTNSYSTEM (4) (RTNSYSTEM)

Specifies the name of a variable used to retrieve the name of the system from which the file was retrieved. In CL programs, this should be a 4-character variable.

The values that can be returned are *LCL (file found on the local system) and *RMT (file found on a remote system).

CL var for RTNLIB (10) (RTNLIB)

Specifies the name of a variable used to retrieve the name of the library in which the file containing the specified file member is located. In CL programs, this should be a 10-character variable.

CL var for RTNMBR (10) (RTNMBR)

Specifies the name of a variable used to retrieve the name of the file member whose description is being retrieved. In CL programs, this should be a 10-character variable.

CL var for FILEATR (3) (FILEATR)

Specifies the name of a variable used to retrieve the file attribute. In CL programs, this should be a 3-character variable.

The values that can be returned are *PF (physical file member) and *LF (logical file member).

CL var for FILETYPE (5) (FILETYPE)

Specifies the name of a variable used to retrieve the file type. In CL programs, this should be a 5-character variable.

The values that are returned are *DATA (data file member) and *SRC (source file member).

CL var for SRCTYPE (10) (SRCTYPE)

Specifies the name of a variable used to retrieve the source file member type if this is a source file member. Blanks are returned if this is not a source file member. In CL programs, this should be a 10-character variable.

CL var for SRCCHGDATE (13) (SRCCHGDATE)

Specifies the name of a 13-character CL variable used to retrieve the century, date, and time the last source file member was changed. The format is CYYMMDDHHMMSS where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, D = Day, H = Hour, M = Minutes, and S = Seconds.

Blanks are returned if no date is available. Remote non-IBM i and non-System/38 files or non-source physical file return blanks.

CL var for CRTDATE (13) (CRTDATE)

Specifies the name of a variable used to retrieve the file member creation century, date, and time. In CL programs, this should be a 13-character variable. The format is CYYMMDDHHMMSS where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, D = Day, H = Hour, M = Minutes, and S = Seconds.

CL var for EXPDATE (7) (EXPDATE)

Specifies the name of a variable used to retrieve the file member expiration century and date. In CL programs, this should be a 7-character variable. The format is CYYMMDD where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, and D = Day.

*NONE is returned if no date is available.

CL var for TEXT (50) (TEXT)

Specifies the name of a variable used to retrieve the file member text. In CL programs, this should be a 50-character variable.

CL var for NBRCURRCD (10 0) (NBRCURRCD)

Specifies the name of a variable used to retrieve the current number of nondeleted records in this file member. In CL programs, this should be a 10-position decimal variable.

If the member is a keyed logical member, the number of index entries is returned. For nonkeyed logical members, the number of nondeleted records in the based-on physical file member is returned.

For a join logical file, the number of records returned is a total of all the nondeleted records in the files being joined. This number includes those records that exist in the secondary file which do not have matching records in the primary file. If omit or select criteria is used, the number of records returned will be reduced or increased by the number of records meeting the selection criteria in the specified files.

CL var for NBRDLTRCD (10 0) (NBRDLTRCD)

Specifies the name of a variable used to retrieve the current number of deleted records in this file member. In CL programs, this should be a 10-position decimal variable. Zero (0) is returned for keyed logical files. Remote non-IBM i and non-S/38 files return a value of 0. For nonkeyed logical files, the number of deleted records in the based-on physical file member is returned.

CL var for SHARE (4) (SHARE)

Specifies the name of a variable used to retrieve a value indicating whether the open data path (ODP) allows sharing with other programs in the same job. In CL programs, this should be a 4-character variable.

Values for ODP sharing are *YES (ODP sharing is allowed) and *NO (ODP sharing is not allowed).

Remote non-IBM i and non-S/38 files return *NO.

CL var for DTASPCSIZ (15 0) (DTASPCSIZ)

Specifies the name of a variable used to retrieve the data space size (in bytes) of this file member. In CL programs, this should be a 15-position decimal variable. Zero (0) is returned if this is a logical file member.

CL var for ACCPTHSIZ (12 0) (ACCPTHSIZ)

Specifies the name of a variable used to retrieve the access path size (in bytes) for this file member. In CL programs, this should be a 12-position decimal variable. Zero (0) is returned if the file member is non-keyed. Remote non-IBM i and non-S/38 files return a value of 0.

CL var for CHGDATE (13) (CHGDATE)

Specifies the name of a variable used to retrieve the file change century, date, and time. In CL programs, this should be a 13-character variable. The format is CYYMMDDHHMMSS where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, D = Day, H = Hour, M = Minutes, and S = Seconds.

CL var for SAVDATE (13) (SAVDATE)

Specifies the name of a variable used to retrieve the file member and the save century, date, and time. In CL programs, this should be a 13-character variable. The format is CYYMMDDHHMMSS where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, D = Day, H = Hour, M = Minutes, and S = Seconds.

Blanks are returned if no date is available. Remote non-IBM i and non-System/38 files return blanks.

CL var for RSTDATE (13) (RSTDATE)

Specifies the name of a variable used to retrieve the file member and restore century, date, and time. In CL programs, this should be a 13-character variable. The format is CYYMMDDHHMMSS where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, D = Day, H = Hour, M = Minutes, and S = Seconds.

Blanks are returned if there is no date available. Remote non-IBM i and non-System/38 files return blanks.

CL var for NBRDTAMBRS (2 0) (NBRDTAMBRS)

Specifies the name of a variable used to retrieve the number of data file members for this logical file member. In CL programs, this should be a 2-position decimal variable. If the member is a physical file member, a value of 0 is returned.

CL var for USEDATE (7) (USEDATE)

Specifies the name of a variable used to return the member last used century and date. In CL programs, this should be a 7-character variable. The format is CYYMMDD where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, and D = Day.

CL var for USECOUNT (5 0) (USECOUNT)

Specifies the name of a variable that is used to return the number of days the member has been used. In CL programs, this should be a 5 decimal variable. If the member does not have a last used date, 0 is returned.

CL var for RESETDATE (7) (RESETDATE)

Specifies the name of a variable that is used to return the century and date the days used count was last reset to 0. In CL programs, this should be a 7-character variable. The format is CYYMMDD where C = Century (0 = 1940 through 1999 and 1 = 2000 through 2039), Y = Year, M = Month, and D = Day. If the days used count has not been reset, blanks are returned.

Examples

Assume the user has a file named MYFILE in library MYLIB (which is the current library) with members QMEMBER, BMEMBER, ZMEMBER, and JMEMBER (created in that order).

Also assume the following variables are specified in the CL program:

DCL  &LIB        TYPE(*CHAR) LEN(10)
DCL  &MBR        TYPE(*CHAR) LEN(10)
DCL  &SYS        TYPE(*CHAR) LEN(4)
DCL  &MTYPE      TYPE(*CHAR) LEN(5)
DCL  &CRTDATE    TYPE(*CHAR) LEN(13)
DCL  &CHGDATE    TYPE(*CHAR) LEN(13)
DCL  &TEXT       TYPE(*CHAR) LEN(50)
DCL  &NBRRCD     TYPE(*DEC) LEN(10 0)
DCL  &SIZE       TYPE(*DEC) LEN(10 0)

Example 1: Retrieving Member Description Values

RTVMBRD   FILE(*CURLIB/MYFILE)  MBR(BMEMBER *SAME)  +
          RTNLIB(&LIB)  RTNSYSTEM(&SYS)  +
          RTNMBR(&MBR)  FILEATR(&MTYPE)  +
          CRTDATE(&CRTDATE)  TEXT(&TEXT)  +
          NBRCURRCD(&NBRRCD)  DTASPCSIZ(&SIZE)

This command retrieves the member description for member BMEMBER of file MYFILE located using the library list. The requested information is placed in the CL variables as follows:

• The current library name (MYLIB) is placed in the CL variable named &LIB.
• The system on which MYFILE was found is placed in the CL variable named &SYS. (*LCL means the file was found on the local system, and *RMT means the file was found on a remote system.)
• The member name (BMEMBER) is placed in the CL variable named &MBR.
• The file attribute of MYFILE is placed in the CL variable named &MTYPE. (*DATA means the member is a data member, and *SRC means the file is a source member.)
• The creation date of BMEMBER is placed in the CL variable named &CRTDATE.
• The text associated with BMEMBER is placed in the CL variable called &TEXT.
• The current number of records in BMEMBER is placed in the CL variable called &NBRRCD.
• The size of BMEMBER's data space (in bytes) is placed in the CL variable called &SIZE.

Example 1: Retrieving the Next Member Description

RTVMBRD   FILE(&LIB/MYFILE)  MBR(&MBR *NEXT)  +
          RTNMBR(&MBR)  CRTDATE(&CRTDATE)  +
          TEXT(&TEXT)  NBRCURRCD(&NBRRCD)  +
          DTASPCSIZ(&SIZE)

This command retrieves the member description for the member of file MYFILE which is "next" (in name order). The requested information is placed in the CL variables as follows:

• The next member's name after BMEMBER (JMEMBER since the file is searched in name order) in MYFILE is placed in the CL variable named &MBR.
• The creation date of JMEMBER is placed in the CL variable named &CRTDATE.
• The text associated with JMEMBER is placed in the CL variable called &TEXT.
• The current number of records in JMEMBER is placed in the CL variable called &NBRRCD.
• The size of JMEMBER's data space (in bytes) is placed in the CL variable called &SIZE.

The file can also be searched backwards. An example is:

RTVMBRD   FILE(*CURLIB/MYFILE)  MBR(ZMEMBER *PRV)  +
          RTNMBR(&MBR)  CHGDATE(&CHGDATE)  TEXT(&TEXT)

The requested information is placed in the CL variables as follows:

• The member name (QMEMBER since it is the member just previous to ZMEMBER in a name-ordered list) is placed in the CL variable named &MBR.
• The date QMEMBER was last changed is placed in the CL variable named &CHGDATE.
• The text associated with QMEMBER is placed in the CL variable called &TEXT.

If only the first part of the member name is known, you can use a generic name (or partial name) search of the list of members, as follows:

RTVMBRD   FILE(*LIBL/MYFILE)  MBR(JM*)  RTNMBR(&MBR)  +
          CHGDATE(&CHGDATE)  TEXT(&TEXT)

The requested information is placed in the CL variables as follows:

• The member name (JMEMBER since it is the first member starting with the characters JM in a name ordered list) is placed in the CL variable named &MBR.
• The date JMEMBER was last changed is placed in the CL variable named &CHGDATE.
• The text associated with JMEMBER is placed in the CL variable called &TEXT.

Error messages

*ESCAPE Messages

CPF3018

Member &3 for file &1 in &2 not available.

CPF3019

File &1 in library &2 has no members.

CPF3027

File &1 in &2 not a database file.

CPF3038

Attributes for return variable &1 not valid.

CPF3039

Return variable &1 too small to hold result.

CPF3049

*NEXT or *PRV member does not exist.

CPF3051

File &1 in library &2 not available.

CPF325F

Conversion of the text failed.

CPF327B

File &1 information cannot be retrieved.

CPF8109

&8 damage on physical database file &4.

CPF8110

&8 damage on logical data base file &4 in &9. VLOG-&7.

CPF8111

&8 damage on member &9 file &4.

CPF9803

Cannot allocate object &2 in library &3.

CPF9806

Cannot perform function for object &2 in library &3.

CPF9810

Library &1 not found.

CPF9812

File &1 in library &2 not found.

CPF9815

Member &5 file &2 in library &3 not found.

CPF9820

Not authorized to use library &1.

CPF9822

Not authorized to file &1 in library &2.