home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / at3_15b.zip / AT3.DOC next >
Text File  |  1997-01-03  |  15KB  |  442 lines
  1.  
  2.  
  3.                           AT3  ---  by Rob Hamerling
  4.  
  5.     AT3
  6.  
  7.     This document describes the program AT3 for OS/2 2.0 and up (32-bit
  8.     version).
  9.  
  10.  
  11.     INTRODUCTION
  12.  
  13.     AT3 is a simple OS/2 program with a limited but useful function: it
  14.     sends characters from the OS/2 commandline as AT-command to a Hayes
  15.     compatible modem (with blanks suppressed).
  16.  
  17.     AT3 also shows the modem response(s), if any, which may be redirected,
  18.     for example to be stored in a file.
  19.  
  20.  
  21.     WHO MAY USE AT3?
  22.  
  23.     AT3 may be used for private personal use only, not in a commercial or
  24.     business environment.  Please contact the author if you have a business
  25.     need for AT3.
  26.  
  27.        R. Hamerling
  28.        Vianen, The Netherlands
  29.        Phone: BBS/FAX: 31-347-322423
  30.        FIDOnet: 2:281/732 or 2:280/804.1098
  31.        E-mail: rob.hamerling@f732.n281.z2.elcom.org
  32.  
  33.     AT3 may be distributed freely, without charging a fee, as long as it
  34.     remains a complete package as originally distributed and no other
  35.     changes are applied without the explicit permission by the author.
  36.  
  37.  
  38.     PACKAGE CONTENTS:
  39.  
  40.     AT3 is distributed as ZIP file (AT3_15B.ZIP) with the following
  41.     contents:
  42.  
  43.     AT3.DOC   This documentation file
  44.  
  45.     AT3.EXE   32-bits executable, for OS/2 2.0 and newer
  46.  
  47.     IBM7855A.CMD Sample commandfile to customise an IBM 7855-010 modem for
  48.               use in ASYNC mode with RTS/CTS handshaking.
  49.  
  50.  
  51.  
  52.     AT3 PARAMETERS
  53.  
  54.     AT3 builds the string to be sent to the modem with all commandline
  55.     parameters.  These may be specified as a single string, or as separate
  56.     parameters, which will be concatenated by AT3 to form a single string.
  57.     The string will be preceeded with 'AT' and terminated with a Carrier
  58.     Return character (ASCII 13).
  59.  
  60.     The string will be sent to the modem in 8-bit, NO parity, 1 stop-bit
  61.     mode.
  62.  
  63.     
  64.                                                                      AT3  1
  65.  
  66.                           AT3  ---  by Rob Hamerling
  67.  
  68.  
  69.  
  70.     SPECIAL PARAMETERS
  71.  
  72.     AT3 accepts 2 optional parameters to control its behaviour.  These must
  73.     be specified as first parameters on the OS/2 commandline and can only
  74.     be numeric to distinguish them from modem-commands.  Of course these
  75.     parameters will not be sent to the modem, AT3 will send the first
  76.     non-numeric and all subsequent parameters (even if numeric) to the
  77.     modem.
  78.  
  79.     1. A value from 1 to 8 will be considered as port number (COM1...COM8).
  80.        COM1 will be addressed by default.
  81.  
  82.     2. A value higher than 8 will be considered as port-speed to be set and
  83.        subsequently used to transmit the AT-command and receive the modem
  84.        response.  If not specified, the speed with which the COM-port has
  85.        been initialised before will be used and not changed.
  86.  
  87.     When either the port is not available (not installed or in use), or the
  88.     speed is not an acceptable value for OS/2, AT3 will terminate with an
  89.     error message, and not issue an AT-command.  The most common errors
  90.     are:
  91.  
  92.     ■  Invalid port number will result in a DosOpen failure (rc=110)
  93.     ■  Unacceptable speed will give a DosDevIOCtl error (rc=87)
  94.  
  95.     AT3 does not perform any kind of syntax checking for modem commands.
  96.  
  97.  
  98.     EXAMPLES
  99.  
  100.     Here some examples for AT3:
  101.  
  102.     AT3 Z          Reset modem: AT3 will send 'ATZ<CR>' to the modem.
  103.  
  104.     AT3 E1         Set modem command-echoing ON: AT3 will send 'ATE1<CR>'
  105.                    to the modem.
  106.  
  107.     AT3 19200 M1   Set the com-port to 19200 bps and set modem-speaker on.
  108.  
  109.     AT3 2 \S       Report configuration of modem on COM2.
  110.  
  111.     AT3 ^&V >modem.cfg Report current and stored modem profiles, and store
  112.                    modem responses in file 'modem.cfg' (this command may
  113.                    vary with the modem).
  114.  
  115.                    Note: A '^'-character is needed as escape-character in
  116.                    front of every '&'-character on the commandline of AT3!
  117.                    The '&'-character otherwise acts as command separator.
  118.                    See your OS/2 command reference manual for details.
  119.  
  120.     AT3 ^&Z0=322423 Store (replace) a telephone number in the modem
  121.                    directory.
  122.  
  123.     Of course these are just examples, use your imagination and your modem
  124.     manual!
  125.  
  126.     
  127.                                                                      AT3  2
  128.  
  129.                           AT3  ---  by Rob Hamerling
  130.  
  131.  
  132.  
  133.     COMMANDFILE FOR IBM7855
  134.  
  135.     Of course AT3 can also be used from a batch file or a REXX procedure.
  136.     As an example this AT3 package contains a file IBM7855A.CMD to
  137.     customise the IBM 7855-010 modem for use by an asynchronous
  138.     communications package.
  139.  
  140.     With a slight modification (&M2 in stead of &M0) the modem is
  141.     started-up in sync-mode with power-on.  So the modem can be used with
  142.     the communications manager in SDLC-mode with a Multiprotocol
  143.     Communications Adapter or SDLC-card, and be used in Asynchronous mode
  144.     after switching the modem to an Asynchronous communications port.
  145.  
  146.  
  147.     RETURNCODES
  148.  
  149.     When encountering some kind of problem during execution, AT3 displays a
  150.     message indicating the last executed Function (DosOpen, DosDevIOCtl,
  151.     etc), and the returncode of that function.  This returncode is also
  152.     returned in 'errorlevel' for use in batch files.
  153.  
  154.     When AT3 is invoked without any parameter, some help information is
  155.     displayed, and a returncode of 1 is returned.
  156.  
  157.     When the modem does not respond, the returncode of AT3 will be the
  158.     value 255.  This may however not be a real error. Examples are: the
  159.     modem is in echo-off state, programmed to not responding.
  160.  
  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.     
  190.                                                                      AT3  3
  191.  
  192.                           AT3  ---  by Rob Hamerling
  193.  
  194.     IMPLEMENTATION
  195.  
  196.  
  197.  
  198.     IMPLEMENTATION
  199.  
  200.     AT3 is completely written in C-language, and uses the standard OS/2
  201.     Application Programmers Interface and functions provided by the
  202.     COM-port driver COM.SYS for OS/2 2.0 and newer.  The program has been
  203.     compiled with IBM C/C++ 2.0 and IBM Program Development Toolkit for
  204.     OS/2 Warp.
  205.  
  206.  
  207.     CONTROL OF THE DTR SIGNAL
  208.  
  209.     AT3 does not set DTR true during execution by default.  The reason for
  210.     this is that modems which are programmed with a phone number to be
  211.     dialed when DTR becomes true might inadvertently start to dial that
  212.     number when AT3 only tries to deliver an AT command.  On the other hand
  213.     there are modems which do not accept an AT command when DTR is not
  214.     true, and almost certainly will not deliver responses in that case.
  215.  
  216.     To make AT3 generally useful for modems which require DTR being true
  217.     before accepting AT-commands, AT3 scans for the environmentstring "AT3"
  218.     during at startup.  When this string is set to "DTR", AT3 activates the
  219.     DTR lead before delivering its AT-command, and drops it at termination.
  220.     Otherwise AT3 keeps DTR false.
  221.  
  222.     So enter (e.g. in your CONFIG.SYS):
  223.  
  224.          SET AT3=DTR
  225.  
  226.     in case you have a modem that needs DTR to work with AT3.  If you don't
  227.     know, just try without this SET command to see if AT3 works as desired.
  228.     If not then make it work with this enviroment setting.
  229.  
  230.     Note: AT3 makes RTS true during execution, otherwise hardly any modem
  231.     would listen to commands from the computer.
  232.  
  233.  
  234.     DIALING
  235.  
  236.     If you want to use AT3 for dial commands, then you need to set the
  237.     environment variable slightly different, for example:
  238.  
  239.          SET AT3=DTR,500
  240.  
  241.     Hardly any modem will execute a dial-command whithout DTR being true.
  242.     But also the standard timeout of AT3 is too short to wait for the
  243.     completion of a dial command.  DTR will be turned off after that time,
  244.     which will prevent the modem from finishing the dial operation.  The
  245.     sample value of '500' modifies the standard timeout from .5 seconds to
  246.     5 seconds (the value is expressed in hundredths of seconds), which will
  247.     generally be large enough for tone-dialing.  But it may not be the
  248.     right value for your modem, modem command or network.  Experiment with
  249.     this value!
  250.  
  251.  
  252.     
  253.                                                           Implementation  4
  254.  
  255.                           AT3  ---  by Rob Hamerling
  256.  
  257.     Note: Only values higher than the default of 50 (.5 seconds) are
  258.     accepted.
  259.  
  260.  
  261.     LIMITATIONS
  262.  
  263.     The following minor restrictions may cause you some inconvenience:
  264.  
  265.     ■  Most Hayes-compatible modems have a commandbuffer of 40 characters.
  266.        Therefore AT3 limits the command-string to 40 characters.
  267.        '^'-characters on the commandline do not appear to AT3 and will
  268.        therefore not be included.  The first parameter that would make the
  269.        length of the AT-command string exceed 40 characters and all
  270.        subsequent parameters will be ignored.  Of course this does NOT
  271.        include AT3-parameters for COM-port and speed.  If you need to sent
  272.        more data to your modem, use as many invocations of AT3 as you
  273.        desire.
  274.  
  275.     ■  For communication with the modem, AT3 may change certain COM-port
  276.        parameter settings.  These parameters are not reset to their
  277.        previous values after AT3 has finished.  This may leave the port in
  278.        a setting that you may want differently.
  279.  
  280.     Always issue a MODE command with the proper parameters after using AT3.
  281.  
  282.  
  283.     AT3 IS NOT A REPLACEMENT FOR MODE
  284.  
  285.     AT3 is not a stand-in for the MODE command:
  286.  
  287.     ■  It would make AT3 considerably more complicated and error-prone.
  288.     ■  Every OS/2 installation has the MODE-command available, so why
  289.        duplicate good work?
  290.  
  291.     The exception is the setting of port-speed.  Using the MODE-command
  292.     just for setting the speed of the COM-port has the potential problem
  293.     that it may set DTR true.
  294.  
  295.     Use AT3 to address your modem, use MODE to control your COM-port.
  296.  
  297.  
  298.     AT3 DESIGN ISSUES
  299.  
  300.     It was originally designed for just switching a modem from SYNC to
  301.     ASYNC mode (and vice versa) in a situation where communications
  302.     services are used of which some use Synchronous (SDLC) protocol and
  303.     others use Asynchronous protocol.  This could be done with redirecting
  304.     an ECHO command (ECHO ATE1 >COM1), which works perfectly for DOS in
  305.     combination with some modems.  However, OS/2 and some other modems
  306.     behave differently.
  307.  
  308.     MODE and ECHO may result in DTR becoming true (and may stay true!).
  309.     And the modem might be programmed to dial a built-in phone number to a
  310.     SYNC connection point when DTR becomes true.  This may have some
  311.     undesirable effects:
  312.  
  313.     ■  It is in most cases not useful to start dialing the programmed
  314.  
  315.     
  316.                                                           Implementation  5
  317.  
  318.                           AT3  ---  by Rob Hamerling
  319.  
  320.        number when you are in the process of configuring your COM-port or
  321.        modem.
  322.     ■  It is certainly not useful to dial a service with Synchronous
  323.        protocol when the modem is connected to an ASYNC port (which is the
  324.        only possibility to deliver AT-commands)!
  325.  
  326.     To avoid these problems, AT3 opens the COM-port by default without
  327.     making DTR true
  328.  
  329.     With AT3 you must be able to send any AT-string to the modem.  To avoid
  330.     a possible interpretation error (whether AT3 should use a commandline
  331.     parameter as program-parameter or a modem-command), an environment
  332.     variable is used to control the DTR signal.
  333.  
  334.     AT3 waits about 0.5 seconds for the modem to transfer a response after
  335.     receiving an AT command.  This timeout is long enough for most modems.
  336.     On the other hand it ensures that AT3 terminates quickly when there is
  337.     no response, or even when there is no modem connected to the port at
  338.     all.
  339.  
  340.     Some modems have multiple output screens to show its configuration
  341.     after being requested so (for example with the command AT\S).  The
  342.     operator is requested to hit the ENTER key before the modem shows the
  343.     next screen of information.  AT3 tries to anticipate this situation by
  344.     issuing a CR (Carriage Return) when the modem stops sending data.  If
  345.     this works for your modem you'll get the modem-configuration in 1
  346.     single outputstream.  Otherwise you may get the remaining screens at
  347.     the next occasion, for example when your 'real' communications program
  348.     opens the COM-port.
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.     
  379.                                                           Implementation  6
  380.  
  381.                           AT3  ---  by Rob Hamerling
  382.  
  383.     APPENDIX A.  SAMPLE REXX COMMANDFILE FOR SETUP OF IBM 7855 MODEM
  384.  
  385.     /* ╔═════════════════════════════════════════════════════╗        */
  386.     /* ║  IBM7855A.CMD by Rob Hamerling (see AT3.DOC file).  ║        */
  387.     /* ╚═════════════════════════════════════════════════════╝        */
  388.     /* Change portnumber into the appropriate value (2 for COM2 etc). */
  389.     /* Change phone number as desired.                                */
  390.  
  391.     modem = 'IBM 7855-010'
  392.     port  = '2'
  393.     speed = '19200'
  394.     phone = '322423'
  395.  
  396.     Say ''
  397.     Say 'Customise 'modem' modem for ASYNC (put it in SYNC mode with &M2).'
  398.     Say 'Modem must have been set in AT-commandset mode from the frontpanel!'
  399.     say ''
  400.     say 'Modem is supposed to be on COM'port':'
  401.  
  402.     set AT3'='
  403.  
  404.     /* First see if the modem responds: */
  405.     AT3  port  speed  'I'
  406.     if rc > 0 then signal noreply
  407.  
  408.     /* Reset the modem to the factory settings: */
  409.     AT3  port  '^&F1'
  410.     if rc > 0 then signal problem
  411.  
  412.     /* Transmit the customisation commands: */
  413.     /* (this may be a little bit more than absolutely needed after &F1) */
  414.     AT3 port 'B0 E0 L1 M0 Q0 V1 X4 S0=0'
  415.     AT3 port '^&AP7 ^&AL8 ^&B8N1 ^&C1 ^&D2 ^&I0 ^&L0 ^&M0 ^&R1 ^&S2 ^&X0 ^&Y0'
  416.     AT3 port '^\A3 ^\C3 ^\G0 ^\K2 ^\M14 ^\N3 ^\Q2 ^\R2 ^\T2 ^\V1 ^\X0'
  417.     AT3 port '%%B0 %%C0 %%D0 %%E1 %%F1 %%G1 %%H1 %%I1 %%O1 %%R1 %%V0'
  418.  
  419.     /* Store current configuration to both(!) NVM profiles */
  420.     AT3  port  '^&W0 ^&W1'
  421.  
  422.     /* Finally set the phone number to be auto-dialed in SYNC-mode. */
  423.     AT3  port  '^&Z'phone
  424.  
  425.     exit 0
  426.  
  427.     problem:
  428.     if rc>0 then Say 'See returncode of reported function for probable cause.'
  429.  
  430.     noreply:
  431.     if rc=255 then say '[rc='rc'] Is 'modme' modem connected to COM'port'?'
  432.     exit rc
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.     
  442.         Appendix A.  Sample REXX commandfile for setup of IBM 7855 modem  7