Chapter 3: File Handling

The chapter describes the file handling facilities supplied with Mainframe Express Assembler Option.

3.1 Introduction

Assembler Option provides file handling facilities for a subset of the data set organizations supported by Mainframe Express. The following table shows the data set organizations and access methods that you can use in your Assembler programs:

Data Set Organization Record Formats Access Methods
PS (member of GDG) Fixed, variable, line sequential QSAM, BSAM
PS Fixed, variable, line sequential QSAM, BSAM
PSU Fixed, variable, line sequential QSAM, BSAM
ES (Entry sequence) Fixed, variable VSAM
KS (Key sequence) Fixed, variable VSAM
RR (Relative record) Fixed, variable VSAM

Assembler Option performs all file handling by calling the Mainframe Express COBOL file handler; this ensures 100% compatibility. Your Assembler programs can access any file created by a Mainframe Express COBOL program, as long as its data set organization is one of those shown in the table. Equally, Mainframe Express COBOL programs can access files created by Assembler programs.

In your Assembler program you define your files and perform input/ouput operations on them using the same macros that you use on the mainframe. Assembler Option ignores some control block parameters and applies others differently, but in general the level of compatibility between control blocks on the PC and control blocks on the mainframe is very high. The input/output request macros expand differently from the mainframe. All fields in request macros that accept register notation in a mainframe environment also accept register notation in Assembler Option.

The online help contains full specifications of all the file handling macros supported; click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Assembler Option, Macro Instructions.

If you are working with mainframe-style files you should map PC filenames to mainframe-style names using the Mainframe Express catalog.

Further information about working with files in the Mainframe Express IDE is available in the chapters Files and Data Sets and Overview of Working with Data Files in your User's Guide, and in the chapter Advanced Data Set Information in your IDE Technical Guide.

3.2 Using QSAM for File Handling

Assembler Option supports QSAM-style processing of files with the data set organizations PS and PSU. You define your file with the DCB macro and process it with the OPEN, CLOSE, GET and PUT request macros. QSAM file handling is identified in the DCB by the MACRF options of G, P, or G,P for GET, PUT or GET/PUT. The two-byte COBOL ANSI 85 file status code is available after every file operation at byte 6 in the data control block (DCB).

Your files can have fixed, variable or Micro Focus line sequential record formats. The length of the last record read or written is always available in the LRECL field of the DCB.

In the case of variable-length records, each record is prefixed by a four-byte mainframe-compatible record descriptor word (RDW)

To use Micro Focus line sequential file organization, specify RECFM=T in the DCB. All records are variable length and, whether read or written, must end with ANSI carriage-return and line-feed characters (x"0D0A").

Some of the sample programs provided with Assembler Option illustrate the use of QSAM-style file handling:

Program
Summary
pgasm04.mlc Uses the input/ouput macro statements to copy a line sequential file. The input file is mf370get.dat; the new output file is mf370put.dat. The program displays the records on the screen as it copies them. The source is in folder \mfuser\projects\demo\asmpg04\source.
qsamex4.mlc Reads an ANSI text file (line sequential format ) and writes the records to an EBCDIC PS file of 80-character fixed length records. The source and the input file are in folder \mfuser\projects\demo\asmdemo\source. This sample program is very useful for converting ASCII text files into 80-byte EBCDIC card-images to be read by other Assembler programs.

3.3 Using BSAM for File Handling

Assembler Option supports BSAM-style processing of files with the data set organizations PS and PSU. You define your file with the DCB macro and process it with the OPEN, CLOSE, READ and WRITE request macros. BSAM file handling is identified in the DCB by the MACRF options of R, W, or R,W for READ, WRITE or READ/WRITE. The two-byte COBOL ANSI 85 file status code is available after every file operation at byte 6 in the data control block (DCB).

The BSAM READ and WRITE operations act on a block of records at a time; your Assembler program is responsible for any processing required to deblock and block individual records. However, PC operating systems do not currently support blocked record files; all PC files must consist of individual logical records. There are two solutions to this incompatibility between the mainframe and PC. In both cases you need to convert the file to an unblocked format on the mainframe, using either a specially-written program or a third-party utility. The two solutions are as follows:

Your blocked files can have fixed, variable or Micro Focus line sequential record formats. Fixed length records are held in fixed length blocks, while variable length records are held in variable length blocks. Line sequential records are held in variable length blocks, one record per block.

In the case of variable-length blocks, each block is prefixed by a four-byte mainframe-compatible block descriptor word. Each record is normally prefixed by its own record descriptor word, but processing this is the responsibility of your Assembler program.

To use Micro Focus line sequential file organization, specify RECFM=T in the DCB. The single record in each block must end with ANSI carriage-return and line-feed characters (x"0D0A").

3.4 Using VSAM for File Handling

Assembler Option supports VSAM-style processing of files with the data set organizations ES, KS and RR, providing sequential, indexed and random access. You define your file with the ACB, EXLST and RPL control block macros and process it with the OPEN, CLOSE, GET, PUT, POINT and ERASE request macros. You can also manipulate the ACB, EXLST and RPL control blocks at execution time using the SHOWCB, MODCB, TESTCB and GENCB macros. The two-byte COBOL ANSI 85 file status code is available after every file operation at byte 6 in the access method control block (ACB).

Your files can have fixed or variable record formats. The length of the last record read or written is always available in the RECLEN field of the request parameter list.

You can use one alternate index to access a VSAM KS files. You specify alternate index access with the AIX option of the MACRF parameter of the ACB macro.

Assembler Option does not support the following mainframe VSAM options: reverse sequential processing, relative byte addressing, control interval access, asynchronous input/output and multiple file positions.

Some of the sample programs provided with Assembler Option illustrate the use of VSAM-style file handling:

Program
Summary
vsamex1.mlc Reads a variable-length KS file sequentially by key and displays each record on the screen. The source and input file are in folder \mfuser\projects\demo\asmdemo\source.
vsamex3.mlc Reads a variable-length KS file directly by key, adding new records and optionally updating retrieved records. The source and input file are in folder \mfuser\projects\demo\asmdemo\source.
vsamex5.mlc Reads a fixed-length RR file, erases any existing records then performs a sequence of tests to demonstrate that records can be written and read sequentially and at random. The source and input file are in folder \mfuser\projects\demo\asmdemo\source.
vsamex19.mlc Reads a variable-length KS file using an alternate index. The alternate key values are verified after each read and a success or fail message is written to the screen depending on the sequence of records returned. The source and input file are in folder \mfuser\projects\demo\asmdemo\source.

Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.