213 lines
12 KiB
HTML
213 lines
12 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE html
|
||
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html lang="en-us" xml:lang="en-us">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<meta name="security" content="public" />
|
||
<meta name="Robots" content="index,follow" />
|
||
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
<meta name="DC.Type" content="reference" />
|
||
<meta name="DC.Title" content="Character host variables in C and C++ applications that use SQL" />
|
||
<meta name="abstract" content="There are three valid forms for character host variables." />
|
||
<meta name="description" content="There are three valid forms for character host variables." />
|
||
<meta name="DC.subject" content="character host variable, C, C++, host variable, character, C program, C++ program, varchar host variable, varchar, SQL-varchar host variable, SQL-varchar, NUL-terminator, character host variables, precompiler parameter, OPTION(*CNULRQD), precompiler command, CRTSQLCI, CRTSQLCPPI, *CNULRQD, OPTION(*NOCNULRQD), *NOCNULRQD" />
|
||
<meta name="keywords" content="character host variable, C, C++, host variable, character, C program, C++ program, varchar host variable, varchar, SQL-varchar host variable, SQL-varchar, NUL-terminator, character host variables, precompiler parameter, OPTION(*CNULRQD), precompiler command, CRTSQLCI, CRTSQLCPPI, *CNULRQD, OPTION(*NOCNULRQD), *NOCNULRQD" />
|
||
<meta name="DC.Relation" scheme="URI" content="rzajpdeclaringhostc.htm" />
|
||
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
<meta name="DC.Format" content="XHTML" />
|
||
<meta name="DC.Identifier" content="rzajpccharhost" />
|
||
<meta name="DC.Language" content="en-us" />
|
||
<!-- 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. -->
|
||
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
<title>Character host variables in C and C++ applications that use SQL</title>
|
||
</head>
|
||
<body id="rzajpccharhost"><a name="rzajpccharhost"><!-- --></a>
|
||
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
<h1 class="topictitle1">Character host variables in C and C++ applications that use SQL</h1>
|
||
<div><p>There are three valid forms for character host variables. </p>
|
||
<div class="section"><p>These forms are:</p>
|
||
<ul><li>Single-character form</li>
|
||
<li>NUL-terminated character form</li>
|
||
<li>VARCHAR structured form</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section"><p>In addition, an SQL VARCHAR declare can be used to define a varchar
|
||
host variable.</p>
|
||
</div>
|
||
<div class="section"><p>All character types are treated as unsigned.</p>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Single-character form</h4><pre><span><img src="./c.gif" border="0" alt="Read syntax diagram" longdesc="rzajpccharhostsyn1.htm" /></span><a href="#d0e152"><img src="./c.gif" border="0" alt="Skip visual syntax diagram" /></a>
|
||
>>-+--------+--+----------+--+----------+--char----------------->
|
||
+-auto---+ +-const----+ +-unsigned-+
|
||
+-extern-+ '-volatile-' '-signed---'
|
||
'-static-'
|
||
|
||
.-,-----------------------------------------------.
|
||
V |
|
||
>----<i>variable-name</i>--+---------+--+-----------------+-+-- ; ----><
|
||
'-[--<i>1</i>--]-' '- = --<i>expression</i>-'
|
||
|
||
</pre><a name="d0e152"></a></div>
|
||
<div class="section"><h4 class="sectiontitle">NUL-terminated character form</h4><pre><span><img src="./c.gif" border="0" alt="Read syntax diagram" longdesc="rzajpccharhostsyn2.htm" /></span><a href="#d0e196"><img src="./c.gif" border="0" alt="Skip visual syntax diagram" /></a>
|
||
>>-+--------+--+----------+--+----------+--char----------------->
|
||
+-auto---+ +-const----+ +-unsigned-+
|
||
+-extern-+ '-volatile-' '-signed---'
|
||
'-static-'
|
||
|
||
.-,------------------------------------------------.
|
||
V |
|
||
>----<i>variable-name</i>--[--<i>length</i>--]--+-----------------+-+-- ; ---><
|
||
'- = --<i>expression</i>-'
|
||
|
||
</pre><a name="d0e196"></a></div>
|
||
<div class="section"> <div class="note"><span class="notetitle">Notes:</span> <ol><li>The length must be an integer constant that is greater than 1 and not
|
||
greater than 32 741.</li>
|
||
<li>If the *CNULRQD option is specified on the <span class="cmdname">CRTSQLCI</span> or <span class="cmdname">CRTSQLCPPI</span> command,
|
||
the input host variables must contain the NUL-terminator. Output host variables
|
||
are padded with blanks, and the last character is the NUL-terminator. If the
|
||
output host variable is too small to contain both the data and the NUL-terminator,
|
||
the following actions are taken:<ul><li>The data is truncated</li>
|
||
<li>The last character is the NUL-terminator</li>
|
||
<li>SQLWARN1 is set to 'W'</li>
|
||
</ul>
|
||
</li>
|
||
<li>If the *NOCNULRQD option is specified on the <span class="cmdname">CRTSQLCI</span> or <span class="cmdname">CRTSQLCPPI</span> command,
|
||
the input variables do not need to contain the NUL-terminator. <div class="p">The following
|
||
applies to output host variables. <ul><li>If the host variable is large enough to contain the data and the NUL-terminator,
|
||
then the following actions are taken: <ul><li>The data is returned, but the data is not padded with blanks</li>
|
||
<li>The NUL-terminator immediately follows the data</li>
|
||
</ul>
|
||
</li>
|
||
<li>If the host variable is large enough to contain the data but not the NUL-terminator,
|
||
then the following actions are taken: <ul><li>The data is returned</li>
|
||
<li>A NUL-terminator is not returned</li>
|
||
<li>SQLWARN1 is set to 'N'</li>
|
||
</ul>
|
||
</li>
|
||
<li>If the host variable is not large enough to contain the data, the following
|
||
actions are taken: <ul><li>The data is truncated</li>
|
||
<li>A NUL-terminator is not returned</li>
|
||
<li>SQLWARN1 is set to 'W'</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">VARCHAR structured form</h4><pre><span><img src="./c.gif" border="0" alt="Read syntax diagram" longdesc="rzajpccharhostsyn3.htm" /></span><a href="#d0e298"><img src="./c.gif" border="0" alt="Skip visual syntax diagram" /></a>
|
||
>>-+--------+--+----------+------------------------------------->
|
||
+-auto---+ +-const----+
|
||
+-extern-+ '-volatile-'
|
||
'-static-'
|
||
|
||
>--+---------+--struct--+-----+-- { ---------------------------->
|
||
'-_Packed-' '-<i>tag</i>-'
|
||
|
||
.-int-.
|
||
>--+--------+--short--+-----+--<i>var-1</i>-- ; ----------------------->
|
||
'-signed-'
|
||
|
||
>--+----------+--char--<i>var-2</i>--[--<i>length</i>--]-- ; -- } ------------>
|
||
+-unsigned-+
|
||
'-signed---'
|
||
|
||
.-,------------------------------------------------------.
|
||
V |
|
||
>----<i>variable-name</i>--+-------------------------------------+-+-- ; -><
|
||
'- = --{--<i>expression ,</i>--<i>expression</i>--}-'
|
||
|
||
</pre><a name="d0e298"></a></div>
|
||
<div class="section"> <div class="note"><span class="notetitle">Notes:</span> <ol><li><em>length</em> must be an integer constant that is greater than 0 and not
|
||
greater than 32 740.</li>
|
||
<li><em>var-1</em> and <em>var-2</em> must be simple variable references and cannot
|
||
be used individually as integer and character host variables.</li>
|
||
<li>The struct tag can be used to define other data areas, but these cannot
|
||
be used as host variables.</li>
|
||
<li>The VARCHAR structured form should be used for bit data that may contain
|
||
the NULL character. The VARCHAR structured form will not be ended using the
|
||
nul-terminator.</li>
|
||
<li>_Packed must not be used in C++. Instead, specify #pragma pack(1) prior
|
||
to the declaration and #pragma pack() after the declaration.<div class="note"><span class="notetitle">Note:</span> You can
|
||
use #pragma pack (reset) instead of #pragma pack() because they are the same.</div>
|
||
<pre>#pragma pack(1)
|
||
struct VARCHAR {
|
||
short len;
|
||
char s[10];
|
||
} vstring;
|
||
#pragma pack()</pre>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="section"><div class="p"><em>Example</em>: <pre>EXEC SQL <strong>BEGIN DECLARE SECTION</strong>;
|
||
|
||
/* valid declaration of host variable vstring */
|
||
|
||
struct VARCHAR {
|
||
short len;
|
||
char s[10];
|
||
} vstring;
|
||
|
||
/* invalid declaration of host variable wstring */
|
||
|
||
struct VARCHAR wstring;</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">SQL VARCHAR form</h4> <pre><span><img src="./c.gif" border="0" alt="Read syntax diagram" longdesc="rzajpccharhostsyn4.htm" /></span><a href="#d0e411"><img src="./c.gif" border="0" alt="Skip visual syntax diagram" /></a>
|
||
.-,-------------------------------------------------.
|
||
V |
|
||
>>-VARCHAR----<i>variable-name</i>--[--<i>length</i>--]--+------------------+-+-- ; -><
|
||
'- = --<i>"init-data"</i>-'
|
||
|
||
</pre><a name="d0e411"></a></div>
|
||
<div class="section"> <div class="note"><span class="notetitle">Notes:</span> <ol><li>VARCHAR can be in mixed case.</li>
|
||
<li>Length must be an integer constant that is greater than 0 and not greater
|
||
than 32 740.</li>
|
||
<li>The SQL VARCHAR form should be used for bit data that may contain the
|
||
NULL character. The SQL VARCHAR form will not be ended using the nul-terminator.</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle"><em>Example</em></h4><p>The following declaration: </p>
|
||
<pre>VARCHAR vstring[528]="mydata";</pre>
|
||
<p>Results
|
||
in the generation of the following structure: </p>
|
||
<pre>_Packed struct { short len;
|
||
char data[528];}
|
||
vstring={6, "mydata"};</pre>
|
||
</div>
|
||
<div class="section"><p>The following declaration: </p>
|
||
<pre>VARCHAR vstring1[111],
|
||
vstring2[222]="mydata",
|
||
vstring3[333]="more data";</pre>
|
||
<p>Results in the generation
|
||
of the following structures: </p>
|
||
<pre>_Packed struct { short len;
|
||
char data[111];}
|
||
vstring1;
|
||
|
||
_Packed struct { short len;
|
||
char data[222];}
|
||
vstring2={6,"mydata"};
|
||
|
||
_Packed struct { short len;
|
||
char data[333};}
|
||
vstring3={9,"more data"};</pre>
|
||
</div>
|
||
</div>
|
||
<div>
|
||
<div class="familylinks">
|
||
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzajpdeclaringhostc.htm" title="The C and C++ precompilers recognize only a subset of valid C and C++ declarations as valid host variable declarations.">Declare host variables in C and C++ applications that use SQL</a></div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html>
|