Left String

Summary

The following are the RPG/LE fully free-form definitions and instructions needed for using the Left String service procedure. This service procedure simply allows the caller to extract the left-most n characters from a supplied string.

Justification

Some service procedures (minus their error checking) are so small that one might question creating a service procedure at all. They might feel that simply employing the stripped-down code directly in their program code is the best way to go (saving the necessity of calling a separate reoutine—with the additional overhead that such action would require).

Rule of Thumb

Sometimes, having a service procedure is simply a means of making code more self-documenting (i.e., easier for others to understand).

To wit... Which would you rather see in an RPG program—this?

if %subst(myLongString:1:4) = 'TEMP';
// do something
endif;

...or, this?

if GenUtl_LeftString(myLongString:4) = 'TEMP';
// do something
endif;

It is the opinion of many that the second form is more readable and is self-documenting. Hence, this service procedure.

Service Procedure

**free

//==============================================================================
// Return leftmost number of bytes -- optional padding on right.
//==============================================================================
dcl-pr GenUtl_LeftString          varchar(256) rtnparm;
  OrigString            varchar(65535) const;
  ByteCount             packed(3:0) const;
  PadChar               char(1)   const     options(*nopass);
end-pr;

//==============================================================================
// Return leftmost number of bytes -- optional padding on right.
//==============================================================================
dcl-proc GenUtl_LeftString        export;
  dcl-pi *n             varchar(256) rtnparm;
    OrigString          varchar(65535) const;
    ByteCount           packed(3:0) const;
    PadChar             char(1)   const     options(*nopass);
  end-pi;

  dcl-s StrLeng         like(ByteCount);
  dcl-s NewString       varchar(256) inz('');
  dcl-s PadString       char(256) inz(*blanks);

                                       // prevent errors
  StrLeng = ByteCount;                      // start with bytes requested
  if %parms < %parmnum(PadChar)             // if no padding and
  and StrLeng > %len(OrigString);           // request greater than string supplied
    StrLeng = %len(OrigString);             // take supplied string length
  endif;

  if StrLeng > *zero;                  // if something to return
    if StrLeng > %len(PadString);           // if more than what can return
      StrLeng = %len(PadString);            // set to max return length
    endif;
    if %parms < %parmnum(PadChar);          // if no padding
      NewString = %subst(OrigString: 1: StrLeng);
    else;                                   // else, with left padding
      NewString = %subst( OrigString + %xlate(' ': PadChar: PadString)
                        : 1: StrLeng );
    endif;
  endif;

  return NewString;                    // return the suffix string
end-proc;