1 02/14/84  mode_string_
  2 
  3 The mode_string_subroutine provides a set of entry points for handling
  4 mode strings.  Mode strings are a way for a user to pass control
  5 information to a command or subsystem.  A mode string is a character
  6 string which contains one or more modes, or is empty.  A mode is a
  7 character string, separated from other modes by a comma.
  8 
  9 The mode_string_ entries describe a mode string with the data
 10 structures declared in mode_string_info.incl.pl1.  See the
 11 Subroutines manual (AG93) for more information.
 12 
 13 
 14 Entry points in mode_string_:
 15    (List is generated by the help command)
 16 
 17 
 18 :Entry:  combine:  02/14/84 mode_string_$combine
 19 
 20 
 21 Function: returns a mode string which represents the union of the
 22 modes defined in the two input arguments.  The order of modes in the
 23 output string is not defined.  If the same parameter is given in both
 24 structures, the type and value are taken from the second structure.
 25 
 26 
 27 Syntax:
 28 declare mode_string_$combine entry (ptr, ptr, char (*),
 29      fixed bin (35));
 30 call mode_string_$combine (mode_string_info_ptr1,
 31      mode_string_info_ptr2, modestr, code);
 32 
 33 
 34 Arguments:
 35 mode_string_info_ptr1
 36    points to the first mode_string_info structure.  (Input)
 37 mode_string_info_ptr2
 38    points to the second mode_string_info structure.  (Input) This
 39    pointer may be null, and the string is formed from the first
 40    structure only.
 41 modestr
 42    is a mode string.  (Input)
 43 code
 44    is a standard system error code.  (Output)
 45 
 46 
 47 :Entry:  delete:  02/14/84 mode_string_$delete
 48 
 49 
 50 Function: returns a new mode string, with any mention of specified
 51 modes deleted.  It is not an error if any of the specified modes are
 52 absent from the structure.
 53 
 54 
 55 Syntax:
 56 declare mode_string_$delete entry (ptr, (*) char (*), char (*),
 57      fixed bin (35));
 58 call mode_string_$delete (mode_string_info_ptr, excludes, modestr,
 59      code);
 60 
 61 
 62 Arguments:
 63 mode_string_info_ptr
 64    is a pointer to the mode_string_info structure.  (Input)
 65 excludes
 66    is the array of names to be excluded.  (Input) To exclude a single
 67    name, a scalar may be given.
 68 modestr
 69    is a mode string.  (Input)
 70 code
 71    is a standard system error code.  (Output)
 72 
 73 
 74 :Entry:  get:  02/14/84 mode_string_$get
 75 
 76 
 77 Function: returns a mode string formed from the mode string info
 78 structure supplied it.  If the caller supplied string is not long
 79 enough to hold the mode string, it is truncated at the nearest whole
 80 mode, and the error code error_table_$mode_string_truncated is
 81 returned.  This ensures that the mode string returned is valid.
 82 
 83 
 84 Syntax:
 85 declare mode_string_$get entry (ptr, char (*), fixed bin (35));
 86 call mode_string_$get (mode_string_info_ptr, modestr, code);
 87 
 88 
 89 Arguments:
 90 mode_string_info_ptr
 91    is a pointer to the mode_string_info structure.  (Input)
 92 modestr
 93    is a mode string.  (Input)
 94 code
 95    is a standard system error code.  (Output)
 96 
 97 
 98 :Entry:  get_error:  02/14/84 mode_string_$get_error
 99 
100 
101 Function: returns a mode string built from an info structure.  Only
102 the modes whose values have nonzero error codes are returned.  This
103 selection mechanism can be used to return a list of bad modes when a
104 call to iox_$modes fails, for inclusion in an error message.
105 
106 
107 Syntax:
108 declare mode_string_$get_error entry (ptr, char (*), fixed bin (35));
109 call mode_string_$get_error (mode_string_info_ptr, modestr, code);
110 
111 
112 Arguments:
113 mode_string_info_ptr
114    is a pointer to the mode_string_info structure.  (Input)
115 modestr
116    is a mode string.  (Input)
117 code
118    is a standard system error code.  (Output)
119 
120 
121 :Entry:  get_mode:  02/14/84 mode_string_$get_mode
122 
123 
124 Function: parses a supplied mode string and extracts a single
125 parameter from it, filling in a caller-supplied mode_value structure
126 (remember to set the version), or returning an error code if the
127 parameter is not present in the string.
128 
129 
130 Syntax:
131 declare mode_string_$get_mode (char (*), char (*), ptr,
132      fixed bin (35));
133 call mode_string_$get_mode (modestr, mode_name, mode_value_ptr, code);
134 
135 
136 Arguments:
137 modestr
138    is a mode string.  (Input)
139 mode_name
140    is the name of the mode to search for.  (Input)
141 mode_value_ptr
142    is a pointer to a mode_value structure.  (Input)
143 code
144    is a standard system error code.  (Output)
145 
146 
147 :Entry:  parse:  02/14/84 mode_string_$parse
148 
149 
150 Function: parses a mode string, allocating a structure giving the
151 parameters specified in the string.
152 
153 
154 Syntax:
155 declare mode_string_$parse entry (char (*), ptr, ptr, fixed bin (35));
156 call mode_string_$parse (modestr, areap, mode_string_info_ptr, code);
157 
158 
159 Arguments:
160 modestr
161    is a mode string.  (Input)
162 areap
163    points to an area where the mode string info structure may be
164    allocated.  (Input) If a null pointer is provided, the system area
165    is used.
166 mode_string_info_ptr
167    is a pointer to the mode_string_info structure.  (Output)
168 code
169    is a standard system error code.  (Output)  It can be:
170    error_table_$bad_mode_value
171       rejects modes for incorrect type.