List processing Directory

Directory .ZIP

	objects?

These source modules make up a set of simple commands that help in processing 'lists' of objects, files or members in CL. These are given here only because someone asked for them, not because they're particularly good examples of anything.

The source modules are for a set of commands and the associated command-processing programs. The 'build (BLD*)' commands create 'lists' by running the DSPFD TYPE(*BASATR), DSPFD TYPE(*MBR) and DSPOBJD commands with OUTPUT(*OUTFILE). These outfiles form the lists that are input for the 'process (PRC*)' commands.

The process commands each accept a command that gets executed against each item on the list. You are allowed to use a few special substitution variables when entering the command, similar to PDM user-defined functions.

The currently available ones are:

@@O

List-item object name

@@F

List-item file name

@@M

List-item member name

@@L

List-item library name

@@T

List-item object type -- only allowed for EXCOBJLST

The object type substitution variable (@@T) is a problem. You can't enter a command such as DSPOBJD OBJTYPE(@@T) because the command prompter rejects <@@T> as an invalid type. I got around that by... cheating.

There is an additional command shell named EXCOBJLST for the PRCOBJLST CL program. The difference is in how the CMD() parameter is defined. With PRCOBJLST, this parameter allows you to enter a command and use the prompter, similar to the SBMJOB CMD() parameter. But with EXCOBJLST, that parameter is a simple character string, similar to the SBMJOB RQSDTA() parameter. (Hmmm... why not just put both parameters on the PRCOBJ command... similar to SBMJOB?)

I generally prompt PRCOBJLST, type in whatever command I want but use a temporary value for OBJTYPE(), e.g., *FILE, and then cancel prompting with <F12>. I can then use <F9> to retrieve the command, type over the 'PRC' in the command name with 'EXC', insert quotes around the command string, type '@@T' over the bogus OBJTYPE() value and press <Enter>.

I looked at a few alternative ways to handle that, but the effort never seemed worthwhile. If you don't need to use [@@T], the PRCOBJLST command can be used directly.

Usage

One sequence I use to run these commands is first to execute BLDxLST, then to use STRSQL (or my RUNSQL command) to DELETE items I don't want included in the list, and finally to execute PRCxLST over the remaining list items. If you have your own RUNSQL command or use STRQMQRY or RUNSQLSTM, you can combine the three steps in a CL program to manipulate just about everything. 

Another example sequence is to begin with BLDFLST, then use the file list as input to PRCFLST in order to process the BLDMBRLST LSTOPT(*N *ADD) command, i.e., nesting of BLDxLST commands. The resulting member list has a record for every member of every file in the file list. With SQL between the BLDFLST and PRCFLST, you can select only data files or source files or any other possibility.

Control data areas

Three data areas may be used to control some defaults. When an outfile is created, you have to give it a name. I wanted the files to have a default name so you wouldn't have to enter it every time, but I couldn't settle on the right name. No matter what I thought, it was possible to step on a name already in use at whatever site the commands ran at.

So, I externalized the names of the three types of list files by relying on data areas. Seemed like a great solution at the time. (Problem: How to avoid stepping on the names of existing data areas?)

The three data area names are:

VLDFTF

System-wide default 'list files' name

VLDFTMBR

System-wide default 'list members' name

VLDFTOBJ

System-wide default 'list objects' name

These are all *CHAR(10) data areas. I usually put these into QGPL and give them values of #$LSTF, #$LSTMBR and #$LSTOBJ. Because references to these are not qualified, they can be anywhere in your library list. If necessary, you can have different versions in different libraries, possibly different ones for different users or applications.

Whatever way you use them, they aren't worth much unless you need them; and then they can be invaluable.

General comments

I originally put these together quite a few (17? 18?) years ago. Little has been done since then to improve them because they've provided all the basic function I've needed. There isn't much documentation because I didn't need any. I use them only for myself and I always know what they're doing and how they work. I figure a lot of others will figure them out quickly enough. They just aren't complex enough to matter -- yet.

However, by posting them here, I suspect I'm forcing myself to do something with them. I'll have to add comments and finally get around to resolving the one or two odd behaviors that I've gotten used to.

Recently, I did do some general cleanup. The PRCxLST CLs now are required to be ILE CL because I wanted to handle the substitution/replacement differently. The repetitive statements that scanned the command string and did the replacements have all been replaced by a procedure call that does the work.

Also, I reduced the use of custom commands. The CLSCAN command is still used, but it can be replaced by coding to the QCLSCAN API if desired. And the RTNLEN command is still used in a few places -- other uses of it have been replaced by a trivial technique of using RTVMSG to act as a function to return the significant length of a string by resolving message ID CPF9897 with the string as MSGDTA(). That technique can't be used when the string to measure is more than 512 bytes, and the command strings are defined to allow expansion up to 6000 bytes. Since the source as supplied, anyone may limit the command strings as they wish. I only wanted to show the RTVMSG technique in case someone else thought it was useful.

Until more is done, you're stuck with WYSIWYG.

Please read the @GENERAL DISCLAIMER document for any items you should be aware of if you download any of these items.

---

CLPs

BLDFLST -- Build a File List:

This program creates a DSPFD TYPE(*BASATR) outfile. DSPFD TYPE(*BASATR) command itself can be used directly instead, but BLDFLST gives consistency; no need to remember from one use to the next what TYPE() to specify or other parameters. The 'list' parameter handling matches with PRCFLST better in concept.

BLDMBRLST -- Build a Member List:

This program creates a DSPFD TYPE(*MBR) outfile.

BLDOBJLST -- Build an Object List:

This program creates a DSPOBJD outfile.

PRCFLST -- Process a File List:

This program RCVFs records from a file built by BLDFLST (or DSPFD TYPE(*BASATR)) and executes a user-specified command for each record. The command string may have special substitution values -- @@F and @@L for file and library -- that will be replaced by the values from the list.

PRCMBRLST -- Process a Member List:

This program RCVFs records from a file built by BLDMBRLST (or DSPFD TYPE(*MBR)) and executes a user-specified command for each record.The command string may have special substitution values -- @@F, @@L and @@M for file, library and member -- that will be replaced by the values from the list.

PRCOBJLST -- Process an Object List:

This program RCVFs records from a file built by BLDOBJLST (or DSPOBJD) and executes a user-specified command for each record.The command string may have special substitution values -- @@O, @@L and @@T for object and library and object type -- that will be replaced by the values from the list.

RPLSST -- Replace a substring:

This procedure accepts a string plus substitution and replacement substrings. Every occurrence of the substitution substring in the main string is replaced by the replacement substring.

---

CMDs

BLDFLST -- Build a File List:

The command definition object source for BLDFLST encapsulates the BLDFLST CLP. The command defines the FILE(), LSTOPT(), LSTF() and FILEATR() parameters to determine how the list is to be built. These generally correspond to the FILE(), OUTMBR(), OUTFILE() and FILEATR() parameters of DSPFD when OUTPUT(*OUTFILE) is specified.

BLDMBRLST -- Build a Member List:

The command definition object source for BLDMBRLST encapsulates the BLDMBRLST CLP. The command defines the FILE(), LSTOPT(), LSTF() and FILEATR() parameters to determine how the list is to be built. These generally correspond to the FILE(), OUTMBR(), OUTFILE() and FILEATR() parameters of DSPFD when TYPE(*MBR) and OUTPUT(*OUTFILE) is specified.

BLDOBJLST -- Build an Object List:

The command definition object source for BLDOBJLST encapsulates the BLDOBJLST CLP. The command defines the OBJ(), LSTOPT(), LSTF() and OBJTYP() parameters to determine how the list is to be built. These generally correspond to the OBJ(), OUTMBR(), OUTFILE() and OBJTYPE() parameters of DSPOBJD when OUTPUT(*OUTFILE) is specified.

EXCOBJLST -- Execute an Object List:

The command definition object source for EXCOBJLST encapsulates the PRCOBJLST CLP. This is a variant of PRCOBJLST that does not allow prompting for the user-specified command parameter. This variant can be used when support for OBJTYP(@@T) is needed.

PRCFLST -- Process a File List:

The command definition object source for PRCFLST encapsulates the PRCFLST CLP. Full command prompting is allowed for the CMD() parameter.

PRCMBRLST -- Process a Member List:

The command definition object source for PRCMBRLST encapsulates the PRCMBRLST CLP. Full command prompting is allowed for the CMD() parameter.

PRCOBJLST -- Process an Object List:

The command definition object source for PRCOBJLST encapsulates the PRCOBJLST CLP. Full command prompting is allowed for the CMD() parameter.