Powerful Stuff: Creating Commands with Variable-Length Parameters!

Published: November 29, 2006

by Ted Holt

The code associated with this article is available for download.

If you like to solve the same problems over and over, this tip is not for you. As far as I'm concerned, that sort of thing is for the birds. I prefer to solve a problem once and move on to other challenges. If you agree, then I have a good technique to share with you.

One very good way to solve a problem once--and only once--is by writing your own CL commands. After all, you don't write an RPG (COBOL, whatever HLL . . .) program when you need to make a copy of a file, do you? I suspect you use the Copy File (CPYF) command.

One of the greatest features of CL, as I see it, is the ability to create your own commands. This means you can add new CL commands to carry out tasks that IBM has not seen fit to address. If you've never written a command, then I encourage you to learn to do so. If you're already an expert at writing commands, then don't stop reading yet, in case you're not aware of what I'm about to share with you.

Let's get back to the issue of solving problems. In his article, Editing Numbers in CL, Cletus the Codeslinger pointed out a problem that appears to me to be worth solving once--that of suppressing leading zeros in order to make a number more easily read.

A zero-suppress command would need a parameter for the unedited value. The command-processing program could update that parameter, but I would prefer to pass the edited value back through another parameter, as the Convert Date (CVTDAT) command does. How long should those parameters be? Here's where today's tip comes in.

Why not allow the parameters to be of any reasonable length? Using variable-length parameters would allow you to pass variables of whatever sizes you happened to be working with at the time.

Here's the source code for a zero-suppression command, ZEROSUP.

/* ============================================*/ 
/* ZEROSUP -- Zero suppress a number           */ 
/* ============================================*/ 
/*  To create:                                 */ 
/*                                             */ 
/*     CRTCMD CMD(xxx/ZEROSUP)                 */ 
/*            PGM(*LIBL/ZEROSUP1)              */ 
/*            SRCFILE(xxx/QCMDSRC)             */ 
/*            SRCMBR(ZEROSUP)                  */ 
/*            ALLOW(*BMOD *BPGM *IMOD *IPGM)   */ 
/*                                             */ 
/* =========================================== */ 
                                            
CMD   PROMPT('Zero suppress a number')      
                                            
PARM  KWD(VALUE) TYPE(*CHAR) LEN(32) MIN(1) +     
        EXPR(*YES) VARY(*YES *INT2) PROMPT('Value') 
PARM  KWD(TOVAR) TYPE(*CHAR) LEN(1) RTNVAL(*YES) +
        MIN(1) VARY(*YES *INT2) +                 
        PROMPT('CL var for converted data')       
PARM  KWD(ZEROBAL) TYPE(*LGL) LEN(1) RSTD(*YES) + 
        DFT(*YES) SPCVAL((*YES '1') (*NO '0')) +  
        EXPR(*YES) PROMPT('Show a zero balance?')

Notice the VARY keyword on the first two parameter definitions. The *YES value indicates that the parameter can vary in length. The *INT2 value indicates that the parameter's length will be passed to the command-processing program in a two-byte prefix to the parameter value. That is, a four-byte value will be passed to the CPP in six bytes.

It is the CPP's job to determine how many bytes were passed for each parameter and to process values of those lengths. That is, if you pass a five-byte character value to the command, the CPP must not read more than five bytes. If you receive the zero-suppressed number into a 12-byte variable, the CPP must not modify any more than 12 bytes.

The CPP must look at the first two bytes of a variable-length parameter to determine the parameter's current length. The parameter's value will then be extracted beginning with byte three of the parameter. In the following code fragment, from the CPP ZEROSUP1, the programmer determines how many bytes were passed in through parameter &inFromVal. (My experience is that at least one character is always passed, even if that character is a blank.)

pgm parm(&inFromVal &ouToVar &inZeroBal)

  dcl &inFromVal *char 34 /* the value to be zero-suppressed       */
  dcl &ouToVar   *char 34 /* the receiving variable                */
  dcl &inZeroBal *lgl   1 /* 1=return one zero for a zero value    */
                          /* 0=return blanks for a zero value      */

/* How big is the input value (the value with leading zeros)? */
  chgvar  &ValueSize    %bin(&inFromVal 1 2)
  if (&ValueSize *gt 0) do
     chgvar  &WorkValue  %sst(&inFromVal 3 &ValueSize)
  enddo
  else do
     chgvar  &WorkValue  ' '
  enddo

Once you have learned to use variable-length parameters, you will be able to think of many ways to use them to develop flexible code. Here are a few ideas to get the creative energies in motion.

• a command that suppresses whichever leading character you name
• a command to reverse a string
• a command to fill a string by repeating a character string
• a command to return the length of a string without trailing blanks
• a command to insert editing characters
• a command to right-adjust a string
• a command to center a string
• a command to assign a value to a string only if that string is blank

RELATED STORIES

Editing Numbers in CL

Variable-Length Character Data