AM4PM.DOC 93-07-14 Rev 24


   What is AM4PM?
   
  AM4PM is a simple answering machine program for OS/2 2.x PM and
  ZyXEL  1496.  I wrote it for personal use because I  could  not
  find  a suitable program. When I started to write it I had  the
  following objectives:
  
  - To be able to distinguish between voice/fax/modem.
    
  - To  be  able  to  use  external programs for  modem  and  fax
    handling. I did not want to write these.
    
  - To  be  able  to  listen to recorded messages from  a  remote
    phone.
    
  - To  make  a  program  that could easily be  modified  without
    having to recompile my code.
    
  - To  make  the program give up the COM port if another program
    needs it.
    
  Other things on the wish list were: call my personal pager or a
  special  phone  number  if an important  message  is  recorded,
  change  the  greeting  message from a  remote  phone  or  at  a
  specified  time,  use  some external program  such  as  ZIP  to
  compress the voice files.
  
  Not  all  these  features  have been implemented  yet,  but  be
  patient;   some   day  they  will.  I  must  also   admit   the
  documentation might need some further work.
  
  PLEASE  note that this documentation does not describe how  the
  ZyXEL  modem  works. To be able to modify the  program  a  good
  knowledge of the voice AT commands is required.
  
  AM4PM is a public domain program. It is free to use and free to
  distribute  as long as unmodified versions of all the  original
  programs  and  this  document are included. Please  report  any
  grammatical or spelling errors in this text to me. How else can
  I learn to write correct English?
  
  I  take  no responsibility whatsoever for any damage AM4PM  can
  cause. Neither do I guarantee the functionality of the program.
  
  I  might  not be able to fix all bugs and answer all  questions
  about AM4PM, but I would like to be informed about problems and
  ideas on further development.
  
  The  program  have  been tested on a 486 clone  with  a  16550A
  running OS/2 2.1 march beta and a ZyXEL 1496+ ROM v6.00.
  
  Thomas Olsson
  Gteborg, Sweden
  email d8olsth@dtek.chalmers.se
  


   What is included in this version?
   
  Most  of  the functionality is programmed in REXX.  AM4PM  adds
  some  functions to the REXX language that makes it possible  to
  control the modem. The REXX scripts that comes with AM4PM gives
  the following functionality:
  
  - The program can be set to answer after a predifined number of
    rings.  It will answer after the programmed number  of  times
    minus one if there are messages waiting. It will then play  a
    greeting  message.  A short beep indicates  the  end  of  the
    greeting message and the beginning of the recording.
    
  - If  a  voice  is heard during recording the message  will  be
    saved. The end of the message is determined either by 7 s  of
    silence or after a specific maximum time.
    
  - If a fax calling tone  or a DTMF '5' is heard during playback
    or recording AM4PM will try to see if it is a fax or a modem.
    This  will  also happen if no voice has been  heard  for  the
    first 7 s of recording.
    
  - If  a  DTMF  '*' is heard during playback or recording  AM4PM
    will enter command mode. A command consists of a DTMF '*' and
    a  number followed by a DTMF '#'. The only available  command
    will  make  it  possible listen to recorded messages  from  a
    remote phone.
    
  - The  COM  port can be released by starting AM4PMCMD with  the
    command  'R'.  The port can also be released by pressing  the
    'Release' button in the PM window. AM4PM will try to open the
    port again after 30 s and thereafter every ten seconds.
    


   The functions of the program
   
  The  main window presents a list of recorded messages. The date
  of  the recording is displayed together with the length of  the
  message if it was recorded in CELP mode.
  
  To  display  the  popup menu press the right  mouse  button  or
  sh-F10.
  
  
  Play
  By  selecting  one  or  more messages  in  the  list  and  then
  selecting  Play  the  messages will be played  in  the  modem's
  internal speaker.
  
  
  Delete
  By  selecting  one  or  more messages  in  the  list  and  then
  selecting  Delete the messages will be deleted.  If  Delete  is
  pressed during playback the messages will be played first.
  
  
  File | Play...
  selected.
      selected. When the Play button is pressed the selected file
      will be played in the speaker of the modem.
      
  
  File | Record...
  A  file  dialog  will  be displayed when File  |  Record...  is
  selected. When the Record button is pressed the recording of  a
  message from the microphone connected to the modem will start.
  
  
  Abort
  By  selecting  Abort  the  current  playback  or  recording  is
  aborted. If a delete operation is delayed due to a playback the
  delete operation will also be aborted.
  
  
  Stop
  The current playback or recording will be stopped when Stop  is
  selected.
  
  
  Release
  Selecting  Release  will release the COM port  for  30  s.  The
  program will then try to reopen to COM port every ten seconds.
  
  This  can also be accomplished by starting the program AM4PMCMD
  with the parameter 'R'.
  


   How to get started
   
  - Put at least all the following files in one directory:
    
     AM4PM.EXE
     AM4PM.MSG
     *.AMC
  
  - Start  AM4PM.EXE. The status bar at the bottom of the  screen
    will  display "Initializing..." and then "Waiting for  call".
    If any other message is written instead check the settings by
    selecting Settings... from the menu.
    
  
  - Make recordings of the following messages:
    
Name               Description
GREETINGS.ZVD      Played when a call is answered.
GREET2.ZVD         Played when someone has pressed the code
                   for listening to the recorded messages.
NOMSG.ZVD          Played to tell that there are no recorded
                   messages.
DELMSG.ZVD         Played to tell that a message has been
                   deleted.
ENDMSG.ZVD         Played to tell that are no more waiting
                   messages.
          
          
  - Change the remote code and the password in RING.AMC.
    
  - If  you  want to use OS2YOU make sure it is in your path.  If
    FaxWorks is to be used to receive faxes see to that FxRcv  is
    in the path.
    
  To  play recorded messages from a remote phone press '*' on the
  phone during the greeting message. This will be acknowledged by
  a  beep. Enter your code (the default code is '123') and  press
  '#'.  The message GREET2.ZVD will be played. If there  are  any
  messages  they will now be played. After all the messages  have
  been  played you will hear ENDMSG.ZVD. If there are no messages
  NOMSG.ZVD is played. During playback of a message you can press
  any of the following keys:
  
  1    Skip to the next message
  
  2    Delete the current message
  
  3    Play the message from the start again
  


   The REXX scripts
   
  AM4PM  uses REXX scripts for many tasks. This makes it easy  to
  modify and costomize the operation of AM4PM. The scripts called
  normally have the file extension AMC. Some functions are  added
  to the REXX language to control the modem.
  
  
  RING.AMC
  This  script is called when AM4PM receives 'VCON' or  a  string
  starting with 'RING' from the modem.
  
  The first parameter is the string that was recieved before this
  script was started. If it is 'VCON' the hook is already off. If
  it  is a string starting with 'RING' the second parameter tells
  the  number  of rings that has been detected so  far  for  this
  call.  When  the time between two successive rings are  greater
  than  five  seconds they are considered to belong to  different
  calls.
  
  mode
  modem  communiction program if it detects a  fax  or  a  modem.
  Features for listening to recorded messages from a remote phone
  might also be included.
  
  To  save  hard  disk space this script can call  a  compression
  program such as LHARC to compress the recorded messages.
  
  If  CID is supported this script can attach a suitable text  as
  an  EA  with the name .SUBJECT to the recorded file.  The  text
  will be displayed in the list of messages.
  
  The  first  parameter can be used together with the distinctive
  ring  feature of some modems to make AM4PM answer in  different
  ways
  
  
  PLAY.AMC
  This  script is called when the user have selected one or  more
  messages  from  the list in the main window in AM4PM  and  then
  selected Play from the menu.
  
  Input parameter is the name of the file to play.
  
  Normally this script just plays the message through the speaker
  in  the  modem,  but if the message is stored in  a  compressed
  format it is necessay to uncompress it first.
  
  Other  functionality in this script can be to play the  message
  on another device such as a SB card.
  
  
  RECORD.AMC
  This  script  is called when the user selects File |  Record...
  from the menu.
  
  Input parameter is the name of the file to record.
  
  Normally   this  script  just  starts  a  recording  from   the
  microphone  connected  to  the modem. The  recording  continues
  until Stop is selected.
  
  Other functionality in this script can be to record the message
  from another device such as a SB card.
  
  
  DELETE.AMC
  This  script is called when the user have selected one or  more
  messages  from  the list in the main window in AM4PM  and  then
  selected Delete from the menu.
  
  Input parameter is the name of the file to delete.
  
  This script just deletes the file.
  
  
  CID.AMC
  This  script is called when AM4PM receives CID information from
  the modem. The CID messages are identified by the string 'TIME'
  at the beginning.
  
  Input parameter is the the string starting with 'TIME'.
  
  The CID information can be displayed in the last event field of
  AM4PM.
  
  
  INIT.AMC
  This  script  is called every time AM4PM want to  reninitialize
  the modem.
  
  Normally  this  script  resets the modem (ATZ),  disables  echo
  (ATE0) and sets answer mode (AT+FCLASS=8).
  
  
  Other scripts
  Other scripts can be called by using the program AM4PMCMD  (see
  separate description below).
  
  This  can  be  used  when another program wants  to  access  to
  functions  of AM4PM. For example if a voice message  should  be
  delivered  at  a specific time the alarm application  can  call
  AM4PMCMD  to  start  a script. That script can  then  call  the
  number and play the message.
  


   The REXX functions
   
  
  handle = AMGetHotComm()
  AM4PM  stops  using  the  COM  port until  AMReleaseHotComm  is
  called. The port is not closed. A file handle to the open  port
  is  returned  and can be used as a parameter to other  programs
  such as REFAX/2 and OS2YOU.
  
  The  settings for data format and handshaking are  restored  to
  the same values they had when AM4PM was started.
  
  
  CALL AMReleaseHotComm
  AM4PM  reinitializes  the port and starts listening  for  input
  again.
  
  
  port = AMCloseComm()
  AM4PM  closes  the  COM  port to make  it  available  to  other
  programs.  The port can be reopened by calling AMOpenComm.  The
  port will also be reopened if the script is ended.
  
  
  CALL AMOpenComm
  AM4PM  opens the port and sets the port mode settings.  If  the
  port  can  not be opened this function will retry  to  open  it
  every ten seconds.
  
  
  CALL AMDPrint text
  Prints  text  to  the  debug window.  Debugging  printouts  are
  enabled  by  starting the debug printout application  and  then
  start AM4PM with the switch '-d'.
  
  
  filename = AMOpenRecFile(mode)
  Creates  a  unique  file to be used for storing  messages.  The
  filename  is  returned.  The file is  created  in  the  current
  directory  and  is  called Mnnnn.ZVD where  nnnn  is  a  unique
  number.
  
  The  mode parameter is used for setting the voice mode  in  the
  modem by sending 'AT+VSM'. The following modes are supported on
  a ZyXEL 1496E+ with ROM v6.00:
  
  1.             CELP    9600 baud. High compression. Fairly good
     quality.
     
  2.            bit ADPCM    19200 baud. Bad quality.
     
  3.            bit ADPCM    28800 baud. Good quality.
     
  Reception  of  a  message is started by calling AMStartRec  and
  ended by calling AMEndRec.
  
  The file must be closed by calling AMCloseRecFile.
  
  
  CALL AMCloseRecFile
  Closes the message file opened by calling AMOpenRecFile.
  
  This  function also attaches an EA with the name  AM4PM.LEN  to
  the  file that tells the length of the message in seconds. This
  EA  should  be  of type BINARY and stored as a 32-bit  unsigned
  integer.  The length information will be displayed in the  list
  of  messages.  If  this  EA is not found  the  length  will  be
  calculated as the file size divided by 2000.
  
  
  dlecode = AMPlayFile(filename)
  Plays  the  file filename. If a DLE code is returned  from  the
  modem  the  playback  is  aborted and  the  code  is  returned.
  Otherwise a blank is returned. At least following codes can  be
  returned:
  
  '0'-'9', '*', '#'   A DTMF code was received.
  
  c          A fax calling tone was received.
  
  b          A busy tone was received.
  
  
  CALL AMStartRec
  Starts  recording. The message is saved in the current  message
  file  opened by calling AMOpenRecFile. The recording is stopped
  by   calling  AMEndRec  and  the  file  is  closed  by  calling
  AmCloseRecFile.
  
  The function AMWaitDLECode is normally called between this call
  and AMEndRec to see if any DLE codes are heard.
  
  
  CALL AMEndRec
  Ends  the  recording.  The  file  must  be  closed  by  calling
  AMCloseRecFile.
  
  
  CALL AMStartListenDLECode
  Start  recording but does not save the message to a file.  This
  is  used to listen for DLE codes. The listening must be stopped
  by calling AMEndListenDLECode.
  
  The function AMWaitDLECode is normally called between this call
  and AMEndListenDLECode to see if any DLE codes are heard.
  
  
  CALL AMEndListenDLECode
  Ends the listening for DLE codes.
  
  
  dlecode = AMWaitDLECode()
  Listen  for  DLE  codes  during  recording  started  either  by
  AMStartRec  or  AMStartListenDLECode. At  least  the  following
  codes can be returned
  
  '0'-'9', '*', '#' A DTMF code was received.
               
  c           A fax calling tone was received.
               
  b           A busy tone was received.
               
  q            Quiet  detected.  Some  voice  was  heard  at  the
               beginning, but now there is silence.
               
  s            Silence detected. No voice has been heard at all.
               
  
  dceresp = AMSendW(text)
  Sends  the  text text followed by CR/LF to the modem  and  then
  waits for a response. The response is returned. Note that  this
  functions waits for a LF to be received from the modem.
  
  
  dceresp = AMGetMoreDCEResp()
  response
  response  to AMSendW this function can the be used to  retrieve
  them.
  
  
  rc = AMStartProg(command)
  Starts  the  program  found  at the  beginning  of  the  string
  command.  The  program  name must be  given  without  path  and
  extension.  The  environment variable path will  be  used  when
  searching  for  the file. All text following the  program  name
  will be used as a parameter to the program.
  
  The return code of the program is returned.
  
  The  program  will  be started minimized and  closed  when  the
  session ends unless AM4PM is in debug mode.
  
  
  CALL AMSetStateText text
  Sets the text in the AM4PM window under the heading 'State'  to
  text.
  
  The  text is reset to 'Waiting for call' when the rexx  program
  terminates.
  
  
  CALL AMSetLastEventText text
  Sets  the  text  in  the AM4PM window under the  heading  'Last
  event' to text.
  
  The text is set to 'Abort' when Abort is pressed.
  
  
  value = AMReadIni(key, default)
  Retreives a value from the file AM4PM.INI.
  
  
  CALL AMWriteIni(key, value)
  Sets a value in the file AM4PM.INI.
  


   The REXX variables
   
  AM4PM adds some variables to the REXX script language.
  
  
  vAMRings
  The  number of rings that should be heard before AM4PM answers.
  This  value can be changed by the script and the new value will
  be stored.
  
  
  vAMMsgs
  The number of messages recorded.
  


   AM4PMCMD
   
  This program is used for controlling AM4PM from other programs.
  It sends messages to AM4PM. All messages are queued.
  
Command          Description
R                Release COM port for 30 s. AM4PM will
                 then try to reopen the port every 10 s.
                 AM4PMCMD waits until the port is
                 released.
C command        Tells AM4PM to run the script command.
                 AM4PMCMD does not wait for the script
                 to execute. All text after the first
                 space in command will be sent as a
                 parameter to the script. For example
                 the command
                    AM4PMCMD C "play.amc greeting.zvd"
                    
                    will play the message greeting.zvd.
          
          
  A return code of zero indicates a successful call.
  


   The file AM4PM.INI
   
Key              Description
Rings            The number of rings before answering.
Com              The name of the COM port to open.
Baud             The baud rate to use when communicating
                 with the modem.
Titles           Set to 'Y' if the field titles should
                 be displayed in the list of messages.
          
          
  The  values used by AM4PM must not be changed when the  program
  is  running.  To modify the settings use the variables  in  the
  Rexx script language.
  
  This  file can also be used to store values of other keys  used
  by scripts written for AM4PM. No version of AM4PM will ever use
  a  key starting with an 'x'. This can be used to make sure that
  there is no conflict with future versions.
  


   Functions I will add some day
   
  -  Better error handling.
      
  -  Keep  track of messages that have never been listened to and
      mark them in some way in the list.
      
  -  The  icon displayed when the program is minimized should  be
      changed when there are messages waiting.
      
  -  Make  it  possible  to  use  AM4PM with  Rockwell  chip  set
      modems.
      
  -  Make  it  possible to change greeting message from a  remote
      phone.
      
  -  An  installation  program  that  generates  the  AMC  script
      files.
      
