RTVMBRD (Retrieve Member Description)

RTVMBRD Command syntax diagram

 

Purpose

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.

 

Required Parameters

FILE

Specifies the qualified name of the file that contains the member description being retrieved.

Note:

*OBJOPR authority to the file and *READ authority to the library are required for the member description being retrieved.

The name of the file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

file-name: Specify the name of the file.

 

Optional Parameters

MBR

Specifies the member whose description is retrieved.

*FIRST: The first member in the database file is used.

*LAST: The last member of the specified physical file is retrieved.

Element 1: Member to Retrieve

*FIRSTMBR: The first member in a list sorted by name is retrieved.

*LASTMBR: The last member in a list sorted by name is retrieved.

member-name: Specify the name of the reference member. The reference member is a base from which the *NEXT, *PRV, or *SAME member is retrieved.

generic*-member-name: Specify the generic member name being retrieved. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic names, refer to generic names.

Element 2: Operation to Perform on Member

*SAME: The reference member is retrieved.

*NEXT: The member immediately after the reference member is retrieved.

*PRV: The member immediately before the reference member is retrieved.

RTNSYSTEM

Specifies the name of a 4-character CL variable used to retrieve an indication of the system from which the description is retrieved. The possible values are *LCL (file found on the local system) and *RMT (file found on remote system).

RTNLIB

Specifies the name of a 10-character CL variable used to retrieve the name of the library where the specified file is located.

RTNMBR

Specifies the name of a 10-character CL variable used to retrieve the name of the member whose description is being retrieved.

FILEATR

Specifies the name of a 3-character CL variable used to retrieve the file attribute. The possible values are *PF (retrieves the attribute for a physical file member) and *LF (retrieves the attribute for a logical file member).

FILETYPE

Specifies the name of a 5-character CL variable used to retrieve the file type. The possible values are *DATA (retrieves the file type for a data member) and *SRC (retrieves the file type for a source member).

SRCTYPE

Specifies the name of a 10-character CL variable used to retrieve the source member type (if this is a source member). Blanks are returned if this is not a source member.

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 or if the date of remote non-iSeries 400 or non-System/38 files are retrieved.

CRTDATE

Specifies the name of a 13-character CL variable used to retrieve the member creation century, date, and time. 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.

EXPDATE

Specifies the name of a 7-character CL variable used to retrieve the member expiration century, date, and time. 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.

TEXT

Specifies the name of a 50-character CL variable used to retrieve the text description of the file member. More information on this parameter is in Commonly used parameters.

NBRCURRCD

Specifies the name of a 10-position decimal CL variable used to retrieve the current number of nondeleted records in the member. 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.

NBRDLTRCD

Specifies the name of a 10-position decimal CL variable used to retrieve the current number of deleted records in this member. Zero (0) is returned for keyed logical files. For nonkeyed logical files, the number of nondeleted records in the based-on physical file member is returned.

SHARE

Specifies whether the open data path (ODP) for the member description is shared with other programs in the routing step. When an ODP is shared, the programs accessing the file share facilities such as the file status and the buffer.

More information on shared database files is in the Database Programming topic in the Information Center.

DTASPCSIZ

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

ACCPTHSIZ

Specifies the name of a 12-position decimal CL variable used to retrieve the access path size (in bytes) for this member. Zero (0) is returned if the member is nonkeyed. Remote non-iSeries 400 and non-System 38 files return a value of zero (0).

CHGDATE

Specifies the name of a 13-character CL variable used to retrieve the member change century, date, and time. 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.

SAVDATE

Specifies the name of a 13-character CL variable used to retrieve the member save century, date, and time. 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-iSeries 400 and non-System 38 files return blanks.

RSTDATE

Specifies the name of a 13-character CL variable used to retrieve the member restore century, date, and time. 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.

NBRDTAMBRS

Specifies the name of a 2-position decimal CL variable used to retrieve the number of data members for this logical member. If the member is a physical member, zero (0) is returned.

USEDATE

Specifies the name of a 7-character CL variable that is used to retrieve the date the object was used last. The date will be returned in the form CYYMMDD where C=Century (0=1940 through 1999 and 1=2000 through 2039), Y=Year, M=Month, and D=Day. If the object does not have a last-used date, blanks will be returned.

USECOUNT

Specifies the name of a 5 position decimal CL variable used to return the number of days the object has been used. If the object does not have a last used date, 0 will be returned.

RESETDATE

Specifies the name of a 7-character CL variable that is used to return the date the days-used count was last reset to 0. The date will be returned in the form 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 will be returned.

Examples for RTVMBRD

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)

This command is run:

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

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.

This command is run next:

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

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

• The next members 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, the user can do a Generic* (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 for RTVMBRD

*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.