04/20/82 value_ The value_ subroutine reads and maintains value segments containing name-value pairs. Entry points in value_: (List is generated by the help command) :Entry: defined: 07/16/81 value_$defined Function: returns "1"b if a value is defined for name, "0"b otherwise. Syntax: dcl value_$defined entry (ptr, bit (36), char (*), fixed bin (35)) returns (bit (1)); defined_sw = value_$defined (seg_ptr, switches, name, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) See "Notes". switches is a bit (36) aligned word of switches: (Input) perprocess looks for a perprocess value, as opposed to one stored in any value segment. Either this switch or "permanent" must be on. If both switches are on, a perprocess value is returned if one exists, otherwise a value stored in the value segment is returned. permanent looks for a value stored in the value segment. name is a character string with at least one nonblank character. Trailing blanks are trimmed. (Input) code is a standard status code. (Output) Access required: r on the value segment, except for perprocess values. Notes: To initialize a new value segment, create a segment with suffix "value" and call value_$init_seg with a pointer to its base. If seg_ptr is null, the default value segment is used, which is initially [home_dir]>[user name].value but can be changed by value_$set_path or the value_set_path (vsp) command. :Entry: delete: 07/16/81 value_$delete Function: this entry point causes there to be no value defined for name. Syntax: dcl value_$delete entry (ptr, bit (36), char (*), fixed bin (35)); call value_$delete (seg_ptr, switches, name, code); Arguments: seg_ptr is a pointer to the base of a value segment. If seg_ptr is null, the default value segment is used, which is initially: [home_dir]>[user name].value but can be changed by value_$set_path or the value_set_path (vsp) command. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a character string with at least one nonblank character. Trailing blanks are trimmed. (Input) code is a standard status code. (Output) Access required: rw on the value segment, except for perprocess values. :Entry: get: 07/16/81 value_$get Function: returns the defined value of a name. Syntax: dcl value_$get entry options (variable); call value_$get (seg_ptr, switches, name, value_arg, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a fixed-length or varying character string. If fixed-length, trailing blanks are trimmed. There must be at least one character. (Input) value_arg is the returned value, having any data type. If conversion from the internal character string representation cannot be performed, error_table_$bad_conversion is returned. Conversion errors cannot occur if value_arg is a character string, but if it has a maxlength > 0, the error code error_table_$smallarg is returned if truncation occurs. (Output) code is a standard error code. It is error_table_$oldnamerr ("Name not found.") if no value is defined. (Output) Access required: r access to the value segment, except for perprocess values. Notes: Perprocess values are stored in a temporary value segment in the process directory, and disappear when the process terminates. :Entry: get_data: 07/16/81 value_$get_data Function: returns, into a caller-supplied buffer, the region of storage that is defined as the value of a name, as set by either value_$set_data or value_$test_and_set_data. Values set by other entrypoints are not seen by value_$get_data. Syntax: dcl value_$get_data entry (ptr, bit (36), char (*), ptr, ptr, fixed bin (18), fixed bin (35)); call value_$get_data (seg_ptr, switches, name, area_ptr, data_ptr, data_size, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a character string with at least one nonblank character. Trailing blanks are trimmed. (Input) area_ptr points to an area in which the value can be allocated. (Input) data_ptr points to the value returned. (Output) data_size is the number of words in the value. If it is greater than buffer_size, only buffer_size words are returned, data_size is set to the full size of the value, and error_table_$smallarg is returned. (Output) code is a standard error code. It is error_table_$oldnamerr ("Name not found.") if no value is defined. (Output) Access required: r on the value segment, except for perprocess values. Notes: Perprocess values are stored in a temporary value segment in the process directory, and disappear when the process terminates. :Entry: get_path: 07/16/81 value_$get_path Function: returns the pathname of the current default value segment used by value commands without -pathname. Syntax: dcl value_$get_path entry (char (*), fixed bin (35)); call value_$get_path (path, code); Arguments: path is the pathname. (Output) code is a standard status code. (Output) :Entry: init_seg: 07/16/81 value_$init_seg Function: initializes a segment to be a value segment. Syntax: dcl value_$init_seg entry (ptr, fixed bin, ptr, fixed bin (19), fixed bin (35)); call value_$init_seg (seg_ptr, seg_type, remote_area_ptr, seg_size, code); Arguments: seg_ptr is a pointer to a segment. (Input) seg_type determines the type of use to which the value segment will be put, and therefore the method of allocating values: (Input) 0 permanent: shareable by multiple processes and therefore locked when modified, with values always stored in the value segment itself. 1 perprocess: for use only by the calling process and therefore never locked, with values optionally stored in an area outside the "value segment" (see the remote_area_ptr argument below). remote_area_ptr for a perprocess segment only, points to an area outside the value segment in which values are to be allocated. For example, the "value segment" can be a region of storage 72 words long consisting only of a header, and remote_area_ptr can point to the user's own area. If remote_area_ptr is null and seg_type is 1, values are allocated in the system free area. (Input) seg_size is the number of words available to the value segment, or to the remote area if remote_area_ptr is nonnull. If seg_size is 0, the available size is an entire segment. (Input) code is a standard status code. (Output) Access required: rw on the segment. :Entry: delete_data: 04/20/82 value_$delete_data Syntax: dcl value_$delete_data entry (ptr, bit (36), char (*), fixed bin (35)); call value_$delete_data (seg_ptr, switches, name, code); Function: deletes values set by value_$set_data. Arguments: seg_ptr is a pointer to the base of a value segment. If seg_ptr is null, the default value segment is used, which is initially: [home_dir]>[user name].value but can be changed by value_$set_path or the value_set_path (vsp) command. (Input) switches is a bit (36) aligned word of switches: (Input) perprocess deletes a perprocess value, as opposed to one stored in any value segment. Either this switch or "permanent" must be on. If both switches are on, the perprocess value is deleted if one exists, otherwise the value in the value segment is deleted. permanent deletes a value stored in the value segment. name is a character string with at least one nonblank character. Trailing blanks are trimmed. (Input) code is a standard status code. (Output) Access required: rw on the value segment, except for perprocess values. :Entry: list: 07/16/81 value_$list Function: Given a list of starnames and regular expressions to match and exclude, returns a list of variable names and their values. Only values set by value_$set are returned; see value_$list_data_names to list variables set by value_$set_data. Syntax: dcl value_$list entry (ptr, bit (36) aligned, ptr, ptr, ptr, fixed bin (35)); call value_$list (seg_ptr, switches, match_info_ptr, area_ptr, value_list_info_ptr, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) word of switches (perprocess or permanent). (Input) match_info_ptr is a pointer to a user-allocated structure, declared in value_structures.incl.pl1. (Input) See "Notes on structures" below. area_ptr is a pointer to an area in which the output value_list_info structure is to be allocated. (Input) value_list_info_ptr is a pointer to a structure, allocated by value_$list and freed by the caller when done. It is also declared in the include file value_structures.incl.pl1. (Output) See "Notes on structures". code is a standard status code. (Output) Access required: r on the value segment, except for perprocess values. Notes: Names are returned in alphabetical order. Notes on structures: The match_info_ptr argument is a pointer to the following user-allocated structure, declared in value_structures.incl.pl1: dcl 1 match_info aligned based (match_info_ptr), 2 version fixed bin, /* = 1 */ 2 name_count fixed bin, 2 max_name_len fixed bin (21), 2 name_array (alloc_name_count refer (match_info.name_count)), 3 exclude_sw bit (1) unaligned, 3 regexp_sw bit (1) unaligned, 3 pad bit (34) unaligned /* = "0"b */ 3 name char (alloc_max_name_len refer (match_info.max_name_len)) varying; If a name's regexp_sw is ON, the name is a regular expression to be matched. Otherwise, it is a starname to be matched. If the name's exclude_sw is ON, variables matching the name are excluded from the list built up so far, as for the -exclude control argument to the value_list command. Otherwise, matching variables are added to the list. The value_list_info_ptr argument is a pointer to the following structure, declared in the include file value_structures.incl.pl1: dcl 1 value_list_info aligned based (value_list_info_ptr), 2 version fixed bin, /* = 1 */ 2 pair_count fixed bin, 2 chars_len fixed bin (21), 2 pairs (alloc_pair_count refer (value_list_info.pair_count)), 3 type_switches bit (36), 3 name_index fixed bin (21), 3 name_len fixed bin (21), 3 value_index fixed bin (21), 3 value_len fixed bin (21), 2 chars (alloc_chars_len refer (value_list_info.chars_len)); For each pair (i), the variable name is: substr (chars, name_index (i), name_len (i)) and the value is: substr (chars, value_index (i), value_len (i)) The first bit in type_switches (i) is ON if the variable is perprocess, the second is ON instead for a variable stored in the value segment. The user is responsible for freeing the value_list_info structure when done. :Entry: list_data_names: 04/20/82 value_$list_data_names Syntax: dcl value_$list_data_names entry (ptr, bit (36) aligned, ptr, ptr, ptr, fixed bin (35)); call value_$list_data_names (seg_ptr, switches, match_info_ptr, area_ptr, value_list_info_ptr, code); Function: Operates exactly the same as value_$list, but returns variables set by value_$set_data instead of value_$set, and does not return the values. Instead, it sets value_list_info.value_len to the number of words in the value. Arguments: are the same as for value_$list. :Entry: set: 07/16/81 value_$set Function: defines a value for a name, readable by value_$get. Syntax: dcl value_$set entry options (variable); call value_$set (seg_ptr, switches, name, new_value, old_value, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a fixed-length or varying character string. If fixed-length, trailing blanks are trimmed. There must be at least one character. (Input) new_value is the value to be set, having any data type. If conversion to the internal character string representation cannot be performed, error_table_$badcall is returned. (Input) old_value is the current value, having any data type. If no value is currently defined, the value of this argument is not changed. If conversion from the internal character string representation cannot be performed, error_table_$bad_conversion is returned. (Output) code is a standard error code. Having no previous value defined does not cause an error code to be returned. Access required: rw to the value segment, except for perprocess values. Notes: Perprocess values are stored in a temporary value segment in the process directory, and disappear when the process terminates. :Entry: set_data: 07/16/81 value_$set_data Function: defines the value for a name to be a specified number of words of data, readable by value_$get_data. Values set by this entrypoint cannot be seen by value_$get or value_$defined. Syntax: dcl value_$set_data entry (ptr, bit (36), char (*), ptr, fixed bin (18), ptr, ptr, fixed bin (18), fixed bin (35)); call value_$set_data (seg_ptr, switches, name, new_data_ptr, new_data_size, area_ptr, old_data_ptr, old_data_size, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a character string with at least one nonblank character. Trailing blanks are trimmed. (Input) new_data_ptr is a pointer to the value to be set. (Input) new_data_size is the number of words in the value to be set. (Input) area_ptr if nonnull, points to an area in which the old (return) value is to be allocated. If null, the old value is not returned. (Input) old_data_ptr is a pointer to the old value. (Output) old_data_size is the number of words returned as the old value. (Output) code is a standard status code. Having no previous value defined does not cause an error code to be returned. (Output) Access required: rw on the value segment, except for perprocess values. Notes: Perprocess values are stored in a temporary value segment in the process directory, and disappear when the process terminates. :Entry: set_path: 07/16/81 value_$set_path Function: sets the default value segment used by the value commands with no -pathname argument. Syntax: dcl value_$set_path entry (char (*), bit (1), fixed bin (35)); call value_$set_path entry (path, create_sw, code); Arguments: path is the pathname. The value suffix is assumed. (Input) create_sw is ON to create a value segment if none exists. (Input) code is a standard status code. If it is error_table_$no_w_permission, the value segment has been set. Any other nonzero code indicates that the segment was not set. (Output) :Entry: test_and_set: 07/16/81 value_$test_and_set Function: defines a new value for a name, only if the name has a specified current value. Syntax: dcl value_$test_and_set entry options (variable); call value_$test_and_set (seg_ptr, switches, name, new_value, old_value, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a fixed-length or varying character string. If fixed-length, trailing blanks are trimmed. There must be at least one character. (Input) new_value is the value to be set, having any data type. If conversion to the internal character string representation cannot be performed, the error code error_table_$badcall is returned. (Input) old_value is the caller-supplied value that must equal the value currently defined in order for the new value to be set. (Input) code is a standard status code. It is error_table_$action_not_performed if old_value does not match the currently defined value. Access required: rw to the value segment, except for perprocess values. Notes: If the value tested is perprocess, the value set is also perprocess, and vice-versa. :Entry: test_and_set_data: 07/16/81 value_$test_and_set_data Function: defines the value for a name to be a specified number of words of data, readable by value_$get_data, only if the first N words of the name's current value have specified contents. Syntax: dcl value_$test_and_set_data entry (ptr, bit (36), char (*), ptr, fixed bin (18), ptr, fixed bin (18), fixed bin (35)); call value_$test_and_set_data (seg_ptr, switches, name, new_data_ptr, new_data_size, old_data_ptr, old_data_size, code); Arguments: seg_ptr is a pointer to the base of a value segment. (Input) switches is a bit (36) aligned word of switches (perprocess or permanent). (Input) name is a character string with at least one nonblank character. Trailing blanks are trimmed. (Input) new_data_ptr is a pointer to the value to be set. If null, the current value is deleted and no value is defined. (Input) new_data_size is the number of words in the value to be set. (Input) old_data_ptr is a pointer to some data, whose first old_data_size words must equal the first old_data_size words of the name's current value in order for the new value to be set. (Input) old_data_size is the number of words to be compared. This number can be less than the number of words in the name's current value (used, for example, to compare only the header of a structure), but an error code is returned if it is greater. (Input) code is a standard status code. It is error_table_$action_not_performed if the old-value match fails. (Output) Access required: rw on the value segment, except for perprocess values. Notes: If the value tested is perprocess, the value set is also perprocess, and vice-versa. The value of a name can be conditionally deleted by passing a null new_data_ptr. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved