Understanding VSAM Logical Record Access Methods
VSAM utilizes three primary methods to find logical records - Relative Byte Address, Relative Record Number, and Key field. Relative Byte Address assigns a unique address to each record based on sequential ordering. Relative Record Number is used in RRDS datasets to access records by a numbered sequence. Keys, such as primary and secondary keys, play a crucial role in accessing records in KSDS datasets. Additionally, the concept of generic keys offers a way to navigate through records efficiently based on a partial key.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. Download presentation by click this link. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
E N D
Presentation Transcript
Introduction to VSAM for Assembler Programmers Part Two
How Does VSAM Find Logical Records? Three ways: 1. Relative Byte Address 2. Relative Record Number 3. Key field
Relative Byte Address VSAM records have a sequential ordering, and the bytes they contain are numbered starting from the first record to the last Each offset to the first byte of a record is called a relative byte address (RBA) The RBA of the first record is 0 The RBA of the second record is equal to the length of the first record Records can be accessed using an RBA The RBA of a record is volatile and can change if records are added or deleted. If a record is read two times within the same application, the RBAs for that record might be different
Relative Byte Address Example: Assume CISIZE=4k, 80-byte records RBA = 0 RBA = 80 RBA = 160 RBA = 240 CI 1 . . . Record 1 Record 2 Record 3 Record 4 CI 2 Record 5 RBA = 4096 RBAs are block relative, not true relative
Relative Record Number (RRN) Associated with RRDS Records in a RRDS are numbered starting with the first record having RRN = 0 Record two has RRN = 1 Records in a Fixed-length RRDS are accessed using the RRN RRN 0 1 2 3 4 5 Empty Record Record Record Empty Record Slots
Keys Keys are fields in KSDS datasets that are used to access records Records can have multiple keys The key associated with the base cluster is called the primary key Keys associated with alternate indexes are called secondary keys For a KSDS, each record must have a unique, embedded, fixed-length key in the same position of each record the primary key Alternate index keys don t have to be unique Key sizes range from 1 255 bytes, binary (all 0 s or all 1 s are valid)
Generic Keys A generic key is the high-order portion of a regular key Example A credit card company maintains records using a full key that consists of a bank number, followed by a customer number BANK # CUSTOMER # The generic key could be the BANK # Using a generic key, you could skip to the first customer for a specific bank
Key Sequenced Data Set (KSDS) The most heavily used type of VSAM dataset Allocated with IDCAMS DEFINE - parameter INDEXED Records are initially added sequentially to an empty cluster in key sequence Records can be added, deleted and updated (primary keys can t be altered) Records can be processed sequentially, skip-sequentially, or directly (by key or RBA),
Entry Sequenced Data Set (ESDS) Created with IDCAMS DEFINE parameter NONINDEXED Records are sequenced by order of entry New records are added at the end Records can be updated, but the length can t change Records can t be physically deleted (use a flag to mark it invalid)
Entry Sequenced Data Set (ESDS) Records are usually accessed sequentially , but can also be accessed directly (by RBA) RBA positioning is allowed before sequential processing, but no skip- sequential processing can occur When a record is loaded or added, VSAM returns the RBA
Fixed-Length Relative Record Data Set (RRDS) Defined using IDCAMS DEFINE parameter NUMBERED The file consists of a collection of pre-formatted, fixed-length, logical record slots Each slot has a unique RRN Each logical record occupies a slot and is stored and retrieved by RRN Slots can be empty or occupied Can be processed sequentially, directly, or skip sequentially
Fixed-Length Relative Record Data Set (RRDS) Processing by RBA or key is not supported When processing sequentially, empty slots are skipped Typically, a RRDS is processed directly using the RRN
Access Method Control Block (ACB) Similar in function to a DCB for QSAM Contains logical information about the VSAM dataset Used by OPEN and CLOSE Can be created by the ACB macro at assembly time, and by the GENCB macro at execution time https://www.ibm.com/docs/en/zos/2.4.0?topic=instructions-introduction-vsam-programming
Start with these ACB fields AM Specifies the access method is VSAM DDNAME a logical link to the physical file name in the JCL EXLST the address of one or more exit routines MACRF one or more parms that describe the types of processing you will do with the file. There are many options here.
Start With These ACB MACRF Parms MACRF Parm Meaning ADR Addressed access to a KSDS or ESDS. RBA search arguments. Sequential access is by entry sequence KEY Keyed access to a KSDS or RRDS. Keys or RRNs search arguments. Sequential access by key for KSDS, by RRN for RRDS DIR Direct Access to a KSDS, ESDS, or RRDS SEQ Sequential access to a KSDS, ESDS, or RRDS SKP Skip-sequential access to a KSDS or RRDS. Used only with keyed access in a forward direction. RST Data set must be reusable. When opened, the RBA is set to 0. Underlined parms are the default Multiple parms of the same category can be included. For example, you could select DIR and SEQ in the same ACB The ACB specifies all the options that can be used with the cluster
Start With These ACB MACRF Parms MACRF PARM Meaning IN Retrieval of records for KSDS, ESDS, and RRDS. Use GET. OUT Storage of records for KSDS, ESDS, and RRDS. Update of records in a KSDS, ESDS, and RRDS. Deletion of records in a KSDS or RRDS. Also supports GET.
ACB Example: FILEOUT ACB AM=VSAM, MACRF=(KEY,SEQ,OUT), DDNAME=FILEOUT
Request Parameter List (RPL) Used to generate a request parameter list. A request that describes a specific GET or PUT operation The options it contains should be compatible with the options described in the ACB Lots of possible parameters https://www.ibm.com/docs/en/zos/2.4.0?topic=examples- rplgenerate-request-parameter-list-assembly-time
Start with these RPL Parms (there are more) RPL Parm Meaning ACB The address Names the ACB associated with this RPL request AREA The address of a work area where a record (or the address of a record) will be delivered AREALEN A length that is >= the length of a fixed-size record (or field) , or >= the max length of a variable- length record used in this request for PUTs the length of the record being stored for GETs VSAM stores the length of the record it retrieved in this field The field (address) that contains the search argument for direct retrieval, skip-sequential retrieval, and positioning The length of a generic key RECLEN ARG KEYLEN
Start with these RPL Parms RPL Parm Meaning OPTCD There are many parms that can be coded, including: KEY - access by keys ADR access by RBAs DIR direct access SEQ sequential access SKP skip-sequential access LOC locate mode I/O MVE move mode I/O See https://www.ibm.com/docs/en/zos/2.4.0?topic=examples-rplgenerate-request-parameter-list-assembly- time
Start with these RPL Parms RPL Parm Meaning UPD - A data record being retrieved may be updated or deleted NUP - A data record being retrieved will not be updated or deleted KEQ - search argument must equal the key for certain operations KGE search argument can be greater than or equal to the key for certain operations GEN a generic key will be used OPTCD See https://www.ibm.com/docs/en/zos/2.4.0?topic=examples-rplgenerate-request-parameter-list-assembly- time
Example RPL: WRTREQ RPL AM=VSAM, ACB=FILEOUT, AREA=RECOUT, RECLEN=80, OPTCD=(KEY,SEQ,MVE)
Read QSAM Write VSAM - Move Mode I/O User Region FILEIN FILEOUT User Program GET FILEIN,RECIN MVC RECOUT,RECIN PUT RPL=WRTREQ LTR R15,R15 JNZ ERRORO FILEOUT ACB AM=VSAM, MACRF=(KEY,SEQ,OUT), DDNAME=FILEOUT WRTREQ RPL AM=VSAM, ACB=FILEOUT, AREA=RECOUT, RECLEN=L'RECOUT, OPTCD=(KEY,SEQ,NUP,MVE) RECOUT RECIN Input Buffers Output Buffers
Read VSAM Write QSAM - Move Mode I/O User Region FILEIN FILEOUT User Program OPEN (FILEIN,(INPUT)) LTR R15,R15 JNZ BADOPEN GET RPL=RDREQ LTR R15,R15 BNZ BADGET MVC RECOUT,RECIN PUT FILEOUT,RECOUT FILEIN ACB AM=VSAM, MACRF=(KEY,SEQ,IN), DDNAME=FILEIN, EXLST=FILEINEX RDREQ RPL AM=VSAM, ACB=FILEIN, AREA=RECIN, RECLEN=L RECIN, OPTCD=(KEY,SEQ,NUP,MVE) RECOUT RECIN Input Buffers Output Buffers
Read VSAM Write VSAM - Move Mode I/O User Region FILEIN FILEOUT User Program GET RPL=RDREQ LTR R15,R15 BNZ BADGET MVC RECOUT,RECIN PUT RPL=WRTREQ BNZ BADWRT FILEIN ACB AM=VSAM, MACRF=(KEY,SEQ,IN), DDNAME=FILEIN, EXLST=FILEINEX RDREQ RPL AM=VSAM, ACB=FILEIN, AREA=RECIN,AREALEN=80, OPTCD=(KEY,SEQ,NUP,MVE) FILEOUT ACB AM=VSAM, MACRF=(KEY,SEQ,OUT), DDNAME=FILEOUT WRTREQ RPL AM=VSAM, ACB=FILEOUT, AREA=RECOUT, AREALEN=L'RECOUT, RECLEN=L'RECOUT, OPTCD=(KEY,SEQ,NUP,MVE) RECOUT RECIN Input Buffers Output Buffers
When Things Go Wrong VSAM puts a non-zero return code in R15 Return codes are paired with reason codes that are set in the access method control block (ACB) and the request parameter list (RPL). Reason codes that are set in the ACB indicate open or close errors. Reason codes that are set in the RPL indicate record management errors. Use SHOWCB to get access to the reason codes Look up the reason codes z/OS DFSMS Macro Instructions for Data Sets : https://www.ibm.com/docs/en/zos/2.4.0?topic=instructions-vsam-macro- return-reason-codes
When Things Go Wrong: SHOWCB SHOWCB is used to copy certain fields from an ACB or an RPL into your program Parms Meaning FIELDS The fields you want copied into your program AREA The return area you are supplying for VSAM to display the contents of the fields specified in the FIELDS parameter. Fields are displayed in the order they appear in the FIELDS parameter LENGTH specifies the length, in bytes, of the return area you are providing for VSAM to display the indicated fields
Coding for Errors with Open or Close Use keyword ERROR in FIELDS of SHOWCB to get the reason code from the ACB SHOWCB ACB=FILEOUT,AREA=RCODE,LENGTH=4,FIELDS=(ERROR) RCODE DS F The AREA must be fullword aligned Return code is in R15 Reason code is delivered in a fullword by SHOWCB Look up the reason code in Open Return and Reason Codes : https://www.ibm.com/docs/en/zos/2.4.0?topic=codes-open-return-reason
Example Open Error Handling OPEN (FILEIN,(INPUT)) LTR R15,R15 JNZ BADOPENI BADOPENI EQU * PUT DEBUGQ,=CL80'BAD OPEN OF VSAM KSDS (INPUT)' SHOWCB ACB=FILEIN,AREA=FDBKWD,LENGTH=4,FIELDS=(ERROR) (Examine FDBKWD to determine the error)
Test Your Error Handling Code for Open Try commenting out the DD statement for a VSAM dataset This produces a Return code of x 00000008 and a reason code of X 00000080
Coding for Errors with GET, PUT Use keyword FDBK IN THE SHOWCB for the RPL to retrieve the RPL feedback word The AREA must be fullword aligned Return code is in R15 Reason code in the rightmost byte of the delivered fullword in AREA SHOWCB RPL=RPL1,FIELDS=(FDBK),AREA=REASON,LENGTH=4 REASON DS F
Example GET Error Handling GET RPL=RDREQ LTR R15,R15 JNZ BADGET BADGET EQU * PUT DEBUGQ,=CL80'BAD VSAM GET' SHOWCB RPL=RDREQ,AREA=FDBKWD,LENGTH=4,FIELDS=(FDBK) (Examine the reason code in FDBKWD)
Test Your Error Handling Code for GET If you are reading a VSAM file sequentially, remove the EXLST in the ACB. This will generate an error at EOF. Return code = x 00000008 , Reason code = x 00000004 Look up the reason code in Record Management Return and Reason Codes : https://www.ibm.com/docs/en/zos/2.4.0?topic=codes-open-return- reason (follow Reason codes, Logical Errors)
Coding for Errors with Control Block Macros Test register 0 for a control block manipulating macros (GENCB, MODCB, SHOWCB, and TESTCB). Look up the return codes in Control Block Manipulation Macro Return and Reason Codes https://www.ibm.com/docs/en/zos/2.4.0?topic=codes-control-block- manipulation-macro-return-reason
