1 :Info: translator_temp_:  2020-11-20  translator_temp_
  2 
  3 Function:  This subroutine provides an inexpensive temporary storage
  4 management facility for translators in the Tools Library.  It uses the
  5 get_temp_segment_ subroutine to obtain temporary segments in the
  6 user's process directory.  Each segment begins with a header that
  7 defines the amount of free space remaining in the segment.  An entry
  8 is provided for allocating space the temporary segment.  If the
  9 requested space is not available in the temporary segment, the chain
 10 is extended; the current and subsequent allocations come from that
 11 extension segment.
 12 
 13 
 14 :Entry: get_segment:  2020-08-09  translator_temp_$get_segment
 15 
 16 Function:  This entry point should be called by each program
 17 activation to obtain the first temporary segment used during that
 18 activation.  Before the activation ends, the program should release
 19 the temporary segment for use by other programs.  (See the
 20 translator_temp_$release_all_segments entry point.)
 21 
 22 
 23 Syntax:
 24    dcl translator_temp_$get_segment entry (char(*) aligned, ptr,
 25           fixed bin(35));
 26    call translator_temp_$get_segment (program_id, Psegment, code);
 27 
 28 
 29 Arguments:
 30 program_id
 31    is the name of the program that is using the temporary segment.
 32    (Input)  This name is printed out by the list_temp_segments
 33    command.
 34 Psegment
 35    points to the temporary segment that was created. (Output)
 36 code
 37    is a status code. (Output)
 38 
 39 
 40 :Entry: allocate:  2020-08-09  translator_temp_$allocate
 41 
 42 Function:  This entry point can be called to allocate a block of space
 43 within a temporary segment.
 44 
 45 
 46 Syntax:
 47    dcl translator_temp_$allocate entry (ptr, fixed bin) returns (ptr);
 48    Pspace = translator_temp_$allocate (Psegment, Nwords);
 49 
 50 
 51 Arguments:
 52 Psegment
 53    points to the temporary segment in which space is to be allocated.
 54    (Input/Output)  Psegment must be passed by reference rather than by
 55    value, because the allocation routine may change its value if there
 56    is insufficient space in the current temporary segment to perform
 57    the allocation.
 58 Nwords
 59    number of words to be allocated. (Input)  It must not be greater
 60    than sys_info$max_seg_size-32.
 61 Pspace
 62    points to the space that was allocated. (Output)  The returned
 63    space contains all "0"b bits.
 64 
 65 
 66 Notes:
 67 A program that must perform many allocations can include the
 68 translator_temp_alloc.incl.pl1.  This include file contains a PL/I
 69 quick internal procedure called allocate that can be called like
 70 translator_temp_$allocate as shown above.
 71 
 72 
 73 :Entry: empty_all_segments:  2020-11-20  translator_temp_$empty_all_segments
 74 
 75 Function:  This entry point can be called by a program activation to
 76 empty storage allocated in all temporary segments (obtained earlier by
 77 calling translator_temp_$get_segment or $get_next_segment).  All except
 78 the first temporary segment are released back to the get_temp_segment_
 79 pool.  Storage in the given temporary segment is freed, and its
 80 no-free storage area is initialized to all "0"b bits.
 81 
 82 
 83 Syntax:
 84    dcl translator_temp_$empty_all_segments (ptr, fixed bin(35));
 85    call translator_temp_$empty_all_segments (Psegment, code);
 86 
 87 
 88 Arguments:
 89 Psegment
 90    points to one of the temporary segments obtained previously.
 91    (Input/Output)  Psegment must be passed by reference rather than by
 92    value, because the empty mechanism may change its value if the
 93    input value points to an extension segment in the list of temporary
 94    segments.  Upon return, Psegment points to the first segment of the
 95    translator_temp_ list.
 96 code
 97    is a status code. (Output)
 98 
 99 
100 :Entry: get_next_segment:  2020-08-09  translator_temp_$get_next_segment
101 
102 Function:  This entry point can be called by a program activation to
103 obtain an additional temporary segment for allocations.  The new
104 segment is chained to the initial temporary segment returned by
105 translator_temp_$get_segment.
106 
107 
108 Syntax:
109    dcl translator_temp_$get_next_segment (ptr, ptr, fixed bin(35));
110    call translator_temp_$get_next_segment (Psegment, Pnew_segment,
111         code);
112 
113 
114 Arguments:
115 Psegment
116    points to one of the temporary segments obtained previously.
117    (Input)
118 Pnew_segment
119    points to the new temporary segment. (Output)
120 code
121    is a status code. (Output)
122 
123 
124 :Entry: release_all_segments:  2020-08-09  translator_temp_$release_all_segments
125 
126 Function:
127 This entry point releases all of the temporary segments used by a
128 program activation for use by other programs.  It truncates these
129 segments to conserve space in the process directory.  It should be
130 called by each program activation that uses temporary segments before
131 the activation is terminated.
132 
133 
134 Syntax:
135    dcl translator_temp_$release_all_segments entry (ptr,
136       fixed bin(35));
137    call translator_temp_$release_all_segments (Psegment, code);
138 
139 
140 Arguments:
141 Psegment
142    points to any one of the temporary segments. (Input)
143 code
144    is a status code. (Output)
145 
146 
147 :Entry: release_segment:  2020-08-09  translator_temp_$release_segment
148 
149 Function:
150 This entry point releases one of the temporary segments used by a
151 program activation.  It truncates the segment to conserve space in the
152 process directory.
153 
154 
155 Syntax:
156    dcl translator_temp_$release_segment entry (ptr, fixed bin(35));
157    call translator_temp_$release_segment (Psegment, code);
158 
159 
160 Arguments:
161 Psegment
162    points to the temporary segment to be released. (Input)
163 code
164    is a status code. (Output)
165 
166 
167 :hcom:
168 
169 /****^  HISTORY COMMENTS:
170   1) change(2020-08-13,GDixon), approve(2020-11-30,MCR10083),
171      audit(2020-12-20,Swenson), install(2020-12-20,MR12.6g-0049):
172      A) Create info segment documenting all translator_temp_ entrypoints.
173                                                    END HISTORY COMMENTS */