<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-E932B20C-5155-530F-9669-6F5BB1F1AD41" xml:lang="en"><title>STRUCT
statement</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<codeblock xml:space="preserve">&lt;struct-statement&gt;
struct-statement ::= 
STRUCT &lt;struct-name&gt; [ BYTE | WORD ] { &lt;struct-member-list&gt; } </codeblock>
<p>A <codeph>STRUCT</codeph> statement defines the format of a struct; all
resources are defined in terms of structs. The struct has a name designated
by <varname>struct-name</varname>, and some items designated by <varname>struct-member-list</varname>.</p>
<section><title>Struct names</title><p>The following rules must
be observed for <varname>struct-names</varname>:</p><ul>
<li id="GUID-E490ACC3-1A5E-5A93-97BC-EA13322F93B3"><p>they must be given in
upper case</p> </li>
<li id="GUID-A8237D56-9872-5869-9041-1F66130F1BCA"><p>they must begin with
an alphabetic character, although subsequent characters may be numeric</p> </li>
<li id="GUID-8F0B5DE9-C6B0-5637-A755-0BD408744898"><p>they may not begin with
any of the 12 struct <varname>type-names</varname> (see <xref href="GUID-89ADFC64-AF9F-51B1-AC5F-493897226270.dita">STRUCT
members</xref>), or the keywords: <codeph>GLOBAL</codeph>, <codeph>STRUCT</codeph>, <codeph>LEN</codeph> or <codeph>RESOURCE</codeph>.
This restriction applies only to the <varname>struct-name</varname>, not the <varname>member-name</varname> of
any individual struct members.</p> <p>So the following struct definition will
generate an error</p> <codeblock id="GUID-A2D5E9FB-1C45-52FE-8997-95D2117DFE05" xml:space="preserve">STRUCT BUFTHING
 {
 BUF buffer;
 }</codeblock> <p>whereas this struct definition will compile correctly</p> <codeblock id="GUID-6EEF6653-C2D9-559E-BA72-5C70E30B9633" xml:space="preserve">STRUCT ABUFTHING
 {
 BUF buffer;
 }</codeblock> </li>
</ul></section>
<section><title>Struct member list</title><p>The <varname>struct-member-list</varname> is
a sequence of <varname>struct-member</varname> s where each member is terminated
by a semi-colon. The complete list is enclosed within a pair of braces.</p><p>See <xref href="GUID-89ADFC64-AF9F-51B1-AC5F-493897226270.dita">STRUCT members</xref> for
more details.</p></section>
<section><title>BYTE/WORD keywords</title><p><codeph>STRUCT</codeph> definitions
allow resource instances to be of variable length, as the struct can allow
default variables for its members. A resource’s entire length can be deduced
from the position of the next resource; this information is available in a
resource file’s index. If the resource is used as a member within an instance
of another resource, however, its length <i>must</i> be identified another
way.</p><ul>
<li id="GUID-6EBE2158-D5F4-588F-B45E-94AB86D87547"><p>Use <codeph>BYTE</codeph> to
prefix the struct with a single byte indicating its length (zero to 255 characters).</p> </li>
<li id="GUID-43D2F295-C031-5812-A0BD-5F017C20918B"><p>Use <codeph>WORD</codeph> to
prefix the struct with a word indicating its length (zero to 65,535 characters).</p> </li>
</ul></section>
<example><p>The following are valid <codeph>STRUCT</codeph> statements:</p><codeblock id="GUID-04C66589-84AC-591F-80A3-73FC1C973F4C" xml:space="preserve">STRUCT STRING
 {
 LTEXT str;
 }</codeblock><p>This defines a struct called <codeph>STRING</codeph> which
contains a single <codeph>LTEXT</codeph> item.</p><codeblock id="GUID-C85D999C-4E6A-57B8-ACFB-E6A7DB51E960" xml:space="preserve">STRUCT TEST BYTE
 {
 WORD status;
 STRUCT text;
 }</codeblock><p>This defines a struct called <codeph>TEST</codeph> which
contains a <codeph>WORD</codeph> and an embedded struct. The total length
of <codeph>TEST</codeph> is unknown, but should not exceed 255 characters:
the <codeph>BYTE</codeph> directive in the definition indicates that, when
this struct is embedded within another, it should be preceded with a byte
indicating its length (zero to 255 characters).</p></example>
</conbody></concept>