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