1 01/30/84  sort_seg_
  2 
  3 The sort_seg_ subroutine provides entry points for sorting segments and
  4 character strings.  It is the subroutine interface used by the sort_seg
  5 command, and provides all of the facilities of this command at a
  6 subroutine level.
  7 
  8 
  9 Entry points in sort_seg_:
 10    (List is generated by the help command)
 11 
 12 
 13 :Entry:  seg:  09/07/83 sort_seg_$seg
 14 
 15 
 16 Function:  This entry point sorts an entire segment.  The sorted output
 17 can either replace the original segment or be written into a new
 18 segment.
 19 
 20 
 21 Syntax:
 22 declare sort_seg_$seg entry (char(*), ptr, char(*), char(*), char(*),
 23      char(*), fixed bin(21), fixed bin(21), fixed bin(35));
 24 call sort_seg_$seg (caller, ss_info_ptr, in_dir, in_ent, out_dir,
 25      out_ent, out_len, undelim_char_index, code);
 26 
 27 
 28 Arguments:
 29 caller
 30    specifies the name of the calling procedure.  Temporary segments
 31    used for sort work space will be obtained in the caller's name, and
 32    the user may be asked questions in the caller's name when errors
 33    occur.  (Input)
 34 ss_info_ptr
 35    points to a structure which defines the type of sorting to be
 36    performed, the sort field specifications, and so forth.  The caller
 37    must set all structure elements before calling sort_seg_ entry
 38    points.  This info structure is declared in sort_seg_info.incl.pl1.
 39    (Input)
 40 in_dir
 41    pathname of the directory containing the segment to be sorted.
 42    (Input)
 43 
 44 
 45 in_ent
 46    entryname of the segment to be sorted.  (Input)
 47 out_dir
 48    pathname of the directory in which the sorted results are to be
 49    placed.  (Input)
 50 out_ent
 51    entryname of the segment in which the sorted results are placed.
 52    The same segment may be identified by in_dir/in_ent and
 53    out_dir/out_ent, in which case the input segment is replaced by the
 54    sorted results.  (Input)
 55 out_len
 56    the length in characters of the sorted results.  This may be useful
 57    if the caller wants to examine or print the sorted results.
 58    However, the caller need not truncate or set the bit count for the
 59    output segment.  sort_seg_ performs these functions.  (Output)
 60 
 61 
 62 undelim_char_index
 63    if characters are found following the last sort string delimiter in
 64    the input segment, then this is the character index of the first
 65    such character in the sorted output results.  Such undelimited
 66    characters always appear at the end of the sorted output.  It is 0
 67    if no such undelimited characters are found in the input segment.
 68    Output)
 69 code
 70    is a system status code.  If code is nonzero, then sort_seg_ will
 71    already have printed an error message via sub_err_.  (Output)
 72 
 73 
 74 Access required:
 75 To use the sort_seg_$seg interface, the user must have read access to
 76 the segment being sorted, and rw access to the output segment.  If the
 77 user lacks rw access to the output segment, sort_seg_$seg will ask if
 78 access should be temporarily set to allow sorting.
 79 
 80 
 81 :Entry:  string:  09/07/83 sort_seg_$string
 82 
 83 
 84 Function:  This entry point sorts the contents of a character string.
 85 The sorted output can either replace the original string or be written
 86 into another string.
 87 
 88 
 89 Syntax:
 90 declare sort_seg_$string entry (char(*), ptr, char(*), char(*),
 91      fixed bin(21), fixed bin(21), fixed bin(35));
 92 call sort_seg_$string (caller, ss_info_ptr, in_string, out_string,
 93      out_len, undelim_char_index, code);
 94 
 95 
 96 Arguments:
 97 caller
 98    specifies the name of the calling procedure.  Temporary segments
 99    used for sort work space will be obtained in the caller's name, and
100    the user may be asked questions in the caller's name when errors
101    occur.  (Input)
102 ss_info_ptr
103    points to a structure which defines the type of sorting to be
104    performed, the sort field specifications, and so forth.  The caller
105    must set all structure elements before calling sort_seg_ entry
106    points.  This info structure is declared in sort_seg_info.incl.pl1.
107    (Input)
108 
109 
110 in_string
111    the string to be sorted.  (Input)
112 out_string
113    the string in which the sorted results are placed.  The same string
114    may be given for both in_string and out_string, in which case the
115    sorted results overwrite the in_string.  The out_string may also
116    overlap part of the storage for in_string.  When the overlapping is
117    partial or complete, the in_string is copied into a temporary
118    segment prior to being sorted.  (Output)
119 out_len
120    the length in characters of the sorted results.  (Output)
121 
122 
123 undelim_char_index
124    if characters are found following the last sort string delimiter in
125    the input string, then this is the character index of the first such
126    character in the sorted output results.  Such undelimited characters
127    always appear at the end of the sorted output.  It is 0 if no such
128    undelimited characters are found in the input string.  (Output)
129 code
130    is a system status code.  If code is nonzero, then sort_seg_ will
131    already have printed an error message via sub_err_.  (Output)