$ListImg: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (image_id wordsmithing) |
||
| (22 intermediate revisions by 3 users not shown) | |||
| Line 2: | Line 2: | ||
<span class="pageSubtitle">Associate an image with a $list</span> | <span class="pageSubtitle">Associate an image with a $list</span> | ||
<p class=" | <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== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax">[<span class="term">%result</span> =] $ListImg(<span class="term">list_identifier</span>, <span class="term">image_id</span>) | ||
< | |||
</p> | </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> | |||
<p class="code"> | <tr><th>image_id</th> | ||
<td>A string containing the name of an image (or, as shown below in the [[#imageItem|Usage notes]], it can be an identifier of an image-item from the 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> | </p> | ||
Suppose there is an image with the following description: | ==Usage notes== | ||
<p class="code"> IMAGE SALES | <ul> | ||
<li id="imageItem">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> | </p> | ||
One can associate this image with the $list % | One can associate this image with the $list <code>%list</code> with: | ||
<p class="code"> % | <p class="code">%rc = $ListImg(%list, 'SALES') | ||
</p> | </p> | ||
or | or | ||
<p class="code"> % | <p class="code">%rc = $ListImg(%list, %SALES:ID) | ||
</p> | </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: | |||
Functions that can use the association between an image and a $list are: | |||
<ul> | <ul> | ||
| Line 55: | Line 58: | ||
<li>[[$ListOvl]]</li> | <li>[[$ListOvl]]</li> | ||
<li>[[$ListRepI]]</li> | <li>[[$ListRepI]]</li> | ||
<li>[[$ListSrt]]</li> | <li>[[$ListSort and $ListSrt|$ListSrt]]</li> | ||
<li>[[$ListSub]]</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> | </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]] | [[Category:$Functions|$ListImg]] | ||
Latest revision as of 20:51, 12 June 2018
Associate an image with a $list
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListImg function is BindImage.
The $ListImg 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 callable $function.
Syntax
[%result =] $ListImg(list_identifier, image_id)
| %result | A string that contains a 0, or it contains a negative number (see Return codes) if an error has occurred. |
|---|---|
| list_identifier | A $list identifier. This is a required argument. |
| image_id | A string containing the name of an image (or, as shown below in the Usage notes, it can be an identifier of an image-item from the image). This is a required argument. |
Return codes
-5 - Required argument not specified -6 - $List identifier invalid -8 - Image not found
Usage notes
- Suppose there is an image with the following description:
IMAGE SALES ITEM IS STRING LEN 16 ID IS STRING LEN 8 PRICE IS BINARY LEN 4 END IMAGE
One can associate this image with the $list
%listwith:%rc = $ListImg(%list, 'SALES')
or
%rc = $ListImg(%list, %SALES:ID)
While the latter is syntactically inefficient (
:IDis superfluous), it is more efficient because the image name hashing and lookup is done at compile time rather than evaluation time. - Functions that can use the association between an image and a $list are:
- 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 $ListSav and $ListRst.