1 04/15/86  set_ext_variable_
  2 
  3 
  4 To obtain information on a particular entry point use the "ep" request
  5 
  6 
  7 Entry points in set_ext_variable_:
  8    (List is generated by the help command)
  9 
 10 
 11 :Entry:  set_ext_variable_:  04/15/86  set_ext_variable_
 12 
 13 
 14 Function: allows the caller to look up an external variable by name.
 15 If the name is not found, the variable is created.
 16 
 17 
 18 Syntax:
 19 declare set_ext_variable_ entry (char(*), ptr, ptr, bit(1) aligned,
 20      ptr, fixed bin(35));
 21 call set_ext_variable_ (ext_name, init_info_ptr, sb_ptr, found_sw,
 22      node_ptr, code);
 23 
 24 
 25 Arguments:
 26 ext_name
 27    is the name of the external variable.  (Input)
 28 init_info_ptr
 29    is a pointer to the initialization info (see "Notes on
 30    init_info structure").
 31    (Input)
 32 sb_ptr
 33    is a pointer to the base of the stack of the caller.  (Input)
 34 found_sw
 35    is set to indicate whether the variable was found or not.
 36    (Output)
 37 
 38 
 39 node_ptr
 40    is a pointer to the external variable node.  (see "Notes on
 41    variable_node structure")
 42    (Output)
 43 code
 44    is an error code.  (Output)
 45 
 46 
 47 
 48 :Entry:  locate:  04/15/86 set_ext_variable_$locate
 49 
 50 
 51 Function: This entry point locates the specified external variable
 52 and returns a pointer to the structure describing the variable.
 53 
 54 
 55 Syntax:
 56 dcl set_ext_variable_$locate entry (char(*), ptr, ptr,
 57     fixed bin(35));
 58 call set_ext_variable_$locate (ext_name, sb_ptr, node_ptr, code);
 59 
 60 
 61 Arguments:
 62 ext_name
 63    is the name of the external variable.  (Input)
 64 sb_ptr
 65    is a pointer to the base of the stack of the caller.  (Input)
 66 node_pointer
 67    is a pointer to the variable_node describing the specified
 68    variable.  This structure is defined in the
 69    system_link_names.incl.pl1 include file.  (see "Notes on
 70    variable_node structure")
 71    (Output)
 72 code
 73    is an error code.  (Output)
 74 
 75 
 76 :Entry:  star_heap:  04/15/86  set_ext_variable_$star_heap
 77 
 78 
 79 Function: allows the caller to look up heap variables by name.  If
 80 the name is not found, the variable is created and added to the
 81 list of heap variables.
 82 
 83 
 84 Syntax:
 85 declare set_ext_variable_$star_heap entry (char(*), ptr, ptr, ptr
 86    bit(1) aligned, ptr, fixed bin(35));
 87 call set_ext_variable_$star_heap (ext_name, init_info_ptr, sb_ptr,
 88   seg_ptr, found_sw, node_ptr, code);
 89 
 90 
 91 Arguments:
 92 ext_name
 93    is the name of the external variable.  (Input)
 94 init_info_ptr
 95    is a pointer to the initialization info (see "Notes on
 96    init_info structure").
 97    (Input)
 98 sb_ptr
 99    is a pointer to the base of the stack of the caller.  (Input)
100 seg_ptr
101    is a pointer to the segment containing the object to be
102    initialized. (Input).
103 found_sw
104    is set to indicate whether the variable was found or not.
105    (Output)
106 
107 
108 node_ptr
109    is a pointer to the external variable node.
110    (see "Notes on variable_node structure") (Output)
111 code
112    is an error code.  (Output)
113 
114 
115 :Entry:  pointer:  04/15/86  set_ext_variable_$pointer
116 
117 
118 Function: allows the caller to create a system external variable
119 using list_init_ pointer intialization.
120 
121 
122 Syntax:
123 declare set_ext_variable_$pointer entry (char(*), ptr, ptr, ptr
124    bit(1) aligned, ptr, fixed bin(35));
125 call set_ext_variable_$pointer (ext_name, init_info_ptr, sb_ptr,
126   seg_ptr, found_sw, node_ptr, code);
127 
128 
129 Arguments:
130 ext_name
131    is the name of the external variable.  (Input)
132 init_info_ptr
133    is a pointer to the initialization info (see "Notes on
134    init_info structure").
135    (Input)
136 sb_ptr
137    is a pointer to the base of the stack of the caller.  (Input)
138 seg_ptr
139    is a pointer to the segment containing the object to be
140    initialized. (Input).
141 found_sw
142    is set to indicate whether the variable was found or not.
143    (Output)
144 
145 
146 node_ptr
147    is a pointer to the external variable node.
148    (see "Notes on variable_node structure") (Output)
149 code
150    is an error code.  (Output)
151 
152 
153 Notes on init_info structure:
154 When a new external variable is allocated (not found), it must be
155 initialized.  The following structure, described in
156 system_link_init_info.incl.pl1, is pointed to by init_info_ptr:
157 
158    dcl 1 init_info           aligned based,
159          2 size              fixed bin(19),
160          2 type              fixed bin,
161          2 init_template
162       (init_size refer
163       (init_info.size))      fixed bin(35);
164 
165 
166    Structure elements:
167    size
168       is the initialization template size, in words.
169    type
170       is the type of initialization to be performed.
171       0 no init
172       1 invalid
173       2 invalid
174       3 init from template
175       4 init area to empty ()
176       5 list_template intialization (see "Notes on
177         list_template initialization structure").
178    init_template
179       is the initialization template to be used when type = 3.
180 
181 
182 Notes on list_template initialization structure:
183 When the initialization type is 5 or a list_template
184 initialization is being performed the init_info structure is not
185 used.  The structure used is the list_init_info structure which
186 has the following definition in system_link_init_info.incl.pl1 :
187 
188 dcl       1 list_init_info         aligned based,
189             2 size                 fixed bin (35),
190             2 type                 fixed bin,
191             2 pad                  bit (18) unaligned,
192             2 list_size            fixed bin (18)
193                                    unsigned unaligned,
194             2 template             (0 refer
195                                    (list_init_info.list_size))
196                                    bit (36);
197 
198 
199    Structure Elements:
200    size
201       is the size of the variable in words.
202    type
203       is the type of initialization to be performed.
204       5 list_template
205    list_size
206      is the number of list_template_entries that make up the
207      template.
208 
209 
210    template
211      takes the form of a list_template_entry structure as defined
212      in system_link_init_info.incl.pl1.  This structure is passed
213      on to list_init_ and decoded into data which is copied to the
214      variable.  See the description of list_init_ in the
215      Privileged Subroutines Manual for a more complete
216      description.
217 
218 
219 Notes on variable_node structure:
220 Great care should be taken when using the node_ptr.  The
221 variable_node structure should never be modified.  Modifications
222 to the variable_node will have unpredictable results.
223 
224 A pointer to the following structure is returned by the entry
225 points in this subroutine.  It is declared in
226 system_link_names.incl.pl1.
227 
228    dcl 1 variable_node       aligned based,
229          2 forward_thread    ptr unaligned,
230          2 vbl_size          fixed bin(23) unaligned,
231          2 init_type         fixed bin(11) unaligned,
232          2 time_allocated    fixed bin(71),
233          2 vbl_ptr           ptr,
234          2 init_ptr          ptr,
235          2 name_size         fixed bin(21) aligned,
236          2 name              char (nchars refer
237                              (variable_node.name_size)),
238          2 seg_ptr           ptr;
239 
240 
241    Structure elements:
242    forward_thread
243       is used by the linker to thread this variable to the
244       next.
245    vbl_size
246       is the size, in words, of this variable.
247    init_type
248       is the type of initialization that is performed:
249       0 none
250       1 invalid
251       2 invalid
252       3 initialize from template
253       4 initialize to an empty area
254       5 initialize using a list template (see "Notes on
255         list_template initialization structure").
256 
257 
258    time_allocated
259       is the clock reading at the time this variable was
260       allocated.
261    vbl_ptr
262       is a pointer to the variable's storage.
263    init_ptr
264       is a pointer to the initialization template.
265    name_size
266       is the number of characters in the variable name.
267    name
268       is the name of the variable.
269    seg_ptr
270       is a pointer to the segment containing the variables
271       initialization information.
272