wntinc.txt draft-5 930902/WNB The Newstar table compiler WNTINC --------------------------------- 1. Introduction WNTINC is a replacement for WNTAB. The major changes are based on comments/remarks made by JPH and MdV, and on deficiencies found by myself. It has been rewritten to make it more modular and to get rid of any non-described numerical codes. Main features: - calculation on local variables - multiple structure definitions - structure definitions inside DEFINE - structures in data statements - implicit array lengths - implicit string lengths - alignment possibilities - map/union options (not implemented in this version yet) - deletion of some unused options - complete C coverage - continuation lines An example of the use can be found in wnt.dsc 2. Input structure The input file to WNTINC is a NAME.dsc file. The parameter to WNTINC is NAME, possibly modified by a directory indication. Whatever the case of NAME, it will be assumed to reference a lc NAME.dsc. All input lines will be converted to UC, unless enclosed in "". The output names will all be UC for Fortran and Unix parameters; lc for Unix variable names. Blanks in the following indicate 'white space' (i.e. in general spaces and/or tabs) NAME.dsc will consist of a number of lines. Each line consists of a (possibly empty) command part, followed by an optional comment part which should be preceded with an !. A line can be continued by having the last non-blank character in the command part to be a '\'. An empty line will be considered to be a comment line; a comment not starting at the beginning of the line will be considered to be a continuation of the previous line (whether '\' present or not. (This is to distinguish comments that should precede fields from comments that should follow fields)). Each command can be: - empty (i.e. comment line only) can occur everywhere - the first non-blank character a '%': commands that steer the behaviour of the compiling process can occur everywhere - the first non-blank character a '.': commands that steer the data interpretation process can occur only in 'data-blocks'; except .DEFINE: can occur only once outside a data-block; .STRUCTURE (.BEGIN) that can occur inside and outside data-blocks and which define the start of data-blocks; .PARAMETER that can occur everywhere - data command (starts always with a '-' (dummy name)) or alphabetic character 3. Output files WNTINC produces the following output files (NAME is the input file name name, or set by the %NAME) (all filenames in lc): a. If .STRUCTURE type data blocks present: - NAME_o.def Fortran include file containing parameters and/or comments and/or 'structure-type' definitions - NAME_o.inc C include file containing parameters and/or comments and/or structure definitions - NAME_t.def Fortran include file containing information for translating data structures from one representation to another (using WNTT* routines) - NAME_t.inc C include file - NAME_e.def Fortran include file containing information for formatted printout and/or input of data structures - NAME_e.inc C include file b. If a .DEFINE data block present, or if no .STRUCTURE and no .DEFINE type present: - NAME.def Fortran include file containing comments, parameters (if no _o present) and/or common blocks and/or data definitions - NAME.inc C include file containing the same - NAME_bd.for Common block data-initialisation (if necessary) d. Always: NAME.LIS describing: - the input lines - the offset in and structure of common blocks and data structures. 4. Comment lines Commment outside data blocks will be considered to be comments for the .dsc file only. Comments inside data blocks will form part of the program output. Lines starting with a ! will be output proceeding the data items following. Other comments will always follow the data items they follow. 5. % commands %name commands steer the compiling process. Some action may be dependent on wether it is inside or outside data blocks. The following commands are recognized: %NAME=string name of output files to be used. Default: input file name %DATE=yymmdd date of producing output Default: today %USER=name name of user Default: login name %VERSION=num Current version Default: 1 %SYSTEM=num Current system Default;1 %%NAME will show currently defined name %%DATE .. date %%USER .. user %%VERSION .. version %%SYSTEM .. system If more than one of the above commands are encountered, the last will be used %[NO]LIST list lines in log (e.g. to suppress include file listing) Default: LIST %[NO]PRINT list comments in output (not fully implemented) Default: print %[NO]ALIGN align data items on their lengths (complex data on their constituant length; structure on the largest element length included in the structure) The above act as switches %INSERT=string include specified file %INCLUDE=string include specified file As a rule the string will be of the form NAME_DSF, referencing an include file name.dsf The above are identical %COMMENT=string include specified comment at begin of output file %REVISION=nam=yymmdd=string include specified comment as a revision %FORTRAN=string include the Fortran statement (e.g. IMPLICIT NONE). If outside data block: at begin of output; if inside: at end of output %CC=string include the C statement The above act additive %LOCAL=name=expr specify a local variable name with a value expr. The value of the name can be an integer value, or a character string. If the expr can be evaluated to an integer constant it will have an integer value, else a character string value. In most places were information has to be supplied it can be supplied as: - integer expression: containing known variable names, integer constants (), +-*/, +- unary - character expression: single known name with a character value - string (anything that cannot be interpreted as one of the above) Note: an expression starting with a ( will be deemed to have been ended at the belonging ). This is for some formatting reason. Note: / is only recognised if not preceded and or followed by blanks. This is to recognize the /../ initialisation Examples: 2. is string "2." 01 is value 1 (and string "1" if appropiate) (1)*2 is string "(1)*2" +(1)*2 is value 2 ("2" string) %GLOBAL=name=expr identical to the combination: %LOCAL=name=expr .PARAMETER name tp /expr/ where tp is either J or C(length expr) 6. . commands . commands define some aspects of the data commands present. Recognized: .END ends blocks starting with .STRUCTURE, .DEFINE, or .MAP .DEFINE starts a 'define-block' Can only occur once outside a data block (define- or struct-block). The sub-type will initially be data .STRUCTURE[=sname] starts a structure block with name sname or NAME can occur inside or outside a define-block. Many structure blocks are allowed, but they may not be nested (there references (see S:) may, of course, be nested. Each structure block should have a unique name (i.e. only one unnamed allowed). The sub-type will initially be data .BEGIN[=sname] identical to .STRUCTURE (for historical reasons) The above define the type of current data block. It will define the output files produced, and which sub-types are allowed. .[OFFSET]=nexpr will define a current offset Only for structure-blocks; assumed to be in data-sub For define-blocks allowed in common-sub .ALIGN=nexpr Align offset on specified lengths (note the program knows the defined local variables LB_B etc) Allowed in common-sub en structure data-sub .MAP[=nexpr] will start equivalence structures .UNION[=nexpr] will start the next structure to be equivalent The nexpr will serve as an id that can be used in the WNT translation tables to get the proper translation of the data; and is used to generate a name for C. Definition ends at .END Can only be used in structure-blocks at data-sub Note: Not implemented yet, but its action can be made by the equivalence = (except for the translation choice option) .PARAMETER Interprets following data lines as parameters .DATA Interprets following lines as data .COMMON[=cname] Interprets following lines as to belong to common cname_COM (or NAME_COM) Only in define-block 7. Data commands A data command describes a data-item. It consists of two mandatory fields separated by blanks, and an optional (obligatory for parameters and implied lengths) initialisation and an optional editing field (only allowed for structure data-sub). A full command is: name[=rnam] type [/init, ..../] [] Name can be "-" to indicate a dummy name (to be used for filling) or a name starting with an alphabetic (including _$) character and having only alphanumeric characters (including _$). The name can be followed with an '=' followed by a reference name (not valid for parameter data). The data will be put at the same offset as the data at the reference name. Limitations: - rnam should immediately precede name in the same sub-block, i.e. all names referencing the same rnam should be continuous after rnam - name should describe an entity not larger than the entity of rnam - if in ALIGN mode, the alignment of name should be of the same or lesser value than that of rnam Type describes the data entity. It consists of a type indicator, optionally followed by an array definition. The indicator can be: - B I1 byte I I2 integer*2 J I4 integer*4 K long integer (for now identical to J) E R4 real*4 D R8 real*8 X complex*8 Y complex*16 A double length ASCII Cnexpr character*(nexpr) C* character*(*) (length from initialisation string; hence only allowed for parameters and data in common-sub or define data-sub S:name structure as defined by name A:[([start][,inc])] enumeration(add). If in a data-type mode in define-block, it will generate a character string array with an implied length from the initialisation data, containing the strings provided and a final ' ' string. This variable can then be used in e.g. WNCAFU to do a minimax search for its occurrence. In addition (and in all other cases only) it will produce a series of parameters consisting of pre_txt with values starting at start and incrementing with inc, where the txt is the first three (or less if not existing) characters of the strings, and pre__N will be defined to give the number of values+1; pre__I the increment and pre__L and pre__H the lowest and highest values. The pre__* will also be available as local variables. Default start, inc: 1 E.g.: cb E: /structure,define,end/ will produce: CHARACTER*(10) CB__TXT(4) DATA CB__TXT/'STRUCTURE','DEFINE','END',' '/ INTEGER CB_STR,CB_DEF,CB_END,CB__N, CB__I,CB__H,CB__L PARAMETER(CB_STR=1,CB_DEF=2,CB_END=3, CB__N=4,CB__I=1,CB__L=1,CB__H=3) AR:[([start][,inc])] as A:, but the parameter names will be *_pre M:[([start][,fac])] enumeration(mul). As A:, but multiplicative rather than additive. Default start, fac: 1, 2 MR:[([start][,fac])] as M:, but *_pre parameters N:[(val,...)] enumeration(named). As A:, but values are specified (up to number of array indices allowed, currently 16). Default val: 1,2,3,... Note: No __H,__L and __I produced NR:[(val,...)] as N:, but *_pre parameters [A|M|N][R][F][*]:[...] as A: M: or N:, but Reversed name_ if R present, full name (rather than 3 first characters) if F present, no __ names and text if * present. Array specification: (nexpr[:nexpr],....) The last index (i.e. the high-bound) can be specified as '*' to indicate an implied length to be deduced from the initialisation string (if this was allowed). All format types except A:, M: and N: can have an array index. Initialisation data: /init, .../ each init can be an expression, or (nexpr)init. In the latter case the (nexpr) gives a repeat factor. If the format was character and the string contains blanks, ',' '/' or anything that can be but should not be interpreted as an expression (e.g. '02' which may not be converted to '2'), or is case sensitive, it should be enclosed in "". Edit data: Each field may be omitted, trailing ',' may be omitted. format: WNCTXT (WNCTXI) type format (e.g. AEF12.6) Default: deduced from item code: 0: editing of field allowed, >0: not allowed Default: 0 units: string specifying units (e.g. "deg") Default: " " special: string to indicate something special defined by user of edit data (e.g. if formatting types are not sufficient, e.g. to type interferometer names) Default: " " The special field is used for S: fields, the default will be "S:NAME". By definition the user can put anything in it. The only definition I have now is: "D:NAME" for a field containing a disk pointer to to a structure NAME. The editing routine will be extended to recognise these special codes. 8. Program changes, omissions The following features are not fully implemented yet: - initialisation of structures (relatively easy, will do soon) - MAP/UNION: the = feature caters for everything except the run-time choice of translation table. This last feature is probably dangerous anyway. If the need arises, easily to implement. - C: I have only tested that the .inc files look ok, and are all accepted by the C compilers. The following existing programs need changes: - ncomp/ndel.ssc: to change to WNTINC: done - no _m.mvx output: use existing ones by preserving them. If the f??.dsc files change, the .mvx has to change. However, the DECalpha has a different assembler from the VAX, and changes are necessary anyway in the existing Macro programs (i.e. the I/O routines). I have done the preservation, and will look at changing the Macro programs to Fortran. - no .RECORD: it has been enhanced by the S: data item: scw.dsc and ohw.dsc uses this: change done - output now _o.inc rather than -c.inc to get uniform naming: wnf I/O routines have to change: done 9. Detailed program output The output of the program consist of: - parameters - structure definitions - data definitions - common defintions - translation tables - edit tables - Parameters Parameters are output in Fortran as PARAMETER, with name and type as given. In C as #define NAME init-text Note: Maybe they should be given as: #define NAME (cast) init-text ?? comments please For A:, M:, N: type the following INTEGER PARAMETERs are produced: NAME__N # of items in list +1 (==first available element). Also available as local variable NAME__L First value (not for N:) NAME__H Last value (not for N:) NAME__I Increment(A:) or factor(M:) NAME_txt For each non-empty init-txt (i.e. not ,, or ,/) the first 3 char of the text (or less if shorter text) are taken as txt. - Structure definitions Structure definitions are given in C as: struct struct-name { type name [indices]; ,,,}; All names in lc; indices in reversed order from Fortran. In Fortran each given name is combined with the struct-name sname to produce the following INTEGER PARAMETERs: SNAME__L Byte length of structure SNAME__V Version SNAME__S System In the edit output: SNAME__EL Length of edit arrays The above are also available as %LOCAL constants For historic reasons also available: snameHDL snameHDV snameHDS snameEDL For all structure elements: SNAME_NAME_1 Byte offset from start of structure In addition for CHARACTER data: SNAME_NAME_N Length in characters for STRUCTURE data: SNAME_NAME_N Length in bytes for all if the offset from the beginning is an integer multiple of the unit size of the data type (e.g. LB_J=4 for INTEGER; structure length for structure): SNAME_NAME_type Offset in unit-length units from start of structure. Types are the types as given in the definition (C,J,E,Y,S etc) Automatic formatting of data structures --------------------------------------- (contributed 941010 by JPH, based on research and correspondence with WNB) WNTINC copies the edit directives in .DSC literally to _E_DEF. The directives are not interpreted, so they may have any form; double quotes can be used to include blanks etc.". They must fit, however, in elements of the CHARACTER array declared in the latter file. The declaration is written by WNTIOS through WNCTXT calls. On 941010 the length has been increased fro 10 to 12 characters. The directives are read and interpreted by NSCXXS. This routine imposes some formatting constraints and defaults of its own. See the comments in that file.