BindImage (Stringlist subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
 
(28 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<span style="font-size:120%"><b>Associate an image with a Stringlist</b></span>
{{Template:Stringlist:BindImage subtitle}}


This method associates or binds an image to a Stringlist. BindImage is a subroutine that accepts one argument, an image name, and does not return anything.
This method associates or binds an image to a <var>Stringlist</var>. <var>BindImage</var> is a subroutine that accepts one argument, an image name, and does not return anything.


BindImage is a member of the [[Stringlist class]].
==Syntax==
{{Template:Stringlist:BindImage syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>imageName</th>
<td>A string that contains the name of an image. This argument is case sensitive. That is, in the likely event the <var class="product">User Language</var> was written in mixed case, with automatic upper-casing in effect, the image name should be in uppercase.</td></tr>
</table>


==BindImage Syntax==
==Usage notes==
<pre>
<ul><li>All errors in <var>BindImage</var> result in request cancellation.
%sl:BindImage(imagename)
<li>These methods can use the association between an image and a <var>Stringlist</var>:
</pre>
 
===Syntax Terms===
<dl>
<dt>%sl<dd>A Stringlist object.<dt>imagename<dd>A string that contains the name of an image.
This argument is case sensitive. That is, in the likely event the User Language was written in mixed case, with automatic upper-casing in effect, the image name should be in uppercase.
</dl>
 
==Usage Notes==
<ul><li>All errors in BindImage result in request cancellation.
<li>These methods can use the association between an image and a Stringlist:
<ul>
<ul>
<li>[[AddImage (Stringlist function)]]
<li><var>[[AddImage (Stringlist function)|AddImage]]</var>
<li>[[GetImage (Stringlist subroutine)]]
<li><var>[[GetImage (Stringlist subroutine)|GetImage]]</var>
<li>[[InsertImage (Stringlist function)]]
<li><var>[[InsertImage (Stringlist function)|InsertImage]]</var>
<li>[[ReplaceImage (Stringlist function)]]
<li><var>[[ReplaceImage (Stringlist function)|ReplaceImage]]</var>
<li>[[Sort (Stringlist subroutine)]]
<li><var>[[Sort (Stringlist subroutine)|Sort]]</var>
<li>[[SortNew (Stringlist function)]]
<li><var>[[SortNew (Stringlist function)|SortNew]]</var>
</ul>  
</ul>
 
</li>
The association between an image and a Stringlist is generally used when all Stringlist items have the same layout as the image. Methods that create a new Stringlist usually propagate the image binding from the method Stringlist to the output Stringlist.</ul>
<li>The association between an image and a <var>Stringlist</var> is generally used when all <var>Stringlist</var> items have the same layout as the image. Methods that create a new <var>Stringlist</var> usually propagate the image binding from the method <var>Stringlist</var> to the output <var>Stringlist</var>.
</li>
<li>A <var>BindImage</var> done inside a subroutine or method is not undone/popped when the subroutine or method returns, so care must be taken when adding a <var>BindImage</var> against a subroutine/method parameter as the subroutine/method caller must restore its own <var>BindImage</var> in such a case.</li>
</ul>


==Examples==
==Examples==
<ol><li>Once an image is bound to a Stringlist, methods that operate on an image can omit the image name parameter. This is not only convenient from a coding perspective, it is more efficient -- no image name lookup needs to be done in NTBL.  
<ol><li>Once an image is bound to a <var>Stringlist</var>, methods that operate on an image can omit the image name parameter. This is not only convenient from a coding perspective, it is more efficient — no image name lookup needs to be done in NTBL.


The following example illustrates such a use of BindImage:
The following example illustrates such a use of <var>BindImage</var>:


<pre>
<p class="code">%list is object stringList
%list is object stringList
...
...
image customer
image customer
id is string len 8
  id is string len 8
lname is string len 32
  lname is string len 32
end image
end image
...
...
Line 47: Line 46:
...
...
for each record in %recset
for each record in %recset
%customer:id = id
  %customer:id = id
%customer:lname = lname
  %customer:lname = lname
%list:addImage
  %list:addImage
end for
end for
</pre>
</p>


<li>BindImage could also enable the Sort and SortNew methods to use the names of image items in the sort criteria rather than column numbers, for example, where a Stringlist has a layout described by an image:
<li><var>BindImage</var> could also enable the <var>[[Sort (Stringlist subroutine)|Sort]]</var> and <var>[[SortNew (Stringlist function)|SortNew]]</var> methods to use the names of image items in the sort criteria rather than column numbers, for example, where a <var>Stringlist</var> has a layout described by an image:


<pre>
<p class="code">%list is object stringList
%list is object stringList
...
...
image customer
image customer
id is string len 8
  id is string len 8
lname is string len 32
  lname is string len 32
end image
end image
...
...
Line 67: Line 65:
...
...
%list:sort('LNAME,A ID,D')
%list:sort('LNAME,A ID,D')
</pre>
</p>


<li>It is probably quite common that one and only one image is bound to a Stringlist in a request. In such cases, the BindImage functionality can be achieved with the New method (:hdref reftxt=New refid=slnew.) by using an image name argument on the New method invocation:
<li>It is probably quite common that one and only one image is bound to a <var>Stringlist</var> in a request. In such cases, the <var>BindImage</var> functionality can be achieved with the <var>[[New (Stringlist constructor)|New]]</var> method by using an image name argument on the method invocation:


<pre>
<p class="code">%list is object stringList
%list is object stringList
...
...
image customer
image customer
id is string len 8
  id is string len 8
lname is string len 32
  lname is string len 32
end image
end image
...
...
%list = new('CUSTOMER')
%list = new('CUSTOMER')
</pre>
</p></ol>
</ol>


[[Category:Stringlist methods|BindImage function]]
==See also==
{{Template:Stringlist:BindImage footer}}

Latest revision as of 13:44, 19 January 2022

Associate a Stringlist with an image (Stringlist class)


This method associates or binds an image to a Stringlist. BindImage is a subroutine that accepts one argument, an image name, and does not return anything.

Syntax

sl:BindImage( imageName)

Syntax terms

sl A Stringlist object.
imageName A string that contains the name of an image. This argument is case sensitive. That is, in the likely event the User Language was written in mixed case, with automatic upper-casing in effect, the image name should be in uppercase.

Usage notes

  • All errors in BindImage result in request cancellation.
  • These methods can use the association between an image and a Stringlist:
  • The association between an image and a Stringlist is generally used when all Stringlist items have the same layout as the image. Methods that create a new Stringlist usually propagate the image binding from the method Stringlist to the output Stringlist.
  • A BindImage done inside a subroutine or method is not undone/popped when the subroutine or method returns, so care must be taken when adding a BindImage against a subroutine/method parameter as the subroutine/method caller must restore its own BindImage in such a case.

Examples

  1. Once an image is bound to a Stringlist, methods that operate on an image can omit the image name parameter. This is not only convenient from a coding perspective, it is more efficient — no image name lookup needs to be done in NTBL. The following example illustrates such a use of BindImage:

    %list is object stringList ... image customer id is string len 8 lname is string len 32 end image ... %list = new %list:bindImage('CUSTOMER') ... for each record in %recset %customer:id = id %customer:lname = lname %list:addImage end for

  2. BindImage could also enable the Sort and SortNew methods to use the names of image items in the sort criteria rather than column numbers, for example, where a Stringlist has a layout described by an image:

    %list is object stringList ... image customer id is string len 8 lname is string len 32 end image ... %list = new %list:bindImage('CUSTOMER') ... %list:sort('LNAME,A ID,D')

  3. It is probably quite common that one and only one image is bound to a Stringlist in a request. In such cases, the BindImage functionality can be achieved with the New method by using an image name argument on the method invocation:

    %list is object stringList ... image customer id is string len 8 lname is string len 32 end image ... %list = new('CUSTOMER')

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=BindImage_(Stringlist_subroutine)&oldid=118320"