The ROUTE EDIT Macro for ISPF

Syntax

ROUTE must be invoked as an EDIT macro in an EDIT or VIEW ISPF session.

	ROUTE
	  dest				SPOOL Destination or WS File Name
	  first				First line       .A
	  last				Last line        .B
	  CCHAR				Data contains carriage control characters
	  CLASS(class)			Class
	  COPIES(copies)		Number of copies
	  DEST(dest)			Destination (alt)
	  FCB(FCB-name)			Name of the FCB
	  FORMS(forms-number)		Forms number
	  HOLD/NOHOLD			HOLD/NOHOLD
	  TITLE|NOTITLE			Print/Do-not-print header
	  PAGELEN(lines)		Number of lines per page
	  OUTDES(output-descriptor-name)
	  PORTRAIT|LANDSCAPE		Print Format on Laserjet or Xerox 3700
	  WRITER(external-writer-name)

	Defaults: CLASS(A) NOCCHAR NOHOLD PAGELEN(60) TITLE 

Operands

• dest is the name of the JES printer to which the data will be written. dest must be coded like the DEST key-word of a DD statement or ALLOCATE command. For a local printer, specify LOCAL or R0. For other destinations, use the appropriate value, such as R4, L3287, PROD.X3700, N5R22, or RMT35. dest defaults to LOCAL if CLASS is specified; otherwise, dest is a required operand unless a default is specified in Default_Dest. dest may also be specified as a key-word operand, i.e. DEST(dest). If dest is specified as a work-station file name such as c:\abcdef.txt or /usr/etc/abcdef, ROUTE uses the ISPF FILEXFER service to transfer the data to the corresponding work-station file.
• first and last are labels that define the range of lines to be printed. Any currently defined label is valid, e.g. .ZF .ZCSR .HERE, etc. A range of lines can alternatively be specified using C/CC or M/MM line commands. Specification of a range is optional; if no range is specified, the entire data set is written.
• class optionally specifies the output class used by ROUTE to allocate the SYSOUT data set. If not specified, Default_class is used or, if value specified for dest is present in the Default Attribute Table, the associated class is used.
• copies optionally specifies the number of copies. The default value is one.
• Output-descriptor is the name of an output descriptor that will be associated with the SYSOUT data set. Output descriptors are created by the // OUTPUT statement in the LOGON procedure or the OUTDES command.
• Lines optionally specifies the number of lines printed per page. The default is Default_pagelen unless dest is present in the Default Attribute Table.
• Forms-number is a 4-character forms number. The default is Default_forms unless dest is present in the Default Attribute Table.
• HOLD and NOHOLD specify that the output should be held in the JES output queue until it is released (HOLD) or should be made available for printing immediately (NOHOLD).
• FCB-number is a 4-character FCB number. The default is blank and can be overridden on a dest basis in the Default Attribute Table.
• CCHAR is an optional key-word indicating that the first byte of each record is a carriage control character (ASA or machine). ROUTE inspects the first record to determine the control character type (i.e. ASA or machine). CCHAR implies NOTITLE.
• TITLE is a default key-word that needs only be specified in conjunction with CCHAR.
• NOTITLE is an optional key-word that prevents a title line from being printed at the beginning of the print file to identify its contents.
• PORTRAIT and LANDSCAPE are optional key-words that generate the character sequences necessary to switch an HP LasetJet or a XEROX 3700 printer to the corresponding orientation at the beginning of the print file, then switch it back to the default orientation at the end. Support for XEROX 3700 printers requires making a small change to the ROUTE REXX exec - please contact us for details.

Notes:

• ROUTE operands may be specified in any order.
• ROUTE was initially designed to print on RJE printers, which is why the destination parameter is mandatory. To make the destination an optional parameter, set the Default_dest variable to the default destination (such as LOCAL or RMTnn).
• The C or M line commands (in any form) may be used to select a range of lines. If the M line command is used, the lines printed are deleted.
• When printing data that does not contain control characters, you may use the control word .SK in pos 1 of a line each time you want to start a new page.
• Routing to a work-station file requires an existing connection to the work-station agent (WSA). Only the dest and debug parameters are allowed; all other parameters are ignored.
• You can invoke ROUTE from a REXX exec or CLIST to provide shortcuts or hide complex option strings. The outer macro specifies additional operands as arguments to the ROUTE macro. For example, to relieve users from having to type WRITER(W132) when they print to a particular printer, create a ROUTE132 macro as follows: "%ROUTE WRITER(W132)"; EXIT RC

Examples:

• ROUTE R4
• ROUTE FLOOR1 COPIES(2) CCHAR
• ROUTE XRX3700 .A .B CLASS(Q) COPIES(3) NOTITLE PORTRAIT CCHAR
• ROUTE c:\temp\text.file debug

Installation and Tailoring

ROUTE can be found in file 183 of the CBT Tape, and consists of three elements:

1. The ROUTE Macro itself, a TSO/E REXX exec
2. The ROUTEHLP member, a TSO HELP file
3. The ROUTEPGM assembler program, an optional performance enhancer for ROUTE

To install ROUTE and make it available to ISPF/PDF users, simply copy the REXX exec to a REXX or CLIST library allocated to the TSO/ISPF session in the SYSEXEC or SYSPROC DD concatenations.

You may also copy the ROUTEHLP member to an ISPPLIB data set. This allows TSO users to get help when they enter the ROUTE ? command.

The ROUTEPGM program may be assembled and link-edited into a load-library accessible to ISPF. When ROUTEPGM is present, ROUTE automatically uses it to speed up its processsing. Incidentally, ROUTEPGM is a fairly generic program which can be used by any CLIST or REXX EDIT macro which needs to copy data from the EDIT (or VIEW) session to a data set.

The ROUTE macro itself can be tailored at installation time by modifying two tables it contains:

/*--------------------------------------------------------------------*/
/*                                                                    */
/*                  Define Default Values                             */
/*                                                                    */
/*--------------------------------------------------------------------*/
Default_Class='A'              /* Default CLASS                       */
Default_Dest='LOCAL'           /* DEST defaults to LOCAL              */
Default_Dest=''                /* User must specify DEST              */
Default_Forms=''               /* No special form required            */
Default_Node=''                /* Dest defined on this JES            */
Default_Pagelen=60             /* Lines per page                      */
Print_Line_Numbers='NO'        /* Do NOT print line numbers           */
Print_Line_Numbers='YES'       /* Print line numbers                  */
Routepgm='XYZ.LOAD'            /* Use ISPLLIB LIBDEF                  */
Routepgm='NO'                  /* Use the REXX stack and EXECIO       */
Routepgm='YES'                 /* Use the ROUTEPGM program            */
xdsn='ISPFCS.TEXT'             /* temp dsn for WS download            */ 

Default_Node optionally indicates a default NJE node through which remote printers are accessible. If Default_Node is non-null, ROUTE prepends the specified value to the dest value.

/*--------------------------------------------------------------------*/
/*                                                                    */
/*                Printer Default Attribute Table                     */
/*                                                                    */
/*     This table defines default attributes for printers.            */
/*  It must be set up locally for every printer that requires default */
/*  attributes different from the values set in the Default_nnnnn     */
/*  variables above.  Hyphens must be used to indicate null values.   */
/*                                                                    */
/*  Note: for a JES2 remote, you must use the RMTn format (no leading */
/*        zeroes in the numeric portion).                             */
/*--------------------------------------------------------------------*/

 /*         PRINTER  NODE/NODE.DEST CLASS PAGELEN FORMS  FCB  MODE   */
printer.1 ="LOCAL    -                A     60    -       -    -      "
printer.2 ="DEVV     -                G     60    -       -    -      "
printer.3 ="ROSV     -                Q     60    -       -    -      "
printer.4 ="XRX3700  -                Q     60    -       -    P37    "
printer.5 ="ESG3700  DEVV             Q     60    -       -    P37    "
printer.6 ="SSG1     DEVV.SSG13287    Q     60    -       -    L37    " 

Historical Background

ROUTE was written in 1988 as a CLIST for ISPF/PDF 2.3, the first release of ISPF/PDF which supported EDIT macros. ROUTE was designed to print EDIT data to a nearby 3287 matrix printer, defined to JES2 as RMT4, or R4. In the 1990s, ROUTE was converted from CLIST to REXX and enhanced for flexibility and speed. In 1995, ROUTE R604 was added to File 183 of the CBT Tape. Support for writing to work-station files via the ISPF FILEXFER service was added in 1998.

Original ROUTE CLIST, ca 1988:

ISREDIT MACRO (DEST,FIRST,LAST)
IF &DEST = &STR() THEN -
  DO
    WRITENR ENTER DESTINATION:
    READ DEST
    IF &DEST = &STR() THEN EXIT CODE(8)
  END
IF &FIRST = &STR() THEN SET FIRST = .ZFIRST
IF &LAST  = &STR() THEN SET LAST  = .ZLAST
IF &SUBSTR(1:1,&FIRST) = &STR(.) THEN ISREDIT (FIRST) = LINENUM &FIRST
IF &SUBSTR(1:1,&LAST)  = &STR(.) THEN ISREDIT (LAST)  = LINENUM &LAST
ISREDIT (DSNAME) = DATASET
ISREDIT (MEMBER) = MEMBER
IF &MEMBER ¬= &STR() THEN SET MEMBER = &STR((&MEMBER))
ISREDIT (LEN) = LRECL
/* IF &LEN > 132 THEN SET LEN = 132
SET LEN = 133
 /*
  ALLOC DD(DDROUTE) SYSOUT(A) DEST(&DEST) RECFM(F A) BLKSI(&LEN) REUSE
IF &DEST = LOCAL OR &DEST = R0 THEN  +
  ALLOC DD(DDROUTE) SYSOUT(V) DEST(&DEST) RECFM(F A) BLKSI(&LEN) REUSE
OPENFILE DDROUTE OUTPUT
SET DDROUTE = &STR(USERID=&SYSUID  DATE=&SYSDATE TIME=&SYSTIME)
SET DDROUTE = &STR(1&DDROUTE    DATASET=&DSNAME&MEMBER)
PUTFILE DDROUTE                            /* WRITE HEADER
SET CTLCHR=0
SET LINECT=2
 /*
DO WHILE (&FIRST LE &LAST)
  ISREDIT (DDROUTE) = LINE &FIRST          /* GET CURRENT LINE
  IF &LEN > 133 THEN SET DDROUTE = &SUBSTR(1:&LEN,&STR(&DDROUTE))
  SET DDROUTE = &STR(&CTLCHR&DDROUTE)
  PUTFILE DDROUTE                          /* WRITE CURRENT LINE
  SET FIRST = &FIRST+1                     /* NEXT LINE NUMBER
  SET CTLCHR=&STR( )
  SET LINECT=&LINECT+1
  IF &LINECT>75 THEN SET CTLCHR=1
  IF &LINECT>75 THEN SET LINECT=1
END
CLOSFILE DDROUTE
FREE DD(DDROUTE)
SET &ZEDSMSG = &STR(DATA SET ROUTED)       /* SHORT MESSAGE
SET &ZEDLMSG = &STR(YOUR EDIT DATA SET HAS BEEN ROUTED TO DEST(&DEST))
ISPEXEC SETMSG MSG(ISRZ001)                /* SEND THE MESSAGE