IBM i RTVJOBA Command Reference

RTVJOBA (Retrieve Job Attributes) copies attributes of the job it runs in into CL variables. A CL program uses it to read the current job’s identity, library lists, output routing, date and time formats, or character set. The program can then use those values to make a decision, or pass them along to another command.

This page is a parameter lookup for CL authoring. The single attribute most programs reach for RTVJOBA to save is the user library list. See IBM i Library List Commands Reference for saving and restoring USRLIBL around a temporary library-list change. This page does not repeat that material; it covers the rest of what RTVJOBA retrieves.

Syntax

RTVJOBA JOB(&VAR) USER(&VAR) NBR(&VAR)
        SYSLIBL(&VAR) USRLIBL(&VAR)
        CURLIB(&VAR)
        OUTQ(&VAR) OUTQLIB(&VAR) PRTDEV(&VAR)
        DATFMT(&VAR) DATSEP(&VAR) TIMSEP(&VAR)
        CCSID(&VAR)

Every parameter is output-only: you pass a CL variable, and RTVJOBA fills it in. Request only the attributes you actually need; unused parameters can be omitted entirely rather than listed with a placeholder.

Parameters covered here

JOB, USER and NBR identify the job the program is running in; RTVJOBA does not take an input job name to inspect a different job. For that you need WRKJOB or the job-related QSYS2 services, not RTVJOBA.

SYSLIBL and USRLIBL are separate from CURLIB: the current library is its own job attribute, not part of either list. The library-list article above covers inspecting and restoring USRLIBL; this page only notes that RTVJOBA is the CL command that reads it.

This table deliberately covers only the attributes a typical CL program retrieves most often. RTVJOBA documents roughly 65 parameters in total, including subsystem, accounting code, time zone, device-recovery and sign-off handling attributes not listed above; this page is a lookup for the common subset, not a complete parameter reference. Check IBM’s CL Reference or F4 prompting for a parameter not covered here rather than assuming it does not exist.

Example: retrieving attributes for conditional logic

PGM
DCL VAR(&USER)   TYPE(*CHAR) LEN(10)
DCL VAR(&DATFMT) TYPE(*CHAR) LEN(4)
DCL VAR(&OUTQ)     TYPE(*CHAR) LEN(10)
DCL VAR(&OUTQLIB)  TYPE(*CHAR) LEN(10)

MONMSG MSGID(CPF0000)

RTVJOBA USER(&USER) DATFMT(&DATFMT) OUTQ(&OUTQ) OUTQLIB(&OUTQLIB)

IF COND(&USER *EQ 'QPGMR') THEN(DO)
  SNDPGMMSG MSG('Running under QPGMR - review before continuing')
ENDDO

IF COND(&DATFMT *NE '*YMD') THEN(DO)
  SNDPGMMSG MSG('Job date format is not *YMD; date parsing may differ')
ENDDO

ENDPGM

What the example does

A MONMSG MSGID(CPF0000) placed immediately after the DCL statements, before any other command, is a program-level MONMSG: IBM’s documentation on MONMSG states that one or more MONMSG commands placed at the beginning of a program, immediately following the declare commands (or the PGM command if there are no declares), “monitor messages sent by all of the commands in the program,” as opposed to a command-level MONMSG elsewhere in the program, which “applies only to the immediately preceding command.” Because no EXEC parameter is coded here, a matching message is simply ignored and the program continues — IBM’s documentation states that when a command is not coded for EXEC, “monitored messages are ignored.” (If EXEC were coded on a program-level MONMSG, IBM’s documentation requires it to be GOTO to a label; it cannot run an arbitrary command the way a command-level MONMSG‘s EXEC can.)

The program then declares four CL variables sized to match what each parameter returns, then calls RTVJOBA once to fill all four in a single statement.

It checks &USER to flag an unexpected run-as profile. It checks &DATFMT against *YMD because downstream logic that parses dates needs to know whether the job uses year-month-day order or one of the other three documented job date formats (*MDY, *DMY, *JUL). *ISO is not a value RTVJOBA returns for the job’s DATFMT attribute — IBM’s CHGJOB documentation, which sets this same job attribute, lists only *YMD, *MDY, *DMY and *JUL as the settable date-format values (plus *SAME/*SYSVAL, which are CHGJOB inputs, not values RTVJOBA returns); an earlier draft of this example incorrectly compared &DATFMT against *ISO, a format used for SQL/data-type date columns, not the job attribute. It retrieves &OUTQ and &OUTQLIB so a later SBMJOB or print-related command can route output to the same queue the current job uses.

One RTVJOBA call gathers everything the rest of the program needs, instead of retrieving the attributes separately.

This example is documentation-checked, not compiler-tested or runtime-tested: the parameter names, keywords and variable lengths have been checked against IBM’s CL command documentation, but the program has not been compiled or run on an IBM i system as part of producing this page.

Required authorities

RTVJOBA reads attributes of the job it runs in and requires no special object authority beyond normal job execution — there is no target object to secure, since it does not accept a parameter to select a different job.

Common mistakes

• Variable type or length mismatch. RTVJOBA fails if the receiving variable’s type or length does not match what the parameter returns. USRLIBL in particular needs *CHAR LEN(2750) to hold the full user library list (250 entries at 11 characters each); a shorter variable truncates or errors depending on the specific parameter.

• Treating OUTQ as a single qualified field. RTVJOBA returns the output queue name and its library as two separate parameters — OUTQ (10 characters) and OUTQLIB (10 characters) — not one 20-character qualified value. Retrieve both if the program needs to reference the queue elsewhere.

• Retrieving attributes the program never uses. Every unused parameter on a RTVJOBA call is still retrieved. Listing CCSID, PRTDEV or other attributes “just in case” costs nothing dramatic on its own. But repeating an over-broad RTVJOBA call inside a loop, instead of calling it once outside the loop, adds avoidable overhead. Retrieve once, store the values, and reuse them.

• Assuming RTVJOBA reflects a change made later in the same program. If the program itself changes an attribute, for example with CHGLIBL or CHGCURLIB, values already retrieved into variables are stale. Re-run RTVJOBA after the change if the program needs the current value again.

• Confusing CURLIB with the first entry in USRLIBL. They are different attributes. A program that only checks USRLIBL can miss the current library entirely.

RTVJOBA vs. RTVSYSVAL

RTVJOBA and RTVSYSVAL are easy to reach for interchangeably, but they read from different places. RTVJOBA reports the current job’s own attributes, which can be overridden per job (a user’s own DATFMT, a job’s own CURLIB). RTVSYSVAL reports system-wide values that apply unless something more specific overrides them. When a program needs to know what a job is actually using right now, RTVJOBA is the correct command; RTVSYSVAL answers a different question about the system’s shipped or configured default.

Related reference

• IBM i Library List Commands Reference — DSPLIBL, ADDLIBLE, RMVLIBLE, CHGLIBL, EDTLIBL and CHGCURLIB, including the full save-and-restore pattern for USRLIBL using RTVJOBA and QCMDEXC. This page does not repeat that pattern.

Summary

• RTVJOBA retrieves attributes of the job it runs in, into CL variables you declare first.
• Match each variable’s type and length to the attribute it receives; USRLIBL needs the full 2750-character length.
• Retrieve an attribute once and reuse the variable rather than calling RTVJOBA repeatedly for values that have not changed.
• For user library-list save-and-restore mechanics, use the library list commands reference instead of duplicating that logic here.