Today, we extend the USEDIRPGM command.

In last month's column, "Clearing, Rather than Deleting, an IFS File," we implemented a CLRSTMF command. Today, we will start to incorporate this command into the USEDIRPGM command that we created earlier in the year.

The USEDIRPGM command, most recently discussed in the article "Using Command Parameter Lists, Elements, and Conditional Prompting," currently provides the ability to display and/or remove IFS stream files that have not been accessed within a user-determined number of days. We will start by adding a clear stream file option, *CLR, to the USEDIRPGM command as shown below. The change, adding the value *CLR to the VALUES parameter defining the STMFOPTS keyword, is shown in bold.

             CMD        PROMPT(DIR0001)                               

             PARM       KWD(DIR) TYPE(*PNAME) LEN(1024) DFT(*CURDIR) +

                          SPCVAL((*CURDIR '.')) PROMPT(DIR0002)      

             PARM       KWD(STMFOPTS) TYPE(*CHAR) LEN(10) RSTD(*YES) +

                          DFT(*DSP) VALUES(*DSP *CLR *RMV) MIN(0) +  

                          MAX(2) PROMPT(DIR0005)                     

             PARM       KWD(DAYS) TYPE(*UINT4) DFT(3) PROMPT(DIR0003)

             PARM       KWD(SUBTREE) TYPE(*CHAR) LEN(10) RSTD(*YES) +

                          DFT(*ALL) VALUES(*ALL *NONE) PROMPT(DIR0004)

             PARM       KWD(SUBTREEIND) TYPE(INDENTVALS) +           

                          PMTCTL(SUBTREEALL) PROMPT(DIR0006)         

 INDENTVALS: ELEM       TYPE(*UINT2) DFT(*NONE) SPCVAL((*NONE 0)) +  

                          PROMPT(DIR0007)                            

             ELEM       TYPE(*UINT2) DFT(*NONE) SPCVAL((*NONE 0)) +  

                          PROMPT(DIR0008)                            

 SUBTREEALL: PMTCTL     CTL(SUBTREE) COND((*EQ *ALL))                

Though we now have three valid values defined for the STMFOPTS keyword, we will leave the MAX keyword value at two. This is done since allowing both remove (*RMV) and clear (*CLR) operations against the same stream file doesn't really make a lot of sense. If the command processing program (CPP) for the USEDIRPGM command implements *CLR prior to *RMV, then we'll just be wasting system resources by clearing the file of any data prior to removing the file anyway. If the CPP implements *RMV prior to *CLR, then we'll just be generating a lot of CPE3025 escape messages (No such path or directory) as the file to be cleared has already been removed from the system.

Leaving the MAX value at two however does not prevent the user from specifying both *RMV and *CLR when running the USEDIRPGM command (and not specifying *DSP). To prevent the user from using *RMV and *CLR at the same time, we have a few choices.

How to Avoid the *RMV + *CLR Problem

One approach is to detect this use of conflicting parameter values within the CPP and then send an escape message if it occurs. This will certainly prevent a user from adding *CLR to the end of the STMFOPTS list while forgetting to remove a pre-existing *RMV list entry (and accidently deleting files). But this type of runtime check can also lead to abnormal terminations of a job if, for instance, the USEDIRPGM command was running in a CL program submitted to batch.

A second choice might be to always have the CPP implement the last choice of conflicting parameter values that are specified within the STMFOPTS list. For example, the Create Bound RPG Program (CRTBNDRPG) command supports a list of values with the Compiler options keyword OPTION. If you specify two conflicting options, such as *GEN and *NOGEN to respectively generate and not generate a program object, then the last option specified in the list controls the actual generation of the program. This behavior would then be documented in the help text for the list parameter (see "Providing Help Text for a User Command" for how you can provide help text with your commands), but it may catch a few users off guard as we all know how often people really read help text. It would, however, at least protect the user from adding the *CLR option to the end of the STMFOPTS list and forgetting to remove a previous *RMV value within that list.

The best solution though, to my way of thinking anyway, is to attempt to prevent the use of conflicting parameter values when the command is being entered (as opposed to when the command is being run).

With some commands, though admittedly not USEDIRPGM as it's currently defined, you can use the Dependent Definition (DEP) command to prevent the use of conflicting parameters. By way of example, let's say that rather than having the STMFOPTS list parameter of the USEDIRPGM command we had defined the command to use separate (non-list) parameters, as shown below, for removing and clearing the stream file. Note that the XXX0001 and XXX0002 messages used to PROMPT these parameters do not exist, so don't try looking for them in message file USERMSGF. The message IDs are solely for demonstration purposes.

PARM       KWD(RMV) TYPE(*CHAR) LEN(10) RSTD(*YES) +   

             DFT(*NO) VALUES(*NO *YES) PROMPT(XXX0001) 

PARM       KWD(CLR) TYPE(*CHAR) LEN(10) RSTD(*YES) +   

             DFT(*NO) VALUES(*NO *YES) PROMPT(XXX0002)

With this type of command definition we could have used the following DEP command to prevent the user from entering the value *YES for both the RMV and the CLR parameters.

DEP        CTL(&RMV *EQ *YES) PARM((&CLR *NE *YES)) +

             MSGID(YYY0001)    

The DEP command basically says that if the RMV parameter value is equal to *YES, then the CLR parameter value must not be equal to *YES. If both RMV and CLR are specified as *YES, then message description YYY0001 (which we have also not created, so don't bother looking for it either) is to be sent. Message description YYY0001 might then be defined with text such as "*YES cannot be specified for both CLR and RMV." This message (YYY0001) would be sent when the user enters the following command within an SEU edit session using a source type of CLLE or on a command line.

USEDIRPGM … RMV(*YES) CLR(*YES) …

Note that this use of DEP is not "perfect" in terms of catching mutually exclusive parameter values when entering a command as part of a CL program.  The dependency check defined by the DEP command can, in some cases, be deferred to when the command is actually run. This deferred checking is possible because the RMV and CLR parameters are, by default, picking up the Allow variable names (ALWVAR) *YES attribute of the PARM command. So in the following CL program, the DEP check cannot be made by the system until the USEDIRPGM command is actually run and the current values for parameters RMV and CLR determined.

Pgm                                                    

Dcl        Var(&Yes) Type(*Char) Len(10) Value('*YES')

UseDirPgm  … Rmv(&Yes) Clr(&Yes) …              

EndPgm                                                

If the previous program were to run, the system would then send message YYY0001 as a diagnostic message. Message YYY0002 would be followed by the escape message CPF0001 (Error found on USEDIRPGM command). If you create your own user commands and have not previously looked at the DEP command, you really should. The documentation for the command can be found here, and the DEP command can provide a very valuable buffer between the CPP of the command and any user looking to run the command.

The DEP command unfortunately does have a limitation when it comes to checking for dependencies within a command list parameter—namely that, when using lists, the DEP command can check only the first value specified within a list, which is definitely a problem when we want to check for conflicts within the list. To provide dependency checks within a list parameter, when the command is being entered, we can use a validity-checking program.

Using a Validity-Checking Program

A command validity-checking program is passed the same parameters as a command CPP and provides additional parameter checking beyond that specified by the command definition statements (PARM, DEP, etc.) used when creating the command. The following validity-checking program, Use Dir Program Validation (USEDIRPGMV), demonstrates how we can detect conflicting parameter values for the USEDIRPGM STMFOPTS parameters.

Pgm        Parm(&Dir_In &NbrStmFOpt &Days &SubTree &SubTreeInd)  

Dcl        Var(&Dir_In)     Type(*Char) Len(1024)                

Dcl        Var(&NbrStmFOpt) Type(*Int)  Len(2)                   

Dcl        Var(&Days)       Type(*UInt)                          

Dcl        Var(&SubTree)    Type(*Char) Len(10)                  

Dcl        Var(&SubTreeInd) Type(*Char) Len(6)                   

Dcl        Var(&StmFOptPtr) Type(*Ptr)                           

Dcl        Var(&StmFOpt)    Type(*Char) Stg(*Based) +            

             Len(10) BasPtr(&StmFOptPtr)                         

Dcl        Var(&StmF_Rmv)   Type(*Lgl)                           

Dcl        Var(&StmF_Clr)   Type(*Lgl)                            

Dcl        Var(&Counter)    Type(*Int)  Len(2)                   

Dcl        Var(&Error)      Type(*Lgl)                           

ChgVar     Var(&StmFOptPtr) Value(%Addr(&NbrStmFOpt))            

ChgVar     Var(%ofs(&StmFOptPtr)) +                              

             Value(%ofs(&StmFOptPtr) + 2)                        

DoFor      Var(&Counter) From(1) To(&NbrStmFOpt)                 

           Select                                                

              When Cond(&StmFOpt = '*RMV') +                     

                   Then(ChgVar Var(&StmF_Rmv) Value('1'))        

              When Cond(&StmFOpt = '*CLR') +                     

                   Then(ChgVar Var(&StmF_Clr) Value('1'))        

           EndSelect                                             

           ChgVar Var(%ofs(&StmFOptPtr)) +                       

                    Value(%ofs(&StmFOptPtr) + 10)                

           EndDo                                                 

If         Cond((&StmF_Rmv) *And (&StmF_Clr)) Then(Do)           

           SndPgmMsg MsgID(CPD0006) MsgF(QCPFMSG) +            

             MsgDta('0000STMFOPTS values of *RMV and *CLR +    

                    are mutually exclusive. +                   

                    Select one or use neither') +              

             MsgType(*DIAG)                                    

           ChgVar Var(&Error) Value('1')                       

           EndDo                                                

If         Cond(&Error) Then( +                                

           SndPgmMsg MsgID(CPF0002) MsgF(QCPFMSG) +            

             MsgType(*Escape))                                  

EndPgm                                                         

Comparing the source for USEDIRPGMV and that of the CPP from last month's article, DIR3, you'll notice that quite a bit has been reused. The PGM and DCL statements related to the parameters being passed to the programs are the same, and I have selectively copied those parts of the DIR3 program that apply to our validation program—that is, the variables related to the processing of the STMFOPTS parameter. Two new variables, &StmF_Clr and &Error, shown above in bold, are the only two additions to this part of the program.

The DOFOR loop has been changed to no longer check for a STMFOPTS value of *DSP (as *DSP is not in conflict with either *RMV or *CLR) and to include a new check for the value of *CLR. When the special value *CLR is encountered, the logical variable &StmF_Clr is set to true ('1'). This addition will also need to be made to the DIR3 CPP in a future column in order to implement the CLRSTMF command.

Following the DOFOR is a check for both &StmF_Rmv and &StmF_Clr having been set to true. If this is the case, then conflicting STMFOPTS values of *RMV and *CLR have been specified and the diagnostic message CPD0006 is sent followed by the setting of variable &Error to true. We'll look more at the sending of validation diagnostic messages in a future column; for now, it's sufficient to know that the system provides message CPD0006 to allow a validity-checking program to send immediate error-related text to the user of a command. The message text must start with a four-byte character string of '0000' followed by the text to be seen by the user of the command. In our case, the message text to be displayed is "STMFOPTS values of *RMV and *CLR are mutually exclusive. Select one or use neither."

After all validations are done, USEDIRPGMV checks to see if any validation errors were found by testing the &Error variable. If &Error is true, then escape message CPF0002 is sent. The sending of this escape message is what informs the system that the previously sent diagnostic messages should be displayed to the user.

Note that the variable &Error is not actually necessary with our simple validation program. USEDIRPGMV could just as easily have sent the CPF0002 escape message immediately following the sending of the CPD0006 diagnostic message. A validation program can, however, send multiple diagnostic messages if multiple validation errors are found. So deferring the sending of CPF0002 to until all validation tests are done (of which there is only one in USEDIRPGMV) allows the user to see all validation errors rather than just the first error.

To create the validity-checking program USEDIRPGMV, you can use the command shown below.

CRTBNDCL PGM(USEDIRPGMV)

Assuming that you have added the *CLR option to the USEDIRPGM command source as shown at the start of this column, we're now ready to enable the USEDIRPGMV validity-checking program. To associate the USEDIRPGMV program with the USEDIRPGM command, as a validity checker, you would use the following command.

CRTCMD CMD(USEDIRPGM) PGM(DIR3) VLDCKR(USEDIRPGMV) PMTFILE(USERMSGF)        

With this change, running the command below will now result in the message "STMFOPTS values of *RMV and *CLR are mutually exclusive. Select one or use neither" thereby preventing the use of conflicting parameter values.

USEDIRPGM STMFOPTS(*CLR *RMV)

As with the DEP command discussed earlier, the use of variables within the STMFOPTS list (rather than constants) can cause deferral of this message to runtime.

Next month, we'll look at additional enhancements that can be made to our validity-checking program USEDIRPGMV.

More CL Questions?

Wondering how to accomplish a function in CL? Send your CL-related questions to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll try to answer your burning questions in future columns.

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7, V6R1

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

TechTip: Printing from a CL Program (the PRTLN Command)

TechTip: Date Arithmetic in CL Programs

TechTip: Entering Quotes in CL Variables — A Better Way?