1 03/12/85  dial_manager_
  2 
  3 
  4 The dial_manager_ subroutine is the user interface to the answering
  5 service dial facility.  The dial facility allows a process to
  6 communicate with multiple terminals at the same time.  This subroutine
  7 uses a structure, dial_manager_arg, to receive arguments from its
  8 caller.  This structure is declared in dial_manager_arg.incl.pl1.
  9 For more information, see the description of the dial command in the
 10 Commands manual.
 11 
 12 The dial_manager_ subroutine uses an event channel to communicate with
 13 the answering service.  This event channel is specified by
 14 dial_manager_arg.dial_channel.  The channel must be created by the
 15 caller.  The answering service sends notices of dial connections and
 16 hangups over this channel.  The dial_manager_ subroutine goes blocked
 17 on the event-wait channel awaiting a response to the request from the
 18 answering service.
 19 
 20 
 21 When the user program receives wakeups over this channel, it should
 22 call the convert_dial_message_ subroutine to decode the event message.
 23 The dial_manager_$allow_dials and dial_manager_$registered_server
 24 entry points establish a dial line.  The dial_id specified in
 25 dial_manager_arg.dial_qualifier is used as the first argument to the
 26 dial command when connecting a terminal to a process.  The dial_id may
 27 be an alphanumeric string from 1 to 12 characters long.  The dial_id
 28 "system" and "s" are reserved for the Initializer process.  A process
 29 can have only one dial line active at a time.
 30 
 31 
 32 Entry points in dial_manager_:
 33    (List is generated by the help command)
 34 
 35 
 36 :Entry:  allow_dials:  03/12/85 dial_manager_$allow_dials
 37 
 38 
 39 Function:  This entry point requests that the answering service
 40 establish a dial line to allow terminals to dial to the calling
 41 process.  The caller must set dial_manager_arg.dial_qualifier to the
 42 dial_id for the dial line.  The caller must also set
 43 dial_manager_arg.dial_channel to an event-wait channel in the caller's
 44 process.  After the dial_manager_$allow_dials entry point has been
 45 called, the event channel may be changed to an event-call channel.  To
 46 connect a terminal to the process, the User_id of the process must be
 47 specified as the second argument of the dial command.  If the process
 48 has already established another dial line, the request is rejected and
 49 code is set to error_table_$dial_active.
 50 
 51 
 52 Syntax:
 53 declare dial_manager_$allow_dials entry (ptr, fixed bin(35));
 54 call dial_manager_$allow_dials (request_ptr, code);
 55 
 56 
 57 Arguments:
 58 request_ptr
 59    is a pointer to the dial_manager_arg structure declared in
 60    dial_manager_arg.incl.pl1.  (Input)
 61 code
 62    is a standard status code.  (Output)
 63 
 64 
 65 :Entry:  dial_out:  03/12/85 dial_manager_$dial_out
 66 
 67 
 68 Function:  This entry point is used to request that an auto call
 69 channel be dialed to a given destination and, if the channel is
 70 successfully dialed, that the channel be assigned to the requesting
 71 process.  The caller must set dial_manager_arg.dial_out_destination to
 72 the telephone number to be dialed.  The caller must also set
 73 dial_manager_arg.dial_channel to an event-wait channel in his process.
 74 The answering service sends notice of dial completions and hangups over
 75 this channel.  After the dial_manager_$dial_out entry point has been
 76 called the event channel may be changed to an event-call channel.  The
 77 user programs receiving the wakeup should call the
 78 convert_dial_message_ subroutine to decode the event message.  The
 79 caller may set dial_manager_arg.channel_name to the name of a specific
 80 channel to be used.  It is also possible to set
 81 dial_manager_arg.channel_name to a starname, in which case the
 82 answering service chooses a channel that has a matching name and has
 83 all the attributes specified in dial_manager_arg.reservation_string.
 84 The name of the chosen channel is not returned by dial_manager_; it
 85 must be obtained via a call to convert_dial_message_.
 86 
 87 
 88 Syntax:
 89 declare dial_manager_$dial_out entry (ptr, fixed bin(35));
 90 call dial_manager_$dial_out (request_ptr, code);
 91 
 92 
 93 Arguments:
 94 request_ptr
 95    is a pointer to the dial_manager_arg structure declared in
 96    dial_manager_arg.incl.pl1.  (Input)
 97 code
 98    is an error status indicator.  (Output)
 99 
100 
101 :Entry:  privileged_attach:  03/12/85 dial_manager_$privileged_attach
102 
103 
104 Function:  This entry point allows a privileged process to attach a
105 "slave" channel.  The effect is as if that terminal had dialed to the
106 requesting process.  The caller must set all variables required by the
107 dial_manager_$allow_dials entry point and then must set
108 dial_manager_arg.channel_name to the name of the channel that is to be
109 attached; dial_manager_arg.dial_qualifier is not used and should be set
110 to the null string.  This must be the same name as specified by the
111 channel master file.  The slave service type must be specified for this
112 channel in the channel master file.  The calling process must have rw
113 access to the access control segment <channel_name>.acs in >sc1>rcp if
114 this request is to be honored.
115 
116 
117 Syntax:
118 declare dial_manager_$privileged_attach entry (ptr, fixed bin(35));
119 call dial_manager_$privileged_attach (request_ptr, code);
120 
121 
122 Arguments:
123 request_ptr
124    is a pointer to the dial_manager_arg structure declared in
125    dial_manager_arg.incl.pl1.  (Input)
126 code
127    is a standard status code.  (Output)
128 
129 
130 :Entry:  registered_server:  03/12/85 dial_manager_$registered_server
131 
132 
133 Function:  This entry point is used to request that the answering
134 service establish a dial line to allow terminals to dial to the calling
135 process using only the dial qualifier.  The calling process must have
136 rw access to the access control segment dial.<dial qualifier>.acs in
137 >sc1>rcp if this request is to be honored.  If the process has already
138 established a dial line, the request is rejected and code is set to
139 error_table_$dial_active.
140 
141 
142 Syntax:
143 declare dial_manager_$registered_server entry (ptr, fixed bin(35));
144 call dial_manager_$registered_server (request_ptr, code);
145 
146 
147 Arguments:
148 request_ptr
149    is a pointer to the dial_manager_arg structure declared in
150    dial_manager_arg.incl.pl1.  (Input)
151 code
152    is a standard status code.  (Output)
153 
154 
155 :Entry:  release_channel:  03/12/85 dial_manager_$release_channel
156 
157 
158 Function:  This entry point is used to request the answering service to
159 release the channel specified in channel_name.  This channel must be
160 dialed to the caller at the time of this request.  The caller must set
161 dial_manager_arg.dial_channel to an event wait channel in the caller's
162 process.  The caller also must set dial_manager_arg.channel_name to the
163 name of the channel to be released.  The user must make
164 dial_manager_arg.dial_channel an event-wait channel before using this
165 call.  If the channel was dialed, the channel is returned to the
166 answering service and another access request may be issued.  If the
167 channel is a slave channel, the channel is hung up.
168 
169 
170 Syntax:
171 declare dial_manager_$release_channel entry (ptr, fixed bin(35));
172 call dial_manager_$release_channel (request_ptr, code);
173 
174 
175 Arguments:
176 request_ptr
177    is a pointer to the dial_manager_arg structure declared in
178    dial_manager_arg.incl.pl1.  (Input)
179 code
180    is a standard status code.  (Output)
181 
182 
183 :Entry: release_channel_no_hangup: 03/12/85 dial_manager_$release_channel_no_hangup
184 
185 
186 Function:  This entry point performs the same function as the
187 dial_manager_$release_channel entry point except that slave channels
188 are not hung up.
189 
190 
191 :Entry:  release_dial_id:  03/12/85 dial_manager_$release_dial_id
192 
193 
194 Function:  This entry point functions as does
195 dial_manager_$shutoff_dials, except that dialed terminals are not hung
196 up.  The user can later release dialed terminals by a call to
197 dial_manager_$shutoff_dials or by calls to
198 dial_manager_$release_channel.
199 
200 
201 Syntax:
202 declare dial_manager_$release_dial_id (ptr, fixed bin (35));
203 call dial_manager_$release_dial_id (request_ptr, code);
204 
205 
206 Arguments:
207 request_ptr
208    is a pointer to the dial_manager_arg structure declared in
209    dial_manager_arg.incl.pl1.  (Input)
210 code
211    is a standard status code.  (Output)
212 
213 
214 :Entry:  release_no_listen:  03/12/85 dial_manager_$release_no_listen
215 
216 
217 Function:  This entry point requests the answering service to release
218 the channel specified in channel_name, which must have been attached by
219 means of the dial_manager_$tandd_attach entry point.  The channel is
220 left in a hung-up state and is not available for use until an explicit
221 "attach" operator command is issued for the channel.  This entry point
222 has the same requirements as the dial_manager_$release_channel entry
223 point.
224 
225 
226 Syntax:
227 declare dial_manager_$release_no_listen entry (ptr, fixed bin (35));
228 call dial_manager_$release_no_listen (request_ptr, code);
229 
230 
231 Arguments:
232 request_ptr
233    is a pointer to the dial_manager_arg structure declared in
234    dial_manager_arg.incl.pl1.  (Input)
235 code
236    is a standard status code.  (Output)
237 
238 
239 :Entry:  shutoff_dials:  03/12/85 dial_manager_$shutoff_dials
240 
241 
242 Function:  This entry point informs the answering service that the user
243 process wishes to prevent further dial connections, and that existing
244 connections should be terminated.  The same information should be
245 passed to this entry point as was passed to the
246 dial_manager_$allow_dials or dial_manager_$registered_server entry
247 point.  The dial_channel must be an event-wait channel.
248 
249 
250 Syntax:
251 declare dial_manager_$shutoff_dials (ptr, fixed bin(35));
252 call dial_manager_$shutoff_dials (request_ptr, code);
253 
254 
255 Arguments:
256 request_ptr
257    is a pointer to the dial_manager_arg structure declared in
258    dial_manager_arg.incl.pl1.  (Input)
259 code
260    is a standard status code.  (Output)
261 
262 
263 :Entry:  tandd_attach:  03/12/85 dial_manager_$tandd_attach
264 
265 
266 Function:  This entry point allows a process with appropriate access to
267 attach any communications channel that is in the channel master file
268 and not already in use, for the purpose of performing online testing of
269 the channel.  The requesting process acquires the channel in a hung-up,
270 nonlistening state.  The channel can be released using either the
271 dial_manager_$release_channel or the dial_manager_$release_no_listen
272 entry point.  In the latter case, the channel will be unavailable to
273 users until the operator enters an attach command for the channel.  The
274 caller must set all the variables required by the
275 dial_manager_$privileged_attach entry point;
276 dial_manager_arg.dial_qualifier is not used and should be set to the
277 null string.
278 
279 
280 Syntax:
281 declare dial_manager_$tandd_attach entry (ptr, fixed bin (35));
282 call dial_manager_$tandd_attach (request_ptr, code);
283 
284 
285 Arguments:
286 request_ptr
287    is a pointer to the dial_manager_arg structure declared in
288    dial_manager_arg.incl.pl1.  (Input)
289 code
290    is a standard status code.  (Output)
291 
292 
293 Access Required:
294 The caller must have at least rw access to both >sc1>rcp>tandd.acs and
295 >sc1>rcp>CHAN_NAME.acs, where CHAN_NAME is the name of the channel to
296 be attached.
297 
298 
299 :Entry:  terminate_dial_out:  03/12/85 dial_manager_$terminate_dial_out
300 
301 
302 Function:  This entry point is used to request that the answering
303 service hang up an auto call line and unassign it from the requesting
304 process.  The caller must set dial_manager_arg.channel_name to the name
305 of the channel being used; channel_name cannot be null.  The caller
306 also must set dial_manager_arg.dial_channel to an event-wait channel.
307 
308 
309 Syntax:
310 declare dial_manager_$terminate_dial_out entry (ptr, fixed bin(35));
311 call dial_manager_$terminate_dial_out (request_ptr, code);
312 
313 
314 Arguments:
315 request_ptr
316    is a pointer to the dial_manager_arg structure declared in
317    dial_manager_arg.incl.pl1.  (Input)
318 code
319    is a standard status code.  (Output)
320 
321 
322 Notes:
323 The structure dial_manager_arg declared in dial_manager_arg.incl.pl1
324 is used to pass a variety of information to the dial_manager_
325 subroutine.