$lists - Revision history

JAL: remove "Sirius"

2018-06-06T21:58:56Z

remove "Sirius"

← Older revision		Revision as of 21:58, 6 June 2018
Line 13:		Line 13:
	up with the execution of the <var>Release All Records</var> statement.		up with the execution of the <var>Release All Records</var> statement.

	Every $list has associated with it an integer called a		Every $list has associated with it an integer called a '''$list identifier.'''
	'''$list identifier'''.
	This $list identifier is guaranteed to be greater than 0.		This $list identifier is guaranteed to be greater than 0.
	Other than this, applications should not depend on the actual values for		Other than this, applications should not depend on the actual values for
	$list identifiers, because ~~Sirius~~ Software reserves the right to change		$list identifiers, because Rocket Software reserves the right to change
	these as needed.		these as needed.

JAL: /* $lists and ECF */ minor word change

2018-06-06T21:35:08Z

$lists and ECF: minor word change

← Older revision		Revision as of 21:35, 6 June 2018
Line 66:		Line 66:
	<p class="syntax"><span class="literal">EXTERNAL CALL COBPROG WITH $LIST </span><span class="term">inlist outlist</span>		<p class="syntax"><span class="literal">EXTERNAL CALL COBPROG WITH $LIST </span><span class="term">inlist outlist</span>
	</p>		</p>
	~~where~~:		Where:
	<table ~~class="syntaxTable"~~>		<table>
	<tr><th>inlist		<tr><th>inlist
	</th><td>The $list identifier to be passed to the ECF program as input.		</th><td>The $list identifier to be passed to the ECF program as input.
	</td></tr>		</td></tr>

	<tr><th>outlist		<tr><th>outlist
	</th><td>The $list identifier to receive the data as modified by the ECF program. The contents of this $list are replaced with the ECF program output. The length of the $list items are made to match that of the input $list, and if the output $list is the same identifier as the input $list, the output data simply replaces the original input data. For <code>PARMTYPE=INPUT</code> ECF programs, the output $list is ignored.		</th><td>The $list identifier to receive the data as modified by the ECF program. The contents of this $list are replaced with the ECF program output. The length of the $list items are made to match that of the input $list, and if the output $list is the same identifier as the input $list, the output data simply replaces the original input data. For <code>PARMTYPE=INPUT</code> ECF programs, the output $list is ignored.
	</td></tr></table>		</td></tr>
	The input $list is copied into the ECF parameter area before the ECF program is called.		</table>
	The $list items are concatenated and there is		The input $list is copied into the ECF parameter area before the ECF program is called. The $list items are concatenated and there is
	no way to determine where one ends and the next begins, so presumably		no way to determine where one ends and the next begins, so presumably
	the $list items would all have the same length, or some $list items		the $list items would all have the same length, or some $list items

Dme: Undo revision 45953 by Dme (talk)

2012-07-21T03:02:16Z

Undo revision 45953 by Dme (talk)

← Older revision		Revision as of 03:02, 21 July 2012
Line 37:		Line 37:
	</ul>		</ul>

	~~If CCATEMP~~ is ~~full, this~~ will ~~either be reflected by a -3~~ return code ~~from the $function~~, or it will result in request		It is possible to store as many as three gigabytes of data on a single $list.
			An attempt to store more data into a $list will return
			an error code identical to a CCATEMP full condition, or it will result in request
	cancellation, depending on the setting of the <var>[[$SirParm]]</var> <var>LISTFC</var> flag.		cancellation, depending on the setting of the <var>[[$SirParm]]</var> <var>LISTFC</var> flag.

Dme at 20:41, 20 July 2012

2012-07-20T20:41:02Z

← Older revision		Revision as of 20:41, 20 July 2012
Line 37:		Line 37:
	</ul>		</ul>

	It is ~~possible to store as many as three gigabytes of data on a single $list.~~		If CCATEMP is full, this will either be reflected by a -3 return code from the $function, or it will result in request
	~~An attempt to store more data into~~ a ~~$list will~~ return
	~~an error~~ code ~~identical to a CCATEMP full condition~~, or it will result in request
	cancellation, depending on the setting of the <var>[[$SirParm]]</var> <var>LISTFC</var> flag.		cancellation, depending on the setting of the <var>[[$SirParm]]</var> <var>LISTFC</var> flag.

JAL2: Created page with "Many Sirius $functions manipulate a data structure called a '''$list'''. A $list is a collection of variable length strings stored in CCATEMP. Each item in a $list has an associa..."

2011-10-13T21:32:11Z

Created page with "Many Sirius $functions manipulate a data structure called a '''$list'''. A $list is a collection of variable length strings stored in CCATEMP. Each item in a $list has an associa..."

New page

Many Sirius $functions manipulate a data structure called a '''$list'''.
A $list is a collection of variable length strings stored in CCATEMP.
Each item in a $list has an associated item number and no length limit.

$lists are always cleaned up (that is, their CCATEMP pages are released, hence
they can no longer be accessed)
at request termination, except in the case of global $lists.
Global $lists are $lists that were saved with <var>[[$ListSav and $ListSave|$ListSav]]</var> or
<var>[[$ListSav and $ListSave|$ListSave]]</var> (and have not been restored with <var>[[$ListRst]]</var>) or those that were
created with <var>[[$List_Global and $List_Session|$List_Global]]</var>.
All non-global $lists, except those created
with the <var>NOREL</var> attribute on <var>[[$ListNew]]</var>, are also cleaned
up with the execution of the <var>Release All Records</var> statement.

Every $list has associated with it an integer called a
'''$list identifier'''.
This $list identifier is guaranteed to be greater than 0.
Other than this, applications should not depend on the actual values for
$list identifiers, because Sirius Software reserves the right to change
these as needed.

Any function that creates a $list returns a $list identifier as its result.
The following functions create $lists:
<ul>
<li><var>[[$ListCpy]]</var>
<li><var>[[$List_Global and $List_Session|$List_Global]]</var>
<li><var>[[$ListNew]]</var>
<li><var>[[$ListNewI]]</var>
<li><var>[[$ListRst]]</var>
<li><var>[[$ListSort and $ListSrt|$ListSort]]</var>
<li><var>[[$ListSort and $ListSrt|$ListSrt]]</var>
<li><var>[[$ListSub]]</var>
<li><var>[[$PrcLEx]]</var>
<li><var>[[$PrcLExG]]</var>
<li><var>[[$Proc_List]]</var>
<li><var>[[$Proc_ListG]]</var>
</ul>

It is possible to store as many as three gigabytes of data on a single $list.
An attempt to store more data into a $list will return
an error code identical to a CCATEMP full condition, or it will result in request
cancellation, depending on the setting of the <var>[[$SirParm]]</var> <var>LISTFC</var> flag.

$lists provide several advantages over arrays:
<ul>
<li>Data is stored in CCATEMP, so less server space is used.
You can also store much more data in a $list than in an array.
<li>You do not have to know the size of your $list ahead of time.
<li>$list items are variable length, thus use only as much space
as the data requires.
<li>$functions are provided to sort, search, and subset $lists.
<li>You can delete or insert items into a $list.
</ul>

The one disadvantage of $lists relative to arrays is that
they require disk buffer pool access, hence they require a little
more CPU to access than array elements.
Also, for $lists that have not been accessed in a while, disk writes
might be performed and then a disk read might be required for each
page that has been written out.

The data associated with a $list identifier can be assigned to a
different $list identifier with the <var>[[$ListMove]]</var> function.
==$lists and ECF==
A $list identifier can be passed to an ECF program, as in:
EXTERNAL CALL COBPROG WITH $LIST inlist outlist

where:
<table class="syntaxTable">
<tr><th>inlist
</th><td>The $list identifier to be passed to the ECF program as input.
</td></tr>
<tr><th>outlist
</th><td>The $list identifier to receive the data as modified by the ECF program. The contents of this $list are replaced with the ECF program output. The length of the $list items are made to match that of the input $list, and if the output $list is the same identifier as the input $list, the output data simply replaces the original input data. For <code>PARMTYPE=INPUT</code> ECF programs, the output $list is ignored.
</td></tr></table>
The input $list is copied into the ECF parameter area before the ECF program is called.
The $list items are concatenated and there is
no way to determine where one ends and the next begins, so presumably
the $list items would all have the same length, or some $list items
have the length or number of occurrences of a following set of $list
items (which can be used in the ECF program to determine the structure of
the data).

More likely, the structure for passing data from a $list to an
ECF program will be a $list where all $list items have the same length.
To facilitate use of such a structure, the $list ECF interface automatically
places a one word (four byte) binary number of occurrences before the
copied $list items in the ECF parameter area.
This makes it possible, if the ECF program is written in COBOL, to refer
to the $list as a <code>DEPENDING</code> array where the number of occurrences
can vary at run-time.
To refer to the $list, the COBOL program would look something like this:
LINKAGE SECTION.
01 STUBB.
03 NUM-HARPOONS PIC 9(9) BINARY
03 HARPOON-INFO OCCURS 0 TO 25000 TIMES
DEPENDING ON NUM-HARPOONS.
...
PROCEDURE DIVISION USING STUBB.

If for some reason, this count is deemed undesirable in the linkage
structure, it can be suppressed via the <code>NOCOUNT</code> keyword in the <code>EXTERNAL
CALL</code> statement as in:
EXTERNAL CALL COBPROG WITH $LIST %LIST NOCOUNT

Multiple $lists and images can be passed in a single ECF call as
in:
EXTERNAL CALL COBPROG WITH $LIST %LIST, INIMAGE, $LIST %LIST2


[[Category:Overviews]]
[[Category:User Language syntax enhancements]]