View source for $ListImg

{{DISPLAYTITLE:$ListImg}}
<span class="pageSubtitle">Associate an image with a $list</span>

<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the <var>$ListImg</var> function is <var>[[BindImage (Stringlist subroutine)|BindImage]]</var>. </p>

The <var>$ListImg</var> function accepts two arguments and returns a numeric result: a 0 (indicating that the image has been associated with the $list) or a negative number (indicating that an error has occurred). It is a [[Calling Sirius Mods $functions|callable]] $function. 


==Syntax==
<p class="syntax">[<span class="term">%result</span> =] $ListImg(<span class="term">list_identifier</span>, <span class="term">image_id</span>)
</p>
<table>
<tr><th>%result</th>
<td>A string that contains a 0, or it contains a negative number (see [[#Return codes|Return codes]]) if an error has occurred. </td></tr>

<tr><th>list_identifier</th>
<td>A $list identifier. This is a required argument. </td></tr>

<tr><th>image_id</th>
<td>A string containing the name of an image, or it can be any image item from the required image. This is a required argument. </td></tr>
</table>

===Return codes===
<p class="code">-5 - Required argument not specified
-6 - $List identifier invalid
-8 - Image not found
</p>

==Usage notes==
<ul>
<li>Suppose there is an image with the following description:
<p class="code">IMAGE SALES
ITEM IS STRING LEN 16
ID IS STRING LEN 8
PRICE IS BINARY LEN 4
END IMAGE
</p>

One can associate this image with the $list <code>%list</code> with:

<p class="code">%rc = $ListImg(%list, 'SALES')
</p>
or
<p class="code">%rc = $ListImg(%list, %SALES:ID)
</p>
<p>
While the latter is syntactically inefficient (<code>:ID</code> is superfluous), it is more efficient because the image name hashing and lookup is done at compile time rather than evaluation time. </p></li>

<li>Functions that can use the association between an image and a $list are:

<ul>
<li>[[$ListAddI]]</li>
<li>[[$ListInf]]</li>
<li>[[$ListInfI]]</li>
<li>[[$ListInsI]]</li>
<li>[[$ListLoc]]</li>
<li>[[$ListLup]]</li>
<li>[[$ListOvl]]</li>
<li>[[$ListRepI]]</li>
<li>[[$ListSort and $ListSrt|$ListSrt]]</li>
<li>[[$ListSub]]</li>
</ul></li>

<li>The association between an image and a $list is an association between the image and the particular $list identifier value. A [[$ListMove]] does not change the image association of the target $list, and the image association of a $list is not saved or restored with <var>$ListSav</var> and <var>$ListRst</var>. </li>
</ul>

==Products authorizing {{PAGENAMEE}}== 
<ul class="smallAndTightList">
<li>[[Sirius Functions]] </li>
<li>[[Fast/Unload User Language Interface]] </li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]] </li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]] </li>
<li>[[Janus Sockets]] </li>
<li>[[Janus Web Server]] </li>
<li>Japanese functions </li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul> 


[[Category:$Functions|$ListImg]]