RTVOBJD Command Reference

This page is a lookup for RTVOBJD: what it returns, into which variables, the required OBJTYPE values, and the authority it needs. For interactive object inspection, see the IBM i Object and Library Commands Reference. For the command index, see the IBM i Command Reference.

RTVOBJD only runs inside a compiled CL program (*BPGM/*IPGM) or a REXX procedure (*BREXX/*IREXX); it has no interactive prompt output of its own, unlike DSPOBJD, which this page does not duplicate.

Purpose

Retrieves the description of a single object into CL program or REXX variables, so a program can branch on an object’s attributes, dates, size, journaling status or source information without parsing DSPOBJD output.

Input parameters

ASPDEV must be * when OBJ‘s library is specified as *CURLIB or *LIBL.

Required OBJTYPE values

OBJTYPE has no default and must be one of a fixed list. The most common for an RPG/CL shop are:

*FILE   *PGM    *SRVPGM  *MODULE  *DTAARA  *DTAQ   *JOBD
*JOBQ   *LIB    *MSGQ    *MSGF    *OUTQ    *JRN    *JRNRCV
*USRPRF *SBSD   *BNDDIR  *CMD     *AUTL

The full list also includes *ALRTBL, *CFGL, *CHTFMT, *CLD, *CLS, *CNNL, *COSD, *CRG, *CRQD, *CSI, *CSPMAP, *CSPTBL, *CTLD, *DEVD, *DOC, *DTADCT, *EDTD, *EXITRG, *FCT, *FLR, *FNTRSC, *FNTTBL, *FORMDF, *FTR, *GSS, *IGCDCT, *IGCSRT, *IGCTBL, *IMGCLG, *IPXD, *JOBSCD, *LIND, *LOCALE, *MEDDFN, *MENU, *MGTCOL, *M36, *M36CFG, *NODGRP, *NODL, *NTBD, *NWID, *NWSCFG, *NWSD, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PNLGRP, *PRDAVL, *PRDDFN, *PRDLOD, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *RCT, *SCHIDX, *SPADCT, *SQLPKG, *SQLUDT, *SQLXSR, *SSND, *SVRSTG, *S36, *TBL, *TIMZON, *USRIDX, *USRQ, *USRSPC, *VLDL, *WSCST.

A minimal CL example

PGM
DCL VAR(&OBJLIB)   TYPE(*CHAR) LEN(10)
DCL VAR(&CRTDATE)  TYPE(*CHAR) LEN(13)
DCL VAR(&TEXT)     TYPE(*CHAR) LEN(50)

RTVOBJD    OBJ(MYLIB/ORDERPGM) OBJTYPE(*PGM) +
           RTNLIB(&OBJLIB) CRTDATE(&CRTDATE) TEXT(&TEXT)

SNDPGMMSG  MSG('Object library:' *BCAT &OBJLIB *BCAT +
           'created' *BCAT &CRTDATE)
ENDPGM

Each return value is declared as its own CL variable, sized to the type the parameter documents (character or zoned decimal); the command sets them by reference, it does not return a single structure.

Frequently used return parameters

The full return list also covers ASP placement, save/restore history, compression status, digital signatures and usage tracking. Declare only the variables you actually need, in the order the command documents them.

ASP, storage and digital-signature return parameters

Beyond the frequently used set above, RTVOBJD can return several other groups of fields. These are less commonly needed, but are useful when a program must report on storage placement, save history or signing status without a separate command.

Each of these is declared the same way as the frequently used parameters: as its own CL variable, with the length and type the command documents for that field.

Authority requirements

• *EXECUTE authority on the library containing the object.
• Some authority other than *EXCLUDE on the object itself; for a *FILE object, *OBJOPR is required.
• *ALLOBJ or *AUDIT special authority to retrieve a meaningful OBJAUD value; without it, OBJAUD returns *NOTAVL.

Common escape messages

A CPF9801 or CPF9810 from RTVOBJD is diagnosed the same way as from any other object command: verify the qualified name, the library list if *LIBL was used, and that the object was not deleted or renamed. See the IBM i Job Log and CPF Messages Reference for reading the surrounding job log.

Common mistakes

• Omitting OBJTYPE. It is required with no default; a program that only sometimes supplies it will fail to compile, not fail at run time.
• Declaring a return variable with the wrong length or type, which truncates or misreads the value silently instead of raising an error.
• Using RTVOBJD interactively from a command line expecting to see output. It only sets variables inside a program or REXX procedure; use DSPOBJD for an interactive display.
• Specifying ASPDEV with a device/search-type pair while OBJ‘s library is *CURLIB or *LIBL, which is not a valid combination.
• Reading OBJAUD and treating *NOTAVL as “auditing is off” rather than “the caller lacks *ALLOBJ/*AUDIT to see the real value.”

FAQ

Can RTVOBJD be run directly on a command line?

No. It only operates inside a compiled CL program or REXX procedure, where it sets CL variables by reference. Use DSPOBJD for interactive, on-screen object information.

What authority does RTVOBJD need?

*EXECUTE on the library, and any authority other than *EXCLUDE on the object (*OBJOPR for files). *ALLOBJ or *AUDIT special authority is additionally required to see a real OBJAUD value instead of *NOTAVL.

Does RTVOBJD search the library list?

Only if OBJ‘s library is given as *LIBL; otherwise it looks in the named library or *CURLIB exactly as specified.

Related references

• IBM i Object and Library Commands Reference: WRKOBJ, DSPOBJD, CHKOBJ and the interactive object-inspection commands.
• IBM i Library List Commands Reference: DSPLIBL, ADDLIBLE and related library-list commands.
• IBM i Command Reference: the full command index by task.

Summary

• RTVOBJD retrieves an object’s description into CL or REXX variables. It only runs inside a program or procedure, not from a command line.
• OBJTYPE is required with no default, chosen from a fixed list of valid object types.
• It needs *EXECUTE on the library and non-*EXCLUDE authority on the object (*OBJOPR for files); *ALLOBJ/*AUDIT is additionally needed for a real OBJAUD value.

Verification

• Parameters, return variables, required OBJTYPE values, authority requirements and escape messages checked against IBM’s CL command reference for IBM i 7.5, Retrieve Object Description (RTVOBJD) (https://www.ibm.com/docs/en/ssw_ibm_i_75/cl/rtvobjd.htm).
• The worked CL example is a documentation-derived illustration only; not compiled or run on PUB400 or any other system.