292 lines
9.3 KiB
HTML
292 lines
9.3 KiB
HTML
|
<!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>
|
||
|
|
|