         


























                             DECUS C LANGUAGE SYSTEM


                                  Tool Library
                                Reference Manual


                                       by

                                  Martin Minow







        This  document  describes a number of tools, written in C.  Most
        of these do not require any knowlege of,  or  interest  in,  the
        language C itself.  


                         DECUS Structured Languages SIG

                              Version of 11-Nov-83


                                      NOTE

             This  software  is  made available without any support
             whatsoever.    The   person   responsible    for    an
             implementation of this system should expect to have to
             understand and modify the source code if any  problems
             are  encountered  in  implementing  or maintaining the
             compiler  or  its   run-time   library.    The   DECUS
             'Structured  Languages  Special Interest Group' is the
             primary focus for communication among  users  of  this
             software.  



        UNIX  is  a  trademark  of  Bell  Telephone  Laboratories.  RSX,
        RSTS/E,  RT11  and  VMS  are  trademarks  of  Digital  Equipment
        Corporation.  



        1.0  General Considerations 

        With few exceptions, all Decus C tools use a Unix-like method of
        passing parameters to the program, allowing for  redirection  of
        the  "standard"  input-output  devices.   This section describes
        overall tool installation and the parameter passing mechanism.  


        1.1  Installing the Tools 

        The  tools  are compiled and linked with the C run-time library.
        The resulting executable program (.TSK, .SAV, or  .EXE)  may  be
        copied to a convenient directory.  The following conventions are
        used:  

              o  On RSTS/E, the tools are copied to the account named in
                 the system-wide logical "PUB:".  In order  to  use  the
                 supplied  command  files  without  editing,  the system
                 manager  must  have   defined   this   account   as   a
                 "system-wide logical".  

                 Decus  C  programs  can be run using the RSTS/E consise
                 command (CCL) facility.  If the system manager does not
                 wish  to install all programs as CCL commands, the CRUN
                 program, written in  Basic-Plus  may  be  compiled  and
                 installed.   You  may  then  run a tool (or any Decus C
                 program) by a command such as 

                        CRUN Disk:[P,Pn]file argument list 

                 where "Disk[P,Pn]" indicates the disk and account where
                 the executable program is stored.  CRUN chains  to  the
                 program,  passing  the  argument list in a common area.
                 It is very specific to RSTS/E.  

              o  On  VMS,  the  tool build process writes the executable
                 image to the user-defined logical  "BIN:".   Tools  are
                 "installed" by the foreign command definition:  

                        $ TOOLNAME :== $BIN:TOOL.EXE 

              o  On  RSX, tools may be installed as known images.  There
                 is  no  equivalent  of  the  CRUN   program   currently
                 available.  

              o  On RT11, tools are RUN.  There is no (supported) way to
                 pass a command line to C programs.  

        When  specifically  RUN  (rather  than  executed via a command),
        (most) tools will prompt for a command line, using a prompt such
        as:  

                Argv> 

        The  user  types  the command line which is parsed and passed to
        the tool's main program.  The specific prompt varies from system
        to system.  If known, the name of the tool will be used.  


        1.2  Argument Lists 

        If a tool is invoked using an argument list as in:  

                tool arg1 arg2 "argument three" 

        the  main  program  will receive the arguments as strings.  Note
        the following:  

              o  Non-quoted arguments are converted to lower-case.  This
                 is compatible with Vax-11 C.  

              o  Argument  strings  may  be quoted using "..." or '...'.
                 Within a quoted string, the other quote  character  may
                 be used.  

              o  Within  an  argument,  the backslash '\' character will
                 quote the next character:  

                        tool don\'t ...  


              o  As will be described, the '<' and '>' characters may be
                 used to specify I/O redirection.  



        1.3  I/O Redirection 

        Normally,  tools  read  from  and  write  to  the user's command
        terminal.  Most tools allow the specific file to  be  redefined,
        allowing  tools  to  be  combined  into  larger  entities.   I/O
        redirection is done as follows:  

              o  If  any  (non-quoted)  argument  begins  with  the  '<'
                 character, the argument will define a file to  be  used
                 for command input.  

              o  If  any  (non-quoted)  argument  begins  with  the  '>'
                 character, the argument will define a file  to  receive
                 normal  output.   If  the  argument  begins  with '>>',
                 output will be appended to the file  (if  supported  by
                 the operating system).  

        Note  that  I/O  redirection  is  not  supported by the Vax-11 C
        run-time library.   A  few  tools,  though  not  all,  implement
        redirection as described above.  
                                                                                                                