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 (35,0) 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 bin(18) 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 bin(18) 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 (35,0) 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 bin(18) 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 (63,0) 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 (63,0) 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 bin(18) 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 bin(1)); 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 bin(18) 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);