1 02/02/84 sort_items_indirect_
2
3 Function: provides a facility for sorting a group of data items, based
4 upon the value of an information field that is logically associated
5 with each item but resides at a varying offset from the beginning of
6 each item.
7
8
9 Notes: This procedure differs from that used in the sort_items_
10 subroutine in that an array of indices into the vector is sorted
11 rather than the vector itself. This allows the caller to create two
12 vectors of pointers: one containing pointers to the data items to be
13 sorted and one containing pointers to the particular data field within
14 each item on which the item is to be sorted. There is a one-to-one
15 correspondence between the elements of the data items vector and the
16 elements of the data field within each item vector. This
17 correspondence is maintained across the reordering of the index array.
18 Thus, the index array provides indices into the sorted list of data
19 fields and also into the sorted list of data items containing these
20 fields.
21
22
23 Only indices are moved or copied into temporary storage. Vector
24 elements and data items remain where they were when
25 sort_items_indirect_ was invoked.
26
27 If the information field upon which the sort is based is located at a
28 known offset from the beginning of each item, then the calling program
29 can avoid creating the index array and the item vector by using the
30 sort_items_ subroutine. This subroutine cannot process adjustable
31 length fields. The field vector is passed to the sort_items_
32 subroutine, and then the elements of the item vector are computed by
33 applying the appropriate offset to the corresponding field vector
34 elements.
35
36
37 Entry points in sort_items_indirect_:
38 List is generated by the help command
39
40
41 :Entry: adj_char: 02/02/84 sort_items_indirect_$adj_char
42
43
44 Function: sorts a group of information fields, which are unaligned
45 adjustable length character strings, into ASCII collating sequence
46 order by reordering an index array. The elements in this index array
47 are indices into an array of unaligned pointers to the character
48 strings in the group.
49
50
51 Syntax:
52 declare sort_items_indirect_$adj_char ptr ptr ptr;
53 call sort_items_indirect_$adj_char v_ptr i_ptr l_ptr;
54
55
56 Arguments:
57 v_ptr
58 points to a structure containing an array of unaligned pointers to
59 the aligned fixed binary 350 numbers to be sorted. Input.
60 The structure is to be declared as follows, where n is the number
61 of elements to be sorted.
62
63 dcl 1 v aligned,
64 2 n fixed bin 18,
65 2 vector n ptr unaligned;
66
67
68 i_ptr
69 points to a structure containing an ordered array of fixed bin18
70 indices into the unaligned pointer array. Input. The structure
71 is to be declared as follows, where n is the number of elements to
72 be sorted.
73
74 dcl 1 i aligned,
75 2 n fixed bin 18,
76 2 array n fixed bin 18;
77
78
79 l_ptr
80 points to a structure containing an array of lengths of the
81 unaligned adjustable length character strings to be sorted.
82 Input. The structure is declared as follows, where n is the
83 number of elements to be sorted.
84
85 dcl 1 l aligned,
86 2 n fixed bin 18,
87 2 vector n fixed bin 21;
88
89
90 :Entry: bit: 02/02/84 sort_items_indirect_$bit
91
92
93 Function: sorts a group of information fields, which are fixed-length
94 unaligned bit strings into bit string order by reordering an index
95 array. The elements of this index array are indices into an array of
96 pointers to the bit strings in the group. Bit string ordering
97 guarantees that, if each ordered bit string is converted to a binary
98 natural number, the binary value is less than or equal to the value of
99 each of its successors.
100
101
102 Syntax:
103 declare sort_items_indirect_$bit entry ptr ptr fixed bin 24;
104 call sort_items_indirect_$bit v_ptr i_ptr length;
105
106
107 Arguments:
108 v_ptr
109 points to a structure containing an array of unaligned pointers to
110 the fixed-length unaligned bit strings to be sorted. Input The
111 structure is to be declared as follows, where n is the number of
112 elements to be sorted.
113
114 dcl 1 v aligned,
115 2 n fixed bin 18,
116 2 vector n ptr unaligned;
117
118
119 i_ptr
120 points to a structure containing an ordered array of fixed bin18
121 indices into the unaligned pointer array. Input The structure is
122 to be declared as follows, where n is the number of elements to be
123 sorted.
124
125 dcl 1 i aligned,
126 2 n fixed bin 18,
127 2 array n fixed bin 18;
128
129 length
130 is the number of bits in each string. Input
131
132
133 :Entry: char: 02/02/84 sort_items_indirect_$char
134
135
136 Function: sorts fixed-length unaligned character strings into ASCII
137 collating sequence by reordering an index array whose elements are
138 indices into a pointer array that points to the strings. All the
139 strings must be the same length.
140
141
142 Syntax:
143 declare sort_items_indirect_$char entry ptr ptr fixed bin 21;
144 call sort_items_indirect_$char v_ptr i_ptr string_lth;
145
146
147 Arguments:
148 v_ptr
149 points to a structure containing an array of unaligned pointers to
150 the fixed-length unaligned character string to be sorted. Input
151 The structure is to be declared as follows, where n is the number
152 of elements to be sorted.
153
154 dcl 1 v aligned,
155 2 n fixed bin 18,
156 2 vector n ptr unaligned;
157
158
159 i_ptr
160 points to a structure of fixed bin 18 indices into the unaligned
161 pointer array. Input The structure is to be declared as follows,
162 where n is the number of elements to be sorted.
163
164 dcl 1 i aligned,
165 2 n fixed bin 18,
166 2 array n fixed bin 18;
167
168 string_lth
169 indicates the length of each character string. Input
170
171
172 :Entry: fixed_bin: 02/02/84 sort_items_indirect_$fixed_bin
173
174
175 Function: sorts a group of information fields, which are aligned fixed
176 binary 350 numbers, into numerical order by reordering an index
177 array. The elements of this index array are indices into an array of
178 unaligned pointers to the numbers in the group.
179
180
181 Syntax:
182 declare sort_items_indirect_$fixed_bin entry ptr ptr;
183 call sort_items_indirect_$fixed_bin v_ptr i_ptr;
184
185
186 Arguments:
187 v_ptr
188 points to a structure containing an array of unaligned pointers to
189 the unaligned adjustable length character strings to be sorted.
190 Input The structure is to be declared as follows, where n is the
191 number of elements to be sorted.
192
193 dcl 1 v aligned,
194 2 n fixed bin 18,
195 2 vector n ptr unaligned;
196
197
198 i_ptr
199 points to a structure containing an ordered array of fixed bin18
200 indices into the unaligned pointer array. Input The structure is
201 to be declared as follows, where n is the number of elements to be
202 sorted.
203
204 dcl 1 i aligned,
205 2 n fixed bin 18,
206 2 array n fixed bin 18;
207
208
209 :Entry: float_bin: 02/02/84 sort_items_indirect_$float_bin
210
211
212 Function: sorts a group of information fields, which are aligned float
213 binary 630 numbers, into numerical order by reordering an index
214 array. The elements of this index array are indices into an array of
215 unaligned pointers to the numbers in the group.
216
217
218 Syntax:
219 declare sort_items_indirect_$float_bin entry ptr ptr;
220 call sort_items_indirect_$float_bin v_ptr i_ptr;
221
222
223 Arguments:
224 v_ptr
225 points to a structure containing an array of unaligned pointers to
226 the aligned float binary 630 numbers to be sorted. Input The
227 structure is to be declared as follows, where n is the number of
228 elements to be sorted.
229
230 dcl 1 v aligned,
231 2 n fixed bin 18,
232 2 vector n ptr unaligned;
233
234
235 i_ptr
236 points to a structure containing an ordered array of fixed bin18
237 indices into the unaligned pointer array. Input The structure is
238 to be declared as follows, where n is the number of elements to be
239 sorted.
240
241 dcl 1 i aligned,
242 2 n fixed bin 18,
243 2 array n fixed bin 18;
244
245
246 :Entry: general: 02/02/84 sort_items_indirect_$general
247
248
249 Function: sorts a group of information fields which are arbitrary
250 data elements structures or other aggregates into a user-defined
251 order. It does this by reordering an array of indices into a pointer
252 array. The elements of this index array point to the sort information
253 field within the data items of the group. The structure and data type
254 of the information field and the data ordering principle are decoupled
255 from the sorting algorithm by calling a user-supplied function to
256 order pairs of information fields. The function is called with
257 pointers to a pair of fields. It must compare the fields and return a
258 value that indicates whether the first field of the pair is less than,
259 equal to, or greater than the second field. The sorting algorithm
260 reorders the elements of the index array based upon the results of the
261 information field comparisons.
262
263
264 Syntax:
265 declare sort_items_indirect_$general entry ptr ptr entry;
266 call sort_items_indirect_$general v_ptr i_ptr function:
267
268
269 Arguments:
270 v_ptr
271 points to a structure containing an array of unaligned pointers to
272 the information fields to be sorted. Input The structure is to
273 be declared as follows, where n is the number of elements to be
274 sorted.
275
276 dcl 1 v aligned,
277 2 n fixed bin 18,
278 2 vector n ptr unaligned;
279
280
281 i_ptr
282 points to a structure containing an ordered array of fixed bin 18
283 indices into the unaligned pointer array. Input The structure is
284 to be declared as follows, where n is the number of elements to be
285 sorted.
286
287 dcl 1 i aligned,
288 2 n fixed bin 18,
289 2 array n fixed bin 18;
290
291 function
292 is a user-supplied ordering function. Input See "Notes" below.
293
294
295 Notes:
296 The sort_items_indirect_$general entry point calls a user-supplied
297 function to compare pairs of data items. This function must know the
298 structure and data type of the information fields, and it must know the
299 ordering principle to be used to compare a pair of information fields.
300 The function returns a relationship code as its value. The calling
301 sequence of the function is as follows:
302
303 declare function entry ptr unaligned ptr unaligned
304 returns fixed bin1;
305 value = function ptr_1st_field ptr_2nd_field;
306
307
308 ptr_1st_field
309 is an unaligned pointer to the first information field. Input
310 ptr_2nd_field
311 is an unaligned pointer to an information field to be compared with
312 the first information field. Input
313 value
314 is the value of the first information field compared to the second
315 information field. Output. It can be:
316 -1 first information field is less than the second.
317 0 first information field is equal to the second.
318 +1 first information field is greater than the second.
319
320 A simple example of a user-supplied ordering function is shown in the
321 Subroutines manual under the sort_items_ subroutine.
322
323
324 :Entry: varying_char: 02/02/84 sort_items_indirect_$varying_char
325
326
327 Function: sorts a group of information fields, which are varying
328 unaligned character strings, into ASCII collating sequence by
329 reordering an index array. The elements of this index array are
330 indices into an array of pointers to the character strings in the
331 group.
332
333
334 Syntax:
335 declare sort_items_indirect_$varying_char entry ptr ptr;
336 call sort_items_indirect_$varying_char v_ptr i_ptr;
337
338
339 Arguments:
340 v_ptr
341 points to a structure containing an array of unaligned pointers to
342 the varying fixed-length character strings to be sorted. Input
343 The structure is to be declared as follows, where n is the number
344 of elements to be sorted.
345
346 dcl 1 v aligned,
347 2 n fixed bin 18,
348 2 vector n ptr unaligned;
349
350
351 i_ptr
352 points to a structure containing an ordered array of fixed bin18
353 indices into the unaligned pointer array. Input The structure is
354 to be declared as follows, where n is the number of elements to be
355 sorted.
356
357 dcl 1 i aligned,
358 2 n fixed bin 18,
359 2 array n fixed bin 18;