
















                                     TXTWRT


                                       by


                                   S.C. CRIBBS
                                Pinawa, Manitoba
                                 Canada  R0E1L0










                                    ABSTRACT

             TXTWRT is an RT-11 text formatting program written to  help
        programmers  create  effective  text  and  graphics  displays on
        today's "smart" terminals.  In addition,  full  support  of  the
        ANSI  standard  escape  sequence control strings used by Digital
        Equipment's video  and  printing  terminals  is  provided.   The
        output  generated  may be directly routed to the terminal, or to
        an ASCII stream file, or  TXTWRT  will  create  an  output  file
        suitably  formatted  as  either  FORTRAN-IV  or  MACRO-11 source
        statements.





                                     TXTWRT
                                     ------

             TXTWRT is an RT-11 text formatting program.  It  is  not  a
        text  editor!   TXTWRT  was  written  to help programmers create
        effective  text  and  graphics  displays  on   today's   "smart"
        terminals.   This  software tool can generate a "real-time" look
        at trial output forms and then format the finished product so it
        can be included in FORTRAN-IV or MACRO-11 programs.



        1.0  OVERVIEW




        1.1  Terminal Control Strings


             On the present generation of terminals, text  and  graphics
        characters  may be specifically located on the display screen or
        output form.  In addition, single lines and even  whole  display
        screens of text may be assigned special attributes such as bold,
        blinking, reverse video, or double  size.   These  features  are
        usually  implemented  through  use  of  multi-character  control
        strings sent to  the  terminal  from  the  application  program.
        TXTWRT generates the popularly used ANSI escape sequence control
        strings (ANSI standards:  X3.41-1974 & X3.64-1979 code extension
        techniques).

             1.  TXTWRT supports the DEC VT100 family of video terminals
                 (VT100, VT101, VT102, VT105, VT125, VT131) and also

             2.  supports the DEC LA120  family  of  hardcopy  terminals
                 (LA12, LA34, LA100, LA120, LA180).




        1.2   Output Routing Flexibilty


             1.  TXTWRT's  output  can  be  sent  to  the  terminal  for
                 immediate display, or

             2.  written  to  a  file  as  an  ASCII  stream  and  later
                 displayed on a terminal, or

             3.  written to a file formatted as FORTRAN-IV  or  MACRO-11
                 ASCII source input.


                                                                  Page 2



        1.3  Varied Output Formats


             TXTWRT combines text and escape sequence  control  commands
        in one of 3 formats:

             1.  a simple ASCII stream,
                 ie:
                 	$[2J$[3;10HHi there!
                    -where "$" represents an <ESC> character
                  

             2.  or as FORTRAN-IV source text,
                 ie:
                     BYTE TXTWRT(21)
                     DATA TXTWRT/"33,'[','2','J',"33,'[','3',';',
                    #   '1','0','H','H','i',' ','t','h','e',
                    #   'r','e','!',"200/
                  

             3.  or as MACRO-11 source text.
                 ie:
                     TXTWRT: .ASCII <33>/[2J/<33>/[3;10HHi there!/
                  


             Note that for either  the  FORTRAN-IV  or  MACRO-11  output
        formats,  two  additional  control  parameters may be specified.
        The output line length defaults to 72 characters.  Command  line
        options  allow  this value to be overwridden by the user.  It is
        not possible to represent all of  the  defined  ASCII  character
        codes   with  single  character  symbols.   By  default,  TXTWRT
        produces numeric byte values for ASCII codes  of  less  than  40
        octal  and  again  for  the highest (177 octal) code <DEL>.  The
        user may lower the high limit to record, for example, lower case
        characters  -  or  possibly  all  characters as their octal byte
        value equivalents.  This feature will  be  most  appreciated  by
        users with upper case only printers.

             RT-11  FORTRAN-IV  does  not  support   character   strings
        containing  more  than 255 characters.  TXTWRT relieves the user
        of the tedium of dividing the input into multiple strings.   The
        program  first  determines  the total number of characters to be
        formatted and then queries the user for  a  name  for  the  BYTE
        vectors  to be generated.  When more than 254 characters must be
        formatted, the  user  is  prompted  for  names  of  6  or  fewer
        characters.   TXTWRT  fills  in  numeric  characters to indicate
        sequence in the formatted output vectors.  It then  divides  the
        input  into 254 character length vectors, appending an octal 200
        byte string terminator to each.

                                                                  Page 3



        1.4  Input routing flexiblity


             TXTWRT requires user input of  two  distinct  types:   that
        which  controls  the program (COMMANDS) such as the input-output
        file specifications and also the actual characters and  terminal
        escape  sequences  (TEXT) that are to be combined and formatted.
        Input may be routed to the program in the following manner:

             1.  TEXT and COMMANDS may come from the user's terminal, or

             2.  TEXT and COMMANDS may come from an RT-11 command  file,
                 or

             3.  the TEXT  input  may  be  read  from  a  separate  user
                 specified file.




        1.5  Varied Input Formats


             TEXT input to  TXTWRT  is  received  by  the  RT-11  SYSLIB
        subroutines  "GTLIN"  and  "GETSTR"  and  is thus subject to the
        limitations of these two  routines.   Input  lines  must  be  80
        characters or less when read from the terminal or a command file
        but may be up to 132 characters in length when read from a  text
        file.  Four types of TEXT input lines are recognized by TXTWRT:

             1.  a simple line of text
                 ie:
                     How ya doin?
                  

             2.  a mnemonic for a terminal control command
                 ie:
                     \CLRALL		-erases VT100's screen
                     \CUP(3,10)		-position the cursor
                  

                      Terminal control command mnemonics generate Escape
                 sequence control strings.  A description of the defined
                 control strings is provided  in  Appendix  A.   Control
                 commands   consist  of  1  -  6  character  identifiers
                 followed optionally by numeric  arguments  enclosed  in
                 parentheses.   TXTWRT recognizes up to 20 arguments per
                 command where appropriate.   Each  argument  may  be  a
                 maximum  of  4  digits  long.  Characters following the
                 closing parentheses, (or the sixth  character  position
                 when  no  parameters  are specified), on the input line
                 are ignored and so may be used for documentation.


                                                                  Page 4



             3.  A TXTWRT program directive
                 ie:
                     \$REPT(5)	
                        .
                        .   -repeat enclosed text & commands 5 times
                        .
                     \$ENDR
                  
                        TXTWRT  supports  two  directives:   \$REPT  and
                 \$ENDR.   Place terminal control commands and text that
                 must be duplicated  between  these  two  directives  to
                 minimize   repetition  in  the  input  stream.   \$REPT
                 accepts one numeric argument enclosed  in  parentheses.
                 It's  value  specifies the number of times the enclosed
                 text  and/or  commands  are  to  be  duplicated  during
                 output.   An  argument  value  of zero requests that no
                 output of the enclosed text be generated.   The  \$REPT
                 directive can be nested to a depth of 9 levels.

             4.  An Octal number representing an ASCII character
                 ie:
                     \25		<NAK>
                     \12		<LINEFEED>
                  

                      Individual ASCII control characters must be  input
                 as  octal  numbers.  Trailing spaces on input lines are
                 not passed by "GTLIN" or "GETSTR" to TXTWRT,  therefore
                 spaces  to  follow text string input should be inserted
                 as octal codes.




        2.0  OPERATION


             TXTWRT  has  been  designed  to  execute  as  an  RT-11  V4
        background  job.  It may be started with either of the following
        commands.
         
        	.R TXTWRT         !if stored on the system device
         
                    or
         
        	.RUN XXu:TXTWRT   !if stored on alternate device XXu:

             TXTWRT proceeds through  two  phases  of  operation:   Once
        started,  the  program  is  in  COMMAND  phase to accept input -
        output file specifications and options.  When a command has been
        successfully  interpreted,  the  TEXT processing phase is begun.
        This phase continues until an end of  text  input  is  detected,
        where  upon  TXTWRT reverts back to COMMAND phase.  If the input
        has come from a terminal, text phase must be terminated  by  the
        two character sequence Control-Z <RET>.

                                                                  Page 5



        2.1  Command Phase


             Commands to TXTWRT are parsed by the RT-11  command  string
        interpreter  (CSI).  User's not familiar with it's syntax should
        consult the RT-11 User's Guide.  The program may  be  terminated
        by  either  a  Control-C  or  a  /E  option  response to the CSI
        asterisk  prompt.   Several  examples  follow  to  describe  the
        command options available.
         
        	I/O Command String Examples:
         
        *DL0:OUTPUT.FOR/F=TT:		!FORTRAN format (72 chars/line)
         
        *OUTPUT.FOR/F:60.=INPUT.TXT	!FORTRAN format (60 chars/line)
         
        *OUTPUT.FOR/L:137=DY1:INPUT.TXT	!Lowercase chars. as octal bytes
         
        *OUTPUT.MAC/M:80.=TT:		!MACRO format (80 chars/line)
         
        *OUP.MAC/M/E=INPUT.TXT/S	!MACRO from an ASCII stream file
        				! and then exit
         
        *TT:=INPUT.TXT			!Unformatted ASCII to terminal
         
        *TT:=TT:			!Read and write to terminal
         
        */E				!Terminate TXTWRT
         


                                                                  Page 6



             As  mentioned  above,  TXTWRT  features  are  selected   by
        including options and qualifiers in the I/O command string.  All
        but the /S option should be placed to  follow  the  output  file
        specification.   The  /S  option  must  follow  the  input  file
        specification and that file must reside  on  a  file  structured
        device  (ie  disk).   The /L and /E options may be combined with
        either of the two language formatting options.   Either  the  /F
        (FORTRAN-IV)  or  the /M (MACRO-11) outputs may be requested but
        not both in the same command  string.   Output  that  is  to  be
        formatted  as either of these languages must be routed to a file
        structured device.
         
        	Option			Definition
         
        	 /E		-Terminate upon completing command.
         
        	 /F:xxx		-Output in FORTRAN-IV, line length
        			  maximum of xxx characters.
         
        	 /H		-Print Help message on terminal.
         
        	 /L:vvv		-Output as octal code those characters
        			  with a value higher than vvv.
         
        	 /M:xxx		-Output in MACRO-11, line length
        			  maximum of xxx characters.
         
        	 /S		-This is an ASCII stream input file.
         



        2.2  Text Phase


             Input is read one line at a time.  Lines not  beginning  in
        column one with a backslash character are written directly to an
        ASCII stream output file.  Terminal  control  command  mnemonics
        are  parsed  and,  if  valid,  dispatched  to a subroutine which
        generates the appropriate Escape sequence.  The resulting string
        is  routed to the output stream.  Octal numbers are converted to
        binary before being written out.  Program  directives  \$REPT  &
        \$ENDR  are  tested  for  possible  nesting  errors before being
        implemented.  When FORTRAN-IV or MACRO-11  output  formats  have
        been requested, the ASCII stream output file is read back in and
        it's contents converted to the proper format before being saved.
        A  /S  option on the input file specification requests just this
        latter stage of processing.

             Two input examples suitable for use  with  VT100  terminals
        follow:

                                                                  Page 7



        \CLRALL			!Example  1 - Double sized centered text
        \CUP(10,34)
        Double Sized
        \NEL
        \NEL
        \BIGTOP
        \CUF(15)
        CENTERED
        \NEL
        \BIGBOT
        \CUF(15)
        CENTERED
        \NEL
        \NEL
        \CUF(37)
        Text
        \CUP(22,1)		!End of example  1
         
        \CLRALL			!Example  2 - Blinking text within box
        \CUP(7,20)
        \SCSGRF
        l
        \$REPT(4)	 ----
        \$REPT(9)	---  |
        q
        \$ENDR		---  |
        \$ENDR		 ----
        k
        \$REPT(9)	---
        \NEL		   |
        \CUF(19)	   |
        x
        \CUF(36)	   |
        x
        \$ENDR		---
        \CUP(17,20)
        m
        \$REPT(3)	  -----
        \$REPT(4)	 ----  |
        \$REPT(3)	---  | |
        q
        \$ENDR		---  | |
        \$ENDR		 ----  |
        \$ENDR		  -----
        j
        \SCSUSA
        \CUP(12,38)
        \SGR(1,5)
        WOW!
        \SGR(0)
        \CUP(22,1)		!End of example  2
         

                                                                  Page 8



        3.0  PROGRAM STRUCTURE


             TXTWRT.SAV which is an executable file suitable for use  on
        RT-11  systems that support EIS instructions, has been provided.
        It requires 13.0 Kw of memory.  TXTWRT.OVL is the  same  program
        but  linked  as  an  overlay  structure  and requires 11.2 Kw of
        memory.  The source files have also been included.  Should it be
        necessary to rebuild the program, execute command files TXTC.COM
        to compile and TXTL.COM OR TXTLO.COM to link the object modules.
        This  will  be necessary for systems that support only NHD code.
        TCFL.BFO, (the terminal  control  command  generator),  must  be
        generated  from  PTXTW.MAC,TCFLO.MAC  &  TCFLIO.MAC with symbols
        ONLY$O, USERBF, VT125, & LA34 all defined to be 1,  (and  symbol
        NHD defined if no EIS instruction support).  
         
        	File:  TXTC.COM
         
         .FORTRA/NOLINE (TXTWRT,IPARSE,MATCH,NEST,ENC).FOR
         .MACRO KMP2WU.MAC,IDSPTC.MAC
         .MACRO PTXTW+TCFLIO/OBJECT
         .MACRO PTXTW+TCFLO/OBJECT
         .LIBRARY/CREATE TCFL.BFO TCFLIO,TCFLO
         
        	File:  TXTL.COM
         
         .LINK/I/PROMPT TXTWRT,IPARSE,MATCH,KMP2WU,IDSPTC,NEST
         *ENC,TCFL.BFO//
         Library search?  $SHORT
         Library search?
         
        	File:  TXTLO.COM
         
         .LINK/I/PROMPT TXTWRT
         *IPARSE,MATCH,KMP2WU,IDSPTC,NEST,TCFL.BFO/O:1
         *ENC/O:1//
         Library search?  $SHORT
         Library search?
         












                                   APPENDIX A

              Alphabetical Index of All Terminal Control Commands




Alphabetical Index of All Terminal Control Commands             Page A-2



        ================================================================
         Name	     Generated Code		Function Description
        ----------------------------------------------------------------
        ALIGND		<"33>#8		-ALIGN Display (fill the text
        				 screen with E's)
        ANSI		<"33><		-set terminal to respond to ANSI
        				 escape codes
        BIGBOT		<"33>#4		-BIG BOTtom of double height and
        				 width line
        BIGTOP		<"33>#3		-BIG TOP of double height and
        				 width line
        CLRALL		<"33>[2J	-CLeaR ALL of the text screen
         
        CLRBEG		<"33>[1K	-CLeaR the BEGinning of this
        				 text line
        CLRBOT		<"33>[0J	-CLeaR from cursor to BOTtom of
        				 the screen
        CLREND		<"33>[0K	-CLeaR from cursor to the END of
        				 this text line
        CLRLIN		<"33>[2K	-CLeaR this entire text LINe
         
        CLRTOP		<"33>[1J	-CLeaR text from TOP of screen
        				 to the cursor position
        CRLF		<"15><"12>	-generate Carriage Return,
        				 Line Feed sequence
        CUB(m)		<"33>[~D	-move CUrsor Backward "m"
        				 character positions
        CUD(m)		<"33>[~B	-move CUrsor Down "m" lines
         
        CUF(m)		<"33>[~C	-move CUrsor Forward "m"
        				 character positions
        CUP(m,n)	<"33>[~;~H	-CUrsor Position to line "m"
        				 column "n"
        CUU(m)		<"33>[~A	-move CUrsor Up "m" lines
         
        DCS105		<"33>P0t	-Device Control String - emulate
        				 VT105 graphics
        DCS125		<"33>P0p	-Device Control String - enter
        				 REGIS graphics
        DCSDIF		<"33>P0q	-Device Control String - Delimit
        				 Image Format
        DWL		<"33>#6		-Double Width Line
         
        GIMOAP		<"33>[?0i	-Graphics IMage Output to
        				 Auxiliary Port
        GIMOHC		<"33>[?2i	-Graphics IMage Output to Host
        				 Computer

Alphabetical Index of All Terminal Control Commands             Page A-3



        ----------------------------------------------------------------
         Name	     Generated Code		Function Description
        ----------------------------------------------------------------
        GPOFF		<"33>2		-Graphics Processor OFF
         
        GPON		<"33>1		-Graphics Processor ON
         
        HPA(m)		<"33>[0`	-Horizontal Position Absolute
         
        HPR(m)		<"33>[0a	-Horizontal Position Relative
         
        HRDCPY		<"33>#7		-HaRDCoPY (Dump VT100 text
        				 screen to printer)
        HTBCLA		<"33>[3g	-Horizontal TaB CLear All
         
        HTBCLC		<"33>[0g	-Horizontal TaB CLear at Current
        				 position
        HTBSTC		<"33>H		-Horizontal TaB SeT at Current
        				 position
        HTBSTS(m,n...)	<"33>[~;~;~;~u	-Horizontal TaB SeT at 
        				 Specified columns 
        IND		<"33>D		-INDex (move down one line,
        				 maintain column)
        KPAM		<"33>=		-KeyPad Application mode
         
        KPNM		<"33>>		-KeyPad Numeric mode
         
        LLEDS(m,n,o,p)	<"33>[~;~;~;~q	-Light specified LEDS (0 means
        				 extinguish all) 
        LNEFDM		<"33>[20l	-LiNE FeeD Mode (<LF> generates
        				 only <LF>)
        MDCPY(m)	<"33>[~i	-Media CoPY mode option "m"
         
        NEL		<"33>E		-NExt Line (move to beginning of
        				 the next line)
        NWLNEM		<"33>[20h	-NeW LiNE Mode (<LF> generates
        				 <CR><LF>)
        PLD		<"33>K		-Partial Line Down
         
        PLU		<"33>L		-Partial Line Up
         
        RESCUR		<"33>8		-REStore CURsor
         
        RGSTRM		<"33>\		-ReGiS graphics mode terminator
         
        RI		<"33>M		-Reverse Index (up one line,
        				 maintain column)
        RIS		<"33>c		-Reset to Initial State
         
        RM(m)		<"33>[?0l	-Reset Mode for option "m"
         

Alphabetical Index of All Terminal Control Commands             Page A-4



        ----------------------------------------------------------------
         Name	     Generated Code		Function Description
        ----------------------------------------------------------------
        RPTCP		<"33>[6n	-RePorT Cursor Position
         
        RPTDS		<"33>[5n	-RePorT Device Status
         
        RPTID		<"33>[0c	-RePorT Terminal IDentification
        				 code
        SAVCUR		<"33>7		-SAVe CURsor
         
        SCS0		<"17>		-Shift to Character Set G0
         
        SCS1		<"16>		-Shift to Character Set G1
         
        SCSAL1(m)	<"33>*1		-Select Character Set -
        				 Alternate Standard set
        SCSAL2(m)	<"33>*2		-Select Character Set -
        				 Alternate Special set
        SCSFIN(m)	<"33>*C		-Select Character Set - FINNISH
         
        SCSFRA(m)	<"33>*R		-Select Character Set - FRENCH
        				 (FRANCE)
        SCSGER(m)	<"33>*K		-Select Character Set - GERMAN
         
        SCSGRF(m)	<"33>*0		-Select Character Set - VT100
        				 line graphics
        SCSNOR(m)	<"33>*E		-Select Character Set - 
        				 NORWEGIAN
        SCSQUE(m)	<"33>*Q		-Select Character Set - FRENCH
        				 (Quebec)
        SCSSWE(m)	<"33>*H		-Select Character Set - SWEDISH
         
        SCSUK(m)	<"33>*A		-Select Character Set - ENGLISH
        				 (BRITAIN)
        SCSUSA(m)	<"33>*B		-Select Character Set - ENGLISH
        				 (AMERICAN)
        SETLPP(m)	<"33>[~t	-SET "m" Lines Per Page
         
        SETLRM(m,n)	<"33>[~;~s	-SET Left (column "m") & Right
        				 ("n") Margins
        SETTBM(m,n)	<"33>[~;~r	-SET Top (line "m") & Bottom
        				  "n" Margins (scrolling region)
        SGR(m,n,o,p)	<"33>[~;~;~;~m	-Select Graphic Rendition of
        				 following chars.
        SHPTCH(m)	<"33>[~w	-Set Horizontal PiTCH to
        				 option "m"
        SM(m)		<"33>[?~h	-Set Mode for option "m"
         

Alphabetical Index of All Terminal Control Commands             Page A-5



        ----------------------------------------------------------------
         Name	     Generated Code		Function Description
        ----------------------------------------------------------------
        SS2		<"33>N		-Single Shift 2 - select G2 set
        				 for one character
        SS3		<"33>O		-Single Shift 3 - select G3 set
        				 for one character
        SVPTCH(m)	<"33>[~z	-Set Vertical PiTCH to option "m"
         
        SWL		<"33>#5		-Single Width Line
         
        VPA(m)		<"33>[~d	-Vertical Position Absolute - 
        				 active line to "m"
        VPR(m)		<"33>[~e	-Vertical Position Relative - 
        				 advance "m" lines
        VTBCLA		<"33>[4g	-Vertical TaB CLear All
         
        VTBCLC		<"33>[1g	-Vertical TaB CLear at Current
        				 position
        VTBSTC		<"33>J		-Vertical TaB SeT at Current
        				 position
        VTBSTS(m,n...)	<"33>[~;~;.;.v	-Vertical TaB SeT at Specified
        				 lines "m,n..."
        ----------------------------------------------------------------
         
        Notes:

             1.  The symbol " ~  "  represents  the  ASCII  code  for  a
                 decimal numerical argument to a terminal command.

             2.  Omitted or null  arguments  to  commands  that  require
                 arguments result in a zero character being generated in
                 the output string.  Argument values  too  large  for  a
                 particular   command  are  replaced  with  the  highest
                 acceptable value.  Excess arguments are ignored.   ANSI
                 protocol  does  not  limit the number of arguments that
                 may be passed to commands HTBSTS  &  VTBSTS.   However,
                 default  space  for  arguments  in the output string is
                 twenty characters, thus a  program  reassembly  may  be
                 necessary for special case applications.

             3.  Arguments to the character set selection commands  (eg.
                 SCSUSA(m))  are  a  special  case.   The argument value
                 should be either zero or one.  If the argument is  zero
                 or  omitted,  the  "  * " in the generated code will be
                 replaced with a " ( " which designates  this  character
                 set  as the G0 set.  An argument value of one generates
                 the " ) " character which designates this character set
                 as the G1 set.

             4.  Characters enclosed in angle parentheses  describe  the
                 octal value of the ASCII code generated.


