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.
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.
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.
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.
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)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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