home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / com / utils / at_cmd / at2.doc next >
Encoding:
Text File  |  1992-08-24  |  11.7 KB  |  334 lines
  1.  
  2.  
  3.                           AT2  ---  by Rob Hamerling
  4.  
  5.   AT2
  6.  
  7.   This document describes the programs AT2 and AT3:
  8.  
  9.   AT2   OS/2 1.3 or 2.0 (16-bit version)
  10.   AT3   for OS/2 2.0 (32-bit version)
  11.  
  12.   From version 1.4a on I use a single source file.  This means that both
  13.   executables:
  14.  
  15.   ■  are functionally identical
  16.   ■  have the same version number, currently 1.4a
  17.  
  18.   For simplicity only AT2 is mentioned in the remainder of this text.
  19.   Essential differences between AT2 and AT3 are mentioned explicitly.
  20.  
  21.  
  22.   INTRODUCTION
  23.  
  24.   AT2 is a simple OS/2 program with a limited but useful function: it sends
  25.   characters from the OS/2 commandline as AT-command to a Hayes compatible
  26.   modem (with blanks suppressed).
  27.  
  28.   AT2 also shows the modem response(s), if any, which may be redirected, for
  29.   example to be stored in a file.
  30.  
  31.  
  32.   WHO MAY USE AT2?
  33.  
  34.   AT2 may be used for private personal use only, not in a commercial or
  35.   business environment.  Please contact the author if you have a business
  36.   need for AT2.
  37.  
  38.      R. Hamerling
  39.      Vianen, The Netherlands
  40.      Phone: ++31.3473.72136 (voice, maybe my answering machine)
  41.      FIDOnet: 2:512/4.1098
  42.  
  43.   AT2 may be distributed freely, without chargeing a fee, as long as it
  44.   remains a complete package as originally distributed and no other changes
  45.   are applied without the explicit permission by the author.
  46.  
  47.  
  48.   PACKAGE CONTENTS:
  49.  
  50.   AT2 is distributed as ZIP file (AT2_1.4a.ZIP) with the following contents:
  51.  
  52.   AT2.DOC   This documentation file
  53.  
  54.   AT2.EXE   16-bits executable, for OS/2 1.3 and 2.0
  55.  
  56.   AT3.EXE   32-bits executable, for OS/2 2.0 only
  57.  
  58.   IBM7855A.CMD Sample commandfile to customise an IBM 7855-010 modem for a
  59.             specific purpose: use it for SDLC with the Communications
  60.             Manager, and in Async mode for Bulletin Boards, etc.
  61.  
  62.  
  63.  
  64.  
  65.                           AT2  ---  by Rob Hamerling
  66.  
  67.   AT2 PARAMETERS
  68.  
  69.   AT2 builds the string to be sent to the modem with all commandline
  70.   parameters.  These may be specified as a single string, or as separate
  71.   parameters, which will be concatenated by AT2 to form a single string.  The
  72.   string will be preceeded with 'AT' and terminated with a Carrier Return
  73.   character (ASCII 13).
  74.  
  75.   The string will be sent to the modem in 8-bit, NO parity, 1 stop-bit mode.
  76.  
  77.  
  78.   SPECIAL PARAMETERS
  79.  
  80.   AT2 accepts 2 optional parameters to control its behaviour.  These must be
  81.   specified as first parameters on the OS/2 commandline and can only be
  82.   numeric to distinguish them from modem-commands.  Of course these
  83.   parameters will not be sent to the modem, AT2 will send the first
  84.   non-numeric and all subsequent parameters (even if numeric) to the modem.
  85.  
  86.   1. A value from 1 to 8 will be considered as port number (COM1...COM8).
  87.      COM1 will be addressed by default.
  88.  
  89.   2. A value higher than 8 will be considered as port-speed to be set and
  90.      subsequently used to transmit the AT-command and receive the modem
  91.      response.  If not specified, the speed with which the COM-port has been
  92.      initialised before will be used and not changed.
  93.  
  94.   When either the port is not available (not installed or in use), or the
  95.   speed is not an acceptable value for OS/2, AT2 will terminate with an error
  96.   message, and not issue an AT-command.  The most common errors are:
  97.  
  98.   ■  Invalid port number will result in a DosOpen failure (rc=110)
  99.   ■  Unacceptable speed will give a DosDevIOCtl error (rc=87) (e.g. when a
  100.      value higher than 19200 for OS/2 1.3 is specified).
  101.  
  102.   AT2 does not perform any kind of syntax checking for modem commands.
  103.  
  104.  
  105.   EXAMPLES
  106.  
  107.   Here some examples for AT2:
  108.  
  109.   AT2 Z          Reset modem: AT2 will send 'ATZ<CR>' to the modem.
  110.  
  111.   AT2 E1         Set modem command-echoing ON: AT2 will send 'ATE1<CR>' to
  112.                  the modem.
  113.  
  114.   AT2 19200 M1   Set the com-port to 19200 bps and set modem-speaker on.
  115.  
  116.   AT2 2 \S       Report modem configuration of modem on COM2.
  117.  
  118.   AT2 ^&V >modem.cfg Report current and stored modem profiles, and store
  119.                  modem responses in file 'modem.cfg' (note: this command may
  120.                  vary with the modem).
  121.  
  122.                  Note: A '^'-character is needed as escape-character in front
  123.                  of every '&'-character on the commandline of AT2!  The
  124.                  '&'-character otherwise acts as command separator.  See your
  125.  
  126.  
  127.                           AT2  ---  by Rob Hamerling
  128.  
  129.                  OS/2 command reference manual for details.
  130.  
  131.   AT2 ^&Z0=0347372136 Store (replace) a telephone number in the modem
  132.                  directory.
  133.  
  134.   Of course these are just examples, use your imagination!
  135.  
  136.  
  137.   COMMANDFILE FOR IBM7855
  138.  
  139.   Of course AT2 can also be used from a batch file.  As an example this AT2
  140.   package contains a file IBM7855A.CMD to customise the IBM 7855-010 modem
  141.   for use by an asynchronous communications package, while the modem is
  142.   started-up in sync-mode with power-on.  So the modem can be used with the
  143.   communications manager in SDLC-mode with a Multiprotocol Communications
  144.   Adapter or SDLC-card, and be used in Asynchronous mode after switching the
  145.   modem to an Asynchronous communications port.
  146.  
  147.  
  148.   RETURNCODES
  149.  
  150.   When encountering some kind of problem during execution, AT2 displays a
  151.   message indicating the last executed Function (DosOpen, DosDevIOCtl, etc),
  152.   and the returncode of that function.  This returncode is also returned in
  153.   'errorlevel' for use in batch files.
  154.  
  155.   When AT2 is invoked without any parameter, some help information is
  156.   displayed, and a returncode of 1 is returned.
  157.  
  158.   When the modem does not respond, the returncode of AT2 will be the value
  159.   255.  This may however not be a real error. Examples are: the modem is in
  160.   echo-off state, programmed to not responding.
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.                           AT2  ---  by Rob Hamerling
  190.  
  191.   IMPLEMENTATION
  192.  
  193.  
  194.  
  195.   IMPLEMENTATION
  196.  
  197.   AT2 is completely written in C-language, and uses the standard OS/2
  198.   Application Programmers Interface and functions provided by the COM-port
  199.   drivers COM0x.SYS of OS/2 1.3 and COM.SYS for OS/2 2.0.
  200.  
  201.   It is distributed in 2 versions:
  202.  
  203.   ■  a 16-bit version for OS/2 1.3 and 2.0, compiled with MS-C 6.00a and IBM
  204.      Program Development Toolkit 1.2/1.3.
  205.  
  206.   ■  a 32-bit program useable with OS/2 2.0 only, compiled with IBM C Set/2
  207.      and IBM Program Development Toolkit 2.0.  This version has a pretty
  208.      large EXE-file, since it has been linked 'statically' with some runtime
  209.      library routines for those of you who do not have that library (others
  210.      may want to recompile with the /GD+ option).
  211.  
  212.  
  213.  
  214.   CONTROL OF THE DTR SIGNAL
  215.  
  216.   AT2 does (by default) not set DTR true during execution.  The reason for
  217.   this is that modems which are programmed with a phone number to be dialed
  218.   when DTR becomes true might inadvertently start to dial that number when
  219.   AT2 only tries to deliver an AT command.  On the other hand there are
  220.   modems which do not accept an AT command when DTR is not true, and almost
  221.   certainly will not deliver responses in that case.
  222.  
  223.   To make AT2 generally useful for modems which require DTR being true before
  224.   accepting AT-commands, AT2 scans for an environmentstring "AT2" during its
  225.   startup phase.  When this string is set to "DTR", AT2 does set DTR true
  226.   before delivering its AT-command (and drops it before termination).
  227.   Otherwise AT2 keeps DTR false.
  228.  
  229.   So enter (e.g. in your CONFIG.SYS):
  230.  
  231.        SET AT2=DTR
  232.  
  233.   in case you have a modem that needs DTR to work with AT2.  Just try without
  234.   this SET command to see if AT2 works as desired.  If not, try with this
  235.   enviroment setting, then it should work.
  236.  
  237.   Note:
  238.  
  239.   1. For AT3 the environment string should be named AT3 (SET AT3=DTR).
  240.  
  241.   2. RTS is made true during execution of AT2, otherwise many modems would
  242.      not listen at all.
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.                           AT2  ---  by Rob Hamerling
  252.  
  253.   LIMITATIONS
  254.  
  255.   The following minor restrictions may cause you some inconvenience:
  256.  
  257.   ■  Most Hayes-compatible modems have a commandbuffer of 40 characters.
  258.      Therefore AT2 limits the command-string to 40 characters.
  259.      '^'-characters on the commandline do not appear to AT2 and will
  260.      therefore not be included.  The first parameter that would make the
  261.      length of the AT-command string exceed 40 characters and all subsequent
  262.      parameters will be ignored.  Of course this does NOT include
  263.      AT2-parameters for COM-port and speed.  If you need to sent more data to
  264.      your modem, use as many invocations of AT2 as you desire.
  265.  
  266.   ■  For communication with the modem, AT2 may change certain COM-port
  267.      parameter settings.  These parameters are not reset to their previous
  268.      values after AT2 has finished.  This may leave the port in a setting
  269.      that you may want differently.
  270.  
  271.   Always issue a MODE command with the proper parameters after using AT2.
  272.  
  273.  
  274.   AT2 IS NOT A REPLACEMENT FOR MODE
  275.  
  276.   AT2 is not a stand-in for the MODE command:
  277.  
  278.   ■  It would make AT2 considerably more complicated and error-prone.
  279.   ■  Every OS/2 installation has the MODE-command available, so why duplicate
  280.      good work?
  281.  
  282.   The exception is the setting of port-speed.  Using the MODE-command just
  283.   for setting the speed of the COM-port has the potential problem that it may
  284.   make DTR come true.  So the use of AT2 may be more convenient.
  285.  
  286.   Use AT2 to control your modem, use MODE to control your COM-port.
  287.  
  288.  
  289.   AT2 DESIGN ISSUES
  290.  
  291.   It was originally designed for just switching a modem from SYNC to ASYNC
  292.   mode (and vice versa) in a situation where communications services are used
  293.   of which some use Synchronous (SDLC) protocol and others use Asynchronous
  294.   protocol.  This could be done with redirecting an ECHO command (ECHO ATE1
  295.   >COM1), which works perfectly for DOS in combination with some modems.
  296.   However, OS/2 and some other modems behave differently.
  297.  
  298.   MODE and ECHO may result in DTR becoming true.  And the modem might be
  299.   programmed to dial a built-in phone number to a SYNC connection point when
  300.   DTR becomes true.  This may have some undesirable effects:
  301.  
  302.   ■  It is in most cases not useful to start dialing the programmed number
  303.      when you are in the process of configuring your COM-port or modem.
  304.   ■  It is certainly not useful to dial a service with Synchronous protocol
  305.      when the modem is connected to an ASYNC port (which is the only
  306.      possibility to deliver AT-commands)!
  307.  
  308.   To avoid these problems, AT2 opens the COM-port by default without making
  309.   DTR true
  310.  
  311.  
  312.  
  313.                           AT2  ---  by Rob Hamerling
  314.  
  315.   With AT2 you must be able to send any AT-string to the modem.  To avoid a
  316.   possible interpretation error (whether AT2 should use a commandline
  317.   parameter as program-parameter or a modem-command), an environment variable
  318.   is used to control the DTR signal.
  319.  
  320.   AT2 waits about 0.5 seconds for the modem to transfer a response after
  321.   receiving an AT command.  This timeout is long enough for most modems.  On
  322.   the other hand it ensures that AT2 terminates quickly when there is no
  323.   response, or even when there is no modem connected to the port at all.
  324.  
  325.   Some modems have multiple output screens to show its configuration after
  326.   being requested so (for example with the command AT\S).  The operator is
  327.   requested to hit the ENTER key before the modem shows the next screen of
  328.   information.  AT2 tries to anticipate this situation by issuing a CR
  329.   (Carriage Return) when the modem stops sending data.  If this works for
  330.   your modem you'll get the modem-configuration in 1 single outputstream.
  331.   Otherwise you may get the remaining screens at the next occasion, for
  332.   example when your 'real' communications program opens the COM-port.
  333.  
  334.