Assembler Option Technical

Micro Focus Mainframe Express™
Assembler Option
Technical Guide
MERANT™
Issue 3
June 1999
Copyright (C) 1999 MERANT International Limited. All rights reserved.
ASFRNT.C00 05Jul99 15:55:08 33547 MERANT Confidential Draft

This document and the proprietary marks and names used herein are
protected by international law.
MERANT has made every effort to ensure that this guide is correct and
accurate but reserves the right to make changes without notice at its sole
discretion at any time.
The software described in this document is supplied under a license and
may be used or copied only in accordance with the terms of such license,
and in particular any warranty of fitness of MERANT software products
for any particular purpose is expressly excluded and in no event will
MERANT be liable for any consequential losses.
Micro Focus® is a registered trademark, and MERANT™, Assembler Option™,

Mainframe Express™, MF/370™ and Micro Focus COBOL™ are trademarks, of
MERANT International Limited
IBM® and S/390® are registered trademarks, and CICS™, ESA/390™ and MVS™ are
trademarks, of International Business Machines Corporation
Copyright© 1987-1999 MERANT

All Rights Reserved.
ii Assembler Option Technical Guide

Preface
The Assembler Option component of Mainframe Express provides an

environment for the development of IBM 370 Assembler application
programs within the integrated development environment of Mainframe
Express.
Audience
This technical guide is for Assembler programmers who need
information about the advanced features of the Assembler Option
component of Mainframe Express. The basic features and functions of
Assembler Option are described in the Mainframe Express User’s Guide
and the online help that is part of Mainframe Express.
Notation
The following type styles and conventions are used in this Guide:
Text that you type is shown like this:
cat script_name | more
The italic text denotes a variable that you type as part of the
command.
Optional text in command lines and code examples is shown in
square brackets. In the following example, the expression can
specify that the column_name is like the pattern_value, or is
not like the pattern_value, depending on the absence or
presence of the optional word NOT:
column_name [NOT] LIKE pattern_value
Assembler Option Technical Guide iii

Preface
A section or paragraph that applies only to a particular model or

operating system is identified by a bold italic side-heading
immediately preceding the paragraph or section. For example:
Windows 95 This paragraph only applies on Windows 95 systems.
iv Assembler Option Technical Guide

Table of Contents
1 Compiling and Linking Assembler Modules

1.1 Setting Compiler Directives 1-1(7)
1.2 Linking Modules 1-3(9)
1.2.1 Program Structures and Linking 1-3(9)
1.2.1.1 Single Assembler Module 1-4(10)
1.2.1.2 Multiple Assembler Modules with Calls Using
External Names 1-4(10)
Entry Points 1-4(10)
1.2.2 Assembler Modules that call COBOL Modules 1-5(11)
1.2.3 Link File INCLUDE commands 1-5(11)
1.2.4 Other Link File Commands 1-6(12)
1.3 Entry Point Mapping 1-6(12)
2 Run-time Considerations
2.1 Memory Requirements 2-1(13)
2.1.1 Reserving Memory for Execution 2-2(14)
2.1.2 How to Specify Your Memory Requirements 2-2(14)
2.1.2.1 Program Only Uses Memory Below the Line 2-3(15)
2.1.2.2 Program Only Uses Memory Above the Line 2-3(15)
2.1.2.3 Program Uses Memory Below and Above the Line 2-4(16)
2.1.3 Setting Residency Mode 2-5(17)
2.1.4 Using Subpools 2-5(17)
2.2 Macros and SVCs 2-6(18)
3 File Handling
3.1 Introduction 3-1(21)
3.2 Using QSAM for File Handling 3-2(22)
Assembler Option Technical Guide v
ASTOCC.C00 05Jul99 15:55:09 21786 MERANT Confidential Draft

Table of Contents
3.3 Using BSAM for File Handling 3-3(23)

3.4 Using VSAM for File Handling 3-4(24)
vi Assembler Option Technical Guide
ASTOCC.C00 05Jul99 15:55:09 21786 MERANT Confidential Draft

Chapter 1
Compiling and Linking
Compiling and Linking Assembler Modules

Assembler Modules
This chapter provides detailed information about compiling and linking

Assembler modules.
1.1 Setting Compiler Directives

You can use directives to control the way the Assembler Compiler
behaves. For normal operation you need no more than a few directives.
Most of the time, you use the default values.
Note that setting some directives affects the default setting of other
directives. For example, setting one directive might automatically unset
another directive, and some directive settings are mutually exclusive.
You can set directives in the IDE simply by making selections in the Build
Settings dialog box, at either project or program level. These appear in
Build Settings at the bottom of the page.
You can also enter directives not already set by typing them into
Additional Directives. As you type into Additional Directives, the
directives you add appear in Build Settings.
Directives set at project level automatically apply to all Assembler
programs within the project, unless you override them at program level.
Assembler Option Technical Guide 1-1[7]
ASCOMP.C00 05Jul99 15:55:08 78764 MERANT Confidential Draft

The build settings are distributed over four Assembler pages in the Build
Settings dialog box: General, Link, Preproc (for Preprocessor) and Adv
(for Advanced). You can set directives to:
Create debug information. The compiler stores the debug
information in files progname.idf and progname.idx, where
progname is the name of your program.
Create optimized code. An optimized code compilation fully
resolves references to addresses in macro code. If the compilation of
your program involves the execution of many macros, you can
reduce the total compilation time by specifying this directive.
Mark the code as serially reusable. This prevents reloading of the

module each time it is called.
Generate a listing file with optional cross-reference listing.
Link the module automatically; see the section Linking Modules for
more information.
Mark the code as re-entrant. This has the same effect as marking
code as serially reusable.
Resolve external calls at link time; see the section Linking Modules
for more information.
Set addressing mode and residency mode; see the section Memory
Requirements in the chapter Run-time Considerations for more
information.
Specify what type of load module is to be produced, an executable

code file or a data table.
Specify whether the module includes EXEC CICS commands, which
will need to be preprocessed.
Use macros that have been partly pre-compiled, rather than
recompiling them from the source file. If a macro source file has
changed since the date of pre-compilation, it is recompiled anyway.
Note that if you have changed a copybook that is included in a
macro file, you should always recompile the macro file from the
source file.
Create Assembler Analysis Tool files. These are files that assist in
the analysis of Assembler programs. For example, you could use
them to help you locate date fields that need changing to work
correctly in the year 2000 and beyond.
1-2[8] Assembler Option Technical Guide

Provide a value for $SYSPARM, which is a variable that can be used

within an Assembler module to determine which parts of the code
to assemble.
More detailed information is available in the pop-up help in the Build
Settings dialog box and in the reference help; click Help Topics on the

Mainframe Express Help menu, then on the Contents tab click
Reference, Assembler Option, Compiler Directives or Linker
Directives.
1.2 Linking Modules

When you build a project containing one or more Assembler modules,
the Assembler Compiler first creates an object code file (.obj) for each
module. Next, you can either have the Assembler compiler automatically
link the object code file into an executable load module (.390) or you can
run a separate linker process that combines several object modules into a
single linked load module. The link process uses its own link file (.lin)
containing link commands. The Assembler automatically searches for
external references in CALL commands in the object code files and
includes additional object code files as necessary to resolve the external
references.
Linking modules when you build the project is known as static linking.
You can also link modules dynamically at execution time, when external
references in LINK or LOAD commands are resolved.
1.2.1 Program Structures and Linking

You can statically link one or more Assembler modules in several types
of executable program structure, using build settings and an optional
link file. Your executable program can consist of :
A single Assembler module which is either executed stand-alone or
is dynamically called from another Assembler program or a COBOL
program.
Several Assembler modules, one of which is the main module that

calls the other modules. The main module calls the called modules
using their external names (that is, there is only one entry point in
each called program).

Several Assembler modules, one of which is the main module that

calls the other modules. The main module calls the other modules
using entry points other than the modules’ external names.
1.2.1.1 Single Assembler Module

To link a single stand-alone Assembler module, you simply need to
ensure that Automatically link module is checked. You can find this
check box on the Link page of the Assembler page in the Build Settings
for Project dialog box or the Build Settings for filename dialog box.

External Names
To link multiple Assembler modules where all the calls reference the
external names of the called modules, you need to ensure that
Automatically link module and Resolve external calls at link time are
checked for the main module (the calling module) and unchecked for the
called modules.
You can find both these check boxes on the Link page of the Assembler
page in the Build Settings for Project dialog box or the Build Settings for
filename dialog box.
Since all the calls reference the modules’ external names, the Assembler
Compiler finds and locates all the called modules in your Assembler
source libraries, and builds the main and called modules into one .390
file.
1.2.1.3 Multiple Assembler Modules with Calls Using Entry

Points
To link multiple Assembler modules where the calls reference entry
points in the called programs rather than their external names, you need
to:
1. Ensure that Automatically link module is unchecked for all the
modules in the project. You can find this check box on the Link
page of the Assembler page in the Build Settings dialog box.
2. Ensure that Resolve external calls at link time is checked on the
General page of the Linker page in the Build Settings dialog box.

3. Create a link file (.lin) that lists all the object files to be included
with the main module in the executable file.This link file must have
the same name as the main module. For example if the main
module has the name mymain.mlc, the link file must have the name
mymain.lin. See the section Link File INCLUDE commands for more
information about link files.

When the project is built, the Assembler Linker looks in the .lin file to
find out which object files need to be included in the executable file.
1.2.2 Assembler Modules that call COBOL Modules

You cannot statically link Assembler modules with COBOL modules in
one executable program. However, there are two methods of dynamically
linking to COBOL modules:
You can issue a CALL macro call in your Assembler program. With
this method you also need to include an INCLUDE command in a
link file for the module you want to link to. When the Linker
processes the INCLUDE command, it does not actually include the
COBOL module, but instead generates and includes a small
Assembler module. When the CALL is executed at run time, the
Assembler module loads and links to the COBOL module.
You can issue a LOAD macro call in your Assembler program.

Again, the LOAD macro does not load the COBOL module directly,
but instead creates and loads an Assembler module the address of
which is returned by the LOAD. You then issue a BALR instruction
specifying this address. The Assembler module then performs the
dynamic link to the COBOL module. Note that if you use this
option you must set the high bit in the last parameter address to the
number of parameters being passed.
1.2.3 Link File INCLUDE commands

You need an INCLUDE command in your link file for each module that
you want to be linked with the main module to produce one .390 file. The
INCLUDE command is documented in full in the on-line help; click Help
Topics on the Mainframe Express Help menu, then on the Contents tab
click Reference, Assembler Option, Link File Commands.
Here is an example of a link file. Assume that assemA is the main
Assembler module that calls assemB, assemC and cobolD (with two

parameters). The link file assemA.lin contains the following three

records:
INCLUDE SYSLIB(assemB)
INCLUDE SYSLIB(assemC)
INCLUDE SYSLIB(cobolD),TYPE=CBL,PARMS=2
The TYPE parameter specifies the language of the called module and is
optional; it defaults to ASM (for Assembler) if the main module is
Assembler. The PARMS parameter specifies the number of parameters to
be passed to the called program; you only need to specify it if TYPE =
CBL (for COBOL) . There are options that allow you to call a COBOL IMS
program and to call a program with a variable number of parameters.
1.2.4 Other Link File Commands

Link files can also contain the following commands:
NAME. Use this command to specify a name for the executable file
other than the name of the source. For example, the name of the
source file might be myprog.mlc, but you may want the executable
to have the name program1.390
ENTRY. Use this command if the executable file you are building
may be called by another program, and you want all such calls to
enter the program at a particular entry point, rather than the
beginning of the program.
ALIAS. Use this command to create an alias for the executable file
that you are building. The alias is created in the Mainframe Express
entry point mapping file mfentmap.dat.
These link file commands are documented in full in the online help; click
Help Topics on the Mainframe Express Help menu, then on the Contents
tab click Reference, Assembler Option, Link File Commands.
1.3 Entry Point Mapping

If one module calls another using the LOAD statement and the call is to
an entry point within the module rather than to the external name of the
module, you need to specify the relationship between the entry point and
the module. You do this by editing the Mainframe Express entry point
mapping file mfentmap.dat. For further information see the chapter
Compatibility with the Mainframe Environment in your User’s Guide.

Chapter 2
Run-time
Considerations
Run-time Considerations
This chapter provides information about various aspects of the run-time
behavior of Assembler programs.
2.1 Memory Requirements

On the mainframe, an area of memory can be located either below the
line or above the line. The term ’the line’ means the point at which the
address of an area of memory requires four bytes to hold it. Three-byte
addresses can point to memory up to 16Mb. Any area of memory starting
at a higher point than this requires a four-byte address. Four-byte
addresses are actually 31-bit addresses, since bit 0 is used for other
purposes. A 31-bit address can point to memory up to 2Gb.
The memory requirements of an Assembler program are indicated by its
AMODE (or addressing mode) and RMODE (or residency mode).
AMODE governs the type of addresses the program uses, while RMODE
indicates where the program must be located when it is loaded for
execution.
There are two AMODE values:

AMODE(24) indicates 24-bit (three-byte) addressing - memory
below the line
AMODE(31) indicates 31-bit addressing - memory above and below
the line.
You can set AMODE to 24 or 31 in Mainframe Express, since it emulates

both types of addressing by mapping mainframe-style above and below
ASRUNS.C00 05Jul99 15:55:09 77935 MERANT Confidential Draft

the line addresses to real 32-bit PC memory addresses. An AMODE (24)

program can only access memory below the line, while an AMODE(31)
program can access memory both below and above the line.
There are two RMODE values:
RMODE(24) indicates that the program must be loaded into
memory below the line
RMODE(31) indicates that the program can be loaded either below

or above the line.
2.1.1 Reserving Memory for Execution

When the Assembler Option run-time system is initialized, it allocates an
area of memory called the system queue area to the executable program.
You can specify how much of this memory is below the line and how
much is above the line. The main executable program and any other
executables that it loads are loaded into memory below or above the line
depending on the program’s RMODE settings.When a program issues
requests for extra memory using the macros GETMAIN or STORAGE
OBTAIN, it can specify whether the memory needs to come from the
below-the-line allocation or the above-the-line allocation, depending on
its addressing needs.
2.1.2 How to Specify Your Memory Requirements

Getting access to the type of memory you require involves several steps.
You must:
1. Specify how much memory the program needs below the line and
above the line, using the Max. memory below 16Mb line and Max.
memory above 16Mb line fields. You can find these fields on the
Assembler page of the Execution page of the Project Settings dialog
box.
2. Specify the addressing mode of the program and of any programs

that the main program calls, using the Addressing mode field.
Addressing mode appears in two places:
On the Link page of the Assembler page in the Build Settings
for Project dialog box or the Build Settings for filename dialog
box. Set addressing mode here for each Assembler program
that does not need a separate link file to control the production
of an executable code file.

On the General page of the Linker page in the Build Settings

for Project dialog box or the Build Settings for filename dialog
box. Set addressing mode here for each Assembler program
that does need a separate link file to control the production of
an executable code file.
3. Ensure that all your GETMAIN or STORAGE OBTAIN macro calls
indicate which type of memory is required.
The following sections cover most possibilities.
2.1.2.1 Program Only Uses Memory Below the Line
If your program only needs to address memory below the line, you
should:
1. Set Max. memory below 16Mb line to the maximum amount of
memory below the line that your program requires. The default is
3Mb and the maximum is 16Mb.
2. Set Addressing mode to AMODE(24) for the main program and for
each program that the main program loads.
3. Omit the LOC parameter from all GETMAIN or STORAGE

OBTAIN macros issued by your program.
2.1.2.2 Program Only Uses Memory Above the Line

If your program needs to address memory above the line, you should:
1. Set Max. memory above 16Mb line to the maximum amount of

memory above the line that your program requires. The default is
3Mb and the maximum is 2Gb.
2. Set Addressing mode to AMODE(31) for the main program and for
each program that the main program loads.
3. Set LOC=ANY in all GETMAIN and STORAGE OBTAIN macros
issued by your program.

2.1.2.3 Program Uses Memory Below and Above the Line

If your program needs to address both types of memory, that is, you have
a mix of some modules that use memory below the line and others that
use memory above the line, you should:
1. Set Max. memory below 16Mb line to the maximum amount of
memory below the line that your program requires. The default is
3Mb and the maximum is 16Mb.
2. Set Max. memory above 16Mb line to the maximum amount of
memory above the line that your program requires. The default is
3Mb and the maximum is 2Gb.
3. Set Addressing mode to AMODE (24) for each program to be

loaded that uses memory below the line.
4. Set Addressing mode to AMODE (31) for each program to be
loaded that uses memory above the line.
5. To allocate memory below the line, omit the LOC parameter from
all GETMAIN and STORAGE OBTAIN macros that the module
issues.
6. To allocate memory above the line, set LOC=ANY in all GETMAIN

and STORAGE OBTAIN macros that the module issues.
7. Use the Assembler instructions BASSM or BSM to transfer control
between programs that use different addressing modes.
Notes:
If a program that uses 31-bit addressing needs to manipulate 24-bit

addresses, you must include code to clear the unused byte of the
address before any instruction that sets a register to a new address.
These instructions include LA, BAL, BALR, EDMK and TRT.
You can only set LOC=ANY on the RU and RC formats of the
GETMAIN macro. The R format of GETMAIN is restricted to
memory below the line.

2.1.3 Setting Residency Mode

You specify the residency mode of a program and of any programs that
the main program calls using the Residency mode field. Residency
mode appears in two places:
On the Link page of the Assembler page in the Build Settings for
Project dialog box or the Build Settings for filename dialog box. Set
residency mode here for each Assembler program that does not
need a separate link file to control the production of an executable
code file.
On the Advanced page of the Linker page in the Build Settings for
Project dialog box or the Build Settings for filename dialog box. Set
residency mode here for each Assembler program that does need a
separate link file to control the production of an executable code file.
The valid combinations of AMODE and RMODE are:

AMODE(24) and RMODE(24)
AMODE(31) and RMODE(31)
AMODE(31) and RMODE(24): use this combination where the

Assembler program contains 24-bit address constants but needs to
be executed in 31-bit addressing mode so that it can handle 31-bit
addresses passed as parameters by calling COBOL programs.
Note: If you set AMODE to 31 and RMODE to 31, but the Assembler module
contains 24-bit addresses, the Linker overrides your RMODE setting and
loads the module below the line, and displays a warning message.
2.1.4 Using Subpools

You can use subpools to help manage your memory requirements in just
the same way as you do on the mainframe. A subpool is a logical
grouping of memory allocations that can be de-allocated with a single
FREEMAIN or STORAGE RELEASE macro statement. Subpools are
available for memory both above and below the line.
You create a subpool simply by including the SP parameter in a
GETMAIN or STORAGE OBTAIN macro statement. Valid subpool
numbers are 0 through to 127, 131 and 132. If you omit the SP parameter
from your GETMAIN and STORAGE OBTAIN macro statements, all

memory is allocated in subpool 0, unless you specify the NONCAN link

directive, in which case all memory is allocated in subpool 132.
2.2 Macros and SVCs

Assembler Option supports a number of macros and SVCs (supervisor
calls). Those that are supported are compatible with the equivalent
macros and SVCs on the mainframe, so you shouldn’t need to alter your
code just for the PC environment. However, some macro options may not
be supported. This means that they will compile, but will not have any
effect when executed. There are also some macros which are supported in
stub form, that is, macro code exists but it simply returns control to the
calling program. These stubs are provided for macros that perform tasks
that have no meaning on the PC. An example stub macro is provided in
\mfe\mfasm\include\stub.mac; you can use this to create your own
stub macros.
The online help contains full specifications of all the macros and SVCs
supported; click Help Topics on the Mainframe Express Help menu, then
on the Contents tab click Reference, Assembler Option, Macro
Instructions or Supervisor Services.
There are two categories of macro:

Assembler services macros. These provide services for interfacing
with the Assembler Option run-time system, managing memory,
calling other programs and for general functions such as saving and
restoring registers. There are also services for accessing the catalog
and for dynamically allocating and deallocating data sets at
execution time.
File handling macros. These provide access to files. There is more
information about these macros in the chapter File Handling.

Many Assembler services macros equate to SVCs. You can choose

whether to code the macro or its equivalent SVC, but in general it is
easier to use the macros. The following table relates the SVCs and service
macros:
SVC Macro Description
4 GETMAIN L LC LU E EC EU, Get memory (list, element and variable

VC, VU requests).
5 FREEMAIN L LC LU E EC EU, Free memory (list, element and variable
VC, VU requests).
6 LINK Link to another Assembler program.
8 LOAD Load another Assembler program or a COBOL

program.
9 DELETE Delete a loaded module.
10 GETMAIN R Get memory (R type register requests).
11 TIME Get the time of day and the date.
13 ABEND Terminate the program and open the

Assembler debugger if possible, or display
information about the state of the program
when the abend occurred.
14 SPIE Handle a program exception within the

executing module.
26 CATALOG and LOCATE Uncatalog a data set; return a volume list for a
data set.
29 SCRATCH Delete a data set.
35 WTO Display a message on the screen.

WTOR Display a message on the screen and wait for a
reply.
39 LINKC2 Link to a COBOL program.
41 IDENTIFY Associate a name you specify with an already

loaded program.

SVC Macro Description
62 Remove the executing program. There is no

corresponding macro.
99 DYNALLOC Allocate or deallocate a resource at execution

time.
103 XLATE Convert between ANSI and EBCDIC.
120 GETMAIN RU, RC, VRC, VRU; Get memory (RU and RC type register requests)
FREEMAIN R, RU, RC, VRC Free memory (all types of register requests).
and VRU;
STORAGE Get memory or free memory
CALL Transfer control to a statically linked module.

There is no corresponding SVC.
CAMLST Create parameter list for CATALOG, LOCATE

or SCRATCH. There is no corresponding SVC.
DEQ Relinquish control of one or more serially

reusable resources. There is no corresponding
SVC.
ENQ Request control of one or more serially

reusable resources. There is no corresponding
SVC.
EXTRACT Obtain information from control block. There

is no corresponding SVC.
RETURN Restore registers and sets the address to return

to. There is no corresponding SVC.
SAVE Save registers. There is no corresponding SVC.
SPLEVEL Test or set the level of MVS macro

compatibility. There is no corresponding SVC.
WAIT Wait for event completion. There is no

corresponding SVC.

Chapter 3
File Handling
The chapter describes the file handling facilities supplied with

Mainframe Express Assembler Option.
File Handling
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
ASMEFH.C00 05Jul99 15:55:09 70972 MERANT Confidential Draft

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

File Handling
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.
File Handling
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

File Handling
specially-written program or a third-party utility. The two solutions are

as follows:
If the file is to be accessed only by an Assembler program, your
conversion program should write out each block as a record. Then
when the Assembler program on the PC issues a READ, although
the COBOL file handler returns a single record, the Assembler
program can continue to treat it as a block.
If the file is to be accessed by both an Assembler program and a
COBOL program, your conversion program should write out each
record individually. Then on the PC your COBOL program can
access the file one record at a time, while the Assembler program
can access it one block at a time, with each block holding one
record. You can only use this approach if your Assembler program
is able to handle blocks containing variable numbers of records.
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).

File Handling
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
File Handling
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
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

File Handling

Index
Index
! C
&SYSPARM Assembler compiler directive CALL Assembler macro 1-5(11)
1-3(9) Catalog 3-2(22)
24-bit addressing 2-1(13) accessing at run time 2-6(18)
31-bit addressing 2-1(13) CICS Option, and Assembler Option 1-2(8)
.390 file 1-3(9) CLOSE Assembler macro 3-2(22)–3-4(24)
COBOL program, called by Assembler 1-5(11)
Compiler directive
AMODE 2-1(13)
A Assembler 1-1(7)
AAT, See Assembler Analysis Tool RMODE 2-1(13)
ACB Assembler macro 3-4(24) Compiling Assembler program, directive
Access method 3-1(21) 1-1(7)
control block 3-4(24) Control block, macro 3-2(22)
Addressing mode, Assembler program 2-1(13)
ALIAS command in link file 1-6(12)
Alternate, index 3-5(25) D
AMODE directive 2-1(13)
Assembler Analysis Tool 1-2(8) Data, control block 3-2(22)–3-3(23)
Assembler Option Data file, in Assembler Option 3-1(21)–3-6(26)
build settings 1-3(9) Data set
CICS commands 1-2(8) dynamic allocation 2-6(18)
file handling 3-1(21)–3-6(26) organization 3-1(21)
macro 1-2(8), 2-6(18), 3-2(22) DCB Assembler macro 3-2(22)–3-3(23)
memory management 2-1(13) Debugging, Assembler program 1-2(8)
program structure 1-3(9) Dynamic, allocation 2-6(18)
sample program 3-3(23), 3-5(25)
SVC 2-6(18)
Assembler program
addressing mode 2-1(13) E
calling a COBOL program 1-5(11) ENTRY command in link file 1-6(12)
compiling 1-1(7) Entry point, in Assembler module 1-4(10)
debugging 1-2(8) Entry point mapping 1-6(12)
entry point 1-4(10) EXLST Assembler macro 3-4(24)
entry point mapping 1-6(12) Extended, memory 2-1(13)
linking 1-3(9) External, name 1-4(10)
structure 1-3(9)
B F
File, link 1-3(9)
Blocked record format, conversion 3-3(23) FREEMAIN Assembler macro 2-5(17)
BSAM file handling 3-3(23)
Build settings, with Assembler Option 1-3(9)
Assembler Option Technical Guide Index-1
ASINDX.C00 05Jul99 15:55:08 47036 MERANT Confidential Draft

Index
G P
GENCB Assembler macro 3-4(24) PARMS parameter to link file commands
GET Assembler macro 3-2(22), 3-4(24) 1-6(12)
GETMAIN Assembler macro 2-2(14), 2-5(17) POINT Assembler macro 3-4(24)
Pre-compiled Assembler macro 1-2(8)
PUT Assembler macro 3-2(22), 3-4(24)
I
INCLUDE command in link file 1-5(11) Q
Index, alternate 3-5(25)
QSAM file handling 3-2(22)
K
Key, alternate 3-5(25)
R
Re-entrant code, Assembler program 1-2(8)
READ Assembler macro 3-3(23)
Record, format 3-1(21)–3-2(22), 3-4(24)
L Register, notation 3-2(22)
.lin file 1-3(9) Request
Line, sequential file 3-3(23)–3-4(24) macro 3-2(22)
Link file 1-3(9) parameter list 3-4(24)
command 1-5(11)–1-6(12) Residency mode 2-1(13)
LOAD Assembler macro 1-5(11) RMODE directive 2-1(13)
RPL Assembler macro 3-4(24)
M S
Macro 2-6(18), 3-2(22)
pre-compiled 1-2(8) Serially-reusable code, Assembler program
stub 2-6(18) 1-2(8)
Memory, access to extended 2-1(13) SHOWCB Assembler macro 3-4(24)
mfentmap.dat 1-6(12) STORAGE Assembler macro 2-2(14), 2-5(17)
MODCB Assembler macro 3-4(24) Stub macro 2-6(18)
Subpool 2-5(17)
Supervisor call 2-6(18)
SVC, See Supervisor call
N System, queue area 2-2(14)
NAME command in link file 1-6(12)
NONCAN link directive 2-5(17)
T
TESTCB Assembler macro 3-4(24)
O TYPE parameter to link file commands 1-6(12)
.obj file 1-3(9)
OPEN Assembler macro 3-2(22)–3-4(24)
Optimized code, Assembler program 1-2(8) V
Variable-length record 3-2(22), 3-4(24)
VSAM, file handling 3-4(24)
Index-2 Assembler Option Technical Guide

Index
W
WRITE Assembler macro 3-3(23)
Index
Year 2000, Assembler Analysis Tool 1-2(8)
Assembler Option Technical Guide Index-3

Index
Index-4 Assembler Option Technical Guide

Assembler Option Technical

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Assembler Option Technical

Diunggah oleh

Hak Cipta:

Format Tersedia

Micro Focus Mainframe Express™

Copyright (C) 1999 MERANT International Limited. All rights reserved.

ASFRNT.C00 05Jul99 15:55:08 33547 MERANT Confidential Draft

Micro Focus® is a registered trademark, and MERANT™, Assembler Option™,

Copyright© 1987-1999 MERANT

ii Assembler Option Technical Guide

Copyright (C) 1999 MERANT International Limited. All rights reserved.

ASFRNT.C00 05Jul99 15:55:08 33547 MERANT Confidential Draft

The Assembler Option component of Mainframe Express provides an