Download TelePACE C Tools User Manual

modemDial
Connect to a Remote Dial-up Controller
Syntax
#include <ctools.h>
enum DialError modemDial(struct ModemSetup *configuration, reserve_id *id);
Description
The modemDial function connects a controller to a remote controller using an external dialup modem. One modemDial function may be active on each serial port. The modemDial
function handles all port sharing and multiple dialing attempts.
The ModemSetup structure specified by configuration defines the serial port, dialing
parameters, modem initialization string and the phone number to dial. Refer to the
Structures and Types section for a description of the fields in the ModemSetup structure.
id points to a reservation identifier for the serial port. The identifier ensures that no other
modem control function can access the serial port. This parameter must be supplied to the
modemDialEnd and modemDialStatus functions.
The function returns an error code. DE_NoError indicates that the connect operation has
begun. Any other code indicates an error. Refer to the dialup.h section for a complete
description of error codes.
Notes
The serial port type must be set to RS232_MODEM.
Note:
The SCADAPack 100 does not support dial up connections on com port 1.
The SCADASense series controllers do not support dial up connections.
The modemDialStatus function returns the status of the connection attempt initiated by
modemDial.
The modemDialEnd function terminates the connection to the remote controller. Note that a
pause of a few seconds is required between terminating a connection and initiating a new
call. This pause allows the external modem time to hang up.
If a communication protocol is active on the serial port when a connection is initiated, the
protocol will be disabled until the connection is made, then re-enabled. This allows the
controller to communicate with the external modem on the port. The protocol settings will
also be restored when a connection is terminated with the modemDialEnd function.
If a modemInit function or an incoming call is active on the port, the modemDial function
cannot access the port and will return an error code of DE_NotInControl. If communication
stops for more than five minutes, then outgoing call requests are allowed to end the
incoming call. This prevents problems with the modem or the calling application from
permanently disabling outgoing calls.
The reservation identifier is valid until the call is terminated and another modem function or
an incoming call takes control of the port.
To optimize performance, minimize the length of messages on com3 and com4. Examples
of recommended uses for com3 and com4 are for local operator display terminals, and for
programming and diagnostics using the TelePACE program.
Do not call this function in a task exit handler.
TelePACE C Tools User and Reference Manual
May 9, 2007
336