# CAPTURE macro for downloading text files from VMS without Kermit protocol.
#
# Windows Installation:
#   Copy this text into your K95CUSTOM.INI file.
#   Tell K95 to "take \v(appdata)k95custom.ini" or restart K95.
#   Alternatively, store this in a separate file and add a TAKE
#   command for it to your K95CUSTOM.INI file.
#   Alternatively, just give a TAKE command for this file at the K-95> prompt.
#
# Usage:
#   You must already have a connection to VMS and VMS must be at its
#   command prompt.  If necessary, use Alt-X (or the second toolbar button)
#   to go to K95's command screen.
#   At the K-95> prompt, type "capture xxx", where xxx is the name of the
#   file you want to download.  Alternatively you can type
#   "capture xxx yyy" where yyy is the name you want to give the in Windows.
#   If you don't give the second argument the file is stored with the
#   same name.  The default timeout (maximum number of seconds for the
#   capture to complete) is 120 seconds.  You can override the default by
#   giving another number as the third argument.  After the capture, use
#   Alt-X or the second toolbar button to rerturn to VMS.
#
# Bugs and limitations:
#   1. The VMS command prompt appears at the end of the captured file.
#   2. The capture can terminate prematurely if the VMS command prompt
#      appears in the file itself.
#   3. Since there is no error checking the captured file might have errors
#      or gaps, especially on serial-port or modem connections.
#   4. You can only capture text files this way.
#   5. You can only capture one file at a time.
# (That's why it's better to use a real file transfer protocol)
#
# Note: by changing the first two parameters just below, this macro can also
# be used to capture files from Unix or other OS's with text-based command
# shells.
#
# Note 2: Instructions are for Windows, but it can be run on Unix, VMS,
# or other platforms too.
#
# F. da Cruz, Columbia University, July 2008
#
define hostprompt "$ "                  # VMS command prompt
define typecommand "TYPE /NOPAGE"       # VMS command to display the file
define capturetimeout 120               # Maximum time for capture (seconds)

define CAPTURE {
    if not def \%1 {
        echo "Usage:"
        echo "CAPTURE vmsfilename [ localfilename [ timeout ] ]"
        end 1
    }
    if not def \%2 assign \%2 \%1       # Local filename
    if not def \%3 assign \%3 \m(capturetimeout) # Timeout

    if exist \%2 getok "OK to overwrite existing copy of \%2? "
    if fail end 1    

    clear input                         # Clear INPUT buffer
    output \13                          # Send a carriage return
    input 5 "\m(hostprompt)"            # Wait to see prompt
    if fail stop 1 CAPTURE: ERROR - FAILURE TO SEE DCL PROMPT "\m(hostprompt)"
    
    log session \%2                     # Open capture file
    if fail end 1                       # Make sure it was opened.
    output \m(typecommand) \%1\13       # Tell VMS to display the file.
    input \m(capturetimeout) "\m(hostprompt)" # Wait for next DCL prompt
    if fail {
        echo "TIMEOUT \v(inwait) seconds - \%2 might be incomplete." 
        echo "Check that the VMS prompt definition agrees with the"
        echo "the actual VMS prompt.  Hint: you can specify a longer"
        echo "timeout by changing the 'capturetimeout' definition or by"
        echo "specifying the time limit as a third agument."
        close session
        end 1
    }
    close session                       # Close the capture file
    echo "CAPTURE \%1 -> \%2 OK:"       # Give messages
    directory \%2    
    end 0
}
