Parser For VT420 Terminal Emulators

Download the source code for the parser

Before Using VTParser In Any Applications, Please Read The Entire Document

This software is being provided to you, the LICENSEE, by the Massachusetts Institute of Technology (M.I.T.) under the following license. By obtaining, using and/or copying this software, you agree that you have read, understood, and will comply with these terms and conditions:

Permission to use, copy, modify and distribute this software and its documentation for any purpose and without fee or royalty is hereby granted, provided that you agree to comply with the following copyright notice and statements, including the disclaimer, and that the same appear on ALL copies of the software and documentation, including modifications that you make for internal use or for distribution:

Copyright 1995 by the Massachusetts Institute of Technology. All rights reserved.


The name of the Massachusetts Institute of Technology or M.I.T. may NOT be used in advertising or publicity pertaining to distribution of the software. Title to copyright in this software and any associated documentation shall at all times remain with M.I.T., and USER agrees to preserve same.

Files Required:

  1. VTPARSER.C --- Code for the parser's engine
  2. VTPARSER.H --- Internal header for the parser
  3. VTTABLE.C ---- Dispatch tables for the parser
  4. VTCMND.H ----- Header defining and briefly describing VTxxx commands
  5. VTPSDEF.H ---- Header declaring ParserStruct
  6. VTESCSEQ.C --- Code for including definitions of escape sequences
  7. VTCONST.H ---- Header defining values for the parser constants
  8. VTPRNCTL.C --- Definitions for the special terminating sequences
  9. VTPRNCTL.H --- Declarations for the special terminating sequences
  10. VTDCS.C ------ Code for processing DCS sequences
  11. VTDCS.H ------ Header for processing DCS sequences
  12. VTE152.T ----- ESC Fc - type sequences for VT52
  13. VTE1ANSI.T --- ESC Fc - type sequences for VT420 mode
  14. VTE2.T ------- ESC Ic Fc - type sequences
  15. VTCSI.T ------ CSI sequences
  16. VTDCS.T ------ DCS sequences
  17. MAKETBL.BAT -- Batch file for converting all .t files into .tbl
  18. __FOO__.BAT -- Batch file used internally by MAKEDEF.BAT
  19. CUTCOM.COM --- Used internally by __FOO__.BAT and MAKENAME.BAT
  20. SORTSTR.COM -- Used internally by __FOO__.BAT and MAKENAME.BAT (like DOS, but case sensitive).
  21. SHELL.C ------ A debug/demonstration shell for the parser.
  22. MAKENAME.BAT - Batch file for converting VTCMND.H into VTDEBUG.TBL
  23. CMNDNAME.EXE - Used internally by MAKENAME.BAT

Compatibility and Portability of the Parser:

VTPARSER is written completely in ANSI C to guarantee its compatibility with different platforms and C compilers. Please, note that the program allows using PASCAL-style function calls. For that purpose "PASCAL" is defined as "pascal" in VTPARSER. For your compiler you might need to change the definition of PASCAL or define PASCAL to nothing. You may also want to change the definitions of the data types according to the operating system for which the code is to be complied. If you decide to redefine the data type for your operating system, the only requirement for the size of the data-types is to be not smaller than the standard associated with the mnemonic allows.

In order to use this VTParser within your applications, you will need to include VT420.H header file.

Functions available to the application:

PS structure's variables available to the application:

The following variables are available for READ/WRITE:

The following variables are available for READ ONLY:

Please do NOT modify these variables, or the parser may become unstable. To change the parser's mode do not modify vtmode, but use SwitchParserMode instead.

Customizing VTTABLE.C

const PA_INT parse_tbl[];

The first table defined in VTTABLE.C describes the action the parser has to perform when it encounters a corresponding ASCII value in the data. The actions, as defined in VTCONST.H, are:

const PA_USHORT flag_tbl[];

The second table defined in VTTABLE.C is a flag table. It describes characters for CSI and DCS sequences. These constants are defined in VTCONST.H

const PA_USHORT hextodec[];

This is a lookup table for the conversions of hexadecimals to decimals. The values are:

const PA_SHORT keytbl[];

This is a table that correlates the key codes to the actual functional key numbers for Process_DECUDK. Values:

const PA_SHORT attrtbl[];

This is a table that related the attributes to their codes. Note, ATTR_BOLD is associated with code 1 and code 2. Attributes are defined in VTCONST.H

const PA_SHORT citbl[];

This table contains the code-types for Process_DECRSCI. The values are:

Customizing Escape, Control, And Device Sequence Definitions:


The parser is using several tables that define most of the VT control sequences. Those tables (slightly modified by MAKETBL.BAT) are included at compile-time. All tables have .t extension. All tables are text files that define one escape sequence per line.

Format of escape sequence definition tables

All tables can contain blank lines and comments surrounded by /* and */ (typical c-style comments). Comments must either be on a blank line, or come after the last comma in an escape definition. Do not use commas in comments. Also, all fields (including numbers, but excluding defaults and COMMAND mnemonics) must be right-aligned by columns. Please note that every line that contains an escape definition MUST end with a comma even if it is the last line of the file. For examples see the provided .T files.

Meaning of the individual fields common to all tables:

< default >

This field contains the dafault value for the arguments in the corresponding command sequence. Note that since there is only one dafulat value, all arguments in the command sequence would be set to the same default value if they are ommitted in the command sequence. To provide several default values, see section on Processing Nonstandard Commands.

< command >

This is a VT420 command mnemonic. The mnemonics can be found in VTCMND.H.


These files define escape sequences with the < final character > coming immediately after the escape character.

The fields are: < final character >, < default >, < command >,

Example: '\157', 3, DO_LS3, /* o */
Description: command DO_LS3 is assigned to the final character '\157' with the default parameter being 3.
Will be triggered by: ESC o

Note: Since there sequences to do not accept arguments, default will always be the parameter passed.


This file defines escape sequences that consist of exactly two characters coming after the escape character (< intermediate character > and < final character >).

The fields are: < intermediate character >, < final character >, < default >, < command >,

Example: '#', '8', 0, DO_DECALN,
Description: command DO_DECALN is assigned to the combination of intermediate character '#'and final character '\157' with the default parameter being 0.
Will be triggered by: ESC # 8

Note: Since there sequences to do not accept arguments, default will always be the parameter passed.


This file defines CSI sequences (sequences that start with CSI or ESC [).

The fields are: < final character >, < flag >, < arg >, < default >, < command >,

Example 1: 'h', 0x0001, 6, 1, DO_DECOM,
Description: command DO_DECOM is assigned to the combination of flag '?'and final character 'h' with arg 6 and (default) parameter being 0.
Will be triggered by: CSI ? 6 h or CSI 6 ? h

Example 2: 'q', 0x0100, 1899, 0, DO_DECELF,
Description: command DO_DECELF is assigned to the combination of flag '+'and final character 'q' that takes groups of 2 arguments (arg = 1899), each of which, if ommitted, is defaulted to 0.
Will be triggered by: CSI + 1 ; 2 ; 2 ; 0 q is equivalent to CSI + 1 ; 2 q CSI + 2 q

Here the < final character > is the ASCII code of the final character. The <flag> is a bitwise combination of flags as defined in the second table in VTTABLE.C.

< arg >:


This file defines DCS sequences that are processed by the DCS-processing functions.

The fields are: < final character >, < flag >, < dcs-processing function's name >,

Example: 'u', 0x0004, Process_DECAUPSS,
Description: function Process_DECAUPSS is to process DCS functions with flag '!'and final character 'u'.
Will be triggered by: DCS ! arguments u arguments-to-DCS

Special Note: DO__DIRECT is an internal for the parser command that stands for VT52's Direct Cursor Positioning command. If it is present among the escape sequence definitions, it can only be in VTE1xxxx.T files.

Writing DCS-Processing Functions:

If you will be adding the processing for the new DCS sequences, you will need to create your function to conform to DCS-processing protocol.

Because of the little similarity among the data strings of different DCS commands, each one requires a separate function to be parsed. Here is an overview of the DCS protocol used by this parser. To be know as a DCS-compliant function, the function must:

  1. set curdcs field of PS block to itself

  2. be able to process calls to itself with pendingstate field of PS set to STTERM and NONSTTERM.

The DCS-complaint functions are called with pendingstate field of STTERM when ST character has been encountered by getNextChar or ProcessESC, and pendingstate field of NONSTTERM when the parsing of the DCS string has to terminate by any other reasons (CAN, SUB, CSI commands, for example). When an STTERM call is made, the last character in the PS buffer pendingstr[pendingpos-1] is CHAR_ST no matter whether ST has been received simply as ST or its 7-bit equivalent pair.

If your DCS-Processing function is not DCS-compliant (that is, it does not set curdcs to itself), it will not be called when the DCS string processing will have to terminate (by STTERM or NONSTTERM). Instead, it will be aborted just as any ESC or CSI-processing functions would be. This, of course, might be the desired behavior.

In any case, do not forget to add an entry about your function to VTDCS.T and build VTDCS.TBL.

Processing Unusual And Nonstandard Commands:

Extra Compatibility Scheme:

This parser is written and the .T files are distributed with the Extra Compatibility scheme in mind. This scheme means that in any VT terminal modes, the parser will understand and correctly parse escape sequences particular to the other terminal modes, unless they conflict with the mode's native sequences. This is meant for the maximum compatibility with the poorly written programs the application might have to communicate with. For example, there are no CSI sequences in the native VT52 mode, and ESC A is the only way to express "cursor up." However, the parser will correctly interpret CSI A as "cursor up" (ANSI's way of moving cursor up) even in VT52 mode. Conversely, ESC Y is defined only in VT52 and means as direct cursor positioning command. However, if ESC Y is encountered in VT420 mode, it still will be interpreted as direct cursor positioning, even though formal VT420 specification does not define ESC Y to do anything.

Nonstandard Commands Supported by the Parser:

A few commands understood by this parser are not standard VT commands. However, a few terminal programs do use them. Theses are the commands that allow the remote host to control the file system of the terminal. These commands are XTRANS, XRECEIVE, XAPPEND, and XSAVE. In addition to these, there are some commands (one command and two terminal responses) unique to this parser. They are XSUPP (command) and XOK with XERROR (responses). Please, refer to VTCMND.H for a detailed description of each command.

Compiling in the Debugging Mode:

When the parser is compiled in the debugging mode, it provides some additional tests of the integrity of the code and the tables. If an error is found, DO_VERR command is passed to ProcessAnsi and iArgs[0] is set to the error code. A list of error codes is found in VTCMND.H. The debugging code is compiled if _DEBUG or _PA_DEBUG symbols are defined.

Using the Debug Shell (SHELL.C):

SHELL.C is a debugging tool that can be used to test the parser's functionality on a known VT420 data stream or to test the VT420 data stream itself.

SHELL.C accepts its input from the standard input and outputs it to the standard output. Therefore, it can be used with the operating system's pipe and redirection of input/output mechanisms. To introduce a hold for a few calls to ProcessAnsi put a character with ASCII code 254 into the data stream. The terminating character for SHELL.C is a character with the ASCII value of 255. Function ProcessAnsi prints out a character if a character is received or announces that a function is received and shows its value, mnemonic, and the contents of iArgs array.

Compiling Parser Applications:

The very first time before you compile VTESCSEQ.C, and every time you change any of the .T files, you will need to run MAKETBL.BAT to create .TBL files out of the .T files.

Also, the very first time before you compile SHALL.C, and every time you change VTCMND.H file, you will need to run MAKENAME.BAT to create VTDEBUG.TBL from VTCMND.H.

For more information about video terminal products, I would recommend browsing an archive maintained by Richard Shuford.

Please contact DOS and Windows Development Group ( with bug reports or any comments pertinent to this program.