TAA Tools

 SCNVAR      SCAN A VARIABLE                            TAACLPG

 The SCNVAR  command scans a  CL variable for  a pattern.   The function
 provides a  command interface to  the QCLSCAN function  provided by the
 system.   Two commands  are provided.   SCNVAR allows a  variable to be
 scanned of up to 999 bytes.   SCNVAR2 allows up to 5000 bytes  and uses
 an RPGLE program to perform the scan.

 To  scan a  20  byte variable  &NAME  for the  letters  ABC, you  would
 specify:

       SCNVAR     RESULT(&RESULT) STRING(&NAME) STRLEN(20) +
                    PATTERN(ABC) PATTERNLEN(3)
       IF         (&RESULT *GT 0) DO /* Pattern was found */
                     .
                     .

 If  the &RESULT variable  is greater  than zero, it  indicates that the
 pattern was found  and the first  location within the  string where  it
 was found.

 Examples
 --------

 1.           SCNVAR  RESULT(&RESULT) STRING('Now is the time')
                        STRINGLEN(15) PATTERN('the')
                        PATTERNLEN(3) TRIM(*NO)

                          &RESULT = 8

 2.           SCNVAR  RESULT(&RESULT) STRING('Now is the time')
                        STRINGLEN(15) PATTERN('the')
                        PATTERNLEN(4) TRIM(*NO)

                          &RESULT = 8
                             Since the both the string and the
                               pattern have 'the', a match occurs

 3.           SCNVAR  RESULT(&RESULT) STRING('Now is the time')
                        STRINGLEN(15) PATTERN('the')
                        PATTERNLEN(5) TRIM(*NO)

                          &RESULT = 0
                             Since the string has 'the t..'
                               a match does not occur

 4.           DCL     &PATTERN *CHAR LEN(100) VALUE('the')
               .
              SCNVAR  RESULT(&RESULT) STRING('Now is the time')
                        STRINGLEN(15) PATTERN(&PATTERN) +

                        PATTERNLEN(100) TRIM(*YES)

                          &RESULT = 8
                             Since the pattern is trimmed to a
                               a value of 'the', a match occurs.
                               If TRIM(*NO) had been used, the
                               compare would be for 100 bytes and
                               no match would occur.

 Command interface
 -----------------

 The  command  interface  resembles  the  parameters  that  are  on  the
 QCLSCAN  program  provided  by the  system.    SCNVAR  uses QCLSCAN  to
 perform the  scan.   SCNVAR2 uses  an RPG  IV program  and runs  faster
 that QCLSCAN in some situations.

 SCNVAR Command parameters                             *CMD
 -------------------------

    RESULT        The result field to  be returned.  It must  be defined
                  as  LEN(3 0).    If the  scan is  not  successful, the
                  value  will be zero.   If the  scan is successful, the
                  value will  be the  first position  where the  pattern
                  matches.

    STRING        The  string to  be scanned.   It  must be  a character
                  value of up to 999 bytes.

    STRLEN        The  length of the string  to be scanned.   It must be
                  in a range of 1 - 999.

    STRPOS        The start position  in the string  to start the  scan.
                  The default is 1.

    PATTERN       The  pattern  to  be  scanned  for.    It  must  be  a
                  character value of up to 999 bytes.

                  If  a  variable is  used  for the  parameter,  you may
                  want to  trim  off  trailing blanks.    See  the  TRIM
                  parameter.

    PATTERNLEN    The length of the  pattern variable.  It must  be in a
                  range of 1 - 999.

    TRANSLATE     A  *YES/*NO  value that  defaults  to  *NO meaning  no
                  translation of the STRING value is performed.

                  *YES   may  be  specified   to  translate  the  STRING
                  variable  to all  upper  case  before  performing  the
                  scan.   Only the lower  case letters ('a' to  'z') are
                  translated.

    TRIM          A  *YES/*NO  value that  defaults to  *NO  meaning the
                  entire STRING value is scanned.

                  *YES may  be specified  when you  use  a variable  for
                  the  PATTERN  parameter  and  want  to  trim  off  the
                  trailing blanks before performing the scan.

    WILD          The  single character  that will act  as a  wild card.
                  A blank is  the default  and means that  no wild  card
                  character should  be used.   The wild  card may be  in
                  any position in the PATTERN except for position 1.

 SCNVAR2 Command parameters                            *CMD
 --------------------------

    RESULT        The result  field to be returned.   It must be defined
                  as  LEN(5  0).   If the  scan  is not  successful, the
                  value will be  zero.  If  the scan is successful,  the
                  value  will be  the first  position where  the pattern
                  matches.

    STRING        The  string to  be scanned.   It  must be  a character
                  value of up to 5,000 bytes.

    STRLEN        The length of the  string to be scanned.   It must  be
                  in a range of 1 - 5000.

    STRPOS        The start  position in the  string to start  the scan.
                  The default is 1.

    PATTERN       The  pattern  to  be  scanned  for.    It  must  be  a
                  character value of up to 999 bytes.

                  If a  variable  is used  for  the parameter,  you  may
                  want  to trim  off  trailing  blanks.   See  the  TRIM
                  parameter.

    PATTERNLEN    The length of the pattern variable.

    TRANSLATE     A  *YES/*NO  value that  defaults  to  *NO meaning  no
                  translation of the STRING value is performed.

                  *YES  may  be  specified to  to  translate  the STRING
                  variable  to all  upper  case  before  performing  the
                  scan.   Only the  lower case letters  ('a' o  'z') are
                  translated.

    TRIM          A  *YES/*NO  value that  defaults to  *NO  meaning the
                  entire STRING value is scanned.

                  *YES may  be specified  when you  use  a variable  for
                  the  PATTERN  parameter  and  want  to  trim  off  the
                  trailing blanks before performing the scan.

    WILD          The  single character  that will act  as a  wild card.
                  A blank is  the default  and means that  no wild  card
                  character should  be used.   The wild  card may be  in
                  any position in the PATTERN except for position 1.

    RCLACTGRP     Whether  to  reclaim  the  activation  group  created.
                  The  default is *YES to  reclaim the activation group.

                  *NO may  be specified  if you  are repeatedly  running
                  the SCNVAR2 command.

                  *ONLY  may  be  specified  to reclaim  the  activation
                  group  without performing  a scan.   This  is intended
                  if you have been using  *NO for repeated use and  then
                  no longer need the function.

 Considerations
 --------------

 QCLSCAN will  return negative  values for error  conditions such  as if
 the  pattern length  is less  than 1.   These  are turned  into CPF9898
 escape messages  with  specific  text to  help  identify  the  problem.
 SCNVAR2 emulates the same error conditions.

 Restrictions
 ------------

 The TRANSLATE(*YES) function only operates on a-z.

 The wild  card character  may be used  in any  position of  the pattern
 except position 1.

 Prerequisites
 -------------

 The following TAA Tools must be on your system:

       SNDESCINF     Send escape information
       SNDESCMSG     Send escape message

 Implementation
 --------------

 None, the tool is ready to use.

 Objects used by the tool
 ------------------------

    Object        Type       Attribute      Src member     Src file
    ------        -----      ---------      ----------     -----------

    SCNVAR        *CMD                      TAACLPG        QATTCMD
    SCNVAR2       *CMD                      TAACLPG2       QATTCMD
    TAACLPGC      *PGM          CLP         TAACLPGC       QATTCL
    TAACLPGC2     *PGM          CLP         TAACLPGC2      QATTCL
    TAACLPGR2     *PGM          RPGLE       TAACLPGR2      QATTRPG

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.