Black Box 4/BlackBox.cdr/os2/at2-13b.arj/AT2.DOC

Text File | 1992-06-04 | 9.1 KB | 222 lines

                    AT2  Version 1.3  ---  by Rob Hamerling

  AT2



  INTRODUCTION

  AT2 is a simple OS/2 program with a limited but nevertheless very useful
  function: it sends characters from the commandline as AT-command to a Hayes
  compatible modem (with blanks suppressed).

  AT2 also shows the modem responses, if any.  All AT2 output, including the
  modem-responses, may be redirected, for example to be stored in a file.


  WHO MAY USE AT2?

  AT2 may be used for private personal use only, not in a commercial or
  business environment.  Please contact the author if you have a business
  need for AT2.

     R. Hamerling
     Vianen, The Netherlands
     Phone: ++31.3473.72136 (voice, might be the answering machine)
     FIDOnet: 2:512/4.1098

  AT2 may be distributed freely, without chargeing a fee.


  AT2 PARAMETERS

  AT2 builds the string to be sent to the modem with all commandline
  parameters.  They may be specified as a single string, or as separate
  commands which will be concatenated by AT2 to form a single string.  The
  string will be preceeded with 'AT' and terminated with a Carrier Return
  character (ASCII 13).

  The string will be sent to the modem in 8-bit, NO parity, 1 stop-bit mode.


  SPECIAL PARAMETERS

  AT2 accepts 2 optional parameters to control its behaviour.  These must be
  specified as first parameters on the commandline, and can only be numeric
  to distinguish them from modem-commands.  Of course these parameters will
  not be sent to the modem, AT2 will send the first non-numeric and all
  subsequent parameters (even when numeric) to the modem.  So you can even
  send a dial-string to your modem.

  1.  A value from 1 to 8 will be considered as port number (COM1...COM8).
      COM1 will be addressed by default.

  2.  A value higher than 8 will be considered as port-speed to be set and
      subsequently used to transmit the AT-command and receive the modem
      response.  When not specified, the speed with which the COM-port has
      been initialised before will be used and not changed.

  When either the port is not available (not installed or in use), or the
  speed is an unacceptable value for OS/2, AT2 will terminate with an error
  message, and not issue an AT-command.  The most common errors are:


                    AT2  Version 1.3  ---  by Rob Hamerling

  ■   invalid port number will result in a DosOpen failure (rc=110)
  ■   unacceptable speed will give a DosDevIOCtl error (rc=87)

  AT2 does not perform any kind of syntax checking for modem commands.


  EXAMPLES

  Here some examples for AT2:

  AT2 E1         Set modem command-echoing ON: AT2 will send 'ATE1<CR>' to
                 the modem.

  AT2 19200 M1   Set the com-port to 19200 bps and set modem-speaker on.

  AT2 2 \S       Report modem configuration of modem on COM2.

  AT2 ^&v >modem.cfg Report current and stored modem profiles, and store
                 modem responses in file 'modem.cfg'.

                 Note: A '^'-character is needed as escape-character in front
                 of every '&'-character on the commandline of AT2!  The
                 '&'-character otherwise acts as command separator.  See your
                 OS/2 command reference manual for details.

  AT2 ^&Z0=0347372136 Store (replace) a telephone number in the modem
                 directory.

  Of course these are just examples, use your imagination!


  IMPLEMENTATION

  AT2 is written in C-language, and uses the standard OS/2 Application
  Programmers Interface and functions provided by the COM-port driver
  COMxx.SYS of OS/2.  It is distributed as a 16-bit program, and has been
| tested with OS/2 versions 1.3 and 2.0.


| CONTROL OF THE DTR SIGNAL

| AT2 does (by default) not set DTR true during execution.  The reason for
| this is that modems which are programmed with a phone number to be dialed
| when DTR becomes true would inadvertently start to dial that number when
| AT2 only tries to deliver an AT command.  On the other hand there are
| modems which do not accept an AT command when DTR is not true, and almost
| certainly will not deliver responses in that case.

| To make AT2 generally useful for many if not all modems in different
| configurations, AT2 scans for an environmentstring "AT2" during its startup
| phase.  When this string is set to "DTR", AT2 does set DTR true before
| delivering its AT-command (and drops it before termination).  In all other
| cases AT2 keeps DTR false.

| So enter (e.g. in your CONFIG.SYS):

|      SET AT2=DTR

| in case you have a modem that needs DTR to work with AT2.  Just try with
| and without this SET command to see if there is a different behaviour!

                    AT2  Version 1.3  ---  by Rob Hamerling

  Note: RTS is made true during execution of AT2, otherwise many modems would
  not listen at all.


  LIMITATIONS

  The following minor restrictions may make AT2 a less useful to you:

  ■   Most Hayes-compatible modems have a commandbuffer of 40 characters.
      Therefore AT2 limits the command-string to 40 characters.  The
      '^'-characters do not appear to AT2 and will not be included.  The
      first parameter that would make the length of the AT-command string
|     exceed 40 and all subsequent parameters will be ignored.

| ■   Even if your modem responds as expected to the commands delivered by
|     AT2, it may require DTR true for a dial-command.  If that is the case
|     for your modem, and if you want to use AT2 for dialing, you'll have to
|     set the environment variable AT2=DTR, as explained in "Control of the
|     DTR signal" on page 2.

  ■   For communication with the modem, AT2 may change certain COM-port
      parameter settings.  These parameters are not reset to their previous
      values after AT2 has finished.  This may leave the port in a setting
      that you may want differently.

  Always issue a MODE command with the proper parameters after using AT2.


  AT2 IS NOT A REPLACEMENT FOR MODE

  I have considered making AT2 a stand-in for the MODE command, dedicated for
  the COM-port, but I dropped the idea:

  ■   It would make AT2 considerably more complicated and error-prone.
  ■   Every OS/2 installation has the MODE-command available, so why
      duplicate good work?

  The exception is the setting of port-speed.  This is just for convenience.

  Using the MODE-command for setting the speed of the COM-port has the
  potential problem that it may make DTR come true.  This should in
  particular be avoided if the modem is programmed to dial a telephone number
  on rising DTR.

  Note: The same applies to the use of ECHO to send AT-commands to a modem!

  Use AT2 to control your modem, use MODE to control your COM-port.


  AT2 DESIGN ISSUES

  It was originally designed for just switching a modem from SYNC to ASYNC
  mode (and vice versa) in a situation where communications services are used
  of which some use Synchronous (SDLC) protocol and others use Asynchrounous
  protocol.  This could be done with redirecting an ECHO command (ECHO ATE1
  >COM1), which works perfectly for DOS in combination with some modems.
  However, OS/2 and some other modems behave differently.

  MODE and ECHO may result in DTR becoming true.  And the modem might be
  programmed to dial a built-in phone number to a SYNC connection point when

                    AT2  Version 1.3  ---  by Rob Hamerling

| DTR becomes true.  This may have some undesirable effects:

| ■   It is in most cases not useful to start dialing the programmed number
|     when you are in the process of configuring your COM-port or modem.
| ■   It is certainly not useful to dial a service with Synchronous protocol
|     when the modem is connected to an ASYNC port (which is the only
|     possibility to deliver AT-commands)!

| To avoid these problems, AT2 opens the COM-port by default without making
| DTR true

| With AT2 you must be able to send any AT-string to the modem.  To avoid a
| possible interpretation error (whether a commandline parameter is meant to
| be a program-parameter or a modem-command), an environment variable is used
| to control the DTR signal.

  AT2 waits about 0.5 seconds for the modem to transfer a response after
  receiving an AT command.  This timeout is long enough for most modems.  On
  the other hand it ensures that AT2 terminates quickly when there is no
  response, or even when there is no modem connected to the port at all.

  Some modems have multiple output screens to show its configuration after
  being requested so (for example with the command AT\S).  The operator is
  requested to hit the ENTER key before the modem shows the next screen of
  information.  AT2 tries to anticipate on this situation by issuing a CR
  (Carriage Return) when the modem stops sending data.  If this works for
  your modem you'll get the modem-configuration in 1 single outputstream.
  Otherwise you may get the remaining screens at the next occasion, for
  example when your 'real' communications program opens the COM-port.