$ListImg: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (image_id wordsmithing)
 
(37 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="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListImg function is the [[BindImage (Stringlist subroutine)]].</p>
<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>


This function returns a 0 indicating that the image has been associated with the $list or a negative number indicating that an error has occurred.  
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.  


The <var>$ListImg</var> function accepts two arguments and returns a numeric result. It is a callable $function (see [[Calling Sirius Mods $functions]]).


The first argument is a $list identifier. This is a required argument.
The second argument can be a string containing the name of an image, or it can be any image item from the required image. This is a required argument.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListImg(list_identifier, image_id)
<p class="syntax">[<span class="term">%result</span> =] $ListImg(<span class="term">list_identifier</span>, <span class="term">image_id</span>)
<section end="syntax" /></p>
<p class="caption">$ListImg Function
</p>
</p>
<p class="caption">%RESULT is a string that contains a 0, or it contains a negative number if an error has occurred.</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, 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>


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


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


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


<p class="code"> %RC = $ListImg(%LIST, 'SALES')
<p class="code">%rc = $ListImg(%list, 'SALES')
</p>
</p>
or
or
<p class="code"> %RC = $ListImg(%LIST, %SALES:ID)
<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>


While the latter is syntactically inefficient (<tt>:ID</tt> is superfluous), it is more efficient because the image name hashing and lookup is done at compile time rather than evaluation time.
<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>


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


[[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 %list with:

    %rc = $ListImg(%list, 'SALES')

    or

    %rc = $ListImg(%list, %SALES:ID)

    While the latter is syntactically inefficient (:ID is 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.

Products authorizing $ListImg