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 Up to Top