1 04/20/82 value_
2
3 The value_ subroutine reads and maintains value segments containing
4 name-value pairs.
5
6
7 Entry points in value_:
8 List is generated by the help command
9
10
11 :Entry: defined: 07/16/81 value_$defined
12
13
14 Function: returns "1"b if a value is defined for name, "0"b otherwise.
15
16
17 Syntax:
18 dcl value_$defined entry ptr bit 36 char * fixed bin 35
19 returns bit 1;
20 defined_sw = value_$defined seg_ptr switches name code;
21
22
23 Arguments:
24 seg_ptr
25 is a pointer to the base of a value segment. Input See "Notes".
26 switches
27 is a bit 36 aligned word of switches: Input
28 perprocess
29 looks for a perprocess value, as opposed to one stored in any
30 value segment. Either this switch or "permanent" must be on.
31 If both switches are on, a perprocess value is returned if one
32 exists, otherwise a value stored in the value segment is
33 returned.
34 permanent
35 looks for a value stored in the value segment.
36
37
38 name
39 is a character string with at least one nonblank character.
40 Trailing blanks are trimmed. Input
41 code
42 is a standard status code. Output
43
44
45 Access required:
46 r on the value segment, except for perprocess values.
47
48
49 Notes: To initialize a new value segment, create a segment with suffix
50 "value" and call value_$init_seg with a pointer to its base. If
51 seg_ptr is null, the default value segment is used, which is initially
52 home_dir>user name.value but can be changed by value_$set_path or
53 the value_set_path vsp command.
54
55
56 :Entry: delete: 07/16/81 value_$delete
57
58
59 Function: this entry point causes there to be no value defined for
60 name.
61
62
63 Syntax:
64 dcl value_$delete entry ptr bit 36 char * fixed bin 35;
65 call value_$delete seg_ptr switches name code;
66
67
68 Arguments:
69 seg_ptr
70 is a pointer to the base of a value segment. If seg_ptr is null, the
71 default value segment is used, which is initially:
72 home_dir>user name.value
73 but can be changed by value_$set_path or the value_set_path vsp
74 command. Input
75 switches
76 is a bit 36 aligned word of switches perprocess or permanent.
77 Input
78 name
79 is a character string with at least one nonblank character.
80 Trailing blanks are trimmed. Input
81 code
82 is a standard status code. Output
83
84
85 Access required:
86 rw on the value segment, except for perprocess values.
87
88
89 :Entry: get: 07/16/81 value_$get
90
91
92 Function: returns the defined value of a name.
93
94
95 Syntax:
96 dcl value_$get entry options variable;
97 call value_$get seg_ptr switches name value_arg code;
98
99
100 Arguments:
101 seg_ptr
102 is a pointer to the base of a value segment. Input
103 switches
104 is a bit 36 aligned word of switches perprocess or permanent.
105 Input
106 name
107 is a fixed-length or varying character string. If fixed-length,
108 trailing blanks are trimmed. There must be at least one character.
109 Input
110
111
112 value_arg
113 is the returned value, having any data type. If conversion from the
114 internal character string representation cannot be performed,
115 error_table_$bad_conversion is returned. Conversion errors cannot
116 occur if value_arg is a character string, but if it has a maxlength
117 > 0, the error code error_table_$smallarg is returned if truncation
118 occurs. Output
119 code
120 is a standard error code. It is error_table_$oldnamerr "Name not
121 found." if no value is defined. Output
122
123
124 Access required:
125 r access to the value segment, except for perprocess values.
126
127
128 Notes: Perprocess values are stored in a temporary value segment in
129 the process directory, and disappear when the process terminates.
130
131
132 :Entry: get_data: 07/16/81 value_$get_data
133
134
135 Function: returns, into a caller-supplied buffer, the region of
136 storage that is defined as the value of a name, as set by either
137 value_$set_data or value_$test_and_set_data. Values set by other
138 entrypoints are not seen by value_$get_data.
139
140
141 Syntax:
142 dcl value_$get_data entry ptr bit 36 char * ptr ptr
143 fixed bin 18 fixed bin 35;
144 call value_$get_data seg_ptr switches name area_ptr data_ptr
145 data_size code;
146
147
148 Arguments:
149 seg_ptr
150 is a pointer to the base of a value segment. Input
151 switches
152 is a bit 36 aligned word of switches perprocess or permanent.
153 Input
154 name
155 is a character string with at least one nonblank character.
156 Trailing blanks are trimmed. Input
157 area_ptr
158 points to an area in which the value can be allocated. Input
159 data_ptr
160 points to the value returned. Output
161
162
163 data_size
164 is the number of words in the value. If it is greater than
165 buffer_size, only buffer_size words are returned, data_size is set
166 to the full size of the value, and error_table_$smallarg is
167 returned. Output
168 code
169 is a standard error code. It is error_table_$oldnamerr "Name not
170 found." if no value is defined. Output
171
172
173 Access required:
174 r on the value segment, except for perprocess values.
175
176
177 Notes: Perprocess values are stored in a temporary value segment in
178 the process directory, and disappear when the process terminates.
179
180
181 :Entry: get_path: 07/16/81 value_$get_path
182
183
184 Function: returns the pathname of the current default value segment
185 used by value commands without -pathname.
186
187
188 Syntax:
189 dcl value_$get_path entry char * fixed bin 35;
190 call value_$get_path path code;
191
192
193 Arguments:
194 path
195 is the pathname. Output
196 code
197 is a standard status code. Output
198
199
200 :Entry: init_seg: 07/16/81 value_$init_seg
201
202
203 Function: initializes a segment to be a value segment.
204
205
206 Syntax:
207 dcl value_$init_seg entry ptr fixed bin ptr fixed bin 19
208 fixed bin 35;
209 call value_$init_seg seg_ptr seg_type remote_area_ptr seg_size
210 code;
211
212
213 Arguments:
214 seg_ptr
215 is a pointer to a segment. Input
216 seg_type
217 determines the type of use to which the value segment will be put,
218 and therefore the method of allocating values: Input
219 0 permanent: shareable by multiple processes and therefore
220 locked when modified, with values always stored in the value
221 segment itself.
222 1 perprocess: for use only by the calling process and therefore
223 never locked, with values optionally stored in an area outside
224 the "value segment" see the remote_area_ptr argument below.
225
226
227 remote_area_ptr
228 for a perprocess segment only, points to an area outside the value
229 segment in which values are to be allocated. For example, the
230 "value segment" can be a region of storage 72 words long consisting
231 only of a header, and remote_area_ptr can point to the user's own
232 area. If remote_area_ptr is null and seg_type is 1, values are
233 allocated in the system free area. Input
234 seg_size
235 is the number of words available to the value segment, or to the
236 remote area if remote_area_ptr is nonnull. If seg_size is 0, the
237 available size is an entire segment. Input
238 code
239 is a standard status code. Output
240
241
242 Access required:
243 rw on the segment.
244
245
246 :Entry: delete_data: 04/20/82 value_$delete_data
247
248 Syntax:
249 dcl value_$delete_data entry ptr bit 36 char * fixed bin 35;
250
251 call value_$delete_data seg_ptr switches name code;
252
253
254 Function: deletes values set by value_$set_data.
255
256
257 Arguments:
258 seg_ptr
259 is a pointer to the base of a value segment. If seg_ptr is null, the
260 default value segment is used, which is initially:
261 home_dir>user name.value
262 but can be changed by value_$set_path or the value_set_path vsp
263 command. Input
264 switches
265 is a bit 36 aligned word of switches: Input
266 perprocess
267 deletes a perprocess value, as opposed to one stored in any
268 value segment. Either this switch or "permanent" must be on.
269 If both switches are on, the perprocess value is deleted if one
270 exists, otherwise the value in the value segment is deleted.
271 permanent
272 deletes a value stored in the value segment.
273 name
274 is a character string with at least one nonblank character.
275 Trailing blanks are trimmed. Input
276 code
277 is a standard status code. Output
278
279
280 Access required: rw on the value segment, except for perprocess values.
281
282
283 :Entry: list: 07/16/81 value_$list
284
285
286 Function: Given a list of starnames and regular expressions to match
287 and exclude, returns a list of variable names and their values. Only
288 values set by value_$set are returned; see value_$list_data_names to
289 list variables set by value_$set_data.
290
291
292 Syntax:
293 dcl value_$list entry ptr bit 36 aligned ptr ptr ptr
294 fixed bin 35;
295 call value_$list seg_ptr switches match_info_ptr area_ptr
296 value_list_info_ptr code;
297
298
299 Arguments:
300 seg_ptr
301 is a pointer to the base of a value segment. Input
302 switches
303 is a bit 36 word of switches perprocess or permanent. Input
304 match_info_ptr
305 is a pointer to a user-allocated structure, declared in
306 value_structures.incl.pl1. Input See "Notes on structures" below.
307 area_ptr
308 is a pointer to an area in which the output value_list_info
309 structure is to be allocated. Input
310 value_list_info_ptr
311 is a pointer to a structure, allocated by value_$list and freed by
312 the caller when done. It is also declared in the include file
313 value_structures.incl.pl1. Output See "Notes on structures".
314 code
315 is a standard status code. Output
316
317
318 Access required:
319 r on the value segment, except for perprocess values.
320
321
322 Notes: Names are returned in alphabetical order.
323
324
325 Notes on structures:
326 The match_info_ptr argument is a pointer to the following
327 user-allocated structure, declared in value_structures.incl.pl1:
328
329 dcl 1 match_info aligned based match_info_ptr,
330 2 version fixed bin, /* = 1 */
331 2 name_count fixed bin,
332 2 max_name_len fixed bin 21,
333 2 name_array alloc_name_count refer
334 match_info.name_count,
335 3 exclude_sw bit 1 unaligned,
336 3 regexp_sw bit 1 unaligned,
337 3 pad bit 34 unaligned /* = "0"b */
338 3 name char alloc_max_name_len refer
339 match_info.max_name_len varying;
340
341
342 If a name's regexp_sw is ON, the name is a regular expression to be
343 matched. Otherwise, it is a starname to be matched. If the name's
344 exclude_sw is ON, variables matching the name are excluded from the
345 list built up so far, as for the -exclude control argument to the
346 value_list command. Otherwise, matching variables are added to the
347 list.
348
349
350 The value_list_info_ptr argument is a pointer to the following
351 structure, declared in the include file value_structures.incl.pl1:
352
353 dcl 1 value_list_info aligned based value_list_info_ptr,
354 2 version fixed bin, /* = 1 */
355 2 pair_count fixed bin,
356 2 chars_len fixed bin 21,
357 2 pairs alloc_pair_count refer
358 value_list_info.pair_count,
359 3 type_switches bit 36,
360 3 name_index fixed bin 21,
361 3 name_len fixed bin 21,
362 3 value_index fixed bin 21,
363 3 value_len fixed bin 21,
364 2 chars alloc_chars_len refer
365 value_list_info.chars_len;
366
367
368 For each pair i, the variable name is:
369 substr chars name_index i name_len i
370 and the value is:
371 substr chars value_index i value_len i
372
373 The first bit in type_switches i is ON if the variable is
374 perprocess, the second is ON instead for a variable stored in the
375 value segment.
376
377 The user is responsible for freeing the value_list_info structure when
378 done.
379
380
381 :Entry: list_data_names: 04/20/82 value_$list_data_names
382
383 Syntax:
384 dcl value_$list_data_names entry ptr bit 36 aligned ptr ptr ptr
385 fixed bin 35;
386
387 call value_$list_data_names seg_ptr switches match_info_ptr
388 area_ptr value_list_info_ptr code;
389
390
391 Function: Operates exactly the same as value_$list, but returns
392 variables set by value_$set_data instead of value_$set, and does not return
393 the values. Instead, it sets value_list_info.value_len to the number of
394 words in the value.
395
396
397 Arguments:
398 are the same as for value_$list.
399
400
401 :Entry: set: 07/16/81 value_$set
402
403
404 Function: defines a value for a name, readable by value_$get.
405
406
407 Syntax:
408 dcl value_$set entry options variable;
409 call value_$set seg_ptr switches name new_value old_value code;
410
411
412 Arguments:
413 seg_ptr
414 is a pointer to the base of a value segment. Input
415 switches
416 is a bit 36 aligned word of switches perprocess or permanent.
417 Input
418 name
419 is a fixed-length or varying character string. If fixed-length,
420 trailing blanks are trimmed. There must be at least one character.
421 Input
422 new_value
423 is the value to be set, having any data type. If conversion to the
424 internal character string representation cannot be performed,
425 error_table_$badcall is returned. Input
426
427
428 old_value
429 is the current value, having any data type. If no value is
430 currently defined, the value of this argument is not changed. If
431 conversion from the internal character string representation cannot
432 be performed, error_table_$bad_conversion is returned. Output
433 code
434 is a standard error code. Having no previous value defined does not
435 cause an error code to be returned.
436
437
438 Access required:
439 rw to the value segment, except for perprocess values.
440
441
442 Notes: Perprocess values are stored in a temporary value segment in
443 the process directory, and disappear when the process terminates.
444
445
446 :Entry: set_data: 07/16/81 value_$set_data
447
448
449 Function: defines the value for a name to be a specified number of
450 words of data, readable by value_$get_data. Values set by this
451 entrypoint cannot be seen by value_$get or value_$defined.
452
453
454 Syntax:
455 dcl value_$set_data entry ptr bit 36 char * ptr
456 fixed bin 18 ptr ptr fixed bin 18 fixed bin 35;
457 call value_$set_data seg_ptr switches name new_data_ptr
458 new_data_size area_ptr old_data_ptr old_data_size code;
459
460
461 Arguments:
462 seg_ptr
463 is a pointer to the base of a value segment. Input
464 switches
465 is a bit 36 aligned word of switches perprocess or permanent.
466 Input
467 name
468 is a character string with at least one nonblank character.
469 Trailing blanks are trimmed. Input
470 new_data_ptr
471 is a pointer to the value to be set. Input
472 new_data_size
473 is the number of words in the value to be set. Input
474
475
476 area_ptr
477 if nonnull, points to an area in which the old return value is to
478 be allocated. If null, the old value is not returned. Input
479 old_data_ptr
480 is a pointer to the old value. Output
481 old_data_size
482 is the number of words returned as the old value. Output
483 code
484 is a standard status code. Having no previous value defined does
485 not cause an error code to be returned. Output
486
487
488 Access required:
489 rw on the value segment, except for perprocess values.
490
491
492 Notes: Perprocess values are stored in a temporary value segment in
493 the process directory, and disappear when the process terminates.
494
495
496 :Entry: set_path: 07/16/81 value_$set_path
497
498
499 Function: sets the default value segment used by the value commands
500 with no -pathname argument.
501
502
503 Syntax:
504 dcl value_$set_path entry char * bit 1 fixed bin 35;
505 call value_$set_path entry path create_sw code;
506
507
508 Arguments:
509 path
510 is the pathname. The value suffix is assumed. Input
511 create_sw
512 is ON to create a value segment if none exists. Input
513 code
514 is a standard status code. If it is error_table_$no_w_permission,
515 the value segment has been set. Any other nonzero code indicates
516 that the segment was not set. Output
517
518
519 :Entry: test_and_set: 07/16/81 value_$test_and_set
520
521
522 Function: defines a new value for a name, only if the name has a
523 specified current value.
524
525
526 Syntax:
527 dcl value_$test_and_set entry options variable;
528 call value_$test_and_set seg_ptr switches name new_value
529 old_value code;
530
531
532 Arguments:
533 seg_ptr
534 is a pointer to the base of a value segment. Input
535 switches
536 is a bit 36 aligned word of switches perprocess or permanent.
537 Input
538 name
539 is a fixed-length or varying character string. If fixed-length,
540 trailing blanks are trimmed. There must be at least one character.
541 Input
542
543
544 new_value
545 is the value to be set, having any data type. If conversion to the
546 internal character string representation cannot be performed, the
547 error code error_table_$badcall is returned. Input
548 old_value
549 is the caller-supplied value that must equal the value currently
550 defined in order for the new value to be set. Input
551 code
552 is a standard status code. It is error_table_$action_not_performed
553 if old_value does not match the currently defined value.
554
555
556 Access required:
557 rw to the value segment, except for perprocess values.
558
559
560 Notes: If the value tested is perprocess, the value set is also
561 perprocess, and vice-versa.
562
563
564 :Entry: test_and_set_data: 07/16/81 value_$test_and_set_data
565
566
567 Function: defines the value for a name to be a specified number of
568 words of data, readable by value_$get_data, only if the first N words
569 of the name's current value have specified contents.
570
571
572 Syntax:
573 dcl value_$test_and_set_data entry ptr bit 36 char * ptr fixed
574 bin 18 ptr fixed bin 18 fixed bin 35;
575 call value_$test_and_set_data seg_ptr switches name new_data_ptr
576 new_data_size old_data_ptr old_data_size code;
577
578
579 Arguments:
580 seg_ptr
581 is a pointer to the base of a value segment. Input
582 switches
583 is a bit 36 aligned word of switches perprocess or permanent.
584 Input
585 name
586 is a character string with at least one nonblank character.
587 Trailing blanks are trimmed. Input
588 new_data_ptr
589 is a pointer to the value to be set. If null, the current value is
590 deleted and no value is defined. Input
591 new_data_size
592 is the number of words in the value to be set. Input
593
594
595 old_data_ptr
596 is a pointer to some data, whose first old_data_size words must
597 equal the first old_data_size words of the name's current value in
598 order for the new value to be set. Input
599 old_data_size
600 is the number of words to be compared. This number can be less than
601 the number of words in the name's current value used for example
602 to compare only the header of a structure, but an error code is
603 returned if it is greater. Input
604 code
605 is a standard status code. It is error_table_$action_not_performed
606 if the old-value match fails. Output
607
608
609 Access required:
610 rw on the value segment, except for perprocess values.
611
612
613 Notes: If the value tested is perprocess, the value set is also
614 perprocess, and vice-versa.
615
616
617 The value of a name can be conditionally deleted by passing a null
618 new_data_ptr.