SETUP_DETAILS.TXT for:                                           15-Nov-2004

     Drain-Printer, TOOLS, Capture a print stream into a file

See the very lengthy comments at the beginning of the source code for all the
details on what this does and how to set it up... an overview follows here.

Since the program itself is named DRAIN, I may use that name instead of
Drain-Printer from time to time...

---------------------------------------------------

STEPS TO GET STARTED:

1.  Choose a high-numbered port;  in this example I will use 9876.

2.  Choose a local printer name;  I will use TEST3.

3.  Choose where the output should go;  I will use DUA2:[VERNE]TEST.LIS.

4.  Optional: Choose a pre-filter DCL cmd file;  DUA3:[DRAIN]PRE-FILTER.COM

5.  Optional: Choose a post-filter DCL cmd file;  DUA3:[DRAIN]POST-FILTER.COM

6.  Optional: Choose an OPCOM message class to receive msgs;  I'll use OPER5.
	(Note:  see HELP  REQUEST  /TO  for a list of all the message classes)
	(DRAIN reports significant errors to OPCOM using this message class;
	the default class is CENTRAL)

7.  take the EXE file you have created (or use mine) and put it someplace
	accessible;  I will use the Multinet: directory.   See
	KIT_CONTENTS.TXT for details on the prebuilt files I've included.

---------------------------------------------------

Typically Multinet server modules run under the username SYSTEM, and DRAIN
runs as a detached process (and then dies) whenever a print job comes to it.
Since all the above logicals must be available to DRAIN, the easy place
to put them is in the system table:

  DEFINE/SYSTEM  MULTINET_DRAIN_9876       DUA2:[VERNE]TEST.LIS
  DEFINE/SYSTEM  MULTINET_DRAIN_CMD1_9876  DUA3:[DRAIN]PRE-FILTER.COM
  DEFINE/SYSTEM  MULTINET_DRAIN_CMD2_9876  DUA3:[DRAIN]POST-FILTER.COM
  DEFINE/SYSTEM  MULTINET_DRAIN_OPC_CLASS_9876  OPER5

Now create the Multinet service and restart the Master Server
(Note: the name of the service is not important;  naturally it must not
conflict with any existing Multinet service):

  $ MULTINET CONFIGURE/SERVER
  MultiNet Server Configuration Utility V4.3(42)
  [Reading in configuration from MULTINET:SERVICES.MASTER_SERVER]
  SERVER-CONFIG> ADD  DRAIN9876
  [Adding new configuration entry for service "DRAIN9876"]
  Protocol: [TCP] TCP
  TCP Port number: 9876
  Program to run: MULTINET:DRAIN.EXE
  [Added service DRAIN9876 to configuration]
  [Selected service is now DRAIN9876]
  SERVER-CONFIG> RESTART
  Configuration modified, do you want to save it first ? [YES] YES
  [Writing configuration to MULTINET_COMMON_ROOT:[MULTINET]SERVICES.MASTER_SERVER]
  %RUN-S-PROC_ID, identification of created process is xxxxxx
  SERVER-CONFIG> QUIT

Now create the Multinet print queue and make it operational:

  $ MULTINET CONFIG/PRINT
  MultiNet Remote Printer Configuration Utility V4.3(25)
  PRINTER-CONFIG> ADD  TEST3
  [Adding new configuration entry for queue "TEST3"]
  Remote Host Name: 127.0.0.1
  Protocol Type: [LPD] STREAM
  TCP Port Number: [23] 9876
  [TEST3 => 127.0.0.1, TCP port 9876 (no telnet option negotiation)]
  PRINTER-CONFIG> EXIT
  [Writing configuration to MULTINET:REMOTE-PRINTER-QUEUES.COM]
  $ @MULTINET:REMOTE-PRINTER-QUEUES.COM  TEST3

Of course see the Multinet documentation for general assistance on
setting up your system to receive inbound LPR jobs and such...
or to restrict who can "print" to you  :-)

Now any printouts directed to the queue TEST3 will end up as a text file
called TEST.LIS in the directory DUA2:[VERNE].

To do fancy stuff, you can use the optional PRE and POST DCL command
files... in there use code like:

  $owner = f$getjpi("","OWNER")
  $!
  $port = f$trnlnm("MULTINET_DRAIN_P1_''OWNER'")
  $!
  $size = f$file("MULTINET_DRAIN_''port'","ALQ")
  $!
  $output_name = f$search("MULTINET_DRAIN_''port'")
  $!
  $tmp_name = f$search("MULTINET_SPOOL:DRAIN_''port'.TMP")

to make decisions on how to proceed or to do special things.

DRAIN will not complain if the PRE or POST DCL routine cannot be located
or accessed... DRAIN will process the print job in the default manner.

Both the PRE and POST DCL routines can pass back a simple flag to DRAIN;
use $EXIT xxx in DCL to pass back a control value via the $STATUS mechanism:

         1          create filtered file, delete temp file
         9 (8+1)    Don't create filtered file
        17 (16+1)   Don't delete temp file
        25 (8+16+1) Don't do either one

If any value is received other than one of these, DRAIN will do all normal
processing as if "1" was received.  Naturally when returning from POST the 9
flag wouldn't make sense since by the time POST is ran the filtered file
already exists  (and DRAIN will not delete it once it has been created)  :-)


Verne
-----------------------------------------------------------------------
Verne Britton, Lead Systems Programmer     voice: (304) 293-5192 x230
Systems Support Group                      (in WV, call 1-800-253-1558)
West Virginia Network for                  FAX:   (304) 293-5540
     Educational Telecomputing             verne@wvnet.edu
837 Chestnut Ridge Road                    http://vaxa.wvnet.edu/~verne
Morgantown, WV  26505
