ETC RA17K

USER'S MANUAL
DOC17K
DOCUMENT PROCESSOR
(PRELIMINARY)
©
1995
Document No. EEU-1536
(O. D. No. EEU-5006)
Date Published May 1995 P
Printed in Japan
SIMPLEHOST and emlC-17K are trademarks of NEC Corporation.
MS-DOS is a trademark of Microsoft Corporation.
PC/AT and PC DOS are trademarks of IBM Corporation.
The information contained in this document is being issued in advance of the production cycle for the
device. The parameters for the device may change before final production or NEC Corporation, at its
own discretion, may withdraw the device prior to its production.
No part of this document may be copied or reproduced in any form or by any means without the prior written
consent of NEC Corporation. NEC Corporation assumes no responsibility for any errors which may appear in
this document.
NEC Corporation does not assume any liability for infringement of patents, copyrights or other intellectual
property rights of third parties by or arising from use of a device described herein or any other liability arising
from use of such device. No license, either express, implied or otherwise, is granted under any patents,
copyrights or other intellectual property rights of NEC Corporation or of others.
Preface
Product Outline:
The Document Processor (DOC17K) extracts program information from 17K Series relocatable
assembler (RA17K) or C compiler (emlC-17KTM) source programs and documents the
information in a specified format.
Audience:
This manual is aimed at those engineers who use RA17K or emlC-17K to develop application
systems based on the 17K Series 4-bit single-chip microcontroller.
Organization:
This manual consists of the following chapters:
General
Running the Document Processor
Types of Output Listings and Options
Output Listings
Error Messages
Reading This Manual:
The reader is assumed to be familiar with the concepts of RA17K or emlC-17K.
Conventions:
In this manual, the following symbols are used:
...
: Indicates repetition.
[]
: Elements in brackets are optional.
{|}
: One of the characters or character strings, delimited by ”|” in braces,
must be selected.
<>
: The actual characters enclosed in the angular brackets are to be
specified; often used to indicate a title.
CR
: Carriage return.
LF
: Line feed.
TAB
: Horizontal tab.
xxx
: Any character string.
Single-byte
: Single-byte character.
Double-byte(Note) : Double-byte character.
(Note) Only the PC-9800 version supports double-byte characters.
File Naming Conventions:
[drive-name:][\directory-name\…]filename[.extension]
A filename includes a drive name and a directory name. A drive name and directory
name together constitute a pathname.
Related Documents:
Note that these related documents may be preliminary editions. These documents are
not marked ”Preliminary” in this manual.
• Documents related to software tools
Project Manager Version 1.00 User’s Manual : To be released soon
RA17K User’s Manual
: To be released soon
RA17K Utility User’s Manual
: To be released soon
LK17K User’s Manual
: To be released soon
emlC-17K Version 1.00 User’s Manual
: EEU-1427
DOC17K User’s Manual
: This manual
• Documents related to SIMPLEHOSTTM
SIMPLEHOST Version 2.0 corresponding to emlC-17K/RA17K
User’s Manual, Tutorial: To be released soon
SIMPLEHOST Version 2.0 corresponding to emlC-17K/RA17K
User’s Manual, Reference: To be released soon
The software package may contain a README.DOC file. The README.DOC file
provides information that was not available when the manual was printed. Always
read the contents of the README.DOC file before attempting to use the product.
Contents
Chapter 1
General ..............................................................................1-1
1.1
Configuration ........................................................................1-1
1.2
Outline of Functions ............................................................1-2
1.3
System Configuration ..........................................................1-3
1.3.1
Chapter 2
1.4
Operating Environment .......................................................1-5
1.5
Environmental Variable .......................................................1-5
1.6
Limitations .............................................................................1-6
Running the Document Processor ..............................2-1
2.1
Execution ...............................................................................2-1
2.1.1
2.1.2
2.1.3
Chapter 3
Execution Procedure ...................................................................2-1
Sample Runs ................................................................................2-3
Sample Runs without Parameters .............................................2-5
2.2
Start and End Messages ...................................................2-16
2.3
Cancellation (CTRL + C) ...................................................2-17
Supported Output Listings and Options ..................3-11
3.1
Options ...................................................................................3-1
3.1.1
3.1.2
3.1.3
Chapter 4
Files That Are Referenced or Created ......................................1-4
Options That Specify a Listing Utility ........................................3-2
Options Common to All Listing Utilities .....................................3-4
Listing-Specific Options ..............................................................3-6
Output Listing ..................................................................4-1
4.1
Option Information Listing .................................................4-1
4.2
Absolute Address Format Listing .....................................4-3
4.3
Cross-Reference Listing .....................................................4-7
4.3.1
4.3.2
4.4
Module Map and Program Map Listings ........................4-13
4.4.1
4.4.2
DOC17K User's Manual
Embedded Cross-References.....................................................4-7
Table Cross-References .............................................................4-9
Map Listings ...............................................................................4-13
Symbol Listing ............................................................................4-18
TOC - 1
Contents
4.5
Report Listing .....................................................................4-20
4.6
Document Listing ...............................................................4-24
4.6.1
4.6.2
4.6.3
Chapter 5
Document Listing .......................................................................4-24
Summary Rules..........................................................................4-28
Format Definition .......................................................................4-33
4.7
Call Tree Listing .................................................................4-39
4.8
Module Listing ....................................................................4-40
4.9
Address Map .......................................................................4-42
Error Messages ...............................................................5-1
5.1 Error Handling ..........................................................................5-1
5.2 Error Messages ........................................................................5-1
5.3 System Error Messages .........................................................5-6
TOC - 2
DOC17K User's Manual
List of Figures
(1/1)
Figure 1-1.
Figure 1-2.
DOC17K Functions ..................................................................................................1-1
DOC17K System Configuration ..............................................................................1-3
Figure
Figure
Figure
Figure
3-1.
3-2.
3-3.
3-4.
Report Listing Output Format (Default) ...............................................................3-13
Document Listing Output Format (Default) ..........................................................3-14
Module Listing Output Format (Default) ..............................................................3-16
Address Map Output Format .................................................................................3-16
Figure 4-1.
Figure 4-2.
Figure 4-3.
Sample Memory Map Listing ................................................................................4-14
Representation of a Data Memory Map Greater than One ...............................4-15
Summary Layout ....................................................................................................4-29
DOC17K User's Manual
TOC - 3
Contents
[MEMO]
TOC - 4
DOC17K User's Manual
List of Tables
(1/1)
Table 2-1.
Listing Utilities ..........................................................................................................2-1
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Types of Output Listings and Options ...................................................................3-1
Options That Specify a Listing Utility .....................................................................3-2
Input Files Required to Enable Listing Output ......................................................3-3
Input File Extensions ...............................................................................................3-4
Options That Are Common to All Listing Utilities .................................................3-4
-TAB Option Settings ...............................................................................................3-5
-FORM Option Settings ...........................................................................................3-5
-HEAD Option Settings ............................................................................................3-6
Absolute Address Format Listing Options .............................................................3-6
-GEN Option Settings ..............................................................................................3-7
-COND Option Settings ...........................................................................................3-7
-SEQ Option Settings ..............................................................................................3-7
-BRANCH Option Settings ......................................................................................3-8
Module Map Listing and Program Map Listing Options .......................................3-8
-AXIS Option Settings ..............................................................................................3-9
-LINEKIND Option Settings .....................................................................................3-9
-LINEKIND Option Settings (Detailed Settings) ..................................................3-10
-SEPARATE Option Settings ................................................................................3-10
-SORT Option Settings ..........................................................................................3-11
Cross-Reference Listing Option............................................................................3-12
-XFORM Option Settings .......................................................................................3-12
Report Listing Option .............................................................................................3-12
Document Listing Options .....................................................................................3-13
Call Tree Listing Option .........................................................................................3-15
Module Listing Options ..........................................................................................3-15
3-1.
3-2.
3-3.
3-4.
3-5.
3-6.
3-7.
3-8.
3-9.
3-10.
3-11.
3-12.
3-13.
3-14.
3-15.
3-16.
3-17.
3-18.
3-19.
3-20.
3-21.
3-22.
3-23.
3-24.
3-25.
Table 4-1.
Table 4-2.
Relationship Between Components of Contents and Program Units ...............4-25
Reserved Item Names in the Format Definition File ..........................................4-34
Table 5-1.
Error Messages ........................................................................................................5-2
DOC17K User's Manual
TOC - 5
Contents
[MEMO]
TOC - 6
DOC17K User's Manual
Chapter 1
General
The Document Processor (DOC17K) extracts program information from relocatable assembler
(RA17K) or C compiler (emlC-17K) source programs and documents the information in
a specified format.
1.1 Configuration
The multi-functional Document Processor consists of several sets of utilities and programs
that manage these utilities.
Figure 1-1. DOC17K Functions
DOC17K Document Processor
Document generation functions
: Document listing utility
SPEC17K
: Module listing utility
MOD17K
TREE17K(Note) : Call tree listing utility
Report writing function
REP17K: Report listing utility
Cross-reference generation functions
XREF17K : Cross-reference listing utility
PUB17K : Public cross-reference listing
utility
Memory map generation functions
MAP17K : Module map listing utility
AMAP17K: Program map listing utility
MOD17K : Address map output
(produced with the module
listing utility)
(Note) Available only when emlC-17K is used.
DOC17K User's Manual
1-1
Chapter 1
General
1.2 Outline of Functions
The Document Processor provides the following functions:
(1) Document generation
The Document Processor produces the following document components:
(a) Contents
The titles assigned to all blocks are output as a table of contents.
(b) Program specifications
Module (including routine) information in a summary format.
(c) Module listing
A listing of each module file and its routines.
(d) Module configuration
A call tree listing (supported only when emlC-17K is being used).
(2) Cross-reference (symbol cross-reference) generation
The Document Processor can produce two kinds of listing:
module-specific cross-reference listings and program public symbol cross-reference
listings.
(3) Memory map generation
(a) Memory map/flag map
The Document Processor can produce two kinds of maps:
module-specific memory maps and program memory maps.
(b) Symbol list
(4) Report writing function
(a) Listing file reformatting
(b) Report (log file) reformatting
1-2
DOC17K User's Manual
Chapter 1
General
1.3 System Configuration
Figure 1-2 shows the configuration of the DOC17K system.
Figure 1-2. DOC17K System Configuration
Source file
Device file
emlC-17K
(C compiler)
RA17K
(Relocatable assembler)
REL file
(.REL)
Intermediate PRN file (.IPN)
XREF data file (.IXF)
Summary file (.SUM)
Log file (.LOG)
Preprocessing file (.PPL)
XREF data file (.IXF)
Summary file (.SUM)
Log file (.LOG)
LK17
(Linker)
LNK file
(.LNK)
DOC17K
(Document processor)
Absolute address format listing Cross-reference listing (.XRF)
(.PRN) –> Output with LIST17K –> Output with XREF17K
Public cross-reference listing (.PUB)
–> Output with PUB17K
Report listing (.REP)
–> Output with REP17K
Program map list (.AMP)
–> Output with AMAP17K
Module listing (.MOD)
–> Output with MOD17K
Call tree listing (.TRE)
–> Output with TREE17K
available only when emlC-17K
is used.
DOC17K User's Manual
Document listing (.SPC)
–> Output with SPEC17K
Module map listing (.MAP)
–> Output with MAP17K
1-3
Chapter 1
General
1.3.1 Files That Are Referenced or Created
(1) Files that are referenced
(a) REL file (.REL)
A file of relocatable object codes and assembly (or compilation) information,
produced by RA17K or emlC-17K.
A LNK file (.LNK) must be specified at the same time, by specifying the -LNK
option.
(b) Log file (.LOG)
A file recording the messages output by RA17K or emlC-17K upon assembly or
compilation.
(c) Intermediate PRN file (.IPN)
An assembly result list file produced by RA17K.
(d) Preprocessing file (.PPL)
A precompilation result list file produced by emlC-17K.
(e) Cross-reference data file (.IXF)
An information file used to produce a symbol cross-reference listing.
(f) Summary file (.SUM)
A file of information defined by a SUMMARY pseudo instruction.
(2) Files that are created
(a) Absolute address format listing (.PRN)
An edited listing, represented in absolute address format, of the contents of an
intermediate PRN file, along with the address and object codes stored in it.
(b) Cross-reference listing (.XRF)
An edited listing of cross-reference information.
(c) Public cross-reference listing (.PUB)
An edited listing of cross-references between the public symbols of a program.
(d) Module map listing (.MAP)
A module-specific data memory map, presented as a table.
(e) Program map listing (.AMP)
A program data memory map, presented as a table.
1-4
DOC17K User's Manual
Chapter 1
General
(f) Report listing (.REP)
Run-time information, produced by RA17K or emlC-17K, presented as a listing.
(g) Document listing (.SPC)
Summary information, and information derived from an intermediate PRN file,
presented as a document.
(h) Call tree listing (.TRE)
A tree listing of all the functions defined and referenced by emlC-17K.
(i)
Module listing (.MOD)
A module file-specific routine listing, which may contain a program address map
if needed.
1.4 Operating Environment
DOC17K requires the operating environment described below:
• Host machine
: NEC PC-9800 Series
IBM PC/ATTM
• OS
: MS-DOSTM Ver.3.30 or higher
PC DOSTM Ver.5.02 or higher
• Main memory
: 640K bytes or more. At least 400K bytes of free memory
is required.
• Extended memory (EMS) : At least 1M byte of extended memory is recommended.
• External storage
: At least 1M byte. (The use of a hard disk is recommended.)
1.5 Environmental Variable
The following environmental variable is used with DOC17K:
TMP: Specifies a temporary file search path. If more than one path is specified, only
that specified first becomes valid.
Paths are used in the following order:
<1> If a work path option (-WORK) is specified, temporary files are created on that path.
<2> If environmental variable TMP is specified, temporary files are created on that path.
<3> If neither <1> nor <2> is specified, temporary files are created on the current path.
DOC17K User's Manual
1-5
Chapter 1
General
1.6 Limitations
The limitations imposed on DOC17K are summarized below:
(1) Utilities other than MAP17K support up to 8,000 symbols. MAP17K supports up to
6,000 symbols for each data memory bank of the device (17K Series). If EMS memory
is available, a symbol area is allocated in EMS memory; otherwise, it is allocated in
main memory. When EMS memory is not available, the number of symbols supported
is limited by the amount of free main memory.
(2) During list processing, a work area is allocated as needed. The size of the allocated
work area depends on the number of symbols to be processed. The size of the work
area that can be allocated is limited by the amount of free main memory in the host.
1-6
DOC17K User's Manual
Chapter 2
Running the Document Processor
2.1 Execution
The Document Processor runs the individual listing utilities for which options have been
specified. Run the Document Processor (DOC17K) to produce all the listings at one
time.
The listing utilities may also be run independently.
2.1.1 Execution Procedure
(1) Command
• Running DOC17K
>DOC17K[.EXE]<module-name>-LNK=<link-filename>[-<option>...]
• Running listing utilities independently
>xxx17K[.EXE]<module-name>-LNK=<link-filename>[-<option>...]
Table 2-1 lists the listing utilities and indicates the order in which they are excuted by
DOC17K.
Table 2-1. Listing Utilities
Name
Description
LIST17K
Absolute address format listing utility
1
XREF17K
Cross-reference listing utility
2
PUB17K
Public cross-reference listing utility
3
MAP17K
Module map listing utility
4
AMAP17K
Program map listing utility
5
REP17K
Report listing utility
6
SPEC17K
Document listing utility
7
MOD17K
Module listing utility
8
TREE17K
Call tree listing utility
9
DOC17K User's Manual
Execution order
2-1
Chapter 2
Running the Document Processor
(a) module-name
Specify the REL filename(Note) (.REL) of a module to be output.
To name more than one module, specify a parameter file containing a list of
modules.
Code a parameter file in ‘@filename’ format, along with any extension.
Each module name appearing in the parameter file must also be a REL filename.
(Note)
For TREE17K, specify the filename of a preprocessing file (.PPL) produced by
emlC-17K, not a REL filename.
(b) link-filename
Specify the filename of the link object file (.LNK) containing the module to which
information is to be directed.
(c) option
Specify listing options as necessary. Which options are valid varies with the
listings.
If more than one module name is specified, the option(s) specified here applies
to all the specified modules.
To produce the same listing but with different options, execute a listing utility for
each module involved.
Options may also be specified in the parameter file. Any options specified in the
parameter file are overridden, however, by options specified from the command
line. Options can be altered, therefore, simply by specifying the initial options,
without having to modify the parameter file.
(2) Parameter file format
Options and a REL filename can be written in the parameter file.
The options must precede the REL filename. Otherwise, an error will occur.
When the same option is coded more than once, that coded last becomes effective.
A character string beginning with semicolon (;) is handled as a comment.
Example
; options
-LNK=SAMPLE.LNK -LIST -COL=128 ; listing
-LNK=SAMPLE.LNK -MAP -AXIS=R
; map listing
; REL filename
SAMPLE1.REL
SAMPLE2.REL
2-2
DOC17K User's Manual
Chapter 2
Running the Document Processor
(3) Listing output destination specification
There are two ways of specifying the destination to which listings are to be directed.
When more than one module is named, if a filename is not specified as a listing
option, module-specific listings are produced. Therefore, always specify an output
filename when lists are to be directed to one file.
(i) When the filename is omitted
If a single module is named, an output file having the REL filename as its filename
is produced.
If more than one module is named in the parameter file, an output file is produced
for each named module if the filename following the options is omitted. Program
map and public cross-reference listings, however, are directed to the single file
named ”module-name.extension.” If a single module is named, or to a single file
named ”parameter-file.extension” if more than one module is named.
(ii) When the filename is specified
When ”=filename” is specified after the listing options, all output listings are
directed to the named file, regardless of whether a single module or more than
one module has been named.
2.1.2 Sample Runs
(1) DOC17K sample runs
(a) Single-module specification
>DOC17K SAMPLE1.REL -LNK=SAMPLE1.LNK -LIST -MAP -XREF
SAMPLE1.PRN, SAMPLE1.MAP, and SAMPLE1.XRF are produced.
(b) Multi-module specification
Assume that a parameter file, named SAMPLE.INP, contains a list of module
names (SAMPLE1.REL, SAMPLE2.REL).
>DOC17K @SAMPLE.INP -LNK=SAMPLE.LNK -LIST - MAP -XREF
Listings are produced for each module specified by SAMPLE.INP.
SAMPLE1.PRN, SAMPLE1.MAP, SAMPLE1.XRF, SAMPLE2.PRN, SAMPLE2.MAP,
and SAMPLE2.XRF are produced.
DOC17K User's Manual
2-3
Chapter 2
Running the Document Processor
(2) Listing utility sample runs
(a) Single-module specification
>LIST17K SAMPLE1.REL -LNK=SAMPLE1.REL -COL=128
SAMPLE1.PRN is produced in 128 positions per line.
(b) Multi-module specification and module-specific output
Assume that a parameter file, SAMPLE.INP, contains a list of module names
(SAMPLE1.REL, SAMPLE2.REL) and a link filename (-LNK=SAMPLE.LNK).
>LIST17K @SAMPLE.INP
An absolute address format listing is produced for each module specified by
SAMPLE.INP.
SAMPLE1.PRN and SAMPLE2.PRN are produced.
(c) Multi-module specification and single file output
Assume that a parameter file, named SAMPLE.INP, contains a list of module
names (SAMPLE1.REL, SAMPLE2.REL).
>MAP17K @SMAPLE.INP -LNK=SAMPLE.LNK -MAP=SAMPLE.MAP
A module map listing for each module specified by SAMPLE.INP is output to
SAMPLE.MAP.
Caution
2-4
LIST17K does not support output file specification.
DOC17K User's Manual
Chapter 2
Running the Document Processor
2.1.3 Sample Runs without Parameters
If no parameters are specified (only the EXE filename is entered), control returns to the
DOS prompt and the following HELP messages are displayed:
(1) DOC17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: DOC17K input-file [option[ ...]]
: DOC17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file : Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-LNK=file
-LIS[T]/-NOL[IST]
-XRE[F][=file]/-NOX[REF]
-PUB[XREF][=file]/-NOP[UBXREF]
-MAP[=file]/-NOM[AP]
-AMA[P][=file]/-NOA[MAP]
-REP[ORT][=file]/-NOR[EPORT]
-SPE[C][=file]/-NOSP[EC]
-MOD[ULE][=file]/-NOMO[DULE]
-TRE[E][=file]/-NOTR[EE]
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-GEN/-NOG[EN]
-CON[D]/-NOC[OND]
-SEQ/-NOS[EQ]
-BRA[NCH]/-NOB[RANCH]
-AXI[S]={C|R}
DOC17K User's Manual
:Specify linkage file name.
:Create assemble list / Not.
:Create cross referrence list
[with specified name] / Not.
:Create public cross reference list
[with specified name] / Not.
:Create module memory map list
[with specified name] / Not.
:Create program memory map list
[with specified name] / Not.
:Create report list
[with specified name] / Not.
:Create document list
[with specified name] / Not.
:Create module list
[with specified name] / Not.
:Create tree list
[with specified name] / Not.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify printing generate lines or not.
:Specify printing condition lines or not.
:Specify printing options or not.
:Specify printing label reffer or not.
:Specify axis column or row.
2-5
Chapter 2
Running the Document Processor
-NAM[ELENGTH]=n
-LIN[EKIND]={H|Z}
-SEP[ARATE]={PERIOD|POINT}
-DEL[IMITER]=character
-NRO[W]=n
-NV=character
-NB=character
-STR=character
-SOR[T]=n
-SYM[LENGTH]=n
-LU=character
-LD=character
-RU=character
-RD=character
-UC=character
-DC=character
-LC=character
-RC=character
-CR=character
-XFO[RM]=n
-RFM[T]=file
-SUM[MARY]=’text’, file
-DFM[T]=file
-MAI[N]=function_name
-MFM[T]=file
-PMA[P]
-MLE[N]=n
-RLE[N]=n
:Specify name length.
:Specify line kind.
:Specify separate line period or point.
:Specify delimiter character.
:Specify lines of name.
:Specify nibblev character.
:Specify nibble character.
:Specify structure/union character.
:Specify sorting symbol.
:Specify symbol name length.
:Specify left up corner character.
:Specify left down corner character.
:Specify right up corner character.
:Specify right down corner character.
:Specify up cross character.
:Specify down cross character.
:Specify left cross character.
:Specify right cross character.
:Specify cross character.
:Specify cross referrence list output format.
:Specify report format file name.
:Specify program title and text file name.
:Specify document format file name.
:Specify main function name.
:Specify module format file name.
:Create program map list.
:Specify module name length
:Specify routine name length.
DEFAULT ASSIGNMENT: -LIS -NOX -NOP -NOM -NOA -NOR -NOSP -NOMO -NOTR -ROW=66
-COL=80 -NOTA=8 -NOF -HEA -WOR=current -GEN -CON -NOSE -NOB
-AXI=C -NAM=8 -LIN=H -SEP=PERIOD -DEL = ∗ -NRO=1 -NV=^ -NB=>
-STR=& -SOR=1 -SYM=32 -LU =+ -LD=+ -RU=+ -RD=+ -UC=+ -DC=+
-LC=+ -RC=+ -CR=+ -XFO=0 -MLE=32 -RLE=12
2-6
DOC17K User's Manual
Chapter 2
Running the Document Processor
(2) LIST17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: LIST17K input-file [option[ ...]]
: LIST17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file: Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-LIST[T]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-GEN/-NOG[EN]
-CON[D]/-NOC[OND]
-SEQ/-NOS[EQ]
-BRA[NCH]/-NOB[RANCH]
:Create assemble list.
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify printing generate lines or not.
:Specify printing condition lines or not.
:Specify printing options or not.
:Specify printing label reffer or not.
DEFAULT ASSIGNMENT: -LIS -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current -GEN
-CON -NOS -NOB
DOC17K User's Manual
2-7
Chapter 2
Running the Document Processor
(3) MAP17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: MAP17K input-file [option[ ...]]
: MAP17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file: Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-MAP[=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-AXI[S]={C|R}
-NAM[ELENGTH]=n
-LIN[EKIND]={H\Z}
-SEP[ARATE]={PERIOD\POINT}
-DEL[IMITER]=character
-NRO[W]=n
-NV=character
-NB=character
-STR=character
-SORT=n
-SYM[LENGTH]=n
-LU=character
-LD=character
-RU=character
-RD=character
-UC=character
-DC=character
-LC=character
-RC=character
-CR=character
:Create map list [with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify axis column or row.
:Specify name length.
:Specify line kind.
:Specify separate line period or point.
:Specify delimiter character.
:Specify lines of name.
:Specify nibblev character.
:Specify nibble character.
:Specify structure/union character.
:Specify sorting symbol.
:Specify symbol name length.
:Specify left up corner character.
:Specify left down corner character.
:Specify right up corner character.
:Specify right down corner character.
:Specify up cross character.
:Specify down cross character.
:Specify left cross character.
:Specify right cross character.
:Specify cross character.
DEFAULT ASSIGNMENT: -MAP -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current -AXI=C
-NAM=8 -LIN=H -SEP=PERIOD -DEL = ∗ -NRO=1 -NV=^ -NB=> -STR=&
-SORT=1 -SYM=32 -LU=+ -LD=+ -RU=+ -RD=+ -UC=+ -DC=+ -LC=+
-RC=+ -CR=+
2-8
DOC17K User's Manual
Chapter 2
Running the Document Processor
(4) AMAP17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: AMAP17K input-file [option[ ...]]
: AMAP17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file : Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-AMA[P][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-AXI[S]={C|R}
-NAM[ELENGTH]=n
-LIN[EKIND]={H|Z}
-SEP[ARATE]={PERIOD|POINT}
-DEL[IMITER]=character
-NRO[W]=n
-NV=character
-NB=character
-STR=character
-SOR[T]=n
-SYM[LENGTH]=n
-LU=character
-LD=character
-RU=character
-RD=character
-UC=character
-DC=character
-LC=character
-RC=character
-CR=character
:Create all map list [with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify axis column or row.
:Specify name length.
:Specify line kind.
:Specify separate line period or point.
:Specify delimiter character.
:Specify lines of name.
:Specify nibblev character.
:Specify nibble character.
:Specify structure/union character.
:Specify sorting symbol.
:Specify symbol name length.
:Specify left up corner character.
:Specify left down corner character.
:Specify right up corner character.
:Specify right down corner character.
:Specify up cross character.
:Specify down cross character.
:Specify left cross character.
:Specify right cross character.
:Specify cross character.
DEFAULT ASSIGNMENT: -AMA -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current -AXI=C
-NAM=8 -LIN=H -SEP=PERIOD -DEL = ∗ -NRO=1 -NV=^ -NB=> -STR=&
-SOR=1 -SYM=32 -LU=+ -LD=+ -RU=+ -RD=+ -UC=+ -DC=+ -LC=+
-RC=+ -CR=+
DOC17K User's Manual
2-9
Chapter 2
Running the Document Processor
(5) XREF17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: XREF17K input-file [option[ ...]]
: XREF17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file: Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-XRE[F][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-XFO[RM]=n
:Create cross referrence list
[with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify cross referrence list output format.
DEFAULT ASSIGNMENT: -XRE -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current -XFO=0
2 - 10
DOC17K User's Manual
Chapter 2
Running the Document Processor
(6) PUB17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: PUB17K input-file [option[ ...]]
: PUB17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file : Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-PUB[XREF][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-XFO[RM]=n
:Create public cross referrence list
[with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify public cross referrence list output format.
DEFAULT ASSIGNMENT: -PUB -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current -XFO=0
DOC17K User's Manual
2 - 11
Chapter 2
Running the Document Processor
(7) REP17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: REP17K input-file [option[ ...]]
: REP17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file: Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-REP[ORT][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-RFM[T]=file
:Create report list [with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify format file name.
DEFAULT ASSIGNMENT: -REP -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current
2 - 12
DOC17K User's Manual
Chapter 2
Running the Document Processor
(8) SPEC17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: SPEC17K input-file [option[ ...]]
: SPEC17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file : Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-SPE[C][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-SUM[MARY]=’text’, file
-DFM[T]=file
:Create document list [with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify program title and text file name.
:Specify format file name.
DEFAULT ASSIGNMENT: -SPE -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current
DOC17K User's Manual
2 - 13
Chapter 2
Running the Document Processor
(9) TREE17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: TREE17K input-file [option[ ...]]
: TREE17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file: Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-TRE[E][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-MAI[N]=function_name
:Create call tree list [with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify main function name.
DEFAULT ASSIGNMENT: -TRE -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR=current
2 - 14
DOC17K User's Manual
Chapter 2
Running the Document Processor
(10) MOD17K
17K Series Document Processor Vx. xx [DD MM YY]
Copyright (c) NEC Corporation 1994
usage1
usage2
: MOD17K input-file [option[ ...]]
: MOD17K @input-file [option[ ...]]
input_file : Specify object file name.
@input_file : Specify file name of object file name list.
The option is as follows ([ ] means omissible).
-MOD[ULE][=file]
-LNK=file
-ROW=n
-COL[UMN]=n
-TAB/-NOT[AB][=n]
-FOR[M]/-NOF[ORM]
-HEA[D]/-NOHE[AD]
-WOR[K]=path_name
-MFM[T]=file
-PMA[P]
-MLE[N]=n
-RLE[N]=n
:Create module list [with specified name].
:Specify linkage file name.
:Specify row in a page.
:Specify column in a line.
:Specify tab code or space.
:Specify form feed code or line feed code.
:Specify printing header or not.
:Specify path name for temporary file.
:Specify format file name.
:Create program map list.
:Specify module name length.
:Specify routine name length.
DEFAULT ASSIGNMENT: -MOD -ROW=66 -COL=80 -NOT=8 -NOF -HEA -WOR= current -MLE=32
-RLE=12
DOC17K User's Manual
2 - 15
Chapter 2
Running the Document Processor
2.2 Start and End Messages
The Document Processor issues a normal end message to the standard output when
processing ends normally. It issues an abnormal end message if the processing ends
abnormally.
(1) Start message
17K Series Document Processor Vx.xx [DD MM YY]
Copyright (c) NEC Corporation 1994
- process-name start hh:mm:ss yy/dd/mm -
Remarks 1.
2.
Vx.xx
: Version number
[DD MM YY] : Date when the process was developed
hh:mm:ss
: Time when the program was started
yy/dd/mm
: Date on which the program was started
process-name
Document Processor
: DOC17K
Absolute address format listing : LIST17K
Module map listing
: MAP17K
Program map listing
: AMAP17K
Cross-reference listing
: XREF17K
Public cross-reference listing
: PUB17K
Report listing
: REP17K
Document listing
: SPEC17K
Call tree listing
: TREE17K
Module listing
: MOD17K
(2) End messages
<1> Message output upon normal end
- process-name end hh:mm:ss yy/dd/mm Total error(s) : x Total warning(s) : y
Remark
hh:mm:ss
yy/dd/mm
x
y
:
:
:
:
Time when the program was ended
Date on which the program was ended
Number of errors
Number of warnings
<2> Message output upon abnormal end
- process-name end hh:mm:ss yy/dd/mm Program aborted.
Remark
2 - 16
hh:mm:ss : Time when the program was ended
yy/dd/mm : Date on which the program was ended
DOC17K User's Manual
Chapter 2
Running the Document Processor
2.3 Cancellation (CTRL + C)
The cancellation key sequence (CTRL + C) returns control to the OS, deleting all temporary
files and output files that have been opened.
If BREAK=ON is not defined in the CONFIG.SYS file (the default is BREAK=OFF), the
CTRL + C interrupt is enabled only upon message output and a limited number of other
instances. Consequently, the CTRL + C interrupt may be rejected during listing.
To enable the CTRL + C interrupt during disk access, for example, specify BREAK=ON
in the CONFIG.SYS file. Remember, however, that specifying BREAK=ON has an adverse
affect on processing speed due to the constant monitoring of the CTRL + C interrupt.
DOC17K User's Manual
2 - 17
Chapter 2
Running the Document Processor
[MEMO]
2 - 18
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
DOC17K outputs the listings indicated in Table 3-1
Some listing utilities support the specification of detailed output options. For more information
on these output options, see the description of the options for each listing utility.
Table 3-1. Types of Output Listings and Options
Output listing
Output file extension
DOC17K execution option
Absolute address format listing
.PRN
-LIS[T]
Optional information output
-SEQ
Embedded cross-reference output
-BRA[NCH]
Cross-reference listing
.XRF
-XRE[F]
Public cross-reference listing
.PUB
-PUB[XREF]
Module map listing
.MAP
-MAP
Program map listing
.AMP
-AMA[P]
Report listing
.REP
-REP[ORT]
Document listing
.SPC
-SPE[C]
Module listing
.MOD
-MOD[ULE]
Address map output
Call tree listing
-PMA[P]
.TRE
-TRE[E]
3.1 Options
There are three types of options:
• Options that specify a listing utility
• Options common to all listing utilities
• Listing-specific options
DOC17K User's Manual
3-1
Chapter 3
Supported Output Listings and Options
3.1.1 Options That Specify a Listing Utility
Table 3-2. Options That Specify a Listing Utility
Option name
Default
Explanation
-LNK=filename
–(Note)
Specifies the link object file (.LNK)
produced by the linker (LK17K).
-LIS[T] [=filename]
-NOL[IST]
LIS
Produces an absolute address format
listing.
-XRE[F] [=filename]
-NOX[REF]
NOX
Produces a cross-reference listing.
-PUB[XREF] [=filename]
-NOP[UBXREF]
NOP
Produces a public cross-reference listing.
-MAP[=filename]
-NOM[AP]
NOM
Produces a module map listing (modulespecific data memory map).
-AMA[P] [=filename]
NOA[MAP]
NOA
Produces a program map listing (program data memory map).
-REP[ORT] [=filename]
-NOR[EPORT]
NOR
Produces a report listing
-SPE[C] [=filename]
-NOSP[EC]
NOSP
Produces a document listing.
-MOD[ULE] [-filename]
-NOMO[DULE]
NOMO
Produces a module listing.
-PMA[P]
–
Produces a program address map.
-TRE[E] [=filename]
-NOTR[EE]
NOTR
Produces a call tree listing.
(Note) -LNK must be specified to execute DOC17K and the listing utilities. See Section 2.1.
3-2
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
(1) Input files
The files listed in Table 3-3 are needed to output listings.
Specify the required file output options when starting RA17K, emlC-17K, and LK17K.
For more details on the file output options, refer to the RA17K, emlC-17K, and LK17K
User’s Manuals.
Table 3-3. Input Files Required to Enable Listing Output
Input file
Output listing (option)
Absolute address format listing
(-LIS[T])
Intermediate
PRN file
REL file
LNK file
XREF file
O
O
O
O(Note 1)
O
O
O
O
O
O
O
O
Cross-reference listing (-XRE[F])
Summary
file
Log file
Public cross-reference listing
(-PUB[XREF])
Module map listing (-MAP)
O(Note 2)
Program map listing (-AMA[P])
Report listing (-REP[ORT])
Document listing (-SPE[C])
O
O
Module listing (-MOD[ULE])
O
O
Call tree listing (-TRE[E])
O(Note 3)
O
O
O
O
(Note 1) Used when -BRA[NCH] is specified.
(Note 2) Used to extract symbol definition comments.
(Note 3) With emlC-17K, use a preprocessing file instead of an intermediate PRN file.
DOC17K User's Manual
3-3
Chapter 3
Supported Output Listings and Options
(2) Input file extensions
Input files are named using the specified filename, to which one of the following
extensions is appended.
Table 3-4. Input File Extensions
Specification
Module name specification
Parameter filename specification
Intermediate PRN file
Preprocessing file
Module name.IPN
Module name.PPL
Module name.IPN
Module name.PPL
REL file
Module name.REL
Module name.REL
LNK file
Specified filename.LNK
Specified filename.LNK
XREF file
Module name.IXF
Module name.IXF
Summary file
Module name.SUM
Module name.SUM
Log file
Module name.LOG
Module name.LOG
Input file
3.1.2 Options Common to All Listing Utilities
The output listing format control options are common to all listing utilities.
Table 3-5 lists the options that are common to all listing utilities.
Table 3-5. Options That Are Common to All Listing Utilities
Option name
Default
Contents
-ROW=n
n = 66
Number of lines per page of the listing
-COL[UMN]=n
n = 80
Number of columns per line of the listing
-TAB
-NOT[AB] [=n]
NOT = 8
Tab conversion control
-FOR[M]
-NOF[ORM]
NOF
Form feed control
-HEA[D]
-NOH[EAD]
HEA
List header control
-WOR[K]=pathname
Current
Work drive and directory specification
(1) -ROW=n
Specifies the number of output lines per page (50 ≤ n ≤ 255). The default is
n = 66.
3-4
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
(2) -COL[UMN]=n
Specifies the number of output columns per line (72 ≤ n ≤ 255). The default is
n = 80. Any part of the listing that exceeds the specified number of columns is not
output. When the specified number of columns per line is not in a multiple of doublebyte characters, the listing is truncated one column before the double-byte character.
A sufficiently large value should be specified for COL. Any map listing that exceeds
the number of columns per line specified here is directed to the next page. A listing
that exceeds the number of columns for two pages is not output.
If the number of columns per line is specified in the format file for document listing,
that number is used.
(3) -TAB/-NOT[AB] [=n]
Specifies whether to replace each occurrence of a TAB code with a blank or output
it as is. The default is -NOT[AB]=8.
Table 3-6. -TAB Option Settings
Setting
Explanation
-NOT[AB] [=n]
Insert a blank to align the character following the TAB with a column
that is an integer multiple of n (1 ≤ n ≤ 255).
-TAB
Output the TAB code as is.
(4) -FOR[M]/-NOF[ORM]
Specifies whether to feed forms with null lines to output a form feed code (FF). The
default is -NOF[ORM].
Table 3-7. -FORM Option Settings
Setting
Explanation
-FOR[M]
Feed forms with FF codes.
-NOF[ORM]
Output CR/LF codes until the line specified by -ROW.
DOC17K User's Manual
3-5
Chapter 3
Supported Output Listings and Options
(5) -HEA[D]/-NOH[EAD]
Controls header output at the beginning of each page. The default is -HEA[D].
Table 3-8. -HEAD Option Settings
Setting
Explanation
-HEA[D]
Output a header on each page.
-NOH[EAD]
Output a header on the first page only.
When -NOH[EAD] is specified, the following header is omitted:
RA17K V1.00 V1 <<∗∗∗∗∗∗∗ ∗∗∗ LIST>>...
PROG = ∗∗∗∗∗
(6) -WOR[K]=pathname
Specifies the work drive and directory used by the Document Processor. If environmental
variable TMP is specified, the TMP path is used when this option is omitted.
If environmental variable TMP is not specified, the current path is used.
3.1.3 Listing-Specific Options
Listing-specific options can be specified.
All options for each listing utility can be specified when DOC17K starts. Once a listing
utility has been run independently, however, only those options specific to that listing
can be specified. Remember that an option error is likely to result if the parameter file
used to start DOC17K is used as the parameter file for running a particular listing utility.
(1) Absolute address format listing options
Table 3-9. Absolute Address Format Listing Options
3-6
Option name
Default
Explanation
-GEN
-NOG[EN]
GEN
Macro and repeat pseudo instruction expansion
control
-CON[D]
-NOC[OND]
CON
Conditional statement control
-SEQ
-NOS[EQ]
NOS
Option information listing control
-BRA[NCH]
-NOB[RANCH]
NOB
Embedded cross-reference listing control
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
(a) -GEN/-NOG[EN]
Controls the listing of the macro-expanded part of a macro statement. The default
is -GEN. With -NOG[EN], output is controlled by the macro expansion control
pseudo instructions in the source program.
Table 3-10. -GEN Option Settings
Setting
Explanation
-GEN
Lists all statements.
-NOG[EN]
• SMAC/VMAC/NOMAC/OMAC/LMAC pseudo instructions
Controls the listing of the macro-expanded part.
• SBMAC/VBMAC/NOBMAC/OBMAC/LBMAC pseudo instructions
Controls the listing of the embedded macro-expanded part.
Remark
Refer to the RA17K User’s Manual for details of the macro expansion control pseudo
instructions.
(b) -CON[D]/-NOC[OND]
Controls the listing of an IF, IFCHAR, IFNCHAR, IFSTR, or CASE conditional
statement when the is false. The default is -CON[D].
Table 3-11. -COND Option Settings
Setting
Explanation
-CON[D]
Lists all statements regardless of the condition.
-NOC[OND]
Controls the listing of the conditional statement with SFCOND/
LFCOND pseudo instructions in the source program.
Remark
Refer to RA17K User’s Manual for more details on the conditional listing output control
pseudo instructions.
(c) -SEQ/-NOS[EQ]
Controls the listing of option information. The default is -NOS[EQ].
Table 3-12. -SEQ Option Settings
Setting
Explanation
-SEQ
Produces an option information listing.
-NOS[EQ]
Does not produce an option information listing.
DOC17K User's Manual
3-7
Chapter 3
Supported Output Listings and Options
(d) -BRA[NCH]/-NOB[RANCH]
Controls the listing of label reference line information (embedded cross-references). The default is -NOB[RANCH].
Table 3-13. -BRANCH Option Settings
Setting
Explanation
-BRA[NCH]
Lists embedded cross-references.
-NOB[RANCH]
Does not list embedded cross-references.
(2) Module map listing and program map listing options
Table 3-14. Module Map Listing and Program Map Listing Options
Option name
Default
Explanation
-AXI[S]={C|R}
C
Vertical and horizontal axis
specification
-NAM[ELENGTH]=n
n=8
number-of-characters-per-box
specification
-LIN[EKIND]={H|Z}
H
Line kind specification
-SEP[ARATE]={PERIOD|POINT}
PERIOD
PUBLIC/LOCAL separator line type
specification
-DEL[IMITER]=character
∗
Deleted character setting
-NRO[W]=n
n=1
Symbol name number-of-characters
specification
-NV=character
^
NIBBLEnV attribute display character
setting
-NB=character
>
NIBBLEn attribute display character
setting
-STR=character
&
STRUCTURE/UNION attribute
display character setting
-SOR[T]=n
n=1
Symbol order specification
-SYM[LENGTH]=n
n = 32
Symbol name number-of-charactersper-line specification
Remarks 1.
2.
3-8
Decimal digits may be specified for options.
Only single-byte single characters can be used to specify options on PC/AT
host machines. Both single- and double-byte single characters are supported
by PC-9800 host machines.
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
(a) -AXI[S]={C|R}
Specifies the vertical and horizontal axes of a map listing in tabular form. The
default is C.
Table 3-15. -AXIS Option Settings
Setting
Explanation
R
Sets the vertical address for the row address (0xH to 7xH) and that for
the column address (x0H to xFH).
C
Sets the vertical address for the column address (x0H to xFH) and that
for the row address (0xH to 7xH).
(b) -NAM[ELENGTH]=n
Specifies the number of characters that can be displayed in a row of a box
(8 ≤ n ≤ 255). The default is 8. The number of characters actually displayed
equals NAMELENGTH ∗ NROW.
(c) -LIN[EKIND]={H|Z}
Specifies the frame lines to be drawn. The default is H.
Table 3-16. -LINEKIND Option Settings
Setting
Explanation
Z
Double-byte line
H
Single-byte line
Caution
DOC17K User's Manual
With PC/AT host machines, double-byte lines (-LINEKIND=Z)
cannot be specified.
3-9
Chapter 3
Supported Output Listings and Options
In addition, the following options can be specified to set a line kind in part:
Table 3-17. -LINEKIND Option Settings (Detailed Settings)
Setting
Explanation
-LU=character
Upper left corner (default: double-byte ”
”, single-byte ”
”)
-LD=character
Lower left corner (default: double-byte ” ”, single-byte ”
”)
-RU=character
Upper right corner (default: double-byte ” ”, single-byte ”
”)
-RD=character
Lower right corner (default: double-byte ”
”)
-UC=character
Upper intersection (default: double-byte ”
”, single-byte ”
”)
-DC=character
Lower intersection (default: double-byte ”
”, single-byte ”
”)
-LC=character
Left intersection (default: double-byte ”
-RC=character
Right intersection (default: double-byte ”
-CR=character
Cross-intersection (default: double-byte ”
”, single-byte ”
”, single-byte ”
”)
”, single-byte ”
”, single-byte ”
”)
”)
(d) -SEP[ARATE]={PERIOD|POINT}
Specifies the type of public/local separator lines. The default is PERIOD.
Table 3-18. -SEPARATE Option Settings
Setting
Explanation
POINT
Point
PERIOD
Period
Caution
With PC/AT host machines, the point (-SEPARATE=POINT)
cannot be specified.
(e) -DEL[IMITER]=character
Specifies a delimiter character that is attached to a symbol name when it exceeds
the value specified by -NAM[ELENGTH] or -NRO[W]. ”∗” is assumed by default.
(f) -NRO[W]=n
Specifies the number of lines (1 ≤ n ≤ 5) that are displayed when a symbol name
exceeds the value specified by -NAM[ELENGTH]. The default is 1. When a
symbol name exceeds the specified number of lines, it is terminated by a delimiter
and the subsequent characters are not displayed.
The number of characters actually displayed equals NAMELENGTH ∗ NROW.
3 - 10
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
(g) -NV=character
Specifies the character used to identify a NIBBLEnV attribute symbol. ”^” is
assumed by default. This identification character is prefixed to each symbol
name when it is displayed.
(h) -NB=character
Specifies the character used to identify a NIBBLEn attribute symbol. ”>” is
assumed by default. This identification character is prefixed to each symbol
name when it is displayed.
(i)
-STR=character
Specifies the character used to identify a STRUCTURE (structure or union)
attribute symbol. ”&” is assumed by default. This identification character is
prefixed to each symbol name when it is displayed.
(j)
-SOR[T]=n
Specifies the order in which symbol names are output in the symbol name listing.
If this option is omitted, symbol names are output in alphabetic order.
Table 3-19. -SORT Option Settings
Setting
Explanation
0
In order of appearance
1
In alphabetic order
2
In address order
(k) -SYM[LENGTH]=n
Specifies the symbol name length of the symbol name listing (1 ≤ n ≤ 255). The
default is 32. A symbol name longer than 32 characters is output using two lines,
together with symbol information.
DOC17K User's Manual
3 - 11
Chapter 3
Supported Output Listings and Options
(3) Cross-reference listing option
Table 3-20. Cross-Reference Listing Option
Option name
Default
Explanation
-XFO[RM]=n
0
Specifies the output format of a cross-reference listing.
(a) -XFO[RM]=n
Specifies the output format of a cross-reference listing. The default is 0.
Table 3-21. -XFORM Option Settings
Setting
Explanation
0
Outputs definition/reference line numbers on one line.
1
Outputs a filename and a reference line number for each reference in
a tag jump format.
[Sample output] -XFO[RM]=0
SYMBOL
Symbol name
VALUE
ATTR
TYPE
/REF(#DEF)
00000001
Local
DAT
/#1, 2
[Sample output] -XFO[RM]=1
MODULE(LineNo.)
:
VALUE
B:\RA17K\SAMPLE.ASM(5)
: 00000001
: ATTR
: TYPE
: SYMBOL
: Local
: MEM
: symbol-name
B:\RA17K\SAMPLE.ASM(8)
(4) Report listing option
Table 3-22. Report Listing Option
Option name
Default
Explanation
-RFM[T]=filename
–
Names a report listing format file.
(a) -RFM[T]=filename
Names the format file containing the user-specified format in which a report listing
is to be produced. If this option is omitted, the output format shown in Figure
3-1 is assumed.
3 - 12
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
Figure 3-1. Report Listing Output Format (Default)
[Assemble/compile]
PROCESS
START
END
ELAPSED
process-name
start-time
end-time
elapsed-time
TOTAL
total-elapsedtime
[Used-memory information]
MEMORY BLOCKS
SIZE
area-name
secured-size
USED
used-size
PERCENT
use-rate
[Created file information]
FILE NAMES
SIZE
filename
file-size
(5)
Document listing options
Table 3-23. Document Listing Options
Option name
Default
Explanation
-SUM[MARY]=’program title’,filename
–
Output the program summary
-DFM[T]=filename
–
Names a module and routine format file.
(a) -SUM[MARY]=’program-title’,filename
This option allows program summaries to be included in the document listing as
desired. The contents of the file specified by title and filename are output in the
document listing.
(b) -DFM[T]=filename
Names the format file containing the user-specified format in which modules and
routines are to be listed. The output format shown in Figure 3-2 is assumed when
this option is omitted.
DOC17K User's Manual
3 - 13
Chapter 3
Supported Output Listings and Options
Figure 3-2. Document Listing Output Format (Default)
[Module summary]
Chapter n. Module Title
[Specifications]
Module Summary
Module Name
Create
Size
Step
:
:
:
:
module-name
created-date
file-size
steps
PUBLIC(MEM)
PUBLIC(FLG)
PUBLIC(DAT)
PUBLIC(LAB)
EXTRN(MEM)
EXTRN(FLG)
EXTRN(DAT)
EXTRN(LAB)
:
:
:
:
:
:
:
:
PUBLIC-symbol-name
PUBLIC-symbol-name
PUBLIC-symbol-name
PUBLIC-symbol-name
EXTRN-symbol-name
EXTRN-symbol-name
EXTRN-symbol-name
EXTRN-symbol-name
[Routine summary]
n. m Routine Title
[Specifications]
Routine Summary
[Routine Information]
Address Range
Entrance
MEM Changed
MEM Referred
MEM Manipulated
FLG Changed
FLG Referred
DAT Referred
Branch To
Subroutines Called
LAB Manipulated
System Call
:
:
:
:
:
:
:
:
:
:
:
:
start-address to end-address
entry-name
changed MEM type symbol
referred MEM type symbol
manipulated MEM type symbol
changed FLG type symbol
referred FLG type symbol
referred DAT type symbol
branch to LAB type symbol
subroutines called LAB type symbol
manipulated LAB type symbol
SYSCAL entry name
TAG information
3 - 14
DOC17K User's Manual
Chapter 3
Supported Output Listings and Options
(6) Call tree listing option
Table 3-24. Call Tree Listing Option
Option name
Default
Explanation
-MAI[N]=main-function-name
MAIN
Names the first function to appear in the
tree listing.
(a) -MAI[N]=main-function-name
Names a main function in the tree listing. If this option is omitted, a tree listing
is produced from ”MAIN”.
(7) Module listing options
Table 3-25. Module Listing Options
Option name
Default
Explanation
-MFM[T]=filename
–
Names a module listing format file.
-PMA[P]
–
Produces a program address map.
-MLE[N]=n
32
Specifies a module name length.
-RLE[N]=n
12
Specifies a function (routine) name length.
(a) -MFM[T]=filename
Names the format file that contains the user-specified format in which a module
listing is to be produced. If this option is omitted, the output format shown in
Figure 3-3 is assumed.
DOC17K User's Manual
3 - 15
Chapter 3
Supported Output Listings and Options
Figure 3-3. Module Listing Output Format (Default)
MODULE NAME
CREATED DATE/TIME
module-file-name
created-date
created-time
file-size
created-date
created-time
file-size
include-file-name
FILE SIZE
ROUTINE NAME
SRC STEPS
ADDRESS RANGE
routine-name
source-steps
start-address to
end-address
(b) -PMA[P]
Specifies program address map output. Address map output is suppressed if
-PMA[P] is omitted.
When -PMA[P] is specified, an address map is appended to a module listing
output file (.MOD). An address map is produced page by page (PAGE0 to
PAGE3).
Figure 3-4. Address Map Output Format
SEGMENT NO = x
PAGE0
ROUTINE NAME/VARIABLE
MODULE NAME
routine-name or variable-name
defined-module-name
ADDRESS
address-range
PAGE1
PAGE2
PAGE3
(c) -MLE[N]=n
Specifies the length of the module name output field (12 ≤ n ≤ 64). The default is 12.
(d) -RLE[N]=n
Specifies the length of the routine name output field (22 ≤ n ≤ 128). The default is 32.
3 - 16
DOC17K User's Manual
Chapter 4
Output Listing
4.1 Option Information Listing
Information relating to the options specified at the initiation of the assembler (RA17K),
compiler (emlC-17K), linker (LK17K), and Document Processor (DOC17K), can be output
as a listing.
(1) Option
Specify -SEQ to produce an option information listing. When -NOL[IST] is specified,
however, specifying -SEQ does not allow option information listing. An option information
listing is output at the beginning of each module-specific absolute address format
listing.
(2) Output file
Absolute address format listing (.PRN)
(3) Output details
An option listing is output.
(a) MODULE OPTION
The assembly (or compilation) options specified at the initiation of RA17K (or
emlC-17K) and the options specified at the initiation of DOC17K are listed.
The options are listed along with their specified values, or with the defaults when
no values are specified.
(b) LINK OPTION
The linker options specified at the initiation of LK17K are listed.
The options are listed along with their specified values, or with the defaults when
no values are specified.
DOC17K User's Manual
4-1
Chapter 4
Output Listing
[Sample output]
RA17K
V1.00 V1 << D17XXX
ASSEMBLE LIST >> HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
<MODULE OPTION>
NOOBJ/OBJ
NOUND/UND
INCLUDE
NOLIST/LIST
NOXREF/XREF
ZZZ0
ZZZ1
ZZZ2
ZZZ3
ZZZ4
ZZZ5
ZZZ6
ZZZ7
ZZZ8
ZZZ9
ZZZ10
ZZZ11
ZZZ12
ZZZ13
ZZZ14
ZZZ15
WARNING
ABSOLUTE/RELOCATABLE
SUMMARY/NOSUMMARY
HOST/NOHOST
WORK
TAGSTART
TAGEND
NOLIST/LIST
SEQ/NOSEQ
BRANCH/NOBRANCH
GEN/NOGEN
COND/NOCOND
NOTAB/TAB
FORM/NOFORM
ROW
COLUMN
WORK
LNK
HEAD/NOHEAD
4-2
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
OBJ=A:\RA17K\SAMPLE. REL
NOUND
INCLUDE=
LIST=A:\RA17K\SAMPLE. IPN
XREF=A:\RA17K\SAMPLE. IXF
ZZZ0=0
ZZZ1=0
ZZZ2=0
ZZZ3=0
ZZZ4=0
ZZZ5=0
ZZZ6=0
ZZZ7=0
ZZZ8=0
ZZZ9=0
ZZZ10=0
ZZZ11=0
ZZZ12=0
ZZZ13=0
ZZZ14=0
ZZZ15=0
WARNING=4
RELOCATABLE
NOSUMMARY
NOHOST
WORK=D:\
TAGSTART=.
TAGEND=..
LIST=SAMPLE. PRN
SEQ
NOBRANCH
GEN
COND
NOTAB=8
NOFORM
ROW=66
COLUMN=80
WORK=D:\
LNK=SAMPLE.LNK
HEAD
DOC17K User's Manual
Chapter 4
Output Listing
< LINK OPTION >
NOOBJ/OBJ
NOICE/ICE
NOPROM/PROM
HOST/NOHOST
WORK
WARNING
INCREMENT/NOINCREMENT
DIRECTIVE
PARAMETER
PROG
INDIRECT
JUNK/NOJUNK
NOL/LMAP
RA17K
:
:
:
:
:
:
:
:
:
:
:
:
:
OBJ=A:\RA17K\SAMPLE. LNK
ICE=A:\RA17K\SAMPLE.ICE
NOPROM
NOHOST
WORK=D:\
WARNING=0
NOINCREMENT
DIRECTIVE=
PARAMETER=
PROG=
INDIRECT=
NOJUNK
LMAP=A:\RA17K\SAMPLE.LMP
V1.00 V1 << D17XXX
ASSEMBLE LIST >>
HH:MM:SS MM/DD/YY PAGE 002
PROG =
ML/NOML
: NOML
MP/NOMP
: NOMP
4.2 Absolute Address Format Listing
The results of source program assembly and linkage are converted to absolute addresses
for assembly listing.
(1) Option
Specify -LIST to produce an absolute address format listing.
(2) Output file
Absolute address format listing (.PRN)
(3) Output details
(a) Line format
EEEE STNO LOC.OBJECT M I SOURCE STATEMENT
DOC17K User's Manual
4-3
Chapter 4
Output Listing
• EEEE
: Error code (A four-character string indicating the type of an
error as it occurs.)
• STNO
: Source line number.
• LOC.
: Location address (absolute address). Address 1xxxx for
EPA. For a branch table, addresses and object codes are
listed with section names on the comment lines.
• OBJECT
: Object code.
• M
: Macro nesting level.
• I
: Include nesting level.
• SOURCE STATEMENT : Source program contents.
Remark
Refer to the RA17K User’s Manual for details of the line format.
(b) Listing of statements expanded in the macro, repeat, and include parts
Statements expanded in the macro, repeat, and include parts are listed according
to the following:
• STNO : A ”+” sign and the line number of each expanded statement are listed
until the expansion ends. The expanded statement line number is
incremented each time expansion is performed.
• M
: The nesting levels of macros, repeat instructions, and built-in macros
are listed.
• I
: The nesting level of INCLUDE pseudo instructions is listed.
(c) Error statement listing
If error statements have been encountered, error codes and error numbers are
listed in place of EEEE. Refer to the RA17K or emlC-17K User’s Manual for
details of the error codes and error numbers.
(d) End of listing
The end of a listing is identified by the output of the following information:
• TOTAL ERRORS
: Total number of errors that occurred during source
module assembly.
• TOTAL WARNINGS
: Total number of warnings generated during source
module assembly.
(e) Related pseudo instructions
• TITLE
: Whenever a TITLE pseudo instruction is encountered, a form feed
is performed and a title is output as a header on the new page. Title
output continues until the next TITLE pseudo instruction is encountered.
4-4
DOC17K User's Manual
Chapter 4
Output Listing
• EJECT
: A form feed is performed whenever an EJECT pseudo
instruction is encountered.
• LIST/NOLIST
: Statement listing is controlled.
• SFCOND/LFCOND : Conditional statement listing is controlled.
• C14344/C4444
: The object code format is controlled.
• SMAC/VMAC/NOMAC/OMAC/LMAC
: Listing of the macro-expanded part is controlled.
• SBMAC/VBMAC/NOBMAC/OBMAC/LBMAC
: Listing of the embedded macro-expanded part is controlled.
Remark
DOC17K User's Manual
Refer to the RA17K User’s Manual for details of the listing control instructions.
4-5
Chapter 4
Output Listing
[Sample output]
RA17K V1.00 V1
<< D17XXX ASSEMBLE LIST >>
HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
SOURCE = SAMPLE. ASM
EEEE STNO LOC. OBJECT
225
226
227
228
229
230 00000D
231 00000D 071F0
232
233
234
235
236
237 00000E 1D790
238 00000F 1D700
239 000010 1D710
240 000011 1D720
241 000012 1D730
242
243 000013 1D791
244 000014 1D700
245 000015 1D710
246 000016 1D720
247 000017 1D730
248
249 000018 1D792
250 000019 1D700
251 00001A 1D710
252 00001B 1D720
253
Using the EPA area
254 10001C 1D790
255 10001D 1D7E0
256
257
258
259
260
1
+
1
2
+
2 10001E 1D78F 2
+
3 10001F 07324 2
Using the JUMP table
00000 0C000
M I
SOURCE STATEMENT
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
;∗
;∗ RESET POWER ON RESET PROCESS
;∗
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
IRESET:
DI
INTERRUPT DISABLE
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
;∗ PORT INITIALIZE
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
MOV
MOV
MOV
MOV
MOV
BANK,
RP0A,
RP0B,
RP0C,
RP0D,
#0
#CP0AINI
#CP0BINI
#CP0CINI
#CP0DINI
;
;
;
;
PORT0A
PORT0B
PORT0C KEY STB
PORT0D KEY IN
MOV
MOV
MOV
MOV
MOV
BANK,
RP1A,
RP1B,
RP1C,
RP1D,
#1
#CP1AINI
#CP1BINI
#CP1CINI
#CP1DINI
;
;
;
;
PORT1A
PORT1B
PORT1C
PORT1D
MOV
MOV
MOV
MOV
BANK,
RP2A,
RP2B,
RP2C,
#2
#CP1AINI ; PORT2A
#CP1BINI ; PORT2B
#CP1CINI ; PORT2C
MOV
MOV
BANK, #0
RPL, #BRBANK0
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
;∗ REGISTER FILE SET
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
INITFLG P2ABIO3, P2ABIO2, P2ABIO1, P2ABIO0
SET4
P2ABIO3, P2ABIO2, P2ABIO1, P2ABIO0
MOV
WR, #1111B
POKE .MF.P2ABIO3 SHR 4. WR
; Jump Table:?INIT
TOTAL ERRORS = 0
TOTAL WARNINGS = 0
END OF LIST
4-6
DOC17K User's Manual
Chapter 4
Output Listing
4.3 Cross-Reference Listing
4.3.1 Embedded Cross-References
LIST17K lists the reference line numbers of the labels appearing in source programs in
an absolute address format listing.
(1) Option
Specify -BRA[NCH] to list embedded cross-references. When -NOL[IST] is specified,
however, the specification of -BRA[NCH] does not permit embedded cross-reference
listing.
(2) Output file
Absolute address format listing (.PRN)
(3) Output details
Those addresses for referencing labels and the types of instructions are listed.
• P-xxxx
: A public label referenced from another module. Used at address xxxx.
• B-xxxx
: Used by the BR instruction at address xxxx.
• C-xxxx : Used by the CALL instruction at address xxxx.
DOC17K User's Manual
4-7
Chapter 4
Output Listing
[Sample output]
RA17K V1.00 V1
<< D17XXX ASSEMBLE LIST >>
HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
SOURCE = SAMPLE. ASM
EEEE STNO
5
:
123
124
125
LOC.
126 00000D
127 00000D
128
129
130
131
132
133 00000E
134 00000F
135 000010
136 000011
137 000012
138
:
Reference within the
:
234 000124
:
238 000128
OBJECT
071F0
SOURCE STATEMENT
PUBLIC IRESET
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
;∗ RESET
POWER ON RESET PROCESS
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
P-23F, P-242, B-124, C-128
IRESET:
DI
: INTERRUPT DISABLE
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
;∗ PORT INITIALIZE
;∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
1D790
1D700
1D710
1D720
1D730
MOV
MOV
MOV
MOV
MOV
BANK,
RP0A,
RP0B,
RP0C,
RP0D,
#0
#CP0AINI
#CP0BINI
#CP0CINI
#CP0DINI
0C00D
BR
IRESET
1C00D
CALL IRESET
;
;
;
;
PORT0A
PORT0B
PORT0C KEY STB
PORT0D KEY IN
same module
Reference from another module
4
:
84 00023F 0C00D
:
98 000242 1C00D
4-8
M I
EXTRN
BR
; BR RESET
; CALL RESET
LAB:IRSET
IRESET
CALL IRESET
; BR RESET
; CALL RESET
DOC17K User's Manual
Chapter 4
Output Listing
4.3.2 Table Cross-References
(1) Local cross-references
The definitions and reference positions of symbols referenced within a source module
are listed.
(a) Option
Specify -XRE[F] to list local cross-references.
(b) Output file
Cross-reference listing (.XRF)
(c) Output details
(i) -XFO[RM]=0
symbol-name evaluation-value attribute type reference/definition-linenumber(#definition-line-number)
(ii) -XFO[RM]=1
Definition line: source-module-name(nn):evaluation-value:attribute:
type :symbol-name
Reference line: source-module-name(nn)
DOC17K User's Manual
4-9
Chapter 4
Output Listing
The following table details the line format.
Legend
Output value
Explanation
Definition line number
nn
Indicates the number of the line on which a symbol is
defined.
Reference line number
Indicates the number of the line from which the symbol
is referenced
Evaluation value (VALUE)
32 bits (hexadecimal)
Refer to the RA17K User’s Manual for details.
Attribute (ATTR)
Public
A symbol that can be referenced from other modules
Local
A symbol that can be referenced only within the module
in which it appears.
DAT
Data type
MEM
Memory type
Nn
Horizontal nibble memory type
NnV
Vertical nibble memory type
LAB
Label type
FLG
Flag type
MAC
Macro
STR
Structure
UNI
Union
ARY
Array
Type (TYPE)
Remark Up to about 8,000 symbols can be contained within a cross-reference listing.
[Sample output] -XFO[RM]=0
RA17K V1.00 V1 << D17XXX
XREF LIST >> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE. ASM
SYMBOL
Symbol name
4 - 10
VALUE
ATTR TYPE
00000001 Local DAT
/REF(#DEF)
/#1, 2
DOC17K User's Manual
Chapter 4
Output Listing
[Sample output] -XFO[RM]=1
RA17K V1.00 V1 << D17XXX
XREF LIST >> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE. ASM
MODULE(LineNo.)
: VALUE
: ATTR : TYPE : SYMBOL
B:\RA17K\SAMPLE. ASM(5) : 00000001 : Local : MEM : symbol-name
B:\RA17K\SAMPLE. ASM(8)
B:\RA17K\SAMPLE. ASM(12)
B:\RA17K\SAMPLE1.MLC(7) : 00000000 : Local : STR : structured-symbol-name
B:\RA17K\SAMPLE1.MLC(18)
B:\RA17K\SAMPLE1.MLC(22)
(2) Public cross-references
The definitions and reference positions of those symbols referenced from external
modules are listed.
(a) Option
Specify -PUB[XREF] to list public cross-references.
(b) Output file
Public cross-reference listing (.PUB)
(c) Output details
(i) -XFO[RM]=0
symbol-name evaluation-value attribute type [m] reference/definition-linenumber (#definition-line-number)
(ii) -XFO[RM]=1
Definition line: source-module-name(nn):evaluation-value:attribute:
type:symbol-name
Reference line: source-module-name(nn)
DOC17K User's Manual
4 - 11
Chapter 4
Output Listing
The table below details the line format.
Legend
Output value
Explanation
Definition line number
nn
Indicates the number of the line on which a symbol is
defined.
Reference line number
Indicates the number of the line from which the symbol is
referenced
m
m
Indicates the module number (sequence number of the REL
file specified at entry).
Evaluation value (VALUE)
32 bits (hexadecimal)
Refer to the RA17K User’s Manual for details.
Attribute (ATTR)
Public
Symbol that can be referenced from other modules
Local
Symbol that can be referenced only within the module in
which it appears.
DAT
Data type
MEM
Memory type
Nn
Horizontal nibble memory type
NnV
Vertical nibble memory type
LAB
Label type
FLG
Flag type
MAC
Macro
STR
Structure
UNI
Union
ARY
Array
Type (TYPE)
Remark
Up to about 8,000 symbols can be contained within a cross-reference listing.
[Sample output] -XFO[RM]=0
RA17K V1.00 V1 << D17XXX
PUBXREF LIST >> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE.ASM
SYMBOL
Symbol name
4 - 12
VALUE
ATTR TYPE
00000001 Local DAT
/REF(#DEF)
/[1]# 1
DOC17K User's Manual
Chapter 4
Output Listing
[Sample output] -XFO[RM]=1
RA17K V1.00 V1 << D17XXX
PUBXREF LIST >> HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
MODULE(LineNo.)
: VALUE
: TYPE : SYMBOL
B:\RA17K\MAIN. ASM(5) : 00000001 : MEM : PUBLIC-symbol-name
B:\RA17K\SAMPLE. ASM(24)
B:\RA17K\SUB. ASM(32)
B:\RA17K\SAMPLE1. MLC(7) : 00000000 : STR : structured-symbol-name
B:\RA17K\SAMPLE2. MLC(18)
B:\RA17K\SAMPLE3. MLC(22)
4.4 Module Map and Program Map Listings
4.4.1 Map Listings
A map listing presents memory definitions as a table.
(1) Options
Specify -MAP to output a module map listing or -AMA[P] to output a program map
listing.
(2) Output file
• Module map listing (.MAP)
-MAP
: REL filename.MAP
-MAP=<filename> : <filename>.MAP
If more than one module is named, a map listing is output
for each of the named modules.
• Program map listing (.AMP)
-AMA[P]
: Parameter filename.AMP
-AMA[P]=<filename> : <filename>.AMP
A map listing in which the symbols of multiple modules
are merged is output.
(3) Output details
A map listing consists of a bank-specific listing of memory attribute (MEM, NIBBLEn,
and NIBBLEnV) symbols and flat attribute symbols. A map of the members of
emlC-17K structures and unions is included.
Caution
DOC17K User's Manual
To output a structure and union map, specify a debug
option at emlC-17K compile time. No structure or union
map is output if this debug option is omitted.
4 - 13
Chapter 4
Output Listing
(a) Delimiters
The kinds of lines used to represent the height, width, corners, intersections and
other aspects of a memory map can be represented with specified characters.
Delimiters may also be specified for public and local variables.
(b) Symbol name display
When a variable name is too large to be displayed in a specified box, a specified
delimiter is displayed. For the NIBBLEn, NIBBLEnV, and STRUCTURE attributes, the variable name is padded with a specified character to enable the
display of more than one box.
(c) Array display
Arrays are represented by the name [ ]....
Example 1 BYTE abc[2] [3]: Listing of six arrays
abc[0] [0] abc[0] [1] abc[0] [2] abc[1] [0] abc[1] [1] abc[1] [2]
Example 2 Array representation of the structure STRUCTURE
struct A a[2];
&a[0] &a[0] &a[1] &a[1]
Figure 4-1. Sample Memory Map Listing
>GRL_3_D
>GRL_3_D
>GRL_3_D
&STR
&STR
&STR
ARY[0]
ARY[1]
ARY[2]
^GRR_1_∗
Upper level: Local
PUB_SYM
Lower level: Public
^GRR_1_∗
Remark
Double-byte lines, 8 characters, and delimiter ”∗”.
Caution
4 - 14
While the number of symbols displayed in each box is
unlimited, the execution of symbol processing requires
that a work area be secured in the host machine’s memory.
If the available memory space is limited, it may prove
impossible to display all the symbols. For a 17K Series
device, do not assign more than 6,000 symbols per bank
of data memory.
DOC17K User's Manual
Chapter 4
Output Listing
(d) Height and width as a number of characters
The height and width of a page are set to the option values of ROW (height) and
COLUMN (width). A data memory map which exceeds the capacity of one page
is continued on the next page.
If, however, a map is greater than two pages in length, that portion exceeding
two pages is truncated.
Figure 4-2. Representation of a Data Memory Map Greater than
One Page in Length
Designated
range for
1 page
Page 1
Page 2
Page 3
Page 4
Map for one bank
DOC17K User's Manual
4 - 15
Chapter 4
Output Listing
[Sample output 1]
RA17K V1.00 V1 << D17XXX DATA MEMORY MAP >> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE.ASM
BANK = 0
0
R
0 ^GRL_1_D
O
1
LCDD0
2
COL
3
4
5
6
7
>GRL_1_D
DATA TOP
KEY_COU∗ RG0
>GRL_2_D
VOL_DAT
RG1
>GRL_1_D
W
1
^GRL_2_D
LCDD1
>GRL_2_D
&struct
2
^GRL_3_D
&struct
LCDD2
&struct
&struct
&abc[0]
>GRL_3_D
&abc[0]
&abc[1]
&abc[1]
DELAY_W∗
RG2
DELAY_FL BAL_DAT DLY_COU∗
RG3
>GRL_3_D
^PNV_SYM
3
K_DAT
LCDD3
P_SYM
4
AR3
^PNV_SYM
LCDD4
DLY_IXL
>PN_SYM
^K_DAT_X
>PN_SYM
^PNV_SYM
5
AR2
LCDD5
^GRL_7_D
FAD_DAT LEVEL_D∗
LCD_DA_3 ^K_DAT_Y
^GRR_1_∗
6
AR1
LCDD6
^K_DAT_X
^GRL_7_D
^GRR_1_∗
7
AR0
LCDD7
^GRL_7_D
DTM_IXM2 ^GRL_5_D
^K_DAT_X
^GRL_6_D
^K_DAT_Y
DELAY_FR SUR_M_D∗ ^GRL_6_D
^GRL_5_D
^GRR_1_∗
4 - 16
DOC17K User's Manual
Chapter 4
Output Listing
Symbols with the NIBBLEn or NIBBLEnV attribute, for which multiple nibbles are
defined, are output unconditionally. Symbols with the NIBBLEn type are preceded with ”>”. Those with the NIBBLEnV type are preceded with ”^”. Structured
symbols are preceded with ”&”; arrays are terminated by array-number[n].
Symbols exceeding the value of -NAMELENGTH are terminated by ”∗”.
[Sample output 2]
RA17K V1.00 V1
<< D17XXX FLAG MAP >>
HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE.ASM
BANK = 0
MSB
63
3
LCD_DWN
2
1
0
LSB
LCD_UP
P_FLG1
66
68
P_FLG2
70
P2A3
P2A2
P2A1
P2A0
[Sample output 3]
A sample listing of the structure definition shown below is presented on the
following pages.
struct
puba
{
BYTE
a1;
BYTE
a2[2];
struct
pubb
{
BYTE
b1;
BYTE
b2[2];
}
PubB1;
struct
pubb
Pb2[2];
};
DOC17K User's Manual
4 - 17
Chapter 4
Output Listing
RA17K V1.00 V1 << D17XXX STRUCTURE MAP >> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE. MLC
STRUCT = pubb
COL
R
0
1
2
3
4
5
6
7
O
W0
^b1
^b1
^b2[0]
^b2[0]
^b2[1]
^b2[1]
RA17K V1.00 V1 <<D17XXX STRUCTURE MAP>> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE.MLC
STRUCT = puba
COL
R
0
1
2
3
4
5
6
7
O
^a1
^a1
^a2[0]
^a2[0]
^a2[1]
^a2[1]
&PubB1
&PubB1
1
&PubB1
&PubB1
&PubB1
&PubB1
&Pb2[0]
&Pb2[0]
&Pb2[0]
&Pb2[0]
2
&Pb2[0]
&Pb2[0]
&Pb2[1]
&Pb2[1]
&Pb2[1]
&Pb2[1]
&Pb2[1]
&Pb2[1]
W0
4.4.2 Symbol Listing
The map listings are followed by a symbol listing that consists of memory and flag symbol
information.
(1) Option
Specify -MAP to produce a module-specific symbol listing, or -AMA[P] to produce a
symbol listing for an entire program.
4 - 18
DOC17K User's Manual
Chapter 4
Output Listing
(2) Output files
• Module map list (.MAP)
-MAP
: REL filename.MAP
-MAP=<filename> : <filename>.MAP
If more than one module is named, a map listing is produced
for each of the named modules.
• Program map listing (.AMP)
-AMA[P]
: Parameter filename.AMP
-AMA[P]=<filename> : <filename>.AMP
A map listing consisting of symbols from multiple modules
is produced.
(3) Output details
SYMBOL VALUE TYPE BIT INFORMATION
The table below details the line format.
Legend
Output value
Explanation
SYMBOL
Symbol name
Symbol name. When a symbol name exceeds the value of SYMLENGTH, (one double-byte character or two single-byte
characters), only the symbol name is output on the first line. All
the information following VALUE is directed to the subsequent
lines.
Evaluation value
(VALUE)
32 bits (hexadecimal)
Refer to the RA17K User’s Manual for details.
Type (TYPE)
DAT
Data type
MEM
Memory type
Nn
Horizontal nibble memory type
NnV
Vertical nibble memory type
LAB
Label type
FLG
Flag type
BIT
Bit position
INFORMATION
1
…1
2
..1.
4
.1..
8
1…
STR
Structure
UNI
Union
ARY
Array
–
Contents of the comment on the symbol definition line
DOC17K User's Manual
4 - 19
Chapter 4
Output Listing
[Sample output]
RA17K V1.00 V1
<< D17XXX
SYMBOL MAP >> HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE. ASM
SYMBOL
VALUE
TYPE BIT INFORMATION
ABC_MEM
00000010 MEM
WORK
00000021 FLG …1 ; Local variable
ABC_NIB
00001003 N2
; NIBBLE 2
XYZ_NIBV
00009004 N2V
; NIBBLE 2 V
STRUCT
00000000 STR
; Structure
UNION
00000000 UNI
; Union
ARRAY
00000000 ARY
; Array
; Public variable
4.5 Report Listing
A report listing provides a record of the status of assembly execution, including the assembly
time spent, the status of memory utilization, and file information.
(1) Option
Specify -REP[ORT] to output a report listing.
(2) Output file
Report listing (.REP)
(3) Output details
(a) Run durations
The time at which assembly started, the time at which it ended, and the elapsed
time. If more than one module is named, run durations are listed in sequence.
(b) Status of memory utilization
The memory utilization status for the assembler. If more than one module is
named, the memory utilization status is output for each of the named modules.
(c) File information
The sizes of the files used by the assembler. If more than one module is named,
file information is output for each of the named modules.
4 - 20
DOC17K User's Manual
Chapter 4
Output Listing
[Sample output]
RA17K V1.00 V1
<< D17XXX
REPORT LIST >> HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
<ELAPSED TIME>
PROCESS
START
END
ELAPSED
ASSEMBLER(TEST1. ASM)
13:02:05
13:03:17
00:01:12
ASSEMBLER(TEST2. ASM)
13:04:00
13:05:17
00:01:17
COMPILER(SAMPLE3. MLC)
13:05:20
13:06:03
00:00:43
COMPILER(SAMPLE4. MLC)
13:06:04
13:06:17
00:00:13
TOTAL
DOC17K User's Manual
00:03:25
4 - 21
Chapter 4
Output Listing
RA17K V1.00 V1
<< D17XXX
REPORT LIST >>
10:34:40 04/22/93 PAGE 002
PROG = SAMPLE
SOURCE = TEST1. ASM
< USED MEMORY >
MEMORY BLOCKS
SIZE
USED
REL
TMP
4317
259
6.0
REL
TMP
2269
669
29.1
REL
TMP
4317
515
11.9
REL
FILE
4341
1145
26.4
INTERM
TMP
8413
242
2.9
XREF
FILE
8437
245
2.9
SYMBOL
MAIN
16384
16384
100.0
SYMBOL
EMS
0
0
0.0
LIST
TMP
4341
393
9.1
5223
520
10.0
ETC
PERCENT
< USED FILES >
FILE NAMES
SIZE
C:\RA17K\SYSTEM\REP17K\TEST1. REL
900
C:\RA17K\SYSTEM\REP17K\TEST1. IXF
0
C:\RA17K\SYSTEM\REP17K\TEST1. IPN
148
(4) Coding a format definition file
A format definition file can be specified with the -RFMT option to output a report
listing in a user-specified format.
A format definition file is coded by preceding each line with a line control character.
Normal lines are marked by ”N,” the last line by ”P.” The last line is mandatory.
Item coding formats are described below.
(a) %D#item-name [,number-of-characters]%
Item-name may be either a reserved item name or a user-defined item name.
If number-of-characters is omitted, the item is output using the number of
characters of item-name.
4 - 22
DOC17K User's Manual
Chapter 4
Output Listing
If one item name is specified per line when number-of-characters is omitted, the
column length can be adjusted by coding ”%S%”. If more than one item name
is specified per line, however, the column length cannot be adjusted.
Each occurrence of ”%D#item-name” in the intermediate PRN file is replaced with
the specified item upon detection.
(b) %S%
Code ”%S%” to adjust the column length. Pad each line with blanks to align the
last character with the end of the line.
(c) %R-character%
Code ”%R-character%” to specify a repetition character. The character immediately after %R%” is output repeatedly with column length adjustment.
(d) Other characters
All other characters and lines are output as is.
[Sample coding]
Definition
Output
N
%D#TITLE, 8%
8 columns
Adjust the column length
N
%D#TITLE%%S%
Adjust the column length with %S%
N
%R—%
Number of characters
for an item
Caution
DOC17K User's Manual
When a fixed character and an item appear on the same
line of the format definition file, the fixed character is output
repeatedly, the specified number of items. To output a
fixed character once only, code it on a different line.
4 - 23
Chapter 4
Output Listing
[Sample coding for a format definition file]
$PROCESSFORM
N< ELAPSED TIME >
N
N
%R
N
PROCESS%S%
N
%R
N
%D#PROC%%S%
N
%R
N%S%
%
START
END
ELAPSED
%
%D#START, 8%
%D#FINISH, 8%
%D#ELAPSE, 8%
%
TOTAL
%D#TOTAL, 8%
P%S%
$MEMORYFORM
N< USED MEMORY >
N
N
%R
%
N
MEMORY BLOCKS%S%
N
%R
SIZE
USED
PERCENT
%
N
%D#MEM%%S%
P
%R
%D#MSIZE, 8%
%D#MUSED, 8%
%D#PER, 8%
%
$FILESFORM
N
N< USED FILES >
N
N
%R
N
FILE NAMES%S%
%
N
%R
N
%D#FILE%%S%
P
%R
SIZE
%
%D#FSIZE, 8%
%
4.6 Document Listing
4.6.1
Document Listing
A document listing is a listing output according to a format definition, on the basis of the
-SUM[MARY] and module information.
The general format of a document listing is shown below.
(1) Contents
(2) Program Specifications
(a) Program summary
(b) Module summary
(c) Routine summary
4 - 24
DOC17K User's Manual
Chapter 4
Output Listing
(1) Option
Specify -SPE[C] to output a document listing.
(2) Output file
Document listing (.SPC)
(3) Contents
(a) Contents
The title assigned to each block is output as a table of contents. Each block can
be divided into units such as chapters, sections, items, and subitems.
Table 4-1. Relationship Between Components of Contents and
Program Units
Component
Corresponding program unit
Chapter
Module file
Section
Routine (function)
Item
Tag
Subitem
Tag (hierarchical level)
A typical contents presentation format is as follows:
Chapter
: Chapter 1, Chapter 2, ..., Chapter n
Section
: 1.1. 1.2, ..., n.n
Item level 1
: 1.1.1, 1.1.2, ..., n.n.n
Item level 2
: (1), (2) ..., (n)
Item level 3
: (a), (b), ... (z)
Item level 4
: <1>, <2>, ..., <20>
[Sample output]
<Header statement> The #toc character string specified in the format definition file is
output.
Chapter 1 Module Title
1
1.1
Section Title
2
1.1.1 Routine Title
3
DOC17K User's Manual
(1) Tag title 1
3
(2) Tag title 2
3
(3) Tag title 3
3
4 - 25
Chapter 4
Output Listing
(b) Program Specifications
Program specification text, directed by a format definition, is created by program,
module, and routine according to the -SUM[MARY] and module information.
(i) Program summary
The contents of the file specified by -SUM[MARY] are output as a program
summary as is. The file contents can be coded freely at the user desires.
[Sample coding]
• Option
-SPEC -SUMMARY=’Program Title’,SUM.TXT
• Contents of SUM.TXT
Program name: SAMPLE.EXE
Program summary file. The information contained in this file is
output as a program file.
[Program summary: Sample output]
Program Title
Program name: SAMPLE.EXE
Program summary file. The information contained in this file is output
as a program file.
(ii) Module summary
The information written in the module block is edited and output according
to the format definition. The output format is the same for both RA17K and
emlC-17K.
A document listing, output as explained in [Sample coding of a format
definition file] in Section 4.6.3(3), is given on the following pages.
4 - 26
DOC17K User's Manual
Chapter 4
Output Listing
[Module summary: Sample output]
RA17K V1.00 V1
<< D17XXX
DOCUMENT LIST >> HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
Chapter 1. Initial Institution
[specifications]
Module Summary
Module Name
Create
Size
Step
:
:
:
:
INITIAL. ASM
92/07/01
4096
20
PUBLIC (MEM)
PUBLIC (FLG)
PUBLIC (DAT)
PUBLIC (LAB)
EXTRN (MEM)
EXTRN (FLG)
EXTRN (DAT)
:
:
:
:
:
:
:
PUB_MEM
PUB_FLG
PUB_DAT
PUB_LAB
EXT_MEM
EXT_FLG
EXT_DAT
EXTRN (LAB)
: EXT_LAB
13:12:11
(iii) Routine summary
The information written in the routine block is edited and output according
to the format definition. The output format is the same for both RA17K and
emlC-17K.
For RA17K, however, input/output information is not output.
DOC17K User's Manual
4 - 27
Chapter 4
Output Listing
[Routine summary: Sample output]
RA17K V1.00 V1
<<D17XXX DOCUMENT LIST>>
HH:MM:SS MM/DD/YY PAGE 002
PROG = SAMPLE
2.1 Volume Control
[specifications]
Routine Summary
[Routine Information]
Input
OutPut
Address Range
EPA Address Range
JumpT Address Range
Entrances
MEM Changed
MEM Referred
MEM Manipulatd
FLG Changed
FLG Referred
DAT Referred
Branch To
Subroutines Called
LAB Manipulated
System Call
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
nibble a
dword b
0 - 1F
10020 - 1002F
0-0
INIT
M_CHG
M_REF
F_CHG
F_REF
D17005_INIT
2.1.1 MODE_KEY
Delay change
Delay key
Delay institution
4.6.2 Summary Rules
The summary rules described in each module (source file) are presented. A comment
symbol is not needed between the SUMMARY and ENDSUM statements. #pragma summary
is presented in a comment format. Summaries cannot be nested by themselves.
Summary statements appearing in tags are directed to the tag table of the program
specifications.
4 - 28
DOC17K User's Manual
Chapter 4
Output Listing
Figure 4-3. Summary Layout
<Module>
Summary 1 (Module summary)
Summary 2 (Routine summary)
<Sections, functions>
<Tag>
<Tag>
<Tag>
Tags can be nested
<Tag>
Tags can be nested
<Tag>
Tags can be nested
(1) Program summary
(a) Title
The information specified with -SUM[MARY].
(b) Summary statement
Defined in the separate file for program summary statements, as named by
-SUM[MARY]. See Section 4.6.1(3)(b)(i).
DOC17K User's Manual
4 - 29
Chapter 4
Output Listing
(2) Module summary
(a) Title
The title of a module summary is specified by pseudo instructions SUMMARY
to ENDSUM (#pragma summary to #pragma end_summary) at the beginning of
the corresponding module. The module filename is assumed as the title when
no title is explicitly specified.
(b) Summary statement
A summary statement is specified by pseudo instructions SUMMARY to ENDSUM
(#pragma summary to #pragma end_summary) at the beginning of the corresponding module.
(3) Routine summary (section or function)
(a) Title
The title of a routine summary is specified by pseudo instructions SUMMARY to
ENDSUM (#pragma summary to #pragma end_summary) that precede the
section or function definition statement. The section or function name is assumed
as a title when no title is explicitly specified.
(b) Summary statement
A summary statement is specified by pseudo instructions SUMMARY to ENDSUM
(#pragma summary to #pragma end_summary) immediately before the section
or function definition statement.
(4) Tag
(a) Title
Tag titles are specified with ”;.” or ”;.V” for RA17K, or with ”//.” for emlC-17K. This
hierarchical level is terminated by ”;..” or ”//..”. Titles can be nested.
The character strings (. and ..), following a comment symbol, can be altered by
using RA17K options -TAGS[TART] and -TAGE[ND].
(b) Summary statement
Any comment statement appearing after a tag line is handled as a summary
statement. A summary statement is terminated by a non-comment line.
4 - 30
DOC17K User's Manual
Chapter 4
Output Listing
[Sample summary coding 1: RA17K]
; Sample Summary
SUMMARY ’Module name title’
Provides a summary of the module (may be omitted).
ENDSUM
SUMMARY ’Routine title’
Provides a summary of the routine (may be omitted).
ENDSUM
PROG1 CSEG
<Program>
;. Tag title
;
The comment following the tag is assumed to be a summary statement
;
The summary statement is terminated by other than a comment statement
;. V
;
The immediately subsequent label is registered as a tag
;
A comment following a tag is regarded as being a summary statement
;
The summary statement is terminated by other than a comment statement
LABEL1:
<Program>
SUMMARY <- The section name is assumed as the title when no title is explicitly specified.
Provides a summary of the routine (may be omitted).
ENDSUM
PROG2 CSEG
<Program>
END
DOC17K User's Manual
4 - 31
Chapter 4
Output Listing
[Sample summary coding 2: emlC-17K]
// Sample Summary
#pragma summary
//
’Module name title’
Provides a summary of the module (may be omitted).
#pragma end_summary
#pragma summary
//
’Routine title’
Provides a summary of the routine (may be omitted).
#pragma end_summary
void prog1(void)
{
< Program >
//.
Tag title 1
//
A comment following the tag is assumed to be a summary statement
//
The summary statement is terminated by other than a comment statement
< Program >
//.
Tag title 2
//
Tags may be nested
//..
//..
< Program >
}
#pragma summary <– The function name is assumed as the title when no title is explicitly specified.
//
Provides a summary of the routine (may be omitted).
#pragma end_summary
void prog2(void)
{
< Program >
}
4 - 32
DOC17K User's Manual
Chapter 4
Output Listing
4.6.3 Format Definition
A format definition file can be specified with the -DFMT option to produce a document
listing in a user-specified format. The document listing utility produces a document file
according to the information defined in the format definition file.
The format definition file contains a definition of the item names and item functions, the
output file format and so on. Users can perform customization by modifying the format
definition file.
Because item name replacement begins at character position ”%”, a sufficiently large
space must be allowed between occurrences of %, or between % and any other delimiter
(such as a line). When a replacement character string is too long to be inserted, the
excess characters are truncated. If more than one replacement character string is specified,
the strings are output at the same position on the next line once the item names have
been exhausted for the current line.
(1) Format definition file format
The table below describes the coding format for the format definition file.
#item
<item-name>:<alias>:<summary-level>
#row
<number-of-lines-per-page>
#column
<number-of-columns>
#toc
<contents>
#idn
<item-number-format> n: level number(Note)
#moduleform
Module specification format
#routineform
Routine specification format
(Note) Item number formats are as follows:
1 = Chapter n (double-byte characters)
7 = (n)
(single-byte characters)
2=n
(double-byte characters)
8 = (a)
(double-byte letters)
3=n
(single-byte characters)
9 = (a)
(single-byte letters)
4 = n. n ...
(double-byte characters)
10 = <1> to <20> (double-byte characters>
5 = n.n ...
(single-byte characters)
11 = .
(double-byte characters)
6 = (n)
(double-byte characters)
12 = .
(single-byte characters)
(2) Item name
The contents of the item specified by an item name in the format definition file are
retrieved from the source module to replace each occurrence of the item name.
DOC17K User's Manual
4 - 33
Chapter 4
Output Listing
(a) Reserved item name
The table below lists reserved item names.
Table 4-2. Reserved Item Names in the Format Definition File
Item name
Explanation
Item name
Explanation
FileName
Module filename
JMPTEndAddr
Branch table ending address
FileSize
Module file size
RoutineName
Routine name
FileDate
File creation date
Public
Public symbol
FileTime
File creation time
Extrn
External symbol
Title
Title
Entry
Entry point
Step
Number of steps in the module
MemRef
Memory reference
Input
Function input interface
MemChg
Memory change
Output
Function output interface
FlgRef
Flag reference
TopAddr
Starting address
FlgChg
Flag change
EndAddr
Ending address
LabRef
Label reference
EPATopAddr
EPA starting address
LabChg
Label change
EPAEndAddr
EPA ending address
Call
Routine call
JMPTTopAddr
Branch table starting address
Br
Branch
(b) User-defined item name
Users can register user-defined items. When an item name is omitted, the item
contents for the preceding item name are assumed. Item contents having the
same item name are linked together.
Continuation of the item contents terminates when the next item name or a blank
line is encountered.
[Item name sample coding: RA17K]
;
<item-name>
;
:
<item-contents>
:
<continuation-of-item-contents>
;
[Item name sample coding: emlC-17K ]
//
//
<item-name>
:
<item-contents>
:
<continuation-of-item-contents>
//
4 - 34
DOC17K User's Manual
Chapter 4
Output Listing
[Examples of user-defined item names]
User-defined item name
Item contents
Coding position in a source module
System
System (program) description
Module summary
Program
Program name
Module
Module description
Revision
Revision number
Manager
Manager name
Routine
Routine description
Spec
Routine specifications
Author
Author
Note
Memo
Routine summary
(3) Coding a format definition file
A line that begins with ”;” is a comment line. Comment lines can be specified anywhere
other than in moduleform and routineform.
A format definition file containing a specification of user-defined item names, the
number of lines per page in the document list, the number of columns, the character
string in the contents, and so on.
Unless otherwise specified, the values listed below are assumed.
#item
No user-defined item
#row
Value specified by -ROW, or the default
#column
Value specified by -COL[UMN], or the default
#toc
Character string ”Contents”
#id1
Item format 1 (Chapter 1)
The format definition file then proceeds with moduleform and routineform, which are
coded the same way. A format definition file is coded by preceding each line with
a line control character. Normal lines are marked by ”N,” the last line by ”P.” The
last line is mandatory.
Item coding formats are described below.
(a) %D#item-name[,number-of-characters]%
Item-name may be either a reserved item name or a user-defined item name.
If number-of-characters is omitted, the number of characters of item-name is
assumed.
DOC17K User's Manual
4 - 35
Chapter 4
Output Listing
If one item name is specified per line when number-of-characters is omitted, the
column length can be adjusted by coding ”%S%”. If more than one item name
is specified per line, however, the column length is not adjustable.
Each occurrence of ”%D#item-name” in the intermediate PRN file is replaced with
the specified item as it is encountered.
(b) %S%
Code ”%S%” to adjust the column length. Pad each line with blanks to align the
last character with the end of the line.
(c) %R-character%
Code ”%R-character%” to specify a repetition character. The character following
%R%” is output repeatedly with column length adjustment.
(e) Other characters
All other characters and lines are output as is.
[Sample coding]
Definition
N
%D#TITLE, 8%
8 columns
Adjust the column length
N
%D#TITLE%%S%
%R—%
Number of characters
for an item
Adjust the column length with %S%
N
Caution
4 - 36
Output
When a fixed character and an item appear on the same
line of the form definition file, the fixed character is output
as many times as the number of items specified. To output
a fixed character once only, code it on a different line.
DOC17K User's Manual
Chapter 4
Output Listing
[Sample coding for a format definition file]
#item
#row=66
#column=250
#toc= ’Contents’
#id1=1
; Chapter 1
#id2=4
; 1. 1
#id3=4
; 1. 1. 1
#id4=6
;(1)
#id5=8
;(a)
#id6=10
; <1>
$moduleform
N
%R—%
N
%D#ID1, 10% %D#TITLE, 10%%S%
N –%R—%–
N
[Spec if ic at ions]%S%
N
%D#Contents%%S%
N –%R—%–
N
Module Name
: %D#FileName%%S%
N
Create
: %D#FileDate% %D#FileTime%%S%
N
Size
: %D#Size%%S%
N
Step
: %D#Step%%S%
N –%R—%–
N
PUBLIC(MEM)
: %D#PubMem%%S%
N
PUBLIC(FLG)
: %D#PubFlg%%S%
N
PUBLIC(DAT)
: %D#PubDat%%S%
N
PUBLIC(LAB)
: %D#PubLab%%S%
N
EXTRN(MEN)
: %D#ExtMem%%S%
N
EXTRN(FLG)
: %D#ExtFlg%%S%
N
EXTRN(DAT)
: %D#ExtDat%%S%
N
EXTRN(LAB)
: %D#ExtLab%%S%
P
%R—%
DOC17K User's Manual
4 - 37
Chapter 4
Output Listing
$routineform
N
%R—%
N
%D#ID2, 10% %D#ROUTINE, 10%%S%
N –%R—%–
N
[Specifications]%S%
N
%D#Contents%%S%
N –%R—%–
N
[Routine Information]%S%
N
Input
: %D#Input%%S%
N
Output
: %D#Output%%S%
N
Address Range
: %D#TopAddr% - %D#EndAddr%%S%
N
EPA Address Range
: %D#EPATopAddr% - %D#EPAEndAddr%%S%
N
JumpT Address Range : %D#JMPTTopAddr% - %D#JMPTEndAddr%%S%
N
Entrances
: %D#Entry%%S%
N
MEM Changed
: %D#MemChg%%S%
N
MEM Referred
: %D#MemRef%%S%
N
MEM Manipulated
: %D#MemMan%%S%
N
FLG Changed
: % D # F l g C h g %%S %
N
FLG Referred
: %D#FlgRef%%S%
N
DAT Referred
: %D#DatRef%%S%
N
Branch To
: %D#Br%%S%
N
Subroutines Called
: %D#SubCall%%S%
N
LAB Manipulated
: %D#LabMan%%S%
N
System Call
: %D#SysCall%%S%
N –%R— %–
N
P
4 - 38
%D#ID2% %D#TAG%%S%
%R—%
DOC17K User's Manual
Chapter 4
Output Listing
4.7 Call Tree Listing
A call tree listing consists of a hierarchical listing of modules/routines (call tree format).
The characters following the function names have the following meanings:
?
: Undefined routine (undefined external reference)
... : Tree already displayed
[n] : n in [n] indicates the ID number with which the tree is displayed.
Function names that are defined but not referenced are labeled <UNREFERENCE>.
Caution
A call tree listing is produced only for the emlC-17K source
program.
[Sample output]
MLC17K V1.00 V1
<< D17XXX
TREE LIST >>
HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
main
1
initialize_table
1
clear_buffer
2
set_table
2
initialize_key
1
key_xxxx ?
2
key_yyyy
3
display
1
menu
1
function_one
1
set_func [3.1.1.1]
1
exec_key
2
function_two
1
set_func. . . [3.1.1.1]
3
function_three
1
set_func. . . [3.1.1.1]
2
modify_mode
DOC17K User's Manual
4 - 39
Chapter 4
Output Listing
MLC17K V1.00 V1
<< D17XXX
TREE LIST >>
HH:MM:SS MM/DD/YY PAGE 002
PROG = SAMPLE
4
function_four
1
set_func. . . [3.1.1.1]
2
change_case
1
attriv
1
convert_mode
5
function_end
1
set_func. . . [3.1.1.1]
2
perform
4
exit
MLC17K V1.00 V1
<< D17XXX
TREE LIST >>
HH:MM:SS MM/DD/YY PAGE 003
PROG = SAMPLE
< UNREFERENCE >
unref_func1
unref_func2
4.8 Module Listing
A module listing is a routine list specific to a module file. Its output format is specified
in a format definition file.
Caution
When source programs have been assembled using RA17K,
a section name is output for each routine name field.
(1) Option
Specify -MOD[ULE] to output a module listing.
(2) Output file
Module listing (.MOD)
(3) Output details
A sample listing is shown below.
4 - 40
DOC17K User's Manual
Chapter 4
Output Listing
(a) Module filename, creation date and time, and file size (includes the
filename, creation date and time, and file size)
(b) Routine name, number of source steps, and address range
The address range includes an EP area (headed by @), and a branch table
(headed by ?) if any.
[Sample module listing]
MLC17K V1.00 V1
<< D17XXX
MODULE LIST >>
HH:MM:SS MM/DD/YY PAGE 01-001
PROG = SAMPLE
SOURCE = SAMPLE1.MLC
MODULE NAME
CREATED DATE/TIME
FILE SIZE
c:program\source\main.mlc
1991/12/16 10:00:00
1234
c:\mll\include\stdio. h
c:\mll\devfile\dl7006. h
c:program\source\sub
1991/10/30 00:00:00
1991/11/01 00:00:00
1991/12/16 12:00:00
324
549
1021
ROUTINE NAME
initialize_table (void)
static clear_buffer (nibble ∗buffer)
static set_table (void)
@_set_table
?_set_table
DOC17K User's Manual
SRC STEPS
33
54
109
-
ADDRESS RANGE
00100 - 00123
00124 - 00129
0012A - 0014F
10150 - 1015F
00000 - 00000
4 - 41
Chapter 4
Output Listing
RA17K V1.00 V1
<< D17XXX
MODULE LIST >> HH:MM:SS MM/DD/YY PAGE 02-001
PROG = SAMPLE
SOURCE = SAMPLE2. ASM
MODULE NAME
CREATED DATE/TIME
FILE SIZE
c:program\source\keyfunc. asm
1991/12/16 10:03:00
1932
c:\include\keyfunc1.asm
c:\include\keyfunc2. asm
1991/10/30 00:00:00
1991/11/01 00:00:00
324
549
ROUTINE NAME
initialize_key
clear_key_buffer
set_key_table
SRC STEPS1
133
98
202
ADDRESS RANGE
00150 - 00153
00154 - 00179
0017A - 0017F
4.9 Address Map
An address map file contains routines (functions) and variables assigned in ROM. An
address map is output page by page (PAGE0 to PAGE3).
Caution
When source programs have been assembled using RA17K,
a section name is output in each routine name field.
(1) Option
Specify -PMA[P] to produce an address map.
(2) Output file
Module file (.MOD)
(3) Output details
A sample listing is shown below.
4 - 42
DOC17K User's Manual
Chapter 4
Output Listing
[Sample address map]
RA17K V1.00 V1
<<D17XXX ADDRESS MAP>>
HH:MM:SS MM/DD/YY PAGE 001
PROG = SAMPLE
SEGMENT NO = x
ROUTINE NAME/VARIABLE
MODULE NAME
?_initialize
main. asm
initialize
main. asm
00100 - 00123
@_initialize
main. asm
10124 - 1012F
PAGE1
clear
sub . asm
00800 - 0012F
PAGE2
input
sub2. asm
01000 - 0130E
PAGE3
output
sub3. asm
01800 - 0004F
PAGE0
DOC17K User's Manual
ADDRESS
00000 - 00000
4 - 43
Chapter 4
Output Listing
[MEMO]
4 - 44
DOC17K User's Manual
Chapter 5
Error Messages
5.1 Error Handling
If an error is detected in any of the options specified in the execution of a listing utility,
control immediately returns to DOS. The listing utility is not run. Correct the option
before attempting to rerun the utility.
If an error is detected while a listing utility is running, control again returns to the calling
process by canceling the execution of the listing utility.
If the parent process is DOS, the DOS prompt is displayed to prompt the user to enter
a command. If the parent process is DOC17K, the listing utility having the next highest
priority is run. Control returns to DOS if there is no other listing utility to run.
Once the error has been corrected, the listing utility may be rerun to output the desired
listing.
5.2 Error Messages
Error messages are output upon the detection of an error during the execution of a listing
utility. Table 5-1 lists the error messages that may be output.
[Message format]
error CNNN: error-message ’error-information’
Remarks 1.
2.
C designates an error code.
A: Abort error F: Fatal error W: Warning error
NNN: Error number (three decimal digits)
[Sample output] Error found in an option
error A003: Invalid option ’option-name’
DOC17K User's Manual
5-1
Chapter 5
Error Messages
Table 5-1. Error Messages (1/5)
Message number
Explanation
A003
Message
Invalid option
Cause
There is an error in the option.
Action
Correct the option.
Message
No Input File
Cause
An input filename is not specified.
Action
Specify a REL filename.
Message
Too many files
Cause
More than one input filename has been specified.
Action
Specify only one input filename (REL file or parameter file).
Message
Couldn't set SIGINT
Cause
The CTRL + C interrupt handler cannot be set.
Action
Rerun.
Message
Illegal character
Cause
The filename contains an illegal character.
Action
Specify a valid filename.
Message
No LNK option
Cause
The -LNK option is not specified.
Action
Specify the -LNK option.
Message
Invalid file format
Cause
The format of the option file to be passed to the process is invalid.
Action
Delete the ”.$$$” files and rerun.
Message
Invalid REL format
Cause
The format of the REL file is invalid.
Action
Reassemble, or recompile and relink.
Message
Invalid LNK format
Cause
The LNK file has an invalid format.
Action
Reassemble, or recompile and relink.
A004
A005
A006
A007
A008
A009
A010
A011
5-2
DOC17K User's Manual
Chapter 5
Error Messages
Table 5-1. Error Messages (2/5)
Message number
Explanation
A012
Message
Not enough memory
Cause
The size of the work area is insufficient.
Action
Create a sufficiently large work area.
Message
No section/function name
Cause
The section or function name is not defined in the LNK file.
Action
Reassemble, or recompile and relink.
Message
No object code
Cause
The object code is not defined in the LNK file
Action
Reassemble, or recompile and relink.
Message
Invalid XREF data
Cause
There is no correspondence between the XREF data and the REF file.
Action
Reassemble, or recompile and relink.
Message
Invalid Input file extension
Cause
The input filename does not have the REL extension.
Action
Specify a REL file as an input file.
Message
No get section addr
Cause
The section address cannot be obtained from the LNK file.
Action
Reassemble, or recompile and relink.
Message
No get section name
Cause
The section name cannot be obtained from the REL file in the ABS mode.
Action
Reassemble, or recompile and relink.
Message
Source file name not found in REL
Cause
The source filename cannot be found in the REL file.
Action
Reassemble, or recompile and relink.
Message
List file name not found in REL
Cause
The list filename cannot be found in the REL file.
Action
Specify the list output option and reassemble, or recompile and relink.
A013
A014
A015
A016
A017
A018
A019
A020
DOC17K User's Manual
5-3
Chapter 5
Error Messages
Table 5-1. Error Messages (3/5)
Message number
Explanation
A021
Message
XREF file name not found in REL
Cause
The XREF filename cannot be found in the REF file.
Action
Specify the XREF output option, then reassemble, or recompile and relink.
Message
Summary file name not found in REL
Cause
The summary filename cannot be found in the REL file.
Action
Specify the summary output option, then reassemble, or recompile and relink.
Message
Invalid Source Number
Cause
The source line number cannot be found in the intermediate PRN file.
Action
Reassemble, or recompile and relink.
Message
Invalid Nest Number
Cause
The expansion line number cannot be found in the intermediate PRN file.
Action
Reassemble, or recompile and relink.
Message
Internal error (xxx)
Cause
An error was detected during internal processing.
Action
Contact your dealer or NEC.
Message
Invalid symbol number
Cause
The symbol number is invalid.
Action
Reassemble, or recompile and relink.
Message
Format data item error
Cause
There is an error in a data item name specified in the format definition file.
Action
Correct the data item name specified in the format definition file.
A022
A023(Note 1)
A024(Note 2)
A025
A026
A027
(Note 1) W023 for MAP.EXE and AMAP.EXE.
(Note 2) W024 for MAP.EXE and AMAP.EXE.
5-4
DOC17K User's Manual
Chapter 5
Error Messages
Table 5-1. Error Messages (4/5)
Message number
Explanation
A028
Message
Format data error
Cause
There is an invalid entry in the specified format definition file.
• A character other than ”N,” ”P,” or ”;” was encountered at the beginning of a line.
• The correspondence of ’%’ is unmatched.
• An invalid format control code was found.
• An extra or lacking entry is found between separate occurrences of %.
• The column length exceeds the default, or the value specified as an option.
• There is more than one column length adjustment on one line.
• The last line specification is missing.
• An odd number of columns must be adjusted when a double-byte character is
specified as a repeat character.
A029
A030
A031
A032
A033
A034
Action
Correct the format definition file.
Message
Invalid line format
Cause
The coding format of the title character string is invalid.
Action
Correct the format of the title character string.
Message
Invalid command format
Cause
The coding format of the output format specification command is invalid.
Action
Correct the command format.
Message
Not Found Line Number
Cause
A line number specified in the summary file cannot be found in the list file.
Action
Reassemble, or recompile and relink.
Message
Log file name not found in REL
Cause
The log filename is not found in the REL file.
Action
Reassemble, or recompile and relink.
Message
Invalid Log file format
Cause
The format of the log file is invalid.
Action
Reassemble, or recompile and relink.
Message
Invalid summary file format
Cause
The format of the summary file is invalid.
Action
Reassemble, or recompile and relink.
DOC17K User's Manual
5-5
Chapter 5
Error Messages
Table 5-1. Error Messages (5/5)
Message number
Explanation
A035
Message
Invalid symbol file format
Cause
The format of the symbol file is invalid.
Action
Reassemble, or recompile and relink.
Message
Invalid PPL file format
Cause
The format of the preprocessing file (.PPL) is invalid.
Action
Reassemble, or recompile and relink.
Message
Function multi defined
Cause
A function name is defined more than once.
Action
Correct the function name then rerun.
Message
Function nest overflow
Cause
The function call nesting level exceeds 40.
Action
Reduce the function call nesting level to 40 or less.
Message
Symbol file name not found in REL
Cause
The symbol filename cannot be found in the REL file.
Action
Reassemble, or recompile and relink.
Message
Option not implemented
Cause
An illegal option has been specified.
Action
Remove the illegal option.
A036
A037
A038
A039
A040
5.3 System Error Messages
In addition to the error messages covered in the previous section, system error messages
may also be output. A system error message might be output, for example, if a file
access request is issued to the OS or if an error is posted from the OS.
[Message format]
Filename: system-error-message
[Sample output] A file cannot be found.
SAMPLE.REL: A file or directory cannot be found
5-6
DOC17K User's Manual