<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>Scan for String Pattern (QCLSCAN) API</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- QCLSCA SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at --> <!-- RCHVMW2 on 5 Feb 1999 at 11:10:40 --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!--File Edited by Kersten Nov 2001 --> <!--End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="Top_Of_Page"></a> <!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <h2>Scan for String Pattern (QCLSCAN) API</h2> <div class="box" style="width: 80%;"> <br> Required Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">1</td> <td align="left" valign="top" width="50%">Character string</td> <td align="left" valign="top" width="20%">Input</td> <td align="left" valign="top" width="20%">Char(*)</td> </tr> <tr> <td align="center" valign="top">2</td> <td align="left" valign="top">Length of character string</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Packed(3,0)</td> </tr> <tr> <td align="center" valign="top">3</td> <td align="left" valign="top">Starting position</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Packed(3,0)</td> </tr> <tr> <td align="center" valign="top">4</td> <td align="left" valign="top">Character pattern</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(*)</td> </tr> <tr> <td align="center" valign="top">5</td> <td align="left" valign="top">Length of character pattern</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Packed(3,0)</td> </tr> <tr> <td align="center" valign="top">6</td> <td align="left" valign="top">Translate characters</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char((1)</td> </tr> <tr> <td align="center" valign="top">7</td> <td align="left" valign="top">Trim trailing blanks</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char((1)</td> </tr> <tr> <td align="center" valign="top">8</td> <td align="left" valign="top">Wildcard character</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(1)</td> </tr> <tr> <td align="center" valign="top">9</td> <td align="left" valign="top">Character string result</td> <td align="left" valign="top">Output</td> <td align="left" valign="top">Packed(3,0)</td> </tr> </table> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: No<br> <!-- iddvc RMBR --> <br> </div> <p>The Scan for String Pattern (QCLSCAN) API is used to scan a string of characters to see if the string contains a pattern. This function is similar to the scan function supported within source entry utility (SEU) and on the display presented by the Display Spooled File (DSPSPLF) command. In addition, the QCLSCAN API also allows you to specify a 1-byte character in the pattern that matches with any character in the string to be searched, and a start position, which allows you to search the same string more than once.</p> <p>A typical use of the QCLSCAN API is to allow the work station user to retrieve all records that contain a specified pattern. For example, if the database has records with book titles, the work station user may want to retrieve all those books with the pattern CHICAGO in the title. The work station user enters CHICAGO on the device display. The application program reads the database, calling the QCLSCAN API at least once for each record to test for the pattern. The application program only processes the records that pass the test for the pattern CHICAGO.</p> <p>Another alternative for this task is using the Open Query File (OPNQRYF) command. If you are searching an entire database member, the OPNQRYF command normally produces faster results. If you are searching a small subset of a member or the file is already open, QCLSCAN normally produces faster results.</p> <p>Scanning a field can require many lines of code in a high-level language and can cause a significant amount of overhead. Calling the QCLSCAN API and passing it a parameter list may be a simpler and faster way to do the scan.</p> <br> <!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. --> <!-- Instead, use the commented out coding below to indicate NONE. --> <h3>Authorities and Locks</h3> <!-- Use this if there are no authorities and locks. --> <p>None.</p> <br> <h3>Required Parameter Group</h3> <dl> <dt><strong>Character string</strong></dt> <dd>INPUT;CHAR(*) <p>A character field from 1 through 999 characters that contains the string to be scanned for the pattern.</p> </dd> <dt><strong>Length of character string</strong></dt> <dd>INPUT;PACKED(3,0) <p>The length of the string to be scanned. If this length is greater than the actual length of the string, unexpected results can occur.</p> </dd> <dt><strong>Starting position</strong></dt> <dd>INPUT;PACKED(3,0) <p>The position in the string where the scan is to start. The position must be greater than zero and not greater than the string length. Normally this value is 1. If the same string has multiple sets of patterns, this allows the string to remain the same while only the start position is varied to find the additional patterns.</p> </dd> <dt><strong>Character pattern</strong></dt> <dd>INPUT;CHAR(*) <p>The pattern being scanned for.</p> </dd> <dt><strong>Length of character pattern</strong></dt> <dd>INPUT;PACKED(3,0) <p>The length of the pattern. If this length is greater than the actual length of the pattern, unexpected results can occur.</p> </dd> <dt><strong>Translate characters</strong></dt> <dd>INPUT;CHAR(1) <p>A variable that indicates to translate lowercase characters in the specified character string to uppercase characters. If this field contains a 1, the program translates lowercase characters of the string to uppercase before the scan using the coded character set identifier (CCSID) for the current job. If the translation cannot be done using the CCSID for the job, *CCSID37 is used. This does not change the user's data. Note that if 1 is specified and the pattern contains lowercase characters, a match never occurs. If 1 is specified, and the data to be searched contains noncharacter data (for example, packed or binary), unexpected results can occur.</p> </dd> <dt><strong>Trim trailing blanks</strong></dt> <dd>INPUT;CHAR(1) <p>A fixed-length pattern field filled (left-justified) by a variable number of characters. If this variable contains a 1, trailing blanks are trimmed from the end of the pattern before the scan is started.</p> </dd> <dt><strong>Wildcard character</strong></dt> <dd>INPUT;CHAR(1) <p>A variable that you can specify in the pattern, in positions that should not be tested when scanning for a match. When this character appears in the pattern, any character in the data is considered a match. A value of blank indicates that all characters of the pattern take part in the scan. If the wildcard character is the first character in the pattern, an error will occur.</p> </dd> <dt><strong>Character string result</strong></dt> <dd>OUTPUT;PACKED(3,0) <p>The value is returned to the user program when the call completes.</p> <p>If the value returned is positive, the result is the position of the first character of the pattern in the string.</p> <p>If the value returned is zero, the pattern was not found.</p> <p>If the value returned is negative, one of the following errors occurred:</p> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td align="left" valign="top" nowrap><em>-1</em></td> <td align="left" valign="top">The pattern is longer than the string.</td> </tr> <tr> <td align="left" valign="top"><em>-2</em></td> <td align="left" valign="top">The pattern length is less than 1.</td> </tr> <tr> <td align="left" valign="top"><em>-3</em></td> <td align="left" valign="top">The first character of the pattern is a wildcard character.</td> </tr> <tr> <td align="left" valign="top"><em>-4</em></td> <td align="left" valign="top">The pattern is blank and the trim trailing blanks parameter value is 1.</td> </tr> <tr> <td align="left" valign="top"><em>-5</em></td> <td align="left" valign="top">The starting position within the string is not valid.</td> </tr> </table> </dd> </dl> <br> <hr> API existed prior to V3R1 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "pgm1.htm">Program and CL Command APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>