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 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 . 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 \12 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 . 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 ( generates only ) 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 ( generates ) 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.