$ListRepI: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:$ListRepI}} <span class="pageSubtitle"><section begin="desc" />Replace $list item with an image<section end="desc" /></span> <p class="warning">Most Sirius $funct...")
 
 
(57 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListRepI}}
{{DISPLAYTITLE:$ListRepI}}
<span class="pageSubtitle"><section begin="desc" />Replace $list item with an image<section end="desc" /></span>
<span class="pageSubtitle">Replace $list item with an image</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListRepI function is [[to be entered]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListRepI function is <var>[[ReplaceImage (Stringlist function)|ReplaceImage]]</var>.</p>


This function replaces a $list item with the contents of an image. Generally, this $list would have been created with the $ListNew function.  
This function replaces a $list item with the contents of an image. Generally, this $list would have been created with the <var>$ListNew</var> function.  


The $ListRepI function accepts four arguments and returns a numeric result. It is a callable $function (:hdref refid=callfun.).  
The <var>$ListRepI</var> function accepts four arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function.  


The first argument is a $list identifier. This is a required argument.  
The first argument is a $list identifier. This is a required argument.  
Line 12: Line 12:
The second argument is the item number which the image is to replace. This is a required argument.  
The second argument is the item number which the image is to replace. This is a required argument.  


The third argument can either be a string containing the name of an image or any image item from the required image. This is an optional argument if an image has been associated with the $list with a $ListImg (:hdref refid=listimg.) function. Otherwise, it is a required argument.  
The third argument can either be a string containing the name of an image or any image item from the required image. This is an optional argument if an image has been associated with the $list with a <var>[[$ListImg]]</var> function. Otherwise, it is a required argument.
 
The fourth argument is a number that indicates the length of the $list item after the replacement. This is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under <var class="product">[[Sirius Mods]]</var> Version 6.2 and later, and 4096 before. If this value is longer than the length of the image, the image is padded on the right with blanks. If this value is shorter than the length of the image, the image is truncated. If this argument is not specified, the new length of the $list item is the length of the replacement image.


The fourth argument is a number that indicates the length of the $list item after the replacement. This is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under ''[[Sirius Mods]]'' Version 6.2 and later, and 4096 before. If this value is longer than the length of the image, the image is padded on the right with blanks. If this value is shorter than the length of the image, the image is truncated. If this argument is not specified, the new length of the $list item is the length of the replacement image.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListRepI(list_id, item_num, image_id, length)
<p class="syntax">[%RESULT =] $ListRepI(list_id, item_num, image_id, length)
<section end="syntax" /></p>
<p class="caption">$ListRepI Function
</p>
</p>
<p class="caption">%RESULT is set to 0 if the new item length is the same as the replaced item length, 1 if it is shorter, 2 if it is longer, or a negative number if an error has occurred.</p>
 
<p class="code">  
<p><var class="term">%result</var> is set to 0 if the new item length is the same as the replaced item length, 1 if it is shorter, 2 if it is longer, or a negative number if an error has occurred.</p>
-3 - No room to add item
 
(if LISTFC $SirParm parameter not set)
===Error codes===
All other errors cause request cancellation
<p class="code">-3 - No room to add item
</p>
          (if LISTFC <var>$SirParm</var> parameter not set)
<p class="caption">$ListRepI Error Codes
All other errors cause request cancellation
</p>
</p>


==Usage notes==
<ul>
<li>The following example demonstrates how <var>$ListRepI</var> can be used to maintain the last copy of an image for a particular ID in a $list:


The following example demonstrates how $ListRepI can be used to maintain the last copy of an image for a particular ID in a $list.
<p class="code">IMAGE CUST
<p class="code">  
  SSN IS STRING LEN 10
IMAGE CUST
  NAME IS STRING LEN 20
SSN IS STRING LEN 10
  BDATE IS STRING LEN 8
NAME IS STRING LEN 20
END IMAGE
BDATE IS STRING LEN 8
. . .
END IMAGE
%LIST = $ListNew
   
   
. . . .
REPEAT FOREVER
  READ IMAGE CUST
%LIST = $ListNew
  IF $STATUS THEN
      LOOP END
REPEAT FOREVER
  END IF
READ IMAGE CUST
  %N = $ListLoc(%LIST, ,%CUST:SSN, 'SSN')
IF $STATUS THEN
  IF %N LT 0 THEN
LOOP END
      %RC = $ListAddI(%LIST, 'CUST')
END IF
  ELSE
%N = $ListLoc(%LIST, ,%CUST:SSN, 'SSN')
      %RC = $ListRepI(%LIST, %N, 'CUST')
IF %N LT 0 THEN
  END IF
%RC = $ListAddI(%LIST, 'CUST')
END REPEAT
ELSE
%RC = $ListRepI(%LIST, %N, 'CUST')
END IF
END REPEAT
</p>
</p>


The above example can be made more efficient by coding the <var>$ListRepI</var> as follows:


The above example can be made more efficient by coding the $ListRepI as follows.
<p class="code">%RC = $ListRepI(%LIST, %N, %CUST:NAME)
<p class="code"> %RC = $ListRepI(%LIST, %CUST:NAME)
</p>
</p>
The specific image item is irrelevant in this call but is more efficient than specifying the image name in quotes because in the first example, the image name must be hashed and looked up (in NTBL) in each invocation of $ListRepI while in the second example, the hashing of the image name and lookup happens only once; at compile time.


An even neater and equally efficient way of coding this would be
The specific image item is irrelevant in this call, but is more efficient than specifying the image name in quotes: In the first example, the image name must be hashed and looked up (in NTBL) in each invocation of <var>$ListRepI</var>, while in the second example, the hashing of the image name and lookup happens only once, and that is at compile time.
<p class="code"> %RC = $ListImg(%LIST, %CUST:BDATE)
<p>
Here is an even neater and equally efficient way of coding this:
 
<p class="code">%RC = $ListImg(%LIST, %CUST:BDATE)
   
   
REPEAT FOREVER
REPEAT FOREVER
. . . . . .
  . . .  
IF %N LT 0 THEN
  IF %N LT 0 THEN
%RC = $ListAddI(%LIST)
      %RC = $ListAddI(%LIST)
ELSE
  ELSE
%RC = $ListRepI(%LIST, %N)
      %RC = $ListRepI(%LIST, %N)
END IF
  END IF
</p>
</p>
In this last example, $ListImg associates the image with the $list, eliminating the need to specify the image name on the $ListRepI. This association is also useful in many other function calls in that it provides a structure to be associated with the $list that is useful for column oriented functions such as $ListLoc and $ListSrt.


$ListRepI is extremely efficient if the $list item size is not being changed (return value for $ListRep of 0), fairly efficient when a $list item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a $list item is being replaced with a longer string (return value of 2). The latter case can be expensive because such a $ListRepI can result in the splitting of a $list leaf page.  
In this last example, [[$ListImg]] associates the image with the $list, eliminating the need to specify the image name on the <var>$ListRepI</var>. This association is also useful in many other function calls in that it provides a structure to be associated with the $list that is useful for column oriented functions such as [[$ListLoc]] and [[$ListSort and $ListSrt|ListSrt]].  


Once a leaf page is split, it will not be merged back together, even if subsequent $LISTREMs make this possible. Because of this, heavy use of $LISREPIs that increase $list item size (and $ListIns and $ListRem) can result in "sparse&CQ. $lists, which places an unnecessary burden on the buffer pool and CCATEMP. It can also result in an inability to add an item to the end of the $list (via $ListAdd) because of a full pointer page, even though the $list is nowhere near the theoretical capacity for a $list. $List compression can be done using the $List_Copy_Items function, documented in :hdref refid=listcit..<p>
<li><var>$ListRepI</var> is extremely efficient if the $list item size is not being changed (return value for [[$ListRep]] of 0), fairly efficient when a $list item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a $list item is being replaced with a longer string (return value of 2). The latter case can be expensive because such a <var>$ListRepI</var> can result in the splitting of a $list leaf page.
<p>
Once a leaf page is split, it will not be merged back together, even if subsequent $LISTREMs make this possible. Because of this, heavy use of $LISREPIs that increase $list item size (and <var>$ListIns</var> and [[$ListRem]]) can result in "sparse". $lists, which places an unnecessary burden on the buffer pool and CCATEMP. It can also result in an inability to add an item to the end of the $list (via [[$ListAdd]]) because of a full pointer page, even though the $list is nowhere near the theoretical capacity for a $list. $List compression can be done using the [[$List_Copy_Items]] function. </p>
</ul>


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|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 $ListRepI
</p>
[[Category:$Functions|$ListRepI]]
[[Category:$Functions|$ListRepI]]

Latest revision as of 00:45, 26 May 2023

Replace $list item with an image

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListRepI function is ReplaceImage.

This function replaces a $list item with the contents of an image. Generally, this $list would have been created with the $ListNew function.

The $ListRepI function accepts four arguments and returns a numeric result. It is a callable $function.

The first argument is a $list identifier. This is a required argument.

The second argument is the item number which the image is to replace. This is a required argument.

The third argument can either be a string containing the name of an image or any image item from the required image. This is an optional argument if an image has been associated with the $list with a $ListImg function. Otherwise, it is a required argument.

The fourth argument is a number that indicates the length of the $list item after the replacement. This is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under Sirius Mods Version 6.2 and later, and 4096 before. If this value is longer than the length of the image, the image is padded on the right with blanks. If this value is shorter than the length of the image, the image is truncated. If this argument is not specified, the new length of the $list item is the length of the replacement image.

Syntax

[%RESULT =] $ListRepI(list_id, item_num, image_id, length)

%result is set to 0 if the new item length is the same as the replaced item length, 1 if it is shorter, 2 if it is longer, or a negative number if an error has occurred.

Error codes

-3 - No room to add item (if LISTFC $SirParm parameter not set) All other errors cause request cancellation

Usage notes

  • The following example demonstrates how $ListRepI can be used to maintain the last copy of an image for a particular ID in a $list:

    IMAGE CUST SSN IS STRING LEN 10 NAME IS STRING LEN 20 BDATE IS STRING LEN 8 END IMAGE . . . %LIST = $ListNew REPEAT FOREVER READ IMAGE CUST IF $STATUS THEN LOOP END END IF %N = $ListLoc(%LIST, ,%CUST:SSN, 'SSN') IF %N LT 0 THEN %RC = $ListAddI(%LIST, 'CUST') ELSE %RC = $ListRepI(%LIST, %N, 'CUST') END IF END REPEAT

    The above example can be made more efficient by coding the $ListRepI as follows:

    %RC = $ListRepI(%LIST, %N, %CUST:NAME)

    The specific image item is irrelevant in this call, but is more efficient than specifying the image name in quotes: In the first example, the image name must be hashed and looked up (in NTBL) in each invocation of $ListRepI, while in the second example, the hashing of the image name and lookup happens only once, and that is at compile time.

    Here is an even neater and equally efficient way of coding this:

    %RC = $ListImg(%LIST, %CUST:BDATE) REPEAT FOREVER . . . IF %N LT 0 THEN %RC = $ListAddI(%LIST) ELSE %RC = $ListRepI(%LIST, %N) END IF

    In this last example, $ListImg associates the image with the $list, eliminating the need to specify the image name on the $ListRepI. This association is also useful in many other function calls in that it provides a structure to be associated with the $list that is useful for column oriented functions such as $ListLoc and ListSrt.

  • $ListRepI is extremely efficient if the $list item size is not being changed (return value for $ListRep of 0), fairly efficient when a $list item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a $list item is being replaced with a longer string (return value of 2). The latter case can be expensive because such a $ListRepI can result in the splitting of a $list leaf page.

    Once a leaf page is split, it will not be merged back together, even if subsequent $LISTREMs make this possible. Because of this, heavy use of $LISREPIs that increase $list item size (and $ListIns and $ListRem) can result in "sparse". $lists, which places an unnecessary burden on the buffer pool and CCATEMP. It can also result in an inability to add an item to the end of the $list (via $ListAdd) because of a full pointer page, even though the $list is nowhere near the theoretical capacity for a $list. $List compression can be done using the $List_Copy_Items function.

Products authorizing $ListRepI