Get to Know Some Powerful CL Commands

October 12, 2005 Bruce Guetzkow

I use CL (and now CLLE) procedures, rather than RPG, to do as much work as I can. It’s usually quicker to write CL than RPG because IBM has given us a great wealth of commands that perform all kinds of activities. Perhaps the most powerful commands are the RTV (Retrieve) commands, which retrieve information about objects (e.g., libraries and files) and non-objects (e.g., jobs and file members) alike. The Retrieve commands can only be used in CL, CLLE, and REXX procedures. Here’s a sampling of some of the data that you can retrieve.

RTVJOBA: Retrieve Job Attributes. This command retrieves information about the job in which it is running.

Here are some of my favorite values that can be retrieved:

• JOB, USER, NUMBER: These values uniquely identify the currently running job and can be used in other commands to get even more information.
• DATE: This is the job date, which is the date the job started, in the job-date format. Be aware that if your job begins before midnight and ends after, this date does not change.
• TYPE: If you need to do different processing based on whether the job is running interactively or in batch, this value can be tested. A ‘0’ indicates batch, ‘1’ is interactive.
• CURUSER: You can get the user profile that is running the job from this value.
• DATETIME: If you need more than just the job date, this value contains the date and time in the format YYYYMMDDHHNNSSXXXXXX which has the time down to microseconds. If you want the job date in YYYYMMDD format, you can extract the first eight characters directly from this value.

Here’s an example:

RTVJOBA JOB(&JOB)          
   USER(&USER)
   NBR(&NBR)
   DATE(&DATE)
   TYPE(&TYPE)
   CURUSER(&CURUSER)
   DATETIME(&DATETIME)

RTVOBJD: Retrieve Object Description. Specify an object and object type and you can find out lots of valuable information.

• RTNLIB: This value will tell you the library where the object resides. This is especially useful if you specify *LIBL for the object name and need to determine the library in which the object is stored.
• OBJATR: If the object specified is of certain types (e.g., a program or file), this value will identify the type of object (RPG, COBOL, PF, LF, etc.).
• TEXT: This is the text used to describe the object when it was created.
• OWNER: This value indicates the current owner of the object.
• CRTDATE: If you need to know the date and time that an object was created, this value contains that information in the format CYYMMDDHHMMSS.
• CRTUSER: As you might have guessed, this is the user that created the object.

The following example illustrates RTVOBJD.

RTVOBJD OBJ(your-library/your-object)
   OBJTYPE(*FILE)
   RTNLIB(&RTNLIB)
   OBJATR(&OBJATR)
   TEXT(&TEXT)
   OWNER(&OWNER)
   CRTDATE(&CRTDATE)
   CRTUSER(&CRTUSER)

RTVMBRD: Retrieve Member Description. Specify a file (and optionally a member) and you can find out more about that file.

• RTNLIB: This value will tell you the library where the file resides. Like RTVOBJD, this parameter is especially useful if you specify *LIBL for the file name and need to determine the library.
• RTNMBR: Just like the previous parameter, if you didn’t specify a member by name, this value will contain that member name.
• SRCTYPE: If the file is a source file, this value will contain the source type of the specified member.
• TEXT: This is the text used when the member was created.
• NBRCURRCD: This is perhaps my favorite parameter from all of the RTV commands. Many times I only need to perform actions if a file actually has data in it. This value contains the current number of data records in the file and member specified.

Here’s an example of the RTVMBRD command.

RTVMBRD FILE(your-library/your-file)
   MBR(*FIRSTMBR)
   RTNLIB(&RTNLIB)
   RTNMBR(&RTNMBR)
   SRCTYPE(&SRCTYPE)
   TEXT(&TEXT)
   NBRCURRCD(&NBRCURRCD)

The RTVMBRD command can be used in a loop to process all members of a multi-member file (physical or source). On the first execution of the command specify the MBR parameter as MBR(*FIRST *SAME) (to process in creation-date order) or MBR(*FIRSTMBR *SAME) (to process in alphabetical-name order). On subsequent executions of the command, specify MBR(&RTNMBR *NEXT). Be sure to specify parameter RTNMBR each time you execute the command so that you’ll have the value for the next iteration. Alternatively you can specify MBR(*LAST *SAME) or MBR(*LASTMBR *SAME) followed by MBR(&RTNMBR *PRV) to read through the members in reverse order.

The following short example illustrates how to process all members of a file in alphabetical order.

Pgm                                                                     
                                                                        
   Dcl  &Member    *char   10                                           
   Dcl  &Position  *char   10                                           
   Dcl  &CurUser   *char   10                                           
   Dcl  &RtnMbr    *char   10                                           
                                                                        
   RtvJobA   curuser(&CurUser)                                          
                                                                        
   /* process members in alphabetical order */
   ChgVar    &Member     *FIRSTMBR                                      
   ChgVar    &Position   *SAME                                          
                                                                        
NextMember:                                                             
   RtvMbrD   file(SomeFile) mbr(&Member &Position) rtnmbr(&RtnMbr)
   MonMsg    cpf3049 exec(goto EndOfFile)                               
                                                                        
   /* place commands to process &RtnMbr here */
   SndMsg msg('Processing member' *bcat &RtnMbr *tcat '.') +            
             tousr(&CurUser)                                            
                                                                        
   /* move to the next member */
   ChgVar    &Member     &RtnMbr
   ChgVar    &Position   *NEXT 
   goto NextMember             
                               
EndOfFile:                     
                               
EndPgm

It doesn’t get much easier than that. You can specify as few or as many parameters for the RTV commands as you like; just remember to define the return variables. When you prompt on the command the parameter descriptions tell you the variable sizes. If you want to see all of the RTV commands available, just go to a command line, key in RTV*, press Enter, explore, and enjoy!

Bruce Guetzkow has programmed on the AS/400 and iSeries since 1990, in manufacturing, distribution, and other industries. He is currently the IS director at United Credit Service in Elkhorn, Wisconsin. Click here to contact Bruce by e-mail.