Defining and Loading VSAM Files

Like OS/390, the Tachyon Operating System requires that VSAM files be explicitly defined before they can be used. OS/390 provides the IDCAMS utility for this purpose. The Tachyon Operating System provides the tosvsam program to delete, define, load and list the definition of VSAM files. The Tachyon Operating System does not provide a way to define and delete VSAM files through JCL DD and EXEC PGM=IDCAMS statements.

Defining a VSAM File

The tosvsam utility can define VSAM files of any of the 4 record-oriented types: Key Sequence Data Sets (KSDS), Entry Sequenced Data Sets (ESDS), Relative Record Data Sets (RRDS) and Variable Length Relative Record Data Sets (VRRDS). Linear Data Sets (LDS) and Alternate Indexes are not supported in the current release of the Tachyon Operating System. The tosvsam utility does not need much of the allocation information required by IDCAMS to define a VSAM file, so many of the DEFINE CLUSTER parameters are not needed. Other DEFINE CLUSTER information is not needed because data sets with the SPANNED, KEYRANGE, IMBED, REPLICATE and other attributes are not supported.

Loading a VSAM File

The file containing records to be loaded into a VSAM file can be in any format supported as a sequential file format by the Tachyon Operating System. This allows a program to create a sequential file that can then be loaded into a VSAM file.

You can also download a file from the mainframe and then load it into a VSAM file. For fixed-length records or records that can be downloaded as ASCII text, you can use any normal file transfer method. The best way to download variable length records is to export them using the TSO TRANSMIT command, download the exported file (in binary), extract the file using the Tachyon Un-Xmit program and then load them into the VSAM file. To download records from a mainframe VSAM data set, you first need to REPRO the records from the VSAM data set to a sequential data set before downloading the sequential data set.

Running the VSAM File Utility

The tosvsam utility is a command-line program. It can be run interactively or entirely through command-line parameters. You will be prompted for any information that the tosvsam program needs that you did not supply as a command line parameter. Thus, if you supply all of the information required to run the utility through the command line, you will not be asked any questions. The command-line syntax is: 
tosvsam [-dir vsam-directory] [vsam-data-set-name]
   [{-delete|-del}] [{-define|-def}] [-load] [{-listcat|-listc}]
   [-recorg {k|ksds|e|esds|r|rrds|v|vrrds}]
   [-ave average-record-length] [-max maximum-record-length]
   [-dci data-control-interval-size]
   [-ici index-control-interval-size]
   [-rkp relative-key-position] [{-keylen|-kl} key-length]
   [-file input-file-name] [-recfm {t|f|v|vb|u}]
   [-lrecl record-length]
-dir vsam-directory
The -dir parameter defines the directory that contains or will contain the VSAM file. The directory must already exist. The directory name is required for all utility functions. You can use a single period to specify the current working directory.
vsam-data-set-name
The VSAM data set name is required for all utility functions. It must be from 1 to 42 characters consisting of one or more groups of 1 to 8 alphanumeric characters (A-Z or 0-9) with a single period separating each group. The first character of each group must be a letter (A-Z).
-delete | -del | -define | -def | -load | -listcat | -listc
If none of these function parameters are specified, you will be prompted for the functions to be performed and you will be able to perform more than one function in a single execution of the utility. If any of these parameters are specified, then only those functions will be performed. If more than one function is specified, the functions will be performed in the following order: -delete, -define, -load, -listcat.

-delete (or -del) will cause the VSAM file to be deleted. -delete can be combined with -define to cause an existing VSAM file to be redefined.

-define (or -def) will cause an empty VSAM file to be defined. The VSAM file must not already exist unless the -delete parameter is also specified. -define can be combined with any or all of the other function parameters: -delete, -load and -listcat. -define uses the information provided by the -recorg, -ave, -max, -dci, -ici, -rkp and -keylen parameters.

-load will cause an existing VSAM file to be loaded. If the VSAM file already contains records, the VSAM file will be emptied before the new records are loaded. -load can be combined with -define and -listcat. -load uses the information provided by the -file, -recfm and -lrecl parameters.

-listcat (or -listc) will cause the definition of the VSAM file to be listed. -listcat can be combined with -define and -load.

-recorg { k | ksds | e | esds | r | rrds | v | vrrds }
When a VSAM file is to be defined, the -recorg parameter specifies the VSAM file type (record organization) for the new file.
-ave average-record-length
When a VSAM file is to be defined, the -ave parameter specifies the average length of the records that will be stored in the file. For a RRDS, the average and maximum record lengths must be the same. For a VRRDS, the average record length must be less than the maximum record length. For a KSDS or ESDS, the average record length must be less than or equal to the maximum record length.
-max maximum-record-length
When a VSAM file is to be defined, the -max parameter specifies the maximum length of the records that will be stored in the file. Spanned records are not supported, so the maximum record length must be no more than 7 less than the data control interval size (11 less for a VRRDS).
-dci data-control-interval-size
When a VSAM file is to be defined, the -dci parameter specifies the control interval size of the data component. Valid control interval sizes are multiples of 512 up to 8192 and multiples of 2048 up to 32768.
-ici index-control-interval-size
When a KSDS or VRRDS VSAM file is to be defined, the -ici parameter specifies the control interval size of the index component. Valid control interval sizes are multiples of 512 up to 8192 and multiples of 2048 up to 32768.
-rkp relative-key-position
When a KSDS VSAM file is to be defined, the -rkp parameter specifies the position of the first byte of the key, relative to zero.
-keylen key-length | -kl key-length
When a KSDS VSAM file is to be defined, the -keylen parameter specifies the length of the key in bytes.
-file input-file-name
When a VSAM file is to be loaded, the -file parameter specifies the name of the file containing the data that will be loaded. The file must already exist. VSAM files cannot be loaded from other VSAM files. To be loaded into a KSDS, the records in the input file must be in ascending key sequence.
-recfm { t | f | v | vb | u }
When a VSAM file is to be loaded, the -recfm parameter specifies the format of the input file.

Format code t specifies that the file contains ASCII text. Each line of text will be converted to EBCDIC before it is loaded into the file. If the records are loaded into a RRDS or if the -lrecl parameter is specified, the records will be padded with blanks to the required length.

Format code f specifies that the file contains fixed length EBCDIC records. The length of each record may be specified through the -lrecl parameter.

Format code v specifies that the file contains variable length records prefixed by a standard 4-byte Record Descriptor Word (RDW). Spanned records are supported.

Format code vb specifies that the file contains blocks of variable length records prefixed by a standard 4-byte Record Descriptor Word (RDW). Each block of records must be prefixed by a standard Block Descriptor Word (BDW). Spanned records are supported.

Format code u specifies that the file contains variable length records prefixed by a 2-byte Record Descriptor Word (RDW) that does not include the length of the RDW.

-lrecl record-length
When a VSAM file is to be loaded with ASCII text or fixed length records, the -lrecl parameter specifies the length of each record. Text records that are shorter than the specified length will be padded with blanks.

Example

This command will delete, define, load and then list the definition for a KSDS named XXX.YYY in the current directory. It will be loaded from text records from the file named records.txt with a key field in the first 8 characters. The following should be entered as a single command: 

tosvsam -del -def -load -listc -dir . XXX.YYY -recorg k -ave 100 -max 200 -rkp 0 -kl 8 -dci 2048 -ici 1024 -file records.txt -recfm t
Output from the example command might look like: 
TLC010I Tachyon Operating System VSAM Utility - version 2.0.00
        (c) Copyright 1997-2000 Tachyon Software LLC
VSAM file XXX.YYY has been deleted.
VSAM file XXX.YYY has been successfully defined.
VSAM file XXX.YYY successfully loaded with 1111 records from "records.txt".

CLUSTER ------ XXX.YYY
   FILE--------XXX.YYY.CAT
   RECORG------KSDS
DATA --------- XXX.YYY.D
   FILE--------XXX.YYY.D.VSM
   ATTRIBUTES
     KEYLEN-----------8    CISIZE--------2048    CI/CA--------83
     RKP--------------0    MAXLRECL-------200
   STATISTICS
     REC-TOTAL-----1111    SPLITS-CI--------0
     REC-DELETED------0    SPLITS-CA--------0
     REC-INSERTED-----0    FREESPACE-%CI----0
     REC-UPDATED------0    FREESPACE-%CA----0
     REC-READ---------0    FREESPACE----77824
   VOLUME------SYSRES
     HI-A-RBA-----169984
     HI-U-RBA------92160
     END-RBA-------90112
INDEX -------- XXX.YYY.I
   FILE--------XXX.YYY.I.VSM
   ATTRIBUTES
     KEYLEN-----------8    CISIZE--------1024    CI/CA---------1
     RKP-------------72    MAXLRECL------1008
   STATISTICS
     REC-TOTAL--------1    SPLITS-CI--------0    INDEX:
     REC-DELETED------0    SPLITS-CA--------0    LEVELS--------1
     REC-INSERTED-----0    FREESPACE-%CI----0    KEY/CI-------83
     REC-UPDATED------0    FREESPACE-%CA----0    SEQ-SET-RBA---0
     REC-READ---------0    FREESPACE--------0    TOP-RBA-------0
   VOLUME------SYSRES
     HI-A-RBA------1024
     HI-U-RBA------1024
     END-RBA----------0

Defining a VSAM file will create a catalog information file in the specified directory with the name of the cluster and an extension of “.CAT”. Loading a VSAM file will cause one or two more files to be created. The data component file will be created with the cluster name followed by “.D” and an extension of “.VSM”. A KSDS or VRRDS will also have an index component file named with the name of the cluster followed by “.I” and an extension of “.VSM”. These file names are shown in the LISTCAT output as shown above.

Note: If you move a VSAM file from one directory or machine to another, you must move all of these files together.

Frames No Frames Previous Next Contents
Introduction Setup Programs Files Running Testing Compatibility Customization Messages Codes
© Copyright 1998-2005, Tachyon Software® LLC.
Last modified on December 1, 2005