home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / shackos2.zip / hacksaw.doc < prev    next >
Text File  |  1997-06-12  |  87KB  |  1,690 lines
  1.  
  2.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  3.                             Hacksaw Version 1.0c
  4.                       InnoVal Systems Solutions, Inc.
  5.                                June 12, 1997
  6.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  7.  
  8.      Hacksaw is a very useful character mode (command-line-based) tool for
  9.      people who deal with files on the internet.  There are identical
  10.      versions for OS/2 and for Windows 95/NT.  This tool can retrieve files
  11.      and headers from HTTP servers; send email to SMTP servers; check,
  12.      retrieve, and delete email from POP3 servers; and has many very
  13.      powerful functions for dealing with FTP servers.  It can be used
  14.      interactively, asking you for the information it needs as it goes
  15.      along.  Or the information can be given to it in an automated fashion,
  16.      so that it can be activated by a scheduler program (like InnoVal's own
  17.      WebSched) in the middle of the night while you're asleep.
  18.  
  19.      If you type HACKSAW by itself or with ? as its argument at the command
  20.      line, it will show you a summary of its syntax.  However, please don't
  21.      try to use that summary alone, to figure out how to use HACKSAW.  It
  22.      won't make very much sense unless you've read this document first.
  23.      Besides, you'll also be missing out on a lot of HACKSAW capabilities
  24.      that aren't explained there.  (That summary screen is also reproduced
  25.      at the end of this document, for your convenience.)
  26.  
  27.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  28.                                How to Install
  29.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  30.  
  31.     Just put the HACKSAW.EXE file into a directory that's on your PATH.
  32.     That's all there is to it.
  33.  
  34.     Unless you want to be able to run both the Windows 95/NT version and the
  35.     OS/2 version on the same machine.  In that case, there are two ways you
  36.     can do it.  Your can put the OS/2 version of HACKSAW.EXE into a
  37.     directory that's on your OS/2 PATH but not on your Windows or NT PATH,
  38.     and vice versa; in which case each of those directories will have its
  39.     own HACKSAW.INI file and you'll need to copy it from one directory to
  40.     the other each time you make a change to it, if you want them to be
  41.     identical.  Or you can keep both HACKSAW.EXE files in the same directory
  42.     if you rename the OS/2 version to HACKOS2.EXE, or rename the Windows
  43.     version to HACKWIN.EXE, and execute HACKOS2 and HACKWIN commands instead
  44.     of HACKSAW commands.  In this case, both versions will be using the same
  45.     copy of the HACKSAW.INI file.
  46.  
  47.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  48.                                  How to Use
  49.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  50.  
  51.      In order to tell HACKSAW what you want it to do, you must give it some
  52.      command line arguments.  Either:
  53.  
  54.        1.  The name of a control file which has COMMAND and SUBCOMMAND
  55.            arguments on its first line (see the CONTROL FILES section of
  56.            this document for more information), or
  57.        2.  A command and a subcommand, and optionally other arguments
  58.  
  59.      The HACKSAW commands tell HACKSAW what kind of server it's going to
  60.      deal with.  The choices are:
  61.  
  62.                 1.  FTP to interact with an FTP server
  63.                 2.  HTTP to interact with an HTTP server
  64.                 3.  EMAIL to interact with an SMTP or POP3 server
  65.                 4.  DEFINE to store data in the HACKSAW.INI file
  66.  
  67.      The subcommands tell HACKSAW what you want to do with that server.
  68.      The available FTP subcommands are:
  69.  
  70.                               1.  SEND
  71.                               2.  SENDALL
  72.                               3.  SYNCHRONIZEHOST
  73.                               4.  RETRIEVE
  74.                               5.  RETRIEVEALL
  75.                               6.  SYNCHRONIZELOCAL
  76.                               7.  LIST
  77.                               8.  DELETE
  78.                               9.  RENAME
  79.                              10.  SITECOMMAND
  80.  
  81.      The available HTTP subcommands are:
  82.  
  83.                               1.  RETRIEVE
  84.                               2.  RETRIEVEHEADERS
  85.  
  86.      The available EMAIL subcommands are:
  87.  
  88.                                 1.  SEND
  89.                                 2.  MAILWAITING
  90.                                 3.  RETRIEVE
  91.                                 4.  DELETE
  92.  
  93.      The DEFINE subcommands are:
  94.  
  95.                               1.  DEFAULT_USERID
  96.                               2.  PASSWORD
  97.                               3.  DEFAULT_MAILUSER
  98.                               4.  DEFAULT_MAILFROM
  99.                               5.  SMTP_SERVER
  100.                               6.  POP3_SERVER
  101.                               7.  FTP_SERVER
  102.                               8.  FTPPROXY_SERVER
  103.                               9.  HTTPPROXY_SERVER
  104.                              10.  FTPPROXY_PORT
  105.                              11.  HTTPPROXY_PORT
  106.                              12.  PROXY
  107.                              13.  PROXY_IGNORE_FILE
  108.                              14.  VARIABLE
  109.  
  110.      Once you've given HACKSAW a command and a subcommand, there are four
  111.      ways of giving the program the rest of the information it needs:
  112.  
  113.                            1.  Prompting
  114.                            2.  The HACKSAW.INI file
  115.                            3.  Command line arguments
  116.                            4.  Control files
  117.  
  118.      These methods can be used in any combination.  That is, you can
  119.      specify some of the arguments at the command line and others in a
  120.      control file, etc.  However, if you have the same argument specified
  121.      in more than one place, the only one that will be used will be the one
  122.      closer to the bottom of the above list.  For example, the program
  123.      won't look for something in the HACKSAW.INI file unless it was not
  124.      found in a control file nor in the command line arguments.  And the
  125.      program won't pay attention to a command line argument, if the same
  126.      argument was also specified, with a different value, in the control
  127.      file.
  128.  
  129.      HACKSAW commands, subcommands, arguments, and variables are all
  130.      completely case insensitive.  That is, "FTP" and "ftp" are seen as
  131.      identical; "SEND" and "send" are seen as identical; "HostFile" and
  132.      "hOsTfIlE" are seen as identical; and "&MyGifDir" and "&MYGIFDIR" are
  133.      seen as identical.  But remember, most FTP servers run on a UNIX
  134.      operating system, and under UNIX, filenames and directory names are
  135.      case sensitive.  So if you tell HACKSAW to retrieve "filename.htm" and
  136.      the file's name on the server machine is "FILENAME.HTM", or vice versa,
  137.      it isn't going to work unless the server is one which does not see
  138.      filenames as being case sensitive.
  139.  
  140.      1.  Prompting
  141.  
  142.      If your control file, command line arguments, and HACKSAW.INI file do
  143.      not include all the information HACKSAW needs in order to perform the
  144.      function you've told it to perform, it will prompt you for all the
  145.      other required arguments, one item at a time.  For example, if you
  146.      type HACKSAW FTP DIR at the command line, HACKSAW will ask you for the
  147.      FTP server's address and you'll type that, then HACKSAW will ask you
  148.      for your userid and you'll type that, then HACKSAW will ask you for
  149.      your password and you'll type that, etc.  But there's no way to enter
  150.      an optional argument using the prompting method.  HACKSAW only prompts
  151.      for required arguments, not optional ones.  So if you want to use an
  152.      optional argument, you must specify it via one of the other methods.
  153.      If you press the ESC key at any time during the prompting process,
  154.      HACKSAW will exit.
  155.  
  156.      2.  The HACKSAW.INI File
  157.  
  158.      HACKSAW can keep a default FTP server and userid; passwords for
  159.      multiple FTP, HTTP, and POP3 userids; default from address and SMTP
  160.      server for sending email; default POP3 server, userid, and password
  161.      for retrieving email; a server name and port number for an FTP proxy
  162.      server and an HTTP proxy server; a setting for whether or not proxy
  163.      support is currently on or off; and a setting for servers for which you
  164.      want your proxy support to be ignored, in the HACKSAW.INI file.  (You
  165.      use HACKSAW's DEFINE command to put them there.)  So any time you don't
  166.      supply these arguments in a control file or on the command line,
  167.      HACKSAW will look for them in that file.  If they're not there either,
  168.      it will prompt you for the required ones during execution.
  169.  
  170.      3.  Command line arguments
  171.  
  172.      If you don't want HACKSAW to prompt you for the arguments that it
  173.      doesn't have stored in the HACKSAW.INI file (or if you want to
  174.      temporarily override an entry in that file), one of your options is to
  175.      feed it the information as command line arguments.  A HACKSAW argument
  176.      must be specified as an argument name, followed (without a space) by
  177.      the argument value in parentheses.  For example, to tell HACKSAW the
  178.      userid and password to use for an FTP SEND operation, you might say:
  179.  
  180.         HACKSAW FTP SEND USERID(innoval) PASSWORD(secret)
  181.  
  182.      (Don't worry, you don't have to include your password on the command
  183.      line or in the control file, for everyone to see, each time you issue
  184.      a HACKSAW command!  You can use the DEFINE command to have HACKSAW
  185.      store a password in its HACKSAW.INI file, for each userid you have.
  186.      And of course, the passwords are encrypted before they're stored.)
  187.  
  188.      You can leave off the closing parenthesis, if you like:
  189.  
  190.         HACKSAW FTP SEND USERID(innoval PASSWORD(secret
  191.  
  192.      You can type HACKSAW arguments in any order, since each argument has a
  193.      label that tells HACKSAW what it's supposed to be.  So the following
  194.      example is exactly the same, as far as HACKSAW is concerned, as the
  195.      above two examples:
  196.  
  197.         HACKSAW FTP SEND PASSWORD(secret) USERID(innoval)
  198.  
  199.      There are also abbreviations or synonyms that you can use for most
  200.      HACKSAW commands, subcommands, and arguments.  For example, PW is a
  201.      valid abbreviation for the PASSWORD argument and U is a valid
  202.      abbreviation for the USERID argument.  So the following command is
  203.      equivalent to the previous ones:
  204.  
  205.         HACKSAW FTP SEND PW(secret) U(innoval)
  206.  
  207.      The recognized synonyms for each HACKSAW command and argument are
  208.      listed on the right side of HACKSAW's syntax screen.  HACKSAW will
  209.      show you its syntax screen any time you execute it without arguments
  210.      or with ? as its argument at the command line.  That screen is also
  211.      reproduced at the end of this document, for your convenience.
  212.      Elsewhere in this document, only the unabbreviated version of each
  213.      command, subcommand, and argument will be used, to avoid confusion; but
  214.      you can use any recognized abbreviation at any time.
  215.  
  216.      Any time the value of an argument (what goes in parentheses) is more
  217.      than one word long (has a space in it), you must surround the value
  218.      with quotation marks.  Otherwise, the operating system's command
  219.      interpreter will not send the argument to HACKSAW in the way that
  220.      HACKSAW can recognize it.  For example:
  221.  
  222.         HACKSAW FTP SEND LOCALFILE("e:\long named dir\filename.ext")
  223.  
  224.      Don't forget that the & symbol has a special meaning to OS/2's command
  225.      interpreter (it separates one command from another on the same command
  226.      line), so if you need to include that symbol in a HACKSAW argument
  227.      under OS/2, you must surround it with quotation marks as well.  This
  228.      way, CMD.EXE will ignore the & symbol and pass the entire argument to
  229.      HACKSAW the way you intended:
  230.  
  231.         HACKSAW HTTP RETRIEVE LOCALFILE(results.txt)
  232.         HOSTFILE("qs.secapl.com/cgi-bin/qs?&tick=alyd")
  233.  
  234.      Any command line argument that HACKSAW doesn't recognize as a valid
  235.      argument for the subcommand being processed, will be entirely ignored.
  236.      So if, for example, you were to use a SINCE argument with an FTP
  237.      SYNCHRONIZEHOST subcommand, the result would be exactly the same as if
  238.      you hadn't.
  239.  
  240.      4.  Control Files
  241.  
  242.      Control files can be used for the same purpose command line arguments
  243.      are used, but they also have an ability that command line arguments do
  244.      not have:  They can tell HACKSAW to perform the same function on
  245.      multiple files at once; to send multiple email messages at once; or to
  246.      retrieve email messages (perhaps from multiple POP3 accounts) into
  247.      multiple mail files at once.  See the CONTROL FILES section of this
  248.      document for more information.
  249.  
  250.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  251.                               FTP SUBCOMMANDS
  252.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  253.  
  254.      These arguments (shown with example values) are required for all FTP
  255.      subcommands:
  256.  
  257.         HOST(ftp.innoval.com)
  258.         USERID(innoval)
  259.         PASSWORD(secret)
  260.         PORT(22) if your FTP server's port number is anything other than
  261.            the default of 21; which is rare, so most people do not need
  262.            this argument; but if you have an FTP server with a non-default
  263.            port, you'll need this argument for every HACKSAW FTP command
  264.            you use to reach that server
  265.         PROXYHOST(internet.innoval.com) if you have FTP access through a
  266.            firewall which uses the type of classical proxy software which
  267.            wants to receive the target server name as part of the userid;
  268.            for example userid@ftp.innoval.com; or if you have a proxy
  269.            server specified in the HACKSAW.INI file and you need for
  270.            HACKSAW to temporarily ignore it, specify "none" or "n" as the
  271.            server name here, or use the HACKSAW DEFINE PROXY subcommand to
  272.            turn off proxy support for a longer period of time, or use
  273.            HACKSAW DEFINE PROXY_IGNORE_FILE to specify certain servers for
  274.            which you always want proxy support to be ignored
  275.         PROXYPORT(22) if that proxy server's FTP port number is anything
  276.            other than the default of 21
  277.  
  278.      Or you could put the arguments into a control file, and use only this
  279.      argument at the command line:
  280.  
  281.         CONTROLFILE(e:\hacksaw\ctrlfile.001)
  282.  
  283.      Optional arguments are:
  284.  
  285.         HOSTDIRECTORY(/innoval)
  286.         LOCALDIRECTORY(e:\stuff)
  287.  
  288.      When you need to tell HACKSAW the directory in which to find or place
  289.      a local file or a host file, you can do it in one of two ways.  If
  290.      you're also specifying a filename to go along with that directory,
  291.      then you can specify the directory and filename together as part of
  292.      the LOCALFILE or HOSTFILE argument, like so:
  293.  
  294.         LOCALFILE(e:\dirname\filename.ext)
  295.  
  296.      Or you can specify just the filename in the LOCALFILE or HOSTFILE
  297.      argument, and use the HOSTDIRECTORY or LOCALDIRECTORY argument to
  298.      specify the directory name.  For example, this line of arguments:
  299.  
  300.         LOCALFILE(e:\stuff\filename.ext) HOSTFILE(/innoval/filename.new)
  301.  
  302.      will cause the same result as the following:
  303.  
  304.         LOCALFILE(filename.ext) LOCALDIRECTORY(e:\stuff)
  305.         HOSTFILE(filename.new) HOSTDIRECTORY(/innoval)
  306.  
  307.      When a LOCALDIRECTORY is specified, it will be prepended to the
  308.      LOCALFILE argument (with a backslash).  When a HOSTDIRECTORY is
  309.      specified, it will be prepended to the HOSTFILE argument (with a
  310.      slash).  (Or if the target filename is not specified on an FTP command,
  311.      HACKSAW will use the part of the source filename past the last slash as
  312.      the target filename, before prepending the directory name to it.)  Why
  313.      would one want to do this?  In a control file, where you can have a
  314.      list of several files to act upon at once, you can use the
  315.      LOCALDIRECTORY or HOSTDIRECTORY argument to tell HACKSAW where the
  316.      files should be, and then each file argument only needs to contain the
  317.      filename, not the entire path to the file.
  318.  
  319.      An even better use for these directory arguments is with & or $
  320.      variables.  You can use the DEFINE VAR subcommand to assign the string
  321.      "/pub/company/thisdir/graphics" to the variable "MyGifDir".  From then
  322.      on, any time you want to say "/pub/company/thisdir/graphics" to
  323.      HACKSAW, you need only tell it "&MyGifDir" or "$MyGifDir" (whichever
  324.      you like) instead.  So you can say HOSTDIRECTORY(&MyGifDir) or
  325.      HOSTDIRECTORY($MyGifDir), and HOSTFILE(filename.gif), instead of
  326.      HOSTFILE(/pub/company/thisdir/graphics/filename.gif).
  327.  
  328.      If you want the target file's name to be the same as the source file's
  329.      name, in an FTP SEND or RECEIVE operation, you don't have to specify it
  330.      in the HOSTFILE or LOCALFILE argument.  But if you don't specify it,
  331.      and you do want to specify the target directory, you cannot use the
  332.      HOSTFILE or LOCALFILE argument for that purpose.  You can only use
  333.      HOSTFILE or LOCALFILE in that way when the specification includes the
  334.      filename as well as the directory name.  So if the target directory is
  335.      not the current directory of the local drive or the root directory of
  336.      the host (or the point of entry for the userid under which you logged
  337.      on), then you have no choice but to use the LOCALDIRECTORY or
  338.      HOSTDIRECTORY argument to specify it.
  339.  
  340.         CHANGEDIRECTORY(/pub)
  341.  
  342.      This argument can be used in place of HOSTDIRECTORY if you need for
  343.      HACKSAW to issue a CWD command to the FTP server before performing the
  344.      command.
  345.  
  346.         PROXYIGNOREFILE(c:\hacksaw\servers.ign)
  347.  
  348.      This argument can be used at the command line or via a control file,
  349.      but is much more likely to be used more permanently via a HACKSAW
  350.      DEFINE PROXY_IGNORE_FILE subcommand.  It is useful, though, at the
  351.      command line or in a control file, if you want HACKSAW to temporarily
  352.      ignore the PROXY_IGNORE_FILE setting in your HACKSAW.INI file:  Just
  353.      use "none" or "n" as the value inside the parentheses.
  354.  
  355.      1.  The SEND Subcommand
  356.  
  357.      This subcommand is used to send one file from the local PC to the host
  358.      server.  It requires the following argument (in addition to the ones
  359.      which are required for all FTP subcommands):
  360.  
  361.         LOCALFILE(e:\dirname\filename.ext)
  362.  
  363.      Optional arguments are:
  364.  
  365.         HOSTFILE(/innoval/filename.new) if you want to specify the name the
  366.            file should receive on the host
  367.  
  368.         TYPE(ascii) if you don't want your file sent in binary mode
  369.  
  370.            Note that HACKSAW FTP sends and retrieves all files in binary
  371.            mode by default.  This is different from most FTP tools, which
  372.            default to ascii mode.  This is because the vast majority of FTP
  373.            transfers are done in binary mode, and we think that people
  374.            shouldn't have to specify the mode they use nearly all the time;
  375.            it should be the default.
  376.  
  377.            "a" is a synonym for "ascii" as the value for the TYPE argument.
  378.            Also, "b" is a synonym for "binary", but the only reason to ever
  379.            use a binary TYPE argument is in a control file where your
  380.            global argument is ascii but you have an exception that needs to
  381.            be sent in binary mode.  Because in any other situation, HACKSAW
  382.            assumes the TYPE(binary) argument without your specifying it.
  383.  
  384.         SITECOMMAND(chmod 666) if you want HACKSAW to execute the site
  385.            command "chmod 666 [HOSTFILE]" for you after transferring the
  386.            file
  387.  
  388.            Note that by default, HACKSAW will append the HOSTFILE name to
  389.            the end of the site command you specify.  (If you don't specify
  390.            HOSTFILE in a SEND subcommand, HACKSAW uses the same name as the
  391.            source file, so that's what it uses as a HOSTFILE argument in
  392.            the site command as well.)  If you need for the HOSTFILE name to
  393.            instead be inserted at some other point in the command, just
  394.            place the string &HF or $HF into your site command at that point.
  395.            For example, SITECOMMAND(chmod $HF 666) would tell HACKSAW to
  396.            execute "chmod [HOSTFILE] 666" after the file has been
  397.            transferred.
  398.  
  399.      Example:  HACKSAW FTP SEND HOST(ftp.innoval.com) USERID(innoval)
  400.                PASSWORD(secret) LOCALFILE(e:\dirname\filename.ext)
  401.  
  402.      2.  The SENDALL Subcommand
  403.  
  404.      This subcommand is used to send all the files in a directory, or all
  405.      the files which match a wildcard specification, from the local PC to
  406.      the host server.  It requires the same arguments as the SEND
  407.      subcommand, with the following exceptions:
  408.  
  409.         LOCALFILE:  Optional.  Instead of one filename, you can specify *
  410.            which means all files (this is the default, so you don't even
  411.            have to specify it), or *.* which means all files which have an
  412.            extension, or *.EXE which means only files which have the
  413.            extension EXE, or T* which means only files which start with T,
  414.            etc.
  415.  
  416.         HOSTFILE:  Not used; the host files will have the same filenames
  417.            as the local files.
  418.  
  419.      Optional arguments are:
  420.  
  421.         SINCE(19961225172536) to tell HACKSAW to send only the files with a
  422.            time stamp of 5:25:36pm on December 25, 1996, or later.  That
  423.            is, the time stamp is specified as yyyymmddhhmmss.  You may
  424.            insert any number of space characters, if you like, to make that
  425.            argument more readable.  For example, SINCE(1996 12 25 172536).
  426.            If you omit any amount of the end of the date string, the
  427.            program will assume the lowest possible values for the omitted
  428.            parts.  For example, if you drop the minutes and seconds, the
  429.            program will assume 00:00.  If you drop the day, hours, minutes,
  430.            and seconds, the program will assume 00:00:00 on the 1st of the
  431.            specified month.  You can also specify TODAY (or leave the value
  432.            in parentheses blank) or YESTERDAY as the value, and the program
  433.            will translate that to 00:00:00 of the date which represents
  434.            today or yesterday.
  435.  
  436.         CASE(lower) if you want the host filenames to be in lowercase
  437.         CASE(upper) if you want the host filenames to be in uppercase
  438.         CASE(drive) if you want the host filenames to be in the same case as
  439.            the local filenames
  440.  
  441.            If you don't use this argument, HACKSAW will send the files with
  442.            the same filenames they have on the local drive.  Using this
  443.            argument, you can specify that they should be sent in uppercase
  444.            or lowercase.  The only reason to ever use "drive" as a CASE
  445.            argument is in a control file where your global argument is
  446.            upper or lower but you have an exception that needs to be sent
  447.            with the normal case treatment instead.
  448.  
  449.            You can use "l", "u", or "d" instead of spelling out "lower",
  450.            "upper", or "drive".
  451.  
  452.         TYPE:  Exactly as used with the SEND subcommand.
  453.  
  454.         SITECOMMAND:  Exactly as used with the SEND subcommand.
  455.  
  456.      Example:  HACKSAW FTP SENDALL HOST(ftp.innoval.com) USERID(innoval)
  457.                PASSWORD(secret)
  458.  
  459.      3.  The SYNCHRONIZEHOST Subcommand
  460.  
  461.      This subcommand is used to make the host directory match the local
  462.      one, by sending all files which exist on the local PC but not on the
  463.      host, and each file which has a later timestamp on the local PC than
  464.      the matching file on the host.  It requires the same arguments as the
  465.      SEND subcommand, with the same required exceptions as the SENDALL
  466.      subcommand.
  467.  
  468.      Optional arguments are:
  469.  
  470.         HOST-LOCALTIMEDIFFERENCE(2:08) to tell HACKSAW that in order to
  471.            compare the time stamps of the files, it must add 2 hours and 8
  472.            minutes to the time stamps of the files on the host.  You would
  473.            use this value as an argument if your FTP server were two time
  474.            zones west of you and also had a clock that was running 8
  475.            minutes slower than your PC's clock.  If it were two time zones
  476.            west and running 8 minutes faster, then your argument would be
  477.            HOST-LOCALTIMEDIFFERENCE(1:52) instead.  If the server were two
  478.            time zones east of you and set to the right time, the argument
  479.            would be HOST-LOCALTIMEDDIFFERENCE(-2).  Or for one time zone
  480.            east, running 8 minutes fast, HOST-LOCALTIMEDIFFERENCE(-0:52).
  481.  
  482.         CASE:  Exactly as used with the SENDALL subcommand.
  483.  
  484.         TYPE:  Exactly as used with the SEND subcommand.
  485.  
  486.         SITECOMMAND:  Exactly as used with the SEND subcommand.
  487.  
  488.      Example:  HACKSAW FTP SYNCHRONIZEHOST HOST(ftp.innoval.com)
  489.                USERID(innoval) PASSWORD(secret)
  490.  
  491.      4.  The RETRIEVE Subcommand
  492.  
  493.      This subcommand (or its popular synonym, GET) is used to download one
  494.      file from the host server to the local PC.  It requires the following
  495.      arguments (in addition to the ones which are required for all FTP
  496.      subcommands):
  497.  
  498.         HOSTFILE(/innoval/filename.ext)
  499.  
  500.      Optional arguments are:
  501.  
  502.         LOCALFILE(e:\dirname\filename.new) if you want to specify the name
  503.            the file should receive on the local drive
  504.  
  505.         TYPE:  Exactly as used with the SEND subcommand.
  506.  
  507.         SITECOMMAND:  Exactly as used with the SEND subcommand.
  508.  
  509.      Example:  HACKSAW FTP RETRIEVE HOST(ftp.innoval.com) USERID(innoval)
  510.                PASSWORD(secret) HOSTFILE(/innoval/filename.ext)
  511.  
  512.      5.  The RETRIEVEALL Subcommand
  513.  
  514.      This subcommand (or its popular synonym, GETALL) is used to retrieve
  515.      all the files in a directory, or all the files which match a wildcard
  516.      specification, from the host server to the local PC.  It requires the
  517.      same arguments as the RETRIEVE subcommand, with the following
  518.      exceptions:
  519.  
  520.         HOSTFILE:  Optional.  Instead of one filename, you can specify *
  521.            which means all files (this is the default, so you don't even
  522.            have to specify it unless you're also specifying a directory
  523.            name here or in a HOSTDIRECTORY argument), or *.* which means all
  524.            files which have an extension, or *.EXE which means only files
  525.            which have the extension EXE, or T* which means only files which
  526.            start with T, etc.
  527.  
  528.         LOCALFILE:  Not used; the local files will have the same filenames
  529.            as the source files.
  530.  
  531.      Optional arguments are:
  532.  
  533.         SINCE:  Exactly as used with the SENDALL subcommand.
  534.  
  535.         TYPE:  Exactly as used with the SEND subcommand.
  536.  
  537.         SITECOMMAND:  Exactly as used with the SEND subcommand.
  538.  
  539.      Example:  HACKSAW FTP RETRIEVEALL HOST(ftp.innoval.com)
  540.                USERID(innoval) PASSWORD(secret) HOSTFILE(/dirname/*)
  541.  
  542.      6.  The SYNCHRONIZELOCAL Subcommand
  543.  
  544.      This subcommand is used to make the local directory match the host
  545.      one, by retrieving all files which exist on the host but not on the
  546.      local PC, and each file which has a later timestamp on the host than
  547.      the matching file on the local PC.  It requires the same arguments as
  548.      the RETRIEVE subcommand, with the same required exceptions as the
  549.      RETRIEVEALL subcommand.
  550.  
  551.      Optional arguments are:
  552.  
  553.         HOST-LOCALTIMEDIFFERENCE:  Exactly as used with the SYNCHRONIZEHOST
  554.            subcommand.
  555.  
  556.         TYPE:  Exactly as used with the SEND subcommand.
  557.  
  558.         SITECOMMAND:  Exactly as used with the SEND subcommand.
  559.  
  560.      Example:  HACKSAW FTP SYNCHRONIZELOCAL HOST(ftp.innoval.com)
  561.                USERID(innoval) PASSWORD(secret) HOSTFILE(/dirname/*)
  562.  
  563.      7.  The LIST Subcommand
  564.  
  565.      This subcommand (or its popular synonym, DIR) is used to get a list of
  566.      the files on the host and some information about each of them.  It
  567.      requires the following arguments (in addition to the ones which are
  568.      required for all FTP subcommands):
  569.  
  570.         HOSTFILE:  Usually a wildcard specification.  Describes the files
  571.            whose information you want the server to show you.  If you want
  572.            the information on the entire current directory, using most FTP
  573.            programs you would just not specify any file; but with HACKSAW,
  574.            leaving out the HOSTFILE specification causes HACKSAW to prompt
  575.            you for it during execution.  To prevent that, you can specify .
  576.            (a single period) as the HOSTFILE.  Do not use *.* for this
  577.            purpose, since it will only show you the files which have an
  578.            extension.  And * will show you the current directory and all of
  579.            its subdirectories as well.  So for the entire current directory
  580.            and nothing else, use . as the HOSTFILE specification.
  581.  
  582.         LOCALFILE:  Can be CON, to show the information on your screen; or
  583.            it can be a filename, in which the information will be stored.
  584.            If the file already exists, it will be overwritten, as would be
  585.            expected with any other FTP function.
  586.  
  587.      Example:  HACKSAW FTP LIST HOST(ftp.innoval.com) USERID(innoval)
  588.                PASSWORD(secret) HOSTFILE(/innoval/*.EXE)
  589.                LOCALFILE(e:\stuff\dirs.out)
  590.  
  591.      8.  The DELETE Subcommand
  592.  
  593.      This subcommand is used to delete a file from the host.  It requires
  594.      the following argument (in addition to the ones which are required for
  595.      all FTP subcommands):
  596.  
  597.         HOSTFILE(/innoval/filename.ext)
  598.  
  599.            Note:  This argument does support wildcards, such as * for all
  600.            files or *.TXT for all files with TXT as their extension.
  601.  
  602.      Example:  HACKSAW FTP DELETE HOST(ftp.innoval.com) USERID(innoval)
  603.                PASSWORD(secret) HOSTFILE(/innoval/filename.ext)
  604.  
  605.      9.  The RENAME Subcommand
  606.  
  607.      This subcommand is used to rename a file on the host.  It requires the
  608.      following arguments (in addition to the ones which are required for
  609.      all FTP subcommands):
  610.  
  611.         SOURCEFILE(/innoval/filename.ext)
  612.  
  613.         TARGETFILE(filename.new)
  614.  
  615.            Note:  The reason this example will work is the fact that HACKSAW
  616.            will copy the source directory specification to the target
  617.            filename specification for you, before passing the command to the
  618.            server.  So you don't have to type the directory name in both
  619.            places even though the server requires it to be in both places.
  620.  
  621.      Example:  HACKSAW FTP RENAME HOST(ftp.innoval.com) USERID(innoval)
  622.                PASSWORD(secret) SOURCEFILE(/innoval/filename.ext)
  623.                TARGETFILE(filename.new)
  624.  
  625.      10.  The SITECOMMAND Subcommand
  626.  
  627.      This subcommand makes HACKSAW tell the FTP server to execute a site
  628.      command on the host computer.  It requires the following arguments (in
  629.      addition to the ones which are required for all FTP subcommands):
  630.  
  631.         HOSTFILE(/innoval/filename.ext)
  632.  
  633.         SITECOMMAND(chmod 666) to tell the server to execute "chmod 666
  634.            [HOSTFILE]"
  635.  
  636.            Notice that by default, HACKSAW appends the HOSTFILE name to the
  637.            end of the site command you specify.  If you need for the
  638.            HOSTFILE name to instead be inserted at some other point in the
  639.            command, just place the string $HF or &HF into your site command
  640.            at that point.  For example, SITECOMMAND(chmod $HF 666) would
  641.            tell HACKSAW to execute "chmod [HOSTFILE] 666" instead.
  642.  
  643.      Example:  HACKSAW FTP SITECOMMAND HOST(ftp.innoval.com)
  644.                USERID(innoval) PASSWORD(secret) SITECOMMAND(chmod 666)
  645.                HOSTFILE(/innoval/filename.ext)
  646.  
  647.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  648.                               HTTP SUBCOMMANDS
  649.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  650.  
  651.      These arguments (shown with example values) are required for all HTTP
  652.      subcommands:
  653.  
  654.         HOSTFILE(www.innoval.com)
  655.         LOCALFILE(index.htm) must be specified even if the filename is to be
  656.            the same as the source file on the host; the program does not
  657.            have any way of being able to tell whether the HOSTFILE you've
  658.            specified is a filename or a directory name, so it cannot assume
  659.            that whatever's after the last slash should be the filename
  660.         USERID(innoval) if the web site is password-protected
  661.         PASSWORD(secret) if the web site is password-protected
  662.         PORT(81) if your HTTP server's port number is anything other than
  663.            the default of 80; which is rare, so most people do not need
  664.            this argument; but if you have an HTTP server with a non-default
  665.            port, you'll need this argument for every HACKSAW HTTP command
  666.            you use to reach that server; Note:  If you use a proxy server,
  667.            you must use a different method to specify the target server's
  668.            port number, instead of using this PORT argument:  Attach it to
  669.            the server's name in the HOSTFILE argument, as in www.abc.com:81
  670.            or www.abc.com:81/dirname/pagename.htm
  671.         PROXYHOST(internet.innoval.com) if you have HTTP access through a
  672.            firewall which uses the type of classical proxy software which
  673.            wants to receive the target server name as part of the GET
  674.            method, at the beginning of what would ordinarily be the
  675.            directory name; for example GET
  676.            http://www.innoval.com:81/index.htm HTTP/1.0; or if you have a
  677.            proxy server specified in the HACKSAW.INI file and you need for
  678.            HACKSAW to temporarily ignore it, specify "none" or "n" as the
  679.            server name here, or use the HACKSAW DEFINE PROXY subcommand to
  680.            turn off proxy support for a longer period of time, or use
  681.            HACKSAW DEFINE PROXY_IGNORE_FILE to specify certain servers for
  682.            which you always want proxy support to be ignored
  683.         PROXYPORT(81) if that proxy server's HTTP port number is anything
  684.            other than the default of 80
  685.  
  686.      Or you could put the arguments into a control file, and use only this
  687.      argument at the command line:
  688.  
  689.         CONTROLFILE(e:\hacksaw\ctrlfile.002)
  690.  
  691.      Optional arguments are:
  692.  
  693.         LOCALDIRECTORY:  Exactly as used with the FTP command.
  694.  
  695.      Note:  If the HTTP server returns an error code of 400 or above, but
  696.      also an entity body (for example, the 404 error code is always
  697.      accompanied by a small web page entitled Not Found; I'm sure you've
  698.      seen it on more than one occasion), then HACKSAW will store the entity
  699.      body in the LOCALFILE but also display a message on your screen and
  700.      return an errorlevel equal to the server's error code.  The screen
  701.      message tells you that there was an error, and the entity body (as
  702.      well as the errorlevel if you happen to know the meanings of the HTTP
  703.      return codes by heart) will tell you what the server had to say about
  704.      what caused the error.
  705.  
  706.         PROXYIGNOREFILE:  Exactly as used with the FTP command.
  707.  
  708.      1.  The RETRIEVE Subcommand
  709.  
  710.      This subcommand (and its popular synonym, GET) is used to retrieve one
  711.      file from the host server to the local PC.
  712.  
  713.      Example:  HACKSAW HTTP RETRIEVE HOSTFILE(www.innoval.com/filename.htm)
  714.                LOCALFILE(filename.htm)
  715.  
  716.      2.  The RETRIEVEHEADERS Subcommand
  717.  
  718.      This subcommand (and its popular synonym, GETHDR) is used to retrieve
  719.      just the header lines (and one line which HACKSAW will add, called
  720.      URL-Address:, which will contain the value used in your HOSTFILE
  721.      argument) of one file from the host server to the local PC.
  722.  
  723.      Example:  HACKSAW HTTP RETRIEVEHEADERS HOSTFILE(www.innoval.com/)
  724.                LOCALFILE(header1.txt)
  725.  
  726.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  727.                              EMAIL SUBCOMMANDS
  728.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  729.  
  730.      This argument (shown with an example value) is required for all EMAIL
  731.      subcommands:
  732.  
  733.         PORT(26) for SEND subcommands if your SMTP server's port number is
  734.            anything other than the default of 25 or for the other
  735.            subcommands if your POP3 server's port number is anything other
  736.            than the default of 110; which is rare, so most people do not
  737.            need this argument; but if you have a server with a non-default
  738.            port, you'll need this argument for every HACKSAW EMAIL command
  739.            you use to reach that server
  740.  
  741.      Or you could put the arguments into a control file, and use only this
  742.      argument at the command line:
  743.  
  744.         CONTROLFILE(e:\hacksaw\ctrlfile.003)
  745.  
  746.      1.  The SEND Subcommand
  747.  
  748.      This subcommand is used to send an email message via an SMTP server.
  749.      It requires the following arguments (shown with example values):
  750.  
  751.         HOST(mail.providername.com)
  752.         FROM(info@innoval.com)
  753.         TO(elsewhere@wherever.com)
  754.  
  755.            The TO value can be a single internet email address; or it can
  756.            be multiple addresses separated by commas, as long as the value
  757.            is not more than 100 characters long; or it can be a filename.
  758.            If HACKSAW can find the file, it will use the contents of the
  759.            file as addresses, instead of using the filename as an address.
  760.            The file should be a plain ASCII text file full of email
  761.            addresses, one on each line.  Or it can have multiple addresses
  762.            on each line if they're separated by commas and the maximum line
  763.            length is not more than 100 characters.
  764.  
  765.         SUBJECT(This is a test)
  766.         NOTETEXT(This is a very short message!)
  767.  
  768.            Of course, most often you will specify a filename instead of a
  769.            string of text as the NOTETEXT argument.  If HACKSAW can find
  770.            the file you've specified, it will use the contents of the file
  771.            as the message text, instead of using the filename as the message
  772.            text.
  773.  
  774.      Example:  HACKSAW EMAIL SEND HOST(mail.providername.com)
  775.                FROM(info@innoval.com) TO(elsewhere@wherever.com)
  776.                SUBJECT(This is a test) NOTETEXT(e:\dirname\message.txt)
  777.  
  778.      THE POP3 SERVER EMAIL SUBCOMMANDS
  779.  
  780.      These arguments (shown with example values) are required for all POP3
  781.      server EMAIL subcommands:
  782.  
  783.         HOST(pop.providername.com)
  784.         USERID(innoval)
  785.         PASSWORD(secret)
  786.  
  787.      2.  The MAILWAITING Subcommand
  788.  
  789.      This subcommand is used to find out whether there's any mail waiting
  790.      for you in your POP3 account, and if so, how many messages.  It does
  791.      not require any arguments other than the ones which are required for
  792.      all EMAIL POP3 server subcommands.
  793.  
  794.      Note on errorlevels:  When the HACKSAW command is actually EMAIL or
  795.      NOTE (case insensitive) and the subcommand is MAILWAITING or one of
  796.      its recognized synonyms, so that the program actually gets into the
  797.      MAILWAITING operation's routines, all errors will be returned with
  798.      negative errorlevels instead of the normal positive numbers.  This is
  799.      so that the number of messages waiting on the POP3 server (zero or a
  800.      positive number) can be returned as an errorlevel code, so a batch
  801.      file or other program from which you're running HACKSAW will be able
  802.      to determine whether there's mail waiting or not, and act accordingly.
  803.  
  804.      Example:  HACKSAW EMAIL MAILWAITING HOST(pop.providername.com)
  805.                USERID(innoval) PASSWORD(secret)
  806.  
  807.      3.  The RETRIEVE Subcommand
  808.  
  809.      This subcommand is used to retrieve email messages from a POP3
  810.      account.  It requires the following argument (in addition to the ones
  811.      which are required for all EMAIL POP3 server subcommands):
  812.  
  813.         LOCALFILE(e:\dirname\filename.ext) to store the messages in that
  814.            file; or you can specify CON as the "filename", to display the
  815.            messages on your screen (in which case you'll want to pipe the
  816.            output to the MORE command, or keep your finger on your PAUSE
  817.            key)
  818.  
  819.      Optional arguments are:
  820.  
  821.         LOCALDIRECTORY:  Exactly as used with the FTP command.
  822.  
  823.         MESSAGENUMBERS(1,7,9) if you want to retrieve only certain
  824.            messages; you may use spaces instead of commas if you like; the
  825.            value of this argument string cannot be longer than 300
  826.            characters; you may also specify ALL or * as the MESSAGENUMBERS
  827.            value in a control file where your global argument is a specific
  828.            message number but you have an exception line that needs to
  829.            retrieve all the waiting messages
  830.  
  831.         REPLACE(y) if you want HACKSAW to overwrite the LOCALFILE if it
  832.            already exists; normally the new mail is appended to the end of
  833.            such a file; you may also specify "N" as the REPLACE value in a
  834.            control file where your global argument is "Y" but you have an
  835.            exception line whose mail you want to have appended to the
  836.            LOCALFILE
  837.  
  838.         DELETE(y) if you want HACKSAW to delete each message from the POP3
  839.            server after successful retrieval; you may also specify "N" as
  840.            the DELETE value in a control file where your global argument is
  841.            "Y" but you have an exception line whose mail you want to leave
  842.            on the host server
  843.  
  844.         HEADERS(y) if you want HACKSAW to store only certain header lines
  845.            (To:, From:, Date:, Subject:, Reply-to:, Priority:, Message-ID:,
  846.            and Content-Type:) and the size of the message, instead of the
  847.            entire message; you may also specify "N" as the HEADERS value in
  848.            a control file where your global argument is "Y" but you have an
  849.            exception line for which you want to get the entire message
  850.  
  851.         SEPARATOR(unix/hex=##/string) to tell HACKSAW what to use as a
  852.            divider line between each message and the next in the LOCALFILE;
  853.            the value "unix" means HACKSAW will use a "From " line as in
  854.            UNIX mail files; a value of, for example, "hex=12" would make
  855.            HACKSAW use the 12h character (and a carriage return) as the
  856.            divider; any other string (200 characters or fewer in length)
  857.            besides "default" or "def" would be used literally as the
  858.            separator; you may specify "default" or "def" as the SEPARATOR
  859.            value in a control file where your global argument is one of the
  860.            others but you have an exception line for which you want HACKSAW
  861.            to use its default separator, which looks something like this:
  862.  
  863.            -=-=-=-=-=-= 25-Dec-96 17:25:36 Message [1 of 3] =-=-=-=-=-=-
  864.  
  865.      Note on errorlevels:  When the HACKSAW command is actually EMAIL or
  866.      NOTE (case insensitive) and the subcommand is RETRIEVE or one of its
  867.      recognized synonyms, so that the program actually gets into the
  868.      EMAIL RETRIEVE operation's routines, all errors will be returned with
  869.      negative errorlevels instead of the normal positive numbers.  This is
  870.      so that the number of messages retrieved can be returned as an
  871.      errorlevel code, so a batch file or other program from which you're
  872.      running HACKSAW will be able to determine whether any mail just
  873.      arrived or not, and act accordingly.
  874.  
  875.      Example:  HACKSAW EMAIL RETRIEVE HOST(pop.providername.com)
  876.                USERID(innoval) PASSWORD(secret)
  877.                LOCALFILE(e:\dirname\filename.ext)
  878.  
  879.      4.  The DELETE Subcommand
  880.  
  881.      This subcommand is used to delete email messages from a POP3 account.
  882.      It requires the following argument (in addition to the ones which are
  883.      required for all EMAIL POP3 server subcommands):
  884.  
  885.         MESSAGENUMBERS(2,6,7) or you may use spaces instead of commas if
  886.            you like; you may also specify ALL or * to delete them all; this
  887.            argument string cannot be longer than 300 characters
  888.  
  889.      Example:  HACKSAW EMAIL DELETE HOST(pop.providername.com)
  890.                USERID(innoval) PASSWORD(secret) MESSAGENUMBERS(3)
  891.  
  892.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  893.                              DEFINE SUBCOMMANDS
  894.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  895.  
  896.      The DEFINE command is used to add entries to your HACKSAW.INI file
  897.      (which is written to and read from in the directory in which your
  898.      HACKSAW.EXE file resides).  This command does not use the same syntax
  899.      as the others; arguments do not involve parentheses, and cannot be
  900.      obtained from control files or via prompting.  They can only be
  901.      specified via the command line.
  902.  
  903.      To remove an entry from your HACKSAW.INI file, just specify "" (that
  904.      is, nothing, between quotation marks) as the value to be added to the
  905.      file.  Instead of changing the entry's value to "nothing", it will
  906.      delete the whole entry.  For example, to remove your default FTP
  907.      server setting, use this command:
  908.  
  909.         HACKSAW DEFINE FTP_SERVER ""
  910.  
  911.      Or if you prefer, you can use any ASCII text editor to modify the file
  912.      manually.
  913.  
  914.      The OS/2 version of HACKSAW does not use the normal OS/2 method of
  915.      writing *.INI files.  Instead, it uses a routine which works the same
  916.      way as Windows's normal *.INI-file-writing routine.  This way, if you
  917.      use both operating systems, your OS/2 HACKSAW.INI file is
  918.      interchangeable with your Windows HACKSAW.INI file.  This also means
  919.      that the HACKSAW.INI file is plain ASCII text.  So you can modify it
  920.      as you like, which is quite difficult with the normal OS/2 style of
  921.      *.INI file.
  922.  
  923.      1.  The DEFAULT_USERID Subcommand
  924.  
  925.      Example:  HACKSAW DEFINE DEFAULT_USERID INNOVAL
  926.  
  927.      This sample command would add this entry to your HACKSAW.INI file so
  928.      that from then on, whenever you told HACKSAW FTP to do something
  929.      without telling it a userid argument to use, it would automatically
  930.      use INNOVAL as the userid without prompting you for a userid.
  931.  
  932.      2.  The PASSWORD Subcommand
  933.  
  934.      Example:  HACKSAW DEFINE PASSWORD INNOVAL SECRET
  935.  
  936.      This sample command would add this entry to your HACKSAW.INI file so
  937.      that from then on, whenever you told HACKSAW FTP, HTTP, or a POP3
  938.      server EMAIL subcommand to use INNOVAL as your userid without also
  939.      telling it the password to use, it would automatically use SECRET as
  940.      INNOVAL's password without prompting you for it.  Of course, the
  941.      password value is encrypted before it's stored in the HACKSAW.INI
  942.      file.  There is no limit to the number of userid/password pairs you
  943.      can store using this subcommand.
  944.  
  945.      3.  The DEFAULT_MAILUSER Subcommand
  946.  
  947.      Example:  HACKSAW DEFINE DEFAULT_MAILUSER innoval secret
  948.  
  949.      This sample command would add this entry to your HACKSAW.INI file so
  950.      that from then on, whenever you told HACKSAW EMAIL to do something
  951.      with a POP3 server without telling it a userid argument to use, it
  952.      would automatically use INNOVAL as the userid and SECRET as the
  953.      password without prompting you for those values.  Of course, the
  954.      password value is encrypted before it's stored in the HACKSAW.INI
  955.      file.
  956.  
  957.      4.  The DEFAULT_MAILFROM Subcommand
  958.  
  959.      Example:  HACKSAW DEFINE DEFAULT_MAILFROM info@innoval.com
  960.  
  961.      This sample command would add this entry to your HACKSAW.INI file so
  962.      that from then on, whenever you told HACKSAW to send an email message
  963.      without giving it a FROM argument, it would automatically use
  964.      info@innoval.com without prompting you for a FROM address.
  965.  
  966.      5.  The SMTP_SERVER Subcommand
  967.  
  968.      Example:  HACKSAW DEFINE SMTP_SERVER mail.providername.com
  969.  
  970.      This sample command would add this entry to your HACKSAW.INI file so
  971.      that from then on, whenever you told HACKSAW to send an email without
  972.      giving it a HOST argument, it would automatically use
  973.      mail.providername.com without prompting you for a server address.
  974.  
  975.      6.  The POP3_SERVER Subcommand
  976.  
  977.      Example:  HACKSAW DEFINE POP3_SERVER pop.providername.com
  978.  
  979.      This sample command would add this entry to your HACKSAW.INI file so
  980.      that from then on, whenever you told HACKSAW to interact with a POP3
  981.      server without giving it a HOST argument, it would automatically use
  982.      pop.providername.com without prompting you for a server address.
  983.  
  984.      7.  The FTP_SERVER Subcommand
  985.  
  986.      Example:  HACKSAW DEFINE FTP_SERVER ftp.innoval.com
  987.  
  988.      This sample command would add this entry to your HACKSAW.INI file so
  989.      that from then on, whenever you told HACKSAW FTP to do something
  990.      without giving it a HOST argument, it would automatically use
  991.      ftp.innoval.com without prompting you for a server address.
  992.  
  993.      8.  The FTPPROXY_SERVER Subcommand
  994.  
  995.      Example:  HACKSAW DEFINE FTPPROXY_SERVER internet.innoval.com
  996.  
  997.      This sample command would add this entry to your HACKSAW.INI file so
  998.      that from then on, whenever you told HACKSAW FTP to do something
  999.      without giving it a PROXYHOST argument, it would automatically use
  1000.      internet.innoval.com as the proxy server unless you had used the PROXY
  1001.      subcommand to turn off the proxy support or unless the target server
  1002.      were specified via a PROXYIGNOREFILE argument or via a DEFINE
  1003.      PROXY_IGNORE_FILE subcommand.
  1004.  
  1005.      9.  The HTTPPROXY_SERVER Subcommand
  1006.  
  1007.      Example:  HACKSAW DEFINE HTTPPROXY_SERVER internet.innoval.com
  1008.  
  1009.      This sample command would add this entry to your HACKSAW.INI file so
  1010.      that from then on, whenever you told HACKSAW HTTP to do something
  1011.      without giving it a PROXYHOST argument, it would automatically use
  1012.      internet.innoval.com as the proxy server unless you had used the PROXY
  1013.      subcommand to turn off the proxy support or unless the target server
  1014.      were specified via a PROXYIGNOREFILE argument or via a DEFINE
  1015.      PROXY_IGNORE_FILE subcommand.
  1016.  
  1017.      10.  The FTPPROXY_PORT Subcommand
  1018.  
  1019.      Example:  HACKSAW DEFINE FTPPROXY_PORT 22
  1020.  
  1021.      This sample command would add this entry to your HACKSAW.INI file so
  1022.      that from then on, whenever you told HACKSAW FTP to use a proxy server
  1023.      without giving it a PROXYPORT argument, it would automatically use 22
  1024.      as the proxy server's port number.
  1025.  
  1026.      11.  The HTTPPROXY_PORT Subcommand
  1027.  
  1028.      Example:  HACKSAW DEFINE HTTPPROXY_PORT 81
  1029.  
  1030.      This sample command would add this entry to your HACKSAW.INI file so
  1031.      that from then on, whenever you told HACKSAW HTTP to use a proxy
  1032.      server without giving it a PROXYPORT argument, it would automatically
  1033.      use 81 as the proxy server's port number.
  1034.  
  1035.      12.  The PROXY Subcommand
  1036.  
  1037.      Example:  HACKSAW DEFINE PROXY OFF
  1038.  
  1039.      This sample command would add this entry to your HACKSAW.INI file so
  1040.      that from then on (until you execute HACKSAW DEFINE PROXY ON), whenever
  1041.      you execute an HTTP or FTP command without specifying a PROXYHOST
  1042.      argument, the program will act as if you did not have a proxy server
  1043.      defined even if you do; in other words, it will interact directly with
  1044.      the target server instead of trying to go through the proxy server.  So
  1045.      this is what you want to do if you take your laptop outside the
  1046.      firewall, or if you're going to work only with servers that are inside
  1047.      the firewall for a while and you haven't specified their names in a
  1048.      PROXY_IGNORE_FILE file.
  1049.  
  1050.      13.  The PROXY_IGNORE_FILE Subcommand
  1051.  
  1052.      Example:  HACKSAW DEFINE PROXY_IGNORE_FILE C:\HACKSAW\SERVERS.IGN
  1053.  
  1054.      This sample command would add this entry to your HACKSAW.INI file so
  1055.      that from then on, whenever you execute an HTTP or FTP command which
  1056.      would otherwise use proxy support, the proxy support will be bypassed
  1057.      if the specified file contains the name of the target server.  So the
  1058.      specified file is where you want to list the names of the servers
  1059.      inside your firewall, and servers you never try to reach except when
  1060.      you've taken your laptop outside the firewall.  The file must be plain
  1061.      ASCII text, one server name per line; blank lines and lines which begin
  1062.      with * will be ignored.
  1063.  
  1064.      14.  The VARIABLE Subcommand
  1065.  
  1066.      Example:  HACKSAW DEFINE VARIABLE MyGifDir /company/thisdir/graphics
  1067.  
  1068.      This sample command would add this entry to your HACKSAW.INI file so
  1069.      that from then on, whenever you want to say
  1070.      "/company/thisdir/graphics" in response to a HACKSAW prompt or as an
  1071.      argument at the command line or in a control file, you could just type
  1072.      $MyGifDir or &MyGifDir instead of typing out that whole long string.
  1073.      When HACKSAW sees an argument that starts with the $ or & symbol, it
  1074.      uses the rest of the string (after that symbol) as a variable name and
  1075.      tries to find that variable in the HACKSAW.INI file.  If it finds one,
  1076.      it uses that variable's value instead of using the string that started
  1077.      with the $ or & symbol.
  1078.  
  1079.      The reason HACKSAW can use either & or $ for this purpose is that, for
  1080.      example, OS/2's command interpreter uses & for its own purpose, to
  1081.      allow more than one command to be typed on one command line.  Other
  1082.      third-party command interpreters can be used which allow the user to
  1083.      specify certain symbols to be used for certain other purposes.  So
  1084.      HACKSAW allows you two choices, so that if your command interpreter
  1085.      uses one of them for another purpose, you still have another choice
  1086.      you can use for this HACKSAW function.  If your command interpreter
  1087.      uses both $ and & for something else, then try enclosing your
  1088.      &VARIABLE or $VARIABLE in quotation marks inside the parentheses;
  1089.      perhaps then your command interpreter will ignore the symbol, and let
  1090.      HACKSAW see it normally.
  1091.  
  1092.      The name HF is reserved for use with the FTP SITECOMMAND subcommand
  1093.      and argument, so don't use it as a variable name.
  1094.  
  1095.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  1096.                          ARGUMENTS FOR ALL COMMANDS
  1097.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  1098.  
  1099.         MESSAGEFILE(e:\dirname\msgsout.txt)
  1100.  
  1101.            Normally, HACKSAW sends messages to the screen to tell you about
  1102.            the progress or results of an action.  You can send those screen
  1103.            messages to a file for later review, instead of to the screen,
  1104.            by using this argument.  You can prevent the messages from going
  1105.            anywhere by using NONE or QUIET as the "filename".  You can
  1106.            specify the "filename" CON, CONS, CONSOLE, or SCREEN to have the
  1107.            output sent to the screen instead of to a file.  But since
  1108.            that's what HACKSAW normally does when you don't specify a
  1109.            MESSAGEFILE argument, the only time you'd need to do that is in
  1110.            a control file where you're using the MESSAGEFILE argument to
  1111.            send most of the output to an output file but want just one
  1112.            file's (or one TO: line's) output to go to the screen instead,
  1113.            for some reason.
  1114.  
  1115.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  1116.                                CONTROL FILES
  1117.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  1118.  
  1119.      1.  How to Use
  1120.  
  1121.      There are two ways to use control files.  You can specify just the
  1122.      control file's name as the only HACKSAW command line argument if the
  1123.      very first line of the control file contains a COMMAND argument and a
  1124.      SUBCOMMAND argument.  For example, if the first line of the
  1125.      CTRLFILE.004 file in the current directory included:
  1126.  
  1127.         COMMAND(FTP) SUBCOMMAND(SEND)
  1128.  
  1129.      then you would just type
  1130.  
  1131.         HACKSAW CTRLFILE.004
  1132.  
  1133.      at the command line instead of having to start HACKSAW with this
  1134.      command:
  1135.  
  1136.         HACKSAW FTP SEND
  1137.  
  1138.      When you start HACKSAW in this manner, with just a control file's name
  1139.      as the first command line argument, any other arguments on the command
  1140.      line will be ignored.  So they must all be inside the control file
  1141.      instead.
  1142.  
  1143.      "CMD" is a valid abbreviation for COMMAND, and "SCMD" and "SUB" are
  1144.      valid SUBCOMMAND abbreviations.
  1145.  
  1146.      The other way to use a control file is to specify the command and the
  1147.      subcommand on HACKSAW's command line, along with a
  1148.      CONTROLFILE(e:\dirname\ctrlfile.005) argument to tell HACKSAW to find
  1149.      some or all of its arguments in that file instead of on the command
  1150.      line.  For example:
  1151.  
  1152.         HACKSAW FTP SEND CONTROLFILE(e:\dirname\ctrlfile.005)
  1153.  
  1154.      In this case, the CTRLFILE.005 file should not contain COMMAND and
  1155.      SUBCOMMAND arguments; and any additional valid arguments you use on
  1156.      that command line will be recognized.
  1157.  
  1158.      2.  How to Build
  1159.  
  1160.      Regardless of which way you use it, a control file must be plain ASCII
  1161.      text, and can contain three types of lines.  The first type, argument
  1162.      lines, is optional.  Any line which starts with anything other than /*,
  1163.      TO:, or FILE: will be treated as an argument line.  You specify the
  1164.      arguments here in the exact same way you specify them at the command
  1165.      line:  An argument name, followed (without a space) by an argument
  1166.      value in parentheses.  But you cannot leave off the closing parenthesis
  1167.      the way you can at the command line.  You can put a separate argument
  1168.      on each line, or put all your arguments on one very long line, or put
  1169.      several arguments on each line but use several lines to hold them all.
  1170.      These argument lines can appear at the beginning of the file, the end,
  1171.      the middle, or mixed througout, with no effect whatsoever on the
  1172.      results.  (Except that COMMAND and SUBCOMMAND arguments will not work
  1173.      unless they're on the first line of the file.)
  1174.  
  1175.      Any argument that HACKSAW doesn't recognize as a valid argument for
  1176.      the subcommand being processed, will be entirely ignored, just as at
  1177.      the command line.
  1178.  
  1179.      The second type of line in a control file is the comment line.  A
  1180.      comment line starts with the string /*.  For example:
  1181.  
  1182.         /* This is a comment.
  1183.  
  1184.      Comment lines are also optional.  You only need to use them if you want
  1185.      to remind yourself of something, or put some information into the file
  1186.      that you want HACKSAW to ignore when it reads the file.  The most
  1187.      common use of comment lines is when you have a control file, to which
  1188.      you want to make a temporary change, which will be easy to put back
  1189.      later:  Just insert /* at the beginning of a line to make the program
  1190.      ignore that line, and then remove the /* from it when it's time to put
  1191.      the file back to its original state.
  1192.  
  1193.      The third type of control file line is the only one that's mandatory.
  1194.      It's the FILE: line where you specify the files you want to act upon
  1195.      or, in the case of the EMAIL SEND subcommand, the TO: line where you
  1196.      specify the addresses to which you want to send the message.  The
  1197.      easiest example is the latter, so let's start with that.
  1198.  
  1199.      3.  TO: Lines for EMAIL SEND Control Files
  1200.  
  1201.      With a control file for an EMAIL SEND subcommand, the TO argument is
  1202.      not used on argument lines or at the command line.  Instead, any number
  1203.      of TO: lines is used:
  1204.  
  1205.         TO: elsewhere@wherever.com
  1206.         TO: nobody@fakedomain.org
  1207.         TO: whosit@thisplace.com
  1208.  
  1209.      You can also specify other arguments on the TO: lines.  For example,
  1210.      if you wanted to use the same subject line for all the messages except
  1211.      for the one that's sent to nobody@fakedomain.org, you could specify
  1212.      that subject line in the SUBJECT argument in one of the argument lines
  1213.      of the control file, or at the command line from which the control
  1214.      file was invoked; and then use this TO: line for
  1215.      nobody@fakedomain.org:
  1216.  
  1217.         TO: nobody@fakedomain.org<TAB>SUBJECT(Other Subject Line)
  1218.  
  1219.      In control files for the EMAIL SEND subcommand, on the TO: lines, the
  1220.      addresses cannot contain any <TAB> characters, and any arguments must
  1221.      be separated from the addresses by a <TAB> character.  So to create
  1222.      such a file, you must use an editor which can put <TAB> characters
  1223.      into a file instead of converting them to spaces the way so many
  1224.      editors do.  Under Windows, three editors which work for this purpose
  1225.      are WordPad, Notepad, and EDLIN.EXE.  Under OS/2, E.EXE does; EPM does
  1226.      as well, but only if you make the <TAB> characters using the Alt-009
  1227.      method rather than with the <TAB> key.
  1228.  
  1229.      Whatever arguments are used on a TO: line will override any same-named
  1230.      arguments specified on the argument lines of the control file or at
  1231.      the command line, for that one TO: address only.  The control file's
  1232.      "global" arguments will still be used for all other TO: lines, before
  1233.      and after that one.
  1234.  
  1235.      The TO: line can contain a filename instead of an email address.  That
  1236.      file should be a plain ASCII text file full of email addresses, one on
  1237.      each line.  There can be more than one address on a line if each is
  1238.      separated from the others by a comma, as long as the entire line is
  1239.      100 characters or fewer in length.  If HACKSAW can find the specified
  1240.      file, it will send the message to all the addresses in it, instead of
  1241.      trying to use the filename itself as an email address.
  1242.  
  1243.      In order to have a way around the problem that can occur when you send
  1244.      too much data at once to some SMTP servers, HACKSAW logs off the
  1245.      server and logs back on between each TO: line and the next.  So you
  1246.      can use one control file to send a very large number of messages at
  1247.      once, without choking your server, as long as each TO: line's message
  1248.      is small enough for the server to handle.  But if you have one message
  1249.      you need to send to a lot of people, and you want it done without
  1250.      HACKSAW disconnecting and reconnecting and you're sure your SMTP server
  1251.      can handle it, then you want to put all the addresses on one TO: line.
  1252.      You can do that by having all the addresses in an ASCII text file and
  1253.      specifying that file's name as your TO: address; or by putting all the
  1254.      addresses on the TO: line, separated by commas, as long as they fit
  1255.      within 100 characters.
  1256.  
  1257.      4.  FILE: Lines for All Other Control Files
  1258.  
  1259.      For subcommands other than EMAIL SEND, a control file needs FILE: lines
  1260.      instead of TO: lines.  These are used instead of any HOSTFILE and
  1261.      LOCALFILE arguments in the argument lines or at the command line.
  1262.      (That is, HOSTFILE and LOCALFILE arguments are not used in control
  1263.      files; the information that would go there goes on the FILE: lines
  1264.      instead.)  Don't ever think of these lines as being like the command
  1265.      line, where in most operating system commands you type the source
  1266.      filename first and then the target filename.  These FILE: lines do not
  1267.      work that way.  In every case in which you need to specify a host
  1268.      filename and a local PC filename in these FILE: lines, you must specify
  1269.      the local PC filename first, then a space, then the host filename.
  1270.      This means if you want to retrieve several files from the host to edit
  1271.      them and then send them back to the host, you can use the same control
  1272.      file, without modification, for your HACKSAW FTP RETRIEVE and SEND
  1273.      subcommands.
  1274.  
  1275.      If you have a filename with a space in it, you must surround it with
  1276.      quotation marks.  For example, to retrieve /innoval/filename.ext from
  1277.      the host, and store it with the same filename on the local PC in this
  1278.      three-word directory, use this FILE: line:
  1279.  
  1280.        FILE: "e:\long named dir\filename.ext" /innoval/filename.ext
  1281.  
  1282.      Just as with the TO: lines in EMAIL SEND control files, the FILE:
  1283.      lines can contain other arguments which act as exceptions to the
  1284.      "global" arguments.  For example, if all of the files you're sending
  1285.      are in the e:\senddir directory except one, you could use
  1286.      LOCALDIRECTORY(e:\senddir) on an argument line or at the command line,
  1287.      to act as a global argument for all the FILE: lines, but then use:
  1288.  
  1289.         FILE: except.txt /innoval/except.txt LOCALDIRECTORY(e:\otherdir)
  1290.  
  1291.      for that one file's FILE: line.  Whatever arguments are used on a FILE:
  1292.      line will override any same-named arguments specified on the argument
  1293.      lines of the control file or at the command line, for that one FILE:
  1294.      entry only.  The control file's "global" arguments will still be used
  1295.      for all other FILE: lines, before and after that one.
  1296.  
  1297.      Exception:  Once the CHANGEDIRECTORY argument has been used to issue a
  1298.      CWD command to an FTP server, that's the server's current directory for
  1299.      the duration of that session, unless another CWD command is issued
  1300.      later.  So in effect, a CHANGEDIRECTORY argument on a FILE: line of a
  1301.      control file will apply to that line and all subsequent lines until
  1302.      another CHANGEDIRECTORY argument is used.
  1303.  
  1304.      Note that on FILE: lines (as opposed to the TO: lines used with EMAIL
  1305.      SEND subcommands), the filenames are separated from any optional
  1306.      arguments by a space character, not by a <TAB> character.
  1307.  
  1308.      Different subcommands require different information on the FILE: lines
  1309.      of their control files.  Here are all of the subcommands followed by
  1310.      the arguments they need on their FILE: lines.
  1311.  
  1312.      FTP SEND
  1313.      FTP RETRIEVE
  1314.      FTP LIST
  1315.      HTTP RETRIEVE
  1316.      HTTP RETRIEVEHEADERS
  1317.  
  1318.         FILE: LOCALFILE HOSTFILE
  1319.  
  1320.      FTP RENAME
  1321.  
  1322.         FILE: SOURCEFILE TARGETFILE
  1323.  
  1324.      FTP DELETE
  1325.      FTP SITECOMMAND
  1326.  
  1327.         FILE: HOSTFILE
  1328.  
  1329.      FTP SENDALL
  1330.      FTP SYNCHRONIZEHOST
  1331.  
  1332.         FILE: LOCALFILE HOSTDIRECTORY
  1333.  
  1334.      FTP RETRIEVEALL
  1335.      FTP SYNCHRONIZELOCAL
  1336.  
  1337.         FILE: LOCALDIRECTORY HOSTFILE
  1338.  
  1339.      EMAIL RETRIEVE
  1340.  
  1341.         FILE: LOCALFILE
  1342.  
  1343.      EMAIL MAILWAITING
  1344.      EMAIL DELETE
  1345.  
  1346.         These subcommands do not take filename arguments, so they have no
  1347.         FILE: lines in control files, so there is very little reason to ever
  1348.         use them with control files; unless you just happen to prefer using
  1349.         a control file to using a command line via a batch file, for some
  1350.         reason.  In which case, it is the argument lines which are mandatory
  1351.         in such control files; rather than the FILE: lines which are the
  1352.         only mandatory lines in any other control files.
  1353.  
  1354.      DEFINE (all)
  1355.  
  1356.         This command cannot be used with control files.
  1357.  
  1358.      At the command line, you can omit the target file specification when
  1359.      you want the target file's name to be the same as that of the source
  1360.      file.  But in control files, you can't do that.  The arguments
  1361.      specified above are absolutely required on every FILE: line in a
  1362.      control file.  But what you can do when you want the target filename
  1363.      to be the same as the source filename, other than typing it in both
  1364.      places, is use an * symbol as the target filename.  However, if you do
  1365.      that in a control file that's to be used for an FTP SEND subcommand,
  1366.      for example, then you can't use the same control file for an FTP
  1367.      RETRIEVE subcommand the way you could if you specified the target
  1368.      filename.  Because when you use the same control file for the opposite
  1369.      operation, what was the target filename specification becomes the
  1370.      source specification; the former can be *, but the latter can not.
  1371.  
  1372.      An EMAIL RETRIEVE control file can let you put each message into a
  1373.      separate LOCALFILE, if you use a MESSAGENUMBERS(1) argument on one
  1374.      line, a MESSAGENUMBERS(2) argument on the next, etc., and different
  1375.      LOCALFILE names on each line.  But if you do this for some reason, you
  1376.      may notice that HACKSAW will log off the POP3 server and log back on,
  1377.      between each FILE: line and the next.
  1378.  
  1379.      The reason it does that, is so that it is possible to retrieve mail
  1380.      from multiple POP3 accounts at once!  You just specify different HOST,
  1381.      USERID, and PASSWORD arguments on each FILE: line.
  1382.  
  1383.      Remember, just like at the command line, any time you have a filename
  1384.      which contains pathname information, you can specify it as part of the
  1385.      filename specification, or you can use the HOSTDIRECTORY or
  1386.      LOCALDIRECTORY argument.  This is particularly useful for control
  1387.      files.  For example, you can have FILE: lines which say:
  1388.  
  1389.         FILE: e:\dirname\file001.gif /innoval/subdir/graphics/file001.gif
  1390.         FILE: e:\dirname\file002.gif /innoval/subdir/graphics/file002.gif
  1391.         FILE: e:\dirname\file003.gif /innoval/subdir/graphics/file003.gif
  1392.  
  1393.      Or you can use LOCALDIRECTORY(e:\dirname) and
  1394.      HOSTDIRECTORY(/innoval/subdir/graphics) arguments and simpler FILE:
  1395.      lines:
  1396.  
  1397.         FILE: file001.gif file001.gif
  1398.         FILE: file002.gif file002.gif
  1399.         FILE: file003.gif file003.gif
  1400.  
  1401.      Another useful example would be to synchronize the following pairs of
  1402.      directories:
  1403.  
  1404.         FILE: e:\directory\subdir1 /innoval/subdir/graphics
  1405.         FILE: e:\directory\subdir2 /innoval/subdir/htmfiles
  1406.         FILE: e:\directory\subdir3 /innoval/subdir/cgifiles
  1407.  
  1408.      An FTP SYNCHRONIZEHOST control file could contain those lines, or it
  1409.      could contain LOCALDIRECTORY(e:\directory) and
  1410.      HOSTDIRECTORY(/innoval/subdir) arguments and these FILE: lines instead:
  1411.  
  1412.         FILE: subdir1 graphics
  1413.         FILE: subdir2 htmfiles
  1414.         FILE: subdir3 cgifiles
  1415.  
  1416.      Even though they're really directory names instead of files, all
  1417.      HACKSAW is going to do is prepend the DIRECTORY arguments to them
  1418.      (with a slash or backslash, as appropriate) before using them, so this
  1419.      will work as desired.
  1420.  
  1421.      5.  Example Control Files
  1422.  
  1423.         COMMAND(FTP) SUBCOMMAND(SEND) HOST(ftp.innoval.com)
  1424.         USERID(innoval) PASSWORD(secret)
  1425.         FILE: e:\dirname\filename.ext /innoval/filename.ext
  1426.         FILE: e:\otherdir\other.fil /innoval/filename.002
  1427.  
  1428.      This control file will execute an FTP SEND subcommand to send two
  1429.      files.  Since it has COMMAND and SUBCOMMAND arguments in it, it needs
  1430.      to be used via a HACKSAW command line with just the control file's name
  1431.      (not even the CONTROLFILE label with it) as the only command line
  1432.      argument.
  1433.  
  1434.         HOST(ftp.innoval.com) USERID(innoval) PASSWORD(secret)
  1435.         FILE: e:\dirname\filename.ext /innoval/filename.ext TYPE(b)
  1436.         FILE: e:\otherdir\other.fil /innoval/filename.002
  1437.  
  1438.      Since this control file does not have COMMAND and SUBCOMMAND arguments
  1439.      on its first line, it needs to be executed via a command line such as:
  1440.  
  1441.         HACKSAW FTP SEND CONTROLFILE(e:\hacksaw\ctrlfile.006) TYPE(a)
  1442.  
  1443.      This control file could be used for both FTP SEND and FTP RETRIEVE.
  1444.      The first file will be transferred in the binary mode, regardless of
  1445.      the global TYPE argument used, if any.  Because its FILE: line has its
  1446.      own TYPE(b) argument.  But the second FILE: line has no TYPE argument,
  1447.      so it will be transferred in whatever mode is in effect globally in the
  1448.      control file.  By default, that would be binary.  But with the example
  1449.      command line shown here, it would be ascii.  Or if there were a
  1450.      TYPE(ascii) argument inside the control file on an argument line or on
  1451.      the second FILE: line, the second file would go in ascii mode then, as
  1452.      well, even if TYPE(a) were not specified on the command line.
  1453.  
  1454.         HOST(mail.providername.com) FROM(info@innoval.com)
  1455.         TO: innoval@ibm.net<TAB>NOTETEXT(Please give me a call asap.)
  1456.         SUBJECT(This is a test) NOTETEXT(e:\dirname\message.txt)
  1457.         TO: prmbeta@ibm.net
  1458.         TO: postsvc@ibm.net<TAB>SUBJECT(Second test)
  1459.  
  1460.      This control file would be used with a HACKSAW EMAIL SEND subcommand.
  1461.      The prmbeta address will receieve the MESSAGE.TXT message with a
  1462.      subject line of "This is a test".  The postsvc address will receive the
  1463.      same message but with its own subject line.  And the innoval address's
  1464.      message will have the global subject line, "This is a test", but its
  1465.      message text will be just that short sentence, "Please give me a call
  1466.      asap."  Note that the fact that the second argument line is between one
  1467.      TO: line and the next instead of being before the first one has no
  1468.      meaning at all.  The program reads all the argument lines at the same
  1469.      time, before it starts working on any of the TO: lines.  The same is
  1470.      true of the FILE: lines in other subcommands' control files, as well.
  1471.  
  1472.         HOST(pop.providername.com) HEADERS(y)
  1473.         FILE: e:\dirname\mailfile.in USERID(innoval) REPLACE(y)
  1474.         FILE: e:\dirname\mailfile.in USERID(postsvc) HEADERS(n)
  1475.         FILE: e:\dirname\mailfile.in USERID(prmbeta) SEPARATOR(PRMBeta Msg)
  1476.  
  1477.      This control file would be used with a HACKSAW EMAIL RETRIEVE
  1478.      subcommand.  It would log onto the POP3 server as the innoval account
  1479.      and retrieve certain header lines of all the messages there, and store
  1480.      them in the MAILFILE.IN file, overwriting that file if it already
  1481.      existed.  Then it would log onto the server as postsvc, and retrieve
  1482.      all those messages.  Since there's no REPLACE(y) argument on that line
  1483.      and the default behavior of the EMAIL RETRIEVE subcommand is to append
  1484.      to the LOCALFILE file when it already exists, the messages will be
  1485.      added to the end of the same file that was used for the innoval
  1486.      messages.  Furthermore, since that line has a HEADERS(n) argument, the
  1487.      entire message will be stored instead of only the headers, even though
  1488.      there's a HEADERS(y) argument in effect globally.  Next, HACKSAW will
  1489.      log onto the server as prmbeta, retrieve the headers, and append them
  1490.      to the end of the same file, this time using "PRMBeta Msg" as the
  1491.      separator line instead of the default separator, before each of the
  1492.      messages it places into the file.
  1493.  
  1494.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  1495.                                 ERRORLEVELS
  1496.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  1497.  
  1498.      For each type of error that HACKSAW can encounter, it returns a
  1499.      different errorlevel code that can be read by a batch file, REXX
  1500.      program, or other type of program from which you might run HACKSAW.
  1501.      Following is the list of errorlevels and their meanings.  Remember, the
  1502.      EMAIL RETRIEVE and MAILWAITING subcommands return these codes as
  1503.      negative errorlevels rather than positive ones.
  1504.  
  1505.        0  No errors found
  1506.        2  User pressed ESC key while HACKSAW was prompting for required
  1507.           arguments
  1508.        5  Required arguments were not supplied
  1509.       10  The first command line argument was not a control file, nor FTP,
  1510.           HTTP, EMAIL, or DEFINE; or the second command line argument was
  1511.           not a valid subcommand for the specified command
  1512.       15  Invalid time stamp found during FTP SENDALL or FTP GETALL
  1513.       20  Could not read control file
  1514.       21  Error allocating memory for a thread
  1515.       30  Error trying to write a DEFINE entry to the HACKSAW.INI file
  1516.       50  Could not connect to host server
  1517.       70  Error issuing USER command to FTP server
  1518.       71  Error issuing PASS command to FTP server
  1519.       72  Timeout during FTP operation
  1520.       73  Error issuing TYPE command to FTP server
  1521.       74  Error issuing PORT command to FTP server
  1522.       75  Error issuing STOR command to FTP server
  1523.       76  Error creating data socket for FTP SEND or RETRIEVE command
  1524.       77  Error opening LOCALFILE during FTP SEND or FTP/EMAIL RETR command
  1525.       78  Could not find LOCALFILE during FTP SEND command
  1526.       79  Error creating listen socket for FTP SEND or RETRIEVE command
  1527.       80  Error issuing RETR command to FTP server
  1528.       81  Error issuing SITE command to FTP server
  1529.       82  Error issuing DELE command to FTP server
  1530.       83  Error issuing RNFR command to FTP server
  1531.       84  Error issuing RNTO command to FTP server
  1532.       85  Error issuing CWD command to FTP server
  1533.       90  No matching files were found during FTP SENDALL
  1534.       91  No matching files were found during FTP GETALL
  1535.       94  No matching files were found during FTP SYNCHRONIZEHOST
  1536.       95  No matching files were found during FTP SYNCHRONIZELOCAL
  1537.      110  Timeout during HTTP operation
  1538.      111  Error opening LOCALFILE during HTTP operation
  1539.      150  Error issuing MAIL FROM command to SMTP server
  1540.      151  Error issuing RCPT TO command to SMTP server
  1541.      152  Error issuing DATA command to SMTP server
  1542.      153  Error sending final (.) line to SMTP server
  1543.      180  Error issuing USER command to POP3 server
  1544.      181  Error issuing PASS command to POP3 server
  1545.      182  Timeout during POP3 operation
  1546.      190  Error issuing STAT command to POP3 server
  1547.      191  Error issuing TOP command to POP3 server
  1548.      192  Error issuing RETR command to POP3 server
  1549.      193  Error issuing DELE command to POP3 server
  1550.      200  Attempt to EMAIL RETRIEVE or EMAIL DELETE while no messages exist
  1551.      201  Error writing LOCALFILE during EMAIL RETRIEVE
  1552.  
  1553.      Any higher errorlevel number is what comes from the HTTP server if
  1554.      there's an error during an HTTP command.
  1555.  
  1556.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  1557.                              Technical Support
  1558.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  1559.  
  1560.      If you need help with this product or have suggestions, please email us
  1561.      at hacksaw@innoval.com, fax us at 914.835.3857, or visit our web page
  1562.      at http://www.innoval.com.
  1563.  
  1564.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  1565.                               Acknowledgments
  1566.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  1567.  
  1568.      Hacksaw is packaged using INFO-ZIP's compression utility.  INFO-ZIP's
  1569.      software (ZIP, UNZIP, and related utilities) is free and can be
  1570.      obtained as source code or executables from various bulletin board
  1571.      services and anonymous FTP sites, including CompuServe's IBMPRO forum
  1572.      and ftp.uu.net/pub/archiving/zip/*.
  1573.  
  1574.      IBM and OS/2 are registered trademarks of the IBM Corporation.
  1575.      Microsoft and Windows are registered trademarks of the Microsoft
  1576.      Corporation.  All other brands, both cited and not cited, are
  1577.      trademarks, registered trademarks, or service marks of their respective
  1578.      companies.
  1579.  
  1580.              =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  1581.                                SYNTAX SCREEN
  1582.         -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  1583.  
  1584.      Here is the syntax screen which HACKSAW displays if you execute it
  1585.      with no command line arguments or with ? as its argument.  Please note
  1586.      the abbreviations (synonyms) listed to the right of each
  1587.      command/subcommand/argument that has them.  You may use any
  1588.      command/subcommand/argument interchangeably with any of its synonyms
  1589.      at any time.  Most of the arguments can be used with all of the
  1590.      subcommands in the group under which they appear.  A few arguments,
  1591.      though, apply only to one or two subcommands.  These arguments have
  1592.      those specific subcommands displayed to their left in lowercase
  1593.      letters.
  1594.  
  1595. Syntax: HACKSAW <command> <subcommand> <arg1>...<argN>   Synonyms:
  1596.  
  1597. Arguments for all commands: MESSAGEFILE(filename)        MESSAGES MSGS MF
  1598.  
  1599. Commands: FTP <ftp subcommand> <arg1>...<argN>
  1600.    FTP subcommands: SEND                                 PUT
  1601.                     SENDALL                              PUTALL
  1602.                     SYNCHRONIZEHOST                      SYNCHOST SYNCH
  1603.                     RETRIEVE                             RETR GET
  1604.                     RETRIEVEALL                          RETRALL GETALL
  1605.                     SYNCHRONIZELOCAL                     SYNCLOCAL SYNCL
  1606.                     LIST                                 DIR
  1607.                     DELETE                               ERASE DELE DEL
  1608.                     RENAME                               REN RE
  1609.                     SITECOMMAND                          SITECMD SITE SC
  1610.      FTP arguments: USERID(userid)                       USER U
  1611.                     PASSWORD(password)                   PASS PW
  1612.                     HOST(host)
  1613.                     PORT(number) [Default: 21]
  1614.                     TYPE(BINARY/ascii)                   MODE
  1615.                     HOSTFILE(host filename)              HFILE HF
  1616.                                                          SOURCEFILE SFILE SF
  1617.                     LOCALFILE(local filename)            LFILE LF
  1618.                                                          PCFILE PFILE PF
  1619.                                                          TARGETFILE TFILE TF
  1620.                     HOSTDIRECTORY(host directory)        HOSTDIR HDIR HD
  1621.                     LOCALDIRECTORY(local directory)      LOCALDIR LDIR LD
  1622.                     CHANGEDIRECTORY(host directory)      CHDIR CD
  1623.   sendall/synchost: CASE(DRIVE/upper/lower)              CS
  1624.    sendall/retrall: SINCE(yyyymmddhhmmss)                ASOF
  1625. synchost/synclocal: HOST-LOCALTIMEDIFFERENCE(hh:mm)      TIMEDIF HLTD TD
  1626.                     SITECOMMAND(site command)            SITECMD SITE SC
  1627.                     PROXYHOST(server)                    PHOST PH
  1628.                     PROXYPORT(number) [Default: 21]      PPORT PP
  1629.                     PROXYIGNOREFILE(filename)            IGNOREFILE PIFILE
  1630.                     CONTROLFILE(control filename)        CFILE CF
  1631.  
  1632.            HTTP <http subcommand> <arg1>...<argN>        WEB
  1633.    HTTP subcommands: RETRIEVE                            RETR GET
  1634.                      RETRIEVEHEADERS                     RETRHEAD GETHDR
  1635.      HTTP arguments: USERID(userid)                      USER U
  1636.                      PASSWORD(password)                  PASS PW
  1637.                      PORT(number) [Default: 80]
  1638.                      HOSTFILE(host filename)             HFILE HF
  1639.                                                          SOURCEFILE SFILE SF
  1640.                      LOCALFILE(local filename)           LFILE LF
  1641.                                                          PCFILE PFILE PF
  1642.                                                          TARGETFILE TFILE TF
  1643.                      LOCALDIRECTORY(local directory)     LOCALDIR LDIR LD
  1644.                      PROXYHOST(server)                   PHOST PH
  1645.                      PROXYPORT(number) [Default: 80]     PPORT PP
  1646.                      PROXYIGNOREFILE(filename)           IGNOREFILE PIFILE
  1647.                      CONTROLFILE(control filename)       CFILE CF
  1648.  
  1649.            EMAIL <email subcommand> <arg1>...<argN>      NOTE
  1650.    EMAIL subcommands: SEND
  1651.                       MAILWAITING                        MAILWAIT MWAIT MW
  1652.                       RETRIEVE                           RETR GET
  1653.                       DELETE                             ERASE DELE DEL
  1654.      EMAIL arguments: PORT(number) [Default: SMTP 25/POP3 110]
  1655.                       HOST(host)                         SMTPSERVER SMTP SS
  1656.                 send: FROM(address)                      F
  1657.                 send: TO(address/filename)               T
  1658.                 send: SUBJECT(subject string)            SUBJ SUB
  1659.                 send: NOTETEXT(text/filename)            TEXT BODY
  1660.   retrieve/mwait/del: USERID(userid)                     USER U
  1661.   retrieve/mwait/del: PASSWORD(password)                 PASS PW
  1662.             retrieve: LOCALFILE(local filename)          LFILE LF
  1663.                                                          PCFILE PFILE PF
  1664.                                                          TARGETFILE TFILE TF
  1665.             retrieve: LOCALDIRECTORY(local directory)    LOCALDIR LDIR LD
  1666.             retrieve: SEPARATOR(DEF,unix,hex=##,string)  DIVIDER SEP DIV
  1667.             retrieve: HEADERS(y/N)                       HDR
  1668.             retrieve: DELETE(y/N)                        ERASE DELE DEL
  1669.             retrieve: REPLACE(y/N)                       REPL REP RE
  1670.      retrieve/delete: MESSAGENUMBERS(msgX,msgY,...msgZ)  MSGNUMS MN
  1671.                                                          NOTENUMBERS NOTES NN
  1672.                       CONTROLFILE(control filename)      CFILE CF
  1673.  
  1674.            DEFINE <define subcommand> <arg1>...<argN>    STORE INI DEF
  1675.    DEFINE subcommands: DEFAULT_USERID userid             DEF_USER DEFUSER DU
  1676.                        PASSWORD userid password          PW
  1677.                        DEFAULT_MAILUSER address password DEF_MAIL MAILUSER DMU
  1678.                        DEFAULT_MAILFROM address          DEF_FROM FROM DF
  1679.                        SMTP_SERVER server                SERVER SMTP SS
  1680.                        POP3_SERVER server                POP3SERVER POP3 PS
  1681.                        FTP_SERVER server                 FTPSERVER FTP FS
  1682.                        FTPPROXY_SERVER server            FPS
  1683.                        HTTPPROXY_SERVER server           HPS
  1684.                        FTPPROXY_PORT number              FPP
  1685.                        HTTPPROXY_PORT number             HPP
  1686.                        PROXY_IGNORE_FILE filename        IGNORE_FILE PIFILE
  1687.                        PROXY on/off
  1688.                        VARIABLE variable value           VAR
  1689.  
  1690.