1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<TITLE>Environmental Resource Management Overview </TITLE> 8<LINK rel="stylesheet" href="../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">Environment Resources Overview</H1> 12<H2>Description</H2> 13<P>The Environmental Resources (ENV) library provides a method for easily getting values defined as resources from a program. Resources are various parameters and configuration values for which the resource names have been defined. Resource values are obtained from a program by specifying a resource name.</P> 14<P>The ENV library provides a convenient way to test operations during program development by changing parameters or by using shared configuration values on multiple programs.</P> 15<HR> 16<H3>Resource Definitions</H3> 17<P>In this ENV library, resource values are returned in response to queries about resource names. A resource name comprises a class name, a period ("."), and a member name.</P> 18<BLOCKQUOTE style="background-color:#ffffcc;"><B>Example:</B><BR> 19In the case of the resource <CODE>myServer.Hostname</CODE>, <CODE>myServer</CODE> is the class name, and <CODE>Hostname</CODE> is the member name.</BLOCKQUOTE> 20<P>These types of resources can be given any of the following as values: <CODE>u8</CODE>, <CODE>s8</CODE>, <CODE>u16</CODE>, <CODE>s16</CODE>, <CODE>u32</CODE>, <CODE>s32</CODE>, <CODE>u64</CODE>, <CODE>s64</CODE>, <CODE>BOOL</CODE>, <CODE>string</CODE>, or <CODE>binary</CODE>. String data is labeled <CODE>string</CODE>, and binary data is labeled <CODE>binary</CODE>.</P> 21<P>Resources are managed internally with a single <CODE>ENVResource</CODE> structure. (Two structures are used for 64-bit resource values.)</P> 22<BLOCKQUOTE style="background-color:#ffffcc;"> 23<P><PRE>struct ENVResource 24{ 25 char* name; 26 u16 len; 27 u16 type; 28 void* ptr; 29};</PRE></P> 30</BLOCKQUOTE> 31<P>The <CODE>name</CODE> element is a pointer to the resource name. The <CODE>len</CODE> element is the length of the resource. The <CODE>type</CODE> element is the information type when the resource is declared. The <CODE>ptr</CODE> element is the pointer to the location where the string and data are actually stored for <CODE>string</CODE> and <CODE>binary</CODE>. Values for <CODE>u8</CODE>, <CODE>s8</CODE>, <CODE>u16</CODE>, <CODE>s16</CODE>, <CODE>u32</CODE>, <CODE>s32</CODE>, or <CODE>BOOL</CODE> are assigned to <CODE>ptr</CODE>. <CODE>u64</CODE> and <CODE>s64</CODE> use two continuous data resources.</P> 32<HR> 33<H3>Description of the Resource Data<BR> 34 35</H3> 36<P>Resource data are defined with an <CODE>ENVResource</CODE> structure array. The following macros have be prepared to define the <CODE>len</CODE>, <CODE>type</CODE>, and <CODE>ptr</CODE> members for the above-mentioned <CODE>ENVResource</CODE> structure all at once. These macros make it easier to describe resources. 37</P> 38<TABLE border="1"> 39 <TBODY> 40 <TR> 41<TD><CODE>ENV_U8</CODE></TD> 42<TD>A macro for a <CODE>u8</CODE> value.</TD> 43 </TR> 44 <TR> 45<TD><CODE>ENV_S8</CODE></TD> 46<TD>A macro for an <CODE>s8</CODE> value.</TD> 47 </TR> 48 <TR> 49<TD><CODE>ENV_U16</CODE></TD> 50<TD>A macro for a <CODE>u16</CODE> value.</TD> 51 </TR> 52 <TR> 53<TD><CODE>ENV_S16</CODE></TD> 54<TD>A macro for an <CODE>s16</CODE> value.</TD> 55 </TR> 56 <TR> 57<TD><CODE>ENV_U32</CODE></TD> 58<TD>A macro for a <CODE>u32</CODE> value.</TD> 59 </TR> 60 <TR> 61<TD><CODE>ENV_S32</CODE></TD> 62<TD>A macro for an <CODE>s32</CODE> value.</TD> 63 </TR> 64 <TR> 65<TD><CODE>ENV_U64</CODE></TD> 66<TD>A macro for a <CODE>u64</CODE> value.</TD> 67 </TR> 68 <TR> 69<TD><CODE>ENV_S64</CODE></TD> 70<TD>A macro for an <CODE>s64</CODE> value.</TD> 71 </TR> 72 <TR> 73<TD><CODE>ENV_BOOL</CODE></TD> 74<TD>A macro for a <CODE>BOOL</CODE> value.</TD> 75 </TR> 76 <TR> 77<TD><CODE>ENV_STRING</CODE></TD> 78<TD>A macro for <CODE>string</CODE> data.</TD> 79 </TR> 80 <TR> 81<TD><CODE>ENV_BINARY</CODE></TD> 82<TD>A macro for <CODE>binary</CODE> data.</TD> 83 </TR> 84 </TBODY> 85</TABLE> 86<P>By using these macros, resources are defined as combination of resource names and resource macros, as shown below.</P> 87<BLOCKQUOTE style="background-color:#ffffcc;"><PRE>ENVResource myResource[] = { 88 "myClass.str1", ENV_STRING( "mario" ), 89 "myClass.bin1", ENV_BINARY( "\x12\x34\x56\x78" ), 90 "myClass2.data1", ENV_S32( -500 ), 91 "myClass2.data2", ENV_U16( 0x8000 ), 92 ENV_RESOURCE_END 93};</PRE></BLOCKQUOTE> 94<P><CODE><FONT color="#ff0033">Add <CODE>ENV_RESOURCE_END</CODE> at the end of the data.</FONT></CODE></P> 95<P>The resource array defined above is then managed internally.</P> 96<BLOCKQUOTE><CODE><IMG src="image_envResource1.gif" border="0"><BR> 97</CODE></BLOCKQUOTE> 98<HR> 99<H3>Resource Array List</H3> 100<P>Searches for resources are performed from the resource array. In the ENV library, multiple resource arrays can be registered in the system. The resource arrays are linked together as a list inside the system. When a search is performed, it is conducted on every array in that list. Searches are performed from the very beginning of the list and from the very beginning of the arrays. If the same resource exists in both, the first one found is used.</P> 101<P>The <A href="ENV_AppendResourceSet.html"><CODE>ENV_AppendResourceSet</CODE></A> function adds new resource arrays to the end of the list.<BR> 102The <A href="ENV_PrependResourceSet.html"><CODE>ENV_PrependResourceSet</CODE></A> function adds new resource arrays to the beginning of the list.<BR> 103The <A href="ENV_InsertResourceSet.html"><CODE>ENV_InsertResourceSet</CODE></A> function adds new resource arrays to a location of the user's choice.<BR> 104</P> 105<P>The <A href="ENV_SetResourceSet.html"><CODE>ENV_SetResourceSet</CODE></A> and <A href="ENV_SetResourceSetArray.html"><CODE>ENV_SetResourceSetArray</CODE></A> functions delete lists that have been registered up to this point and then register a specified list.</P> 106<P>There is a limit to the number of resource arrays that can be registered. The number is <CODE>ENV_RESOURCE_SET_MAX</CODE>. (Defined as 8.)</P> 107<BLOCKQUOTE><IMG src="image_envResource2.gif" border="0"></BLOCKQUOTE> 108<HR> 109<H3>Declaring Resource Arrays</H3> 110<P>The <A href="ENV_Init.html"><CODE>ENV_Init</CODE></A> function specifies resource arrays using the <A href="ENV_Init.html"><CODE>ENVResource* resourceArray[]</CODE></A> array, as shown below.</P> 111<BLOCKQUOTE style="background:#ffffcc"><PRE><FONT color="#ff0000">SDK_WEAK_SYMBOL</FONT> ENVResource *<FONT color="#ff0000">resourceArray</FONT>[] = { NULL }; 112 113void ENV_Init(void) 114{ 115 : 116 <FONT color="#ff0000">ENV_SetResourceSetArray( resourceArray );</FONT> 117}</CODE></BLOCKQUOTE> 118<P><CODE>resourceArray[]</CODE> is an array that holds resource arrays. Because <CODE>resourceArray[]</CODE> is an array of <CODE>NULL</CODE> members that is defined with the WEAK symbol in the system, it is useful for the application to define the array itself. Because <CODE>resourceArray[]</CODE> is an array of resource arrays, it can specify a number of necessary resource arrays all at once.</P> 119 120<HR> 121<H3>Getting Resource Values</H3> 122<P>Use the functions that get resource values from resource names based on the resource definition, as shown below. 123</P> 124<TABLE border="1"> 125 <TBODY> 126 <TR> 127<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetU8</CODE></A></TD> 128<TD>A <CODE>u8</CODE> value defined with <CODE>ENV_U8</CODE>.</TD> 129 </TR> 130 <TR> 131<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetS8</CODE></A></TD> 132<TD>An <CODE>s8</CODE> value defined with <CODE>ENV_S8</CODE>.</TD> 133 </TR> 134 <TR> 135<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetU16</CODE></A></TD> 136<TD>A <CODE>u16</CODE> value defined with <CODE>ENV_U16</CODE>.</TD> 137 </TR> 138 <TR> 139<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetS16</CODE></A></TD> 140<TD>An <CODE>s16</CODE> value defined with <CODE>ENV_S16</CODE>.</TD> 141 </TR> 142 <TR> 143<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetU32</CODE></A></TD> 144<TD>A <CODE>u32</CODE> value defined with <CODE>ENV_U32</CODE>.</TD> 145 </TR> 146 <TR> 147<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetS32</CODE></A></TD> 148<TD>An <CODE>s32</CODE> value defined with <CODE>ENV_S32</CODE>.</TD> 149 </TR> 150 <TR> 151<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetU64</CODE></A></TD> 152<TD>A <CODE>u64</CODE> value defined with <CODE>ENV_U64</CODE>.</TD> 153 </TR> 154 <TR> 155<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetS64</CODE></A></TD> 156<TD>An <CODE>s64</CODE> value defined with <CODE>ENV_S64</CODE>.</TD> 157 </TR> 158 <TR> 159<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetBOOL</CODE></A></TD> 160<TD>A <CODE>BOOL</CODE> value defined with <CODE>ENV_BOOL</CODE>.</TD> 161 </TR> 162 <TR> 163<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetString</CODE></A></TD> 164<TD>String data defined with <CODE>ENV_STRING</CODE>.</TD> 165 </TR> 166 <TR> 167<TD><A href="ENV_GetXXX.html"><CODE>ENV_GetBinary</CODE></A></TD> 168<TD>Binary data defined with <CODE>ENV_BINARY</CODE>.</TD> 169 </TR> 170 </TBODY> 171</TABLE> 172<P>The obtained values are stored at the beginning of the pointer designated in the arguments. The function return value indicates whether the values were successfully obtained.</P> 173<P>Two functions have been prepared that get strings and binaries along with their sizes: <A href="ENV_GetXXX.html"><CODE>ENV_GetStringAndLength</CODE></A> and <A href="ENV_GetXXX.html"><CODE>ENV_GetBinaryAndSize</CODE></A>.</P> 174<HR> 175<H3>Omitting Class Names</H3> 176<P>By passing the class names to the ENV library in advance, the class name part can be omitted, and the member name can be used alone to designate with the functions that require resource names. When designating a member name by itself, be sure to add a period (".") before the name.</P> 177<P>Use the <A href="ENV_SetClass.html"><CODE>ENV_SetClass</CODE></A> function to declare class names.</P> 178<BLOCKQUOTE style="background-color:#ffffcc;"><B>Example:</B><BR> 179All of the following, where the class name is declared, <BR> 180<PRE>u32 d1, d2, d3; 181(void)ENV_GetU32( "myClass.myData1", &d1 ); 182(void)ENV_GetU32( "myClass.myData2", &d2 ); 183(void)ENV_GetU32( "myClass.myData3", &d3 ); 184</PRE> 185can be designated in the following forms, with only the member names: 186<PRE>u32 d1, d2, d3; 187ENV_SetClass( "myClass" ); 188(void)ENV_GetU32( ".myData1", &d1 ); 189(void)ENV_GetU32( ".myData2", &d2 ); 190(void)ENV_GetU32( ".myData3", &d3 ); 191</PRE> 192</BLOCKQUOTE> 193<P>The function used to obtain the current configuration values is <CODE><A href="ENV_GetClass.html">ENV_GetClass()</A></CODE>.</P> 194<HR> 195<H3>Example of Using the ENV Library</H3> 196<P>Below is an example of using the ENV library.</P> 197<BLOCKQUOTE style="background-color:#ffffcc;"><PRE>ENVResource myResource1[] = { 198 "server1.hostName", ENV_STRING( "myserver" ), 199 "server1.IP", ENV_BINARY( "\xc0\xA8\x00\x01" ), 200 "server1.port", ENV_U16( 5000 ), 201 <B><FONT color="#ff0033">ENV_RESOURCE_END</FONT></B> 202}; 203 204ENVResource myResource2[] = { 205 "server2.hostName", ENV_STRING( "ftpserver" ), 206 "server2.IP", ENV_BINARY( "\xc0\xA8\x00\x02" ), 207 "server2.port", ENV_U16( 21 ), 208 <B><FONT color="#ff0033">ENV_RESOURCE_END</FONT></B> 209}; 210 211ENVResource* resourceArray[]={ myResource1, myResource2, NULL }; 212 213 214 215main() 216{ 217 char* hostname; 218 u8* ipAddress; 219 int ipSize; 220 u16 portNum; 221 : 222 //---- ENV system initialization 223 ENV_Init( myResources ); 224 225 //---- Class name designation when omitted 226 ENV_SetClass( "server1" ); 227 228 //---- Get resource 229 if ( ! ENV_GetString( ".hostName", &hostname ) ) 230 { 231 OS_Printf( "error: hostname is not defined.\n" ); 232 }; 233 if ( ! ENV_GetBinaryAndSize( ".IP", &ipAddress, &ipSize) ) 234 { 235 OS_Printf( "error: ipAddress is not defined.\n" ); 236 }; 237 if ( ! ENV_GetU16( ".port", &portNum ) ) 238 { 239 OS_Printf( "error: portNum is not defined.\n" ); 240 }; 241 : 242} 243</PRE></BLOCKQUOTE> 244<HR> 245<H3>Searching for Resources Under Specified Conditions</H3> 246<P>The <CODE>ENVResourceIter</CODE> structure has been defined to search for resources using specified class names or member names. This is used as a search iterator. The functions that get the resource by using the iterators are <A href="ENV_InitIter.html"><CODE>ENV_InitIter</CODE></A>, <A href="ENV_SearchByClass.html"><CODE>ENV_SearchByClass</CODE></A>, <A href="ENV_SearchByMember.html"><CODE>ENV_SearchByMember</CODE></A>, <A href="ENV_SearchByType.html"><CODE>ENV_SearchByType</CODE></A>, and <A href="ENV_SearchByPartialName.html"><CODE>ENV_SearchByPartialName</CODE></A>.</P> 247<P>The following shows the resource with the specified class <CODE>className</CODE> being obtained.</P> 248<BLOCKQUOTE style="background-color:#ffffcc;"><PRE><FONT color="#ff0033">ENVResourceiter iter;</FONT> 249ENVResource* p; 250 251<FONT color="#ff0033">ENV_InitIter( &iter );</FONT> 252while( (p = <FONT color="#ff0033">ENV_SearchByClass( &iter, "className" )</FONT> ) ) 253{ 254 OS_Printf( "resource = %s\n", p->name ); 255}</PRE></BLOCKQUOTE> 256<P>To search for a resource with the specific name "<CODE>memberName</CODE>," use the following statements. The member name is a text string that does not contain a period ("."). If there are any periods other than the delimiter between the class and member, the comparison is performed on the member name up to the location of the first period.</P> 257<BLOCKQUOTE style="background-color:#ffffcc;"><PRE><FONT color="#ff0033">ENVResourceIter iter;</FONT> 258ENVResource* p; 259 260<FONT color="#ff0033">ENV_InitIter( &iter );</FONT> 261while( (p = <FONT color="#ff0033">ENV_SearchByMember( &iter, "memberName" )</FONT> ) ) 262{ 263 OS_Printf( "resource = %s\n", p->name ); 264}</PRE></BLOCKQUOTE> 265<P>For example, when searching with the member name "<CODE>member</CODE>,"</P> 266<BLOCKQUOTE style="background-color:#ffffcc;"><CODE>"class.member"<BR> 267"class.member.001"<BR> 268"class.member.class"</CODE></BLOCKQUOTE> 269<P><CODE>has a match, but</CODE></P> 270<BLOCKQUOTE style="background-color:#ffffcc;"><CODE>"class.member001"<BR> 271"class.member2.member"</CODE></BLOCKQUOTE> 272<P>do not match.</P> 273<HR> 274<H3>Resource Array That Includes Resource</H3> 275<P>It is also possible to get the resource array that includes the resource obtained with <A href="ENV_GetLastResourceSetFromIter.html"><CODE>ENV_GetLastResourceSetFromIter</CODE></A> function immediately after an iterator-based resource search.</P> 276<P>Specify the resource and use the <A href="ENV_GetBelongingResourceSet.html"><CODE>ENV_GetBelongingResourceSet</CODE></A> function to get the resource array to which the resource belongs.<BR> 277 278</P> 279<H2>See Also</H2> 280<P><A href="list_env.html">ENV function list</A></P> 281<H2>Revision History</H2> 282<P>2005/08/29 Added support for multiple registrations of a resource array.<BR> 283 2842005/08/17 Initial version.</P> 285<hr><p>CONFIDENTIAL</p></body> 286</HTML>
