There's something that never occurred to me until a colleague of mine recently had the following situation come up: Suppose a job is added to the job scheduler to run at the end of the day. It's set to launch automatically at 23:45:00 each Monday evening. The job is submitted, but other jobs are in the job queue, so the job doesn't actually start running until after midnight (which is Tuesday morning). The date, therefore, is Tuesday's date, not Monday's. Since there is no way to ensure that the job runs on Monday, my colleague asked, "Is there a way to retrieve the date the job was submitted to the job queue?"

The first thing I said was, "I never thought of that before." But I figured there had to be a way to retrieve the submitted-on date, so I went to the IBM manuals to search the QUSRJOBI (Retrieve Job Information) API to see if it contained the submitted-on date.

It turns out that the API returns the date submitted and the submitter's job name, number, and message queue. All you need to do is specify format JOBI0300 when calling QUSRJOBI. Format JOBI0300 returns job queue and output queue information, as well as information about the submitter's job. Format JOBI0400 may also be used to retrieve the submitter's job name, but it doesn't contain the submitted-on date, so JOBI0300 is the format we need.

The structure of the data returned by QUSRJOBI for format JOBI0300 is located in library QSYSINC in the QRPGLESRC file in member QUSRJOBI. A data structure named QOBJI030000 is included in the normal poor-quality IBM format--meaning that the names are obscure, from-to column notation is used, and the data structure is not qualified.

In the QOBJI030000 data structure, the subfield named QUSJSOD contains the job's submitted-on date. This field and the submitter's information subfields are populated only if the job was submitted to a job queue--that is, a batch job. Therefore, if you test the example in this article within your interactive job, no data will be returned.

The job's submitted-on date is returned in what is described as "system timestamp format." This is an obscure 8-byte format that is not directly interchangeable with traditional date, time, and timestamp data types. Unfortunately, I couldn't find a diagram to illustrate system timestamp format.

To convert system timestamp format into a readable format, you can use the QWCCVTDT API. The QWCCVTDT API refers to system timestamp format as *DTS format and allows you to convert a value in any of the supported date formats into any other date format.

So we call QUSRJOBI to retrieve the submitter's information and then call QWCCVTDT to convert the system timestamp value to YYYYMMDD format. The results are the RTVSBMJOBA command.

Retrieve Submitted Job Attributes (RTVSBMJOBA)

The RTVSBMJOBA command retrieves the job name, user profile, and job number of the job that submitted the batch job. In addition, the message queue and message queue library names are returned, as well as the date the job was placed on the job queue.

Since this CL command returns data into CL variables, it can be used only from within a compiled CL program (CLP or ILE CL). When compiling the command, be sure to specify the ALLOW(*IPGM *BPGM) parameter. (I wish IBM would put that stuff into the source so we wouldn't have to remember it each time we compile). If you intend to use this CL command within a CL *MODULE, then you need to specify ALLOW(*IPGM *BPGM *IMOD *BMOD). You'd think that after more than 22 years, IBM would have figured out a way to imply ALLOW(*IPGM *BPGM) if a parameter in the command accepts a return value. I wrote something to do this way back in 1986 by embedding the CRTCMD command string into the CMD definition source and preprocessing it.

The source code for the RTVSBMJOBA command is available on the RPGIV.com Web site. Click on the "Latest RPG Developer Example Source" link.

To compile RTVSBMJOBA, use the following command:

The command processing program (the program that is run when the RTVSBMJOBA command is performed) is also named RTVSBMJOBA. It is an RPG IV program, and although it could have been written in RPG III, I see no reason to continue to write code in a language that was replaced more than a decade ago.

The source code for RTVSBMJOBA is also available on the RPGIV.com Web site. Again, click on the "Latest RPG Developer Example Source" link.

As mentioned, the QUSRJOBI API is used to retrieve the submitter's information. The prototype for QUSRJOBI is as follows:

See the RPG IV source for RTVSBMJOBA for an example of how to call QUSRJOBI.

The prototype for QWCCVTDT is as follows:

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.