!TITLE VSS UTILITIES
!TOPIC VSS
   General information about VSS applicable to many utilites
is to be found under the heading GENERAL. Other information relating
to specific utilities is to be found under the command name.

!<GENERAL
!KEY
      VSS (Virtual Space Simulator) is a program which runs under
   EMAS, which emulates many of the functions of an IBM OS/VS
   operating system, and so enables many IBM programs to run unmodified.

!<IMPLEMENTATION
!KEY
      Much of the code of VSS is derived from work done at Durham
   university, where it was used to run OS/VS programs in the environment
   of their MTS/MVS operating systems. Hence, our VSS contains within it
   many facilites which emulate MVS facilities. The emulation has two
   stages: OS => MVS => EMAS. This is usually transparent to the user,
   but there are some cases (especially diagnostic messages) where the
   two-stage emulation will be apparent.
      The VSS we obtained from Durham was claimed to be a very full
   emulation of OS/VS facilities, but there are some difficulties with
   our EMAS implementation.
   1. We have not yet implemented all of the Durham VSS.
   2. We have not implemented all of the MVS support facilites required
      by VSS.
   3. Many of the facilities present have not been fully tested and may
      contain bugs.

      Hence, there may be problems with our implementation. These are
   gradually being resolved as more OS programs are run successfully.
!>
!<LICENCING
!KEY
   Many of the packages available to be run under VSS are subject to
licence agreements, which limit the way in which they may be used.
Many of the packages are made available to us on the understanding
that they are for teaching and non-profit research only. Also, they
may not be transferred between machines without the approval of
the originators.
   Details of particular licences will normally be given in the
help information for the package itself. Please respect these
agreements.
!>
!<ROUTES
!KEY
   A VSS ROUTE is a filename, or a construction of the form
   (filename,maxsize,type). This second form contains parameters
much the same as those used by DEFINE.
Some valid routes are:
   .out
   (.null)
   (outsq,,EV1024)

Values for the "type" field are interpreted as follows:
C..Character file (ISO code)
V..Sequential file, ISO code
E..(OR EV) Sequential file, EBCDIC code.
L..VSS "LINE" file (EBCDIC code)

   The types E, EV and V may also have a record length. If not, then
a default is assumed.
   The parameter "maxsize" is only relevant if the file is to be
written. It does not apply to Line files.
  The parameter "type" may be ommitted if the file already exists, as
the type is then determined from the file itself.
   Beware the difference between E and V format. VSS itself
operates in EBCDIC, and translates all data to EBCDIC on reading
it. Hence, the most usual format is "E". Files which contain
binary or EBCDIC data, but which have not been marked as Ebcdic
may be so marked using the command SETSQCODE.
   The LINE file is the most complicated and general type of file,
and should be used for Partitioned Data Sets or Libraries, Direct access
data sets, simulated disks, and data sets on which much re-positioning
is done.
!>
!<LINE FILES
!KEY
   "Line" files are special files used under VSS which support very
general access.
   The file is considered to comprise a number of lines, each of which
has a line-number and length. Any line can be accessed by its line
number, which is often a multiple of 1000. A line of arbitrary
line number and length can be inserted anywhere in the file.
   Many VSS operations can be supported on other EMAS file types, but
line files are required to support (IBM) partitioned data sets
(e.g. macro libraries, load libraries etc.) and for simulated disk files
(including DA files). In addition, the direct-access capability
of line files makes them more efficient when the package requires
to do a lot of re-positioning of the file. This includes many
work files.
   A number of utilites are provided to look at the contents
of line files. These include SCANLINF, DUMPLINF, and COPYLINF.
When manipulating a line file, it is often best to use COPYLINF
to copy the file into an EMAS (ebcdic) sequential file, and then
to manipulate that.
!>
!>END OF VSS
!<LISTLINF
   LISTLINF infile,outfile
Gives a listing of a linefile, including line numbers and lengths.

!PAMSTOP
The following paragraphs describe the parameters to this command.

!<INFILE
!KEY
Input file name.
!>
!<OUTFILE
!KEY
Output file or device.
!>
!>end of listlinf
!<SCANLINF
   SCANLINF infile,outfile
Gives the numbers and lengths of lines in a line file.
"outfile" defaults to ".out".
At the end, the number of lines in the file and the
maximum line length is printed.

!PAMSTOP
The following paragraphs give information about the parameters
to this command.

!<INFILE
!KEY
Name of file to be scanned.
!>
!<OUTFILE
!KEY
Output filename or device.
!>
!>end of scanlinf
!<DUMPLINF
Gives a full hexadecimal dump of each line in a file,
which may be a line file, a SQ file, or a stream file.
ISO files are converted to EBCDIC before dumping.

!PAMSTOP
The following paragraphs describe the parameters
used by this command.

!<INFILE
!KEY
Name of file to be dumped
!>
!<OUTFILE
!KEY
Output filename or device.
!>
!<START
!KEY
Start Line Number - applies only to Line files.
Remember that line numbers are usually multiples of 1000.
By default, dumplinf starts at the beginning of the file.
!>
!<LEN
!KEY
Maximum length of data to be dumped in each block.
May not exceed 8192.
This value limits the amount of data dumped for long data blocks.
!>
!>end of dumplinf
!<COPYLINF
   COPYLINF inroute,outroute
E.g. Copylinf infile,outfile
or    copylinf infile,(outfile,,l)
Copies from inroute to outroute, both of which may be of stream,
sequential, or line format.
   Unless otherwise specified, outroute will be of stream
format, unless this route references a file which already
exists. In this case, the output file retains its type.

!PAMSTOP
The following paragraphs describe the parameters to this command.

!<INFILE
!KEY
The input route, or input filename.
!>
!<OUTFILE
!KEY
The output route. By default, this will be in stream format, unless
the output file already exists, in which case this format will
be used.
E.g. (outfile,,L)
!>
!>end of copylinf
!<VFILETYPE
VFILETYPE infile
   Prints the type of file "infile" - which may be stream,
iso sequential, ebcdic sequential, or line file.

!PAMSTOP
The following paragraph describes the parameter to this command.

!<FILENAME
!KEY
The name of a stream, iso seqential, ebcdic sequential, or line file.
!>
!>end of vfiletype
!<SETSQCODE
SETSQCODE infile,code
   Marks a sequential file as iso or ebcdic. The
data in the file is not changed by this command, but programs which
operate on this file may examine the data code type, and
interpret the data accordingly.

!PAMSTOP
The following paragraphs describe the parameters to this command.

!<FILE
!KEY
   The name of a sequential (SQ) file.
!>
!<CODE
!KEY
   ISO or EBC. The data code relating to the data in the file.
!>
!>end of setsqtype
!<VCREATEF
VCREATEF infile
   Creates an empty line file of name "infile".
An empty line file may be used as a Partitioned Data Set - currently
containing no members.
!>
!<VSSLIB
   This command manipulates an (IBM) partitioned data set,
or library file - e.g. a macro or load library.
The parameter "function" determines the action taken.
!PAMSTOP
The function parameter and various actions are described in the
paragraphs under section FUNCTION. The other paragraphs describe the
various parameters which may be required depending on the function
specified.
   A null Partitioned Data Set may be created using command VCREATEF.
Partitioned Data Sets may be used as Macro Libraries, or as
Load Libraries, amongst other things.
Libraries of macros and copy sections may be manipulated using the
command VMACLIB.
Information about Load Libraries may be obtained using command VLOADLIB.

!<FUNCTION
!KEY
Specify one of the following functions:
MAP     Print a map of the partitioned data set directory.
LIST    Print map, together with dump of user data.
COPY    Copy a member of a partitioned data set.
DELETE  Delete an entry in a partitioned data set directory.
RENAME  Rename an entry in a partitioned data set directory.
ALIAS   Create an entry in a partitioned data set directory.

!PAMSTOP
   The following paragraphs describe these functions in more
detail.

!<MAP
!KEY
   VSSLIB MAP,infile
   Gives a "map" of the VSS partitioned data file "infile". The map
includes the name of each member, its starting record number, the
number of "user half words" of extra data in the file directory, and
the number of "ttr" or record pointer records in the directory.
!>
!<LIST
!KEY
   VSSLIB LIST,infile
   Gives a listing of the directory of the VSS partitioned data file
"Infile". This includes all the information as for MAP, together with
a dump of the user data associated with each member.
!>
!<DELETE
!KEY
   VSSLIB DELETE,fileid_member
   Deletes member "member" of the VSS partitioned data file "fileid".
In accordance with usual IBM practice, the deleted space is not recovered.
!>
!<RENAME
!KEY
   VSSLIB RENAME,fileid_member1,fileid_member2
 OR VSSLIB RENAME,fileid_member1,member2
   Renames member "member1" of VSS partitioned data file "fileid" as
member "member2". All other directory information is retained.
!>
!<ALIAS
!KEY
   VSSLIB ALIAS,fileid_member1,member2
   Creates a new entry in the directory of the partitioned data set
"fileid". The new entry has all the attributes of member "member1",
but has name "member2". Hence, the new name "member2" describes the
same member as the old name "member1". The alias bit is set on the
new directory entry.
!>
!<COPY
!KEY
   VSSLIB COPY,infile,fileid_member
   VSSLIB COPY,fileid_member,outfile
   VSSLIB COPY,fileid1_member1,fileid2_member2

   Copies a file, or member of a VSS partitioned data file, to another
file, or member of a VSS partitioned data file.
   Either the input, or the output file must be a partitioned data file
member.
   If both input and output files are members of partitioned data files,
then the directory information is also copied, and any information
relating to record addresses is also updated. Otherwise, no directory
information can be copied or generated.
   Input and output files may not both be members of the same VSS
partitioned data file.
   An empty line file will serve as a null VSS partitioned file.
Thus, to create a null VSS partitioned file, use VCREATEF.
   If the output file is a member of a partitioned data file,
and that member already exists, then the copy will fail unless
OVERWRITE=YES is given.
!>
!> end of vsslib-function
!<PDSET
!KEY
The filename of the MVS partitioned data set.
!>
!<INFILE
!KEY
The input filename. This may take the form pdsfile_member
if required, to specify a member of an MVS partitioned data set.
   If both input and output files are members of partitioned
data sets, then the user data in the partitioned data set directory
is also copied.
!>
!<OUTFILE
!KEY
The output filename. This may take the form pdsfile_member
if required, to specify a member of an MVS partitioned data set.
   If both input and output files are members of partitioned
data sets, then the user data in the partitioned data set directory
is also copied.
!>
!<PDSMEM
!KEY
An existing member of an MVS partitioned data set.
E.g. PDSFILE_MEMBER
!>
!<NEWMEMBER
!KEY
The name (not exceeding 8 characters) of the new member.
This member must not currently exist.
!>
!<OVERWRITE
!KEY
   This parameter is required if VSSLIB COPY is attempting to
overwrite an existing file. Specify YES if this is intended,
NO otherwise.
!>
!>end of vsslib
!<VLOADLIB
    VLOADLIB MAP,infile
   Gives a map of the VSS partitioned data file "infile", which is assumed
to be a loadlib. This includes the name and storage required
for each member of the loadlib. This information is obtained from the
partitioned file directory.
!>
!<VMACLIB
Utility used to DUMP or GENerate a MACLIB containing MACROs or
COPY sections. The action of this routine is governed by the
function parameter.
Other functions may be performed on macro libraries using
the VSSLIB utility.
!<FUNCTION
!KEY
Give one of the following
DUMP      Dump a macro library, producing COPY directives for each
          subfile.
MACDUMP   Dump a macro library, assuming that all members are valid
          macros, with names corresponding to the member names.
GEN       Generate a macro library from a source file containing
          COPY directives.
MACGEN    Generate a macro library from a source file containing
          macros. The names of the members are derived from the
          names of the macros.
!>
!<MACLIB
!KEY
Give the name of the MACRO library.
If the function is GEN or MACGEN, then any existing file will be
overwritten.
!>
!<CHARFILE
!KEY
Give the name of the source file from which the library is to be
generated, or to which the library is to be dumped.
!>
!>end of Vmaclib
!<VLIBFROMCMS
   VLIBFROMCMS infile,outfile
   Copies a CMS partitioned data file into a VSS partitioned data file.
The input file should normally be an ebcdic sequential file. The output
is a VSS line file.
   Please note that IBM partitioned files do accumulate quantities of
junk - i.e. unused and unaccessable data which has been part of the file
data at some time past. Before moving partitioned files, please
remove junk by compressing them.

!>
!<VLIBFROMUPDS
   Converts an unloaded partitioned data set into a VSS library.
This utility will work with LOADLIB type files, as well as with
text libraries.
   The input for this utility is an ebcdic sequential file containing
80 byte records. On tape, this would be F80 or FB80. If the file is
not of this format, then try VSS UTILITY VLIBFROMBAS.

!PAMSTOP
Information about the parameters to this command is given in the
following paragraphs.

!<INFILE
!KEY
The name of the input file. This should be an EMAS sequential file
of record length 80, normally read from tape, and should have been
marked as EBCDIC (using SETSQCODE).
!>
!<OUTFILE
!KEY
The name of the output file. The output file will be a VSS library.
!>
!<OPTIONS
!KEY
Options. This number is the sum of various bits:
1..monitor file and block headers.
2..monitor member names.
!>
!>end of vlibfromupds
!<VLIBFROMBAS
Converts a file in the format used by BAS at Cambridge
into a VSS library.
VLIBFROMBAS is the appropriate command to deal with most
tapes of release software from IBM sites.
The input to this utility is an EBCDIC sequential file of
variable record length. On tape, this always has VS format. If
the file is F80 or FB80 format, then try VSS UTILITY VLIBFROMUPDS.
!PAMSTOP

The following paragraphs contain information about the parameters
to this command, and the files involved.
!<INFILE
!KEY
Input file name. The input file should have been read from tape, and
marked as EBCDIC using SETSQCODE. On tape, the file will have had
RECFM of VS. On EMAS, this file will be an EBCDIC sequential file of
variable record length.
!>
!<OUTFILE
!KEY
Name of the output file, which will be a library or partitioned data
file for use under VSS.
!>
!<OPTIONS
!KEY
&1#0..monitor block data structure.
&2#0..monitor doread.
&4#0..monitor ttrs of records being processed.
!>
!>end of vlibfrombas
!<VUNBLOCK
   VUNBLOCK infile=..,outfile=..,recfm=F, lrecl=..
or VUNBLOCK infile=..,outfile=..,recfm=V
   Unblocks IBM blocked files.
   For input files of format "V", "VB" or "VBS", "recfm=V" should
   be specified.

!PAMSTOP
The following paragraphs describe the parameters to this command.

!<INFILE
!KEY
Blocked input file.
!>
!<OUTFILE
!KEY
Unblocked output route.
!>
!<RECFM
!KEY
Record format - i.e. F or V.
Specify V if format is V, VB, VS, or VBS.
If format F, then LRECL will be requested.
!>
!<LRECL
!KEY
Record length - i.e. length of records within blocks of blocked
input file. Block size is always an exact multiple of record length.
The usual value for LRECL is 80, which corresponds to card images.
!>
!>end of vunblock
!<VREBLOCK
   VREBLOCK infile=..,outfile=..,recfm=..,blksiz=..
   VREBLOCK is the opposite of VUNBLOCK. It takes individual
   records, and forms a blocked file according to the given 
   recfm and blksiz.
   Recfm may be "V", "VB", "VS" or "VBS".
   Blksize is the maximum block size for formats "VB", "VS" and "VBS",
   but is not required for recfm="V".
   When an IBM standard labelled tape is read using the standard
   ERCC utilities, then blocked files are normally split into
   individual records. VREBLOCK may be used to invert the process.

!PAMSTOP
The following paragraphs describe the parameters to this command.

!<INFILE
!KEY
Input file name. This file contains the records which are to be
assembled to form the blocks of the output file.
!>
!<OUTFILE
!KEY
Blocked output route. A stream file is not suitable for
this purpose, so an ebcdic SQ file, or line file should
be specified.
E.g. (outfile,,EV6000) or (outfile,,L)
!>
!<RECFM
!KEY
Record format. I.e. V, VB, or VBS.
!>
!<BLKSIZ
!KEY
Maximum block size of output file.
!>
!>end of vreblock
!<JOINSQ
   JOINSQ infile1,infil2...,.end,outfile
   Joins sequential files, provided they have compatible formats.
   This is useful where sequential files have been read from tape
   into individual part files, which need to be joined together.
   Subsystem limits may need to be modified, if it is desired to
   create very large files.

!PAMSTOP
The following paragraphs contain information about the parameters
to this command.

!<INFILE
!KEY
Name of input SQ file, or ".end".
!>
!<OUTFILE
!KEY
Name of output SQ file.
!>
!>end of joinsq
!<VZAP
VSS Utility to patch load modules - i.e. members of load libraries.
The patching is done in place. Hence, the user should make a copy
of the original file before patching, if necessary.
Existing data is overwritten by this program. No new program
areas can be created.
Relocation requests are not effected, so the patched data may be
modified during the load sequence. The relocation requests referring
to areas which are patched or dumped are printed during patch and
dump.

!PAMSTOP
Information about the parameters required is given in sections
LIBRARY, MEMBER, and COMMAND.

Depending on the command given, further parameters are read, and
information about these is available in the further paragraphs.
Information about the parameters is given in the following sections.

!<LIBRARY
!KEY
The name of the VSS library file containing the load module
to be patched.
!>
!<MEMBER
!KEY
The member name within the load library file of the load module
to be patched.
The member name should not exceed 8 characters in length.
!>
!<COMMAND
!KEY
The command  to be executed. Valid commands are:

STOP       End processing.
QUIT       Same as STOP.
SYMBOLS    Print symbol table.
DUMP       Dump part of load module.
PATCH      Patch part of a load module.

!>
!<DUMPSECTION
!KEY
The name of the control section to be dumped.
!>
!<DUMPOFFSET
!KEY
The start address within the control section, where dumping is to start.
!>
!<DUMPLEN
!KEY
The length of the data to be dumped.
!>
!<PATCHSECTION
!KEY
The name of the control section to be patched.
!>
!<PATCHOFFSET
!KEY
The start address within the control section, where patching is to start.
!>
!<PATCHDATA
!KEY
The (halfword) data to be stored at the patch address.
Give "-1" to terminate. Reading data also stops at end of section,
and when the patch table is full.
   E.g. x47F0
!>
!>end of ZAP