Google
 

Trailing-Edge - PDP-10 Archives - integ_tools_tops20_v7_30-apr-86_dumper - tools/si_alter011/alter_32.mem
There is 1 other file named alter_32.mem in the archive. Click here to see a list.



                      STEVENS INSTITUTE OF TECHNOLOGY



                                  Draft #3


                              August 23, 1985



                          Functional Specification

                                    for

                                  ALTER-32


                       File Translation/Modification
   ALTER-32 Function Specificaiton                                 Page 2
   Table of Contents


                                      CONTENTS

           1       INTRODUCTION . . . . . . . . . . . . . . . . . . . . 6
           2       RELATED DOCUMENTS  . . . . . . . . . . . . . . . . . 6
           3       REVISION HISTORY . . . . . . . . . . . . . . . . . . 6
           4       MODULES  . . . . . . . . . . . . . . . . . . . . . . 6
           5       COMMAND FORMAT . . . . . . . . . . . . . . . . . . . 8
           5.1       QUALIFIERS . . . . . . . . . . . . . . . . . . . . 8
           5.1.1     Terminology  . . . . . . . . . . . . . . . . . . . 8
           5.1.1.1   Record types . . . . . . . . . . . . . . . . . . . 8
           5.1.1.2   Sizes and Blocking . . . . . . . . . . . . . . . . 9
           5.1.1.3   Fill characters  . . . . . . . . . . . . . . . . . 9
           5.1.2     Qualifier Defaulting and Consistancy Checks  . . . 9
           5.1.3     Examples . . . . . . . . . . . . . . . . . . . .  11
           5.1.4     Qualifier Descriptions . . . . . . . . . . . . .  12
           5.1.4.1   Global Qualifiers  . . . . . . . . . . . . . . .  12
           5.1.4.1.1 /CONCATENATE . . . . . . . . . . . . . . . . . .  12
           5.1.4.1.2 /FDL=filespec  . . . . . . . . . . . . . . . . .  13
           5.1.4.1.3 /GENERATE  . . . . . . . . . . . . . . . . . . .  13
           5.1.4.1.4 /IGNORE_ERRS . . . . . . . . . . . . . . . . . .  13
           5.1.4.1.5 /LOG[=keyword] . . . . . . . . . . . . . . . . .  13
           5.1.4.1.6 /TEXT  . . . . . . . . . . . . . . . . . . . . .  13
           5.1.4.1.7 /TRANS_FILE[=filespec] . . . . . . . . . . . . .  13
           5.1.4.1.8 /VERIFY  . . . . . . . . . . . . . . . . . . . .  14
           5.1.4.2   Local Qualifiers . . . . . . . . . . . . . . . .  14
           5.1.4.2.1 /FILL=char . . . . . . . . . . . . . . . . . . .  14
           5.1.4.2.2 /ILLEGAL=char  . . . . . . . . . . . . . . . . .  14
           5.1.4.2.3 /SUPPRESS=value  . . . . . . . . . . . . . . . .  14
           5.1.4.3   Positional Qualifiers  . . . . . . . . . . . . .  14
           5.1.4.3.1 /ADJUST=value  . . . . . . . . . . . . . . . . .  14
           5.1.4.3.2 /B_FACTOR=value  . . . . . . . . . . . . . . . .  15
           5.1.4.3.3 /BUFFER=value  . . . . . . . . . . . . . . . . .  15
           5.1.4.3.4 /B_FILL=char . . . . . . . . . . . . . . . . . .  15
           5.1.4.3.5 /B_SIZE=value  . . . . . . . . . . . . . . . . .  15
           5.1.4.3.6 /BYTE_SIZE=value . . . . . . . . . . . . . . . .  15
           5.1.4.3.7 /MASK=value  . . . . . . . . . . . . . . . . . .  15
           5.1.4.3.8 /MAX_REC_SIZE=value  . . . . . . . . . . . . . .  15
           5.1.4.3.9 /REWIND  . . . . . . . . . . . . . . . . . . . .  16
           5.1.4.3.10 /R_SIZE=value . . . . . . . . . . . . . . . . .  16
           5.1.4.3.11 /R_TYPE=keyword . . . . . . . . . . . . . . . .  16
           5.1.4.3.12 /VR_LENGTH=length . . . . . . . . . . . . . . .  16
           5.1.4.3.13 /VR_ZERO_CHAR=value . . . . . . . . . . . . . .  16
           5.2       EXAMPLES . . . . . . . . . . . . . . . . . . . .  16
           5.2.1     Basic Functionality  . . . . . . . . . . . . . .  17
           5.2.2     Logging  . . . . . . . . . . . . . . . . . . . .  18
           5.2.3     Translating  . . . . . . . . . . . . . . . . . .  18
           6       THE TRANSLATION FILE . . . . . . . . . . . . . . .  20
           6.1       OPTIONS  . . . . . . . . . . . . . . . . . . . .  20
           6.1.1     ADJUST=value . . . . . . . . . . . . . . . . . .  21
           6.1.2     BLOCK_FILL=char  . . . . . . . . . . . . . . . .  21
           6.1.3     FDL=filespec . . . . . . . . . . . . . . . . . .  21
           6.1.4     FILL=char  . . . . . . . . . . . . . . . . . . .  21
           6.1.5     IEOLS=string . . . . . . . . . . . . . . . . . .  21
           6.1.6     ILLEGAL=char . . . . . . . . . . . . . . . . . .  21
   ALTER-32 Function Specificaiton                                 Page 3
   Table of Contents


           6.1.7     INPUT_BLOCK_SIZE=value . . . . . . . . . . . . .  21
           6.1.8     INPUT_BYTE_SIZE=value  . . . . . . . . . . . . .  21
           6.1.9     INPUT_END_OF_LINE=char . . . . . . . . . . . . .  22
           6.1.10    INPUT_MAX_RECORD_SIZE=value  . . . . . . . . . .  22
           6.1.11    INPUT_RECORD_TYPE = keyword  . . . . . . . . . .  22
           6.1.12    INPUT_BLOCK_FACTOR=value . . . . . . . . . . . .  22
           6.1.13    INPUT_RECORD_SIZE=value  . . . . . . . . . . . .  22
           6.1.14    MASK=value . . . . . . . . . . . . . . . . . . .  22
           6.1.15    OUTPUT_BLOCK_SIZE=value  . . . . . . . . . . . .  22
           6.1.16    OUTPUT_BYTE_SIZE=value . . . . . . . . . . . . .  22
           6.1.17    OUTPUT_END_OF_LINE=char  . . . . . . . . . . . .  23
           6.1.18    OUTPUT_MAX_RECORD_SIZE=value . . . . . . . . . .  23
           6.1.19    OUTPUT_RECORD_SIZE=value . . . . . . . . . . . .  23
           6.1.20    OUTPUT_RECORD_TYPE=keyword . . . . . . . . . . .  23
           6.1.21    OUTPUT_BLOCK_FACTOR=value  . . . . . . . . . . .  23
           6.1.22    OUT_OF_RANGE=value . . . . . . . . . . . . . . .  23
           6.1.23    RADIX=value  . . . . . . . . . . . . . . . . . .  23
           6.1.24    SUPPRESS=char  . . . . . . . . . . . . . . . . .  23
           6.1.25    TABLE  . . . . . . . . . . . . . . . . . . . . .  24
           6.2       SAMPLE TRANSLATION FILES . . . . . . . . . . . .  24
           7       INTERNALS  . . . . . . . . . . . . . . . . . . . .  25
           7.1       Overview . . . . . . . . . . . . . . . . . . . .  25
           7.2       Require files  . . . . . . . . . . . . . . . . .  26
           7.2.1     ALTER_DEFINITIONS.REQ  . . . . . . . . . . . . .  26
           7.2.2     IO_DEFINITIONS.REQ . . . . . . . . . . . . . . .  27
           7.2.3     CHRDEF.REQ . . . . . . . . . . . . . . . . . . .  27
           7.2.4     ALTER.CLD  . . . . . . . . . . . . . . . . . . .  27
           7.3       Routines . . . . . . . . . . . . . . . . . . . .  27
           7.3.1     ALTER.BLI  . . . . . . . . . . . . . . . . . . .  27
           7.3.1.1   MAIN_DRIVER  . . . . . . . . . . . . . . . . . .  27
           7.3.1.2   BUILD_GENERATE_INFO  . . . . . . . . . . . . . .  28
           7.3.1.3   BUILD_OUTPUT_FILENAME  . . . . . . . . . . . . .  28
           7.3.1.4   DO_LOGGING . . . . . . . . . . . . . . . . . . .  28
           7.3.1.5   CHECK_VERIFY . . . . . . . . . . . . . . . . . .  28
           7.3.1.6   PARSE_THE_INPUT_FILES  . . . . . . . . . . . . .  28
           7.3.1.7   FETCH_NEXT_FILE  . . . . . . . . . . . . . . . .  28
           7.3.1.8   PROCESS_INPUT_FILE . . . . . . . . . . . . . . .  29
           7.3.1.9   PROCESS_FIRST_FILE . . . . . . . . . . . . . . .  29
           7.3.1.10  PROCESS_SUBSEQUENT_FILES . . . . . . . . . . . .  29
           7.3.2     ALTER_XLATE_FILE.BLI . . . . . . . . . . . . . .  29
           7.3.2.1   TRN_PARSE_TRANS_FILE . . . . . . . . . . . . . .  29
           7.3.2.2   TRN_INIT_COLLECT_DIGIT . . . . . . . . . . . . .  29
           7.3.2.3   TRN_COLLECT_DIGIT  . . . . . . . . . . . . . . .  30
           7.3.2.4   TRN_STORE_VALUE  . . . . . . . . . . . . . . . .  30
           7.3.2.5   TRN_STORE_NEXT_VALUE . . . . . . . . . . . . . .  30
           7.3.2.6   TRN_STORE_STRING . . . . . . . . . . . . . . . .  30
           7.3.2.7   TRN_DECLARE_TABLE  . . . . . . . . . . . . . . .  30
           7.3.2.8   TRN_STORE_NEXT_TABLE_VALUE . . . . . . . . . . .  30
           7.3.2.9   TRN_DEFAULT_IN_VARREC  . . . . . . . . . . . . .  31
           7.3.2.10  TRN_DEFAULT_OUT_VARREC . . . . . . . . . . . . .  31
           7.3.3     ALTER_TRANLSATION.BLI  . . . . . . . . . . . . .  31
           7.3.3.1   TRN_TRANSLATE_BYTE . . . . . . . . . . . . . . .  31
           7.3.3.2   MERGE_EFF_INFILE_VALUES  . . . . . . . . . . . .  31
           7.3.3.3   MERGE_EFF_OUTFILE_VALUES . . . . . . . . . . . .  32
   ALTER-32 Function Specificaiton                                 Page 4
   Table of Contents


           7.3.3.4   CHECK_INFILE_ENVIRONMENT . . . . . . . . . . . .  32
           7.3.3.5   CHECK_OUTFILE_ENVIRONMENT  . . . . . . . . . . .  32
           7.3.3.6   REC_DETECT_EOL_CHR . . . . . . . . . . . . . . .  32
           7.3.3.7   REC_RET_CHR_DETECT_EOL_CHR . . . . . . . . . . .  33
           7.3.3.8   REC_RET_CHR_DETECT_SEQ_EOL . . . . . . . . . . .  33
           7.3.3.9   REC_RET_CHR_DETECT_VR_EOL  . . . . . . . . . . .  33
           7.3.3.10  REC_RET_CHR_DETECT_FR_EOL  . . . . . . . . . . .  34
           7.3.3.11  REC_RET_CHR_DETECT_RMS_EOL . . . . . . . . . . .  34
           7.3.3.12  REC_RET_CHR_NON_SUPPRESS . . . . . . . . . . . .  34
           7.3.3.13  REC_STORE_CHR_DO_EOL_SEQ . . . . . . . . . . . .  34
           7.3.3.14  REC_STORE_CHR_DO_PADDING . . . . . . . . . . . .  35
           7.3.3.15  REC_STORE_CHR_DO_VLR . . . . . . . . . . . . . .  35
           7.3.3.16  REC_STORE_CHR_DO_RMS . . . . . . . . . . . . . .  35
           7.3.3.17  BLK_FETCH_BLOCK  . . . . . . . . . . . . . . . .  36
           7.3.3.18  BLK_WRITE_BLOCK  . . . . . . . . . . . . . . . .  36
           7.3.3.19  BLK_CLEAR_OUTPUT_BUFFER  . . . . . . . . . . . .  36
           7.3.3.20  BLK_CHECK_LAST_BLOCK . . . . . . . . . . . . . .  36
           7.3.3.21  BLK_CHECK_RECORD_FIT . . . . . . . . . . . . . .  36
           7.3.3.22  BLK_DO_OUTPUT_BLOCKING . . . . . . . . . . . . .  37
           7.3.3.23  BLK_DO_INPUT_BLOCKING  . . . . . . . . . . . . .  37
           7.3.3.24  BYT_FETCH_A_BYTE . . . . . . . . . . . . . . . .  37
           7.3.3.25  BYT_WRITE_A_BYTE . . . . . . . . . . . . . . . .  37
           7.3.3.26  CVT_NUM_STR  . . . . . . . . . . . . . . . . . .  38
           7.3.3.27  PROCESS_IGNORE_ERRS_OPTION . . . . . . . . . . .  38
           7.3.4     ALTER_FILE_IO.BLI  . . . . . . . . . . . . . . .  38
           7.3.4.1   IO_OPEN_FIRST  . . . . . . . . . . . . . . . . .  38
           7.3.4.2   IO_OPEN_NEXT . . . . . . . . . . . . . . . . . .  39
           7.3.4.3   IO_CREATE  . . . . . . . . . . . . . . . . . . .  39
           7.3.4.4   IO_GET . . . . . . . . . . . . . . . . . . . . .  40
           7.3.4.5   IO_PUT . . . . . . . . . . . . . . . . . . . . .  40
           7.3.4.6   IO_INFORMATION . . . . . . . . . . . . . . . . .  41
           7.3.4.7   IO_LOG . . . . . . . . . . . . . . . . . . . . .  41
           7.3.4.8   IO_CLOSE . . . . . . . . . . . . . . . . . . . .  41
           7.3.4.9   DEALLOC_MEM  . . . . . . . . . . . . . . . . . .  41
           7.3.4.10  ALLOCATE_FILE_INFO . . . . . . . . . . . . . . .  42
           7.3.4.11  ALLOCATE_BUFFER_AREA . . . . . . . . . . . . . .  42
           7.3.4.12  RMS_BLOCK_INIT . . . . . . . . . . . . . . . . .  42
           7.3.5     ALTER_DISK_IO.BLI  . . . . . . . . . . . . . . .  43
           7.3.5.1   OPEN_DISK  . . . . . . . . . . . . . . . . . . .  43
           7.3.5.2   GET_DISK . . . . . . . . . . . . . . . . . . . .  43
           7.3.5.3   PUT_DISK . . . . . . . . . . . . . . . . . . . .  43
           7.3.5.4   CLOSE_DISK . . . . . . . . . . . . . . . . . . .  44
           7.3.5.5   PROCESS_RMS_ERROR  . . . . . . . . . . . . . . .  44
           7.3.5.6   DISK_FILE_LOGGING_PROCESS  . . . . . . . . . . .  44
           7.3.5.7   FLAG_FOR_RECORD_TYPE . . . . . . . . . . . . . .  44
           7.3.6     ALTER_TAPE_IO.BLI  . . . . . . . . . . . . . . .  45
           7.3.6.1   OPEN_TAPE  . . . . . . . . . . . . . . . . . . .  45
           7.3.6.2   PROCESS_FOREIGN_FILE . . . . . . . . . . . . . .  45
           7.3.6.3   GET_TAPE . . . . . . . . . . . . . . . . . . . .  45
           7.3.6.4   PUT_TAPE . . . . . . . . . . . . . . . . . . . .  45
           7.3.6.5   CLOSE_TAPE . . . . . . . . . . . . . . . . . . .  46
           7.3.6.6   REWIND_TAPE_DRIVE  . . . . . . . . . . . . . . .  46
           7.3.6.7   OPEN_THE_FILE  . . . . . . . . . . . . . . . . .  46
           7.3.6.8   CREATE_THE_FILE  . . . . . . . . . . . . . . . .  46
   ALTER-32 Function Specificaiton                                 Page 5
   Table of Contents


           7.3.6.9   PROCESS_QIO_ERROR  . . . . . . . . . . . . . . .  47
           7.3.6.10  GENERATE_FOREIGN_FILENAME  . . . . . . . . . . .  47
           7.3.6.11  TAPE_FILE_LOGGING_PROCESS  . . . . . . . . . . .  47
           7.3.6.12  EOF_CATCH  . . . . . . . . . . . . . . . . . . .  48
   ALTER-32 Function Specificaiton                                 Page 6
   INTRODUCTION


        1  INTRODUCTION

        The purpose of ALTER is to translate files from one character  set  or
        format  into another.  The main use of ALTER is to read and write tape
        formats other than VMS tape formats.  Its secondary purpose  is  as  a
        format  translator.   ALTER  is  also  capable of reading from volumes
        which have parity errors  or  data  errors.   ALTER  only  parses  the
        command  line for the most blatent of errors, therefor the user is not
|       restrained in the use of this program.  (Note the  user  can  therefor
|       create translations that are irreversible in format, or simply produce
|       nonsense).

        This document describes the functionality that has been implemented in
        the  program.   It  will  describe  the  effects  of qualifiers in the
        command line, and the format of the command line itself.  It will also
        describe  the  options  available for use in the translation file, and
        explain how to write one.  Examples are given to illustrate  usage  of
        ALTER.



        2  RELATED DOCUMENTS

        The following documents also explain aspects of VMS-ALTER.

        1.  Parser functional specification.
|  
|       2.  VAX/VMS Documentation set Volume 4A, Command Definition Utility
|           Reference Manual, Order No.  AA-Z408A-TE




        3  REVISION HISTORY

        The following is the current revision history for this file
|  
|       1.  Draft #1 - Creation of the documentation file.
|  
|       2.  Draft #2 - Documentation of new routines added after DRAFT #1.
|  
|       3.  Draft #3 - Documentation of edits done for release 1.0.001




        4  MODULES

        ALTER is composed of multiple modules  which  are  compiled  and  then
        linked into the one executable file ALTER.EXE.  The modules are:


        1.  ALTER.BLI - Main  module  for  ALTER,  this  module  contains  the
            driving routines, that dispatch to the actual processing routines.
   ALTER-32 Function Specificaiton                                 Page 7
   MODULES


        2.  ALTER_TRANSLATION.BLI - Handles file copying and  translation  the
            processing of translation files.

        3.  ALTER_XLATE_FILE.BLI  -  Handles  the  processing  of  translation
            files.

        4.  ALTER_ERROR.MSG - Alter specific error messages.

        5.  ALTER_FILE_IO.BLI  -  Handles  dispatching  to   appropriate   I/O
            routines for the device on which a file resides.

        6.  ALTER_DISK_IO.BLI - Handles all input and output from disk.

        7.  ALTER_TAPE_IO.BLI - Handles all input and output from tape.


|       The following REQUIRE FILES are needed by various modules:


        1.  ALTER_DEFINITIONS.REQ - Basic ALTER definitions.

        2.  IO_DEFINITIONS.REQ - I/O processing definitions.

        3.  PARMAC.REQ - Parsing macros.

        4.  CHRDEF.REQ - Character definitions.

        5.  ALTER.CLD - Command language descriptor file.

        Additionally, the modules will search SYS$LIBRARY:STARLET.REQ.

        Each of the BLISS-32 modules is compiled via the  BLISS  DCL  command,
        and  the  message  file  is  compiled  via  the  MESSAAGE DCL command.
        Linking is done with the LINK DCL command.  The following shows how to
        compile the modules:

             $ MESSAGE ALTER_ERROR.MSG
             $ BLISS ALTER.BLI
             $ BLISS ALTER_TRANSLATION.BLI
             $ BLISS ALTER_XLATE_FILE.BLI
             $ BLISS ALTER_FILE_IO.BLI
             $ BLISS ALTER_TAPE_IO.BLI
             $ BLISS ALTER_DISK_IO.BLI

        Once the modules have been compiled, they can be linked together  with
        the following command:

             $ LINK ALTER, ALTER_XLATE_FILE, ALTER_TRANSLATION, ALTER_FILE_IO, -
               ALTER_DISK_IO, ALTER_TAPE_IO, ALTER_ERROR, CLIMSG, PARSER, PARERR
|  
|                                   Command Parser
|  
|               The modules PARSER and PARERR are part of the  command
|               parser  and  are  discussed  in  detail in the Command
|               Parser Functional Specification.
   ALTER-32 Function Specificaiton                                 Page 8
   MODULES


|       To run ALTER-32, you must set up the DCL command.   This  is  done  as
|       follows:
|  
|            $ SET COMMAND ALTER.CLD
|  
|       At this point ALTER is capable of running.



        5  COMMAND FORMAT



|       The general command format is  the  same  as  the  standard  DCL  COPY
        command, namely:


         $ TRANSLATE/qualifiers infilspec[,.,.]/qualifiers outfilspec/qualifiers



        The TRANSLATE command takes standard VAX/VMS file specifications.  The
        possible  qualifiers  are listed below.  Note that though there can be
        multiple input file specifications, there is allowed only  ONE  output
        file  specification  (this  specification  may  be wild carded only in
        conjunction with the /GENERATE  qualifier).   If  the  qualifiers  are
        given  before  the file specs then they apply to both input and output
        file specs.  Otherwise qualifiers after the input file specs apply  to
        all the input file specs, and similarly for the output file spec.



        5.1  QUALIFIERS

        There are quite a number of qualifiers which tell  the  program  about
        the  input  and  output  files.   Although  the  descriptions  of  the
        qualifiers will indicate what  they  are  used  for,  it  may  not  be
        apparent  how different combinations of these qualifiers will interact
        when using them to describe the  format  of  a  file.   The  following
        discussion  will  give  some  of  the  details  on  how ALTER-32 makes
        decisions about a files format based on the qualifiers spceified.
|  
|  
|  
|       5.1.1  Terminology
|  
|       Some terms will need to be understood before we discuss the method  in
|       which   certain   qualifier  values  are  defaulted  and  checked  for
|       consistancy.
|  
|  
|  
|       5.1.1.1  Record types
|  
|       A record type describes the basic format  of  all  the  records  in  a
|       particular  file.   Fixed-length  records  means that all records will
   ALTER-32 Function Specificaiton                                 Page 9
   COMMAND FORMAT


|       contain the same number of bytes.  Delimited records  means  that  all
|       records  end  with a special character sequence containing one or more
|       bytes (i.e.  an end  of  record  can  be  signified  by  the  sequence
|       carriage return, line feed).  Counted records all contain leading byte
|       counts.  These leading byte counts  are  in  the  form  of  a  numeric
|       character  string  of  a  specific length.  ANSI-D records are counted
|       records which use the standard 4  ASCII  character  byte  count.   RMS
|       records  means that RMS (Record Management Service) will keep track of
        where records begin and end.  If a file has no record type,  it  means
        that  there  is  no way to determine where a record ends.  The file is
        one long stream of bytes.



        5.1.1.2  Sizes and Blocking

        The term "record size" refers to the number of bytes to be  placed  in
        each record if fixed length records are used.  A "maximum record size"
        is the largest number of bytes that may be contained in a record.  For
        fixed length records, this is the same as "record size".

        When reading and writing tape files, a block containing  one  or  more
        records  is transferred to or from the tape.  By placing more than one
        record in a block, the tape is used more efficiently.  A "block  size"
        is the number of bytes contained in one block of the file.  The "block
        factor" is the number of records which are contained in one block.



        5.1.1.3  Fill characters

        When dealing with records or blocks which are of a fixed  size,  there
        is  not always enough data to fill them.  If the actual amount of data
        being placed into a fixed length record is  not  enough  to  fill  the
        record, a "fill character" will be used to occupy the remaining space.
        That is, copies of the fill character will be placed into each byte in
        the record that does not contain useful data.

        The same type of procedure is used for blocks which are  not  entirely
        filled.   A  "block  fill  character" can be used to occupy the unused
        space at the end of a block.  For example, if the blocks being written
        to  a  file are 1000 character long, the records are all 80 characters
        long and there is a blocking factor of 12 records per block, then  960
        characters  contain  useful  data and the remaining 40 characters will
        contain the block fill character.



        5.1.2  Qualifier Defaulting and Consistancy Checks

        Following is a "blow by blow" account of how ALTER-32 generates all of
        the  information  it needs based on the qualifiers which were supplied
        by the user.
   ALTER-32 Function Specificaiton                                Page 10
   COMMAND FORMAT


        First, we will discuss the exact procedure ALTER-32 uses  to  fill  in
        defaults  and  do certain consistancy checks.  Afterward, we will give
        some specific examples of how certain qualifiers interact.

        If a maximum record size  (/MAX_REC_SIZE)  was  not  specified  but  a
        record  size  (/R_SIZE)  was,  then  the  record size is copied to the
        maximum record size.  Specifying a record size means all records  will
|       be a fixed length and no record will be larger than that size.
|  
|       If one of the counted record  parameters  (/VR_LENGTH,  /VR_ZERO_CHAR)
|       was  specified,  the  other  one will be defaulted appropriately.  The
|       standard value for the length of the count field (/VR_LENGTH) is 4 and
|       the  standard  for  the  numeric base character (/VR_ZERO_CHAR) is the
|       value of an ASCII "0".

        The next item to handle is defaulting the  record  type  (/R_TYPE)  if
        none  was  given  by  the user.  If the counted record parameters were
        specified, then set the record type  to  COUNTED.   Otherwise,  if  an
        End-Of-Line  sequence  or a set of End-Of-Line characters (input files
        only) was given in a translation file, then set  the  record  type  to
        DELIMITED.  If none of the above conditions are true, then if a record
        length was given, set record type to FIXED.  If that is not  the  case
        and  the  device  for the file is not Tape, use RMS as the record type
        otherwise set record type to NONE.  A record type  of  NONE  indicates
        that there are no record breaks recognized by ALTER-32.  The file will
        be considered one long stream of bytes.

        Next we will select the appropriate End of line processor routine  for
|       the  record  type we are using.  This routine will be used by ALTER to
|       determine where each record ends as it is reading the input file.

        Following this, ALTER-32 does a couple of consistancy checks.  If  the
        record  type  is 'COUNTED' and and End of line sequence was specified,
|       ALTER-32 will complain to the user.  If the record type is 'DELIMITED'
|       and  counted  record  parameters  were  specified,  the  program  will
        complain.  If 'FIXED' was specified as the record type, then fill in a
        record  size  value from the maximum record size if necessary.  If the
        user specifically gave the record type as 'FIXED' and gave  no  record
        size  whatsoever,  the  program will issue an error.  If the user gave
        ALTER-32 block and record information but is using an  RMS  file,  the
        program will warn him about it.

        If no block size (/B_SIZE) was given by the user, it is calculated  as
        the  product  of block factor (/B_FACTOR) and the maximum record size.
        If the user didn't give enough information to compute that, ALTER uses
        the  default  block  size  for  the device or the maximum record size,
        whichever is larger.

        Next, ALTER fills in a default  for  block  factor  if  the  situation
        dictates  that  it is needed.  That is, if the user specified a record
        size and block size or he stated that the record type was fixed.   The
        block factor is computed by dividing block size by record size.

        After this, ALTER makes sure that the block size is not too  small  by
        checking  it  against  the  product of the maximum record size and the
        block factor.
   ALTER-32 Function Specificaiton                                Page 11
   COMMAND FORMAT


        The byte size (/B_SIZE) is set to eight if nothing was specified.  The
        block  size  is then converted into number of eight-bit bytes required
        to hold a full block and that value is  saved  for  future  reference.
        The value computed will be the same as the block size if the byte size
        is eight.

        Finally, ALTER sets up the number of buffers it will  create  and  use
        for  the  file  if nothing was specified by the user.  The default for
        this is two.

        By performing these tasks in the specified order,  ALTER-32  fills  in
        needed information concerning the files format.



        5.1.3  Examples

        Following is a list of examples and how  ALTER-32  will  act  in  each
        case.

        1.  $ TRANSLATE MFA0:*/BSIZE:1000/RSIZE:120 [MUMBLE]

            Alter will use a block factor of eight for the  input  file  since
            none was specified and eight records of 120 characters is the most
            that would fit in a block.  The extra 40 characters at the end  of
            the block will be ignored.

        2.  $ TRANSLATE FILENAME.* MFA0:/BSIZE:1000/RSIZE:120/BFACTOR:10

            This will cause an error since a block would have to be 1200 bytes
            long  to accomodate 10 records of 120 characters each and the user
            specifies only 1000 bytes as the block size.

        3.  $ TRANSLATE [JCOOL]MYFILE.TXT MFA0:/RTYPE:COUNTED

            ALTER-32 will use the default block size for the tape  device  and
|           it  will place into each block as many ANSI-D records as will fit.
            Each record in the output file  will  have  leading  ASCII  record
            counts that are 4 digits long.

        4.  $ TRANSLATE *.TXT MFA0:/BSIZE:1000/RSIZE:80/BFACTOR:10/FILL:32

            ALTER will take all files with the extension .TXT and  write  them
            to  MFA0:.   It  will  write  10  records  per  block and fill the
            remaining 200 characters with ASCII spaces.

        5.  $ TRANSLATE MFA0:*/BSIZE:1000/RTYPE:COUNTED [MYDIR]

            This will cause ALTER to read all the files on the tape  into  the
|           directory  [MYDIR].  From each buffer, it will read as many ANSI-D
|           records as are in that buffer.

        6.  $ TRANSLATE MFA0:*/BSIZE:1000/BFACTOR:5/RTYPE:COUNTED [MYDIR]
   ALTER-32 Function Specificaiton                                Page 12
   COMMAND FORMAT


            This command will do the same as the one immediately above  except
            that  it will read, at most, 5 records out of each block.  It will
            ignore anything past the fifth record.

        7.  $ TRANSLATE [JONES]*.* MFA0:/VRLENGTH:6/MAXRECSIZE:75

            This will cause ALTER to write all  the  files  from  the  [JONES]
            directory to the tape.  The block size written to tape will be the
            device default block size.   Records  will  be  a  maximum  of  75
|           characters.   The  record  format  will  be  counted with a 6 byte
|           leading ASCII count field.

|  
|  
|  
|       5.1.4  Qualifier Descriptions
|  
|       The following qualifiers are used by ALTER to determine the format  of
|       the  input and output file.  The qualifiers override options set up in
|       any translation file used.  VAX/VMS ALTER  does  not  prompt  you  for
|       input,   therefor   you  must  specify  all  file  specifications  and
|       qualifiers on the command line.  There are  two  types  of  qualifiers
|       allowed in ALTER-32 they are local or global qualifiers.
|  
|       Valid arguments types for the qualifiers are:
|  
|       1.  VALUE - Specify a numeric value in decimal.
|  
|       2.  CHAR - The decimal equivalent of the character.
|  
|       3.  LENGTH - A decimal count value for a length.
|  
|       4.  FILESPEC - Standard VMS file specification.
|  
|       5.  KEYWORD - Only specified values are allowed.
|  
|  
|  
|  
|       5.1.4.1  Global Qualifiers
|  
|       Global qualifiers are specified after the command word  TRANSLATE  and
|       apply  to both the input and output files.  The following is a list of
|       the Global Qualifiers.



        5.1.4.1.1  /CONCATENATE

        Take all input files and concatenate them into one output file.
   ALTER-32 Function Specificaiton                                Page 13
   COMMAND FORMAT


|       5.1.4.1.2  /FDL=filespec
|  
        Set up the output  file  characteristics  based  on  values  given  in
        <filespec> (filespec is an FDL description file).



        5.1.4.1.3  /GENERATE

        This will generate a sequence of output files based on the wild carded
        portion of the output file specification.



        5.1.4.1.4  /IGNORE_ERRS

        Continue with tape processing even if you get  parity  or  bad  sector
        errors.  Thus ALTER can be used to read data off a damaged tape.
|  
|  
|  
|       5.1.4.1.5  /LOG[=keyword]
|  
        Type out  a  log  of  the  transaction,  parameters  of  interest  are
        specified by, <keyword>:

        1.  ALL - log file transfers and input block sizes

        2.  BLOCK_SIZES - log activities dealing with input block sizes

        3.  FILES - log data about the files




        5.1.4.1.6  /TEXT

|       Convert characters whose value is less than decimal 32 to "^" followed
|       by  the  printing  equivalent of the character.  This parameter should
|       not normally be specified simultaneously with translations.  NOTEXT is
|       the  default setting of this parameter.  This qualifier is useful when
|       typing out files contioning control characters.
|  
|  
|  
|       5.1.4.1.7  /TRANS_FILE[=filespec]
|  
|       Set the translation file to be used for this  transfer.   "Filespec  "
|       defaults  from  SYS$LOGIN:ALTER_TRANSLATE.TRN.   If it is not found on
|       the user's area, the system library will  be  searched  automatically.
        (Also called /TFILE)
   ALTER-32 Function Specificaiton                                Page 14
   COMMAND FORMAT


        5.1.4.1.8  /VERIFY

        Ask about each file before it is processed.  The user will be prompted
        with  the  file name followed by "[OK]?" at which the user types 'YES'
        or 'NO'.  If  'YES'  is  typed  then  that  file  will  be  processed,
        otherwise it will be skipped.



        5.1.4.2  Local Qualifiers

|       Local  qualifiers  are  specified  either  after   each   input   file
|       specification  or after the output file specifications, and they apply
|       only to the file specification which imediately preceeds them.
|  
|  
|  
|       5.1.4.2.1  /FILL=char
|  
|       Set the fill character used to fill partially full output  records  to
|       "value".
|  
|  
|  
|       5.1.4.2.2  /ILLEGAL=char
|  
|       Set the character to be used when there is no equivalent in the output
|       character set (see special translation function -4).
|  
|  
|  
|       5.1.4.2.3  /SUPPRESS=value
|  
|       Suppress end of record characters whose value is "value."  If  "value"
|       is not present, 32 decimal will be used (space).
|  
|  
|  
|       5.1.4.3  Positional Qualifiers
|  
|       Positional qualifiers are those qualifiers that can be used either  as
|       either  global  or local qualifiers, depending on where they are used.
|       The user must remember though that if the qualifier is used as global,
|       then  it  applies to both input and output file specifications.  So if
|       you want a qualifier to apply to a list of input  files  but  not  the
|       output  file  then  you  would  use  the  same  qualifier  as a global
|       qualifier and a local qualifier after the output file specification.
|  
|  
|  
|       5.1.4.3.1  /ADJUST=value
|  
|       After translating each byte of the input file, add the value specified
|       by the option to the resulting byte.
   ALTER-32 Function Specificaiton                                Page 15
   COMMAND FORMAT


|       5.1.4.3.2  /B_FACTOR=value
|  
|       Specify the number of input or  output  records  per  block.   If  the
|       argument  is  greater than zero read or write "value" records from (or
|       to) the blocks of the specified file(s).  If "value" is  greater  than
|       zero  and  record  size  is specified, but block size is not specified
|       compute block size.  This option can be used to restrict the number of
|       records  read or written in a block.  If record size is not specified,
|       block size is specified and "value" is  greater  than  zero,  variable
|       length output blocks up to block size will be written out with "value"
|       (or less) records per block.  If "value" equals zero, records will  be
|       permitted to fold around blocks.
|  
|  
|  
|       5.1.4.3.3  /BUFFER=value
|  
|       Allocate "value" buffers for the file transfer.
|  
|  
|  
|       5.1.4.3.4  /B_FILL=char
|  
|       If the records in a block do not fill up the allocation of that block,
|       use  the  B_FILL  character  to  fill  in  the  space.  ("char" is the
|       numerical value of the character desired)
|  
|  
|  
|       5.1.4.3.5  /B_SIZE=value
|  
|       Set the input and output block size as "value" bytes.
|  
|  
|  
|       5.1.4.3.6  /BYTE_SIZE=value
|  
|       Set the input and output byte size as "value" bits.  (range:  1 to 32)
|  
|  
|  
|       5.1.4.3.7  /MASK=value
|  
|       Set the mask to be ANDed with each input byte.  This can  be  used  to
|       get  bytes (perhaps 8 bit ASCII) from the input file and truncate bits
|       (perhaps the most significant bit -- parity).
|  
|  
|  
|       5.1.4.3.8  /MAX_REC_SIZE=value
|  
|       Set the value of the maximum record size for the file.
   ALTER-32 Function Specificaiton                                Page 16
   COMMAND FORMAT


|       5.1.4.3.9  /REWIND
|  
|       Rewind  the  tape  drive  before  processing  the  first   file.    An
|       information message will be given if you try to rewind a non-tape or a
|       non-foreign tape, and the qualifier will be ignored for that device.



        5.1.4.3.10  /R_SIZE=value

        Set the input or output record size to "value" bytes.



        5.1.4.3.11  /R_TYPE=keyword

        Tell ALTER-32 what type of records will be transfered.   Valid  record
        types are:
|  
|       1.  COUNTED - Records have a leading byte count.

        2.  DELIMITED - Records are ended by particular end of a record
            character sequence (i.e.  <cr><lf>).

        3.  FIXED - All records contain the same number of characters.

        4.  NONE - No record termination, file is one continuous stream of
            bytes.

        5.  RMS - RMS handles implied end of records.




        5.1.4.3.12  /VR_LENGTH=length

        Is used for an input file that has variable length records.  When this
        qualifier  is given, ALTER expects each record to start with a decimal
        number that specifies the number of  characters  in  the  record  that
        follows.  The argument to the qualifier is the number of digits in the
        leading count.



        5.1.4.3.13  /VR_ZERO_CHAR=value

        This defines the base of the numeric characters in the  character  set
        used for the file.



        5.2  EXAMPLES

        The following are a list of examples to assist the user in  the  usage
        of  this  utility.   For a more detailed description of the qualifiers
        used in the examples, see the QUALIFIER DESCRIPTION section above.
   ALTER-32 Function Specificaiton                                Page 17
   COMMAND FORMAT


        5.2.1  Basic Functionality

        The  following  examples  illustrate  basic  translations   done   via
        ALTER-32.   Basic translations include simple copiing either from disk
        to disk, tape to disk, or tape to tape.



        1.  $ TRANSLATE FOOBAR.ALL FOO.BAR

            The TRANSLATE command in this case is almost the equivalent of the
            standard  COPY command.  Here it will copy the disk file "FOO.BAR"
            to another disk file called "FOOBAR.ALL".


        2.  $ TRANSLATE FOO.BAR,FOOBAR.TXT,BAR.* MFA0:*.*

            This command will copy the disk files "FOO.BAR","FOOBAR.TXT",  and
            the  wildcarded  group  of  files  "BAR.*" out to device MFA0:  as
            files with their original names.


        3.  $ TRANSLATE MFA0:FOOBAR.ALL FOO.BAR

            This command will copy the file "FOOBAR.ALL" from MFA0:  into  the
            disk file "FOO.BAR".


        4.  $ TRANSLATE MFA0:FOO.* FOOBAR.*

            This command will copy all the files on MFA0:  with the file  name
            "FOO" into disk files with the file name "FOOBAR".


        5.  $ TRANSLATE/GENERATE FOO*.* MFA0:TST%%%

            This command will cause ALTER-32 to look for all disk files  whose
            file  names  start  as  "FOO",  and  write them out to MFA0:  as a
            sequential series of files starting with "TST000" and ending  with
            "TST00n" (where "n" is the number of files written).


        6.  $ TRANSLATE/CONCATENATE FOO*.* MFA0:FOOBAR.ALL

            This command will take all disk files  with  file  names  starting
            with  "FOO"  and put them into one file called "FOOBAR.ALL", where
            the  output  file  contains  all  the  input  files   concatenated
            together.


        7.  $ TRANSLATE/BYTESIZE=5 *.FOO,*.BAK,*.COM/BYTESIZE=6
            *.*/BYTE_SIZE

            This command uses the positional qualifier  /BYTE_SIZE  to  inform
            ALTER-32  that  the  byte  sizes  of  the  input files are not the
            standard length.  ALTER-32 will translate '*.FOO' and  '*.BAK'  as
   ALTER-32 Function Specificaiton                                Page 18
   COMMAND FORMAT


            files  having  five bit bytes and '*.COM' as a file having six bit
            bytes.  To make sure the output files are in the standard VMS byte
            size,  we  specify the default byte size for the output files.  If
            this was not done then the output files would be made as five  bit
            bytes, due to the global use of /BYTE_SIZE.




        5.2.2  Logging

        The logging function is designed to give information to  the  user  of
        ALTER-32.   There  are three modes of logging; the first is FILES (the
        default), this function will tell the user what file has  been  copied
        and  what  the  resultant  file is called.  The second is BLOCK_SIZES,
        this function will cause ALTER-32 to tell  the  user  what  the  block
        sizes  are for the input file.  The last one is ALL, this will combine
        the information given for FILES, and BLOCK_SIZES.


             $ TRANSLATE/LOG:ALL FOO.* MFA0:FOOBAR.*

             This command will take all disk files with file  name  "FOO"  and
             write  them out on MFA0:  with file names "FOOBAR".  It will also
             notify the user as each file is written, giving the  input  block
             sizes, and the input and output file names.



        5.2.3  Translating

        Translating a file from one character set or  format  is  done  mainly
        thru  use  of the TRANS_FILE qualifier.  Translation files are used to
        change the format  of  the  file,  to  allow  reading  of  differently
        formated  files, and to do a one to one mapping from one character set
        to another character set.  Implementation  of  translation  files  are
        explained in depth below


        1.  $ TRANSLATE/TRANSFILE:EBCIDICTOASCII.TRN MFA0:*.* *.*

            This command uses a translation file  called  EBCIDIC_TO_ASCII.TRN
            to translate all the files on MFA0:  into ASCII files on disk with
            the same name.


        2.  $ TRANSLATE/TRANSFILE:ASCIITOEBCIDIC.TRN FOOBAR.* MFA0:*.*

            This command uses another translation file to take all disk  files
            with  the  filename  "FOOBAR"  and translate them into EBCIDIC and
            write them out on tape with their original file names.


        The other way to cause translations is to specify the change  required
        via  the  qualifiers  (Note  this  will  not allow you to map from one
        character set to another).  Below are  examples  of  ways  to  achieve
   ALTER-32 Function Specificaiton                                Page 19
   COMMAND FORMAT


        these changes.


        1.  $ TRANSLATE MFA0:*.FOO/BYTESIZE=6 [MUMBLE]*.*

            This command will take all the files on MFA0:   of  type  FOO  and
            copy  them  to  the  disk  in  directory MUMBLE.  The /BYTE_SIZE=6
            causes ALTER-32 to assume the files are written  as  six-bit-bytes
            and trnslates them to the standard VAX/VMS byte size on output.


        2.  $ TRANSLATE *.FOO MFA0:*.*/ADJUST=10

            This command will take all the files on your default directory and
            put  them  out on tape.  The /ADJUST=10 will cause ALTER-32 to add
            the value ten to the octal value of each byte.  The effect  is  to
            channge the character on output.
   ALTER-32 Function Specificaiton                                Page 20
   THE TRANSLATION FILE


        6  THE TRANSLATION FILE

|       The translation file is an optional file that ALTER-32 may  use,  that
|       will  map  one character set or format into another.  The entries on a
|       single line are separated by commas, an entry at the end of a line may
        be  followed by a ";" and a comment or a "!" and a comment or simply a
        carriage return line feed sequence.  There may be  as  many  lines  of
        translation  parameter  setup as necessary.  If a translation table is
        required, it follows the default  parameters.   The  translation  file
        serves two purposes.


        1.  It specifies defaults  for  parameters  which  the  user  did  not
            specify  as  qualifiers  on  the command line.  Note that any user
            specified qualifiers always takes precedence over  any  equivalent
            options specified in the translation file.

        2.  It specifies a translation table through which every input byte is
            mapped.    This   translation   table   contains   either   simple
            translations (eg.  "Z" on input becomes decimal 209 on output)  or
            negative numbers which specify a special translation function (eg.
            ignore this character on input).





        6.1  OPTIONS

        Translation file options are set up in the following format:


                  keyword=<value>, keyword=<value>, keyword=<value>, ...
                                          or
                            keyword=(<value>,<value>,...)


        Valid  KEYWORDS  and  their  arguments  are  specified  below.   Valid
        arguments are specified as follows:
|  
|  
|       1.  VALUE - Specify a numeric value in the current RADIX.
|  
|       2.  CHAR - Specify a standard ASCII character.
|  
|       3.  FILESPEC - Specify a standard VMS file specification.
|  
|       4.  STRING - Specify a string of standard ASCII characters.
|  
|       5.  KEYWORD - Only specified values are allowed.
|  
|  
   ALTER-32 Function Specificaiton                                Page 21
   THE TRANSLATION FILE


        6.1.1  ADJUST=value

        Add "value" to each byte (character) being copied.



        6.1.2  BLOCK_FILL=char

        "Char" is used to fill partially full output blocks and records.



        6.1.3  FDL=filespec

|       "Filespec" is the name of a  file  containing  information  about  the
|       output  file  coded in File Description Language (FDL).  RMS uses this
|       information to set up the attributes of the output file.



        6.1.4  FILL=char

        "Char" is used to fill partially full output blocks and records.



        6.1.5  IEOLS=string

        "String" denotes an  End-Of-Line-String.   This  string  will  delimit
        records in a free formated file.



        6.1.6  ILLEGAL=char

        "Char" is used when -4 appears in the translation table.   "-4"  means
        substitute  the illegal character for this input byte because there is
        no equivalent in the output character set.



        6.1.7  INPUT_BLOCK_SIZE=value

        Set the input block size in bytes.  (Also called IBLOCKSIZE)



        6.1.8  INPUT_BYTE_SIZE=value

        Set the input byte size in bits.  (Also called IBYTESIZE)
   ALTER-32 Function Specificaiton                                Page 22
   THE TRANSLATION FILE


        6.1.9  INPUT_END_OF_LINE=char

        Set the input End-Of-Line character.  It may take  a  single  argument
        which  is  considered to be an End-Of-Line by the program, or a series
        of characters in  parentheses.   These  characters  will  be  used  to
        determine input records for free format input.  (Also called IEOL)



        6.1.10  INPUT_MAX_RECORD_SIZE=value

        Set the maximum record length for an input record.



        6.1.11  INPUT_RECORD_TYPE = keyword

        Determine the type of records used in the  input  file.   For  keyword
        values see /R_TYPE above.



        6.1.12  INPUT_BLOCK_FACTOR=value

|       Set the input standard,  see  /BLOCK_FACTOR  qualifier  above.   (Also
|       called IBLOCKFACTOR or ISTANDARD)



        6.1.13  INPUT_RECORD_SIZE=value

        Set the input record size in bytes.  (Also called IRECORDSIZE)



        6.1.14  MASK=value

        "Value" is a mask to be ANDed with each input byte.



        6.1.15  OUTPUT_BLOCK_SIZE=value

        Set the output block size in bytes.  (Also called OBLOCKSIZE)



        6.1.16  OUTPUT_BYTE_SIZE=value

        Set the output byte size in bits.  (Also called OBYTESIZE)
   ALTER-32 Function Specificaiton                                Page 23
   THE TRANSLATION FILE


        6.1.17  OUTPUT_END_OF_LINE=char

        Set the output End-Of-Line.  These characters  are  attached  to  each
        output record after padding or truncating.  (Also called OEOL)



        6.1.18  OUTPUT_MAX_RECORD_SIZE=value

        Set the maximum output record size in bytes.



        6.1.19  OUTPUT_RECORD_SIZE=value

        Set the output record size in bytes.  (Also called ORECORDSIZE)



        6.1.20  OUTPUT_RECORD_TYPE=keyword

        Determine the format of the output records.  For  allowable  keywords,
        see /R_TYPE above.



        6.1.21  OUTPUT_BLOCK_FACTOR=value

|       Set the output  block  factor.   See  /BLOCK_FACTOR  qualifier  above.
|       (Also called OBLOCKFACTOR or OSTANDARD)



        6.1.22  OUT_OF_RANGE=value

        "Value"  is  used  when  the  input  byte  exceeds  the  size  of  the
        translation table.



        6.1.23  RADIX=value

        Set the radix in which all numeric  input  is  to  be  done  from  the
        appearance  of this command until the next RADIX command.  The "value"
        is always specified in radix 10.



        6.1.24  SUPPRESS=char

        "Char" is a character to be suppressed when appearing at the end of an
        input record.  Note that this character is compared after translation.
   ALTER-32 Function Specificaiton                                Page 24
   THE TRANSLATION FILE


        6.1.25  TABLE

        If a translation file is to follow this must be present  and  also  be
        the  last keyword in the translation file.  "Value" is the size of the
        translation table.  "Value" is always read in radix 10.



        The translation table entries take on the following forms:


          1.   One entry per line  optionally  followed  by  a  ";" or "!"
               and a comment.

          2.   More  than  one  entry  per  line  with  individual  entries
               separated from one another by commas.  The line may also end
               with ";" or "!" and a comment.



        Each individual entry is either a  number  in  the  current  radix  or
        double-quote  (")  followed by an ASCII character.  The first entry in
        the table is taken as the translated value of a zero input  byte,  the
        second entry as the translated value of one input byte, etc.


        Negative  numbers  in  translation  table  positions   cause   special
        functions to be invoked.  These are:


          -3   Ignore the current input byte.

          -4   Insert the "illegal" character value here (as  specified  by
               the ILLEGAL option or translation file default).
|  
|  
|  
|       6.2  SAMPLE TRANSLATION FILES
|  
|       The following translation files will allow ALTER-32 to change  from  8
|       bit, VAX standard, bytes to 7 bit bytes, and back again.
|  
|  
|       1.  8 bit to 7 bit ASCII
|           FILL=32, IEOL=(10), OBYTESIZE=7, IBYTESIZE=8, ORECORD=70, TABLE=127
|           0
|           1
|           2
|           3
|           4
|           .
|           .
|           .
|           122
|           123
|           124
   ALTER-32 Function Specificaiton                                Page 25
   THE TRANSLATION FILE


|           125
|           126
|           127
|  
|       2.  7 bit to 8 bit ASCII
|           SUPRESS=32, IEOL=(10), OBYTESIZE=8, IBYTESIZE=7, ORECORD=80, TABLE=127
|           0
|           1
|           2
|           3
|           4
|           .
|           .
|           .
|           122
|           123
|           124
|           125
|           126
|           127
|  
|  
|       Note that the table of values continues consequtively from 4  to  121,
|       we have ommited these numbers only for space restrictions



        7  INTERNALS

        This  section  will  describe  some  details  about  the  routines  in
        Alter-32.



        7.1  Overview

        The Alter-32 program copies files and does certain character and  data
        translations as described by the user of the program.

        Alter-32 is broken down into a number of layers.  Most of the routines
        which  deal with copying and translating characters are located in the
        ALTER_TRANSLATION module.  Essentially, data is passed  one  character
        at  a  time,  up through a number of layers on the input side and then
        back down through a number of layers on the output side.   Each  layer
        handles  a  different aspect of disecting or constructing data blocks.
        The layers which are involved in copying and translating data are:

        1.  TRANSLATION LAYER

        2.  BLOCK LAYER

        3.  RECORD PADDING LAYER

        4.  RECORD LAYER
   ALTER-32 Function Specificaiton                                Page 26
   INTERNALS


        5.  BYTE LAYER


        The Translation Layer is the top level.  Bytes  are  run  through  the
        translation  table (if any) and are modified according to the MASK and
        ADJUST qualifiers.

        The Block Layer handles stripping off any block  fill  character  that
        may  be  present  on  input or padding a block with fill characters on
        output.  This layer is above the suppression layer on the  input  side
        and below the record layer on the output side.

        The Record Padding  Layer  handles  suppressing  fill  characters  for
        records on input and padding records with fill characters on output.

        The Record Layer handles detecting end-of-record on  the  input  side.
        One  of a number of routines is used to do this according to what type
        of records are in the file (as described by the user of the  program).
        An  example  of  the  different record types which may comprise a file
        are:

        1.  Fixed length - All records contain the same number of characters

        2.  Counted records - Records contain a leading byte count

        3.  Delimited - Records end in a sequence of one or more special
            characters

        On the output side, this layer assures that the records are written in
        the proper format.

        The Byte Layer handles depositing and fetching bytes to and from  data
        buffers.   Since the byte size (in bits) can be specified by the user,
        these routines deal with extracting (or inserting) bytes of  any  size
        from  1  to  32  bits.  This layer also calls routines to read a block
        when the input buffer is empty and  write  a  block  when  the  output
        buffer is full.

        Below is a more complete description of the routines which  carry  out
        all of these functions.



        7.2  Require files

        7.2.1  ALTER_DEFINITIONS.REQ

        This module includes important symbol definitions for Alter-32.  These
        definitions  include  symbols  for /LOG and /R_TYPE keyword values and
        indices for the input and output effective value tables.
   ALTER-32 Function Specificaiton                                Page 27
   INTERNALS


        7.2.2  IO_DEFINITIONS.REQ

        This  require  file  contains  important  definitions  for  the   data
        structures  used  by  the I/O routines.  These data structures include
        the File information blocks and Qio buffer blocks.



        7.2.3  CHRDEF.REQ

        This contains symbol names for  special  characters  (escape,  control
        characters, etc.).



        7.2.4  ALTER.CLD

        ALTER.CLD is the command language description file  for  the  Alter-32
        program.   It  declares  a  command  to the command definition utility
        called  'TRANSLATE'  along  with  the   appropriate   parameters   and
        qualifiers.   The  command  can be added to a users exec by using 'SET
        COMMAND'.  This is described in detail in  the  VAX/VMS  documentation
        set, Vol 4.



        7.3  Routines

        This section is broken into  subsections  by  module,  each  of  which
        contain the routine descriptions for routines located in that module.



        7.3.1  ALTER.BLI

        This module contains the tables for local and  global  qualifiers  for
        the  PARSER  utility  (Refer the the Parser functional specification).
        It also contains descriptions  for  the  parameters  and  all  of  the
        storage  necessary  to  hold  qualifier and parameter values which are
        parsed from the command line.

        The module also contains  the  main  routine  and  the  routine  which
        processes  a  single  input file.  It holds the routines which support
        the /LOG, /GENERATE, and /VERIFY qualifiers.



        7.3.1.1  MAIN_DRIVER

        This routine oversees the entire  ALTER  operation.   It  handles  the
        logic  of  fetching  each  of  the input file names and setting up the
        environment under which  they  are  to  be  translated.   The  routine
        PROCESS_INPUT_FILE  is  then  called  to  copy  the  input file to the
        current output file.
   ALTER-32 Function Specificaiton                                Page 28
   INTERNALS


        7.3.1.2  BUILD_GENERATE_INFO

        This routine is called when the /GENERATE qualifier was  specified  by
        the  user.   It  will examine the input and output file specifications
        and determine if they are valid (i.e.  input filespec must be  totally
        wild or not wildcarded at all, output filespec must have one string of
        one or more '%' wild cards for placement of the sequence number).   It
        also sets up vital information concerning where the sequence number is
        placed  in  the  output  filespec.   The  routine  takes   no   formal
        parameters.



        7.3.1.3  BUILD_OUTPUT_FILENAME

        This routine will generate the next filename  from  the  given  output
        filespec  and  a  running  count  field.   The  running count field is
        incremented by the routine.



        7.3.1.4  DO_LOGGING

        This routine will check the /LOG qualifier and if it  is  present,  it
        will  log information about the file transferred.  There are no formal
        parameters taken by this routine.



        7.3.1.5  CHECK_VERIFY

        This routine will query the user as to whether or not  they  wish  the
        current file to be translated.



        7.3.1.6  PARSE_THE_INPUT_FILES

        This routine will call the parsing routines to get the list  of  input
        files and the qualifiers which are associated with them.



        7.3.1.7  FETCH_NEXT_FILE

        This routine calls IO_OPEN_NEXT with a descriptor pointing to  a  file
        specification.   If  it succeeds, this routine places the FILE_ID into
        INPUT_FILEID.  If it fails, the routine checks to see if there are any
        input files left to process in the input file list.  If so, it returns
        true, otherwise it returns false.
   ALTER-32 Function Specificaiton                                Page 29
   INTERNALS


        7.3.1.8  PROCESS_INPUT_FILE

        PROCESS_INPUT_FILE will handle the logic for scanning the input  file.
        It will open and close the input file, accumulate statistics, call the
        byte translation routine for each character and pass characters on  to
        the  output  routines.   There are no formal parameters passed to this
        routine.
|  
|  
|  
|       7.3.1.9  PROCESS_FIRST_FILE
|  
|       PROCESS_FIRST_FILE will handle the logic  that  goes  along  with  the
|       processing  of the first input file.  It is a separate routine because
|       all checking of previous file processing is invalid.
|  
|  
|  
|       7.3.1.10  PROCESS_SUBSEQUENT_FILES
|  
|       PROCESS_SUBSEQUENT_FILES will handle the processing of all  subsequent
|       files, including the checking done based on previous file processing.



        7.3.2  ALTER_XLATE_FILE.BLI

        This module contains the data and action  routines  used  to  parse  a
        translation  file.   It's  entry  point  is TRN_PARSE_TRANS_FILE.  The
        module  uses  the  LIB$TPARSE  routines  to   gather   the   necessary
        information.   It also holds all the LIB$TPARSE tables needed to parse
        the translation file.



        7.3.2.1  TRN_PARSE_TRANS_FILE

        TRN_PARSE_TRANS_FILE will read a translation  file  specified  by  the
        user.   It  will  build  a translation table (if one is present in the
        file) for TRN_TRNASLATE_BYTE to use.  The routine  will  also  set  up
        certain  variables  related  to how the file should be processed (i.e.
        RECORD_SIZE, BYTE_SIZE, RECORD_TYPE, etc.).   This  routine  takes  no
        formal parameters.



        7.3.2.2  TRN_INIT_COLLECT_DIGIT

        This routine prepares things for calls to  TRN_COLLECT_DIGIT.   It  is
        one  of  the action routines called by LIB$TPARSE.  When it is called,
        it clears TRN_KEY_VALUE and TRN_NEGATE_VALUE.  If the value being read
        is  for  the  TABLE  or RADIX keywords, it saves the current radix and
        sets radix to 10 since these keywords ALWAYS take decimal values.  The
        routine takes no formal parameters.
   ALTER-32 Function Specificaiton                                Page 30
   INTERNALS


        7.3.2.3  TRN_COLLECT_DIGIT

        This routine takes the last digit parsed  by  LIB$TPARSE,  checks  its
        range and calculates TRN_KEY_VALUE according to the following:
|  
|       TRN__KEY__VALUE = TRN__KEY__VALUE * RADIX + digit.
|  
        If it is the first digit and the routine sees a '-' sign, it will  set
        the  TRN_NEGATE_VALUE  flag.   This  flag will tell another routine to
        negate the value before it is stored.



        7.3.2.4  TRN_STORE_VALUE

        This routine will store the keyword value  which  was  accumulated  by
        calls   to   TRN_COLLECT_DIGIT   into   the   appropriate   entry   of
        TRN_STORAGE_TABLE as indicated by TRN_KEY_SEEN.  The routine takes  no
        formal parameters.



        7.3.2.5  TRN_STORE_NEXT_VALUE

        TRN_STORE_NEXT_VALUE  stores  lists  of  values  for  the  End-Of-Line
        sequences.   It  does  any necessary dynamic memory allocation to hold
        the values.  It expands the list size  by  ALLOCATION_INCR  characters
        each  time  the  list  needs  to grow.  This routine does not take any
        formal parameters.



        7.3.2.6  TRN_STORE_STRING

        This routine will store a string gathered by LIB$TPARSE into a dynamic
        string and will place the address of the descriptor in an entry of the
        translation  file  storage  table.   The  routine  takes   no   formal
        parameters.



        7.3.2.7  TRN_DECLARE_TABLE

        Once the Byte Translation table size is known, this action routine  is
        called  to  allocate  the  necessary dynamic memory and initialize the
        table index to 0.  The routine takes no formal parameters.



        7.3.2.8  TRN_STORE_NEXT_TABLE_VALUE

        This action routine is called to store the next  byte  into  the  Byte
        Translation  Table.   After  storing the byte, it increments the index
        into   the   table   for   the   next    call    of    the    routine.
        TRN_STORE_NEXT_TABLE_VALUE takes no formal parameters.
   ALTER-32 Function Specificaiton                                Page 31
   INTERNALS


        7.3.2.9  TRN_DEFAULT_IN_VARREC

|       This routine will determine if all  the  necessary  information  about
|       variable  length  (counted) records was given for the input file(s) in
        the translation file.  If not, the  routine  fills  in  the  defaults.
        This routine takes no formal parameters.



        7.3.2.10  TRN_DEFAULT_OUT_VARREC

        This routine will determine if all  the  necessary  information  about
        variable  length  records  was  given  for  the  output file(s) in the
        translation file.  If not, the routine fills in  the  defaults.   This
        routine takes no formal parameters.



        7.3.3  ALTER_TRANLSATION.BLI

        This module handles all of the byte level,  record  level,  and  block
        level  translation  functions to be performed by the ALTER-32 utility.
        It contains routines to fetch and write bytes of the appropriate size,
        do   padding   or   do   padding   character   suppression,   do  byte
        transformations  through  the  byte  translation  table,  and   handle
        End-of-record and End-of-file conditions.



        7.3.3.1  TRN_TRANSLATE_BYTE

        This routine will  do  all  the  appropriate  transformations  to  the
        current  byte.   Handles  processing for qualifiers such as ADJUST and
        MASK.  If there is a translation table, it uses that  table  to  apply
        the transformation.  The parameter is:

         o  CURR_CHAR - by reference - Byte to be run through the necessary
            translations




        7.3.3.2  MERGE_EFF_INFILE_VALUES

        This routine will scan through the qualifier  values  parsed  and  the
        Translation  file  values  (if a Translation file was present) for the
        input file.  It will select the  effective  values  according  to  the
        following priorities:

         o  Qualifier value from command line

         o  Translation file value

        The routine does a certain  number  of  consistancy  checks,  such  as
        checking for an ILLEGAL character if a -4 has been given as one of the
        entries in the translation table.  There are two parameters:
   ALTER-32 Function Specificaiton                                Page 32
   INTERNALS


         o  EFFECTIVE_TABLE - by reference - Table in which to store the
            effective values

         o  EFFECTIVE_COUNTS - by reference - Table in which to store the
            effective value counts




        7.3.3.3  MERGE_EFF_OUTFILE_VALUES

        This routine will scan through the qualifier  values  parsed  and  the
        Translation  file  values  (if a Translation file was present) for the
        input file.  It will select the  effective  values  according  to  the
        following priorities:

         o  Qualifier value

         o  Translation file value

        The routine does a couple of simple consistancy checks  to  make  sure
        all  the  options  and  qualifiers specified make sense together.  Two
        parameters are passed to the routine.

         o  EFFECTIVE_TABLE - by reference - The table to store the effective
            values

         o  EFFECTIVE_COUNTS - by reference - The table to store the effective
            value counts




        7.3.3.4  CHECK_INFILE_ENVIRONMENT

        This routine will exhaustively check the parameters that were  entered
        by  the  user  concerning  the  input file for consistancy and default
        anything that is necessary.  The routine takes no formal parameters.



        7.3.3.5  CHECK_OUTFILE_ENVIRONMENT

        This routine will exhaustively check the parameters that were  entered
        by  the  user  concerning  the output file for consistancy and default
        anything that is necessary.  This routine takes no formal parameters.



        7.3.3.6  REC_DETECT_EOL_CHR

        This is one of the record layer routines.  It will handle a  piece  of
        the logic for input records.  The routine determines if a character is
        one of a set of single End-of-line characters.
   ALTER-32 Function Specificaiton                                Page 33
   INTERNALS


        There is one parameter given to the routine:

         o  CURR_CHAR - by reference - Character from buffer to check




        7.3.3.7  REC_RET_CHR_DETECT_EOL_CHR

        This is a record layer routine which will handle a piece of the  logic
        for input records.  The routine detects an End-of-line condition for a
        file with a single End-of-line characters from a set of  one  or  more
        End-of-line characters.

        The routine takes one parameter:

         o  CURR_CHAR - by reference - Place to return next character from
            buffer




        7.3.3.8  REC_RET_CHR_DETECT_SEQ_EOL

        This is a record layer routine which handles a piece of the logic  for
        input  records.   The  routine  detects an End-of-line condition for a
        file with an End-of-line sequence.  It  does  this  by  scanning  each
        character that it passes up to the next level routine.  It keeps track
        of how many characters it has seen from the End-of-line sequence.   If
        a  character  matches  the  next one in the sequence, it increases the
        count, otherwise it starts returning characters from  the  End-Of-Line
        sequence.   If it sees the entire sequence, it will return a status of
        ALT_ENDOFLINE.

        The routine takes one parameter:

         o  CURR_CHAR - by reference - Place in which to return next character
            from buffer




        7.3.3.9  REC_RET_CHR_DETECT_VR_EOL

        This is one of the record layer routines.  It detects  an  End-of-line
|       condition for a file with variable length (counted) records.  It takes
|       note of a  leading  record  length  and  counts  out  that  number  of
        characters.   On  the  call  after  the  last character of a record is
        returned, the routine fails with an ALT_ENDOFLINE status.

        This routine takes one parameter:

         o  CURR_CHAR - by reference - Place in which to return next character
            from buffer
   ALTER-32 Function Specificaiton                                Page 34
   INTERNALS


        7.3.3.10  REC_RET_CHR_DETECT_FR_EOL

        This is one of the record layer  routines.   The  routine  detects  an
        End-of-line  condition  for  a file with fixed length records.  On the
        call after it returns the last character of a particular  record,  the
        routine fails with an ALT_ENDOFLINE status.

        The routine takes one character:

         o  CURR_CHAR - by reference - Place in which to return next character
            from buffer




        7.3.3.11  REC_RET_CHR_DETECT_RMS_EOL

        This routine handles RMS input records.  Since records  are  read  one
        per  block,  this  routine  simply  returns End-of-line every time the
        buffer is emptied.

        The routine takes one parameter:

         o  CURR_CHAR - by reference - Place in which to put next character
            read from buffer




        7.3.3.12  REC_RET_CHR_NON_SUPPRESS

        This is a record layer routine that handles the stripping  of  padding
        characters.   If  the  user specifies a SUPPRESS character, and one or
        more of those characters appear immediately  before  the  End-Of-Line,
        those characters will be ignored.

        The routine takes one formal parameter:

         o  CURR_CHAR - by reference - Place in which to return next character
            from buffer




        7.3.3.13  REC_STORE_CHR_DO_EOL_SEQ

        This routine will output characters by calling BLK_DO_OUTPUT_BLOCKING.
        When  ALT_ENDOFLINE  is  passed  in FILE_STATUS, the routine will pass
        each of the characters from the output  End-of-line  sequence  to  the
        byte output routine.

        There are two parameters given to this routine:

         o  CURR_CHAR - by value - Character to be written
   ALTER-32 Function Specificaiton                                Page 35
   INTERNALS


         o  FILE_STATUS - by value - Status for indicating End-of-line or
            End-of-file




        7.3.3.14  REC_STORE_CHR_DO_PADDING

        This routine will pass characters on to BLK_DO_OUTPUT_BLOCKING.  As it
        passes  character through, it will count them and it will truncate the
        record if it exceeds the output record size and fixed  length  records
        are  being written.  If the record is short of the output record size,
        it will fill the record with the fill  character  (which  defaults  to
        null if none is specified).

        There are two parameters given to this routine:

         o  CURR_CHAR - by value - Character to be written

         o  FILE_STATUS - by value - Status indicating End-of-line or
            End-of-file




        7.3.3.15  REC_STORE_CHR_DO_VLR

        This routine will store characters until an entire record is seen.  It
        then  takes  the byte count and creates a numeric string of the length
        specified by the VR_LENGTH qualifier (which defaults to 4).  This byte
        count  is  written out followed by the actual record using a series of
        calls to BLK_DO_OUTPUT_BLOCKING.  The numeric string may be  coded  in
        any character set (the default is ASCII) by specifying the base of the
        numeric characters in  the  coding  scheme  used  (i.e.   for  EBCDIC,
        specify VR_ZERO_CHAR=240).

        Two parameters are passed to this routine:

         o  CURR_CHAR - by value - Character to be written

         o  FILE_STATUS - by value - Status indicating End-of-line or
            End-Of-File




        7.3.3.16  REC_STORE_CHR_DO_RMS

        This is one of the record layer routines.  It handles the  case  where
        we  are dealing with an RMS file.  Records are written to the file one
        at a time so End-Of-Line implies End-Of-Block.

        The routine takes two formal parameters:
   ALTER-32 Function Specificaiton                                Page 36
   INTERNALS


         o  CURR_CHAR - by value - The character to write to the record

         o  FILE_STATUS - by value - Status of input file (True, End-Of-Line,
            End-Of-File etc.).




        7.3.3.17  BLK_FETCH_BLOCK

        This routine will fetch a block of data from the input file.  It  will
        strip any block fill characters from the end of the block and note the
        actual block length.  If logging of block sizes is requested, it  will
        write  the  size  of  the block read out to the terminal.  The routine
        takes no formal parameters.



        7.3.3.18  BLK_WRITE_BLOCK

        This routine is called when we wish to force the current block  to  be
        written, even if it is not full.

        The routine takes no formal parameters.
|  
|  
|  
|       7.3.3.19  BLK_CLEAR_OUTPUT_BUFFER
|  
|       This routine is used when we wish to  clear  out  the  current  output
|       buffer, and fill it with NULLS.



        7.3.3.20  BLK_CHECK_LAST_BLOCK

        This routine will check the last output block.  If there is  any  data
        in it, it will be written to the file with a call to IO_PUT.

        The routine does not take any formal parameters.
|  
|  
|  
|       7.3.3.21  BLK_CHECK_RECORD_FIT
|  
|       This routine will check if a record of a particular size will  fit  in
|       what  remains  of the current output buffer.  If it does not fit, this
|       routine will write the buffer out.
|  
|       The routine takes one formal parameter:
|  
|        o  CHARACTER_COUNT - by value - Number of characters in record
|  
   ALTER-32 Function Specificaiton                                Page 37
   INTERNALS


        7.3.3.22  BLK_DO_OUTPUT_BLOCKING

        This routine will pass characters down to BYT_WRITE_A_BYTE.   It  will
        monitor  the number of records passing through and if there is a value
        for block_factor, it will make sure that the current block  is  output
        to disk after the proper number of records have been written.  It also
        handles insertion of padding characters if necessary.

        The routine takes two formal parameters:

         o  CURR_CHAR - by value - Next character to pass on

         o  FILE_STATUS - by value - Status of input file (True, End-of-line,
            End-of-file, etc.)




        7.3.3.23  BLK_DO_INPUT_BLOCKING

        This routine will note when the end of block has been reached and will
        request the next block from the input file.  It will take into account
        whether or not there is a blocking factor.

        The routine takes one formal parameter:

         o  CURR_CHAR - by reference - Character returned from the file




        7.3.3.24  BYT_FETCH_A_BYTE

        Gets the next byte from the input buffer.  The bytes extracted will be
        of  the  appropriate  size  based on the INPUT_BYTE_SIZE option or the
        BYTE_SIZE qualifier.  When the buffer is  empty,  this  routine  calls
        BYT_FETCH_A_BUFFER to get more data from the input file.

        This routine takes one formal parameter:

         o  CURR_CHAR - by reference - Place in which to return character from
            buffer




        7.3.3.25  BYT_WRITE_A_BYTE

        This routine will write a byte into the buffer.  The  byte  size  used
        will  be  governed  by  the  OUTPUT_BYTE_SIZE  option or the BYTE_SIZE
        qualifier.    When   the   buffer   is   full,   the   routine   calls
        BYT_WRITE_A_BUFFER to dump the buffer to disk.

        The routine takes one formal parameter:
   ALTER-32 Function Specificaiton                                Page 38
   INTERNALS


         o  CURR_CHAR - by value - Byte to stuff into the buffer




        7.3.3.26  CVT_NUM_STR

|       This routine is used to convert the record length for counted  records
        to/from a string.

        There are three formal parameters given to the routine:

         o  THE_NUMBER - by reference - Number to convert (or place to put
            converted string)

         o  THE_STRING - by reference - String to convert (or place to put
            converted number)

         o  NUM_2_STR - by value - True means conversion is from number to
            numeric string otherwise convert the string to a number.




        7.3.3.27  PROCESS_IGNORE_ERRS_OPTION

        If /IGNORE_ERRORS is specified by the user, this routine  is  used  to
        convert  status  codes  for  tape  errors to equivalent warning status
        codes.  It also signals the error or warning.

        The routine takes two formal parameters:

         o  ERROR - by value - The error status to convert

         o  KEYWORD - by value - Indicates whether error was on input or
            output




        7.3.4  ALTER_FILE_IO.BLI

        This program handles I/O for the ALTER-32 program.   It  dispathes  to
        routines which handle either tape or disk files depending on where the
        files reside.



        7.3.4.1  IO_OPEN_FIRST

        The purpose of this routine is to handle all file opening requests  it
        will  dispatch  to  the  proper  opening routine, either tape or disk,
        depending on the value returned in the parsing.  A value will  be  put
        into  the  location contained in FILE_ID that will be used to uniquely
        identify the file for all subsequent file operations.  This FILE_ID is
        actually  the address of the file information block holding all of the
   ALTER-32 Function Specificaiton                                Page 39
   INTERNALS


        data about it.

        The routine takes five formal parameters:

         o  RETURN_FILE_ID - by reference - contains the return address for
            the file identifier

         o  FILENAME_DESC - by descriptor - contains a descriptor block
            specifing the file name string

         o  NUM_BUFF - by value - contains the value specifiing the number of
            buffers

         o  MAX_BUFF_SIZE - by value - contains value of maximum buffer size

         o  EXPANDED_INPUT_FILE - by descriptor - contains address of
            descriptor for resultant file name




        7.3.4.2  IO_OPEN_NEXT

        The purpose of this routine is to handle  all  file  opening  requests
        which  contain  wildcards.   It  will  utilize the RMS search and will
        dispatch to the proper opening routine, either tape or disk, depending
        on the device returned from IO_INFORMATION.

        The routine takes two formal parameters:

         o  FILE_ID - by value - contains the address of the file information
            block

         o  EXPANDED_INPUT_FILE - by descriptor - address of descriptor for
            the resultant file name.




        7.3.4.3  IO_CREATE

        The purpose of this routine is to handle all file  creation  requests.
        It  will  dispatch to the proper opening routine, either tape or disk,
        depending on the value returned in the parse.  A  value  will  be  put
        into  the location contained in FILE_ID that will allow that caller to
        uniquely refer to the file in subsequent calls to ALTER_FILE_IO.

        The routine takes eight formal parameters:

         o  RETURN_FILE_ID - by reference - return address for file identifier

         o  FILENAME_DESC - by descriptor - file name string of file to create

         o  NUM_BUFF - by value - number of buffers to create
   ALTER-32 Function Specificaiton                                Page 40
   INTERNALS


         o  MAX_BUFF_SIZE - by value - maximum size of each buffer

         o  BUFFER_ADDR - by reference - first buffer for output

         o  DEFAULT_FILENAME_DESC - by descriptor - default file name string

         o  EXPANDED_OUTPUT_FILE_DESC - by descriptor - Resultant output file
            name

         o  FDL_FILENAME_DESC - by descriptor - fdl file name for record
            attributes.




        7.3.4.4  IO_GET

        This routine reads one buffer  or  record  from  an  input  file.   It
        dispatches  to  a routine to handle the get for the appropriate device
        type.

        The routine takes three parameters:

         o  FILE_ID - by value - file identifier (address of file information
            block)

         o  BUFFER_ADDR - by reference - address in which to return the buffer
            address

         o  BUFFER_LEN - by reference - address in which to return the buffer
            size in chars




        7.3.4.5  IO_PUT

        This routine handles the writing of a record or  block  to  an  output
        file.   It  dispatches to the appropriate PUT routine according to the
        device on which the file resides.

        The routine takes three formal parameters:

         o  FILE_ID - by value - file identifier of output file (address of
            file information block)

         o  BUFFER_ADDR - by reference - output buffer address

         o  BUFFER_LEN - by reference - output buffer length
   ALTER-32 Function Specificaiton                                Page 41
   INTERNALS


        7.3.4.6  IO_INFORMATION

        The purpose of this routine is to return to  the  caller,  information
        about the characteristics of the specified file.

        There are three parameters given to this routine:

         o  FILENAME_DESC - by reference - File specification string
            descriptor

         o  REQUEST - by value - Token for item of information requested

         o  INFORMATION_ITEM - by reference - Descriptor to hold returned data




        7.3.4.7  IO_LOG

        This routine will return the  proper  filename  for  logging  purposes
        only.  It is called only from outside the ALTER_FILE_IO module.

        There are two formal parameters given to the routine:

         o  FILE_ID - by value - File identifier, address of file information
            area

         o  FILE_DESC - by descriptor - address of descriptor in which to
            place file name




        7.3.4.8  IO_CLOSE

        This routine handles all of the file closing that will be  needed  for
        I/O.   It will dispatch to the appropriate routines to close both disk
        and tape files.  The caller need  only  identify  the  file  with  the
        file-id returned to the caller when the file was opened.

        The routine takes only one formal parameter:

         o  FILE_ID - by value - File identifier of file to be closed




        7.3.4.9  DEALLOC_MEM

        This routine is called by  IO_OPEN_NEXT  and  by  IO_CLOSE.   It  will
        deallocate  all  the  space  that was allocated to process I/O for the
        file (buffers, file information  blocks,  buffer  information  blocks,
        etc.).
   ALTER-32 Function Specificaiton                                Page 42
   INTERNALS


        The routine takes one formal parameter:

         o  FILE_ID - by value - File identifier, address of file information
            block




        7.3.4.10  ALLOCATE_FILE_INFO

        This routine will allocate the area necessary for the file information
        and  buffer information blocks.  It will also divide that area up into
        the respective blocks.

        The routine takes one formal parameter:

         o  FILE_ID - by reference - Location at which to place address of
            file information block




        7.3.4.11  ALLOCATE_BUFFER_AREA

        This routine will allocate all the necessary space  for  QIO  buffers.
        It  will  also divide up the space into buffers and buffer information
        records.

        The routine takes four formal parameters:

         o  FILE_ID - by value - Address of file information area

         o  DEV_TYPE - by value - Device type ('TAPE' or 'DISK' literals)

         o  MAX_BUFF_SIZE - by value - Maximum size of buffers

         o  NUM_BUFF - by value - Number of buffers to create




        7.3.4.12  RMS_BLOCK_INIT

        This routine will initialize the NAM and the FAB blocks  for  any  RMS
        processing  done  by  the program.  It will only initialize the fields
        that are common to both  input  and  output.   The  fields  which  are
        specific to input or output must be set after calling this routine.

        The routine takes four formal parameters:

         o  FILE_ID - by value - Address of file information area

         o  KEYWORD - by value - Input/Output flag ('OPEN' or 'CREATE'
            literals)
   ALTER-32 Function Specificaiton                                Page 43
   INTERNALS


         o  FILENAME_DESC - by descriptor - Descriptor of file to be processed

         o  MAX_BUFF_SIZE - by value - Maximum buffer size




        7.3.5  ALTER_DISK_IO.BLI

        This module handles  all  disk  I/O.   It  uses  RMS  exclusively  for
        openning, reading, writing, and closing disk files.



        7.3.5.1  OPEN_DISK

        This routine will open a disk file using RMS.  It is dispatched to  by
        IO_OPEN_FIRST and IO_OPEN_NEXT.

        Two formal parameters are given to the routine:

         o  FILE_ID - by value - Address of the file information block

         o  EXPANDED_FILE_DESC - by descriptor - pointer to descriptor in
            which to store resultant filename string.




        7.3.5.2  GET_DISK

        This routine will read a record from a disk file.  It utilizes RMS  to
        acomplish this.  IO_GET dispatches to this routine.

        One parameter is required:

         o  FILE_ID - by value - Address of the file information block for the
            file




        7.3.5.3  PUT_DISK

        This routine will write a record to a disk file.  IO_PUT dispatches to
        this  routine  to  do the necessary disk-specific functions, including
        the RMS call to write the record.

        One formal parameter is needed:

         o  FILE_ID - by value - Address of the file information block for the
            file
   ALTER-32 Function Specificaiton                                Page 44
   INTERNALS


        7.3.5.4  CLOSE_DISK

        This routine closes a disk file.  IO_CLOSE dispatches to it to perform
        the disk-specific tasks including the RMS call to close the file.

        The routine takes one formal parameter:

         o  FILE_ID - by value - Address of the file information block for the
            file to be closed.




        7.3.5.5  PROCESS_RMS_ERROR

        This routine will process all of the RMS  errors  which  occur  during
        runtime.  Where appropriate, it translates RMS error codes to internal
        ALTER error codes.

        One formal parameters is required:

         o  ERROR - by value - The RMS error code to translate




        7.3.5.6  DISK_FILE_LOGGING_PROCESS

        This routine will return a complete file name for disk  files.   These
        names are only used for purposes of logging file activity.

        Two formal parameters are given to the routine:

         o  FILE_ID - by value - Address of the file information block

         o  FILE_DESC - by descriptor - Address of descriptor in which to
            place file spec




        7.3.5.7  FLAG_FOR_RECORD_TYPE

        This routine will proform any necessary special functions dependent on
        the particular record type being accessed.

        Two formal parameters are given to the routine:

         o  FILE_ID - by value - Address of the file information block

         o  RECORD_TYPE - by value - Specifies the record type of the file to
            be accessed
   ALTER-32 Function Specificaiton                                Page 45
   INTERNALS


        7.3.6  ALTER_TAPE_IO.BLI

        This  module  handles  all  the  tape  specific  I/O  functions  (i.e.
        openning or creating tape files, reading, writing, and closing).



        7.3.6.1  OPEN_TAPE

        This routine opens a tape  file.   All  tape  specific  functions  are
        performed by QIO calls.

        Two formal parameters are neede by this routine:

         o  FILE_ID - by value - Address of the file information block for
            file to be opened

         o  FILE_DESC - by descriptor - Address of descriptor in which to
            place the expanded file name string




        7.3.6.2  PROCESS_FOREIGN_FILE

        This routine will do the special processing required by  foreign  tape
        files.   The special processing, among other things, is for generating
        a file name.  It is called from IO_OPEN_NEXT.

        The routine takes two formal parameters:

         o  FILE_ID - by value - Address of the file information block

         o  FILE_DESC - by descriptor - Address of descriptor in which to
            place the expanded file name string




        7.3.6.3  GET_TAPE

        This routine reads a buffer from a tape file.  IO_GET dispatches to it
        to do the tape specific tasks involved in reading the file.

        The routine takes one formal parameter:

         o  FILE_ID - by value - Address of the file information block




        7.3.6.4  PUT_TAPE

        This routine writes a buffer to a tape file.  It is called from IO_PUT
        to  do  the  tape  specific  functions involved in writing a buffer to
        tape.
   ALTER-32 Function Specificaiton                                Page 46
   INTERNALS


        The routine takes one formal parameter:

         o  FILE_ID - by value - Address of the file information block




        7.3.6.5  CLOSE_TAPE

        This routine is used to perform the functions  necessary  to  close  a
        tape file.  It is called from IO_CLOSE.

        The routine takes one formal parameter:

         o  FILE_ID - by value - Address of the file information block

|  
|  
|  
|       7.3.6.6  REWIND_TAPE_DRIVE
|  
|       This routine is used to rewind the tape on the device specified in the
|       calling  parameters.  If the device is not a tape-drive or not mounted
|       foreign then an informational message is given to  the  user  and  the
|       /REWIND qualifier is ignored for that device.
|  
|       This routine takes two formal parameters:
|  
|        o  FILE_NAME_DESCRIPTOR - by descriptor - Address of decriptor
|           containing divice name
|  
|        o  OUT_FLAG - by value - Boolean value indicating that this is the
|           output device
|  



        7.3.6.7  OPEN_THE_FILE

        This routine will do the actual QIO call to access the tape file.

        The routine takes two formal parameters:

         o  FILE_ID - by value - Address of the file information block for the
            file to be accessed

         o  FILENAME_DESC - by descriptor - Address of the descriptor in which
            to place the resultant file name string




        7.3.6.8  CREATE_THE_FILE

        This routine does the QIO call to create a tape file.
   ALTER-32 Function Specificaiton                                Page 47
   INTERNALS


        The routine takes two formal parameters:

         o  FILE_ID - by value - Address of the file information block for the
            file to be created

         o  FILENAME_DESC - by descriptor - Address of descriptor in which to
            place the file name of the file created




        7.3.6.9  PROCESS_QIO_ERROR

        This routine will process all Qio errors which occur at  runtime.   If
        necessary,  it  will translate a QIO error into an equivalent internal
        Alter error code.  Otherwise, it simply returns the error code  passed
        to it.

        The routine takes one formal parameter:

         o  ERROR - by value - The QIO error code to process




        7.3.6.10  GENERATE_FOREIGN_FILENAME

        This routine will generate file names  for  foreign  tape  files.   It
        creates them in the form:

               Device:FILEnnn

        where 'Device:' is the device name and nnn is  a  1-3  digit  sequence
        number.

        The routine takes two formal parameters:

         o  FILE_ID - by value - Address of the file information block

         o  FILE_DESC - by descriptor - Address of descriptor in which to
            return the file name generated




        7.3.6.11  TAPE_FILE_LOGGING_PROCESS

        This routine will process  the  tape  file  name  and  will  return  a
        complete  file  specification  including device, directory, file name,
        file type,and file version.

        The routine takes two formal parameters:

         o  FILE_ID - by value - Address of the file information block
   ALTER-32 Function Specificaiton                                Page 48
   INTERNALS


         o  FILE_DESC - by descriptor - Address of descriptor in which to put
            the file specification




        7.3.6.12  EOF_CATCH

        This routine will cancel all pending QIO's associated with a file when
        an End Of File is detected by READVBLK QIO call.

        The routine takes one parameter:

         o  CURRENT_BUFFER_ADDRESS - by reference - Qio buffer information
            block for the buffer which got the End-Of-File